SpriteKit 是做什麼的?
SpriteKit 是 2D iOS 遊戲的預設渲染引擎。它受到支援且未被棄用,但其 API 自 iOS 12 以來已被凍結,因此每個 SpriteKit 呼叫在 iOS 26 上無需 #available 檢查即可運作。專案範圍設定(遊戲模式、ProMotion、應用程式類別)位於 ios-game-design 技能中。
避免使用 SK3DNode:它嵌入了 SceneKit,後者在 iOS 26 已被棄用。請使用 realitykit 技能處理 3D。
在 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]) // 僅限 debug 建置
.ignoresSafeArea()
.statusBarHidden()
.persistentSystemOverlays(.hidden)
}
}
SpriteView 的預設值不適合遊戲;請覆寫它們:
preferredFramesPerSecond預設為 60。傳入 120 並在 Info.plist 中添加CADisableMinimumFrameDurationOnPhone,否則 iPhone 將保持 60 Hz。options預設為[.shouldCullNonVisibleNodes],因此.ignoresSiblingOrder是關閉的。將其打開,並在繪製順序重要之處設定zPosition。
縮放模式:.aspectFit 會產生信箱效果,.aspectFill 會裁剪,.resizeFill 會跟隨視圖大小(在 didChangeSize(_:) 中重新佈局)。選擇一個帶有長寬比的固定設計尺寸,或使用帶有自適應佈局的 .resizeFill。保持世界全出血,並僅透過 view.safeAreaInsets 內嵌 HUD 和觸控目標,或將 HUD 繪製為 SwiftUI 覆蓋層。
Swift 6 並發
SKNode(以及因此SKScene)是@MainActor,繼承自UIResponder。在場景中建立的閉包(SKAction.run、customAction)繼承主執行器。SKPhysicsContactDelegate是非隔離的,因此在沒有預設主執行器隔離的情況下,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內部添加、移除或重塑物理本體。將變更排入佇列,並在下一個update或didSimulatePhysics()中應用。 - 幀內的動作順序未指定。在
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 // 非保留持有:場景必須保持存活
addChild(cam); camera = 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(Scheme > Run > Diagnostics > Show Graphics Overview)進行分析。
陷阱
contactTestBitMask預設為 0,而categoryBitMask和collisionBitMask預設為所有位元。為每個本體設定全部三個。UIScreen.main在 iOS 26 中已被棄用。從view.window?.windowScene?.screen.maximumFramesPerSecond讀取更新頻率。SKShader來源是 GLSL ES,而不是 Metal Shading Language。physicsWorld.contactDelegate不會被保留。- 使用
.ignoresSiblingOrder時,具有相同zPosition的節點以任意順序繪製。
相關技能
輸入和觸覺回饋:game-controller。音效:game-audio-engine。外觀、調色板和效果:game-art-direction。網格和房間佈局:game-level-design。