evomeme-dev 0.1.7

package/skills/phaser-2d-game/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: phaser-2d-game
+description: 用 Phaser、TypeScript 与 Vite 实现 2D 浏览器游戏。在需要场景、玩法系统、摄像机、精灵动画、Arcade 物理、tilemap、DOM 覆盖层 HUD 或竖屏触控时使用。
+---
+
+# Phaser 2D 游戏实现
+
+## 概述
+
+本技能用于 2D 浏览器游戏的具体实现阶段。
+
+技术栈：**Phaser 3 + TypeScript + Vite + pnpm**，正式 HUD/菜单以 **DOM 覆盖层**（通常 React）叠在 Canvas 上。
+
+## 架构原则
+
+1. **系统与场景分离**
+   - 系统（System）拥有游戏规则、回合顺序、移动、战斗、背包、目标和进度逻辑。（与 3D 技能的 `game/simulation` 对位：规则真相层）
+   - Phaser Scene 只将系统状态映射为精灵位置、摄像机运动、动画播放和特效，不持有游戏真相。
+
+2. **场景保持轻量**
+   - Boot Scene：配置初始化与资产预加载
+   - Menu Scene：主菜单或壳层（复杂菜单仍可走 DOM）
+   - Gameplay Scene：主游戏循环视图
+   - 可选：调试并行 Scene（不替代正式 HUD）
+
+3. **渲染对象可丢弃**
+   - 精灵容器、粒子、Tween、摄像机索具是视图状态，不是数据源。
+
+4. **资产键稳定**
+   - 通过 manifest / `public/config.json` 引用资产，业务代码不硬编码散落 URL。
+
+## 实现指导
+
+- Scene 经单一边界读 System，并把输入意图回传 System。
+- 优先确定性系统更新；避免在 `update` 里堆完整规则。
+- 文字密、状态复杂的 HUD/菜单用 DOM，不用 Canvas 密文。
+- 动画状态从游戏状态派生。
+- **视口缩放只用 Phaser Scale Manager**，禁止 CSS/`transform` 手搓缩放（见 `references/engine-runtime.md`）。
+- **spritesheet 先量图再写 loader**（见 `references/engine-spritesheets.md`）。
+
+## 引擎参考（按需加载）
+
+写/改 Phaser 运行时代码时，在 `file-structure.md` 之外按任务加载，勿一次性预读全部：
+
+| 任务 | 加载 |
+| --- | --- |
+| 场景生命周期、Scale、delta、切场景 | `references/engine-runtime.md` |
+| Arcade/Matter 选型、碰撞、对象池 | `references/engine-physics.md` |
+| 任意 spritesheet / 图集 / 九宫 | `references/engine-spritesheets.md`（加载 sheet **之前**） |
+| Tiled 地图、碰撞层、物件刷怪 | `references/engine-tilemaps.md` |
+| 卡顿、池化、裁剪、update 分配 | `references/engine-performance.md` |
+
+## 覆盖的 2D 游戏类型
+
+- 回合制格子与战棋
+- 俯视探索地图
+- 横版动作平台
+- 角色动作战斗（精灵动画帧）
+- 轻量经营或卡牌/指令对战场景
+
+## 摄像机与表现
+
+- 早期确定摄像机模型：锁定、跟随、房间切换、战术平移。
+- 摄像机逻辑与游戏规则完全分离。
+- 震动、顿帧、视差须提升可读性，不能挡关键信息。
+- 大地图：`cameras.setBounds` 与 `physics.world.setBounds` 对齐。
+
+## UI 集成
+
+- HUD、指令菜单、设置与叙事用 DOM 覆盖层。
+- Canvas 负责游戏世界、战斗可读性与运动表现。
+- 除非项目明确要求，不在 Phaser 内渲染密集文字或复杂设置 UI。
+
+## 资产目录规范
+
+```
+assets/
+  characters/   精灵、帧动画
+  environment/  背景、地块、场景件
+  ui/           HUD 图片、图标、按钮
+  fx/           粒子、特效
+  audio/        BGM、SFX
+  data/         关卡配置、对话数据、Tiled JSON
+```
+
+## 脚手架与配置
+
+新项目入口：`index.html`、`src/main.ts`、`public/config.json`。包管理器为 **pnpm**。构建产物含 `dist/index.html` 与 `dist/config.json`。目录与 config schema 以 `references/file-structure.md` 为唯一规范来源。
+
+## 常见反模式
+
+React 与 Phaser 共存时，在 `root.render()` 后立即调用 `createGame()` 会形成启动竞态：React 尚未提交 `#game-container`，Phaser 便可能将 Canvas 挂到错误层级并遮住菜单，而游戏仍停留在 `menu` 或 `inputLocked` 状态，表现为画面可见但无法操作。应使用 `flushSync`、`useLayoutEffect`、回调 ref 或明确的容器就绪信号，按“React 容器提交完成 → 容器存在且尺寸有效 → 创建 Phaser”的顺序启动，并在初始化前检查容器和 Canvas 挂载关系；遇到点击无效时先确认界面状态、输入锁和 DOM 结构，再调整事件路径。
+
+React 开发模式会执行一次额外的挂载清理与重新启动。如果旧 Phaser Scene 被销毁时没有注销其事件监听，按钮虽然收到了点击，事件却可能先命中已经销毁的旧 Scene，随后抛错并中断新 Scene 的点击处理。禁止只销毁 Phaser 实例却遗留 Scene 注册在输入系统、DOM、`window`、共享 EventEmitter 或 React 桥接层上的监听；每次 `on`、`addEventListener` 或订阅都必须有对应的 `off`、`removeEventListener` 或取消订阅，并在 Scene 的 `SHUTDOWN`/`DESTROY` 与 React effect cleanup 中完成清理。开发模式下必须验证重复“创建 → 清理 → 创建”后只剩当前 Scene 响应一次点击。
+
+- 游戏规则写在 Scene `update` 里，没有系统边界
+- Scene 间靠 `window` 可变全局传状态
+- 用 CSS 缩放 Canvas 代替 Scale Manager
+- 未测量就猜 spritesheet 的 frameWidth/Height
+- 简单 AABB 却上 Matter
+- 子弹/敌人无池化狂建销毁
+- 只为方便把正式 HUD 画在 Canvas
+- 资产路径硬编码多处
+- 在游戏 UI 套通用 React 仪表盘模式
+- 用 CRA / Next.js / npm-only 脚手架替换本规范（除非用户明确要求）
+
+## References
+
+**引擎（本技能）**
+- 文件结构与分层：`references/file-structure.md`
+- 运行时 / 缩放：`references/engine-runtime.md`
+- 物理与对象池：`references/engine-physics.md`
+- Spritesheet / 图集：`references/engine-spritesheets.md`
+- Tilemap：`references/engine-tilemaps.md`
+- 性能：`references/engine-performance.md`
+
+**跨技能**
+- 美术风格：`../game-art/references/art-styles.md`
+- 空间构图范式：`../game-art/references/scene-profiles.md`
+- 2D 画面提质：`../phaser-2d-graphics-builder/SKILL.md`
+- 动效规范：`../game-art/references/animation-specs.md`
+- UI 风格：`../game-ui/references/ui-styles.md`
+- 手感：`../game-designer/references/game-feel.md`
+- 关卡设计：`../game-designer/references/game-design-level-design.md`
+- 新游戏 DoD：`../game-designer/references/checklists/new-game-definition-of-done.md`
+- 手感清单：`../game-designer/references/checklists/game-feel.md`
+- 关卡清单：`../game-designer/references/checklists/game-design-level-design.md`

