@hypersoniclabs/helix-cli 0.1.25-helix3.523 → 0.1.25-helix3.525

package/dist/device.js

@@ -364,6 +364,9 @@ const DEVICE_GRAPH_MAX_BRANCH_DEPTH = 8;
  * The interaction `display` hint: `{ kind: 'time', stateKey }` renders an
  * epoch-millisecond state value in the VIEWER's local time ("rings 7:00 AM"),
  * and "Off" when it is 0 or absent. The hint is presentation only.
+ *
+ * `zoneOffsetStateKey` (optional) names an integer/float state holding the UTC offset in minutes of the zone the value was set in
+ * (engine 0.3.417+): the row then reads in that zone, labelled ("11:34 PM, UTC-7"), for every viewer instead of each viewer's own.
  */
 function validateInteractionDisplay(raw, id, state, errors) {
     const path = `interaction ${id} display`;
@@ -376,7 +379,7 @@ function validateInteractionDisplay(raw, id, state, errors) {
         errors.push(`${path}.kind must be "time"`);
     }
     for (const key of Object.keys(display)) {
-        if (key !== 'kind' && key !== 'stateKey') {
+        if (key !== 'kind' && key !== 'stateKey' && key !== 'zoneOffsetStateKey') {
             errors.push(`${path}: unknown field "${key}"`);
         }
     }
@@ -392,6 +395,19 @@ function validateInteractionDisplay(raw, id, state, errors) {
             errors.push(`${path}.stateKey "${String(display.stateKey)}" must be a float or integer state holding epoch milliseconds`);
         }
     }
+    if (display.zoneOffsetStateKey !== undefined) {
+        const zoneKey = String(display.zoneOffsetStateKey);
+        const zoneSpec = object(state[zoneKey]);
+        if (!isNonEmptyName(display.zoneOffsetStateKey)) {
+            errors.push(`${path}.zoneOffsetStateKey must be a non-empty state key`);
+        }
+        else if (state[zoneKey] === undefined) {
+            errors.push(`${path}.zoneOffsetStateKey "${zoneKey}" is not declared in state`);
+        }
+        else if (zoneSpec.type !== 'float' && zoneSpec.type !== 'integer') {
+            errors.push(`${path}.zoneOffsetStateKey "${zoneKey}" must be a float or integer state holding minutes east of UTC`);
+        }
+    }
 }
 /**
  * Validate one behavior-graph step list, recursing into every nested list.
@@ -461,8 +477,36 @@ function validateGraphSteps(steps, context, path, depth) {
                 graphNode(context, step.node, stepPath);
                 if (!['x', 'y', 'z'].includes(String(step.axis)))
                     context.errors.push(`${stepPath}: rotateNode axis must be x, y or z`);
-                if (!['toAngle', 'stop'].includes(String(step.mode)))
-                    context.errors.push(`${stepPath}: rotateNode mode must be toAngle or stop`);
+                if (!['toAngle', 'stop', 'spin', 'sweep'].includes(String(step.mode)))
+                    context.errors.push(`${stepPath}: rotateNode mode must be toAngle, stop, spin or sweep`);
+                // spin turns continuously at `rpm` (an expression, so Speed can drive it); sweep swings `amplitudeDeg` either side every `periodMs`
+                // (device audio r7 engine). Both are presentation only.
+                if (step.mode === 'spin') {
+                    if (step.rpm === undefined)
+                        context.errors.push(`${stepPath}: rotateNode spin needs rpm`);
+                    else
+                        validateGraphExpr(step.rpm, context, `${stepPath}.rpm`);
+                }
+                else if (step.rpm !== undefined) {
+                    context.errors.push(`${stepPath}: rotateNode rpm applies to mode "spin" only`);
+                }
+                if (step.mode === 'sweep') {
+                    if (step.amplitudeDeg === undefined || step.periodMs === undefined)
+                        context.errors.push(`${stepPath}: rotateNode sweep needs amplitudeDeg and periodMs`);
+                    if (step.amplitudeDeg !== undefined &&
+                        (!isFiniteNumber(step.amplitudeDeg) ||
+                            step.amplitudeDeg < 0 ||
+                            step.amplitudeDeg > 180))
+                        context.errors.push(`${stepPath}: rotateNode amplitudeDeg must be a number from 0 to 180`);
+                    if (step.periodMs !== undefined &&
+                        (!isFiniteNumber(step.periodMs) ||
+                            step.periodMs < 200 ||
+                            step.periodMs > 60_000))
+                        context.errors.push(`${stepPath}: rotateNode periodMs must be a number from 200 to 60000`);
+                }
+                else if (step.amplitudeDeg !== undefined || step.periodMs !== undefined) {
+                    context.errors.push(`${stepPath}: rotateNode amplitudeDeg and periodMs apply to mode "sweep" only`);
+                }
                 if (step.targetDeg !== undefined)
                     validateGraphExpr(step.targetDeg, context, `${stepPath}.targetDeg`);
                 if (step.durationMs !== undefined && !isFiniteNumber(step.durationMs))
@@ -1240,7 +1284,8 @@ function applySteps(steps, definition, state, budget) {
 }
 function invoke(definition, state, interaction, value) {
     const control = object(interaction.control);
-    if (control.stateKey && value !== undefined) {
+    // a time control's value is a time of day, not the state value: its action writes the instant
+    if (control.stateKey && control.kind !== 'time' && value !== undefined) {
         const key = String(control.stateKey);
         state[key] = coerce(object(object(definition.state)[key]), value);
     }
@@ -1258,6 +1303,8 @@ function exerciseValue(interaction, state) {
     const control = object(interaction.control);
     if (control.kind === 'number')
         return Number(control.max ?? control.min ?? 1);
+    if (control.kind === 'time')
+        return 7 * 3600 + 35 * 60; // seconds after the viewer's local midnight
     if (control.kind === 'choice') {
         const options = Array.isArray(control.options)
             ? control.options.map(object)
@@ -1470,6 +1517,41 @@ function validateDeviceProject(input, options = {}) {
             if (part.pivot !== undefined && part.pivot !== 'bottom') {
                 errors.push(`${partPath}.pivot must be bottom`);
             }
+            // `parent` (device audio r7 engine): position and rotationDeg are then in that part's frame and a step that moves the parent carries its subtree.
+            if (part.parent !== undefined) {
+                if (typeof part.parent !== 'string' || !part.parent.length || part.parent.length > 64) {
+                    errors.push(`${partPath}.parent must be the name of another part`);
+                }
+                else if (part.parent === name) {
+                    errors.push(`${partPath}.parent cannot be the part itself`);
+                }
+                else if (!Object.prototype.hasOwnProperty.call(parts, part.parent)) {
+                    errors.push(`${partPath}.parent "${part.parent}" is not a part of this model`);
+                }
+                else {
+                    let depth = 0;
+                    let cursor = name;
+                    const seen = new Set();
+                    while (cursor !== undefined && object(parts[cursor]).parent !== undefined) {
+                        if (seen.has(cursor)) {
+                            errors.push(`${partPath}.parent chain loops back on "${cursor}"`);
+                            break;
+                        }
+                        seen.add(cursor);
+                        const next = object(parts[cursor]).parent;
+                        cursor = typeof next === 'string' ? next : undefined;
+                        depth += 1;
+                        if (depth > 8) {
+                            errors.push(`${partPath}.parent chain is deeper than 8`);
+                            break;
+                        }
+                    }
+                }
+            }
+            // `origin`: the shape-local point that sits at `position` and that the part (and its children) turns about (generalises pivot "bottom").
+            if (part.origin !== undefined && !isNumberTriple(part.origin)) {
+                errors.push(`${partPath}.origin must be three numbers`);
+            }
             if (part.color !== undefined && !Number.isInteger(part.color)) {
                 errors.push(`${partPath}.color must be an integer`);
             }
@@ -1650,6 +1732,32 @@ function validateDeviceProject(input, options = {}) {
                         errors.push(`interaction ${id} disabled choice "${String(option.value)}" needs a reason`);
                 }
             }
+            else if (control.kind === 'time') {
+                // A time of day set and shown in the VIEWER's zone (device audio r7 engine). The room keeps one absolute instant in `stateKey`; the control's
+                // `value` is seconds after the viewer's local midnight and is NOT written to the state: the action turns it into the instant.
+                if (!['float', 'integer'].includes(String(spec.type)))
+                    errors.push(`interaction ${id} time control stateKey "${key}" must be a declared integer or float state (epoch milliseconds)`);
+                if (control.setStateKey !== undefined) {
+                    const setSpec = object(state[String(control.setStateKey)]);
+                    if (!['float', 'integer'].includes(String(setSpec.type)))
+                        errors.push(`interaction ${id} time control setStateKey "${String(control.setStateKey)}" must be a declared integer or float state (epoch milliseconds)`);
+                }
+                if (control.stepMinutes !== undefined &&
+                    (!Number.isInteger(control.stepMinutes) ||
+                        Number(control.stepMinutes) < 1 ||
+                        Number(control.stepMinutes) > 60))
+                    errors.push(`interaction ${id} time stepMinutes must be an integer 1..60`);
+                const action = object(interaction.action);
+                if (interaction.action === undefined) {
+                    errors.push(`interaction ${id} a time control needs an action that turns value (seconds after the viewer's local midnight) into the instant`);
+                }
+                else if (!Object.values(object(action.args)).some((arg) => {
+                    const a = object(arg);
+                    return a.type === 'number' && a.fill === 'viewer.localMidnightSec';
+                })) {
+                    errors.push(`interaction ${id} a time control's action needs a number arg with fill "viewer.localMidnightSec" to turn the time of day into an instant`);
+                }
+            }
             else if (control.kind === 'text') {
                 if (spec.type !== 'string')
                     errors.push(`interaction ${id} text control must target string state`);
@@ -1668,7 +1776,7 @@ function validateDeviceProject(input, options = {}) {
                 }
             }
             else if (control.kind === undefined) {
-                errors.push(`interaction ${id} control requires a kind (number|choice|text)`);
+                errors.push(`interaction ${id} control requires a kind (number|choice|text|time)`);
             }
             else {
                 errors.push(`interaction ${id} uses unsupported control kind "${String(control.kind)}"`);