oasis7 docs

Viewer Manual

oasis7 Viewer User Manual

Covers startup modes, controls, auto-focus, automation steps, web closure debugging, and common issue diagnosis for `oasis7_viewer` workflows.

Start Running Go to Web Loop Back to Catalog

Quick Start

1) Start live server (recommended)

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

`oasis7_viewer_live` now defaults to LLM mode; formal gameplay requires a configured, reachable LLM provider.

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

`--no-llm` is observer/debug only; `gameplay_action/prompt/chat` returns `llm_mode_required` or `llm_init_failed`, while `step/play` returns `ControlCompletionAck` with `Blocked + error_code/error_message`.

2) Start viewer

env -u RUSTC_WRAPPER cargo run -p oasis7_viewer -- 127.0.0.1:5023

3) Offline mode (no server connection)

OASIS7_VIEWER_OFFLINE=1 env -u RUSTC_WRAPPER cargo run -p oasis7_viewer

4) Browser mode (Bevy + wasm)

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`.

5) Release mode (P2P recommended)

`oasis7_viewer_live` is now a pure viewer live service and no longer accepts `--release-config`, `--runtime-world`, or `--node-*` control-plane flags.

For P2P release flows, lock chain parameters through `oasis7_chain_runtime` (typically managed by `oasis7_game_launcher` / `oasis7_web_launcher` / `oasis7_client_launcher`). Viewer keeps only `--bind`, `--web-bind`, and `--llm/--no-llm`; `--no-llm` remains observer/debug only.

Common Interaction

Auto Focus

Use environment variables to focus a target at startup:

Supported syntax: `first_fragment`, `first_location`, `first_agent`, `location:<id>`, and `agent:<id>` (with shorthand aliases `fragment/location/agent`).

Auto focus targets are limited to Agent / Location / Fragment.

Auto Select / Automation Steps

./scripts/capture-viewer-frame.sh \
  --scenario llm_bootstrap \
  --addr 127.0.0.1:5131 \
  --auto-select-target first_agent \
  --automation-steps "mode=3d;focus=first_agent;zoom=0.8;select=fragment:frag-0"

Web Closure Loop (default recommendation)

Prerequisites

Standard Flow

Terminal A: start live server.

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

The default path assumes active LLM access; if you explicitly switch to `--no-llm`, this Web route is observer/debug only and does not count as formal gameplay evidence.

Terminal B: start web viewer.

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

Terminal C: run the agent-browser capture loop.

command -v agent-browser >/dev/null || { echo "missing agent-browser" >&2; exit 1; }
mkdir -p output/playwright/viewer
agent-browser --headed open "http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011&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

Note: the artifact directory currently keeps the legacy path output/playwright/viewer/ for compatibility. `render_mode` defaults to auto: use the standard Viewer when hardware WebGL is available, and automatically switch to software_safe when SwiftShader / software renderer / no WebGL is detected. Append &render_mode=software_safe to force the safe mode explicitly.

`sendControl(\"step\")` semantic check

Run the following in browser console or agent-browser evaluate to verify step-by-step control:

window.__AW_TEST__.sendControl("step");
window.__AW_TEST__.sendControl("step", { count: 3 });
window.__AW_TEST__.sendPromptControl("preview", { agentId: "agent-0", shortTermGoal: "software-safe preview" });
window.__AW_TEST__.sendPromptControl("apply", { agentId: "agent-0", shortTermGoal: "software-safe apply" });
window.__AW_TEST__.sendAgentChat("agent-0", "hello from software_safe");
window.__AW_TEST__.getState();

When the page is served by oasis7_game_launcher with viewer auth bootstrap injected, software_safe also exposes a minimal selected-agent prompt/chat surface. The matching automation methods are sendPromptControl(mode, payload) and sendAgentChat(agentId, message).

Prompt Overrides now lives behind the default-collapsed “Advanced Prompt Settings” item. The preview/apply/rollback form appears only after you select an agent and expand that setting. The toggle remembers its last browser-local state and does not affect __AW_TEST__.sendPromptControl(...).

Outputs and Minimum Acceptance

Native fallback (only when web path cannot reproduce)

./scripts/capture-viewer-frame.sh --scenario asteroid_fragment_detail_bootstrap --addr 127.0.0.1:5131 --viewer-wait 12 --auto-focus-target first_fragment --auto-focus-radius 18

Common advanced flags: `--capture-max-wait`, `--no-prewarm`, `--keep-tmp`, `--auto-focus-keep-2d`.

Main Right Panel and Chat Panel

Module visibility and local persistence

Selection details panel

Quick locate agent

Overview Zoom Mode Switch (2D)

Copyable Text Panel

UI Language Switch

Recommended Debug Scenarios

Fragment Depletion Visualization

Troubleshooting

References

Fragment Element Chunk Rendering (default enabled)