spritekit

Compétence de codage pour créer des jeux 2D iOS avec SpriteKit hébergé dans SwiftUI (iOS 26+, Swift 6) : scènes, boucle d'images, actions, physique, caméras, tuiles, particules, shaders, éclairage et performances des appels de dessin. À utiliser lors de l'écriture ou du débogage de code SpriteKit (SKScene, SKNode, SpriteView) ou lorsqu'un jeu 2D s'affiche lentement ou de manière incorrecte.

Qu'est-ce que spritekit ?

Cette compétence fournit des directives expertes et des modèles pour développer des jeux 2D iOS performants avec SpriteKit, hébergés dans SwiftUI, ciblant iOS 26+ et Swift 6. Elle couvre l'ensemble du pipeline de rendu : hébergement de scènes avec SpriteView (configuration correcte des options, taux de rafraîchissement), gestion de la concurrence avec Swift 6 (isolations @MainActor), la boucle d'images (update, actions, physique, contraintes), la structure de scène avec caméra et HUD, et les pièces de base (actions, physique, tuiles, textures, particules, sons). La compétence met l'accent sur les performances en expliquant comment optimiser le batching, éviter les nodes coûteux (SKEffectNode, SKCropNode, SKShapeNode), et utiliser le débogage (showsDrawCount, Instruments). Elle liste également les pièges courants comme les masques de collision par défaut, la dépréciation de UIScreen.main, et l'ordre d'affichage avec ignoresSiblingOrder. Conçue pour fonctionner avec d'autres compétences (game-controller, game-audio-engine, game-art-direction, game-level-design), elle est idéale pour déboguer du code SpriteKit existant ou construire un nouveau jeu 2D de zéro.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait spritekit ?

SpriteKit est le moteur de rendu par défaut pour les jeux 2D iOS. Il est pris en charge et non déprécié, mais son API est figée depuis iOS 12, donc tout appel SpriteKit fonctionne sur iOS 26 sans vérification #available. Les paramètres à l'échelle du projet (mode de jeu, ProMotion, catégorie d'application) se trouvent dans la compétence ios-game-design.

Évitez SK3DNode : il intègre SceneKit, qui est déprécié depuis iOS 26. Utilisez la compétence realitykit pour la 3D.

Héberger la scène dans SwiftUI

import SwiftUI
import SpriteKit

struct GameView: View {
    @State private var scene: GameScene = {          // créer une fois ; jamais à l'intérieur de 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]) // builds de débogage uniquement
            .ignoresSafeArea()
            .statusBarHidden()
            .persistentSystemOverlays(.hidden)
    }
}

Les valeurs par défaut de SpriteView ne sont pas adaptées aux jeux ; remplacez-les :

  • preferredFramesPerSecond par défaut à 60. Passez 120 et ajoutez CADisableMinimumFrameDurationOnPhone à Info.plist, sinon l'iPhone reste à 60 Hz.
  • options par défaut à [.shouldCullNonVisibleNodes], donc .ignoresSiblingOrder est désactivé. Activez-le et définissez zPosition là où l'ordre d'affichage est important.

Modes d'échelle : .aspectFit ajoute des bandes noires, .aspectFill rogne, .resizeFill suit la taille de la vue (réorganisation dans didChangeSize(_:)). Choisissez une taille de conception fixe avec un mode d'aspect, ou .resizeFill avec une disposition adaptative. Gardez le monde en plein écran et insérez uniquement le HUD et les zones tactiles par view.safeAreaInsets, ou dessinez le HUD comme une superposition SwiftUI.

Concurrence Swift 6

  • SKNode (et donc SKScene) est @MainActor, hérité de UIResponder. Les closures créées dans une scène (SKAction.run, customAction) héritent de l'acteur principal.
  • SKPhysicsContactDelegate est non isolé, donc sans isolation par défaut de l'acteur principal class GameScene: SKScene, SKPhysicsContactDelegate ne compile pas en Swift 6. Écrivez une conformité isolée, qui compile sous tous les réglages : SKScene, @MainActor SKPhysicsContactDelegate.
  • Préchargez avec les formes asynchrones (await atlas.preload(), await SKTexture.preload(textures)) ; les formes avec gestionnaire d'achèvement sont @Sendable et émettent un avertissement lorsqu'elles touchent des nodes.
  • await node.run(action) reprend lorsque l'action se termine, ce qui convient aux séquences courtes. Il ne reprend jamais pour repeatForever.
  • Les nouveaux projets Xcode par défaut en mode langage Swift 5 ; définissez SWIFT_VERSION = 6 explicitement.

Boucle d'images