package/skills/phaser-2d-game/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Phaser 2D Game"
+  short_description: "搭建结构清晰的二维浏览器游戏，处理场景、玩法、输入与界面集成"
+  default_prompt: "请使用 $phaser-2d-game 根据我的需求实现这个二维浏览器游戏，并保持场景、玩法系统和界面边界清晰。"
+
+policy:
+  allow_implicit_invocation: true

package/skills/phaser-2d-game/references/engine-performance.md

@@ -0,0 +1,64 @@
+# 引擎：性能
+
+卡顿、掉帧、生成尖峰时加载。
+
+## 优先做的几件事
+
+1. **对象池**：子弹、敌人、飘字、短效粒子载体 — 见 `engine-physics.md`  
+2. **图集**：同屏尽量同一 atlas，减少贴图切换  
+3. **少碰撞对**：只挂需要的 collider/overlap；关闭屏外 body  
+4. **update 不分配**：不在每帧 `{}` / `new Vector2`；复用临时向量  
+5. **时间用 delta**：`delta/1000`；AI/寻路可降频  
+
+## 物理
+
+```ts
+// 屏外可关 body
+enemy.body.enable = cam.worldView.contains(enemy.x, enemy.y);
+
+// 圆形碰撞往往比大矩形便宜
+sprite.body.setCircle(16);
+```
+
+大量动态体时评估 `arcade.useTree` / `maxEntries`；>5000 再考虑关 tree（按实测）。
+
+## 渲染
+
+- 背景用 `tileSprite` 或静态图，勿每帧重绘大图  
+- 慎用 ADD/MULTIPLY 等混合（易拆 batch）  
+- 粒子设 `maxParticles` / `frequency`  
+- 相机外精灵默认会 cull；`scrollFactor 0` 的固定 UI 若在 Canvas 上需有意为之（正式 HUD 仍用 DOM）
+
+## 内存与切场景
+
+```ts
+shutdown() {
+  this.enemies?.clear(true, true);
+  // 按需 this.textures.remove('only-this-level');
+}
+```
+
+切关卸载仅本关大图/tilemap；公共 atlas 可留。
+
+## 降频贵逻辑
+
+```ts
+if (time - this.lastAiAt > 100) {
+  this.lastAiAt = time;
+  this.updateEnemyAi(); // System 侧亦可
+}
+```
+
+移动/相机每帧；AI、寻路、清理扫描可 5–10Hz。
+
+## 快检表
+
+| 症状 | 常因 | 处理 |
+| --- | --- | --- |
+| 越玩越慢 | 泄漏未 destroy | 查池与 shutdown |
+| 周期性顿 | GC | 池化、减 update 分配 |
+| 一直低帧 | 对象/绘制过多 | 裁剪、图集、减粒子 |
+| 生成尖峰 | 当场 create | 预池 |
+| 碰撞卡 | 检查对数爆炸 | 减对、简化 shape |
+
+开发可看 `this.game.loop.actualFps`；发布关掉物理 debug 与密集 FPS 文本（或仅 DOM 调试开关）。

