游戏 API 接口
引擎文档原文游戏 API 接口
默认地址:http://127.0.0.1:3000。请求和响应均为 JSON。
1. 身份与 token
创建对局时返回:
- 每个国家一个 nation token,只能读取和操作对应国家。
- 一个 admin token,可推进时间、开始战斗和读取管理员事件。
token 只在创建响应中明文返回一次,服务端只保存 SHA-256 哈希。调用私有接口时使用:
Authorization: Bearer <token>
无 token 返回 401;token 与路径国家不匹配返回 403。不要把 admin token 发给参与者或前端。
2. 创建对局
POST /api/games
Content-Type: application/json
请求:
{
"seed": "optional-replay-seed",
"nationCount": 10,
"battleChoiceTimeoutMs": 10000
}
seed可选,1..256 字符;不传时服务器生成随机种子。nationCount可选,2..20;API 默认 20,AI runner 会明确传 10。battleChoiceTimeoutMs可选,0..60000。strategies只供内置固定策略模拟使用,LLM 接入通常不传。
响应 201:
{
"gameId": "uuid",
"commitment": "sha256",
"tick": 0,
"config": {"nationCount":10,"windowTicks":30,"maxGameTicks":2400},
"nations": [{"id":"n00","strategy":"mixed"}],
"tokens": {
"nations": {"n00":"...","n01":"..."},
"admin": "..."
}
}
注意:当前这个端点没有平台级认证,必须由内网、VPN 或上层网关保护。
3. 公开状态
GET /api/games/:gameId
无需认证。返回当前 tick、窗口、阶段、存活数、公开国家信息和待处理战斗。阶段为:
runningawaiting_battle_choicesended
前端或外部 AI 可轮询此端点判断何时需要操作,但不要高频到每毫秒;1 秒一次已经足够。
4. 读取某国决策快照
GET /api/games/:gameId/snapshots/:nationId
Authorization: Bearer <该国 token>
返回完整 DecisionSnapshot:
{
"tick": 720,
"windowIndex": 24,
"maxGameTicks": 2400,
"self": {
"id": "n03",
"minerals": 180,
"reserve": 1400,
"farmers": 36,
"army": {"shield":10,"archer":8,"assassin":6},
"soldiersTotal": 24,
"pop": 60,
"popCap": 200,
"territories": 1,
"farmerTarget": 40,
"productionPolicy": {"shield":40,"archer":40,"assassin":20},
"treasuryReserve": 100,
"inCombat": false,
"isProtected": false,
"protectionKind": null,
"farmerLine": null,
"soldierLine": null,
"battlesWon": 0,
"battlesLost": 0,
"nextDecisionWindow": 24
},
"nations": [],
"neighbors": [],
"intel": [],
"recentPublicEvents": []
}
实际响应中的 nations 和 neighbors 是公开粗粒度信息,intel 只含已购买且仍有效的情报。
5. 提交普通决策
POST /api/games/:gameId/decisions/:nationId
Authorization: Bearer <该国 token>
Content-Type: application/json
请求必须是完整格式:
{
"holdWindows": 1,
"internal": {
"farmerTarget": 40,
"productionPolicy": {
"shield": 40,
"archer": 40,
"assassin": 20
},
"treasuryReserve": 100
},
"external": {
"type": "declare_war",
"targetNationId": "n04"
}
}
约束:
holdWindows可选,整数 0..5。farmerTarget为非负整数且不能高于当前人口上限。- 三兵种比例是非负整数且严格合计 100。
treasuryReserve可选,必须是 0..300 的整数;省略时保持原值。新生产不得使矿库存低于它。external.type为none、buy_intel或declare_war。- 后两者必须提供
targetNationId。
响应:
{"queued":true,"appliedAtNextWindow":true,"holdWindows":1}
提交只是排队,实际在下一决策窗口应用。同一国家重复提交会由后一次覆盖尚未消费的前一次。
模型短格式 {"f":40,"p":[40,40,20],"r":100,"a":"N"} 不能直接发到此接口;必须先转换。
6. 读取开战快照
GET /api/games/:gameId/battles/:battleId/snapshot/:nationId
Authorization: Bearer <参战国 token>
仅进攻方和防守方可读。响应:
{
"battleId": 12,
"tick": 930,
"role": "attacker",
"you": {
"id": "n03",
"farmers": 38,
"army": {"shield":14,"archer":10,"assassin":8},
"soldiersTotal": 32
},
"opponent": {
"id": "n04",
"popTierFloor": 60,
"territories": 1,
"inCombat": false,
"isProtected": false,
"protectionKind": null
},
"opponentIntel": {
"id": "n04",
"minerals": 120,
"reserve": 800,
"farmers": 42,
"army": {"shield":8,"archer":6,"assassin":4},
"farmerTarget": 45,
"productionPolicy": {"shield":35,"archer":40,"assassin":25}
},
"frontWidth": 30,
"maxRounds": 60
}
opponentIntel 只有在该参与国对当前对手的已购情报仍处于有效窗口时存在,否则为 null。双方分别判断,绝不自动共享情报。
7. 提交农民参战抉择
POST /api/games/:gameId/battles/:battleId/choices/:nationId
Authorization: Bearer <参战国 token>
Content-Type: application/json
{"farmersJoin":false}
每国每场只能成功提交一次。重复提交返回 409 already_submitted。截止前未提交时默认 false。
8. 管理员统一开始战斗
POST /api/games/:gameId/finalize-battle-choices
Authorization: Bearer <admin token>
所有参战者已提交时可提前开始。未集齐且未到截止时间时返回 409:
{
"error": "deadline_not_reached",
"deadline": 1234567890,
"state": {}
}
截止后服务端定时器或下一次管理员 /step 会自动开始,未提交方按农民不参战处理。
9. 推进时间
POST /api/games/:gameId/step
Authorization: Bearer <admin token>
Content-Type: application/json
{"ticks":30}
ticks 可选,范围 1..2400,默认推进一个 30 tick 窗口。服务端内部逐 tick 处理,因此批量 30 tick 与逐次 1 tick 的核心结果一致。
若正在等待开战抉择且未到截止时间,返回 409 awaiting_battle_choices,逻辑 tick 不推进。对局已结束时返回 409 game_ended。
只有主办方编排器应调用 /step。参与者不能持有 admin token。
10. 事件日志
管理员完整事件:
GET /api/games/:gameId/events?sinceSeq=0&limit=500
Authorization: Bearer <admin token>
公开事件:
GET /api/games/:gameId/events/public?sinceSeq=0&limit=500
响应:
{
"events": [],
"oldestAvailableSeq": 1,
"latestAvailableSeq": 120,
"nextSinceSeq": 121,
"truncated": false,
"hasMore": false
}
客户端下一次把 nextSinceSeq 作为 sinceSeq。若 truncated=true,说明游标之前的事件已被有界内存缓冲淘汰,应重新同步当前公开状态。
公开事件不包含战时采矿数量、精确保护结束 tick、私有决策或 token。
11. 终局结果
GET /api/games/:gameId/result
无需认证,但仅在终局后可用。未结束返回 409 game_not_ended。响应包含:
rawSeed和开局commitment。- 结束原因、结束 tick、赢家。
- 完整排名和每国终局统计。
- 每场战斗记录。
- 首次宣战时间和吞并数量。
终局结果只在 GAME_RETENTION_MS 保留期内通过内存 API 可查;磁盘事件文件不会自动恢复 API 中的对局。
12. 健康检查
GET /health
响应示例:
{
"ok": true,
"games": 1,
"activeGames": 1,
"logging": "disk",
"degradedGames": 0,
"maxGames": 100,
"retentionMs": 3600000
}
logging=memory 表示至少一个活跃对局的磁盘日志失败,但游戏仍能继续,事件仍可从内存接口读取。此时应立即检查目录权限和磁盘空间。
13. 常见 HTTP 错误
| 状态 | 错误 | 含义 |
|---|---|---|
| 400 | invalid_request | 路径、查询或 JSON 不符合 schema |
| 401 | unauthorized | 缺少 Bearer token |
| 403 | forbidden / not_participant | token 身份不符或不是参战方 |
| 404 | game_not_found / nation_not_found / battle_not_found | 资源不存在或已过 TTL |
| 409 | awaiting_battle_choices | 等待参战方选择,tick 未推进 |
| 409 | deadline_not_reached | 尚不能强制开始战斗 |
| 409 | already_submitted | 本场已经提交过农民选择 |
| 409 | game_ended / game_not_ended | 调用阶段错误 |
| 503 | too_many_active_games | 活跃对局已达到 MAX_GAMES |
14. 外部参与者最小流程
参与者只需要收到:
API_BASE_URL
gameId
nationId
nationToken
每个普通窗口:
- 用 nation token GET 自己的 snapshot。
- 调用自己的 AI。
- 转成完整 Decision JSON。
- POST 到自己的 decisions 路径。
当公开状态出现 awaiting_battle_choices 且自己在 awaitingChoices 中:
- GET 对应 battle snapshot。
- 调用 AI 得到布尔值。
- POST
farmersJoin。
参与者不得调用创建、step、finalize 或管理员事件接口。