Avatar Control Client
Status: Admitted Contract; Release-Gated Surface
The runtime avatar control client contract is admitted at the SDK kernel level. The contract pins how an SDK consumer may control avatar state from outside the Avatar carrier; the client surface is usable only when present in SDK package exports.
What This Client Does
The Avatar Control Client is the SDK surface for an app that wants to drive avatar state — request an activity, set an emotion, push a presentation update — through admitted runtime projection. It is not a way to reach into Live2D / VRM directly; backend execution remains inside Avatar.
Boundary
| Owns | Does NOT own |
|---|---|
| Typed runtime-side avatar control surface | Live2D / VRM execution |
| Authorization through admitted runtime projection | Per-frame parameter writes |
| Anchor-scoped activity / emotion / presentation requests | Renderer-local interpolation |
The SDK call goes through Runtime; Runtime emits the typed runtime.agent.presentation.* projection event; Avatar consumes the projection. The SDK does not bypass that chain.
Reader Scenario: An App Triggers An Avatar Wave
An app wants the user's agent to wave when a milestone happens.
- App calls SDK.
controlClient.requestActivity(activityId: 'wave', anchor). - SDK validates. Activity id is in admitted activity ontology; anchor is valid.
- Runtime processes. Emits
runtime.agent.presentation.activity_requestedevent. - Avatar consumes. Projection routes through the active backend branch; wave plays.
- Audit lineage. Activity request is attributed to the app via admitted scoped binding.
Reader Scenario: An App Pushes A Presentation Update
App wants to set the agent's expression for a UI moment.
- App calls SDK.
controlClient.requestExpression('happy', anchor). - Runtime emits.
presentation.expression_requestedevent. - Avatar consumes. Backend renders.
- Anchor scope honored. The change applies to the anchor's stream; not as a global agent state without admitted scope.
What This Client Does Not Do
- It does not bypass the
runtime.agent.*projection. - It does not write Live2D / VRM parameters directly.
- It does not invent activity / emotion / pose ids outside the admitted ontology.
- It does not allow control without an admitted anchor.