Community编程与开发github.com

SpriteKit

编码技能。使用 SpriteKit 在 SwiftUI 中构建 2D iOS 游戏(iOS 26+,Swift 6)——场景、帧循环、动作、物理、摄像机、瓦片地图、粒子、着色器、光照和绘制调用性能。适用于编写或调试 SpriteKit 代码(SKScene、SKNode、SpriteView),或当 2D 游戏渲染缓慢或显示异常时。

SpriteKit 是什么?

本技能专注于使用 Apple 的 SpriteKit 框架开发 2D iOS 游戏。它基于 iOS 26 和 Swift 6 环境,提供从项目设置到性能优化的全面指导。该技能详细解释了如何在 SwiftUI 中托管 SpriteKit 场景,包括 SpriteView 的正确配置,并强调了 Swift 6 并发模型下的重要注意事项,例如 @MainActor 隔离和异步预加载。内容涵盖了帧循环的生命周期, 物理引擎的正确使用模式, 以及一系列实用的构建模块,如摄像机、动作、物理体和粒子系统。此外,还专门讨论了性能优化策略,包括批处理、节点剔除和避免昂贵操作,并针对常见陷阱(如接触测试位掩码和渲染顺序)提供了解决方案。该技能适用于 Cursor、Codex 和 Claude Code 等 AI 代理平台。

兼容平台~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 起已被弃用。对于 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 缩放的游戏逻辑 */ }
}

构建模块

需求使用
摄像机,HUDSKCameraNode;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。

相关技能