package/skills/phaser-2d-game/references/engine-physics.md

@@ -0,0 +1,139 @@
+# 引擎：Arcade 物理与对象池
+
+玩法数值仍归 System / `config.json`；本文件只管 Phaser 物理 API 与常见坑。
+
+改碰撞、平台、子弹池、击退、单向板时加载。
+
+## 世界配置（摘录）
+
+```ts
+physics: {
+  default: 'arcade',
+  arcade: {
+    gravity: { x: 0, y: 300 }, // 可乘 config gravity_scale
+    debug: false,              // 发布关闭
+    fps: 60,
+    overlapBias: 4,
+    tileBias: 16,
+    useTree: true,             // 超大量动态体再评估 false
+  },
+}
+```
+
+## Body 类型
+
+- **Dynamic**：速度、重力、碰撞响应（玩家、敌人、子弹）。
+- **Static**：不动平台；改尺度/位置后调用 `refreshBody()` / group `refresh()`。
+
+```ts
+const player = this.physics.add.sprite(100, 100, 'player');
+player.body.setCollideWorldBounds(true);
+player.body.setSize(24, 40, true);
+player.body.setOffset(4, 8);
+player.body.setMaxVelocity(300, 400);
+player.body.setDrag(100, 0);
+```
+
+圆体：`setCircle(radius, offsetX, offsetY)`。视觉 mesh 可大于 body；**不要**用整张大图当碰撞盒。
+
+## Collider vs Overlap
+
+```ts
+// 物理分离
+this.physics.add.collider(player, platforms);
+this.physics.add.collider(player, enemies, onHit, processCb, this);
+
+// 只检测重叠（拾取、触发器）
+this.physics.add.overlap(player, coins, onCollect, undefined, this);
+```
+
+`process` 回调返回 `false` 可跳过本次碰撞（无敌帧、单向板）。
+
+### 触地 / 贴墙
+
+```ts
+if (player.body.blocked.down) { /* 着地 */ }
+if (player.body.touching.down) { /* 踩在某 body 上 */ }
+if (player.body.wasTouching.down && !player.body.touching.down) { /* 刚离地 */ }
+```
+
+### 世界边界
+
+```ts
+this.physics.world.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.startFollow(player, true, 0.08, 0.08);
+```
+
+## 对象池（高频生成必用）
+
+```ts
+this.bullets = this.physics.add.group({
+  defaultKey: 'bullet',
+  maxSize: 100,
+});
+
+function fire(x: number, y: number, vx: number, vy: number) {
+  const b = this.bullets.get(x, y);
+  if (!b) return;
+  b.setActive(true).setVisible(true);
+  b.body.enable = true;
+  b.body.reset(x, y);
+  b.setVelocity(vx, vy);
+}
+
+function kill(b: Phaser.Physics.Arcade.Sprite) {
+  b.setActive(false).setVisible(false);
+  b.body.enable = false;
+  b.body.stop();
+}
+```
+
+禁止在热路径每帧 `new` / `destroy` 子弹与粒子载体。
+
+## 常用模式
+
+### 平台跳
+
+```ts
+if (jumpPressed && player.body.blocked.down) {
+  player.setVelocityY(-330); // 高度用 config
+}
+```
+
+### 加速度移动
+
+```ts
+player.body.setMaxVelocity(maxSpeed);
+player.body.setDrag(drag, 0);
+player.body.setAccelerationX(left ? -accel : right ? accel : 0);
+```
+
+### 单向板
+
+```ts
+function oneWay(
+  player: Phaser.Physics.Arcade.Sprite,
+  platform: Phaser.Physics.Arcade.Sprite,
+) {
+  return (
+    player.body.velocity.y > 0 &&
+    player.body.bottom <= platform.body.top + 10
+  );
+}
+this.physics.add.collider(player, platforms, undefined, oneWay, this);
+```
+
+### 击退
+
+改速度后由 System 记无敌；Scene 只播反馈。`setVelocity` 方向由相对位置决定。
+
+## 与 System 分层
+
+- 碰撞回调里：**先**把事件交给 System（受伤、拾取），再改视图（闪白、禁用 sprite）。
+- 不要在回调里散落胜负规则副本。
+- `debug: true` 仅开发；发布与截图前关闭。
+
+## Matter？
+
+仅当 Arcade AABB 不够（复杂多边形、关节、布娃娃）。菜单/卡牌不要开物理。细节需求再查 Phaser Matter 文档；默认路径保持 Arcade。

