Community程式設計與開發github.com

SpriteKit

編程技能。使用 SwiftUI 中嵌入的 SpriteKit 構建 2D iOS 遊戲(iOS 26+,Swift 6)- 場景、幀循環、動作、物理、相機、圖塊地圖、粒子、著色器、光照和繪製調用效能。在編寫或除錯 SpriteKit 程式碼(SKScene、SKNode、SpriteView),或當 2D 遊戲渲染緩慢或顯示異常時使用。

SpriteKit 是什麼?

SpriteKit 是蘋果用於 2D iOS 遊戲開發的預設渲染引擎。此技能提供完整的 SpriteKit 指南,涵蓋在 SwiftUI 中託管場景、Swift 6 並發處理、幀循環細節、場景骨架以及效能最佳化。它解釋了如何正確配置 `SpriteView`(例如 `preferredFramesPerSecond` 和 `ignoresSiblingOrder`),並解決了常見的陷阱,例如物理接觸遮罩、Swift 6 下的 `@MainActor` 隔離以及 GLSL ES 著色器限制。此技能適用於 Claude Code、Coder、Cursor 等 AI 代理,協助開發者使用 SpriteKit 編寫、除錯和最佳化 2D 遊戲。它包括用於批次處理、繪製調用最小化和基於裝置的效能分析的實用建議,同時避免了已棄用的 API,例如 `SK3DNode`。

相容平台~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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 縮放的遊戲邏輯 */ }
}

建構積木

需求使用
相機,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(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。

相關技能