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.

2installs

Sourcedinghuanghao/openword

Added on2026-03-06

NPX Install

npx skill4agent add dinghuanghao/openword openword-player

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

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

If repository does not exist locally, run:

git clone https://github.com/dinghuanghao/openword.git

Install and start:
```
npm install
```
```
npm run dev
```
Then proactively open
```
http://127.0.0.1:<PORT>
```
for the user (default
```
30000
```
).
```
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

Ensure one browser tab is online at
```
http://127.0.0.1:<PORT>
```
(default
```
30000
```
).
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
```
).
Loop: call
```
get_current_game_state
```
-> choose next action -> call
```
do_action
```
.
Use
```
last_scene_image_path
```
to share scene visuals with the user.
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

, set:

OPENWORD_BASE_URL="http://127.0.0.1:<PORT>"

.

REST API Schema

Method	Path	Body	Success 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.

Share updates at least every 1-2 turns.
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.