openword-player

Original：🇺🇸 English
Translated
1 scripts

Operate OpenWord end-to-end for live adventure sessions. Use when Codex 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.

5installs
Sourcedinghuanghao/openword
Added on

NPX Install

npx skill4agent add dinghuanghao/openword openword-player

Tags

Translated version includes tags in frontmatter
openwordai-adventure-gamerest-apigemini-apiautomated-gameplay

SKILL.md Content

View Translation Comparison →

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. Keep the user involved during play, including AI-driven sessions.
Use this exact mode-selection question:
这局你想怎么进行：你自己玩（我引导）还是我用 REST API 代玩？
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 proactively open 
    http://127.0.0.1:<PORT>
    for the user (default 
    30000
    ).
  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

  1. Ensure one browser tab is online at 
    http://127.0.0.1:<PORT>
    (default 
    30000
    ).
  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
    ).
  5. Loop: call 
    get_current_game_state
    -> choose next action -> call 
    do_action
    .
  6. Use 
    last_scene_image_path
    to share scene visuals with the user.
  7. Recommended style keywords for REST 
    create_game
    : 
    Claymation
    (clay) and 
    3D Pixel Art
    (voxel).
Use 
scripts/openword_rest.sh
first (curl-only, Python-free). If 
PORT
is not 
30000
, set: 
OPENWORD_BASE_URL="http://127.0.0.1:<PORT>"
.

REST API Schema

MethodPathBodySuccess fields
GET
/health
none
status
, 
bridge_online
POST
/api/create_game
{ "description": string, "style": string }
status
, 
game_id
GET
/api/show_history_games
none
status
, 
games
POST
/api/load_game
{ "game_id": string }
status
GET
/api/get_current_game_state
none
status
, 
game_id
, 
world_view
, 
narrative
, 
player_profile
, 
last_scene_image_path
POST
/api/do_action
{ "description": string }
status
, 
game_id
, 
world_view
, 
narrative
, 
player_profile
, 
last_scene_image_path

Interaction Contract

Never run long silent streaks. Keep the user in the loop even when AI plays.
  1. Share updates at least every 1-2 turns.
  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.