axiom-games

游戏

任何游戏开发、SpriteKit、SceneKit、RealityKit、触控操作、游戏控制器或交互式模拟相关工作，都必须使用此技能。

无法启动 Axiom Agent？ 如果此路由将你引导至某个 Agent，请直接按其流程操作。通过 MCP，axiom_get_agent 会返回该 Agent；在其他环境中，请阅读下方的文件，它只需要文件搜索和读取功能。

此处可用：skills/spritekit-auditor.md。

对于其他 Agent，通过 MCP，axiom_get_agent 也会返回它；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具运行其 xclog、xcsym 和 xcprof 步骤。在其他环境中，请在 Axiom 的技能中搜索 skills/<agent>.md；如果没有，请使用此套件的技能自行完成相关工作，并使用 PATH 中的任意 Axiom 工具。

快速参考

症状 / 任务	参考
构建 SpriteKit 游戏	参见 skills/spritekit.md
为游戏添加触控操作（TouchController）	参见 skills/game-input.md
游戏控制器输入（GCController、轮询与处理程序）	参见 skills/game-input.md
控制器 Home 按钮设置、空间配件 OS27	参见 skills/game-input.md
游戏窗口大小调整、方向锁定、UIRequiresFullScreen OS27	参见 axiom-uikit（skills/uikit-modernization.md）
SpriteKit API 查询	参见 skills/spritekit-ref.md
物理接触未触发	参见 skills/spritekit-diag.md
帧率下降（SpriteKit）	参见 skills/spritekit-diag.md
触控未注册	参见 skills/spritekit-diag.md
游戏过程中内存激增	参见 skills/spritekit-diag.md
坐标混淆	参见 skills/spritekit-diag.md
场景转换崩溃	参见 skills/spritekit-diag.md
对象穿过墙壁	参见 skills/spritekit-diag.md
SpriteKit 节点 / 操作参考	参见 skills/spritekit-ref.md
SceneKit 维护 / 迁移	参见 axiom-graphics（skills/scenekit.md）
SceneKit API / 迁移映射	参见 axiom-graphics（skills/scenekit-ref.md）
RealityKit（3D、ECS、AR）	参见 axiom-graphics（skills/realitykit.md）
RealityKit API 参考	参见 axiom-graphics（skills/realitykit-ref.md）
RealityKit 诊断	参见 axiom-graphics（skills/realitykit-diag.md）
RealityKit 27 游戏功能（导航网格、LOD、点云）	参见 axiom-graphics（skills/realitykit-ref.md Part 10）
长时间游戏会话性能跟踪（metalperftrace）	参见 axiom-graphics（skills/display-performance.md Part 12）
将 Mac/Windows 游戏移植到 Metal	参见 axiom-graphics（skills/metal-migration.md）
游戏内内容、素材包、IAP	参见 axiom-integration（skills/background-assets.md、skills/in-app-purchases.md）

外部路由

这些主题属于更广泛的游戏/3D 领域，但位于单独的技能套件中：

SceneKit（3D — iOS 26 中已软弃用）：

• 维护和迁移规划 → 参见 axiom-graphics（skills/scenekit.md）
• API 参考和迁移映射 → 参见 axiom-graphics（skills/scenekit-ref.md）

RealityKit（3D — 现代）：

• ECS 架构、AR、SwiftUI 集成 → 参见 axiom-graphics（skills/realitykit.md）
• API 参考 → 参见 axiom-graphics（skills/realitykit-ref.md）
• 故障排查 → 参见 axiom-graphics（skills/realitykit-diag.md）
• 27 周期游戏引擎层：导航网格 + 寻路、行为树、动画图、LOD、Gaussian splats → 参见 axiom-graphics（skills/realitykit-ref.md Part 10）

游戏性能和移植：

• 长时间运行的游戏跟踪、metalperftrace CLI、Game Performance Overview 模板 → 参见 axiom-graphics（skills/display-performance.md Part 12）
• Metal 迁移、着色器转换 → 参见 axiom-graphics（skills/metal-migration.md）

游戏内内容和变现：

• Apple-Hosted Background Assets、资源包、Steam depot 转换 → 参见 axiom-integration（skills/background-assets.md）
• App 内购买、StoreKit 视图 → 参见 axiom-integration（skills/in-app-purchases.md）

窗口和方向（OS27）：

• 所有应用在 27 中都可调整大小，包括 iPhone。UIRequiresFullScreen 现在表示游戏采用离散的吸附式调整大小（而非退出全屏）；方向锁定是一项偏好设置；通过 sizeRestrictions 设置最小尺寸 → 参见 axiom-uikit（skills/uikit-modernization.md）
• 游戏在 iPhone Mirroring 中运行：触控板/鼠标输入会以间接事件的形式传递给自定义手势，且场景始终报告为纵向 → 参见 axiom-uikit（skills/uikit-modernization.md）
• 实时调整大小期间的 Metal drawable 尺寸设定、渲染目标重新分配和质量限制 → 参见 axiom-graphics（skills/resizable-rendering.md）

