spritekit

Habilidade de codificação. Cria jogos 2D para iOS com SpriteKit hospedado em SwiftUI (iOS 26+, Swift 6) – cenas, loop de quadros, ações, física, câmeras, mapas de tiles, partículas, shaders, iluminação e desempenho de chamadas de desenho. Use ao escrever ou depurar código SpriteKit (SKScene, SKNode, SpriteView) ou quando um jogo 2D renderiza lentamente ou parece incorreto.

O que é spritekit?

Esta habilidade fornece um guia abrangente para construir jogos 2D iOS usando SpriteKit integrado com SwiftUI, visando iOS 26+ e Swift 6. Ela abrange a criação e configuração adequada de uma cena SpriteKit dentro de um SpriteView SwiftUI, incluindo configurações essenciais como modos de escala, orientação de câmera e desempenho de taxa de quadros. A habilidade explica detalhadamente o loop de quadros do SpriteKit, oferecendo um padrão de esqueleto de cena seguro para Swift 6 com isolamento @MainActor e conformidade de delegate de contato de física. Ela lista os principais blocos de construção para câmeras, ações, física, mapas de tiles, texturas, partículas e som, juntamente com um guia de referência rápida, e fornece dicas de otimização de desempenho, como reduzir chamadas de desenho, evitar nós caros e usar o template Game Performance do Instruments para criação de perfil no dispositivo. A habilidade também documenta armadilhas comuns, como bitmasks de física, taxa de atualização da tela e uso de shaders no SpriteKit. Ela faz referência a habilidades relacionadas para entrada de controle, áudio, direção de arte e design de níveis.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que spritekit faz?

SpriteKit é o renderizador padrão para jogos 2D iOS. Ele é suportado e não obsoleto, mas sua API está congelada desde o iOS 12, portanto toda chamada SpriteKit funciona no iOS 26 sem verificações #available. Configurações de todo o projeto (Game Mode, ProMotion, categoria do aplicativo) estão na habilidade ios-game-design.

Evite SK3DNode: ele incorpora o SceneKit, que está obsoleto desde o iOS 26. Use a habilidade realitykit para 3D.

Hospedar a cena em SwiftUI

import SwiftUI
import SpriteKit

struct GameView: View {
    @State private var scene: GameScene = {          // cria uma vez; nunca dentro do 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]) // apenas builds de depuração
            .ignoresSafeArea()
            .statusBarHidden()
            .persistentSystemOverlays(.hidden)
    }
}

Os padrões de SpriteView estão errados para jogos; sobrescreva-os:

  • preferredFramesPerSecond padrão é 60. Passe 120 e adicione CADisableMinimumFrameDurationOnPhone ao Info.plist, caso contrário o iPhone permanece em 60 Hz.
  • options padrão é [.shouldCullNonVisibleNodes], então .ignoresSiblingOrder está desligado. Ligue-o e defina zPosition sempre que a ordem de desenho for importante.

Modos de escala: .aspectFit letterbox, .aspectFill corta, .resizeFill acompanha o tamanho da view (reorganize o layout em didChangeSize(_:)). Escolha um tamanho de design fixo com um modo de aspecto, ou .resizeFill com layout adaptativo. Mantenha o mundo sem bordas e insira apenas HUD e alvos de toque com view.safeAreaInsets, ou desenhe o HUD como uma sobreposição SwiftUI.

Concorrência Swift 6

  • SKNode (e portanto SKScene) é @MainActor, herdado de UIResponder. Closures criadas em uma cena (SKAction.run, customAction) herdam o main actor.
  • SKPhysicsContactDelegate é não isolado, então sem isolamento padrão de main actor class GameScene: SKScene, SKPhysicsContactDelegate falha ao compilar em Swift 6. Escreva uma conformidade isolada, que compila em todas as configurações: SKScene, @MainActor SKPhysicsContactDelegate.
  • Pré-carregue com as formas assíncronas (await atlas.preload(), await SKTexture.preload(textures)); as formas com manipulador de conclusão são @Sendable e emitem aviso quando tocam em nós.
  • await node.run(action) retoma quando a ação termina, o que é adequado para sequências curtas. Nunca retorna para repeatForever.
  • Novos projetos Xcode usam modo de linguagem Swift 5 por padrão; defina SWIFT_VERSION = 6 explicitamente.

