SpriteKit 是做什么的?
SpriteKit 是 2D iOS 游戏的默认渲染器。它受支持且未被弃用,但其 API 自 iOS 12 以来已被冻结,因此每个 SpriteKit 调用在 iOS 26 上无需 #available 检查即可工作。项目范围设置(游戏模式、ProMotion、应用类别)位于 ios-game-design 技能中。
避免使用 SK3DNode:它嵌入了 SceneKit,后者自 iOS 26 起已被弃用。对于 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 将保持 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)继承主 actor。SKPhysicsContactDelegate是非隔离的,因此在没有默认主 actor 隔离的情况下,class GameScene: SKScene, SKPhysicsContactDelegate在 Swift 6 中无法编译。编写一个隔离的 conformance,它可以在任何设置下编译: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 // 持有不保留引用:场景必须保持存活
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 节点作为摄像机子节点 |
| 补间,缓动 | SKAction 与 timingMode 或自定义 timingFunction |
| 精灵动画 | 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 性能 HUD(方案 > 运行 > 诊断 > 显示图形总览)进行分析。
注意事项
contactTestBitMask默认为 0,而categoryBitMask和collisionBitMask默认为所有位。为每个物理体设置所有三个遮罩。UIScreen.main在 iOS 26 中已弃用。从view.window?.windowScene?.screen.maximumFramesPerSecond读取刷新率。SKShader源码是 GLSL ES,而不是 Metal 着色语言。physicsWorld.contactDelegate不被保留。- 使用
.ignoresSiblingOrder时,具有相同zPosition的节点以任意顺序绘制。
相关技能
输入和触觉:game-controller。音效:game-audio-engine。外观、调色板和视觉效果:game-art-direction。网格和房间布局:game-level-design。