Vifu core runtime design
Status: Available. This page describes behavior implemented in the open-source Vifu runtime today.
Vifu runs a published game as a durable, headless session. Headless means the runtime does not draw the screen, play audio, or read device input. A web app, native game, or game engine owns that presentation and sends player actions to Vifu.
Runtime boundary
The game client decides how the experience looks and feels. Vifu decides how the published game advances: which path runs, how state changes, when an Agent or tool is called, and when the client must perform a game-specific action.
Running components
- Vifu Server exposes the project API, authorizes project keys, owns sessions, and stores committed results.
- Bevy Game Runtime executes the compiled game graph with
bevy_appandbevy_ecs. It does not include Bevy rendering, windows, assets, or input. - PostgreSQL stores releases, sessions, commands, events, effects, and resumable state.
- Effect worker performs an Agent or tool request after the current state change has been recorded.
- Vifu Agent Gateway connects Vifu Server to configured Agent Providers and keeps provider credentials out of game clients.
How a command runs
For each game command, Vifu Server:
- checks the project key and the expected session revision;
- loads the session's pinned release and latest state;
- lets the Bevy runtime advance the game;
- pauses when the game needs player input, an external effect, a host action, completion, or failure; and
- stores the updated state, events, effects, and command result together.
Agent and tool calls run as effects outside the state transition. When an effect finishes, its stored result resumes the same session. A slow provider therefore does not become hidden work inside the game rules.
Public project APIs
| API | Current purpose |
|---|---|
/{project-slug}/v1/game | Run a published game through sessions, commands, events, and host actions. |
/{project-slug}/v1/chat/completions | Call one exposed Agent through an OpenAI-compatible request. |
/{project-slug}/v1/models | List the Agents available to the OpenAI-compatible API. |
The Game API is the stateful contract for a complete game. The chat API is a smaller integration for direct Agent calls. Both use project keys and resolve providers inside the Vifu deployment.
Current guarantees
- A session remains pinned to the release on which it started.
- PostgreSQL preserves session state across Server restarts.
- Idempotency keys prevent a retried command from advancing a session twice.
- Expected revisions detect two callers trying to advance the same session at the same time.
- Ordered CloudEvents can be replayed after a client reconnects.
- Provider credentials and internal Agent conversations are not included in public game state or runtime release bundles.
Read Authoring and releases for how Canvas, Short Drama, Preview, and publishing produce the release executed here. Read Technical direction for work that is not yet part of this runtime contract.