entangled-worlds-orbiters-shared 2.16.0 → 2.17.0

package/dist/faust/recipes.js

@@ -70,20 +70,24 @@ export function readHeadShape(value, sources) {
         if (typeof file !== 'string' || !Object.hasOwn(sources, file))
             throw new Error(`module ${index}: no such source`);
         const last = index === value.length - 1;
-        if (last) {
-            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
-                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
-            const constants = notes.constants ?? {};
+        // Program constants, an instrument's or a note module's: a few safe names, each a small whole number.
+        const constantsOf = (given) => {
+            const constants = given ?? {};
             if (typeof constants !== 'object' || Array.isArray(constants))
                 throw new Error(`module ${index}: constants`);
             const entries = Object.entries(constants);
             if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT)))
                 throw new Error(`module ${index}: constants`);
-            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+            return entries.length ? { constants: Object.fromEntries(entries) } : {};
+        };
+        if (last) {
+            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
+                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...constantsOf(notes.constants) } };
         }
         if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES))
             throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
-        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane, ...constantsOf(notes.constants) } };
     });
 }
 const isHead = (head) => {

package/dist/faust/voiceProgram.d.ts

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -62,6 +63,7 @@ export type SlotNotes = {
 } | {
     kind: 'generator' | 'midi';
     lanesPerLane: number;
+    constants?: Readonly<Record<string, number>>;
 };
 /** One slot of a composed voice: the module's `.dsp`, by file name. */
 export interface VoiceSlot {

package/dist/faust/voiceProgram.js

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -117,7 +118,7 @@ function noteModules(slots, head) {
         }
         const k = wholeAtLeastOne(notes.lanesPerLane, `slot ${index}: lanesPerLane`);
         // A module that adds lanes is told how many it puts out per lane in (an echo's repeats + 1).
-        const env = k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`;
+        const env = (k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`) + constantsEnv(notes.constants, index);
         const fx = `library("${slot.dspFileName}")[${env}].notes(${lanes})`;
         parts.push(`hgroup("${slotGroupId(index)}", nt.bypass(${lanes}, ${k}, ${fx}))`);
         lanes *= k;
@@ -134,13 +135,16 @@ function noteModules(slots, head) {
 function instrumentPart(slots, head, lanes) {
     // The instrument's place salts its random draws too (an LFO's Random), as every note module's does;
     // its program constants (unison's `U`) shape it, as its polyphony does.
-    const constants = Object.entries(slots[head].notes.constants ?? {})
-        .map(([name, value]) => {
+    const constants = constantsEnv(slots[head].notes.constants, head);
+    return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
+}
+/** A slot's program constants as library environment entries (` U = 2;`), each a safe name and a whole number. */
+function constantsEnv(constants, index) {
+    return Object.entries(constants ?? {}).map(([name, value]) => {
         if (!/^[A-Z][A-Z0-9_]*$/.test(name))
-            throw new Error(`[voiceProgram] slot ${head}: unsafe constant ${name}`);
-        return ` ${name} = ${wholeAtLeastOne(value, `slot ${head}: ${name}`)};`;
+            throw new Error(`[voiceProgram] slot ${index}: unsafe constant ${name}`);
+        return ` ${name} = ${wholeAtLeastOne(value, `slot ${index}: ${name}`)};`;
     }).join('');
-    return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
 }
 /** The entry, the note modules and the instrument, up to `head` (the instrument): lanes all the way. */
 function noteChain(slots, head) {
@@ -167,8 +171,8 @@ export function voiceCacheKey(slots) {
     // A note module's lane count is structural too: it shapes the program.
     const shape = (slots ?? []).map((slot) => {
         const notes = slot?.notes;
-        const constants = notes?.kind === 'instrument' ? constantsKey(notes.constants) : '';
-        const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}`;
+        const constants = notes ? constantsKey(notes.constants) : '';
+        const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}${constants}`;
         return String(slot?.dspFileName ?? '') + lanes;
     }).join('>');
     return `v${fnv(shape)}`;
@@ -238,7 +242,10 @@ export function buildHeadPrograms(slots) {
     // FAUST roots a program's controls in a group named after it only when it has several groups at the
     // top: named here, both programs' addresses start as the one program's do, whatever each holds.
     const root = (chain) => `vgroup("${HEAD_PROGRAM_NAME}", ${chain})`;
-    const shape = slots.slice(0, head).map((slot) => `${slot.dspFileName}#${slot.notes.kind}${slot.notes.lanesPerLane}`).join('>');
+    const shape = slots.slice(0, head).map((slot) => {
+        const n = slot.notes;
+        return `${slot.dspFileName}#${n.kind}${n.lanesPerLane}${constantsKey(n.constants)}`;
+    }).join('>');
     return {
         notes: {
             key: `n${fileKey(`${shape}>#p${notes.polyphony}`)}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",

package/src/faust/recipes.ts

@@ -90,16 +90,20 @@ export function readHeadShape(value: unknown, sources: Readonly<Record<string, s
     const notes = (slot as VoiceSlot | null)?.notes as SlotNotes | undefined;
     if (typeof file !== 'string' || !Object.hasOwn(sources, file)) throw new Error(`module ${index}: no such source`);
     const last = index === value.length - 1;
-    if (last) {
-      if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES)) throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
-      const constants = notes.constants ?? {};
+    // Program constants, an instrument's or a note module's: a few safe names, each a small whole number.
+    const constantsOf = (given: unknown): { constants?: Record<string, number> } => {
+      const constants = given ?? {};
       if (typeof constants !== 'object' || Array.isArray(constants)) throw new Error(`module ${index}: constants`);
       const entries = Object.entries(constants);
       if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT))) throw new Error(`module ${index}: constants`);
-      return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+      return entries.length ? { constants: Object.fromEntries(entries) } : {};
+    };
+    if (last) {
+      if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES)) throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+      return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...constantsOf(notes.constants) } };
     }
     if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES)) throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
