axiom-spritekit-diag

SpriteKit Diagnostics

Systematic diagnosis for common SpriteKit issues with time-cost annotations.

When to Use This Diagnostic Skill

Use this skill when:

• Physics contacts never fire (didBegin not called)
• Objects pass through walls (tunneling)
• Frame rate drops below 60fps
• Touches don't register on nodes
• Memory grows continuously during gameplay
• Positions and coordinates seem wrong
• App crashes during scene transitions

Mandatory First Step: Enable Debug Overlays

Time cost: 10 seconds setup vs hours of blind debugging

if let view = self.view as? SKView {
    view.showsFPS = true
    view.showsNodeCount = true
    view.showsDrawCount = true
    view.showsPhysics = true
}

If showsPhysics doesn't show expected physics body outlines, your physics bodies aren't configured correctly. Stop and fix bodies before debugging contacts.

For SpriteKit architecture patterns and best practices, see axiom-spritekit. For API reference, see axiom-spritekit-ref.

---

Symptom 1: Physics Contacts Not Firing

Time saved: 30-120 min → 2-5 min

didBegin(_:) never called
│
├─ Is physicsWorld.contactDelegate set?
│   └─ NO → Set in didMove(to:):
│        physicsWorld.contactDelegate = self
│        ✓ This alone fixes ~30% of contact issues
│
├─ Does the class conform to SKPhysicsContactDelegate?
│   └─ NO → Add conformance:
│        class GameScene: SKScene, SKPhysicsContactDelegate
│
├─ Does body A have contactTestBitMask that includes body B's category?
│   ├─ Print: "A contact: \(bodyA.contactTestBitMask), B cat: \(bodyB.categoryBitMask)"
│   ├─ Result should be: (A.contactTestBitMask & B.categoryBitMask) != 0
│   └─ FIX: Set contactTestBitMask to include the other body's category
│        player.physicsBody?.contactTestBitMask = PhysicsCategory.enemy
│
├─ Is categoryBitMask set (not default 0xFFFFFFFF)?
│   ├─ Default category means everything matches — but in unexpected ways
│   └─ FIX: Always set explicit categoryBitMask for each body type
│
├─ Do the bodies actually overlap? (Check showsPhysics)
│   ├─ Bodies too small or offset from sprite → Fix physics body size
│   └─ Bodies never reach each other → Check collisionBitMask isn't blocking
│
└─ Are you modifying the world inside didBegin?
    ├─ Removing nodes inside didBegin can cause missed callbacks
    └─ FIX: Flag nodes for removal, process in update(_:)