openword-navigator

name	openword-navigator
description	Operate OpenWord end-to-end for live adventure sessions. Use when needs to download/install/start OpenWord, guide a human player in the browser, or play autonomously through REST API (create/load game, do_action loop, state/image retrieval), including configuring GEMINI_API_KEY and sharing interesting scenes and choices during play.

OpenWord Player

Read references/session-runbook.md before running a session. Treat repository README.md as the source of truth for install/startup/API details, and re-check it when commands fail or look outdated.

Session Workflow

1. Ask the user which mode to run before gameplay starts.
2. Prepare runtime (download/install/start, browser, key setup).
3. Branch to human-guided mode or AI REST mode.
4. For every turn in both modes (including AI-driven sessions), show last_scene_image_path + narrative + player_profile as a natural user-facing update (avoid raw field-label dump).

Use this exact mode-selection question:

主人你想自己玩，还是我来玩？

If the user does not choose, default to human-guided mode.

Runtime Preparation

1. If repository does not exist locally, run: git clone https://github.com/dinghuanghao/openword.git
2. Install and start: npm install npm run dev Then check GET /health first: only if bridge_online=false, open one browser window at http://127.0.0.1:<PORT> (default 30000) and re-check once; if already connected, do not open a new window.
3. GEMINI_API_KEY load order is: shell environment variable -> repo .env -> key modal/Settings.
4. PORT is optional (default 30000); ensure browser opens http://127.0.0.1:<PORT>.
5. Confirm the game can reach interactive state before sending turns.

Human-Guided Mode

1. Confirm user can input actions in the browser.
2. Help user craft opening world prompt and style.
3. For each turn, provide a short recap and 3 action options with different risk/reward.
4. Let the user pick or rewrite the action.
5. Remind controls only when relevant: 机器人按钮 toggles built-in Auto Player, Esc exits auto mode/panels, Settings has Connect API Bridge.

AI REST Mode

Creative directive: in AI REST mode, be bold and imaginative; try seemingly impossible actions when they can produce a truly unique story.

1. Ensure one browser tab is online at http://127.0.0.1:<PORT> (default 30000); before opening a new tab/window, check GET /health: if bridge_online=true, do not open; if bridge_online=false, open only one tab/window and re-check once.
2. BFF/Connect API Bridge should be connected by default; do not ask the user to click it unless troubleshooting a bridge failure.
3. Check server health (GET /health).
4. Start or resume game via REST (create_game or load_game).
   • If the player provides a reference image, always include it in create_game.image_path.
   • If the player does not provide a reference image, do not send image_path.
   • When image_path is used, prefer an absolute path.
5. Loop: call get_current_game_state -> choose a high-impact next action -> call do_action -> immediately show a natural-language update synthesized from last_scene_image_path + narrative + player_profile to the user.
6. After each turn update, either continue autonomously or pause at key nodes for user input.
7. Prefer visual style 3D Pixel Art (voxel) or Claymation (clay); avoid frequent style switching in one session.

Use scripts/openword_rest.sh first (curl-only).
If shell behavior is inconsistent across platforms, use scripts/openword_rest.py with the same commands/arguments. If PORT is not 30000, set: OPENWORD_BASE_URL="http://127.0.0.1:<PORT>".

REST API Schema

Method	Path	Body	Success fields	Tips
GET	/health	none	status, bridge_online	Ensure bridge_online=true before create_game, load_game, or do_action.
POST	/api/create_game	{ "description": string, "style": string, "image_path"?: string }	status, game_id	In description, cite the single closest reference game (tone + mechanics) for stable art direction and stronger worldbuilding; set style to voxel/clay first. If player provides a reference image, include image_path (absolute path preferred).
GET	/api/show_history_games	none	status, games	Use after restart to find the most coherent checkpoint before loading.
POST	/api/load_game	{ "game_id": string }	status	Always confirm selected game_id with the user before continuing.
GET	/api/get_current_game_state	none	status, game_id, world_view, narrative, player_profile, last_scene_image_path	Compare with previous state and extract one clear objective for the next turn.
POST	/api/do_action	{ "description": string }	status, game_id, world_view, narrative, player_profile, last_scene_image_path	Prefer interesting actions that directly advance the story; avoid low-impact micro actions that waste tokens.

Interaction Contract

Never run long silent streaks. Keep the user in the loop even when AI plays.

1. After every turn, show one natural-language update based on last_scene_image_path + narrative + player_profile before the next action; do not print rigid prefixes like last_scene_image_path:, narrative:, player_profile:.
2. At meaningful branch points, ask user preference before committing.
3. Surface scene image paths and display scene images when possible.
4. Highlight interesting moments: scene changes, risky decisions, major rewards, unexpected twists.

Failure Handling

1. NO_BRIDGE: first verify the game tab is open and GET /health status; only then ask user to enable Connect API Bridge in Settings for troubleshooting.
2. Bridge occupied: another tab owns the bridge; disconnect that tab first.
3. Missing key/model errors: check GEMINI_API_KEY in shell env first, then repo .env; if still missing, ask user to configure key modal/Settings.
4. Slow/timeout calls: increase timeout, avoid overlapping requests. Some APIs may return BUSY; wait patiently and retry only after the current call settles, which can occasionally take several minutes when the service is blocked.