cortico-world-oni

Cortico World extension for Oxygen Not Included (《缺氧》), bridging game simulation to AI streamers and agents via the OniMods MCP Server.

Owner: src/index.ts
契约: Cortico API v4 (kind: world)

概述 (Overview)

cortico-world-oni 将《缺氧》底层的物理仿真、殖民地数据与指令系统抽象为标准 Cortico World 契约：

• 虚拟文件系统式世界编辑：通过类似读写文本文件的形式审阅局部地图、拓扑管线，并通过 SEARCH/REPLACE 补丁批量下达建造与挖掘任务；

• 殖民地宏观监控与警报：轮询小人窒息、饥饿、受伤、高压等致命状态，并转化为即时事件流推入 Agent 决策回路；

• 游戏节奏控制：支持动态暂停（速度 0）以供 AI 进行深度规划，并在规划完成后恢复游戏流速；

• 解说与情绪引导：内置专属环境提示词（ENV_PROMPT.md），使 AI 主播在遇到突发灾难时能够及时且生动地进行直播解说。

Related MCP server: YetAnotherUnityMcp

核心工具 (Tools)

本扩展在加载后向 AI Agent 暴露 10+1 个与最新 OniMcp 严格对齐的高阶聚合工具：

安装与装载 (Installation)

在 Cortico 项目根目录或 extensions/ 目录下，直接通过 GitHub 安装：

pnpm add -D github:vivy1024/cortico-world-oni

或在 extensions/package.json 中声明：

{
  "dependencies": {
    "cortico-world-oni": "github:vivy1024/cortico-world-oni"
  }
}

随后运行 pnpm install 即可自动完成扩展挂载。

配置示例 (Configuration)

在部署目录（如 deployments/yushu-live/config.json）的 worlds 段中启用：

{
  "worlds": {
    "oni": {
      "enabled": true,
      "endpoint": "http://localhost:8788/mcp/",
      "pollIntervalSeconds": 3,
      "alertThreshold": "warning"
    }
  }
}

• endpoint：游戏内 OniMcp 模组开放的 HTTP MCP 端点（默认端口 8788）；

• pollIntervalSeconds：轮询殖民地警报与突发事件的间隔（秒）；

• alertThreshold：事件上报过滤级别（info / warning / critical）。

配套游戏模组 (Prerequisites)

本扩展依赖在《缺氧》游戏客户端中安装并运行 OniMcp (基于 OniMods 的 C# 模组)：

1. 将 OniMcp.dll 及模组配置部署至《缺氧》本地模组目录；

2. 启动游戏并加载存档，模组将自动在本地后台启动 http://localhost:8788/mcp/ 服务；

3. Cortico 启动后将自动完成 MCP 握手并同步工具定义。若游戏尚未启动，扩展将以优雅降级模式等待重连。

开发与测试 (Development)

corepack pnpm install
pnpm test        # 运行 Vitest 单元测试
pnpm typecheck   # 运行 TypeScript 类型检查

在 Cortico 框架根目录下进行官方契约验证：

pnpm check:extension ../cortico-world-oni

许可证 (License)

MIT