简介面向 Cocos Creator 初学者与休闲跑酷玩法开发者的熊猫主题跑酷项目源码适用于学习角色移动、跳跃、二段跳、障碍生成与场景切换等基础机制也可作为课程设计或原型验证的参考工程。项目基于 Cocos Creator 1.4 及以上版本亲测可运行围绕熊猫主角构建了动画、控制脚本、预制体与关卡数据等模块便于按功能拆分阅读和二次修改。压缩包共 256 个文件约 3.46MB以 json 配置与数据、meta 资源描述、prefab 预制体、js 脚本为主同时包含 png 贴图、plist 图集、map 关卡数据、anim 动画剪辑以及少量演示视频和说明文档覆盖从资源组织到交互逻辑的完整链路。目前已有 3277 人学习下载读者可借此梳理跑酷项目的目录结构、角色状态切换、碰撞与跳跃参数配置思路并对照脚本理解动画与预制体的绑定方式适合作为轻量级跑酷 Demo 的学习样本。1. 一条无限跑道背后这份跑酷源码能给你省下多少活去年有个朋友接了个休闲酷跑的活美术资源先到策划要一周内看到可玩的循环。他最开始的想法是自己从零搭跑到第三天发现卡在「地面怎么无限滚、障碍怎么不长内存地生成」这两个问题上最后是拿一套 Cocos Creator 跑酷源码改出来的。这套源码的定位很明确不是教引擎入门而是给出一份跑酷玩法的最小可玩闭环——三车道横移、跳跃、地面无限衔接、障碍与金币按段落生成、分数与金币本地存档、死亡结算面板一套走完。适合两类人想快速做出一个能上架的休闲跑酷 Demo 的独立开发者以及接了同类外包、需要一份结构干净、能直接往下改的底子的团队。往下读会依次拿到目录骨架、三段核心循环代码、状态与碰撞的接线方式以及一份我踩过的坑清单。2. 工程骨架拆解从 assets 目录到预制体的分层逻辑拿到一份陌生工程我第一件事不是点运行而是把目录翻一遍。目录能暴露作者的分层意图也能提前告诉你哪里会痛。跑酷这类游戏的特殊性在于场景本身几乎不变变的是场景里不断被创建和销毁的物体——地面块、障碍、金币、特效。所以目录分层是不是围绕「可复用单元」来做基本决定了后面改起来顺不顺。2.1 目录分层与各自的职责边界这套源码的 assets 大致是这么组织的parkour-demo/ ├── assets/ │ ├── scenes/ │ │ ├── Loading.scene # 启动场景只做资源预热和跳转 │ │ ├── Main.scene # 主玩法场景常驻不卸载 │ │ └── Result.scene # 结算场景有的版本直接做成 Main 里的弹窗 │ ├── scripts/ │ │ ├── core/ # 与玩法无关的底座状态机、事件总线、常量 │ │ │ ├── GameManager.ts │ │ │ ├── GameState.ts │ │ │ └── EventBus.ts │ │ ├── player/ # 角色相关输入、位移、动画切换 │ │ │ ├── PlayerController.ts │ │ │ └── PlayerAnim.ts │ │ ├── level/ # 关卡循环地面回收、障碍生成、难度曲线 │ │ │ ├── GroundRecycler.ts │ │ │ ├── ObstacleSpawner.ts │ │ │ └── LevelConfig.ts │ │ ├── gameplay/ # 单局内的交互对象金币、障碍、道具 │ │ │ ├── Coin.ts │ │ │ ├── Obstacle.ts │ │ │ └── PowerUp.ts │ │ └── ui/ # HUD、结算面板、暂停 │ │ ├── HUD.ts │ │ └── ResultPanel.ts │ ├── prefabs/ │ │ ├── player.prefab │ │ ├── ground_tile.prefab │ │ ├── obstacle_box.prefab │ │ └── coin.prefab │ ├── configs/ │ │ └── level_01.json # 段落模板、难度参数 │ ├── textures/ │ ├── audio/ │ └── materials/ ├── settings/ # Creator 工程配置含物理分组矩阵 ├── package.json └── tsconfig.json这个分层最值得抄的地方在于core和level的切分。core里放的是「换皮也好、加玩法也好都不会动」的东西比如状态枚举、全局事件名常量level里放的是单局循环的规则难度曲线、段落长度、生成权重都在这个目录里。很多跑酷工程喜欢把生成逻辑直接塞进 GameManager结果就是调一个刷怪密度要去几百行的状态机里翻。scripts下每个文件的职责用一张表看更直观文件职责改它的典型场景GameManager.ts单例持有状态、分数、速度加暂停、加复活GameState.ts状态枚举与合法迁移加倒计时开局EventBus.ts全局事件名与派发入口加新的 UI 事件PlayerController.ts输入映射、车道切换、跳跃改手感、加滑铲GroundRecycler.ts地面块回收与前移改跑道长度、改速度曲线ObstacleSpawner.ts段落式生成障碍与金币改难度、加新障碍类型LevelConfig.ts读取 configs 下的 JSON做多关卡提示如果拿到的工程里没有configs目录难度参数大概率散落在各个脚本的property上改一轮要重新编译一次先在编辑器里把数值外置成 JSON 再谈别的。2.2 场景与预制体的职责边界跑酷项目的场景数量应该尽可能少。这套源码只有一个真正的玩法场景Main.sceneLoading 只负责预热Result 在部分版本里干脆是 Main 内的一个面板。理由很实际跑酷讲究「重开一局只要 0.5 秒」一旦跨场景节点树重建、常驻节点管理、输入监听的重新绑定全都会变成事故来源。我见过不少工程死在「第二局开始按键没反应」上根因就是场景切换时监听没清干净。预制体的划分原则是「谁会被反复创建谁就是预制体」player.prefab单例但从预制体实例化方便换模型不改场景。ground_tile.prefab会被回收复用几十次是对象池的主力。obstacle_box.prefab同一个预制体通过缩放和材质换肤出多种障碍减少预制体数量。coin.prefab数量最多必须走池。场景里只保留三类节点相机、常驻的管理节点挂着 GameManager、Spawner 这类脚本、UI 根节点。所有玩法物体都是运行时实例化的。这么做的直接好处是场景文件小、合并冲突少——多人协作时场景文件冲突是最烦的一类能不进场景的东西就别进场景。2.3 启动链路从 Loading 到第一帧游戏把这套工程跑起来实际执行的顺序是这样的Loading.scene加载Main.scene所需的贴图与音频加载完成后调用director.loadScene(Main)Main.scene的onLoad里GameManager 注册为常驻节点并把自己塞进静态单例状态置为Ready接着 GroundRecycler 把预摆的几块地面登记进池ObstacleSpawner 算出第一段生成点玩家点击屏幕后状态切到Running主循环才开始真正推进。这段链路里有个容易被忽略的细节常驻节点的注册必须早于任何场景切换且只能注册一次。常见写法是// GameManager.ts 片段 onLoad() { if (GameManager.instance) { this.node.destroy(); // 防止重复常驻 return; } GameManager.instance this; director.addPersistRootNode(this.node); this.setState(GameState.Ready); }addPersistRootNode的作用是让这个节点在场景切换时不被销毁它只能作用于场景的根节点挂在子节点上不生效这是新手最容易翻车的一处。参数没有可调项但调用时机有讲究必须在onLoad里做start里做就晚了场景已经完成一次挂载。3. 核心循环实战角色控制、地面回收与障碍生成三段代码跑酷之所以适合作为入门项目是因为它的核心循环特别短玩家不动世界往后跑地面块跑到身后就搬到前面障碍和金币按段落投放到前方。三段逻辑咬合起来就是一个能无限玩下去的关卡。这一段把三段代码拆开讲每段都能单独抄进别的项目。3.1 玩家控制器三车道横移与跳跃的状态分离先说一个血泪教训把横移和跳跃写在同一个节点的position上用 tween 做横移必翻车。tween 每帧写整个position会把跳跃时的 y 值直接抹平表现就是跳跃到一半人突然贴地。正确做法是拆成父子节点——父节点管 x车道子节点管 y跳跃高度。import { _decorator, Component, Node, Vec3, input, Input, EventKeyboard, KeyCode, tween } from cc; const { ccclass, property } _decorator; ccclass(PlayerController) export class PlayerController extends Component { property({ type: Node, tooltip: 只管 y 轴跳跃的子节点 }) body: Node | null null; property({ tooltip: 车道间距一般等于跑道宽度 / 3 }) laneWidth 2.0; property({ tooltip: 横移一次耗时0.08~0.15 手感最好 }) laneSwitchTime 0.12; property({ tooltip: 起跳初速度 }) jumpSpeed 9; property({ tooltip: 重力加速度负数 }) gravity -28; private laneIndex 1; // 0 左 / 1 中 / 2 右 private vy 0; private grounded true; onLoad() { input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this); } onDestroy() { // 必须解绑否则常驻节点会持有已销毁组件的引用 input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this); } private onKeyDown(e: EventKeyboard) { switch (e.keyCode) { case KeyCode.KEY_A: case KeyCode.ARROW_LEFT: this.switchLane(-1); break; case KeyCode.KEY_D: case KeyCode.ARROW_RIGHT: this.switchLane(1); break; case KeyCode.SPACE: case KeyCode.KEY_W: this.jump(); break; } } private switchLane(dir: number) { const next this.laneIndex dir; if (next 0 || next 2) return; // 撞到跑道边界直接忽略不做回弹 this.laneIndex next; const targetX (this.laneIndex - 1) * this.laneWidth; // 只改 xy 保持当前值避免与跳跃冲突 tween(this.node) .to(this.laneSwitchTime, { position: new Vec3(targetX, this.node.position.y, this.node.position.z) }) .start(); } private jump() { if (!this.grounded) return; this.grounded false; this.vy this.jumpSpeed; } update(dt: number) { if (this.grounded || !this.body) return; this.vy this.gravity * dt; const p this.body.position; const y p.y this.vy * dt; if (y 0) { this.body.setPosition(p.x, 0, p.z); this.vy 0; this.grounded true; } else { this.body.setPosition(p.x, y, p.z); } } }逻辑上分三段输入映射只负责把按键翻译成「左/右/跳」三个意图不做任何位移车道切换用 tween 改父节点 x时长控制手感跳跃走手写重力积分每帧按dt累加速度。参数里最关键的是laneSwitchTime调到 0.2 以上会出现明显的「拖沓感」调到 0.05 又像瞬移0.1 附近是大多数跑酷的甜点区。jumpSpeed和gravity的比值决定滞空时间比值约 0.32 时能刚好越过一个 1.2 米高的箱子。这里要注意update里用的是dt而不是固定值。写死 0.016 在编辑器里跑得好好的真机上 30 帧的设备跳跃高度直接矮一截这个坑在第 5 章还会再提一次。3.2 无限地面滚动加回收而不是无限生成新手最容易写出的版本是「每隔一段距离 instantiate 一块新地面」跑两分钟节点树上千个帧率开始抖。跑酷的地面本质上是固定数量的块在循环搬运数量取决于「视野内能看到几块 一块的缓冲」。这套源码的做法是预摆 N 块块跑出相机后方就把它挪到最前面。import { _decorator, Component, Node, Vec3 } from cc; const { ccclass, property } _decorator; ccclass(GroundRecycler) export class GroundRecycler extends Component { property({ type: [Node], tooltip: 预摆的地面块必须在编辑器里拖满 }) tiles: Node[] []; property({ tooltip: 单块地面沿 z 轴的长度要和模型对齐 }) tileLength 20; property({ tooltip: 相机可见距离超过这个值就回收 }) recycleZ -25; private speed 0; start() { // 按顺序摆好初始位置误差累积会导致接缝 this.tiles.forEach((t, i) { t.setPosition(0, 0, -i * this.tileLength); }); } setSpeed(v: number) { this.speed v; } update(dt: number) { if (this.speed 0) return; const move this.speed * dt; for (const t of this.tiles) { const p t.position; const z p.z move; // 地面朝相机方向移动 if (z this.recycleZ) { // 挪到当前最靠前的那块之后 t.setPosition(0, 0, this.getMinZ() - this.tileLength); } else { t.setPosition(p.x, p.y, z); } } } private getMinZ(): number { let min Infinity; for (const t of this.tiles) min Math.min(min, t.position.z); return min; } }tileLength必须和模型实际长度严格一致差 0.1 都会在接缝处露出缝隙或者重叠闪烁这是跑酷里最经典的视觉 bug。recycleZ取相机后方一点点太靠后会看到块消失的瞬间。getMinZ每次都遍历块数少一般 4~6 块时开销可以忽略块数多就改成维护一个最小堆或者直接按索引轮转。用索引轮转的写法更省// 上面的 update 可以换成这种避免每帧遍历找最小 z update(dt: number) { const move this.speed * dt; for (const t of this.tiles) { const z t.position.z move; t.setPosition(0, 0, z this.recycleZ ? z - this.tiles.length * this.tileLength : z); } }前提是初始摆放均匀。这个写法把「找最前」的复杂度从 O(n) 降到常数逻辑上也更不容易出错。3.3 障碍与金币的段落式生成纯随机会生成出「连续三个必死组合」玩家体验直接崩。这套源码用的是段落模板把一段距离当作一个 segment每个 segment 从配置里抽一个模板模板决定这一段有几个障碍、在第几条车道、金币怎么摆。生成器本身只负责按距离推进和投放。import { _decorator, Component, Node, Prefab, NodePool, instantiate, Vec3, math } from cc; const { ccclass, property } _decorator; ccclass(ObstacleSpawner) export class ObstacleSpawner extends Component { property({ type: [Prefab], tooltip: 障碍预制体池随机抽一个 }) obstaclePrefabs: Prefab[] []; property({ type: Prefab, tooltip: 金币预制体 }) coinPrefab: Prefab | null null; property({ type: Node, tooltip: 生成物的父节点 }) spawnRoot: Node | null null; property({ tooltip: 生成点相对相机的 z 偏移要大于可见距离 }) spawnZ 60; property({ tooltip: 一个段落的长度范围 }) minSegment 14; maxSegment 22; property({ tooltip: 三条车道的 x 坐标 }) laneX: number[] [-2, 0, 2]; private pool new NodePool(); private nextSpawnZ 0; update(dt: number) { // 世界在移动生成点跟着往前推这里用速度驱动 // speed 由 GameManager 每帧写入 this.nextSpawnZ - GameManager.instance!.speed * dt; if (this.nextSpawnZ this.spawnZ) { this.spawnSegment(); } } private spawnSegment() { const count math.randomRangeInt(1, 3); // 一段 1~2 个障碍 const usedLane new Setnumber(); for (let i 0; i count; i) { let lane math.randomRangeInt(0, 3); while (usedLane.has(lane)) lane (lane 1) % 3; // 保证不重叠 usedLane.add(lane); this.spawnObstacle(lane, this.nextSpawnZ); } // 空出来的车道放金币形成引导线 for (let lane 0; lane 3; lane) { if (!usedLane.has(lane) this.coinPrefab) { this.spawnCoin(lane, this.nextSpawnZ); } } this.nextSpawnZ - math.randomRangeInt(this.minSegment, this.maxSegment); } private spawnObstacle(lane: number, z: number) { const prefab this.obstaclePrefabs[math.randomRangeInt(0, this.obstaclePrefabs.length)]; const node this.pool.size() 0 ? this.pool.get()! : instantiate(prefab); node.setParent(this.spawnRoot); node.setPosition(this.laneX[lane], 0, z); node.active true; } private spawnCoin(lane: number, z: number) { const node this.pool.size() 0 ? this.pool.get()! : instantiate(this.coinPrefab!); node.setParent(this.spawnRoot); node.setPosition(this.laneX[lane], 0.8, z); node.active true; } /** 由障碍/金币回收时调用 */ recycle(node: Node) { node.active false; this.pool.put(node); } }关键参数是spawnZ和nextSpawnZ的关系。nextSpawnZ从 0 开始往前推推到超过spawnZ才生成这样自然形成「先空一段、再出内容」的节奏。minSegment和maxSegment控制密度值越小越难。usedLane那段去重逻辑看着笨但它保证了同一 z 位置不会出现两个障碍叠在一起——否则玩家看到的是一个、实际撞的是两个这种玄学 bug 排查起来能让人怀疑人生。金币只放在空车道上这是有意的设计玩家的视线会跟着金币走金币本身就是一条安全路径的引导。想加难度就在空车道里随机留一条不放金币玩家会犹豫犹豫就会出错。recycle方法必须由障碍和金币自己的脚本在离开视野时调用比如在Obstacle.ts的update里判断this.node.position.z 30就调spawner.recycle(this.node)。忘了这一步池子永远是空的等于没做池化。4. 数据流与状态管理一局游戏从 Ready 到 Dead 的完整链路核心循环跑起来之后下一个问题是「谁说了算」。跑酷项目里的状态很多开始前、跑动中、暂停、死亡、复活。这些状态如果不集中管理很快就会出现「死了还能跳」「暂停了金币还在转」这类问题。这一章讲状态机、碰撞和存档三件事怎么接起来。4.1 状态机与事件总线这套源码用一个极简的状态机加一个全局事件总线。状态机只管合法迁移和状态值事件总线负责广播UI 和玩法逻辑都只订阅不主动查询。import { EventTarget } from cc; export const bus new EventTarget(); export const EVT { STATE_CHANGED: state-changed, SCORE_CHANGED: score-changed, COIN_PICKED: coin-picked, } as const;import { _decorator, Component, director } from cc; import { bus, EVT } from ./EventBus; const { ccclass } _decorator; export enum GameState { Ready, Running, Paused, Dead } ccclass(GameManager) export class GameManager extends Component { static instance: GameManager | null null; state: GameState GameState.Ready; speed 8; // 世界前进速度米/秒 score 0; coins 0; onLoad() { if (GameManager.instance) { this.node.destroy(); return; } GameManager.instance this; director.addPersistRootNode(this.node); } canTransition(from: GameState, to: GameState): boolean { const table: RecordGameState, GameState[] { [GameState.Ready]: [GameState.Running], [GameState.Running]: [GameState.Paused, GameState.Dead], [GameState.Paused]: [GameState.Running, GameState.Ready], [GameState.Dead]: [GameState.Ready], }; return table[from].includes(to); } setState(next: GameState) { if (next this.state) return; if (!this.canTransition(this.state, next)) return; this.state next; bus.emit(EVT.STATE_CHANGED, next); } update(dt: number) { if (this.state ! GameState.Running) return; this.score this.speed * dt; // 距离即分数 bus.emit(EVT.SCORE_CHANGED, Math.floor(this.score)); } }canTransition用的是表驱动比一长串 if 好维护得多。想加「复活」状态只要在表里给 Dead 加一条到 Running 的边其他逻辑不用动。update里每帧 emit 分数事件看着有点浪费但 UI 那边做了数值变化的判断只有整数变了才刷文本实际开销很小换来的是逻辑完全解耦。订阅端的写法要成对出现// HUD.ts 片段 onEnable() { bus.on(EVT.SCORE_CHANGED, this.onScore, this); bus.on(EVT.STATE_CHANGED, this.onState, this); } onDisable() { bus.off(EVT.SCORE_CHANGED, this.onScore, this); bus.off(EVT.STATE_CHANGED, this.onState, this); }用onEnable/onDisable而不是onLoad/onDestroy是因为 UI 面板会被反复显隐显隐时暂停刷新能省一部分开销也避免了隐藏面板还在监听的问题。4.2 碰撞分组与触发时机跑酷不需要真实物理角色不能因为撞到箱子就翻滚要的是「碰到就死」或「碰到就吃」。所以刚体一律不用只用碰撞体做触发。Creator 里的做法是在工程设置的物理分组矩阵里配好哪些组之间产生碰撞事件代码里给每个碰撞体指定 group。碰撞体配置建议对象碰撞体类型尺寸处理分组玩家BoxCollider略小于模型留 10% 容错PLAYER障碍BoxCollider略小于模型避免「擦边就死」OBSTACLE金币SphereCollider / BoxCollider略大于模型好捡COIN地面不配地面只做视觉滚动-碰撞回调写在障碍与金币自己的脚本上因为「谁被撞」比「谁去撞」更清楚import { _decorator, Component, Collider, ITriggerEvent } from cc; const { ccclass, property } _decorator; ccclass(Obstacle) export class Obstacle extends Component { onEnable() { const c this.getComponent(Collider); c?.on(onTriggerEnter, this.onHit, this); } onDisable() { const c this.getComponent(Collider); c?.off(onTriggerEnter, this.onHit, this); } private onHit(e: ITriggerEvent) { if (GameManager.instance?.state ! GameState.Running) return; GameManager.instance.setState(GameState.Dead); } }第一行的状态判断非常重要。碰撞事件是在物理步里派发的同一帧内可能连续触发好几个如果不判断状态死亡后会继续处理后续碰撞可能连带把金币也算进去结算面板上的数字就对不上。这个防御写起来只有一行省下的排查时间是小时级的。4.3 分数、金币与本地存档存档用sys.localStorage键名带版本号方便以后结构变更时直接换键而不是写迁移逻辑import { sys } from cc; const SAVE_KEY parkour_save_v1; export interface SaveData { best: number; // 历史最高分 coins: number; // 累计金币 soundOn: boolean; } const DEFAULT_SAVE: SaveData { best: 0, coins: 0, soundOn: true }; export function loadSave(): SaveData { const raw sys.localStorage.getItem(SAVE_KEY); if (!raw) return { ...DEFAULT_SAVE }; try { return { ...DEFAULT_SAVE, ...JSON.parse(raw) }; } catch { return { ...DEFAULT_SAVE }; // 存档损坏时兜底不要让它把游戏卡死 } } export function writeSave(data: SaveData) { sys.localStorage.setItem(SAVE_KEY, JSON.stringify(data)); }{ ...DEFAULT_SAVE, ...JSON.parse(raw) }这个合并是关键老版本存档缺字段时自动补默认值不需要写迁移代码。try/catch也别省本地存储在某些环境下会返回被截断的字符串JSON.parse 直接抛异常游戏启动就白屏。写入时机上最高分在死亡结算时写一次就够金币是累计值建议在单局结束时写而不是每捡一个写一次——频繁写本地存储在低端机上有明显的卡顿尤其是小游戏平台。5. 常见问题排查跑酷项目上线前最容易翻车的五个点下面五条是我在不同跑酷工程里反复遇到的按「现象 → 原因 → 解决」整理。有些是这个源码本身已经处理掉的有些是改着改着就会踩进去的。5.1 回到主菜单再进游戏所有按键失灵现象第一局玩得好好的结算后点「再来一局」角色站在跑道上完全不动跳跃也没反应。原因输入监听挂在玩家节点上玩家节点在重开时被销毁重建旧监听还留在input全局对象里持有的是已销毁组件的引用新节点虽然也注册了监听但调用顺序靠后事件被旧的那个先消费掉了。解决所有input.on必须在onDestroy里成对input.off。如果 GameManager 是常驻节点输入监听就统一放到常驻节点上由它转发给当前玩家避免跟随玩家节点生命周期。这是最省心的做法也是这套源码采用的方案。5.2 玩三分钟后帧率从 60 掉到 20现象开局很流畅跑一段之后开始明显掉帧越跑越卡。原因三种可能叠加。障碍和金币创建后没有回池节点持续增长粒子特效播放完没有stop一直在渲染tween 在节点被回收后没有stop还在对一个失活的节点做插值。解决先开 Creator 的节点树面板看节点数量超过 200 个就基本确定是没回收。所有动态物体走对象池回池时除了active false还要调Tween.stopAllByTarget(node)和粒子组件的stop()。我一般会在recycle函数里统一做这三件事避免各处遗漏。5.3 真机上跳跃高度和编辑器里不一样现象编辑器里能跳过箱子打包到手机上跳不过去或者反过来跳得太高。原因update里把每帧的时间增量当固定值用了比如直接写this.vy -28 * 0.016。编辑器跑 60 帧没问题低端机跑 30 帧物理积分直接慢一半反过来高刷屏 120 帧会跳得更高。解决一律用update(dt: number)的dt。另外dt本身要做上限钳制dt Math.min(dt, 0.05)因为切后台再回来时dt可能是几百毫秒一帧就把角色送进地底。这个钳制建议写在主循环的最外层。5.4 构建到小游戏平台后黑屏或资源 404现象编辑器里一切正常构建到小游戏平台打开就黑屏日志里报某个资源加载失败。原因动态加载的资源没放在resources目录下。resources.load只能加载assets/resources里的东西放在别处的资源在构建时会被裁剪掉。另一个常见原因是路径大小写——Windows 上不敏感构建后在某些平台上就 404。解决所有运行时动态加载的资源统一放assets/resources路径用全小写并用常量管理不要散落在各处拼字符串。项目大一点就按功能拆成资源包Bundle关卡的 JSON 配置和贴图各一个包首包能小很多。5.5 高速状态下碰撞偶尔不触发现象速度调快之后角色偶尔会「穿过」障碍直接跑过去什么都不发生。原因这是典型的穿透。角色每帧位移超过了障碍碰撞体的厚度物理步在这一帧结束时两者已经错开没有重叠区间触发事件自然不派发。解决三个方向。把障碍碰撞体沿 z 轴加厚让它在高速下依然有足够厚度给角色和障碍的碰撞体开连续检测如果引擎版本支持最土也最稳的办法是在玩家脚本里自己做一次前向距离判定把「接下来 0.5 秒会撞到的物体」提前筛出来。跑酷的速度曲线通常越跑越快这个问题在后期才暴露测试时要专门调到最高速跑一遍。6. 二次开发路线换皮、加玩法与数值调优怎么改改造这套源码我的建议顺序是「先换皮再调数值最后加玩法」。倒过来做会很痛苦——加了新玩法之后再换模型动画状态机和碰撞尺寸全要重新对一遍。换皮只动三处prefabs/player.prefab换成新模型并调碰撞体尺寸textures下的贴图替换materials里的材质球参数微调。跑酷对材质要求不高主要是让地面贴图的平铺次数和tileLength对上否则接缝会跳。数值调优集中在LevelConfig.ts和 GameManager 的speed上。常见的做法是让速度随距离线性增长并在某个上限封顶import { _decorator, Component } from cc; const { ccclass, property } _decorator; ccclass(DifficultyCurve) export class DifficultyCurve extends Component { property baseSpeed 8; property maxSpeed 16; property { tooltip: 每多少米提速 1 单位 } growthPerMeter 300; getSpeed(distance: number): number { const s this.baseSpeed distance / this.growthPerMeter; return Math.min(s, this.maxSpeed); } }growthPerMeter决定难度爬升的快慢值太小玩家三分钟就玩不下去值太大又没挑战。我的经验是让普通玩家在第 60 到 90 秒之间达到maxSpeed的八成这个手感区间比较稳。加玩法的话优先级最高的是滑铲。它的实现成本最低在 PlayerController 里加一个slide()压缩body的缩放并把跳跃禁用 0.4 秒同时把碰撞体高度减半。其次是磁铁和护盾这类道具改动集中在PowerUp.ts和 GameManager 的状态上注意护盾生效期间要在障碍的onHit里判断并消费护盾而不是阻止碰撞事件派发。改动类型主要文件验证方式换角色模型player.prefab、PlayerController三车道横移后角色是否居中加滑铲PlayerController、PlayerAnim滑铲中能否跳过矮障碍加道具PowerUp.ts、GameManager道具结束后面板是否恢复多关卡LevelConfig.ts、configs/*.json切关卡后生成模板是否生效验证上我有个习惯每次改完先在编辑器里把速度手动拉到maxSpeed用最快的节奏跑三十秒再打包到真机跑一遍。跑酷的问题大多在高速段才暴露低速测试的通过率毫无意义。从那以后我每次动核心循环前都强制自己先把这个高速压力测试跑一遍再提交省下的返工时间比写测试还多。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/30 6:56:23 · 阅读 1.2k Cocos Creator跑酷源码解析：无限跑道、对象池与状态机实战
简介面向 Cocos Creator 初学者与休闲跑酷玩法开发者的熊猫主题跑酷项目源码适用于学习角色移动、跳跃、二段跳、障碍生成与场景切换等基础机制也可作为课程设计或原型验证的参考工程。项目基于 Cocos Creator 1.4 及以上版本亲测可运行围绕熊猫主角构建了动画、控制脚本、预制体与关卡数据等模块便于按功能拆分阅读和二次修改。压缩包共 256 个文件约 3.46MB以 json 配置与数据、meta 资源描述、prefab 预制体、js 脚本为主同时包含 png 贴图、plist 图集、map 关卡数据、anim 动画剪辑以及少量演示视频和说明文档覆盖从资源组织到交互逻辑的完整链路。目前已有 3277 人学习下载读者可借此梳理跑酷项目的目录结构、角色状态切换、碰撞与跳跃参数配置思路并对照脚本理解动画与预制体的绑定方式适合作为轻量级跑酷 Demo 的学习样本。1. 一条无限跑道背后这份跑酷源码能给你省下多少活去年有个朋友接了个休闲酷跑的活美术资源先到策划要一周内看到可玩的循环。他最开始的想法是自己从零搭跑到第三天发现卡在「地面怎么无限滚、障碍怎么不长内存地生成」这两个问题上最后是拿一套 Cocos Creator 跑酷源码改出来的。这套源码的定位很明确不是教引擎入门而是给出一份跑酷玩法的最小可玩闭环——三车道横移、跳跃、地面无限衔接、障碍与金币按段落生成、分数与金币本地存档、死亡结算面板一套走完。适合两类人想快速做出一个能上架的休闲跑酷 Demo 的独立开发者以及接了同类外包、需要一份结构干净、能直接往下改的底子的团队。往下读会依次拿到目录骨架、三段核心循环代码、状态与碰撞的接线方式以及一份我踩过的坑清单。2. 工程骨架拆解从 assets 目录到预制体的分层逻辑拿到一份陌生工程我第一件事不是点运行而是把目录翻一遍。目录能暴露作者的分层意图也能提前告诉你哪里会痛。跑酷这类游戏的特殊性在于场景本身几乎不变变的是场景里不断被创建和销毁的物体——地面块、障碍、金币、特效。所以目录分层是不是围绕「可复用单元」来做基本决定了后面改起来顺不顺。2.1 目录分层与各自的职责边界这套源码的 assets 大致是这么组织的parkour-demo/ ├── assets/ │ ├── scenes/ │ │ ├── Loading.scene # 启动场景只做资源预热和跳转 │ │ ├── Main.scene # 主玩法场景常驻不卸载 │ │ └── Result.scene # 结算场景有的版本直接做成 Main 里的弹窗 │ ├── scripts/ │ │ ├── core/ # 与玩法无关的底座状态机、事件总线、常量 │ │ │ ├── GameManager.ts │ │ │ ├── GameState.ts │ │ │ └── EventBus.ts │ │ ├── player/ # 角色相关输入、位移、动画切换 │ │ │ ├── PlayerController.ts │ │ │ └── PlayerAnim.ts │ │ ├── level/ # 关卡循环地面回收、障碍生成、难度曲线 │ │ │ ├── GroundRecycler.ts │ │ │ ├── ObstacleSpawner.ts │ │ │ └── LevelConfig.ts │ │ ├── gameplay/ # 单局内的交互对象金币、障碍、道具 │ │ │ ├── Coin.ts │ │ │ ├── Obstacle.ts │ │ │ └── PowerUp.ts │ │ └── ui/ # HUD、结算面板、暂停 │ │ ├── HUD.ts │ │ └── ResultPanel.ts │ ├── prefabs/ │ │ ├── player.prefab │ │ ├── ground_tile.prefab │ │ ├── obstacle_box.prefab │ │ └── coin.prefab │ ├── configs/ │ │ └── level_01.json # 段落模板、难度参数 │ ├── textures/ │ ├── audio/ │ └── materials/ ├── settings/ # Creator 工程配置含物理分组矩阵 ├── package.json └── tsconfig.json这个分层最值得抄的地方在于core和level的切分。core里放的是「换皮也好、加玩法也好都不会动」的东西比如状态枚举、全局事件名常量level里放的是单局循环的规则难度曲线、段落长度、生成权重都在这个目录里。很多跑酷工程喜欢把生成逻辑直接塞进 GameManager结果就是调一个刷怪密度要去几百行的状态机里翻。scripts下每个文件的职责用一张表看更直观文件职责改它的典型场景GameManager.ts单例持有状态、分数、速度加暂停、加复活GameState.ts状态枚举与合法迁移加倒计时开局EventBus.ts全局事件名与派发入口加新的 UI 事件PlayerController.ts输入映射、车道切换、跳跃改手感、加滑铲GroundRecycler.ts地面块回收与前移改跑道长度、改速度曲线ObstacleSpawner.ts段落式生成障碍与金币改难度、加新障碍类型LevelConfig.ts读取 configs 下的 JSON做多关卡提示如果拿到的工程里没有configs目录难度参数大概率散落在各个脚本的property上改一轮要重新编译一次先在编辑器里把数值外置成 JSON 再谈别的。2.2 场景与预制体的职责边界跑酷项目的场景数量应该尽可能少。这套源码只有一个真正的玩法场景Main.sceneLoading 只负责预热Result 在部分版本里干脆是 Main 内的一个面板。理由很实际跑酷讲究「重开一局只要 0.5 秒」一旦跨场景节点树重建、常驻节点管理、输入监听的重新绑定全都会变成事故来源。我见过不少工程死在「第二局开始按键没反应」上根因就是场景切换时监听没清干净。预制体的划分原则是「谁会被反复创建谁就是预制体」player.prefab单例但从预制体实例化方便换模型不改场景。ground_tile.prefab会被回收复用几十次是对象池的主力。obstacle_box.prefab同一个预制体通过缩放和材质换肤出多种障碍减少预制体数量。coin.prefab数量最多必须走池。场景里只保留三类节点相机、常驻的管理节点挂着 GameManager、Spawner 这类脚本、UI 根节点。所有玩法物体都是运行时实例化的。这么做的直接好处是场景文件小、合并冲突少——多人协作时场景文件冲突是最烦的一类能不进场景的东西就别进场景。2.3 启动链路从 Loading 到第一帧游戏把这套工程跑起来实际执行的顺序是这样的Loading.scene加载Main.scene所需的贴图与音频加载完成后调用director.loadScene(Main)Main.scene的onLoad里GameManager 注册为常驻节点并把自己塞进静态单例状态置为Ready接着 GroundRecycler 把预摆的几块地面登记进池ObstacleSpawner 算出第一段生成点玩家点击屏幕后状态切到Running主循环才开始真正推进。这段链路里有个容易被忽略的细节常驻节点的注册必须早于任何场景切换且只能注册一次。常见写法是// GameManager.ts 片段 onLoad() { if (GameManager.instance) { this.node.destroy(); // 防止重复常驻 return; } GameManager.instance this; director.addPersistRootNode(this.node); this.setState(GameState.Ready); }addPersistRootNode的作用是让这个节点在场景切换时不被销毁它只能作用于场景的根节点挂在子节点上不生效这是新手最容易翻车的一处。参数没有可调项但调用时机有讲究必须在onLoad里做start里做就晚了场景已经完成一次挂载。3. 核心循环实战角色控制、地面回收与障碍生成三段代码跑酷之所以适合作为入门项目是因为它的核心循环特别短玩家不动世界往后跑地面块跑到身后就搬到前面障碍和金币按段落投放到前方。三段逻辑咬合起来就是一个能无限玩下去的关卡。这一段把三段代码拆开讲每段都能单独抄进别的项目。3.1 玩家控制器三车道横移与跳跃的状态分离先说一个血泪教训把横移和跳跃写在同一个节点的position上用 tween 做横移必翻车。tween 每帧写整个position会把跳跃时的 y 值直接抹平表现就是跳跃到一半人突然贴地。正确做法是拆成父子节点——父节点管 x车道子节点管 y跳跃高度。import { _decorator, Component, Node, Vec3, input, Input, EventKeyboard, KeyCode, tween } from cc; const { ccclass, property } _decorator; ccclass(PlayerController) export class PlayerController extends Component { property({ type: Node, tooltip: 只管 y 轴跳跃的子节点 }) body: Node | null null; property({ tooltip: 车道间距一般等于跑道宽度 / 3 }) laneWidth 2.0; property({ tooltip: 横移一次耗时0.08~0.15 手感最好 }) laneSwitchTime 0.12; property({ tooltip: 起跳初速度 }) jumpSpeed 9; property({ tooltip: 重力加速度负数 }) gravity -28; private laneIndex 1; // 0 左 / 1 中 / 2 右 private vy 0; private grounded true; onLoad() { input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this); } onDestroy() { // 必须解绑否则常驻节点会持有已销毁组件的引用 input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this); } private onKeyDown(e: EventKeyboard) { switch (e.keyCode) { case KeyCode.KEY_A: case KeyCode.ARROW_LEFT: this.switchLane(-1); break; case KeyCode.KEY_D: case KeyCode.ARROW_RIGHT: this.switchLane(1); break; case KeyCode.SPACE: case KeyCode.KEY_W: this.jump(); break; } } private switchLane(dir: number) { const next this.laneIndex dir; if (next 0 || next 2) return; // 撞到跑道边界直接忽略不做回弹 this.laneIndex next; const targetX (this.laneIndex - 1) * this.laneWidth; // 只改 xy 保持当前值避免与跳跃冲突 tween(this.node) .to(this.laneSwitchTime, { position: new Vec3(targetX, this.node.position.y, this.node.position.z) }) .start(); } private jump() { if (!this.grounded) return; this.grounded false; this.vy this.jumpSpeed; } update(dt: number) { if (this.grounded || !this.body) return; this.vy this.gravity * dt; const p this.body.position; const y p.y this.vy * dt; if (y 0) { this.body.setPosition(p.x, 0, p.z); this.vy 0; this.grounded true; } else { this.body.setPosition(p.x, y, p.z); } } }逻辑上分三段输入映射只负责把按键翻译成「左/右/跳」三个意图不做任何位移车道切换用 tween 改父节点 x时长控制手感跳跃走手写重力积分每帧按dt累加速度。参数里最关键的是laneSwitchTime调到 0.2 以上会出现明显的「拖沓感」调到 0.05 又像瞬移0.1 附近是大多数跑酷的甜点区。jumpSpeed和gravity的比值决定滞空时间比值约 0.32 时能刚好越过一个 1.2 米高的箱子。这里要注意update里用的是dt而不是固定值。写死 0.016 在编辑器里跑得好好的真机上 30 帧的设备跳跃高度直接矮一截这个坑在第 5 章还会再提一次。3.2 无限地面滚动加回收而不是无限生成新手最容易写出的版本是「每隔一段距离 instantiate 一块新地面」跑两分钟节点树上千个帧率开始抖。跑酷的地面本质上是固定数量的块在循环搬运数量取决于「视野内能看到几块 一块的缓冲」。这套源码的做法是预摆 N 块块跑出相机后方就把它挪到最前面。import { _decorator, Component, Node, Vec3 } from cc; const { ccclass, property } _decorator; ccclass(GroundRecycler) export class GroundRecycler extends Component { property({ type: [Node], tooltip: 预摆的地面块必须在编辑器里拖满 }) tiles: Node[] []; property({ tooltip: 单块地面沿 z 轴的长度要和模型对齐 }) tileLength 20; property({ tooltip: 相机可见距离超过这个值就回收 }) recycleZ -25; private speed 0; start() { // 按顺序摆好初始位置误差累积会导致接缝 this.tiles.forEach((t, i) { t.setPosition(0, 0, -i * this.tileLength); }); } setSpeed(v: number) { this.speed v; } update(dt: number) { if (this.speed 0) return; const move this.speed * dt; for (const t of this.tiles) { const p t.position; const z p.z move; // 地面朝相机方向移动 if (z this.recycleZ) { // 挪到当前最靠前的那块之后 t.setPosition(0, 0, this.getMinZ() - this.tileLength); } else { t.setPosition(p.x, p.y, z); } } } private getMinZ(): number { let min Infinity; for (const t of this.tiles) min Math.min(min, t.position.z); return min; } }tileLength必须和模型实际长度严格一致差 0.1 都会在接缝处露出缝隙或者重叠闪烁这是跑酷里最经典的视觉 bug。recycleZ取相机后方一点点太靠后会看到块消失的瞬间。getMinZ每次都遍历块数少一般 4~6 块时开销可以忽略块数多就改成维护一个最小堆或者直接按索引轮转。用索引轮转的写法更省// 上面的 update 可以换成这种避免每帧遍历找最小 z update(dt: number) { const move this.speed * dt; for (const t of this.tiles) { const z t.position.z move; t.setPosition(0, 0, z this.recycleZ ? z - this.tiles.length * this.tileLength : z); } }前提是初始摆放均匀。这个写法把「找最前」的复杂度从 O(n) 降到常数逻辑上也更不容易出错。3.3 障碍与金币的段落式生成纯随机会生成出「连续三个必死组合」玩家体验直接崩。这套源码用的是段落模板把一段距离当作一个 segment每个 segment 从配置里抽一个模板模板决定这一段有几个障碍、在第几条车道、金币怎么摆。生成器本身只负责按距离推进和投放。import { _decorator, Component, Node, Prefab, NodePool, instantiate, Vec3, math } from cc; const { ccclass, property } _decorator; ccclass(ObstacleSpawner) export class ObstacleSpawner extends Component { property({ type: [Prefab], tooltip: 障碍预制体池随机抽一个 }) obstaclePrefabs: Prefab[] []; property({ type: Prefab, tooltip: 金币预制体 }) coinPrefab: Prefab | null null; property({ type: Node, tooltip: 生成物的父节点 }) spawnRoot: Node | null null; property({ tooltip: 生成点相对相机的 z 偏移要大于可见距离 }) spawnZ 60; property({ tooltip: 一个段落的长度范围 }) minSegment 14; maxSegment 22; property({ tooltip: 三条车道的 x 坐标 }) laneX: number[] [-2, 0, 2]; private pool new NodePool(); private nextSpawnZ 0; update(dt: number) { // 世界在移动生成点跟着往前推这里用速度驱动 // speed 由 GameManager 每帧写入 this.nextSpawnZ - GameManager.instance!.speed * dt; if (this.nextSpawnZ this.spawnZ) { this.spawnSegment(); } } private spawnSegment() { const count math.randomRangeInt(1, 3); // 一段 1~2 个障碍 const usedLane new Setnumber(); for (let i 0; i count; i) { let lane math.randomRangeInt(0, 3); while (usedLane.has(lane)) lane (lane 1) % 3; // 保证不重叠 usedLane.add(lane); this.spawnObstacle(lane, this.nextSpawnZ); } // 空出来的车道放金币形成引导线 for (let lane 0; lane 3; lane) { if (!usedLane.has(lane) this.coinPrefab) { this.spawnCoin(lane, this.nextSpawnZ); } } this.nextSpawnZ - math.randomRangeInt(this.minSegment, this.maxSegment); } private spawnObstacle(lane: number, z: number) { const prefab this.obstaclePrefabs[math.randomRangeInt(0, this.obstaclePrefabs.length)]; const node this.pool.size() 0 ? this.pool.get()! : instantiate(prefab); node.setParent(this.spawnRoot); node.setPosition(this.laneX[lane], 0, z); node.active true; } private spawnCoin(lane: number, z: number) { const node this.pool.size() 0 ? this.pool.get()! : instantiate(this.coinPrefab!); node.setParent(this.spawnRoot); node.setPosition(this.laneX[lane], 0.8, z); node.active true; } /** 由障碍/金币回收时调用 */ recycle(node: Node) { node.active false; this.pool.put(node); } }关键参数是spawnZ和nextSpawnZ的关系。nextSpawnZ从 0 开始往前推推到超过spawnZ才生成这样自然形成「先空一段、再出内容」的节奏。minSegment和maxSegment控制密度值越小越难。usedLane那段去重逻辑看着笨但它保证了同一 z 位置不会出现两个障碍叠在一起——否则玩家看到的是一个、实际撞的是两个这种玄学 bug 排查起来能让人怀疑人生。金币只放在空车道上这是有意的设计玩家的视线会跟着金币走金币本身就是一条安全路径的引导。想加难度就在空车道里随机留一条不放金币玩家会犹豫犹豫就会出错。recycle方法必须由障碍和金币自己的脚本在离开视野时调用比如在Obstacle.ts的update里判断this.node.position.z 30就调spawner.recycle(this.node)。忘了这一步池子永远是空的等于没做池化。4. 数据流与状态管理一局游戏从 Ready 到 Dead 的完整链路核心循环跑起来之后下一个问题是「谁说了算」。跑酷项目里的状态很多开始前、跑动中、暂停、死亡、复活。这些状态如果不集中管理很快就会出现「死了还能跳」「暂停了金币还在转」这类问题。这一章讲状态机、碰撞和存档三件事怎么接起来。4.1 状态机与事件总线这套源码用一个极简的状态机加一个全局事件总线。状态机只管合法迁移和状态值事件总线负责广播UI 和玩法逻辑都只订阅不主动查询。import { EventTarget } from cc; export const bus new EventTarget(); export const EVT { STATE_CHANGED: state-changed, SCORE_CHANGED: score-changed, COIN_PICKED: coin-picked, } as const;import { _decorator, Component, director } from cc; import { bus, EVT } from ./EventBus; const { ccclass } _decorator; export enum GameState { Ready, Running, Paused, Dead } ccclass(GameManager) export class GameManager extends Component { static instance: GameManager | null null; state: GameState GameState.Ready; speed 8; // 世界前进速度米/秒 score 0; coins 0; onLoad() { if (GameManager.instance) { this.node.destroy(); return; } GameManager.instance this; director.addPersistRootNode(this.node); } canTransition(from: GameState, to: GameState): boolean { const table: RecordGameState, GameState[] { [GameState.Ready]: [GameState.Running], [GameState.Running]: [GameState.Paused, GameState.Dead], [GameState.Paused]: [GameState.Running, GameState.Ready], [GameState.Dead]: [GameState.Ready], }; return table[from].includes(to); } setState(next: GameState) { if (next this.state) return; if (!this.canTransition(this.state, next)) return; this.state next; bus.emit(EVT.STATE_CHANGED, next); } update(dt: number) { if (this.state ! GameState.Running) return; this.score this.speed * dt; // 距离即分数 bus.emit(EVT.SCORE_CHANGED, Math.floor(this.score)); } }canTransition用的是表驱动比一长串 if 好维护得多。想加「复活」状态只要在表里给 Dead 加一条到 Running 的边其他逻辑不用动。update里每帧 emit 分数事件看着有点浪费但 UI 那边做了数值变化的判断只有整数变了才刷文本实际开销很小换来的是逻辑完全解耦。订阅端的写法要成对出现// HUD.ts 片段 onEnable() { bus.on(EVT.SCORE_CHANGED, this.onScore, this); bus.on(EVT.STATE_CHANGED, this.onState, this); } onDisable() { bus.off(EVT.SCORE_CHANGED, this.onScore, this); bus.off(EVT.STATE_CHANGED, this.onState, this); }用onEnable/onDisable而不是onLoad/onDestroy是因为 UI 面板会被反复显隐显隐时暂停刷新能省一部分开销也避免了隐藏面板还在监听的问题。4.2 碰撞分组与触发时机跑酷不需要真实物理角色不能因为撞到箱子就翻滚要的是「碰到就死」或「碰到就吃」。所以刚体一律不用只用碰撞体做触发。Creator 里的做法是在工程设置的物理分组矩阵里配好哪些组之间产生碰撞事件代码里给每个碰撞体指定 group。碰撞体配置建议对象碰撞体类型尺寸处理分组玩家BoxCollider略小于模型留 10% 容错PLAYER障碍BoxCollider略小于模型避免「擦边就死」OBSTACLE金币SphereCollider / BoxCollider略大于模型好捡COIN地面不配地面只做视觉滚动-碰撞回调写在障碍与金币自己的脚本上因为「谁被撞」比「谁去撞」更清楚import { _decorator, Component, Collider, ITriggerEvent } from cc; const { ccclass, property } _decorator; ccclass(Obstacle) export class Obstacle extends Component { onEnable() { const c this.getComponent(Collider); c?.on(onTriggerEnter, this.onHit, this); } onDisable() { const c this.getComponent(Collider); c?.off(onTriggerEnter, this.onHit, this); } private onHit(e: ITriggerEvent) { if (GameManager.instance?.state ! GameState.Running) return; GameManager.instance.setState(GameState.Dead); } }第一行的状态判断非常重要。碰撞事件是在物理步里派发的同一帧内可能连续触发好几个如果不判断状态死亡后会继续处理后续碰撞可能连带把金币也算进去结算面板上的数字就对不上。这个防御写起来只有一行省下的排查时间是小时级的。4.3 分数、金币与本地存档存档用sys.localStorage键名带版本号方便以后结构变更时直接换键而不是写迁移逻辑import { sys } from cc; const SAVE_KEY parkour_save_v1; export interface SaveData { best: number; // 历史最高分 coins: number; // 累计金币 soundOn: boolean; } const DEFAULT_SAVE: SaveData { best: 0, coins: 0, soundOn: true }; export function loadSave(): SaveData { const raw sys.localStorage.getItem(SAVE_KEY); if (!raw) return { ...DEFAULT_SAVE }; try { return { ...DEFAULT_SAVE, ...JSON.parse(raw) }; } catch { return { ...DEFAULT_SAVE }; // 存档损坏时兜底不要让它把游戏卡死 } } export function writeSave(data: SaveData) { sys.localStorage.setItem(SAVE_KEY, JSON.stringify(data)); }{ ...DEFAULT_SAVE, ...JSON.parse(raw) }这个合并是关键老版本存档缺字段时自动补默认值不需要写迁移代码。try/catch也别省本地存储在某些环境下会返回被截断的字符串JSON.parse 直接抛异常游戏启动就白屏。写入时机上最高分在死亡结算时写一次就够金币是累计值建议在单局结束时写而不是每捡一个写一次——频繁写本地存储在低端机上有明显的卡顿尤其是小游戏平台。5. 常见问题排查跑酷项目上线前最容易翻车的五个点下面五条是我在不同跑酷工程里反复遇到的按「现象 → 原因 → 解决」整理。有些是这个源码本身已经处理掉的有些是改着改着就会踩进去的。5.1 回到主菜单再进游戏所有按键失灵现象第一局玩得好好的结算后点「再来一局」角色站在跑道上完全不动跳跃也没反应。原因输入监听挂在玩家节点上玩家节点在重开时被销毁重建旧监听还留在input全局对象里持有的是已销毁组件的引用新节点虽然也注册了监听但调用顺序靠后事件被旧的那个先消费掉了。解决所有input.on必须在onDestroy里成对input.off。如果 GameManager 是常驻节点输入监听就统一放到常驻节点上由它转发给当前玩家避免跟随玩家节点生命周期。这是最省心的做法也是这套源码采用的方案。5.2 玩三分钟后帧率从 60 掉到 20现象开局很流畅跑一段之后开始明显掉帧越跑越卡。原因三种可能叠加。障碍和金币创建后没有回池节点持续增长粒子特效播放完没有stop一直在渲染tween 在节点被回收后没有stop还在对一个失活的节点做插值。解决先开 Creator 的节点树面板看节点数量超过 200 个就基本确定是没回收。所有动态物体走对象池回池时除了active false还要调Tween.stopAllByTarget(node)和粒子组件的stop()。我一般会在recycle函数里统一做这三件事避免各处遗漏。5.3 真机上跳跃高度和编辑器里不一样现象编辑器里能跳过箱子打包到手机上跳不过去或者反过来跳得太高。原因update里把每帧的时间增量当固定值用了比如直接写this.vy -28 * 0.016。编辑器跑 60 帧没问题低端机跑 30 帧物理积分直接慢一半反过来高刷屏 120 帧会跳得更高。解决一律用update(dt: number)的dt。另外dt本身要做上限钳制dt Math.min(dt, 0.05)因为切后台再回来时dt可能是几百毫秒一帧就把角色送进地底。这个钳制建议写在主循环的最外层。5.4 构建到小游戏平台后黑屏或资源 404现象编辑器里一切正常构建到小游戏平台打开就黑屏日志里报某个资源加载失败。原因动态加载的资源没放在resources目录下。resources.load只能加载assets/resources里的东西放在别处的资源在构建时会被裁剪掉。另一个常见原因是路径大小写——Windows 上不敏感构建后在某些平台上就 404。解决所有运行时动态加载的资源统一放assets/resources路径用全小写并用常量管理不要散落在各处拼字符串。项目大一点就按功能拆成资源包Bundle关卡的 JSON 配置和贴图各一个包首包能小很多。5.5 高速状态下碰撞偶尔不触发现象速度调快之后角色偶尔会「穿过」障碍直接跑过去什么都不发生。原因这是典型的穿透。角色每帧位移超过了障碍碰撞体的厚度物理步在这一帧结束时两者已经错开没有重叠区间触发事件自然不派发。解决三个方向。把障碍碰撞体沿 z 轴加厚让它在高速下依然有足够厚度给角色和障碍的碰撞体开连续检测如果引擎版本支持最土也最稳的办法是在玩家脚本里自己做一次前向距离判定把「接下来 0.5 秒会撞到的物体」提前筛出来。跑酷的速度曲线通常越跑越快这个问题在后期才暴露测试时要专门调到最高速跑一遍。6. 二次开发路线换皮、加玩法与数值调优怎么改改造这套源码我的建议顺序是「先换皮再调数值最后加玩法」。倒过来做会很痛苦——加了新玩法之后再换模型动画状态机和碰撞尺寸全要重新对一遍。换皮只动三处prefabs/player.prefab换成新模型并调碰撞体尺寸textures下的贴图替换materials里的材质球参数微调。跑酷对材质要求不高主要是让地面贴图的平铺次数和tileLength对上否则接缝会跳。数值调优集中在LevelConfig.ts和 GameManager 的speed上。常见的做法是让速度随距离线性增长并在某个上限封顶import { _decorator, Component } from cc; const { ccclass, property } _decorator; ccclass(DifficultyCurve) export class DifficultyCurve extends Component { property baseSpeed 8; property maxSpeed 16; property { tooltip: 每多少米提速 1 单位 } growthPerMeter 300; getSpeed(distance: number): number { const s this.baseSpeed distance / this.growthPerMeter; return Math.min(s, this.maxSpeed); } }growthPerMeter决定难度爬升的快慢值太小玩家三分钟就玩不下去值太大又没挑战。我的经验是让普通玩家在第 60 到 90 秒之间达到maxSpeed的八成这个手感区间比较稳。加玩法的话优先级最高的是滑铲。它的实现成本最低在 PlayerController 里加一个slide()压缩body的缩放并把跳跃禁用 0.4 秒同时把碰撞体高度减半。其次是磁铁和护盾这类道具改动集中在PowerUp.ts和 GameManager 的状态上注意护盾生效期间要在障碍的onHit里判断并消费护盾而不是阻止碰撞事件派发。改动类型主要文件验证方式换角色模型player.prefab、PlayerController三车道横移后角色是否居中加滑铲PlayerController、PlayerAnim滑铲中能否跳过矮障碍加道具PowerUp.ts、GameManager道具结束后面板是否恢复多关卡LevelConfig.ts、configs/*.json切关卡后生成模板是否生效验证上我有个习惯每次改完先在编辑器里把速度手动拉到maxSpeed用最快的节奏跑三十秒再打包到真机跑一遍。跑酷的问题大多在高速段才暴露低速测试的通过率毫无意义。从那以后我每次动核心循环前都强制自己先把这个高速压力测试跑一遍再提交省下的返工时间比写测试还多。希望帮到你。本文还有配套的精品资源点击获取