refactor(scene): migrate scenes to runtime lifecycle and finalize rollout

Made-with: Cursor

src/scene/BaseScene.ts

@@ -21,12 +21,32 @@ export abstract class BaseScene implements IBaseScene {
     throw new Error("changeScene not injected by SceneManager");
   }
 
-  // 生命周期方法 - 默认空实现
-  async loadBundle(): Promise<void> {}
-  async unLoadBundle(): Promise<void> {}
-  layout(): void | Promise<void> {}
-  onLoad(): void | Promise<void> {}
-  onUnLoad(): void | Promise<void> {}
+  /**
+   * 新 runtime 生命周期钩子：场景实现优先覆写这些方法。
+   * SceneManager/transaction 仍调用旧接口，这里做统一桥接。
+   */
+  protected onSceneLoadBundle(): Promise<void> | void {}
+  protected onSceneUnloadBundle(): Promise<void> | void {}
+  protected onSceneLayout(): Promise<void> | void {}
+  protected onSceneEnter(): Promise<void> | void {}
+  protected onSceneExit(): Promise<void> | void {}
+
+  // 旧生命周期接口：与当前 runtime/transaction 对齐，内部桥接到新钩子
+  async loadBundle(): Promise<void> {
+    await this.onSceneLoadBundle();
+  }
+  async unLoadBundle(): Promise<void> {
+    await this.onSceneUnloadBundle();
+  }
+  async layout(): Promise<void> {
+    await this.onSceneLayout();
+  }
+  async onLoad(): Promise<void> {
+    await this.onSceneEnter();
+  }
+  async onUnLoad(): Promise<void> {
+    await this.onSceneExit();
+  }
   update(_dt: number, _name: string, _ticker: Ticker): void {}
   lateUpdate(_dt: number, _name: string, _ticker: Ticker): void {}
 }

src/stages/initSceneLayout.ts

@@ -8,4 +8,8 @@ export const initSceneLayout = {
   heroYRatio: 0.46,
   /** 主按钮相对底边的上移（逻辑像素，与 position.get 的 options.y 一致） */
   startCtaOffsetY: -110,
+  /** 首屏进入欢迎页时的切场景策略（对齐 scene transaction 参数） */
+  nextSceneTransition: {
+    isHolderLast: false,
+  },
 } as const;

src/stages/page_init.ts

@@ -40,7 +40,7 @@ export default class InitScene extends BaseScene {
     super("init", SceneType.Normal);
   }
 
-  async loadBundle(): Promise<void> {
+  protected async onSceneLoadBundle(): Promise<void> {
     this.loadingBtn = new Button({
       text: "加载中…",
       position: () => position.get("center", "center"),
@@ -66,11 +66,11 @@ export default class InitScene extends BaseScene {
     this.loadingBtn = undefined;
   }
 
-  async unLoadBundle(): Promise<void> {
+  protected async onSceneUnloadBundle(): Promise<void> {
     await assetManager.unloadBundle("load-screen");
   }
 
-  async layout(): Promise<void> {
+  protected async onSceneLayout(): Promise<void> {
     this.stage.sortableChildren = true;
     this.stage.eventMode = "passive";
 
@@ -149,7 +149,7 @@ export default class InitScene extends BaseScene {
           x: 0,
         }),
       onClick: () => {
-        this.changeScene("welcome", { isHolderLast: false });
+        this.changeScene("welcome", initSceneLayout.nextSceneTransition);
       },
     });
     this.startBtn._comp.zIndex = Z_TEXT;
@@ -158,12 +158,12 @@ export default class InitScene extends BaseScene {
     this.placeHeroElements();
   }
 
-  onLoad(): void {
+  protected onSceneEnter(): void {
     window.addEventListener("resize", this.onResize);
     this.pixie?.gotoAndPlay(0);
   }
 
-  onUnLoad(): void {
+  protected onSceneExit(): void {
     window.removeEventListener("resize", this.onResize);
   }
 

src/stages/welcome/page_welcome.ts

@@ -6,13 +6,14 @@ import position from "@/utils/Position";
 
 export default class WelcomeScene extends BaseScene {
   stage: Container = new Container();
+  private startBtn?: Button;
 
   constructor() {
     super("welcome", SceneType.Normal);
   }
 
-  async layout(): Promise<void> {
-    const btn = new Button({
+  protected onSceneLayout(): void {
+    this.startBtn = new Button({
       text: "进入游戏",
       onClick: () => {
         this.changeScene("welcome2");
@@ -20,14 +21,14 @@ export default class WelcomeScene extends BaseScene {
       position: () => position.center(),
     });
 
-    this.stage.addChild(btn.getView());
+    this.stage.addChild(this.startBtn.getView());
   }
 
-  onLoad(): void {
+  protected onSceneEnter(): void {
     console.log("welcome onLoad");
   }
 
-  onUnLoad(): void {
+  protected onSceneExit(): void {
     console.log("welcome onUnLoad");
   }
 }

src/stages/welcome2/page_welcome2.ts

@@ -4,36 +4,43 @@ import { Container, FederatedPointerEvent, Graphics } from "pixi.js";
 
 export default class Welcome2Scene extends BaseScene {
   stage = new Container();
+  private circle?: Graphics;
+  private goWelcome = (_e: FederatedPointerEvent): void => {
+    if (!this.circle) {
+      return;
+    }
+    this.circle.x += 10;
+    this.changeScene("welcome");
+  };
 
   constructor() {
     super("welcome2", SceneType.Normal);
   }
 
-  layout(): void {
-    const circle = new Graphics();
-    circle.label = "circle";
-    circle.circle(0, 0, 32);
-    circle.fill(0xfb6a8f);
-    circle.x = 130;
-    circle.y = 300;
-    circle.eventMode = "static";
-    circle.cursor = "pointer";
+  protected onSceneLayout(): void {
+    this.circle = new Graphics();
+    this.circle.label = "circle";
+    this.circle.circle(0, 0, 32);
+    this.circle.fill(0xfb6a8f);
+    this.circle.x = 130;
+    this.circle.y = 300;
+    this.circle.eventMode = "static";
+    this.circle.cursor = "pointer";
 
-    const goWelcome = (_e: FederatedPointerEvent) => {
-      circle.x += 10;
-      this.changeScene("welcome");
-    };
-
-    circle.on("touchend", goWelcome);
-    circle.on("mousedown", goWelcome);
-    this.stage.addChild(circle);
+    this.circle.on("touchend", this.goWelcome);
+    this.circle.on("mousedown", this.goWelcome);
+    this.stage.addChild(this.circle);
   }
 
-  onLoad(): void {
+  protected onSceneEnter(): void {
     console.log("onLoad 2");
   }
 
-  onUnLoad(): void {
+  protected onSceneExit(): void {
+    if (this.circle) {
+      this.circle.off("touchend", this.goWelcome);
+      this.circle.off("mousedown", this.goWelcome);
+    }
     console.log("onUnLoad 2");
   }
 }