决策树

digraph games {
    start [label="Game development" shape=ellipse];
    what [label="Which framework?" shape=diamond];
    sprite_what [label="SpriteKit need?" shape=diamond];

    start -> what;
    what -> sprite_what [label="SpriteKit (2D)"];
    what -> "skills/game-input.md" [label="touch controls / game controllers"];
    what -> "axiom-graphics/scenekit" [label="SceneKit (3D legacy)"];
    what -> "axiom-graphics/realitykit" [label="RealityKit (3D modern)"];
    what -> "axiom-graphics/metal-migration" [label="porting (Metal)"];

    sprite_what -> "skills/spritekit.md" [label="architecture/patterns"];
    sprite_what -> "skills/spritekit-ref.md" [label="API lookup"];
    sprite_what -> "skills/spritekit-diag.md" [label="broken/slow"];
}

1. 正在构建/设计 2D SpriteKit 游戏？→ skills/spritekit.md
2. 如何使用特定的 SpriteKit API？→ skills/spritekit-ref.md
3. SpriteKit 出现故障或性能不佳？→ skills/spritekit-diag.md
4. 正在添加触控控制，或处理游戏控制器输入？→ skills/game-input.md
5. 正在维护现有的 SceneKit 代码？→ 参见 axiom-graphics（skills/scenekit.md）
6. 需要 SceneKit API 参考或迁移映射？→ 参见 axiom-graphics（skills/scenekit-ref.md）
7. 正在构建新的 3D 游戏或体验？→ 参见 axiom-graphics（skills/realitykit.md）
8. 如何使用特定的 RealityKit API？→ 参见 axiom-graphics（skills/realitykit-ref.md）
9. RealityKit 实体不可见、手势失效或性能有问题？→ 参见 axiom-graphics（skills/realitykit-diag.md）
10. 正在将 SceneKit 迁移到 RealityKit？→ 参见 axiom-graphics（skills/scenekit.md）（迁移树）+ 参见 axiom-graphics（skills/scenekit-ref.md）（映射表）
11. 正在构建 AR 游戏？→ 参见 axiom-graphics（skills/realitykit.md）
12. 正在将 Mac/Windows 游戏移植到 Apple 平台？→ 参见 axiom-graphics（skills/metal-migration.md）
13. 正在解锁游戏内内容（资源包、IAP）？→ 参见 axiom-integration（skills/background-assets.md，skills/in-app-purchases.md）
14. 游戏需要全屏/方向锁定，或窗口调整大小时出现故障？→ 参见 axiom-uikit（skills/uikit-modernization.md）
15. 想自动扫描 SpriteKit 代码？→ spritekit-auditor agent

自动扫描

SpriteKit 审计 → 启动 spritekit-auditor Agent 或运行 /axiom:audit spritekit

检测反模式和架构缺陷：

• 物理位掩码问题（默认值 0xFFFFFFFF、缺少 contactTestBitMask、魔法数字）
• 绘制调用浪费（游戏过程中使用 SKShapeNode、缺少纹理图集）
• 节点不断累积，以及在 update() 中不断生成对象却不清理
• 动作内存泄漏（强引用 self、.repeatForever 未使用 withKey:）
• 坐标混淆（使用 touch.location(in: self.view)，而不是 in: self）
• 输入无响应区域无提示（自定义 touchesBegan 却未设置 isUserInteractionEnabled）
• 高频对象生成缺少对象池
• 缺少调试覆盖层，或未对其进行门控
• 场景泄漏（过渡时未调用 removeAllActions() 和清理子节点）
• 缺少时间步长限制 → 死亡螺旋会导致物理体穿墙传送
• HUD 附加到场景根节点而非摄像机（会随滚动漂移）
• 快速移动的物理体未启用 usesPreciseCollisionDetection（导致穿透）

评分：性能良好 / 性能下降 / 无法游玩

关键模式

SpriteKit（skills/spritekit.md）：

• 使用带显式位掩码的 PhysicsCategory 结构体（默认值 0xFFFFFFFF 会导致异常碰撞）
• 使用摄像机节点模式分离视口和 HUD
• 将 SKShapeNode 预渲染并转换为纹理
• 在所有 SKAction.run 闭包中使用 [weak self]
• 使用 Delta 时间并限制死亡螺旋

SpriteKit 诊断（skills/spritekit-diag.md）：

