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로 스케일링된 게임 로직 */ }
}
구성 요소
| 필요 | 사용 |
|---|---|
| 카메라, HUD | SKCameraNode; 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.