package/skills/phaser-2d-game/references/engine-runtime.md

@@ -0,0 +1,129 @@
+# 引擎运行时（Phaser 3）
+
+**System 持规则真相、Scene 只做视图、正式 HUD 用 DOM**。目录与 config 以 `file-structure.md` 为准。
+
+写/改场景生命周期、缩放、帧循环、场景切换时加载本文件。
+
+## 与本项目分层的对应
+
+| Phaser 概念 | 本项目落点 |
+| --- | --- |
+| Boot / preload | Boot Scene：读 `config.json`、按 manifest 预加载 |
+| Gameplay Scene | 读 System 状态 → 精灵/相机/特效；输入意图回传 System |
+| 正式 HUD / 菜单 | React DOM 覆盖层（非 Canvas 密文 UI） |
+| 可选并行 Scene | 仅调试 / 极轻量世界内指示；不替代正式 HUD |
+| 可调数值 | `public/config.json`，禁止魔法数散落 |
+
+## 场景结构（推荐）
+
+```text
+scenes/
+├── BootScene.ts       # 配置与资产预加载、进度
+├── MenuScene.ts       # 壳层（可很薄；复杂菜单仍可走 DOM）
+├── GameScene.ts       # 主循环视图
+└──（可选）DebugScene  # 并行调试，勿塞正式 HUD
+```
+
+切换：
+
+```ts
+this.scene.start('GameScene', { level: 1 }); // 停当前，启新
+this.scene.launch('DebugScene');             // 并行
+this.scene.pause('GameScene');
+this.scene.stop('DebugScene');
+```
+
+场景间状态用 **init 数据 / registry / System 门面**，禁止挂可变全局到 `window`。
+
+## 场景生命周期
+
+```ts
+class GameScene extends Phaser.Scene {
+  init(data: unknown) {}           // 接收上一场景数据
+  preload() {}                     // 仅加载；正式项目优先 Boot 集中加载
+  create() {}                      // 对象、物理、输入绑定；接上 System
+  update(time: number, delta: number) {} // delta 单位 ms
+}
+```
+
+规则：
+
+- 资产在 `preload` / Boot，不在 `create` 里才开始 `load` 却立刻引用。
+- `update` **映射** System 结果并采样输入；核心规则在 System，避免「巨型 Scene 上帝类」。
+- 动画/精灵状态从 System 派生，不用随机 sprite flag 当真相。
+
+## 帧率无关运动
+
+Phaser `update` 的 `delta` 是**毫秒**：
+
+```ts
+// 正确
+this.viewX += speedPxPerSec * (delta / 1000);
+
+// 错误：跟帧率绑死
+this.viewX += speedPxPerSec;
+```
+
+物理体优先用 Arcade `setVelocity` / 加速度；手写位移必须乘 `delta/1000`。
+
+## 视口缩放（Scale Manager 唯一正道）
+
+**必须用 Phaser Scale Manager**；禁止用 CSS/`transform`/手写 `resize` 去缩放 canvas（会破坏坐标、输入与物理）。
+
+```ts
+const config: Phaser.Types.Core.GameConfig = {
+  type: Phaser.AUTO,
+  width: 720,
+  height: 1280,
+  scale: {
+    mode: Phaser.Scale.FIT,
+    autoCenter: Phaser.Scale.CENTER_BOTH,
+    parent: 'game-container',
+    width: 720,
+    height: 1280,
+  },
+  // physics / scene ...
+};
+```
+
+| 模式 | 何时用 |
+| --- | --- |
+| `FIT` | 默认：保比例，可能有边距 |
+| `ENVELOP` | 铺满裁切（需接受裁边） |
+| `RESIZE` | 布局随视口变（要自己重排世界/UI） |
+| `NONE` | 固定桌面尺寸 |
+
+响应：
+
+```ts
+this.scale.on('resize', (gameSize: Phaser.Structs.Size) => {
+  // 按需调相机 / 世界边界；正式 HUD 由 DOM 自己响应式
+});
+```
+
+### 反模式（禁止）
+
+```ts
+// 禁止
+canvas.style.width = '75%';
+canvas.style.transform = 'scale(0.75)';
+window.addEventListener('resize', () => { /* 手改 container 像素去「模拟」缩放 */ });
+```
+
+## 物理系统选型（早定）
+
+默认 **Arcade**；Matter 仅刚体/关节场景；菜单/卡牌可不启物理。选型、碰撞与对象池见 `engine-physics.md`。
+
+## 引擎反模式
+
+| 反模式 | 问题 | 做法 |
+| --- | --- | --- |
+| 手写 CSS 缩放 Canvas | 输入/物理错位 | Scale Manager |
+| 规则全写在 `update` | 难测、难复用 | System + Scene 映射 |
+| `window` 全局状态 | 切场景损坏 | registry / System |
+| 在 `create` 才 load 即用 | 资源未就绪 | Boot / preload |
+| 按帧计数当时间 | 掉帧变速 | `delta/1000` |
+| 简单碰撞上 Matter | 过重 | Arcade |
+| 正式 HUD 塞进 Scene 密文 | 难适配竖屏/安全区 | DOM 覆盖层 |
+| 魔法数 | 难调平衡 | `config.json` |
+| 子弹/敌人狂 create/destroy | GC 卡顿 | 对象池（见 physics / performance） |

