Vifu Hub SDK API Reference

Import

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

await hub.ready();

All platform access is exposed through the hub module namespace.

ready

await hub.ready();

Waits until Vifu platform capabilities are ready when the game is running inside Vifu. Outside Vifu, the Vifu Hub SDK stays safe to load; design your game so it can still boot locally.

status

const status = hub.status();

Field	Description
`sdkVersion`	Vifu Hub SDK package version.
`hostConnected`	`true` when the game is connected inside Vifu.

ai.generateText

const result = await hub.ai.generateText({
  model: "quality",
  messages: [{ role: "user", content: "Describe the next room." }],
  tools: {
    openDoor: {
      description: "Open a visible door.",
      parameters: {
        type: "object",
        properties: { color: { type: "string" } },
        required: ["color"]
      },
      execute: async ({ color }) => openDoor(color)
    }
  }
});

generateText follows the AI SDK mental model: prompt or messages, optional tools, and tool execute handlers. Vifu owns provider routing, quota, and backend credentials.

Use this API for most games. It supports executable tools directly as plain objects, so an existing game can keep its local action functions and let the Vifu Hub SDK register them for the current AI turn.

tools may be an object keyed by tool name or an array of definitions created with hub.tool(...).

ai.chat

const response = await hub.ai.chat({
  messages: [{ role: "user", content: "Say hello as an NPC." }]
});

Returns a chat-completion-shaped response for games that already use that format.

Which AI API Should I Use?

Situation	API
One active AI flow in the game	`hub.ai.generateText(...)`
Temporary tools for the current request	`hub.ai.generateText({ tools })`
Multiple independent runtime entities	`hub.agent(...)` + `hub.run(...)`

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]
});

Creates a Runtime Agent: an NPC, tutor, companion, narrator, or other runtime participant with its own tools, instructions, and run session.

Option	Description
`name`	Optional human-readable name for debugging, traces, and handoffs.
`kind`	Product kind such as `npc`, `tutor`, `companion`, or `director`.
`mind`	Optional Mind/persona id. Omit it when the user or host should choose the active Mind.
`instructions`	Optional behavior instructions for this agent.
`tools`	Optional initial tool set for this agent.

Vifu assigns the internal runtime id automatically. Use name when you want the agent to be readable in logs and traces.

tool

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))
});

Creates a standard tool definition that can be passed to hub.agent(...), hub.run(...), or hub.ai.generateText(...).

Use hub.tool(...) when you want a reusable tool definition. For one-off hub.ai.generateText(...) calls, a plain object with description, parameters, and execute is also valid.

Use tools in hub.agent(...) for default tools, or pass tools to hub.run(...) when the tools are only valid for the current request.

run

const result = await hub.run(guard, "The player asks to open the blue door", {
  state: currentRoomSummary(),
  maxSteps: 3
});

Runs one model/tool loop for the target agent. Vifu keeps each agent's tools isolated, so multiple agents can run in the same game session without sharing tool state.

You can pass run-scoped tools when the visible actions are only valid for this specific request:

await hub.run(guard, "Open a visible door", {
  tools: [openDoorTool]
});

Those tools are only available for that request.

resources

const world = await hub.resources.readJson("world");
const text = await hub.resources.readText("script");
const imageUrl = hub.resources.mediaUrl("portrait");
const fileUrl = hub.resources.fileUrl("assets/player.png");

Method	Description
`readJson(id)`	Reads a declared JSON data resource.
`readText(id)`	Reads a declared text data resource.
`dataUrl(id, query?)`	Resolves a URL for declared runtime data.
`mediaUrl(id, query?)`	Resolves a URL for declared runtime media.
`fileUrl(path)`	Resolves a bundled runtime file path.

gameState

hub.gameState.configure({
  slotId: "autosave",
  source: "my-game",
  serialize: () => ({ level, inventory }),
  restore: (stateBlob) => restoreGame(stateBlob)
});

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

Use the high-level configure API for most games. For advanced platform calls, use hub.invoke(capabilityId, args) with an exact capability ID.

Platform capabilities

const definition = await hub.dictionary.lookup({
  text: "猫",
  language: "ja"
});

await hub.voice.speak({ text: "こんにちは" });
await hub.review.grade({ cardId: "card-1", answer: "猫" });

Platform capability calls must be declared through public manifest sections such as dictionary, voice, review, camera, or save.

Vifu Hub SDK API Reference ​

Import ​

ready ​

status ​

ai.generateText ​

ai.chat ​

Which AI API Should I Use? ​

agent ​

tool ​

run ​

resources ​

gameState ​

Platform capabilities ​