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
- Ask the user which mode to run before gameplay starts.
- Prepare runtime (download/install/start, browser, key setup).
- Branch to human-guided mode or AI REST mode.
- For every turn in both modes (including AI-driven sessions), show
last_scene_image_path + narrative + player_profileas 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
- If repository does not exist locally, run:
git clone https://github.com/dinghuanghao/openword.git - Install and start:
npm installnpm run devThen checkGET /healthfirst: only ifbridge_online=false, open one browser window athttp://127.0.0.1:<PORT>(default30000) and re-check once; if already connected, do not open a new window. GEMINI_API_KEYload order is: shell environment variable -> repo.env-> key modal/Settings.PORTis optional (default30000); ensure browser openshttp://127.0.0.1:<PORT>.- Confirm the game can reach interactive state before sending turns.
Human-Guided Mode
- Confirm user can input actions in the browser.
- Help user craft opening world prompt and style.
- For each turn, provide a short recap and 3 action options with different risk/reward.
- Let the user pick or rewrite the action.
- Remind controls only when relevant:
机器人按钮toggles built-in Auto Player,Escexits auto mode/panels, Settings hasConnect 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.
- Ensure one browser tab is online at
http://127.0.0.1:<PORT>(default30000); before opening a new tab/window, checkGET /health: ifbridge_online=true, do not open; ifbridge_online=false, open only one tab/window and re-check once. - BFF/
Connect API Bridgeshould be connected by default; do not ask the user to click it unless troubleshooting a bridge failure. - Check server health (
GET /health). - Start or resume game via REST (
create_gameorload_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.
- Loop: call
get_current_game_state-> choose a high-impact next action -> calldo_action-> immediately show a natural-language update synthesized fromlast_scene_image_path + narrative + player_profileto the user. - After each turn update, either continue autonomously or pause at key nodes for user input.
- Prefer visual style
3D Pixel Art(voxel) orClaymation(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.
- After every turn, show one natural-language update based on
last_scene_image_path + narrative + player_profilebefore the next action; do not print rigid prefixes likelast_scene_image_path:,narrative:,player_profile:. - At meaningful branch points, ask user preference before committing.
- Surface scene image paths and display scene images when possible.
- Highlight interesting moments: scene changes, risky decisions, major rewards, unexpected twists.
Failure Handling
NO_BRIDGE: first verify the game tab is open andGET /healthstatus; only then ask user to enableConnect API Bridgein Settings for troubleshooting.- Bridge occupied: another tab owns the bridge; disconnect that tab first.
- Missing key/model errors: check
GEMINI_API_KEYin shell env first, then repo.env; if still missing, ask user to configure key modal/Settings. - 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.