一款会读取玩家心率、理解开放语音，并让自主小车与对抗性机械臂在真实空间中共同演出的具身 AI 游戏；也是一台配置驱动的具身 AI 游戏创作引擎。

赛道： 软件赛道 · AI & Agent

产品定位： 具身 AI 游戏创作平台，Moonfall 为首款样板游戏

GitHub： https://github.com/Moonfall-Lab/moonfall-ark

四名幸存者迫降月球，必须收集燃料、修复方舟并升空返航；玩家不直接遥控机器人，而是通过策略卡与开放语音影响自主小车。四名玩家的心率会持续改变“月球狂暴度”，并驱动机械臂向实体地图投放月尘、陨石与干扰。

今天的机器人体验通常停留在两端：一端是遥控或编程教学，参与门槛高；另一端是固定流程的设备表演，内容难以复用。创作者若想做一个新的实体互动游戏，需要同时理解机器人控制、视觉定位、传感器、实时通信与规则开发。

Moonfall Ark 把这些能力收敛成一套游戏运行时和配置 IR：

• 玩家负责意图，Agent 负责行动。 策略与自然语言被转成闭合的动作空间，小车自主完成移动、采集、返航与避障。
• 人的状态成为游戏输入。 心率不是展示数据，而是直接影响难度和机械臂事件。
• 物理设备成为可组合能力。 小车、机械臂、心率、语音、定位与大屏通过统一消息协议接入，不互相写死。
• 创作者定义玩法，而不是重写驱动。 地图、阵营、单位、输入、事件和规则由配置描述；同一套硬件可以承载不同游戏。

人类方舟计划的登月舱迫降月球背面，能源核心破碎。四名幸存者指挥探测车在实体月面收集氦-3 与遗迹碎片，修复飞船并尝试升空。

月球拥有意志，名为“上帝之手”。它能感知玩家的紧张程度：心率越高，月球越狂暴；月怒跨过阈值后，机械臂会悬停警告、投放月尘或打击目标，迫使小车重新规划路线。玩家需要在资源竞争、风险控制和情绪管理之间做出选择。

胜利： 收集足够燃料、保持飞船存活并完成点火。

失败： 飞船生命值归零，或未能在回合上限前升空。

flowchart LR
    P[玩家] -->|策略卡 / 开放语音| A[自主小车 Agent]
    A -->|视觉定位 / 路径规划 / 行动| W[实体月面]
    P -->|心率| D[月球导演]
    D -->|灾难指令| M[对抗性机械臂]
    M -->|月尘 / 障碍 / 打击| W
    W -->|位置与事件| R[Moonfall Runtime]
    R -->|实时世界状态| S[Three.js 大屏]
    R --> A
    R --> D

这条链路中的输入、状态、指令和事件都使用统一消息封套，经 WebSocket 实时分发并写入 SQLite 日志，可用于现场调试与复盘。

flowchart TB
    subgraph Inputs[输入层]
      HR[心率 / rPPG]
      VO[语音]
      CA[策略卡]
      PO[视觉定位]
    end

    subgraph Runtime[Moonfall Runtime]
      WS[实时消息总线]
      ST[世界状态]
      VP[语音意图解析]
      RE[规则引擎]
      MD[月球导演]
      LOG[SQLite 日志]
    end

    subgraph Physical[实体能力层]
      RV[自主小车]
      ARM[机械臂]
      PRE[人形机器人 / Presenter]
    end

    UI[React + Three.js 大屏]

    Inputs --> WS
    WS <--> ST
    VP --- ST
    RE --- ST
    MD --- ST
    WS --> LOG
    WS <--> Physical
    WS --> UI

Runtime 是唯一的实时状态中心。前端、小车、机械臂、心率与语音客户端只连接 Runtime，不互相直连。统一边界让物理驱动、屏幕模拟和无头测试可以履行同一能力契约。

Moonfall 是平台运行的首款样板游戏。平台把设备抽象为六类能力：

游戏配置只声明需要什么能力，不绑定设备品牌。binding.physical.json 与 binding.software.json 展示了同一份游戏如何分别运行在实体设备和屏幕模拟驱动上；三份示例游戏均使用同一种强类型 IR。

相关设计：docs/engine_platform_design.md · docs/schema/CONFIG_GUIDE.md · docs/schema/game_config.schema.json

• Python 3.11+
• Node.js 18+
• 可选：DeepSeek API Key 或 NVIDIA OpenAI-compatible 服务
• 实体版可选：顶视摄像头、Deskbot 小车、机械臂、rPPG 服务

macOS / Linux：

git clone https://github.com/Moonfall-Lab/moonfall-ark.git
cd moonfall-ark
cp .env.example .env

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Windows：

git clone https://github.com/Moonfall-Lab/moonfall-ark.git
cd moonfall-ark
copy .env.example .env

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

验证：

