VuuAction User Guide

1. Getting started

VuuAction is a host application. It stores the game project and local context, renders a Three.js preview, and exposes declared game-development capabilities to the shared VuuMake Agent control plane.

Recommended first run: create or open a project, configure the project identity, add at least one scene and level, define an input binding, then use Playtest before building the web game.

Launch VuuAction on Windows with Microsoft Edge WebView2 Runtime installed.
Select New project and choose a workspace folder, or select Open project for an existing project.vua.
Use the workflow cards to add scenes, entities, logic rules, levels, and controls.
Select Save project after structural changes.

2. Workspace layout

Area	Purpose
Workflow rail	Switch between Project, Assets, Scenes, Entities, Logic, Levels, Controls, Playtest, and Build.
Game Preview	Run, pause, reload, maximize, or open DevTools for the local Three.js preview.
Right rail	Open VuMos Agent or Game Script. It can be hidden to give the preview more room.
Host Settings	Configure VuuAction host behavior and host-owned UI preferences. Shared Agent settings remain shared with VuuMake.

The interface is localized, but this guide is intentionally English-first. The visible English labels above match the current desktop UI.

3. Projects and assets

3.1 Project file

A project workspace contains project.vua, a structured JSON project snapshot. It records the project identity, imported assets, scenes, entities, logic rules, levels, and input bindings.

3.2 Assets

Use Assets → Import to copy source files into the project workspace. The project contract supports images, GLTF/GLB models, audio, animation, scripts, and fonts. Rename, copy, remove, copy the path, or open an asset in File Explorer from the asset actions.

Keep source files available: imported files are project copies. If an external source is changed later, import it again or replace the project copy deliberately.

4. Game workflow

Stage	Typical operation
Project	Set the game name, genre, target platform, and startup scene.
Scenes	Add scenes and plan cameras, lights, environment, and spawn points.
Entities	Create players, NPCs, props, triggers, and reusable components; link imported assets where appropriate.
Logic	Add event-to-action rules, state changes, collisions, quests, and win/loss conditions.
Levels	Order levels and define checkpoints, difficulty, and scene transitions.
Controls	Map keyboard, mouse, gamepad, or touch input to game actions such as Jump or Move.
Playtest	Run acceptance checks for workspace, scene, level, and control setup; inspect runtime errors and FPS.

Use the action on each stage, such as Add scene, Add entity, Add rule, Add level, or Add input binding. Save the project after changes.

5. Three.js game preview

The preview is served from a loopback-only local runtime and rendered in WebView2 using the bundled Three.js module. The status line reports WebView2, Three.js, FPS, and the active scene.

Run game preview: start the current preview.
Pause game preview: pause the running preview.
Reload preview: request a fresh runtime load.
Open preview DevTools: inspect browser console and network details when debugging.
Fullscreen / Maximize: enlarge the preview without changing project data.

GPU note: if the runtime reports an empty error or the preview is unavailable, WebGL/GPU acceleration may be unavailable in the WebView2 session, especially over Remote Desktop. Install or repair WebView2 and test with GPU passthrough before changing project data.

6. Game Script

The Game Script rail is a script-driven workflow for capturing the game concept, core loop, world direction, characters, scenes, assets, logic, levels, controls, playtest criteria, build, publishing, and promotion notes.

Select Create to create the starter game-script.html draft.
Use Modify to edit the HTML script when the editor is available.
Use Sync preview to apply the script to the starter preview, then Validate the current workflow.
Save the script beside project.vua.

The script is a planning and content artifact. It does not replace the structured project state or the Playtest checks.

7. Shared Agent and host integration

VuuAction is a product host, not a second Agent runtime. The shared VuuMake control plane owns Agent sessions, model routing, Quantum execution, permissions, memory, and shared runtime resources. VuuAction owns the project context and declared game capabilities.

7.1 Using the embedded Agent

Open VuMos Agent in the right rail and describe the game goal, current project state, desired edits, or validation question. Ask for a plan first when a change affects several stages.

“Create a third-person arena project with a player, two NPCs, one level, and keyboard movement.”
“Read the current project and tell me which Playtest checks are missing.”
“Add a rule for starting the encounter when the player enters the trigger.”
“Sync the current project to the Three.js preview and report any validation failures.”

7.2 Declared capabilities

The host boundary is controlled by VuuActionProjectController. Agent operations should use the declared project capabilities for reading the snapshot, creating or updating project entities, syncing the preview, and running acceptance checks. The Agent must not edit Flutter widgets, WebView DOM, arbitrary screen coordinates, or unrelated files directly.

When VuuMake is running, VuuAction registers with the shared control plane. The resulting authenticated MCP endpoint can be used by a permitted external MCP client such as Claude Code, Claude Desktop, or Codex. If VuuMake is unavailable, VuuAction remains usable locally; external shared-Agent control is simply unavailable until registration succeeds.

7.3 Host Agent system prompt

You are the VuuAction host Agent.

Your job is to help users plan, inspect, edit, validate, preview, and build Three.js game projects through VuuAction's declared host capabilities.

Rules:
1. Treat VuuAction as a product host. Use VuuMake's shared Agent control plane, shared model routing, Quantum, memory, sessions, and permissions. Never create or assume a second local Agent runtime.
2. Before answering a question about how to use the host software, read and rely on the User_Guide.html in the VuuAction host root. If it is unavailable, say so and answer only from verified current host capabilities.
3. Keep host settings separate from shared Agent settings. Do not claim that a host-only preference changes the shared Agent.
4. Use only declared VuuAction capabilities and the VuuActionProjectController mutation boundary. Do not edit Flutter widgets, WebView DOM, arbitrary screen coordinates, unrelated files, or hidden state directly.
5. Prefer inspect/read and plan before mutation. State the intended project change, affected objects, and validation evidence.
6. Preserve project.vua as the structured source of truth. Keep game-script.html as a companion planning/script artifact; do not silently replace structured project state with prose.
7. For preview work, use the Three.js preview bridge and report WebView2, WebGL/GPU, scene, FPS, and runtime errors accurately. Do not claim that a build or static check proves a successful interactive playtest.
8. For build requests, run the available Playtest and Build checks, report copied assets and output paths, and distinguish draft publication metadata from an uploaded or published game.
9. Ask for confirmation before destructive operations such as removing assets, deleting project objects, or overwriting a workspace file.
10. If a capability, shared control-plane connection, model, or runtime is unavailable, report the exact limitation and do not simulate success.

8. Build and publication preparation

Select Build to validate assets and create a self-contained Three.js web build with the project manifest, copied assets, and draft publication metadata.

Run Playtest checks and resolve missing workspace, scene, level, or control setup.
Confirm the preview behaves as intended and inspect errors in DevTools when needed.
Select Build web game.
Review the output folder and the publication draft. Uploading and promotion are separate actions.

9. Troubleshooting

The preview is blank or unavailable

Confirm Microsoft Edge WebView2 Runtime is installed, restart VuuAction, and check whether WebGL/GPU acceleration is available. Remote Desktop sessions may disable GPU passthrough.

The project cannot be opened

Choose the workspace's project.vua, verify that it is valid JSON, and keep a backup before manual repair. A project created by a newer schema may not be readable by an older build.

The Agent cannot control the project

Start VuuMake, reopen VuuAction, and verify that shared-Agent registration succeeds. The app can still work locally when the control plane is offline.

Build succeeds but the game is not published

Build creates local web output and draft metadata. Hosting, upload, promotion, and distribution remain separate release steps.