@gameable/conversation

Interfaces

ConversationCharacter

Story configuration is host-owned; game code names only a character id.

Properties

prefabs?

optional prefabs?: Readonly<Record<string, readonly SpeechChunk[] | undefined>>;

This character's prepared performances, selected by the service.

storyId

storyId: string;

url

url: string;

---

ConversationModule

Session control. Ending an interview retains its session and story revision.

Extends

• EngineModule

Properties

id

readonly id: string;

Unique id. Also the service id when init returns a service.

Inherited from

EngineModule.id

order?

readonly optional order?: number;

Sort key. Lower runs first; equal keys keep registration order.

Rough convention: input -100, gameplay -50, physics 0, rendering helpers 200. Gameplay runs before physics so that the commands a guest tick emits are simulated by the step that follows rather than the next one.

Inherited from

EngineModule.order

Methods

ask()

ask(text): boolean;

Parameters

Parameter	Type
text	string

Returns

boolean

beginFrame()?

optional beginFrame(): void;

Run before the frame's fixed steps. Input capture lives here.

Returns

void

Inherited from

EngineModule.beginFrame

dispose()

dispose(): void;

Release everything this module took.

Returns

void

Inherited from

EngineModule.dispose

end()

end(): void;

Returns

void

endFrame()?

optional endFrame(): void;

Run after rendering. Input's end-of-frame bookkeeping lives here.

Returns

void

Inherited from

EngineModule.endFrame

fixedUpdate()?

optional fixedUpdate(dt): void;

Run once per fixed step.

Parameters

Parameter	Type	Description
dt	number	Always ctx.config.fixedDt, whatever time.timeScale is; time scale changes how many steps a frame runs, not their length.

Returns

void

Inherited from

EngineModule.fixedUpdate

init()

init(ctx): void | object | Promise<void | object>;

Acquire resources.

Parameters

Parameter	Type	Description
ctx	HostContext	The host surface.

Returns

void | object | Promise<void | object>

Nothing, or the service to publish under id.

Inherited from

EngineModule.init

interrupt()

interrupt(): void;

Returns

void

start()

start(character): void;

Parameters

Parameter	Type
character	string

Returns

void

update()?

optional update(dt, alpha): void;

Run once per frame, after the fixed steps and before rendering.

Parameters

Parameter	Type	Description
dt	number	Clamped wall-clock seconds since the previous frame, scaled by time.timeScale.
alpha	number	Interpolation factor in [0, 1) for smoothing transforms.

Returns

void

Inherited from

EngineModule.update

---

ConversationOptions

Optional conversation dependencies and callbacks.

Properties

characters

characters: Readonly<Record<string, ConversationCharacter | undefined>>;

player

player: SpeechPlayer;

prefabs?

optional prefabs?: Readonly<Record<string, readonly SpeechChunk[] | undefined>>;

Prepared performances keyed by Convorcher prefab id; no story mutations.

Methods

connect()?

optional connect(url): ConversationSocket;

Parameters

Parameter	Type
url	string

Returns

ConversationSocket

onError()

onError(message): void;

Parameters

Parameter	Type
message	string

Returns

void

onStatus()

onStatus(status): void;

Parameters

Parameter	Type
status	string

Returns

void

onStory()

onStory(character, snapshot): void;

Parameters

Parameter	Type
character	string
snapshot	StorySnapshot

Returns

void

---

ConversationSocket

Browser connection surface; injectable for service replay tests.

Properties

onclose

onclose: ((event) => void) | null;

onerror

onerror: ((event) => void) | null;

onmessage

onmessage: ((event) => void) | null;

onopen

onopen: ((event) => void) | null;

readyState

readyState: number;

Methods

close()

close(): void;

Returns

void

send()

send(text): void;

Parameters

Parameter	Type
text	string

Returns

void

---

FaceFrame

Face frames use ARKit-52 ordering, with seconds relative to their audio chunk.

Properties

blendshapeWeights

blendshapeWeights: readonly number[];

timeCode

timeCode: number;

---

SpeechChunk

One bounded speech performance, already decoded from the service wire format.

Properties

frames

frames: readonly FaceFrame[];

gesture?

optional gesture?: string;

pcm

pcm: Uint8Array;

text

text: string;

---

SpeechPlayer

Audio-clock speech queue; update reuses a single facial vector.

Methods

dispose()

dispose(): void;

Returns

void

enqueue()

enqueue(chunk): void;

Parameters

Parameter	Type
chunk	SpeechChunk

Returns

void

stop()

stop(): void;

Returns

void

update()

update(): void;

Returns

void

---

SpeechPresentation

Presentation callbacks run on the audio clock.

Methods

expression()

expression(weights): void;

Parameters

Parameter	Type
weights	Float32Array

Returns

void

gesture()

gesture(id): void;

Parameters

Parameter	Type
id	string

Returns

void

reset()

reset(): void;

Returns

void

speaking()

speaking(active): void;

Parameters

Parameter	Type
active	boolean

Returns

void

subtitle()

subtitle(text): void;

Parameters

Parameter	Type
text	string

Returns

void

---

StorySnapshot

Stable full-state message emitted by Convorcher after analysis and on join.

Properties

completedObjectives

completedObjectives: string[];

currentPhase

currentPhase: string;

playerState

playerState: Record<string, string>;

revision

revision: number;

schemaVersion

schemaVersion: 1;

sessionId

sessionId: string;

storyId

storyId: string;

transitionCause

transitionCause: string;

Functions

acceptStorySnapshot()

function acceptStorySnapshot(
   current, 
   next, 
   sessionId, 
   storyId
): StorySnapshot | null;

Idempotent reducer scoped to an expected session and story.

Parameters

Parameter	Type	Description
current	StorySnapshot | null	Last accepted snapshot.
next	StorySnapshot	Candidate snapshot.
sessionId	string	Expected session.
storyId	string	Expected story.

Returns

StorySnapshot | null

The accepted snapshot, or the previous state.

---

conversation()

function conversation(options): ConversationModule;

Build an optional session manager. Construction does not connect to any service.

Parameters

Parameter	Type	Description
options	ConversationOptions	Explicit character allow-list, playback and callbacks.

Returns

ConversationModule

An engine module. Call start only after an interview is requested.

---

createSpeechPlayer()

function createSpeechPlayer(
   context, 
   presentation, 
   destination?
): SpeechPlayer;

Build a bounded PCM player. The caller creates/resumes the context in a user gesture.

Parameters

Parameter	Type	Default value	Description
context	AudioContext	undefined	Shared or dedicated audio clock.
presentation	SpeechPresentation	undefined	Subtitles, gestures and facial rig.
destination	AudioNode	context.destination	Voice bus; defaults to the context destination.

Returns

SpeechPlayer

A player which owns only its sources, not the context.

---

parseStorySnapshot()

function parseStorySnapshot(value): StorySnapshot | null;

Validate a bounded, versioned story snapshot.

Parameters

Parameter	Type	Description
value	unknown	Untrusted message data.

Returns

StorySnapshot | null

Owned snapshot, or null for invalid data.