• 健康检查：http://127.0.0.1:8000/api/health
• 当前世界：http://127.0.0.1:8000/api/state
• API 文档：http://127.0.0.1:8000/docs
• WebSocket：ws://127.0.0.1:8000/ws

也可以运行：

docker compose up --build

cd frontend
npm install
npm run dev

打开 http://127.0.0.1:5173。大屏默认连接本机 8000 端口；局域网演示使用：

http://前端地址:5173/?host=后端电脑IPv4:8000

使用 ?mock=1 可以在没有 Runtime 和硬件时预览完整界面。左上角 LIVE 表示真实后端，MOCK 表示模拟数据。

启动 Runtime 与大屏后，可使用 fake clients 验证完整消息链：

# 终端 1：心率输入
cd backend
python clients/hr_client_example.py

# 终端 2：开放语音
python clients/voice_client_example.py

# 终端 3：小车命令订阅
python clients/robot_client_example.py

# 终端 4：机械臂命令订阅
python clients/arm_client_example.py

在语音终端输入：

让一号车绕开月尘，去中央区域采集燃料

可以观察到：

1. Runtime 将自然语言解析为受约束的 VoiceIntent。
2. WebSocket 广播 cmd.robot，大屏同步更新单位状态与事件流。
3. 心率输入推高月怒；达到阈值后，月球导演广播 cmd.arm。
4. 所有输入、AI 解析和功能事件写入 SQLite，可通过日志 API 查询。

backend/clients/rover_agent/ 是可独立运行的视觉导航 Agent：顶视相机识别桌面角标与车顶 ArUco，换算为厘米坐标；A* 在膨胀障碍地图上规划路径；闭环控制器持续用最新位姿修正轮速。

# 场地初始化：绑定车辆、标定桌面、圈选固定地标
PYTHONPATH=backend/clients python -m rover_agent.setup_field --camera 0

# 可视化定位与路径
PYTHONPATH=backend/clients python -m rover_agent.viz --camera 0

# 运行多车 Agent，并接入 Runtime
PYTHONPATH=backend/clients python -m rover_agent.agent \
  --camera 0 --viz \
  --config docs/schema/examples/moonfall_mvp.game.json \
  --bridge ws://127.0.0.1:8000/ws

详细部署、标定和故障排查见 backend/clients/rover_agent/README.md 与 docs/rover_navigation.md。

项目提供 backend/rppg_bridge.py，可将多人 rPPG 服务的结果每秒转换为统一的 sensor.hr 消息：

cd backend
RPPG_URL=http://RPPG_SERVER:5050 \
MOONFALL_WS=ws://127.0.0.1:8000/ws \
python rppg_bridge.py

完整步骤见 docs/rppg_integration.md。可穿戴设备只要发送相同消息，也可以直接替换 rPPG 数据源。

所有实时消息使用统一格式：

{
  "topic": "sensor.hr",
  "source": "hr_p1",
  "timestamp": 1720000000.0,
  "payload": {
    "player_id": "p1",
    "heart_rate": 105
  }
}

完整协议见 docs/websocket_topics.md 与 docs/rover_backend_api.md。

moonfall-ark/
├── backend/
│   ├── app/                    # FastAPI Runtime、世界状态、规则、导演与日志
│   ├── clients/                # 心率、语音、小车、机械臂示例客户端
│   │   └── rover_agent/        # 视觉定位、规划、控制与多车编队
│   ├── configs/moonfall.yaml   # 当前 MVP 运行配置
│   └── rppg_bridge.py          # 多人 rPPG → sensor.hr
├── frontend/                   # React + Three.js 实时大屏
├── docs/
│   ├── schema/                 # 游戏配置 Schema、DSL 与多游戏示例
│   ├── engine_platform_design.md
│   ├── rover_navigation.md
│   └── rppg_integration.md
├── tests/                      # Runtime 契约与 rover 纯软件测试
├── docker-compose.yml
└── LICENSE

• Runtime： Python, FastAPI, Pydantic, WebSocket, SQLite
• AI： DeepSeek / NVIDIA OpenAI-compatible API，规则解析兜底
• Web： React, Vite, Three.js, Framer Motion, Tailwind CSS
• 视觉与导航： OpenCV, ArUco, NumPy, A*，闭环差速控制
• 设备通信： WebSocket, HTTP, UDP
• 配置： YAML, JSON Schema, 声明式规则 DSL

Moonfall 对标屏幕游戏领域的 Unity 与 Roblox：我们不只制作一款游戏，而是提供具身 AI 游戏的创作与运行基础设施。

长期壁垒来自可复用的设备驱动、行为库、游戏模板，以及创作者与场地方共同形成的内容网络效应。

• 具身 AI 游戏引擎平台设计
• 游戏配置指南
• 规则 DSL 执行规范
• 后端 API 契约
• WebSocket Topics
• 视觉导航小车
• 小车与 Runtime 接口
• rPPG 心率接入
• Docker 部署
• 队友快速接入

本项目使用 Apache License 2.0。