screeps-sandbox

高性能、单机自托管的 Screeps 对战沙盒服务器：多 bot 同世界实时对战， 官方 Screeps 客户端直连 live 观战与回放。C++ + QuickJS（每 bot 独立 runtime）+ teles（事件循环 / 网关 / 可观测），单二进制、零外部中间件（无 Node/Mongo/Redis）。

状态：骨架期（TQCQ-11）。当前入库：构建骨架（CMake/CTest/CPM 离线依赖）、 持续基准体系（首版基准目标 + 基线工具 + 设计文档）。核心模块（JS 沙盒 / 世界引擎 / 网关 / 历史）随子任务陆续落地 —— 见 AGENTS.md 的目录规划与 docs/roadmap.md 的进展盘点与任务清单。

快速开始

cmake -B build -DSBX_BUILD_TESTS=ON -DSBX_BUILD_BENCH=ON .   # 零网络，Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure                    # 含基准机制自检

# 世界目录（R152a：cwd 即世界，git 式）
mkdir myworld && cd myworld
build/src/sbx init --bots hivemind,tooangel   # meta.json + branches/main + assets
build/src/sbx serve                          # 官方客户端直连（锚点链自动持久化）
build/src/sbx run --ticks 500                # 批跑
build/src/sbx branch dev --at 1000           # 从锚点 fork 世界线

# 跑基准（正式流程：基线感知）
python3 tools/bench/bench.py run
python3 tools/bench/bench.py compare --baseline bench/baselines/dev-01.json --markdown

文档

• docs/requirements.md — 需求决策记录（权威：产品定位、运行形态、边界）
• docs/roadmap.md — 设计目标回顾 / 进展盘点 / 任务规划（骨架期定位锚点）
• docs/benchmarking.md — 基准与性能守护体系（设计 + G5 定标方法）
• docs/viewer.md — viewer 能力面与规范（播放器契约 / HTTP+WS 面 / 播放引擎）
• docs/world-objects.md — 世界对象层与无限世界设计（对象模型 / 物化·冷存·追赶 / B0–B6 批次 DAG）
• docs/wasm.md — WebAssembly 面契约（wasm3 供应链 / 能力边界实测矩阵 / M1–M4 分期）
• bench/README.md — 基准编写约定速查
• AGENTS.md — 仓库工程约定（依赖 / 构建 / 格式 / 目录规划）

项目边界

单机部署、性能第一（G5 由持续基准体系定标守护）；不做 Steam 认证、分布式、 官方 mod 生态兼容。完整需求口径见 docs/requirements.md。