Community코딩 & 개발github.com

spritekit

코딩 스킬. SwiftUI(iOS 26+, Swift 6)에 호스팅된 SpriteKit으로 2D iOS 게임을 제작합니다 - 씬, 프레임 루프, 액션, 물리, 카메라, 타일맵, 파티클, 셰이더, 라이팅 및 드로우 콜 성능. SpriteKit 코드(SKScene, SKNode, SpriteView)를 작성하거나 디버깅할 때, 또는 2D 게임이 느리게 렌더링되거나 잘못 보일 때 사용합니다.

spritekit란 무엇인가요?

이 스킬은 iOS 26+ 및 Swift 6 환경에서 SpriteKit을 사용하여 2D 게임을 개발하는 방법을 상세히 설명합니다. SpriteKit은 iOS 12 이후 API가 동결되었지만 여전히 지원되는 기본 2D 렌더러로, 모든 호출이 iOS 26에서 `#available` 검사 없이 작동합니다. SwiftUI의 `SpriteView`를 통해 씬을 호스팅하는 방법과 함께, `preferredFramesPerSecond`, `ignoresSiblingOrder` 등 게임에 최적화된 필수 설정 값을 제공합니다. Swift 6 동시성 모델에서 `@MainActor` 격리와 `SKPhysicsContactDelegate`의 올바른 사용법, 프레임 루프의 세부 단계(업데이트→액션→물리→렌더)와 `dt` 계산을 통한 시간 기반 애니메이션을 다룹니다. 또한 카메라, HUD, 타일맵, 파티클, 셰이더 등 주요 구성 요소의 사용 예제와 함께 배칭, 드로우 콜 최적화, `SKShapeNode` 주의사항, `contactTestBitMask` 기본값 오류 등 실무에서 자주 마주치는 성능 이슈와 함정을 정리합니다.

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

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

spritekit은(는) 무엇을 하나요?

SpriteKit은 2D iOS 게임의 기본 렌더러입니다. 지원되며 폐기되지 않았지만, iOS 12 이후 API가 동결되었으므로 모든 SpriteKit 호출은 #available 검사 없이 iOS 26에서 작동합니다. 프로젝트 전체 설정(게임 모드, ProMotion, 앱 카테고리)은 ios-game-design 스킬에 있습니다.

SK3DNode는 피하십시오: iOS 26부터 폐기된 SceneKit을 내장합니다. 3D가 필요하면 realitykit 스킬을 사용하세요.

SwiftUI에서 씬 호스팅하기

import SwiftUI
import SpriteKit

struct GameView: View {
    @State private var scene: GameScene = {          // 한 번 생성; 절대 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]) // 디버그 빌드만
            .ignoresSafeArea()
            .statusBarHidden()
            .persistentSystemOverlays(.hidden)
    }
}

SpriteView의 기본값은 게임에 적합하지 않으므로 재정의해야 합니다:

  • preferredFramesPerSecond 기본값은 60입니다. 120을 전달하고 Info.plist에 CADisableMinimumFrameDurationOnPhone을 추가하세요. 그렇지 않으면 iPhone이 60Hz로 유지됩니다.
  • options 기본값은 [.shouldCullNonVisibleNodes]이므로 .ignoresSiblingOrder가 꺼져 있습니다. 켜고 드로우 순서가 중요한 곳에 zPosition을 설정하세요.

스케일 모드: .aspectFit은 레터박스, .aspectFill은 크롭, .resizeFill은 뷰 크기를 추적합니다(didChangeSize(_:)에서 재배치). 고정 디자인 크기와 애스펙트 모드를 선택하거나, .resizeFill과 적응형 레이아웃을 사용하세요. 세계를 전체 영역으로 유지하고 HUD와 터치 대상만 view.safeAreaInsets로 여백을 두거나, HUD를 SwiftUI 오버레이로 그리세요.

Swift 6 동시성

  • SKNode(따라서 SKScene)는 UIResponder에서 상속된 @MainActor입니다. 씬에서 생성된 클로저(SKAction.run, customAction)는 메인 액터를 상속합니다.
  • SKPhysicsContactDelegate는 비격리(nonisolated)되어 있으므로, 기본 메인 액터 격리가 없는 class GameScene: SKScene, SKPhysicsContactDelegate는 Swift 6에서 컴파일되지 않습니다. 모든 설정에서 컴파일되는 격리 적합성을 작성하세요: SKScene, @MainActor SKPhysicsContactDelegate.
  • 비동기 형태(await atlas.preload(), await SKTexture.preload(textures))로 사전 로드하세요; 완료 핸들러 형태는 @Sendable이며 노드를 건드리면 경고합니다.
  • await node.run(action)은 액션이 끝날 때 재개되며, 짧은 시퀀스에 적합합니다. repeatForever에서는 절대 재개되지 않습니다.
  • 새 Xcode 프로젝트는 기본적으로 Swift 5 언어 모드를 사용합니다. SWIFT_VERSION = 6을 명시적으로 설정하세요.

