Moonborn — Developers

NPC scene orchestration

Pair Moonborn's chat runtime with your game engine's scene state. Turn order, branching, save/load — what belongs on which side.

Moonborn is the character layer. Your game engine is the scene layer. This guide is the boundary.

What Moonborn owns

Persona generation + persistence.
Per-reply voice fingerprinting + drift detection.
Ensemble relationships (typed edges between personas).
Long-term memory for each chat session.

What your engine owns

Scene state machine — who is on stage, who can speak.
Turn order — round-robin, initiative, narrative cue.
Branching narrative — which scene fires next.
Save / load — serializing scene state alongside Moonborn session IDs.
The UI players touch.

Wiring pattern

// Engine side: define a scene with a cast.
const scene = new Scene({
  participants: [merchant, traveler, tavern_owner],
  turnOrder: 'narrative',
});
 
// Engine triggers a dialogue.
scene.onPlayerSay(async (text) => {
  // Pick who responds based on scene state.
  const speaker = scene.pickResponder(text);
 
  // Talk to Moonborn.
  const reply = await client.chat.sendMessage({
    sessionId: speaker.moonbornSessionId,
    speaker: speaker.personaId,
    content: text,
  });
 
  // Engine handles the reply — animation, UI, state transitions.
  scene.deliver(speaker, reply.content);
});

Multi-persona sessions

For scenes with multiple speakers, open one session with an ensemble array:

const session = await client.chat.createSession({
  personaId: merchant.id,
  ensemble: [traveler.id, tavern_owner.id],
  metadata: { sceneId: 'tavern_arrival' },
});

Each call passes a speaker field so the right persona answers. Drift scores are tracked per speaker, not per scene.

Save / load

The chat session ID is the persistence key. Save it alongside your scene state:

{
  "sceneId": "tavern_arrival",
  "turn": 14,
  "moonbornSessions": {
    "merchant": "sess_01H...",
    "traveler": "sess_01H...",
    "tavern_owner": "sess_01H..."
  }
}

On load, the session resumes — short-term memory is intact; long-term memory + voice fingerprint are still pinned.

Tier