oasis7 Viewer User Manual

Quick Start

1) Start the live server

env -u RUSTC_WRAPPER cargo run -p oasis7 --bin oasis7_viewer_live -- llm_bootstrap --llm --bind 127.0.0.1:5023 --web-bind 127.0.0.1:5011

Formal gameplay requires a reachable LLM provider. If you switch to --no-llm, the route is observer/debug only.

2) Start the web viewer

env -u NO_COLOR ./scripts/run-viewer-web.sh --address 127.0.0.1 --port 4173

Open: http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011

The repo now ships only the formal viewer web surface; software_safe remains a compatibility alias and no other Viewer entry is maintained.

Web Loop

Use the repo-owned regressions when possible:

• ./scripts/viewer-primary-web-entry-regression.sh --headed
• ./scripts/viewer-software-safe-step-regression.sh --headed
• ./scripts/viewer-software-safe-chat-regression.sh --headed

For a manual capture pass:

command -v agent-browser >/dev/null || { echo "missing agent-browser" >&2; exit 1; }
mkdir -p output/playwright/viewer
agent-browser close-all || true
agent-browser --headed open "http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011&render_mode=viewer&test_api=1"
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser eval "JSON.stringify(window.__AW_TEST__?.getState?.() ?? null)"
agent-browser console | tee output/playwright/viewer/console.log
agent-browser screenshot output/playwright/viewer/viewer-web.png
agent-browser close

Minimum pass criteria: the page loads, __AW_TEST__ is available, renderMode=viewer (or the compatibility alias software_safe), and screenshot/log artifacts are produced.

Current Scope

• Supports bilingual UI, realtime observation, formal gameplay summary, and minimal prompt/chat controls.
• No more standard Viewer jump.
• No more native 3D capture, theme-pack, texture-inspector, or visual QA tools.

Troubleshooting

• Blank page: verify that run-viewer-web.sh finished building and is serving the target port.
• Connection failure: verify oasis7_viewer_live is running and the ws parameter matches --web-bind.
• No formal gameplay: check the LLM provider setup; explicit --no-llm is observer/debug only.
• agent-browser failure: verify the local CLI and browser dependencies first.