Audio, NPC and cross-workspace recipes

Create pinned resources

1. Open RIDLEY → Audio. Upload MP3 or PCM16 WAV, give it a name, and use the UI insertion action to obtain an audio declaration with the real asset ID/hash.
2. Open NPCs. Create a persona with bounded knowledge and allowed topics; bind it to an existing scene actor.
3. Insert the persona declaration with its real immutable profile revision/hash.
4. Compile source and inspect resource diagnostics before playback.

The downloadable complete source and matching resources use a generated one-second tone and a generic guide profile. They are compiled automatically. The generic desk/table identities act as test proxies, not animated human characters.

Cross-workspace experience

\npc[actor=@desk,persona=@guide];
\cinematic[id=tour]{
  \sync[]{
    \shot[id=opening,type=medium,subject=@desk,movement=pan,amount=0.1,duration=3s];
    \dialogue[id=hello,actor=@desk,text="Welcome to the workshop.",duration=3s];
    \action[id=look,actor=@desk,action=look-at,target=@table,duration=3s];
    \sfx[id=chime,track=@theme,spatial=@desk,volume=0.2];
  }
  \music[id=music_start,track=@theme,volume=0.3,fade=200ms];
  \wait[id=pause,duration=1s];
  \return[id=done];
}
\trigger[id=near_table,subject=@desk,target=@table,event=near,distance=0.8m,cinematic=tour];
\experience[initial=free]{
  \state[id=free]{
    \control[actor=@desk,owner=user];
    \camera[mode=third-person,owner=user];
    \follow[actor=@table,target=@desk,distance=1.2m,delay=1.5s,speed=1.2];
    \music[track=@theme,volume=0.3,loop=true];
  }
  \state[id=film,mode=cinematic,cinematic=tour]{}
  \state[id=talk,mode=conversation]{\conversation[actor=@desk,persona=@guide];}
  \on[id=enter,from=free,to=film,event="wright.room.enter",subject=@desk,target=@office,once=true];
  \on[id=chat,from=film,to=talk,event="ridley.complete"];
  \on[id=finish,from=talk,to=free,event="ridley.conversation.finished"];
}

This is the body after the audio/persona declarations generated by the UI; use the complete download for exact fixture pins. @office resolves to the WRIGHT room, @desk/@table to QWAY instances, @theme/@guide to pinned RIDLEY resources. The user controls the first proxy in free mode, entering office starts tour, completion enters talk, and ending conversation returns to free.

Soundtrack policies

Use music action=play (default) to start a track, action=stop to stop it, or action=crossfade with from=@old and track=@new. volume is a scalar in [0,1], fade is seconds/milliseconds, loop defaults true. State music persists across transitions unless a command changes it; re-entering a state does not imply restarting every track. Pause/resume is a runtime audio control, not an unsupported music action=pause.

SFX is instantaneous scheduling, optionally spatial at an object. Audio enable requires a browser user gesture. Dialogue with a RIDLEY voice declaration is compiled into cached MP3 speech during WorldPack export. Narration supports per-cue voice settings; subtitles remain silent.

Conversation lifecycle

Persona revisions include personaId, profileId, parentId, revision, createdAt and a verified hash over the description. Profiles contain name, role, instructions, knowledge, speakingStyle, language, allowed/forbiddenTopics, emotionalBaseline, memory and maxTurns/maxHistoryChars. Accepted source pins the revision. Explicitly adopt a new revision; never infer from the latest profile silently.

A conversation has session/request/turn identity, bounded transcript and an optional provider transport. Stale replies are not applied to a different active session. End conversation emits completion and releases ownership. No tools, persistent learning or provider-driven scene mutation are available. Configure the provider in the API environment; exported hosts must supply their own intentional transport.

API provider settings

Settings can be read from the API environment/.env. Do not commit secrets. A fake provider is deterministic test behavior, not a substitute for understanding arbitrary prompts. Enable a real provider only intentionally; manual editing and playback remain available offline.

Replace a standard asset with a user asset

Import your own desk, set a distinct alias such as desk-custom, and select the existing desk instance. Use replacement tools or an unambiguous bounded prompt: “replace this desk with my desk-custom”. Review preserved identity, explicit height/up/front settings and any remapped surface dependencies. If the old worktop has no valid replacement feature, resolve that diagnostic rather than pretending it still exists. Save/reload and use Undo to inspect the pinned previous dependency.