oasis7 Viewer User Manual

Local Real LLM Game Test

./scripts/run-local-letai-game-test.sh --local-world-playtest

Use this preset for local real LetAI provider-backed gameplay. It handles token config, provider bridge, launcher/runtime/viewer/local-standalone-chain startup, and the daily playtest ports 48420/48421/48422; it does not connect to formal/public testnet. The emitted GAME_URL is the manual play and agent-browser evidence entry.

Do not treat bare run-viewer-web.sh as the local real provider-backed gameplay startup path; it belongs to the Viewer/debug loop below.

Lower-Level Viewer Debug 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

This route is Viewer/debug only. If you switch to --no-llm, it remains 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 secondary Viewer jump.
• No more retired visual capture, theme-pack, texture-inspector, or specialized inspection tools.
• The former Standard-3D / egui auto-select flow, right-panel visibility and local cache, selection details, Agent locate action, tiered 2D overview zoom, and copyable-text panel are retired and are not current viewer Web capabilities. The supported boundary remains live observation, current selection, prompt/chat, __AW_TEST__, and the three regression scripts above.

Troubleshooting

• Blank page: for the real local test, first verify that run-local-letai-game-test.sh emitted a GAME_URL; for Viewer/debug, 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.