openword-player

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

运行会话前请先阅读

references/session-runbook.md

。将仓库

README.md

作为安装/启动/API相关细节的权威来源，当命令执行失败或看起来过时时请重新查阅。

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.

游戏开始前询问用户想要运行的模式。
准备运行环境（下载/安装/启动、浏览器、密钥配置）。
分流到人类引导模式或AI REST模式。
游玩过程中保持用户参与，即便是AI驱动的会话也要如此。

请使用以下固定的模式选择问题：

这局你想怎么进行：你自己玩（我引导）还是我用 REST API 代玩？

如果用户未做选择，默认使用人类引导模式。

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.

如果本地不存在该仓库，运行:

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

安装并启动:
```
npm install
```
```
npm run dev
```
随后主动为用户打开
```
http://127.0.0.1:<PORT>
```
（默认端口为
```
30000
```
）。
```
GEMINI_API_KEY
```
的加载优先级为: shell环境变量 > 仓库
```
.env
```
文件 > 密钥弹窗/设置页。
```
PORT
```
为可选配置（默认
```
30000
```
）；确保浏览器打开的地址是
```
http://127.0.0.1:<PORT>
```
。
在发送回合前确认游戏已进入可交互状态。

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

确认用户可以在浏览器中输入操作。
帮助用户构思初始世界提示词和风格。
每个回合提供简短的复盘，以及3个风险/收益各不相同的操作选项。
让用户选择或者重写操作。
仅在相关场景下提醒控制方式:
```
机器人按钮
```
可切换内置自动播放器，
```
Esc
```
键退出自动模式/面板，设置页中有
```
Connect API Bridge
```
选项。

AI REST Mode

AI REST模式

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

确保有一个浏览器标签页已打开
```
http://127.0.0.1:<PORT>
```
（默认
```
30000
```
）并正常运行。
BFF/
```
Connect API Bridge
```
默认会自动连接，除非遇到桥接故障需要排查，否则不要让用户手动点击。
检查服务健康状态（
```
GET /health
```
）。
通过REST启动或恢复游戏（
```
create_game
```
或
```
load_game
```
）。
循环执行: 调用
```
get_current_game_state
```
-> 选择下一步操作 -> 调用
```
do_action
```
。
使用
```
last_scene_image_path
```
向用户分享场景视觉内容。
REST
```
create_game
```
推荐使用的风格关键词:
```
Claymation
```
（粘土动画）和
```
3D Pixel Art
```
（3D像素艺术）。

请优先使用

scripts/openword_rest.sh

（仅需curl，无需Python）。如果

PORT

不是

，请设置:

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`

请求方法	路径	请求体	成功响应字段
`GET`	`/health`	无	`status` , `bridge_online`
`POST`	`/api/create_game`	`{ "description": string, "style": string }`	`status` , `game_id`
`GET`	`/api/show_history_games`	无	`status` , `games`
`POST`	`/api/load_game`	`{ "game_id": string }`	`status`
`GET`	`/api/get_current_game_state`	无	`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.

不要长时间静默运行。即便是AI自主游玩时也要让用户及时了解进度。

至少每1-2个回合分享一次进度更新。
遇到有意义的分支节点时，先询问用户偏好再执行操作。
提供场景图片路径，尽可能展示场景图片。
高亮有趣的节点: 场景切换、风险决策、重大奖励、意外转折。

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.

```
NO_BRIDGE
```
: 首先验证游戏标签页是否已打开，以及
```
GET /health
```
的状态；确认后再让用户在设置中开启
```
Connect API Bridge
```
进行排查。
桥接被占用: 另一个标签页占用了桥接；先断开那个标签页的连接。
密钥/模型缺失错误: 首先检查shell环境变量中的
```
GEMINI_API_KEY
```
，再检查仓库
```
.env
```
文件；如果仍然缺失，让用户在密钥弹窗/设置页中配置。
请求缓慢/超时: 增加超时时间，避免并发请求。