axiom-ios-games

iOS 游戏路由器

任何游戏开发、SpriteKit、SceneKit、RealityKit 或交互式模拟工作都必须使用此技能。

使用时机

在以下情况下使用此路由器：

• 构建新的 SpriteKit 游戏或原型（2D）
• 使用 SceneKit 或 RealityKit 构建 3D 游戏
• 实现物理效果（碰撞、接触、力、关节）
• 搭建游戏架构（场景、图层、摄像机、ECS）
• 调试 SpriteKit、SceneKit 或 RealityKit 问题
• 优化游戏性能（绘制调用、节点数量、实体数量、批处理）
• 管理游戏循环、增量时间或暂停处理
• 在游戏场景中实现触摸/输入处理
• 将 SpriteKit 或 RealityKit 与 SwiftUI 集成
• 使用粒子效果、纹理图集或 3D 模型
• 查询 SpriteKit、SceneKit 或 RealityKit API 详情
• 从 SceneKit 迁移到 RealityKit
• 使用 RealityKit 构建 AR 游戏

路由逻辑

SpriteKit（2D）

架构、模式和最佳实践 → /skill axiom-spritekit

• 场景图模型、坐标系、锚点
• 物理引擎：位掩码规范、接触检测、物体类型
• 动作系统：排序、分组、命名动作、计时
• 输入处理：触摸、坐标转换
• 性能：绘制调用、批处理、对象池、SKShapeNode 陷阱
• 游戏循环：帧周期、增量时间、暂停处理
• 场景过渡和数据传递
• SwiftUI 集成（SpriteView、UIViewRepresentable）
• Metal 集成（SKRenderer）
• 反模式和代码审查清单
• 含应对话术的压力场景

API 参考和查询 → /skill axiom-spritekit-ref

• 全部 16 种节点类型及其属性和性能说明
• SKPhysicsBody 的创建方法和属性
• 完整的 SKAction 目录（移动、旋转、缩放、淡化、组合、物理）
• 纹理和图集管理
• SKConstraint 类型和 SKRange
• SKView 配置和缩放模式
• SKEmitterNode 属性和预设
• SKRenderer 设置和 SKShader 语法

故障排除和诊断 → /skill axiom-spritekit-diag

• 物理接触未触发（6 分支决策树）
• 物体穿透墙壁（5 分支）
• 帧率低（4 个主要分支，12 个末端节点）
• 触摸未注册（6 分支）
• 内存激增和崩溃（5 分支）
• 坐标混淆（5 分支）
• 场景过渡崩溃（5 分支）

自动扫描 → 启动 spritekit-auditor Agent 或使用 /axiom:audit spritekit（检查物理位掩码、绘制调用浪费、节点累积、动作内存泄漏、坐标混淆、触摸处理、缺少对象池、缺少调试叠加层）

SceneKit（3D — 已弃用）

自 iOS 26 起，SceneKit 已软弃用。 仅用于维护现有代码。新的 3D 项目应使用 RealityKit。

维护和迁移规划 → /skill axiom-scenekit

• 场景图架构、坐标系、变换
• 渲染：SCNView、SceneView（已弃用）、SCNViewRepresentable
• 几何体、PBR 材质、着色器修饰符
• 光照、动画（SCNAction、SCNTransaction、CAAnimation 桥接）
• 物理：物体、碰撞类别、接触代理
• 资源管线：Model I/O、USD/DAE/SCN 格式
• ARKit 集成（旧版 ARSCNView）
• 迁移决策树（何时迁移与何时维护）
• 反模式和压力场景

API 参考和迁移映射 → /skill axiom-scenekit-ref

• 完整的 SceneKit → RealityKit 概念映射表
• 场景图 API：SCNScene、SCNNode、SCNGeometry
• 材质：光照模型、PBR 属性、着色器修饰符
• 光照：所有光源类型及其属性
• 摄像机：SCNCamera 属性
• 物理：物体类型、形状、关节
• 动画：SCNAction 目录、计时函数
• 约束：所有约束类型

RealityKit（3D — 现代）

对于非游戏类 3D 内容展示（产品查看器、AR 试穿、空间计算），ios-graphics 路由器也会路由到这些 RealityKit 技能。

架构、ECS 和最佳实践 → /skill axiom-realitykit