Ordre par image : update(_:) → actions → didEvaluateActions() → physique (les callbacks de contact se déclenchent ici) → didSimulatePhysics() → contraintes → didApplyConstraints() → didFinishUpdate() → rendu.

  • currentTime est absolu. Calculez dt vous-même et limitez-le (par exemple à 1/30 s) pour qu'une pause ou un accroc ne téléporte jamais les objets.
  • Le taux d'images varie avec le mode basse consommation et l'état thermique. Mettez à l'échelle tout mouvement par dt.
  • N'ajoutez, ne supprimez ou ne redimensionnez jamais de corps physiques à l'intérieur de didBegin/didEnd. Mettez en file d'attente le changement et appliquez-le dans didSimulatePhysics() ou la prochaine update.
  • L'ordre des actions dans une image n'est pas spécifié. Lisez les positions finales dans didEvaluateActions() ou plus tard.

Squelette de scène

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          // détenu non retenu : la scène doit rester en vie
        addChild(cam); camera = cam                  // les enfants de cam forment un HUD fixe à l'écran
        let body = SKPhysicsBody(circleOfRadius: 12)
        body.categoryBitMask = Category.player
        body.collisionBitMask = Category.wall
        body.contactTestBitMask = Category.enemy     // par défaut 0 : aucun appel didBegin du tout
        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() {             // point sûr pour muter la physique
        pendingRemovals.forEach { $0.removeFromParent() }
        pendingRemovals.removeAll()
    }

    func didBegin(_ contact: SKPhysicsContact) {     // enregistrer seulement ; ne jamais muter ici
        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) { /* logique de jeu mise à l'échelle par dt */ }
}

Éléments de base

BesoinUtilisation
Caméra, HUDSKCameraNode ; nodes HUD comme enfants de la caméra
Interpolations, easingsSKAction avec timingMode ou une timingFunction personnalisée
Animation de spriteSKAction.animate(with:timePerFrame:) sur les textures d'atlas
PhysiqueSKPhysicsBody (cercle/rect le moins cher), masques définis explicitement, usesPreciseCollisionDetection pour les petits corps rapides
Niveaux en grilleSKTileMapNode + SKTileSet ; les tuiles ne sont pas des nodes, donc construisez la collision séparément
TexturesAtlas de sprites dans le catalogue d'actifs, SKTextureAtlas(named:) ; préchargez avant le jeu
Pixel arttexture.filteringMode = .nearest sur chaque texture, y compris chaque image d'atlas
ParticulesFichiers émetteurs .sks, SKEmitterNode(fileNamed:) ; définissez targetNode = scene pour les traînées
Shaders, lumières, filtres, déformationsConsultez references/effects.md
Son ponctuelSKAction.playSoundFileNamed ; tout ce qui dépasse utilise la compétence game-audio-engine
Intégration MetalSKRenderer dessine une scène à l'intérieur de votre propre passe Metal

Performances

  • Regroupement : les nodes qui partagent une texture ou un atlas s'affichent en un seul appel. Les atlas mélangés et les nodes qui se chevauchent à différents zPosition divisent les lots. Surveillez showsDrawCount.
  • Supprimez les nodes hors écran avec removeFromParent() ; l'élagage visite toujours chaque node à chaque image.
  • Coûteux, à utiliser avec parcimonie : SKEffectNode avec CIFilter, SKCropNode, nombreux SKShapeNodes, un SKShader par sprite, et les modifications de source de shader à l'exécution (chacune recompile).
  • SKShapeNode est pour le dessin de débogage. Cuisez une forme une fois avec view.texture(from:) et dessinez des sprites.
  • Profilez sur un appareil avec le modèle Game Performance d'Instruments et le HUD de performances Metal (Scheme > Run > Diagnostics > Show Graphics Overview).

Pièges

  • contactTestBitMask par défaut à 0, tandis que categoryBitMask et collisionBitMask par défaut à tous les bits. Définissez les trois pour chaque corps.
  • UIScreen.main est déprécié dans iOS 26. Lisez le taux de rafraîchissement à partir de view.window?.windowScene?.screen.maximumFramesPerSecond.
  • La source SKShader est en GLSL ES, pas en Metal Shading Language.
  • physicsWorld.contactDelegate n'est pas retenu.
  • Avec .ignoresSiblingOrder, les nodes à zPosition égal s'affichent dans un ordre arbitraire.

Compétences connexes

Entrées et retour haptique : game-controller. Son : game-audio-engine. Aspect visuel, palette et effets : game-art-direction. Disposition de la grille et des pièces : game-level-design.

Skills associés