SDK API リファレンス

ツール@vifu/[email protected]

Protocolcompanion.plugin.v1

実行環境Browser

状態公開 alpha

API

API	用途
createVifuSDK(options)	SDK インスタンスを作成します。ゲームでは transport: "auto" を使います。
context(name, definition)	companion が読めるゲーム状態を登録します。
command(name, definition)	companion が依頼できるアプリ所有のアクションを登録します。
observe(type, data, options)	通常のゲームプレイ事実を host に報告します。
signal(type, definition)	companion に注目してほしい少数の重要なタイミングを定義します。
Vifu.resources.readJson(id) / Vifu.resources.readText(id)	ホスト管理のランタイムリソースを読み取ります。
Vifu.resources.dataUrl(id) / Vifu.resources.mediaUrl(id) / Vifu.resources.fileUrl(path)	ホスト管理のランタイム URL を解決します。
invoke(capabilityId, args)	host またはバックエンドが所有するプラットフォーム能力を要求します。
status()	SDK バージョン、プロトコル、transport、host 接続状態を返します。
isHostConnected()	host 初期化後に true を返します。

Context

companion.context("scene.current", {
  description: "Current scene and objective",
  read: () => ({ scene: "market", objective: "Ask for water" })
});

read が返す値は prompt に入ります。token、隠し答え、私的なメモは含めないでください。

Command

companion.action("dialogue.repeat", {
  title: "Repeat line",
  inputSchema: { type: "object", properties: {}, additionalProperties: false },
  handler: () => ({ ok: true })
});

Command は小さく、プレイヤーに見える効果を持つものにしてください。

Resource

const episode = await Vifu.resources.readJson("episode");
const coverUrl = Vifu.resources.mediaUrl("cover");
const bundledAudio = Vifu.resources.fileUrl("./runtime-package/audio/intro.mp3");

resource はホスト管理のランタイムデータとメディアの公開入口です。SDK は runtime base URL、preview route、token を host adapter の内側に隠します。ゲームコードで /v1/assets/runtime-* や /preview-* URL を直接組み立てないでください。

Invoke

const result = await Vifu.services.invoke("vifu.dictionary.lookup", {
  text: "通っています"
});

await Vifu.services.invoke("host.game_state.persist", {
  slotId: "autosave",
  stateBlob: { cardId: "card-1" },
  source: "anki-runtime"
});

invoke(capabilityId, args) は host またはバックエンドが所有するプラットフォーム能力を要求します。プラットフォーム能力をゲーム command として登録したり、機能ごとの公開 SDK wrapper を増やしたり、直接 postMessage を送らないでください。