Vifu Hub SDK API リファレンス

import と接続待ち

import * as hub from "@vifu/hub";

await hub.ready();

console.log(hub.status());

すべてのプラットフォーム機能は hub モジュール名前空間から使います。ready() は Vifu の中で必要な接続を待ちます。通常のローカルブラウザーでは、ゲームが動き続ける代替処理を用意してください。

AI

const result = await hub.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 つだけある	hub.ai.generateText(...)
現在のリクエストだけにツールを渡す	hub.ai.generateText({ tools })
複数の独立した runtime entity がある	hub.agent(...) + hub.run(...)

Runtime Agent

const openDoorTool = hub.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 = hub.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 hub.run(guard, "プレイヤーが青いドアを開けたいと言っています。", {
  state: currentRoomSummary(),
  maxSteps: 3
});

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

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

リソース

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

hub.resources はホスト管理の URL とトークンを解決します。

ゲーム状態

hub.gameState.configure({
  slotId: "autosave",
  source: "my-game",
  serialize: () => ({ room: "blue-door", inventory: ["key"] }),
  restore: (stateBlob) => restoreGame(stateBlob)
});

await hub.gameState.restore();
await hub.gameState.save({ reason: "level-complete" });

プラットフォーム機能

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

各プラットフォーム機能には hub.dictionary、hub.voice、hub.review、hub.camera などの名前空間 API を使います。