SDK API リファレンス

作成と接続待ち

import { createVifuSDK } from "@vifu/sdk";

const vifu = createVifuSDK();
await vifu.ready();

console.log(vifu.status());

ready() は Vifu の中で必要な接続を待ちます。通常のローカルブラウザーでは、ゲームが動き続ける代替処理を用意してください。

AI

const result = await vifu.ai.generateText({
  model: "basic",
  messages: [{ role: "user", content: "プレイヤーが青いドアを開けたいと言っています。" }],
  tools: {
    openDoor: {
      description: "Open a visible door by color.",
      parameters: {
        type: "object",
        properties: {
          color: { type: "string", enum: ["blue", "red", "green"] }
        },
        required: ["color"],
        additionalProperties: false
      },
      execute: ({ color }) => openDoor(String(color))
    }
  },
  maxSteps: 3
});

generateText は多くのゲームのデフォルト AI API です。prompt または messages を受け取り、execute を持つ普通のツールオブジェクトも直接受け取れます。Vifu が provider ルーティング、使用量、バックエンド認証情報を扱います。

model はプロバイダー名ではなく Vifu のモデル階層名です。現在の公開ドキュメントでは basic と quality を使います。

どの AI API を使うか

場面	API
ゲーム内に現在の AI フローが 1 つだけある	vifu.ai.generateText(...)
現在のリクエストだけにツールを渡す	vifu.ai.generateText({ tools })
複数の独立した runtime entity がある	vifu.agent(...) + vifu.run(...)

Runtime Agent

const openDoorTool = vifu.tool({
  name: "open_door",
  description: "Open a visible door by color.",
  parameters: {
    type: "object",
    properties: {
      color: { type: "string", enum: ["blue", "red", "green"] }
    },
    required: ["color"],
    additionalProperties: false
  },
  execute: ({ color }) => openDoor(String(color))
});

const guard = vifu.agent({
  name: "Blue Door Guard",
  kind: "npc",
  instructions: "You guard the current puzzle room.",
  tools: [openDoorTool]
});

Runtime Agent は、NPC、チューター、AI パートナー、ナレーターなどの実行時エンティティです。ツール、指示、run session を個別に持ちます。 Vifu は内部 runtime id を自動で割り当てます。ログや trace で読みやすくしたい場合は name を渡してください。mind を省略すると、ユーザーまたはホストが現在の Mind を選びます。

const result = await vifu.run(guard, "プレイヤーが青いドアを開けたいと言っています。", {
  state: currentRoomSummary(),
  maxSteps: 3
});

このリクエストだけで有効な表示中ツールは、run に直接渡せます。このツールはそのリクエストだけで使われます。

await vifu.run(guard, "見えているドアを開けてください。", {
  tools: [openDoorTool]
});

リソース

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

ゲームコードで /v1/assets/runtime-* や公開後の URL を組み立てないでください。SDK がホスト管理の URL とトークンを隠します。

ゲーム状態

await vifu.gameState.save("autosave", {
  room: "blue-door",
  inventory: ["key"]
});

const checkpoint = await vifu.gameState.load("autosave");

プラットフォーム機能

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

通常は高レベル API を優先し、必要な場合だけ vifu.invoke を使います。