Docs

文档中心

12 份文档随仓库走，克隆下来就能读。按你要做的事挑一篇——不用从头读到尾。

先做游戏

START-HERE.md 从零做一款游戏：建项目 → 写 .ui → 接布局/渲染 → 三端构建 → 验收。每个坑都有原始报错。 GAME-WORKFLOW.md 做一款完整能上线的游戏：PRD → 占位可玩 → 美术并行 → 手感 → 截图自评 → 包体 → 部署。 GAME-PLANNER.md 写代码前的策划流程。默认轻量 Concept → Top → PRD/ART-BRIEF，完整模式才跑 Architecture/Systems。

写界面与引擎 API

ui-syntax.md .ui 语法真源：region / put / layer、尺寸与对齐、命中语义、22 个通用组件的 props。 ENGINE-API.md 引擎 API 总表：布局与交互纯函数、绘制工具、DrawDeps / MeasureEnv、platform 契约。 CONVENTIONS.md 工程约定：配置字段、产物结构、命令语义、包体红线。

子系统

PHYSICS-GUIDE.md 2D 物理（planck 薄封装）：何时用、像素换算、验收清单。官方示例 games/platformer。 ECONOMY-SAVE.md 数值配表 TSV + 存档 + 离线收益（@mg/economy）。 STORY.md 扁平剧情 .story.tsv + lint / compile（@mg/story）。 UI-PIPELINE.md 美术到代码：风格板 → 整屏图 → tokens → 图层切割 → 补全 → 位图字体。 perf-bench.md Canvas 2D 性能基准：能画多少、什么时候必须上 WebGL。games/bench 可跑。 AGENTS.md 改引擎代码的硬规则（给 AI 的判据）：七条铁律、平台扩展六步、提交前自检、禁止事项。 Agent 工具 文档之外的另外两条通道：两个 Skill（gamekit-minigame / ui-authoring）+ 17 个 MCP 工具 + 一键安装提示词，让 agent 不用猜。

四条核心设计

读代码之前先知道这四条，否则会觉得「为什么这么绕」。

一层一职责

契约（contract.ts）→ 实现 → 测试，三层分开。单文件 300 行是提醒线、500 行是警告线，确需更长要在文件头写 // @long-file <原因> 豁免。

数据 / 逻辑 / 渲染三分

数据文件只放字面量；逻辑是纯函数（输入旧状态 → 输出新状态，不碰 canvas）；渲染只读状态、只画、不做判定。

平台差异只在 platform/

新增一个平台 = 新建目录 + 实现 PlatformAdapter + 写 probe()，不碰 core、不碰契约必需成员。业务代码里出现 wx. / tt. 一律打回。

无全局可变状态

状态挂在 Game 实例上，禁止模块级可变单例。注册表用工厂生产，每次新建一份，谁也污染不到谁。

仓库结构

packages 是框架，games 是游戏，templates 是脚手架。

目录
packages/
  runtime/       引擎内核：loop / stage / input / assets / audio / ads / save / ui / render / tween
                 + 平台适配层（web / wechat / douyin / mock）
  vite-plugin/   @mg/vite：三端产物、资源管线、图集打包、包体红线检查
  ui-plugin/     @mg/ui-plugin：.ui 编译（dev 与 build 走同一个函数）
  economy/       @mg/economy：配表校验、模拟、离线收益
  story/         @mg/story：剧情扁平源 + lint / compile
  physics-2d/    @mg/physics-2d：planck 薄封装（可选）
  debug-mcp/     调试 MCP server：离线 5 个 ui.* 工具 + 运行时 10 个工具
  cli/           mg 命令：create / dev / build / check / pack / doctor

templates/
  iaa-ui/        默认模板：.ui 界面链 + 31 个组件注册表
  iaa-simple/    手写布局 demo：广告三件套 + 主菜单 + 存档 + 最小玩法

games/           游戏工程只能放这里（mg create 强制）
docs/            文档