上手指南
从零到三端产物。每一步都有对应命令，照着抄就能跑通「界面 → 构建」的闭环。
先决条件
Node.js ≥ 22（与 package.json 的 engines、mg doctor 同一口径）、pnpm，仓库已 pnpm install。所有命令都在仓库根执行（有 pnpm-workspace.yaml 的那层）。
pnpm verify-platform（真浏览器门禁用无头 Chrome）必须是有完整进程权限的会话。受限沙箱里 Chrome 的 crashpad 会「启动即自杀」，表现像端口被占或浏览器版本不对，--no-sandbox 也救不了。
安装与体检
git clone https://github.com/ahao0150/gamekit.git
cd gamekit
pnpm install
pnpm doctorpnpm doctor 会核对 Node 版本、pnpm、依赖、契约文件与模板，全过再往下走。
创建游戏
# 默认模板 iaa-ui：.ui 界面链已接好
pnpm mg -- create my-game
# 极简单屏 demo：手写布局老链
pnpm mg -- create my-game --template iaa-simple--template 就是 templates/ 下的目录名，新增模板不用改 CLI。
改 game.config.json
{
"design": { "width": 390, "height": 844 },
"fit": "fill",
"title": "我的游戏",
"assetsDir": "assets",
"subpackages": {}
}fit 取 contain / fill / height。这份配置走 virtual:mg-config，是唯一真源——main.ts 不用再写一遍。
写界面（.ui）
界面写在 ui/*.ui：region 切带，put 往里放组件。没有嵌套、没有括号、没有缩进语义——行序就是语义。
region header top 48 row gap 8 pad 12 align center
put statusText size fill
put pause size fixed 24 align end
region body fill column pad 12
put parcelGrid size fill
region footer bottom 72 column gap 8 pad 12 align stretch
put primaryButton size fill cross fixed 56 style label="开始"改完 .ui 不用碰其它文件：layout.ts 的 UI_OF 负责把编译产物喂给 bindComponents → layout → rects。
组件注册表：31 个现成件
用默认模板 iaa-ui 的话这一步不用动——它的 src/app/ui-registry.ts 已经遍历注册了全部组件。构建期校验与运行时用的是同一份工厂。
内置 9 个
primaryButton / secondaryButton / coinBadge / statusText / pause
parcelGrid / infoPanel / card0 / card1
通用 22 个
progress / panel / label / button / input / list / grid / scroll
slider / tabs / segmented / keypad / carousel / scrollbar / toast
switch / checkbox / radio / divider / badge / icon / avatar写错组件名，mg build 会直接报「未知组件 'xxx'，已注册的有：…」，照抄报错即可。
构建三端
cd games/my-game
pnpm dev # dev server，默认绑 127.0.0.1
pnpm build # = mg build --all → build/{web,wx,tt}
pnpm check # 包体与配置校验（3MB 发布线 / 4MB 平台硬限）
pnpm test # 这个游戏自己的单测mg build 会先跑一次 tsc，类型错了直接停，不会产出半成品。
验收
截图必须肉眼确认画面内容，不能只读状态——「状态全绿、画面全空」在真实项目里复现过多次（分数在涨、棋盘一格没画）。
每张截图过四件事：背景有颜色 / 可点元素可见 / 数字与状态一致 / 截图尺寸与目标视口一致。做不了视觉验收就写「视觉验收未做，已用像素统计替代」并给出数字。
四个踩过的坑
都是实测撞出来的，报错原文照抄。
① region 的 top 是累加，不是绝对偏移
region head top 9% 之后再写 region hudLayer top 9%，第二个 region 从 76px 开始（9% × 844），不是从 0 开始——两者是上下相接的两条带，不是重叠的两层。
症状很隐蔽：深底上看不出来，换了浅底、给 HUD 加了底板，才发现文字落在 HUD 带下方。想让两块同高叠放，用 layer overlay + at <x> <y> size <w> <h> 叠回同一块区域。bottom 同理，是从底部累减。
② 一个界面里同名组件只能出现一次
rects 以组件名为键。要两个按钮，用 button / primaryButton / secondaryButton 这类已有的不同名组件，不要自造实例名（不能写 put startButton）。
③ 样张不能进 assets/
打包规则是「assets/ 下一切媒体文件都进包」。样张进包会顶到微信主包 4MB 红线——实测一次 3.86MB 样张让 wx 主包到了 3922.9 KB，产物直接不能上架。样张、原图、中间产物放 artifacts/。
④ 数据驱动组件要喂两个通道
list / grid / carousel 需要布局期的 bindComponents(env.data) 和绘制期的 DrawDeps.data，两个都要传。只传前者会「状态全对、画面全空」。
下一步
跑通了想做出能上线的完整游戏，看这几篇。