-    return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+    return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane, ...constantsOf(notes.constants) } };
   });
 }
 

package/src/faust/voiceProgram.ts

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -55,7 +56,7 @@ export const MAX_NOTE_LANES = 16;
  * What a slot does with notes: a notes instrument's polyphony (and its program constants, when it has
  * any), or a generator's or MIDI effect's lanes out per lane in.
  */
-export type SlotNotes = { kind: 'instrument'; polyphony: number; constants?: Readonly<Record<string, number>>; copies?: number } | { kind: 'generator' | 'midi'; lanesPerLane: number };
+export type SlotNotes = { kind: 'instrument'; polyphony: number; constants?: Readonly<Record<string, number>>; copies?: number } | { kind: 'generator' | 'midi'; lanesPerLane: number; constants?: Readonly<Record<string, number>> };
 
 /** Faust identifiers: the group name goes into generated source, so keep it tame. */
 const SAFE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -143,7 +144,7 @@ function noteModules(slots: readonly VoiceSlot[], head: number): { parts: string
     }
     const k = wholeAtLeastOne(notes.lanesPerLane, `slot ${index}: lanesPerLane`);
     // A module that adds lanes is told how many it puts out per lane in (an echo's repeats + 1).
-    const env = k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`;
+    const env = (k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`) + constantsEnv(notes.constants, index);
     const fx = `library("${slot.dspFileName}")[${env}].notes(${lanes})`;
     parts.push(`hgroup("${slotGroupId(index)}", nt.bypass(${lanes}, ${k}, ${fx}))`);
     lanes *= k;
@@ -160,14 +161,18 @@ function noteModules(slots: readonly VoiceSlot[], head: number): { parts: string
 function instrumentPart(slots: readonly VoiceSlot[], head: number, lanes: number): string {
   // The instrument's place salts its random draws too (an LFO's Random), as every note module's does;
   // its program constants (unison's `U`) shape it, as its polyphony does.
-  const constants = Object.entries((slots[head].notes as { constants?: Readonly<Record<string, number>> }).constants ?? {})
-    .map(([name, value]) => {
-      if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`[voiceProgram] slot ${head}: unsafe constant ${name}`);
-      return ` ${name} = ${wholeAtLeastOne(value, `slot ${head}: ${name}`)};`;
-    }).join('');
+  const constants = constantsEnv((slots[head].notes as { constants?: Readonly<Record<string, number>> }).constants, head);
   return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
 }
 
+/** A slot's program constants as library environment entries (` U = 2;`), each a safe name and a whole number. */
+function constantsEnv(constants: Readonly<Record<string, number>> | undefined, index: number): string {
+  return Object.entries(constants ?? {}).map(([name, value]) => {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`[voiceProgram] slot ${index}: unsafe constant ${name}`);
+    return ` ${name} = ${wholeAtLeastOne(value, `slot ${index}: ${name}`)};`;
+  }).join('');
+}
+
 /** The entry, the note modules and the instrument, up to `head` (the instrument): lanes all the way. */
 function noteChain(slots: readonly VoiceSlot[], head: number): string[] {
   const { parts, lanes } = noteModules(slots, head);
@@ -194,8 +199,8 @@ export function voiceCacheKey(slots: readonly VoiceSlot[] | null | undefined): s
   // A note module's lane count is structural too: it shapes the program.
   const shape = (slots ?? []).map((slot) => {
     const notes = slot?.notes;
-    const constants = notes?.kind === 'instrument' ? constantsKey(notes.constants) : '';
-    const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}`;
+    const constants = notes ? constantsKey(notes.constants) : '';
+    const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}${constants}`;
     return String(slot?.dspFileName ?? '') + lanes;
   }).join('>');
   return `v${fnv(shape)}`;
@@ -287,7 +292,10 @@ export function buildHeadPrograms(slots: readonly VoiceSlot[]): HeadPrograms {
   // FAUST roots a program's controls in a group named after it only when it has several groups at the
   // top: named here, both programs' addresses start as the one program's do, whatever each holds.
   const root = (chain: string) => `vgroup("${HEAD_PROGRAM_NAME}", ${chain})`;
-  const shape = slots.slice(0, head).map((slot) => `${slot.dspFileName}#${slot.notes!.kind}${(slot.notes as { lanesPerLane: number }).lanesPerLane}`).join('>');
+  const shape = slots.slice(0, head).map((slot) => {
+    const n = slot.notes as Extract<SlotNotes, { kind: 'generator' | 'midi' }>;
+    return `${slot.dspFileName}#${n.kind}${n.lanesPerLane}${constantsKey(n.constants)}`;
+  }).join('>');
   return {
     notes: {
       key: `n${fileKey(`${shape}>#p${notes.polyphony}`)}`,