games-development-ai/.agents/skills/recipes/hit-rect.md

recipe: 命中矩形（按钮点不动的头号根治）

要做：菜单的「开始」、结算的「重来」、玩中的可点区——点了要真响应。

病根九成在这：命中矩形只在 render 的副作用里生成（menuStartBtn = renderMenu(...) 那种回写）。并发渲染帧饥饿时 render 可能一次都没跑过 → 命中矩形恒 null → 点了没反应 → 卡在菜单一局起不来。这是「卡 menu」的头号成因。

根治口诀：按钮几何抽成纯函数，场景 onEnter（状态进入点）确定性建立命中区，render 只画不赋值——同一来源，不漂移。

抄这段形态：

// 纯函数：按钮几何只算一次的来源（onEnter 与 render 都调它，值一致）
function menuStartRect(viewport) {
  return { x: viewport.w / 2 - 90, y: 520, w: 180, h: 64 };
}

sceneFsm.define('menu', {
  onEnter() { this.startRect = menuStartRect(viewport); },   // ★命中区在这里建，不在 render
  render(g) {
    const btn = hudUi.drawButton(g, this.startRect, { label: '开始' }); // drawButton 回吐命中矩形
    // 也可直接 hudUi.drawButton(g, menuStartRect(viewport), {label:'开始'})——同源即可
  },
});

// 输入：只写实例方法 handleTap，L1 在 pointerdown 时直达调用它（别自己订阅输入）
handleTap(x, y) {
  if (sceneFsm.current() === 'menu' && hudUi.pointInRect(x, y, this.startRect)) {
    sceneFsm.transition('play');   // 命中 → 起局
  }
}

别踩：

• drawButton(g, rect, opts) 第二参是 rect 对象 {x,y,w,h}，不是 label/坐标位置参——别写 drawButton(g, '开始', x, y, w, h)。
• 命中判定只有 hudUi.pointInRect(px, py, rect)（collision 插件没有 pointInRect）。
• 输入不写 ctx.getInput、不自建 pendingClicks 队列——只暴露 handleTap(x,y)/handleKey(key)。