Puppet

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

フィールド:

• backend: string - 登録済みバックエンドが応答する名前。必須。指定がない Puppet はコンストラクション時に例外をスローします。
• 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 を参照

特に扱う価値のある値が2つあります。"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");

1つの数値パラメーターを設定し、他のすべてのパラメーターはそのままにします。

• id: string - パラメーターの id
• value: number - その新しい値

id が何を意味するかはバックエンドの領分です。リグのパラメーター、ボーンの上書き、ブレンドウェイトなど、何でもかまいません。エンジンはそれを記憶し、セーブし、ロード時にはマップ全体を返します。

alice.setParam("ParamAngleX", 12);

1つの自由な文字列スロットを設定し、他のすべてのスロットはそのままにします。

• 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 - 画像と同じルールでソースを URL に解決します。プリロード を参照。
• resolveSibling(relativePath: string): string - この Puppet 自身の src を基準にしたパス、つまり同じバンドル内の兄弟ファイルを解決します。モデルバンドル内のファイルを解決する を参照。
• warn(message: string, detail?: unknown): void - 致命的でない問題を報告します。エンジンはそれをログに記録し、ステージを存続させます。例外がスローされることはありません。

1つのマウント済みモデル。エンジンが保持するのはこのハンドルだけです。各メンバーがいつ呼び出されるかについては、バックエンドのライフサイクル を参照してください。

• 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> - 自由な文字列スロット。上記3つの名前がカバーしないものに使用します。

ストーリーが一回限りの 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[] - 登録されているすべてのバックエンドの名前を、登録順に並べたもの。