CommunityProgramación y desarrollogithub.com

spritekit

Skill de codificación. Crea juegos 2D para iOS con SpriteKit alojado en SwiftUI (iOS 26+, Swift 6): escenas, bucle de fotogramas, acciones, física, cámaras, mapas de teselas, partículas, shaders, iluminación y rendimiento de llamadas de dibujo. Úsalo al escribir o depurar código SpriteKit (SKScene, SKNode, SpriteView) o cuando un juego 2D se renderice lento o se vea mal.

¿Qué es spritekit?

Este skill proporciona una guía completa para desarrollar juegos 2D en iOS utilizando SpriteKit integrado con SwiftUI, específicamente optimizado para iOS 26 y Swift 6. Explica cómo alojar correctamente una escena SpriteKit en una SwiftUI SpriteView, ajustando opciones críticas como preferredFramesPerSecond a 120 y activando ignoresSiblingOrder para un orden de dibujo predecible. Aborda la concurrencia de Swift 6, haciendo que las clases que implementan SKPhysicsContactDelegate sean explícitamente @MainActor para evitar errores de compilación. Detalla el bucle de fotogramas de SpriteKit, el cálculo manual del delta de tiempo (dt) con límite para evitar saltos tras pausas, y la mutación segura de cuerpos físicos en didSimulatePhysics. Incluye una plantilla de escena completa con cámara, jugador, detección de colisiones y manejo de eliminaciones pendientes. También cubre componentes clave como SKCameraNode, SKAction, SKPhysicsBody, SKTileMapNode y SKEmitterNode, con consejos de rendimiento sobre batching de texturas, el uso moderado de SKEffectNode y SKCropNode, y la creación de SKShapeNode para depuración. Advierte sobre errores comunes como contactTestBitMask que por defecto es 0, la deprecación de UIScreen.main en iOS 26, y que SKShader usa GLSL ES en lugar de Metal. Finalmente, enlaza a otros skills relacionados como game-controller, game-audio-engine, game-art-direction y game-level-design.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andersmoldin/ios-game-creator-skills/tree/HEAD/skills/spritekit

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace spritekit?

SpriteKit es el motor de renderizado predeterminado para juegos 2D en iOS. Es compatible y no está obsoleto, pero su API está congelada desde iOS 12, por lo que todas las llamadas a SpriteKit funcionan en iOS 26 sin comprobaciones #available. La configuración general del proyecto (Modo de Juego, ProMotion, categoría de la app) se encuentra en el skill ios-game-design.

Evita SK3DNode: incorpora SceneKit, que está obsoleto desde iOS 26. Usa el skill realitykit para 3D.

Alojar la escena en SwiftUI

import SwiftUI
import SpriteKit

struct GameView: View {
    @State private var scene: GameScene = {          // crear una vez; nunca dentro del body
        let s = GameScene(size: CGSize(width: 390, height: 844))
        s.scaleMode = .resizeFill
        s.anchorPoint = CGPoint(x: 0.5, y: 0.5)
        return s
    }()
    @State private var paused = false

    var body: some View {
        SpriteView(scene: scene, isPaused: paused, preferredFramesPerSecond: 120,
                   options: [.ignoresSiblingOrder, .shouldCullNonVisibleNodes],
                   debugOptions: [.showsFPS, .showsNodeCount, .showsDrawCount]) // solo builds de depuración
            .ignoresSafeArea()
            .statusBarHidden()
            .persistentSystemOverlays(.hidden)
    }
}

Los valores predeterminados de SpriteView no son adecuados para juegos; debes sobrescribirlos:

  • preferredFramesPerSecond por defecto es 60. Pasa 120 y agrega CADisableMinimumFrameDurationOnPhone al Info.plist, de lo contrario el iPhone se queda a 60 Hz.
  • options por defecto es [.shouldCullNonVisibleNodes], por lo que .ignoresSiblingOrder está desactivado. Actívalo y configura zPosition cuando el orden de dibujo sea importante.

Modos de escala: .aspectFit añade bordes negros, .aspectFill recorta, .resizeFill se ajusta al tamaño de la vista (reorganiza en didChangeSize(_:)). Elige un tamaño de diseño fijo con un modo de aspecto, o .resizeFill con diseño adaptable. Mantén el mundo sin bordes y solo el HUD y los objetivos táctiles insértalos con view.safeAreaInsets, o dibuja el HUD como una superposición de SwiftUI.

Concurrencia en Swift 6

  • SKNode (y por tanto SKScene) es @MainActor, heredado de UIResponder. Los cierres creados en una escena (SKAction.run, customAction) heredan el actor principal.
  • SKPhysicsContactDelegate no está aislado, por lo que sin un aislamiento predeterminado al actor principal class GameScene: SKScene, SKPhysicsContactDelegate no compila en Swift 6. Escribe una conformidad aislada que compile en cualquier configuración: SKScene, @MainActor SKPhysicsContactDelegate.
  • Precarga con las formas asíncronas (await atlas.preload(), await SKTexture.preload(textures)); las formas con manejador de finalización son @Sendable y advierten si tocan nodos.
  • await node.run(action) se reanuda cuando la acción termina, lo que es adecuado para secuencias cortas. Nunca se reanuda para repeatForever.
  • Los nuevos proyectos de Xcode por defecto usan el modo de lenguaje Swift 5; establece explícitamente SWIFT_VERSION = 6.

Bucle de fotogramas

