1/**
2 * What a scene *is*: a list of vibrating objects, a body for them to sound
3 * over, and nothing else. Everything the app builds — the generated model .m,
4 * the generated scene .m, the op instances, the sliders — is derived from
5 * this description (src/studio/codegen.ts), so this file is the studio's
6 * whole vocabulary.
7 *
8 * Two kinds of number live here, and the split decides what an edit costs:
9 *
10 * - `size` fields are baked into the grids and the coupling ops, so changing
11 * one recompiles (a fresh session, like changing the air grid).
12 * - `params` (model parameters: pitches, decays, gains) are GPU uniforms —
13 * free to move — and `place` (placement in the air: an object's y offset
14 * and height, the body's shape) are scene parameters, which cost one CPU
15 * re-evaluation of the scene .m and a few buffer uploads. Neither
16 * recompiles.
17 *
18 * Object ids are short and stable ('s1', 'm2'); the code generator suffixes
19 * every per-object name with them, so the generated MATLAB stays readable in
20 * the Lab view.
21 */
23export type Params = Record<string, number>;
25/** A tunable scalar and its slider. */
26export interface ParamSpec {
27 key: string;
28 label: string;
29 value: number;
30 min: number;
31 max: number;
32 step: number;
33 /** Shown as a tooltip. */
34 hint?: string;
35 /** Shown in the Play layer (the handful of knobs a player would reach
36 * for); everything else appears only in Build. */
37 musical?: boolean;
38}
40export type ObjectType = 'string' | 'bar' | 'membrane';
42export interface ObjectSpec {
43 /** Unique in the scene: 's1', 'b1', 'm1', ... */
44 id: string;
45 type: ObjectType;
46 /** Baked extents, metres: L1 along x (and L2 along y, for a membrane). */
47 size: { L1: number; L2?: number };
48 /** Model parameter values, by unsuffixed key (f0, t60, ...). */
49 params: Params;
50 /** Placement values, by unsuffixed key (oy, oz). Scene parameters. */
51 place: Params;
52}
54export type BodyType = 'none' | 'box' | 'shell';
56export interface BodySpec {
57 type: BodyType;
58 params: Params;
59}
61export interface SceneSpec {
62 objects: ObjectSpec[];
63 body: BodySpec;
64}
66export const defaultsOf = (specs: ParamSpec[]): Params =>
67 Object.fromEntries(specs.map((p) => [p.key, p.value]));
69/** The suffixed name a per-object thing gets in the generated MATLAB. */
70export const suffixed = (key: string, id: string): string => `${key}_${id}`;