123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
# ONI Agent Mod 开发指南
|
||
|
||
## 概述
|
||
|
||
本文档规定 ONI Agent Bridge Mod 的接口规范和开发约束。
|
||
|
||
## 1. 通信协议
|
||
|
||
### 1.1 传输层
|
||
- **协议**: HTTP 1.1
|
||
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露外部网络）
|
||
- **端口**: 默认 `23876`，可在 `config.json` 修改
|
||
- **编码**: UTF-8
|
||
|
||
### 1.2 数据格式
|
||
所有请求和响应使用 `application/json`。
|
||
|
||
**统一响应格式：**
|
||
|
||
```json
|
||
// 成功
|
||
{ "success": true, "data": { ... } }
|
||
|
||
// 错误
|
||
{ "success": false, "error": "error_code", "errorMessage": "可读信息" }
|
||
```
|
||
|
||
**旧格式兼容**（/health 端点历史版本）：
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
### 1.3 线程模型
|
||
- **读操作**可通过 `EnqueueRead(Func<object>)` 排队到主线程执行（`ManualResetEvent` 同步等待）
|
||
- **写操作**通过静态 `ConcurrentQueue<Action> cmdQueue` + `QueueProcessor` (MonoBehaviour.Update) 排队到主线程
|
||
- **格子数据**（Grid.Element/Mass/Temperature/Objects）可从后台线程直接读取（静态数组）
|
||
|
||
## 2. 端点规范
|
||
|
||
### 2.1 健康检查
|
||
```
|
||
GET /health
|
||
```
|
||
必须始终可达，不依赖游戏状态。
|
||
```json
|
||
{ "success": true, "data": { "status": "ok", "service": "oni-agent-bridge", "version": "2.0.0" } }
|
||
```
|
||
|
||
### 2.2 状态查询 (GET /api/state/)
|
||
| 端点 | 说明 | 实现方式 |
|
||
|------|------|---------|
|
||
| game | 周期/复制人/世界尺寸/暂停/速度 | EnqueueRead |
|
||
| resources | 资源列表(含物态/存量) | EnqueueRead |
|
||
| buildings | 建筑列表(含位置/尺寸) | EnqueueRead |
|
||
| duplicants | 复制人(位置/血量) | EnqueueRead |
|
||
| research | 科技进度 | EnqueueRead |
|
||
| rooms | 房间类型 | EnqueueRead |
|
||
| events | 事件日志(支持since分页) | 直接读取(eventLock) |
|
||
| storage | 储物建筑内容 | EnqueueRead |
|
||
| saves | 存档列表 | EnqueueRead |
|
||
| alert | 游戏警报 | EnqueueRead |
|
||
| camera | 相机位置 | EnqueueRead |
|
||
|
||
### 2.3 格子数据 (GET, 可后台线程)
|
||
| 端点 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| cell | x, y | 单格详情 |
|
||
| cells | x, y, width, height | 矩形区域 |
|
||
| cells/slice | axis, index, start, end | 行列扫描 |
|
||
| gas | x, y, radius | 气体分布 |
|
||
|
||
### 2.4 注册表 (GET /api/registry/)
|
||
| 端点 | 说明 |
|
||
|------|------|
|
||
| buildings | 所有建筑定义(含尺寸/材料类别) |
|
||
| elements | 所有元素定义 |
|
||
| techs | 科技树(含前置) |
|
||
|
||
### 2.5 操作 (POST /api/action/)
|
||
所有操作执行前**自动拉视角**到目标坐标。
|
||
|
||
| 端点 | 请求体 | 说明 |
|
||
|------|--------|------|
|
||
| pause | {reason?} | 暂停(通过SpeedControlScreen) |
|
||
| unpause | {speed?} | 恢复 |
|
||
| speed | {speed} | 设速度 |
|
||
| dig | {x,y,width,height} | 挖掘(使用DigTool.PlaceDig) |
|
||
| build | {buildingId,x,y} | 建造(使用BuildingDef.Instantiate) |
|
||
| deconstruct | {x,y} | 拆除(使用Deconstructable.QueueDeconstruction) |
|
||
| prioritize | {x,y,priority} | 设优先级(1-9) |
|
||
| research | {techId} | 研究(SetActiveResearch) |
|
||
| mop | {x,y} | 清理液体 |
|
||
| harvest | {x,y} | 收获植物 |
|
||
| batch | {actions} | 批量操作 |
|
||
| save | {name?} | 存档 |
|
||
| load | {name} | 读档 |
|
||
| camera | {x,y,zoom?} | 移动视角 |
|
||
| priority_global | {target,priority} | 全局默认优先级 |
|
||
| priority_type | {buildingType,priority} | 按类型优先级 |
|
||
|
||
### 2.6 截图
|
||
```
|
||
GET /api/screenshot/latest
|
||
```
|
||
返回 PNG 图片。通过 `ScreenCapture.CaptureScreenshot` 异步生成。
|
||
|
||
## 3. 事件系统
|
||
|
||
Mod 内部维护事件列表 (`List<AgentEvent> + lock`)。
|
||
事件可通过 `GET /api/state/events?since=N` 轮询。
|
||
事件自动记录操作日志。
|
||
|
||
## 4. Mod 开发检查清单
|
||
|
||
- [ ] Mod 类继承 `UserMod2`，重写 `OnLoad(Harmony)`
|
||
- [ ] 用 `GameObject + MonoBehaviour` 处理队列，`DontDestroyOnLoad`
|
||
- [ ] 用 `HttpListener` 暴露 HTTP 服务，`BeginGetContext` 异步处理
|
||
- [ ] 格子数据安全读取：`Grid.Element[]`、`Grid.Mass[]`、`Grid.Solid[]`、`Grid.Objects[,]`
|
||
- [ ] 读操作用 `EnqueueRead` 同步到主线程
|
||
- [ ] 写操作用 `cmdQueue` 排队到主线程的 `Update()` 中执行
|
||
- [ ] 响应统一 `{success, data}` 或 `{success, error, errorMessage}`
|
||
- [ ] 所有操作自动 `QWithCamera(x,y,action)` 拉视角
|