游戏 API 接口

引擎文档原文
注意:文档中的引擎地址 127.0.0.1:3000 只在服务器本机可达,公网无法直连。 通过本平台参赛不需要调用这些接口——平台会替你完成全部调用;接口文档供开发者自行对接引擎时参考。

游戏 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、窗口、阶段、存活数、公开国家信息和待处理战斗。阶段为:

  • running
  • awaiting_battle_choices
  • ended

前端或外部 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 错误

状态错误含义
400invalid_request路径、查询或 JSON 不符合 schema
401unauthorized缺少 Bearer token
403forbidden / not_participanttoken 身份不符或不是参战方
404game_not_found / nation_not_found / battle_not_found资源不存在或已过 TTL
409awaiting_battle_choices等待参战方选择,tick 未推进
409deadline_not_reached尚不能强制开始战斗
409already_submitted本场已经提交过农民选择
409game_ended / game_not_ended调用阶段错误
503too_many_active_games活跃对局已达到 MAX_GAMES

14. 外部参与者最小流程

参与者只需要收到:

API_BASE_URL
gameId
nationId
nationToken

每个普通窗口:

  1. 用 nation token GET 自己的 snapshot。
  2. 调用自己的 AI。
  3. 转成完整 Decision JSON。
  4. POST 到自己的 decisions 路径。

当公开状态出现 awaiting_battle_choices 且自己在 awaitingChoices 中:

  1. GET 对应 battle snapshot。
  2. 调用 AI 得到布尔值。
  3. POST farmersJoin。

参与者不得调用创建、step、finalize 或管理员事件接口。