Puppet

• config: Partial<IPuppetUserConfig> & {backend: string; src: string}

字段：

• backend: string - 已注册后端所响应的名字。必填；缺少时构造阶段抛出异常
• src: string - 交给后端的资源描述符，原样传递。必填
• options: Record<string, unknown> - 后端专属选项，原样传递。默认 {}
• size: PuppetSize | null - 盒子的逻辑尺寸，单位像素。默认 null，表示舞台尺寸
• layer?: Layer - 参见 Layer
• className?: string - 盒子的类名。它们落在承载盒子 position: relative 与宽高的那个元素上，也就是交给 mount 的容器的父元素，而不是容器本身。再往上一层是写入变换的包裹元素，所以在这里用类名设置 transform 会被逐帧覆盖
• motion: string | null - 初始动作。属于存档状态，能通过存读档往返
• expression: string | null - 初始表情
• skin: string | null - 初始皮肤
• params: Record<string, number> - 初始数值参数
• slots: Record<string, string | null> - 初始字符串槽位

以及可显示元素的全部变换属性：position、scale、rotation、opacity 等

const alice = new Puppet({
    backend: "swatch",
    src: "models/alice/alice.model.json",
    options: {outline: true},
    motion: "idle",
    params: {ParamAngleX: 12},
});

绘制该 Puppet 的后端当前处于什么状态

• 返回 PuppetStatus - 参见 PuppetStatus

其中两个值值得处理。"missing-backend" 表示没有后端响应 config.backend，"error" 表示后端抛出异常或模型加载失败。这两种情况下元素仍在舞台上、仍参与变换、仍会存档，只是没有被绘制

状态描述的是活的实例，不属于存档：读档会重新挂载，状态从 "unmounted" 重新开始

if (alice.getStatus() === "missing-backend") {
    // 本工程依赖的渲染器从未被注册
}

监听该 Puppet 的状态变化，回调收到新状态

• listener: (status: PuppetStatus) => void - 以新状态调用
• 返回 LiveGameEventToken - dispose 它以停止监听

后端是异步失败的：元素先挂载，模型随后加载成功或失败。要知道渲染器是否起来了，订阅这个事件

const token = alice.onStatusChange((status) => {
    if (status === "error") console.warn("Alice is not being drawn");
});

覆盖该 Puppet 使用的图层

• layer: Layer - 参见 Layer
• 返回 this

puppet.useLayer(foreground);

请求一个具名动作，通常是模型稳定下来后循环播放的那个

• motion: string | null - 要请求的动作，null 表示清空

这是持久状态而非一次性动作：它会被保存，并在模型下次挂载时被完整重新应用。只播一次就结束的动作属于 command。剧本不会等待后端摆出这个姿态

alice.setMotion("idle");

请求一个具名表情。与动作一样属于持久状态

• expression: string | null - 要请求的表情，null 表示清空

alice.setExpression("smile");

请求一套具名皮肤或服装。与动作一样属于持久状态

• skin: string | null - 要请求的皮肤，null 表示清空

alice.setSkin("winter");

设置一个数值参数，其余参数保持原样

• id: string - 参数 id
• value: number - 新值

id 的含义由后端决定：绑定参数、骨骼覆盖、混合权重都可以。引擎只负责记住它、保存它，并在读档时把整张映射交回去

alice.setParam("ParamAngleX", 12);

设置一个自由字符串槽位，其余槽位保持原样

• id: string - 槽位 id
• value: string | null - 新值；null 清空该槽位

槽位用于 motion / expression / skin 覆盖不到的具名内容：挂点、替换上去的道具，或某个渲染器自己的叫法

alice.setSlot("prop", "umbrella");

向后端发送一条引擎既不建模也不解释的命令

• name: string - 原样转发
• payload?: unknown - 原样转发
• options?: PuppetCommandOptions - 参见 PuppetCommandOptions

用于 PuppetState 不覆盖的部分：只播一次就结束的动作、命中测试、口型同步。这些都不会被保存，因此读档不恢复、撤销不撤回。需要留存的内容请通过上面的 set* 方法写进状态

不主动要求，剧本就不会等待

alice.command("playMotion", {id: "wave"});                  // 剧本直接继续
alice.command("playMotion", {id: "bow"}, {await: true});    // 这一句会等它结束

• name: string - Puppet 的 backend 配置所指向的键
• mount(container: HTMLDivElement, ctx: PuppetMountContext): PuppetInstance - 创建绑定到宿主元素的实例。引擎负责盒子，后端负责盒子内部。实例被 dispose 时容器会被清空

挂载后端时引擎交给它的信息

• src: string - Puppet 声明的资源描述符，原样传递。引擎唯一会从中读出的结构是它所在的目录，而且只通过 resolveSibling
• options: Readonly<Record<string, unknown>> - 作者为该后端提供的选项，原样传递
• size: PuppetSize - 盒子的逻辑尺寸，单位像素。之后的变化通过 resize 送达
• resolveSrc(src: string): string - 按照与图片相同的规则解析资源。参见 预加载
• resolveSibling(relativePath: string): string - 解析相对于该 Puppet 自身 src 的路径，即同一套文件里的同级文件。参见 解析模型包内的文件
• warn(message: string, detail?: unknown): void - 报告非致命问题。引擎会记录并保持舞台存活，绝不抛出

一个已挂载的模型。引擎持有的只有这个句柄。各成员何时被调用参见 后端调用顺序

• ready(): Promise<void> - 模型加载完成且第一帧绘制之后 resolve
• apply(state: Readonly<PuppetState>): void | Promise<void> - 应用完整状态。挂载时先调用一次，早于 ready()，之后每次变化都会调用
• command(name: string, payload: unknown): void | Promise<void> - 执行具名命令。引擎不解释 name 与 payload。返回 promise 可以让传了 {await: true} 的调用方等待它；默认不等待
• resize(size: PuppetSize): void - 盒子尺寸发生变化
• describe?(): Promise<PuppetDescription> - 可选。向编辑器宿主描述模型
• dispose(): void - 拆除实例。之后容器会被清空

describe 不受状态限制，mount 与 dispose 之间的任何时刻都可能被调用，包括 ready() resolve 之前，也可能被多次调用。只有加载完成才能描述的后端，请在 describe 内部等待自己的加载。reject 也是安全的：宿主会记录日志并退回到让作者手动输入名字

各字段的空值语义参见 null 的含义

• motion: string | null - 当前请求的具名动作，通常是模型稳定下来后循环播放的那个
• expression: string | null - 当前请求的具名表情
• skin: string | null - 当前请求的具名皮肤／服装
• params: Record<string, number> - 自由数值参数
• slots: Record<string, string | null> - 自由字符串槽位，用于上面三个名字覆盖不到的内容

剧本如何对待一次性 command

• await?: boolean - 剧本继续之前等待后端完成该命令。默认 false

等待中的命令与其他计时动作一样可以跳过

模型对编辑器宿主的自述，宿主据此用活实例的数据填充检查器里的下拉框。无法回答的后端不实现 describe，宿主则退回到让作者手动输入名字

• motions: string[]
• expressions: string[]
• skins: string[]
• params: {id: string; min: number; max: number; default: number}[]
• size: PuppetSize | null - 模型自己的画布尺寸，不提供时为 null

• width: number
• height: number

逻辑像素

• game.registerPuppetBackend(backend: PuppetBackend): this - 注册一个后端。返回 game 本身，可链式调用
• game.getPuppetBackend(name: string): PuppetBackend | null - 某个名字下注册的后端，没有则为 null
• game.listPuppetBackends(): string[] - 所有已注册后端的名字，按注册顺序