《Cocos 游戏开发实战》5.2 场景切换与预加载

import {
  _decorator, Component, Node, UIOpacity, BlockInputEvents, tween, director,
} from 'cc';
const { ccclass, property } = _decorator;

@ccclass('TransitionMask')
export class TransitionMask extends Component {
  @property(Node) mask: Node | null = null;

  private busy = false;

  /** 切到目标场景：先淡入遮罩，加载完新场景后淡出 */
  switchTo(sceneName: string): void {
    if (this.busy || this.mask === null) return;
    this.busy = true;
    const mask = this.mask;

    // 遮罩期间吞掉所有点击，避免玩家连点两次按钮触发两次切换
    mask.addComponent(BlockInputEvents);
    const op = mask.getComponent(UIOpacity) ?? mask.addComponent(UIOpacity);

    tween(op)
      .to(0.18, { opacity: 255 })
      .call(() => {
        director.loadScene(sceneName, (err) => {
          if (err !== null) {
            console.error('[TransitionMask] 场景切换失败', err);
          }
          tween(op)
            .to(0.18, { opacity: 0 })
            .call(() => {
              this.busy = false;
              mask.getComponent(BlockInputEvents)?.destroy();
            })
            .start();
        });
      })
      .start();
  }
}

import { _decorator, Component, director, assetManager, ProgressBar } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('SettlementPreloader')
export class SettlementPreloader extends Component {
  @property(ProgressBar) bar: ProgressBar | null = null;

  private nextScene = 'level-2';

  onEnable(): void {
    // 结算面板出现的同一帧就开始预加载，不占用任何用户可见的等待
    director.preloadScene(
      this.nextScene,
      (completed: number, total: number) => {
        if (this.bar !== null && total > 0) this.bar.progress = completed / total;
      },
      (err, sceneAsset) => {
        if (err !== null) {
          console.warn('[SettlementPreloader] 预加载失败，将退回同步加载', err);
          return;
        }
        console.log('[SettlementPreloader] 已就绪', sceneAsset?.name);
      },
    );
  }

  onDisable(): void {
    // 面板被关掉但预加载还在跑时，交给 director 自己完成即可；
    // 这里不主动取消，因为 preloadScene 没有提供取消接口
  }

  goNext(): void {
    director.loadScene(this.nextScene);
  }
}

import { _decorator, Component, director, Director } from 'cc';
const { ccclass } = _decorator;

@ccclass('SceneLifecycleGuard')
export class SceneLifecycleGuard extends Component {
  onEnable(): void {
    director.on(Director.EVENT_BEFORE_SCENE_LAUNCH, this.onBeforeLaunch, this);
    director.on(Director.EVENT_AFTER_SCENE_LAUNCH, this.onAfterLaunch, this);
  }

  onDisable(): void {
    director.off(Director.EVENT_BEFORE_SCENE_LAUNCH, this.onBeforeLaunch, this);
    director.off(Director.EVENT_AFTER_SCENE_LAUNCH, this.onAfterLaunch, this);
  }

  private onBeforeLaunch(): void {
    // 新场景即将挂载：旧场景的自定义全局监听在这里撤掉
    this.unscheduleAllCallbacks();
  }

  private onAfterLaunch(): void {
    const scene = director.getScene();
    console.log('[SceneLifecycleGuard] 已进入场景', scene?.name);
  }
}

// src/core/scene-router.ts —— 与引擎无关，可直接单测
export interface RoutePayload {
  readonly [key: string]: string | number | boolean;
}

export class SceneRouter {
  private pending: RoutePayload = {};
  private current = '';

  /** 切场景前登记参数；同名参数后写覆盖先写 */
  go(target: string, payload: RoutePayload = {}): void {
    this.pending = { ...payload };
    this.current = target;
  }

  /** 新场景 onLoad 时取出参数；取出即清空，避免下一次误读 */
  consume(): { target: string; payload: RoutePayload } {
    const out = { target: this.current, payload: this.pending };
    this.pending = {};
    return out;
  }

  get currentScene(): string {
    return this.current;
  }
}

// tests/scene-router.test.ts
import { describe, it, expect } from 'vitest';
import { SceneRouter } from '../src/core/scene-router';

describe('SceneRouter', () => {
  it('参数取出后清空，第二次读到空对象', () => {
    const r = new SceneRouter();
    r.go('level-1', { score: 120, retry: false });
    const first = r.consume();
    expect(first.target).toBe('level-1');
    expect(first.payload.score).toBe(120);
    expect(r.consume().payload).toEqual({});
  });
});