프레임 루프

프레임당 순서: update(_:) → 액션 → didEvaluateActions() → 물리(충돌 콜백이 여기서 발생) → didSimulatePhysics() → 제약 조건 → didApplyConstraints() → didFinishUpdate() → 렌더.

  • currentTime은 절대 시간입니다. 직접 dt를 계산하고 (예: 1/30초로) 클램핑하여 일시 중지나 끊김이 객체를 순간 이동시키지 않도록 하세요.
  • 프레임 속도는 저전력 모드와 열 상태에 따라 달라집니다. 모든 움직임을 dt로 스케일링하세요.
  • didBegin/didEnd 내에서 물리 바디를 추가, 제거 또는 모양 변경하지 마세요. 변경을 큐에 넣고 didSimulatePhysics() 또는 다음 update에서 적용하세요.
  • 프레임 내 액션 순서는 지정되지 않습니다. 최종 위치는 didEvaluateActions() 또는 이후에 읽으세요.

씬 스켈레톤

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          // unowned로 유지: 씬이 활성 상태여야 함
        addChild(cam); camera = cam                  // cam의 자식은 화면 고정 HUD를 형성
        let body = SKPhysicsBody(circleOfRadius: 12)
        body.categoryBitMask = Category.player
        body.collisionBitMask = Category.wall
        body.contactTestBitMask = Category.enemy     // 기본값 0: 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() {             // 물리 변경에 안전한 지점
        pendingRemovals.forEach { $0.removeFromParent() }
        pendingRemovals.removeAll()
    }

    func didBegin(_ contact: SKPhysicsContact) {     // 기록만; 여기서 절대 변경하지 않음
        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) { /* dt로 스케일링된 게임 로직 */ }
}

구성 요소

필요사용
카메라, HUDSKCameraNode; HUD 노드는 카메라 자식으로
트윈, 이징timingMode 또는 커스텀 timingFunction이 있는 SKAction
스프라이트 애니메이션아틀라스 텍스처를 사용한 SKAction.animate(with:timePerFrame:)
물리SKPhysicsBody (원/사각형이 가장 저렴), 마스크를 명시적으로 설정, 작고 빠른 바디에는 usesPreciseCollisionDetection 사용
그리드 레벨SKTileMapNode + SKTileSet; 타일은 노드가 아니므로 충돌을 별도로 구축
텍스처에셋 카탈로그의 스프라이트 아틀라스, SKTextureAtlas(named:); 게임플레이 전에 사전 로드
픽셀 아트모든 텍스처(각 아틀라스 프레임 포함)에 texture.filteringMode = .nearest 설정
파티클.sks 이미터 파일, SKEmitterNode(fileNamed:); 궤적을 위해 targetNode = scene 설정
셰이더, 라이트, 필터, 워프references/effects.md 참조
일회성 사운드SKAction.playSoundFileNamed; 그 이상은 game-audio-engine 스킬 사용
Metal 통합SKRenderer가 자체 Metal 패스 내에서 씬을 그림

성능

  • 배칭: 텍스처나 아틀라스를 공유하는 노드는 한 번의 호출로 그려집니다. 혼합 아틀라스와 다른 zPosition에서 겹치는 노드는 배치를 나눕니다. showsDrawCount를 확인하세요.
  • 화면 밖 노드는 removeFromParent()로 제거하세요; 컬링은 여전히 매 프레임 모든 노드를 방문합니다.
  • 비용이 많이 들고 드물게 사용해야 하는 것: CIFilter가 있는 SKEffectNode, SKCropNode, 많은 SKShapeNode, 스프라이트당 하나의 SKShader, 그리고 런타임에 변경되는 셰이더 소스(각각 재컴파일).
  • SKShapeNode는 디버그 드로잉용입니다. 모양을 한 번 view.texture(from:)로 구워서 스프라이트로 그리세요.
  • 기기에서 Instruments Game Performance 템플릿과 Metal Performance HUD(스킴 > 실행 > 진단 > 그래픽 개요 표시)로 프로파일링하세요.

주의사항

  • contactTestBitMask 기본값은 0인 반면, categoryBitMask와 collisionBitMask는 모든 비트가 기본값입니다. 모든 바디에 세 가지를 모두 설정하세요.
  • iOS 26에서 UIScreen.main은 폐기되었습니다. view.window?.windowScene?.screen.maximumFramesPerSecond에서 재생 빈도를 읽으세요.
  • SKShader 소스는 Metal Shading Language가 아닌 GLSL ES입니다.
  • physicsWorld.contactDelegate는 유지(retain)되지 않습니다.
  • .ignoresSiblingOrder를 사용하면 동일한 zPosition의 노드가 임의의 순서로 그려집니다.

관련 스킬

입력 및 햅틱: game-controller. 사운드: game-audio-engine. 외관, 팔레트 및 주스: game-art-direction. 그리드 및 방 레이아웃: game-level-design.

관련 스킬