SDK API Reference

Tool@vifu/[email protected]

Protocolcompanion.plugin.v1

RuntimeBrowser

StatusPublic alpha

createVifuSDK

const Vifu = createVifuSDK({ transport: "auto" });
const companion = Vifu.companion;

Option	Type	Description
transport	"auto" | "iframe" | "wkwebview" | CompanionTransport	Host transport. Use auto for games.
documentTitle	string	Runtime name reported during initialization.
postMessage	(message) => void	Compatibility shortcut for custom hosts.

context

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

Contexts must return compact JSON-compatible state. Treat the returned object as prompt-visible.

action

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

Actions are app-owned commands. Validate inputs and keep effects visible to the player.

observe

companion.observe("answer.wrong", { questionId: "q-1" }, {
  context: "scene.current",
  priority: "low"
});

Use observations for normal game facts. They do not require the game to interrupt the player.

signal

const repeatedWrong = companion.signal("learning.repeated_wrong", {
  context: "scene.current",
  commands: ["dialogue.repeat"],
  priority: "high",
  cooldownKey: "q-1-wrong"
});

repeatedWrong.emit({ attempts: 3 });

Signals are for rare moments where the game explicitly asks the companion to pay attention.

resource

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

resource is the public facade for host-managed runtime data and media. The SDK keeps runtime base URLs, preview routes, and tokens inside the host adapter. Game code should not construct /v1/assets/runtime-* or /preview-* URLs directly.

Method	Description
Vifu.resources.readJson(id)	Read a JSON runtime resource by id.
Vifu.resources.readText(id)	Read a text runtime resource by id.
Vifu.resources.dataUrl(id, query?)	Resolve a URL for runtime data.
Vifu.resources.mediaUrl(id, query?)	Resolve a URL for runtime media.
Vifu.resources.fileUrl(path)	Resolve a bundled runtime file path.

invoke

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

await Vifu.services.gameState.save("autosave", { cardId: "card-1" });

Vifu.services.* methods request host-owned or backend-owned capabilities. Vifu.services.invoke(capabilityId, args) remains available for advanced capabilities that do not yet have a facade.

Capability ids are stable product contracts. Provider wiring, auth, backend routes, and local preview behavior are host implementation details. The host rejects undeclared calls according to the manifest policy. Declared calls are then resolved through active first-party plugins loaded by the host; plugin dependencies, auth, device permission, and provider state can still block an invoke before any backend route is called.

Facade	Capability id
Vifu.services.gameState.save(slot, state)	vifu.gameState.save
Vifu.services.gameState.load(slot)	vifu.gameState.load
Vifu.services.dictionary.lookup(input)	vifu.dictionary.lookup
Vifu.services.speech.microphone.request(options)	vifu.speech.microphone.request
Vifu.services.speech.transcribe(input)	vifu.speech.transcribe
Vifu.services.speech.tts.speak(input)	vifu.speech.tts.speak
Vifu.services.ai.companion.turn(input)	vifu.ai.companion.turn
Vifu.services.review.preview(input)	vifu.review.preview
Vifu.services.review.grade(input)	vifu.review.grade
Vifu.services.camera.snapshot(input)	vifu.camera.snapshot

status

Vifu.status();

Field	Description
sdkVersion	SDK package version.
protocolVersion	Companion protocol capability.
capability	Manifest capability required by the host.
transport	Active transport kind.
hostConnected	true after host initialization.