package/skills/phaser-2d-game/references/engine-spritesheets.md

@@ -0,0 +1,99 @@
+# 引擎：Spritesheet 与图集
+
+**加载任何 spritesheet 之前先读本文件。** 帧尺寸差几像素会静默错位，后面全坏。
+
+正式 HUD 默认走 DOM（`game-ui`）；九宫格 Canvas 面板仅在确需世界内/像素风面板时使用。
+
+## 强制：先量再写 loader
+
+1. 打开图片，记下总宽高  
+2. 数清行列  
+3. 量一格真实宽高（像素尺）  
+4. 看格间是否有 gap → `spacing`  
+5. 看整图外圈是否有 padding → `margin`  
+6. 用公式验算必须整除  
+
+```text
+imageWidth  = frameWidth  × cols + spacing × (cols - 1) + margin × 2
+imageHeight = frameHeight × rows + spacing × (rows - 1) + margin × 2
+```
+
+### 角色帧优先试正方形
+
+算出 `frameWidth` 后，**先试 `frameHeight = frameWidth`**，再看高度能否整除。不要一上来就按「行列数相同」瞎除。
+
+### 不同动画可能不同帧尺寸
+
+同一角色的 idle / run / attack 常常 **各自一张 sheet、各自 frame 尺寸**（跑姿更宽、挥砍更宽）。**每张独立测量**，禁止把 idle 的 fw/fh 复制到 attack。
+
+## Loader 示例
+
+```ts
+this.load.spritesheet('player-idle', urlFromManifest, {
+  frameWidth: 64,
+  frameHeight: 64,
+});
+
+this.load.spritesheet('ui-wood', url, {
+  frameWidth: 144,
+  frameHeight: 144,
+  spacing: 8,
+});
+
+this.load.spritesheet('icons', url, {
+  frameWidth: 32,
+  frameHeight: 32,
+  margin: 4,
+  spacing: 2,
+});
+```
+
+资产 URL 走 manifest / `config.json`，不在业务里硬编码散落路径。
+
+## 红旗
+
+- 宽或高无法被帧数整除 / 算出小数  
+- 目测有缝但没写 `spacing`（第一帧对、后面全歪）  
+- 角色动画硬用不方形帧却未验证  
+- 假设行列数相同  
+
+## 调试：先摊开看帧
+
+```ts
+for (let i = 0; i < frameCount; i++) {
+  const col = i % 3;
+  const row = Math.floor(i / 3);
+  this.add.image(100 + col * 120, 100 + row * 120, key, i);
+  this.add.text(100 + col * 120, 150 + row * 120, String(i)).setOrigin(0.5);
+}
+```
+
+单帧就错 → 先修 loader，再进玩法。多动画角色可用临时 AnimTest Scene / `?debug=anims` 左右键切换验证。
+
+## Texture Atlas
+
+多精灵合并图集，减 draw call 与请求：
+
+```ts
+this.load.atlas('sprites', atlasPngUrl, atlasJsonUrl);
+this.add.sprite(x, y, 'sprites', 'player-idle-1');
+this.anims.create({
+  key: 'walk',
+  frames: this.anims.generateFrameNames('sprites', {
+    prefix: 'player-walk-',
+    start: 1,
+    end: 8,
+    zeroPad: 2,
+  }),
+  frameRate: 10,
+  repeat: -1,
+});
+```
+
+## 九宫 / 三截条（仅 Canvas UI 需要时）
+
+- 3×3：角不拉伸，边单轴拉，中心双轴拉；透明边需底色与 overlap 防缝。  
+- 丝带/横幅常是 **左帽 + 中段 + 右帽**，不要整图拉伸。  
+- 参数按资产配置，不写死一套。  
+
+世界内装饰可用；**主菜单/设置/复杂 HUD 仍优先 DOM**。