• Entity-Component-System 心智模型与范式转变
• Entity 层级结构、变换、世界空间查询
• 内置和自定义组件、组件生命周期
• System 协议、更新顺序、事件处理
• SwiftUI 集成：RealityView、Model3D、附件
• iOS 上的 AR：AnchorEntity 类型、SpatialTrackingSession
• 交互：ManipulationComponent、手势、命中测试
• 材质：SimpleMaterial、PBR、Unlit、Occlusion、ShaderGraph、Custom
• 物理：碰撞形状、组/筛选器、事件、力
• 动画：变换、USD 播放、播放控制
• 音频：空间音频、环境音频、通道
• 性能：实例化、组件频繁变更、形状优化
• 多人游戏：同步、所有权
• 反模式和代码审查清单
• 压力场景

API 参考与查找 → /skill axiom-realitykit-ref

• Entity API：属性、层级结构、子类
• 完整组件目录及所有属性
• MeshResource 生成器
• ShapeResource 类型与性能
• System 协议和 EntityQuery
• 场景事件目录
• RealityView API：初始化器、内容、手势
• Model3D API
• 材质系统：所有类型及完整属性列表
• 动画计时函数和播放控制
• 音频组件和播放
• RealityRenderer（Metal 集成）

故障排查与诊断 → /skill axiom-realitykit-diag

• Entity 不可见（8 分支决策树）
• Anchor 未跟踪（6 分支）
• 手势无响应（6 分支）
• 性能问题（7 分支）
• 材质显示异常（6 分支）
• 物理效果无效（6 分支）
• 多人同步问题（5 分支）

决策树

1. 正在构建/设计 2D SpriteKit 游戏？→ axiom-spritekit
2. 如何使用特定的 SpriteKit API？→ axiom-spritekit-ref
3. SpriteKit 出故障或性能不佳？→ axiom-spritekit-diag
4. 维护现有的 SceneKit 代码？→ axiom-scenekit
5. SceneKit API 参考或迁移映射？→ axiom-scenekit-ref
6. 正在构建新的 3D 游戏或体验？→ axiom-realitykit
7. 如何使用特定的 RealityKit API？→ axiom-realitykit-ref
8. RealityKit Entity 不可见、手势失效或性能不佳？→ axiom-realitykit-diag
9. 将 SceneKit 迁移到 RealityKit？→ axiom-scenekit（迁移树）+ axiom-scenekit-ref（映射表）
10. 正在构建 AR 游戏？→ axiom-realitykit
11. 物理接触无效（SpriteKit）？→ axiom-spritekit-diag（症状 1）
12. 帧率下降（SpriteKit）？→ axiom-spritekit-diag（症状 3）
13. 坐标/位置混淆（SpriteKit）？→ axiom-spritekit-diag（症状 6）
14. 需要完整的动作列表？→ axiom-spritekit-ref（第 3 部分）
15. 物理体设置参考？→ axiom-spritekit-ref（第 2 部分）
16. Entity 不可见（RealityKit）？→ axiom-realitykit-diag（症状 1）
17. 手势无响应（RealityKit）？→ axiom-realitykit-diag（症状 3）
18. 想要自动扫描 SpriteKit 代码？→ spritekit-auditor（Agent）

反合理化

想法	现实
“SpriteKit 很简单，我不需要技能”	物理位掩码默认值为 0xFFFFFFFF，会导致幽灵碰撞。位掩码检查清单可在 2 分钟内发现这个问题。
“我直接用 SKShapeNode 就行，很快”	每个 SKShapeNode 都是一次单独的绘制调用。50 个就是 50 次绘制调用。axiom-spritekit 提供了预渲染到纹理的模式。
“我可以自己弄清坐标系”	SpriteKit 使用左下角原点（与 UIKit 相反）。锚点又增加了一层复杂性。axiom-spritekit-diag 症状 6 可在 5 分钟内解决问题。
“物理很简单”	有三种不同的位掩码属性、回调中的修改规则，还有隧穿边缘情况。axiom-spritekit 第 3 节涵盖了所有易错点。
“我的设备上性能没问题”	不同设备的性能差异很大。axiom-spritekit 第 6 节提供了调试叠加层检查清单。
“我们的新项目用 SceneKit 没问题”	SceneKit 在 iOS 26 中已被软弃用。不再添加新功能，只提供安全补丁。axiom-scenekit 提供了迁移决策树。
“我以后再学 RealityKit”	SceneKit 的每一行代码都是迁移负担。axiom-scenekit-ref 提供了概念映射表，让迁移具体可行，而非流于抽象。
“对于简单的 3D 应用，ECS 有点过度设计”	你已经在使用 ECS 了——Entity + ModelComponent。axiom-realitykit 展示了如何从简单扩展到复杂。
“点击操作不需要碰撞形状”	RealityKit 手势需要 CollisionComponent。axiom-realitykit-diag 可在 2 分钟内诊断问题，而不是花 30 分钟猜测。
“我直接用 Timer 更新游戏就行”	基于 Timer 的更新会漏掉帧，且无法与渲染同步。axiom-realitykit 提供了 System 模式。

