Host Bridge Protocol
Most games should not use the host bridge directly. Use @vifu/sdk.
This page exists for advanced debugging and host implementers.
Sources
| Source | Direction | Purpose |
|---|---|---|
vifu-game-runtime | game to host | Runtime notifications and responses. |
vifu-web-host | host to game | Vifu Web runtime requests. |
vifu-ios-host | host to game | iOS WKWebView runtime requests. |
Lifecycle
- The game bundle loads.
- The SDK installs its message listener.
- The SDK announces runtime readiness.
- The host sends initialization.
vifu.ready()resolves andvifu.status().hostConnectedbecomes true.
Public SDK Mapping
| SDK API | Bridge purpose |
|---|---|
vifu.ready() | Wait for host initialization. |
vifu.tool(...) | Declare a callable tool definition. |
vifu.agent(...) | Create an isolated runtime agent for an NPC, tutor, companion, or other entity. |
vifu.run(...) | Run one model/tool loop for a target agent. |
vifu.resources.* | Resolve or read declared runtime resources. |
vifu.gameState.* | Save and restore game-owned state. |
vifu.ai.* | Call Vifu AI through provider routing and quota. |
vifu.dictionary.*, vifu.voice.*, vifu.review.*, vifu.camera.*, vifu.invoke(...) | Call declared platform capabilities. |
Runtime Agent Tool Registries
Vifu keeps tools isolated per agent and per run. A tool exposed for one agent is not available to another agent unless the game explicitly registers it there.
Tools passed directly to vifu.run(agent, input, { tools }) are scoped to that run and cleaned up after the request. Persistent tools registered on the agent stay available until the agent is disposed.
The companion session socket remains a low-frequency play-session event channel. Runtime tool calls use the dedicated runtime-skill Durable Object/WebSocket path.
Policy
The host rejects undeclared calls. Declare the feature with public manifest nouns such as ai, data, media, bundle, links, save, dictionary, voice, camera, or review.
Do not use raw window.parent.postMessage(...) for game/backend logic. Raw bridge messages are a host implementation detail and may change within the compatibility line.