• 5 步位掩码检查清单（耗时 2 分钟，而非盲目猜测 30–120 分钟）
• 将调试覆盖层作为首要诊断步骤
• 穿透防护流程图
• 通过 showsNodeCount 趋势诊断内存增长

游戏输入（skills/game-input.md）：

• 采用单一 GCController 管线——触控控制以 GCController 的形式呈现，现有逻辑保持不变
• 设置 TCTouchController.isSupported 门控，并配置连接、渲染和触控路由
• 为移动和摄像机使用半屏碰撞器形状（切勿使用小圆形）
• 为全屏游戏设置适配安全区域的锚点偏移
• 使用 GCMouse 增量进行视角移动/瞄准，使用 GCKeyboard 键状态（iPad 指针、iPhone 镜像）
• 控制器 Home 按钮设置，以及 visionOS 空间配件 OS27

反合理化

想法	现实
“SpriteKit 很简单，我不需要技能”	物理位掩码默认值为 0xFFFFFFFF，会导致虚假碰撞。位掩码检查清单可在 2 min 内发现这个问题。
“我直接用 SKShapeNode 就行，很快”	每个 SKShapeNode 都是一次单独的绘制调用。50 个就有 50 次绘制调用。spritekit.md 提供了预渲染到纹理的模式。
“我能搞清楚坐标系”	SpriteKit 使用左下角原点（与 UIKit 相反）。锚点又增加了一层复杂性。spritekit-diag.md 的症状 6 可在 5 min 内解决问题。
“物理很简单”	有三种不同的位掩码属性、回调中的修改规则，以及隧穿边缘情况。spritekit.md 第 3 节涵盖了所有易踩的坑。
“我的设备上性能不错”	不同设备上的性能差异很大。spritekit.md 第 6 节提供了调试叠加层检查清单。
“新项目用 SceneKit 没问题”	SceneKit 在 iOS 26 中已软弃用。不再添加新功能，只提供安全补丁。axiom-graphics (skills/scenekit.md) 提供了迁移决策树。
“简单的 3D 应用用 ECS 太复杂了”	你已经在使用 ECS——Entity + ModelComponent。axiom-graphics (skills/realitykit.md) 展示了如何从简单扩展到复杂。
“点击不需要碰撞形状”	RealityKit 手势需要 CollisionComponent。axiom-graphics (skills/realitykit-diag.md) 可在 2 min 内诊断这个问题，而不是花 30 min 碰运气。
“我会叠加 UIButton 来实现触控”	TouchController 在你的 Metal 渲染过程中绘制，并以 GCController 的形式提供，因此现有的控制器逻辑可直接使用。叠加 UIButton 意味着需要第二条输入路径，还会带来每帧的 UIKit 开销。game-input.md 第 2 节。
“触控控制 = 把控制器上的每个按钮都放到屏幕上”	一对一映射会挤占游戏区域，还要求同时使用 3 根以上手指。game-input.md 第 5 节提供了重新设计模式（情境图标、隐藏未使用的按钮、折叠组合操作）。
“游戏都是全屏的——我用不上调整窗口大小”	到 27 时，所有应用都可以调整窗口大小，包括 iPhone。UIRequiresFullScreen 只会让游戏以离散步进调整大小，而不是固定画布。axiom-uikit (skills/uikit-modernization.md) 提供了场景几何和最小尺寸模式。

示例调用

用户：“我正在制作一款 SpriteKit 游戏” → 查看 skills/spritekit.md

用户：“我的物理接触没有触发” → 查看 skills/spritekit-diag.md

用户：“如何根据纹理创建物理实体？” → 查看 skills/spritekit-ref.md

用户：“我的游戏帧率在下降” → 查看 skills/spritekit-diag.md

用户：“有哪些可用的动作类型？” → 查看 skills/spritekit-ref.md

用户：“物体会穿过墙壁” → 查看 skills/spritekit-diag.md

用户：“我正在把控制器游戏移植到 iPhone，需要触控控制” → 查看 skills/game-input.md

用户：“如何处理游戏控制器输入？” → 查看 skills/game-input.md

用户：“如何读取 visionOS 上空间配件的输入？” → 查看 skills/game-input.md

用户：“窗口大小调整后，我的游戏布局就乱了” → 查看 axiom-uikit (skills/uikit-modernization.md)

用户：“我需要制作一款 3D 游戏” → 调用：查看 axiom-graphics (skills/realitykit.md)

用户：“我正在从 SceneKit 迁移到 RealityKit” → 调用：查看 axiom-graphics (skills/scenekit.md) + 查看 axiom-graphics (skills/scenekit-ref.md)

用户：“你能帮我扫描 SpriteKit 代码中的常见问题吗？” → 启动 spritekit-auditor Agent