关键模式

axiom-spritekit：

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

axiom-spritekit-ref：

• 完整的节点类型表（16 种类型及其批处理行为）
• 物理体创建方法（圆形开销最低，纹理开销最高）
• 包含组合模式的完整动作目录
• SKView 调试叠加层和缩放模式矩阵

axiom-spritekit-diag：

• 5 步位掩码检查清单（2 分钟，避免 30–120 分钟的猜测）
• 将调试叠加层作为强制的首要诊断步骤
• 防止隧穿流程图
• 通过 showsNodeCount 趋势诊断内存增长

axiom-scenekit：

• 迁移决策树（新项目 → RealityKit，现有项目 → 维护或迁移）
• 迁移前转换 USDZ 资源（xcrun scntool）
• SceneView 弃用及以 SCNViewRepresentable 替代
• 针对“直接用 SceneKit 就行”这一合理化说法的压力场景

axiom-scenekit-ref：

• 完整的 SceneKit → RealityKit 概念映射表
• 所有材质光照模型和属性
• 完整的约束目录

axiom-realitykit：

• ECS 思维转变表（从场景图思维转向 ECS 思维）
• 自定义组件注册（registerComponent()）
• 组件更新的读-改-写模式
• 所有交互都需要 CollisionComponent
• 使用基于 System 的更新，而非计时器

axiom-realitykit-ref：

• 包含所有属性的完整组件目录
• MeshResource 生成器和 ShapeResource 类型
• 场景事件目录
• 包含所有 PBR 属性的材质系统

axiom-realitykit-diag：

• Entity 可见性检查清单（8 个分支，2–5 分钟，避免 30–60 分钟的排查）
• 手势调试（首先检查 CollisionComponent）
• 性能诊断（实体数量、资源共享、组件频繁变更）
• 物理约束：实体必须共享同一个锚点

示例调用

用户：“我正在构建一款 SpriteKit 游戏” → 调用：/skill axiom-spritekit

用户：“我的物理接触事件没有触发” → 调用：/skill axiom-spritekit-diag

用户：“如何根据纹理创建物理体？” → 调用：/skill axiom-spritekit-ref

用户：“我的游戏帧率正在下降” → 调用：/skill axiom-spritekit-diag

用户：“如何将 SpriteKit 与 SwiftUI 配合使用？” → 调用：/skill axiom-spritekit

用户：“有哪些可用的动作类型？” → 调用：/skill axiom-spritekit-ref

用户：“物体会穿过墙壁” → 调用：/skill axiom-spritekit-diag

用户：“我需要构建一款 3D 游戏” → 调用：/skill axiom-realitykit

用户：“如何将 3D 模型添加到我的 SwiftUI 应用中？” → 调用：/skill axiom-realitykit

用户：“我的 RealityKit 实体没有显示” → 调用：/skill axiom-realitykit-diag

用户：“如何在 RealityKit 中设置物理效果？” → 调用：/skill axiom-realitykit-ref

用户：“我正在从 SceneKit 迁移到 RealityKit” → 调用：/skill axiom-scenekit + /skill axiom-scenekit-ref

用户：“SCNNode 在 RealityKit 中对应什么？” → 调用：/skill axiom-scenekit-ref

用户：“我的新 3D 项目应该使用 SceneKit 吗？” → 调用：/skill axiom-scenekit

用户：“RealityKit 实体上的轻点手势不起作用” → 调用：/skill axiom-realitykit-diag

用户：“如何在 RealityKit 中设置 ECS？” → 调用：/skill axiom-realitykit

用户：“我的 AR 内容无法跟踪” → 调用：/skill axiom-realitykit-diag

用户：“RealityKit 中有哪些材质可用？” → 调用：/skill axiom-realitykit-ref

用户：“如何在 RealityKit 中为实体添加动画？” → 调用：/skill axiom-realitykit-ref

用户：“游戏过程中内存持续增长” → 调用：/skill axiom-spritekit-diag

用户：“火焰效果应该使用哪些粒子发射器设置？” → 调用：/skill axiom-spritekit-ref

用户：“可以扫描我的 SpriteKit 代码，检查常见问题吗？” → 调用：spritekit-auditor agent