SDK API Reference

createVifuSDK

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

const vifu = createVifuSDK();

Option	Description
documentTitle	Optional name shown in Vifu debugging tools.

For static browser builds, use window.vifu from vifu-sdk.js.

ready

await vifu.ready();

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

status

const status = vifu.status();

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

ai.generateText

const result = await vifu.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 SDK register them for the current AI turn.

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

ai.chat

const response = await vifu.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	vifu.ai.generateText(...)
Temporary tools for the current request	vifu.ai.generateText({ tools })
Multiple independent runtime entities	vifu.agent(...) + vifu.run(...)

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

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

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

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

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

run

const result = await vifu.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 vifu.run(guard, "Open a visible door", {
  tools: [openDoorTool]
});

Those tools are only available for that request.

resources

const world = await vifu.resources.readJson("world");
const text = await vifu.resources.readText("script");
const imageUrl = vifu.resources.mediaUrl("portrait");
const fileUrl = vifu.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

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

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

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

Platform capabilities

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

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

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