package/skills/phaser-2d-game/references/engine-tilemaps.md

@@ -0,0 +1,80 @@
+# 引擎：Tilemap（Tiled → Phaser）
+
+横版/俯视用地图、碰撞层、物件层刷怪时加载。
+
+## Tiled 层建议（自上而下）
+
+```text
+Foreground   # 盖住玩家的装饰
+Objects      # 出生点、敌人、拾取、触发（Object Layer）
+Ground       # 主碰撞 Tile Layer
+Background   # 无碰撞装饰 / 视差
+```
+
+导出 **JSON**（推荐）。Tileset 注意 `margin` / `spacing`；防渗色可用 extruded tileset。
+
+## 加载与创建
+
+```ts
+// preload / Boot
+this.load.tilemapTiledJSON('level1', mapUrl);
+this.load.image('tiles', tilesetUrl);
+
+// create
+const map = this.make.tilemap({ key: 'level1' });
+const tileset = map.addTilesetImage('terrain', 'tiles'); // 名称对齐 Tiled
+const ground = map.createLayer('Ground', tileset, 0, 0);
+const fg = map.createLayer('Foreground', tileset, 0, 0);
+
+ground?.setCollisionByProperty({ collides: true });
+// 或 setCollisionByExclusion([-1]) / 按 index
+
+this.physics.add.collider(player, ground!);
+this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
+this.physics.world.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
+```
+
+多 tileset：每个 `addTilesetImage`，`createLayer` 可传数组。
+
+## GID 要点
+
+- `0` = 空  
+- 多 tileset 靠 `firstgid`；本地 id = `gid - firstgid`  
+- 翻转存在高位 flag；手工解析时先清 `0xF0000000`  
+
+一般优先用 Phaser API，少手撕 GID。
+
+## 物件层刷实体
+
+```ts
+const objs = map.getObjectLayer('Objects');
+objs?.objects.forEach((obj) => {
+  if (obj.type === 'spawn' || obj.name === 'player') {
+    // 交给 System 设逻辑位，Scene 只生成视图
+  }
+  if (obj.type === 'coin') {
+    // overlap 组 / 池
+  }
+});
+```
+
+Tiled 自定义属性映射到 config / content 数据，避免在 Scene 写死关卡数值。
+
+## 视差
+
+层在 Tiled 设 `parallaxx` / `parallaxy`，或 Phaser 侧 `setScrollFactor`。远景 factor < 1。
+
+## 常见坑
+
+| 现象 | 处理 |
+| --- | --- |
+| 缝隙渗色 | tileset extrude；检查 spacing/margin |
+| 碰撞对不齐 | 确认 layer 名、tileset 名、缩放后 `setCollision*` |
+| 物件坐标偏 | 注意 Tiled 原点与 Phaser origin；tile object vs point |
+| CSV 图 | 必须在 `make.tilemap` 声明 tileWidth/Height；优先 JSON |
+
+## 与本规范
+
+- 地图 JSON / 图块 URL 进 manifest 或 config，不写死多处路径。  
+- 碰撞结果 → System 事件；Scene 不持关卡进度真相。  
+- 大地图注意相机 bounds 与世界 bounds 一致。