Loop de quadros

Ordem por quadro: update(_:) → ações → didEvaluateActions() → física (callbacks de contato disparam aqui) → didSimulatePhysics() → constraints → didApplyConstraints() → didFinishUpdate() → renderizar.

  • currentTime é absoluto. Calcule dt você mesmo e limite-o (por exemplo a 1/30 s) para que uma pausa ou travamento nunca teletransporte objetos.
  • A taxa de quadros varia com o Modo de Baixo Consumo e estado térmico. Escale todo movimento por dt.
  • Nunca adicione, remova ou reformate corpos de física dentro de didBegin/didEnd. Enfileire a mudança e aplique-a em didSimulatePhysics() ou no próximo update.
  • A ordem das ações dentro de um quadro é não especificada. Leia as posições finais em didEvaluateActions() ou depois.

Esqueleto de cena

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          // mantido não retido: a cena deve permanecer viva
        addChild(cam); camera = cam                  // filhos de cam formam um HUD fixo na tela
        let body = SKPhysicsBody(circleOfRadius: 12)
        body.categoryBitMask = Category.player
        body.collisionBitMask = Category.wall
        body.contactTestBitMask = Category.enemy     // padrão 0: nenhuma chamada 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() {             // ponto seguro para mutar física
        pendingRemovals.forEach { $0.removeFromParent() }
        pendingRemovals.removeAll()
    }

    func didBegin(_ contact: SKPhysicsContact) {     // apenas registra; nunca muta aqui
        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 do jogo escalada por dt */ }
}

Blocos de construção

NecessidadeUse
Câmera, HUDSKCameraNode; nós HUD como filhos da câmera
Interpolações, easingSKAction com timingMode ou uma timingFunction personalizada
Animação de spriteSKAction.animate(with:timePerFrame:) sobre texturas de atlas
FísicaSKPhysicsBody (círculo/retângulo mais barato), máscaras definidas explicitamente, usesPreciseCollisionDetection para corpos pequenos e rápidos
Níveis em gradeSKTileMapNode + SKTileSet; tiles não são nós, então construa colisão separadamente
TexturasSprite Atlas no catálogo de assets, SKTextureAtlas(named:); pré-carregue antes do gameplay
Pixel arttexture.filteringMode = .nearest em cada textura, incluindo cada quadro do atlas
PartículasArquivos .sks de emissores, SKEmitterNode(fileNamed:); defina targetNode = scene para rastros
Shaders, luzes, filtros, deformaçõesLeia references/effects.md
Som de uma vezSKAction.playSoundFileNamed; algo mais usa a habilidade game-audio-engine
Integração MetalSKRenderer desenha uma cena dentro de seu próprio passe Metal

Desempenho

  • Agrupamento: nós que compartilham uma textura ou atlas desenham em uma chamada. Atlas misturados e nós sobrepostos em diferentes zPositions quebram os agrupamentos. Observe showsDrawCount.
  • Remova nós fora da tela com removeFromParent(); a poda ainda visita cada nó a cada quadro.
  • Caros, use com moderação: SKEffectNode com CIFilter, SKCropNode, muitos SKShapeNodes, um SKShader por sprite e alterações de fonte de shader em tempo de execução (cada uma recompila).
  • SKShapeNode é para desenho de depuração. "Asse" uma forma uma vez com view.texture(from:) e desenhe sprites.
  • Crie perfil em um dispositivo com o template Game Performance do Instruments e o HUD de Performance Metal (Scheme > Run > Diagnostics > Show Graphics Overview).

Armadilhas

  • contactTestBitMask padrão é 0, enquanto categoryBitMask e collisionBitMask padrão são todos os bits. Defina todos os três para cada corpo.
  • UIScreen.main está obsoleto no iOS 26. Leia a taxa de atualização de view.window?.windowScene?.screen.maximumFramesPerSecond.
  • A fonte de SKShader é GLSL ES, não a Metal Shading Language.
  • physicsWorld.contactDelegate não é retido.
  • Com .ignoresSiblingOrder, nós com zPosition igual desenham em ordem arbitrária.

Habilidades relacionadas

Entrada e hápticos: game-controller. Som: game-audio-engine. Visual, paleta e "juice": game-art-direction. Layout de grade e salas: game-level-design.

Habilidades Relacionadas