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_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
- If repository does not exist locally, run:
git clone https://github.com/dinghuanghao/openword.git
- 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.
GEMINI_API_KEY load order is: shell environment variable -> repo .env -> key modal/Settings.PORT is optional (default 30000); ensure browser opens http://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, 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.
- 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.
- BFF/
Connect API Bridge should 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_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.
- 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.
- After each turn update, either continue autonomously or pause at key nodes for user input.
- 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.
- 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:.
- 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 and GET /health status; only then ask user to enable Connect API Bridge in Settings for troubleshooting.- Bridge occupied: another tab owns the bridge; disconnect that tab first.
- 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.
- 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.
1---2name: openword-navigator3description: 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.4---56# OpenWord Player78Read `references/session-runbook.md` before running a session.9Treat repository `README.md` as the source of truth for install/startup/API details, and re-check it when commands fail or look outdated.1011## Session Workflow12131. Ask the user which mode to run before gameplay starts.142. Prepare runtime (download/install/start, browser, key setup).153. Branch to human-guided mode or AI REST mode.164. 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).1718Use this exact mode-selection question:1920`主人你想自己玩，还是我来玩？`2122If the user does not choose, default to human-guided mode.2324## Runtime Preparation25261. If repository does not exist locally, run:27`git clone https://github.com/dinghuanghao/openword.git`282. Install and start:29`npm install`30`npm run dev`31Then 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.323. `GEMINI_API_KEY` load order is: shell environment variable -> repo `.env` -> key modal/Settings.334. `PORT` is optional (default `30000`); ensure browser opens `http://127.0.0.1:<PORT>`.345. Confirm the game can reach interactive state before sending turns.3536## Human-Guided Mode37381. Confirm user can input actions in the browser.392. Help user craft opening world prompt and style.403. For each turn, provide a short recap and 3 action options with different risk/reward.414. Let the user pick or rewrite the action.425. Remind controls only when relevant:43`机器人按钮` toggles built-in Auto Player, `Esc` exits auto mode/panels, Settings has `Connect API Bridge`.4445## AI REST Mode4647Creative directive: in AI REST mode, be bold and imaginative; try seemingly impossible actions when they can produce a truly unique story.48491. 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.502. BFF/`Connect API Bridge` should be connected by default; do not ask the user to click it unless troubleshooting a bridge failure.513. Check server health (`GET /health`).524. Start or resume game via REST (`create_game` or `load_game`).53 - If the player provides a reference image, always include it in `create_game.image_path`.54 - If the player does not provide a reference image, do not send `image_path`.55 - When `image_path` is used, prefer an absolute path.565. Loop:57call `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.586. After each turn update, either continue autonomously or pause at key nodes for user input.597. Prefer visual style `3D Pixel Art` (voxel) or `Claymation` (clay); avoid frequent style switching in one session.6061Use `scripts/openword_rest.sh` first (curl-only). 62If shell behavior is inconsistent across platforms, use `scripts/openword_rest.py` with the same commands/arguments.63If `PORT` is not `30000`, set:64`OPENWORD_BASE_URL="http://127.0.0.1:<PORT>"`.6566## REST API Schema6768| Method | Path | Body | Success fields | Tips |69| --- | --- | --- | --- | --- |70| `GET` | `/health` | none | `status`, `bridge_online` | Ensure `bridge_online=true` before `create_game`, `load_game`, or `do_action`. |71| `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). |72| `GET` | `/api/show_history_games` | none | `status`, `games` | Use after restart to find the most coherent checkpoint before loading. |73| `POST` | `/api/load_game` | `{ "game_id": string }` | `status` | Always confirm selected `game_id` with the user before continuing. |74| `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. |75| `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. |7677## Interaction Contract7879Never run long silent streaks. Keep the user in the loop even when AI plays.80811. 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:`.822. At meaningful branch points, ask user preference before committing.833. Surface scene image paths and display scene images when possible.844. Highlight interesting moments:85scene changes, risky decisions, major rewards, unexpected twists.8687## Failure Handling88891. `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.902. Bridge occupied: another tab owns the bridge; disconnect that tab first.913. 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.924. 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.
dinghuanghao