Orden por fotograma: update(_:) → acciones → didEvaluateActions() → física (las devoluciones de llamada de contacto se disparan aquí) → didSimulatePhysics() → restricciones → didApplyConstraints() → didFinishUpdate() → renderizado.

  • currentTime es absoluto. Calcula dt tú mismo y limítalo (por ejemplo a 1/30 s) para que una pausa o un salto nunca teletransporte objetos.
  • La tasa de fotogramas varía con el Modo de Bajo Consumo y el estado térmico. Escala todo el movimiento por dt.
  • Nunca agregues, elimines o remodeles cuerpos físicos dentro de didBegin/didEnd. Pon en cola el cambio y aplícalo en didSimulatePhysics() o en el siguiente update.
  • El orden de las acciones dentro de un fotograma no está especificado. Lee las posiciones finales en didEvaluateActions() o más tarde.

Esqueleto de escena

enum Category { static let player: UInt32 = 1 << 0; static let enemy: UInt32 = 1 << 1; static let wall: UInt32 = 1 << 2 }

final class GameScene: SKScene, @MainActor SKPhysicsContactDelegate {
    private var lastTime: TimeInterval = 0
    private let cam = SKCameraNode()
    private let player = SKSpriteNode(imageNamed: "player")
    private var pendingRemovals: [SKNode] = []

    override func didMove(to view: SKView) {
        physicsWorld.contactDelegate = self          // se mantiene sin retener: la escena debe permanecer viva
        addChild(cam); camera = cam                  // los hijos de la cámara forman un HUD fijo en pantalla
        let body = SKPhysicsBody(circleOfRadius: 12)
        body.categoryBitMask = Category.player
        body.collisionBitMask = Category.wall
        body.contactTestBitMask = Category.enemy     // por defecto 0: sin llamadas a didBegin
        player.physicsBody = body
        addChild(player)
    }

    override func update(_ currentTime: TimeInterval) {
        let dt = lastTime == 0 ? 0 : min(currentTime - lastTime, 1.0 / 30.0)
        lastTime = currentTime
        step(dt)
        cam.position = player.position
    }

    override func didSimulatePhysics() {             // punto seguro para mutar física
        pendingRemovals.forEach { $0.removeFromParent() }
        pendingRemovals.removeAll()
    }

    func didBegin(_ contact: SKPhysicsContact) {     // solo registrar; nunca mutar aquí
        let a = contact.bodyA, b = contact.bodyB
        guard a.categoryBitMask | b.categoryBitMask == Category.player | Category.enemy,
              let enemy = (a.categoryBitMask == Category.enemy ? a : b).node else { return }
        pendingRemovals.append(enemy)
    }

    private func step(_ dt: TimeInterval) { /* lógica del juego escalada por dt */ }
}

Componentes básicos

NecesidadUsa
Cámara, HUDSKCameraNode; nodos del HUD como hijos de la cámara
Interpolaciones, easingSKAction con timingMode o una timingFunction personalizada
Animación de spritesSKAction.animate(with:timePerFrame:) sobre texturas de atlas
FísicaSKPhysicsBody (círculo/rectángulo más económico), máscaras establecidas explícitamente, usesPreciseCollisionDetection para cuerpos pequeños y rápidos
Niveles con cuadrículaSKTileMapNode + SKTileSet; las teselas no son nodos, por lo que construye la colisión por separado
TexturasAtlas de Sprites en el catálogo de activos, SKTextureAtlas(named:); precarga antes del juego
Arte pixeladotexture.filteringMode = .nearest en cada textura, incluyendo cada fotograma del atlas
PartículasArchivos de emisor .sks, SKEmitterNode(fileNamed:); configura targetNode = scene para estelas
Shaders, luces, filtros, deformacionesLee references/effects.md
Sonido de un solo disparoSKAction.playSoundFileNamed; para algo más usa el skill game-audio-engine
Integración con MetalSKRenderer dibuja una escena dentro de tu propio pase de Metal

Rendimiento

  • Agrupación: los nodos que comparten una textura o atlas se dibujan en una sola llamada. Los atlas mixtos y los nodos superpuestos en diferentes zPosition dividen los lotes. Observa showsDrawCount.
  • Elimina nodos fuera de pantalla con removeFromParent(); el recorte aún visita cada nodo en cada fotograma.
  • Costosos, úsalos con moderación: SKEffectNode con CIFilter, SKCropNode, muchos SKShapeNodes, un SKShader por sprite, y cambios en el código fuente del shader en tiempo de ejecución (cada uno se recompila).
  • SKShapeNode es para dibujo de depuración. Hornea una forma una vez con view.texture(from:) y dibuja sprites.
  • Perfila en un dispositivo con la plantilla Game Performance de Instruments y el HUD de Rendimiento Metal (Scheme > Run > Diagnostics > Show Graphics Overview).

Trampas

  • contactTestBitMask por defecto es 0, mientras que categoryBitMask y collisionBitMask por defecto son todos los bits. Configura los tres para cada cuerpo.
  • UIScreen.main está obsoleto en iOS 26. Lee la tasa de refresco de view.window?.windowScene?.screen.maximumFramesPerSecond.
  • El código fuente de SKShader es GLSL ES, no Metal Shading Language.
  • physicsWorld.contactDelegate no se retiene.
  • Con .ignoresSiblingOrder, los nodos con el mismo zPosition se dibujan en orden arbitrario.

Skills relacionados

Entrada y hápticos: game-controller. Sonido: game-audio-engine. Apariencia, paleta y jugosidad: game-art-direction. Diseño de cuadrícula y salas: game-level-design.

Skills relacionados