Skip to main content
Version: 3.0 (next)
Coming soon

App Studio is coming soon: it is in development and testing and is not part of release 3.0. This reference describes the SDK as it is being built and may change before release.

Generated

Generated from the SDK sources by scripts/appstudio-sdk-docs.cjs for runtime-v1. Do not edit; run npm run appstudio:docs:sdk.

@maestrohub/scene

Coming soon: look up the scene kit an app uses to draw its line in 3D, with stations, buffers, finished goods and operators following live topics.

Runtime
runtime-v1
Exports
21 (10 values, 11 types)

The App Studio scene kit: a live 3D production line drawn from a scene spec and bound to topics.

Runtime: runtime-v1. 21 exports (10 values, 11 types). Import with:

import { ... } from '@maestrohub/scene';

Components​

Scene​

function Scene({ spec, values, onSelect, height, quality }: SceneProps): JSX.Element

Scene draws a production line from a scene spec and binds it to live topics: station state drives the stack light and motion, a rise in the good counter sends a part down the line, a rise in the reject counter drops one into the scrap bin, a buffer holds as many parts as its level. Needs uns:read for live topics (not for values).

Example

import scene from './scene.json';
<Scene spec={scene} onSelect={(id) => setSelected(id)} />

Functions​

bufferFill​

function bufferFill(raw: unknown, capacity: number): number

How many parts a buffer shows: the level clamped to 0..capacity.

counter​

function counter(raw: unknown): number | null

A counter value as a number (null when absent or not numeric).

plainValue​

function plainValue(v: unknown): unknown

Reads a plain value out of a topic value: the value itself, or its value / state field.

progress​

function progress(raw: unknown): number | null

Cycle progress as 0..1 (accepts 0..100), null when absent.

sceneTopics​

function sceneTopics(spec: SceneSpec): string[]

Every topic path a spec binds, once each.

stationState​

function stationState(raw: unknown, own?: Record<string, StationState>): StationState

stationState maps a raw state value to a kit state: the station's own map first, then the shared default map (upper-cased), booleans as running/off. Unknown values read as idle, never as running.

webglAvailable​

function webglAvailable(): boolean

True when this browser can draw WebGL at all.

Constants​

SCENE_VOCABULARY​

const SCENE_VOCABULARY: { version: number; kinds: StationKind[]; states: StationState[]; defaultStates: Record<string, StationState>; qualities: SceneQuality[]; maxStations: number; maxBuffers: number; maxCapacity: number; idPattern: string; maxLabelOffset: number; }

The shared vocabulary (also read by the server).

Members

  • defaultStates: Record<string, StationState>
  • idPattern: string
  • kinds: StationKind[]
  • maxBuffers: number
  • maxCapacity: number
  • maxLabelOffset: number
  • maxStations: number
  • qualities: SceneQuality[]
  • states: StationState[]
  • version: number

STATE_COLOR​

const STATE_COLOR: Record<StationState, string>

The colour each state shows on the stack light and the station label.

Members

  • blocked: string
  • faulted: string
  • idle: string
  • maintenance: string
  • off: string
  • running: string
  • starved: string

Types​

BufferSpec​

interface BufferSpec

A buffer conveyor on the line, filled by a level topic: after a station (after), or before one (before), which is how a raw material buffer sits ahead of the first station. Exactly one of the two.

Members

  • after?: string | undefined: The station this buffer follows.
  • before?: string | undefined: The station this buffer feeds: the buffer sits just upstream of it.
  • bind?: { level?: string; } | undefined
  • capacity: number: Parts the buffer holds when full.
  • id: string
  • label?: string | undefined
  • labelOffset?: LabelOffset | undefined: Moves the buffer's label.

LabelOffset​

interface LabelOffset

Moves a label from where the kit puts it, in metres along the line (x), up (y) and towards the viewer (z); each at most maxLabelOffset. For labels that crowd each other near the end of a long line.

Members

  • x?: number | undefined
  • y?: number | undefined
  • z?: number | undefined

ModelRef​

interface ModelRef

A .glb model stored as an attachment on an app record (it replaces the kit's body for the station).

Members

  • attachment: string: The attachment id of the .glb.
  • collection: string: The storage collection holding the record.
  • key: string: The record's key.
  • scale?: number | undefined: Uniform scale applied to the model (default 1).

OperatorSpec​

interface OperatorSpec

A person on the line. They stand at home; when a station they cover faults, they walk to it, work on it, and walk back once it recovers.

Members

  • covers?: string[] | undefined: Stations they answer (default: only home).
  • home: string: The station they stand at when nothing needs them.
  • id: string
  • label?: string | undefined
  • labelOffset?: LabelOffset | undefined: Moves the operator's name tag.
  • vest?: string | undefined: Vest colour (default hi-vis orange).

OutputSpec​

interface OutputSpec

Where finished parts pile up: pallets after a station, filled in layers.

Members

  • after: string: The station that puts parts here (often the last one, an unload robot).
  • bind?: { count?: string; } | undefined
  • id: string
  • label?: string | undefined
  • labelOffset?: LabelOffset | undefined: Moves the output's label (the count above its pallet).
  • perPallet?: number | undefined: Parts on one full pallet (default 24); a full pallet moves to the shipped stack.

SceneProps​

interface SceneProps

Props for Scene.

Members

  • height?: number | undefined: Height in pixels (default 460). The width follows the container.
  • onSelect?: ((stationId: string) => void) | undefined: A station was clicked (its id).
  • quality?: SceneQuality | undefined: Overrides the spec's quality.
  • spec: SceneSpec: The scene: usually import scene from './scene.json'.
  • values?: Record<string, unknown> | undefined: Topic path → value, instead of live topics: sample data, a replay, or values the app computed. When set, the scene subscribes to nothing.

SceneQuality​

type SceneQuality = 'low' | 'balanced' | 'high';

Rendering quality: balanced is the default for shop-floor screens.

SceneSpec​

interface SceneSpec

The whole scene: what src/scene.json holds.

Members

  • buffers?: BufferSpec[] | undefined
  • operators?: OperatorSpec[] | undefined
  • outputs?: OutputSpec[] | undefined
  • quality?: SceneQuality | undefined
  • stations: StationSpec[]
  • version: 1

StationKind​

type StationKind = 'cnc' | 'washer' | 'tester' | 'robot' | 'generic';

The kinds of station the kit can draw.

StationSpec​

interface StationSpec

One station on the line, drawn in spec order from left to right.

Members

  • bind?: { state?: string; good?: string; bad?: string; cycle?: string; } | undefined: Topic paths the station reads.
  • id: string: Unique within the scene; also the key onSelect reports.
  • kind: StationKind
  • label?: string | undefined: Shown above the station; defaults to the id.
  • labelOffset?: LabelOffset | undefined: Moves the station's label.
  • model?: ModelRef | undefined: A stored .glb drawn instead of the kit body.
  • states?: Record<string, StationState> | undefined: Raw state value → kit state, for values the default map does not know.

StationState​

type StationState = 'running' | 'idle' | 'starved' | 'blocked' | 'faulted' | 'maintenance' | 'off';

The states a station shows (stack light, motion, label).