refactor: api

packages/boop-game/vite.config.ts

@@ -9,6 +9,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': path.resolve(__dirname, 'src'),
+      'boardgame-phaser': path.resolve(__dirname, '../framework/src/index.ts'),
     },
   },
 });

packages/framework/src/index.ts

@@ -7,9 +7,9 @@ export { spawnEffect } from './spawner';
 export type { Spawner } from './spawner';
 
 // Scene base classes
-export { GameHostScene } from './scenes';
-export type { GameHostSceneOptions } from './scenes';
+export { ReactiveScene, GameHostScene, FadeScene, FADE_SCENE_KEY } from './scenes';
+export type { ReactiveSceneOptions, ReactiveScenePhaserData, SceneController, GameHostSceneOptions, FadeSceneData } from './scenes';
 
 // React ↔ Phaser bridge
-export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig, GameUI } from './ui';
+export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig, GameUI, type PhaserGameContext, type SceneController as PhaserSceneController } from './ui';
 export type { PhaserGameProps, PhaserSceneProps, GameUIOptions } from './ui';

packages/framework/src/scenes/FadeScene.ts

@@ -0,0 +1,83 @@
+import Phaser from 'phaser';
+import { ReactiveScene, type ReactiveScenePhaserData } from './ReactiveScene';
+
+export interface FadeSceneData {
+    [key: string]: unknown;
+}
+
+/**
+ * 处理淡入淡出到黑色的过渡场景
+ */
+export class FadeScene extends ReactiveScene<FadeSceneData> {
+    private overlay!: Phaser.GameObjects.Rectangle;
+    private isFading = false;
+
+    constructor() {
+        super(FADE_SCENE_KEY);
+    }
+
+    create(): void {
+        super.create();
+
+        // 创建黑色遮罩层，覆盖整个游戏区域
+        const game = this.game;
+        this.overlay = this.add.rectangle(
+            0,
+            0,
+            game.scale.width,
+            game.scale.height,
+            0x000000,
+            1
+        ).setOrigin(0)
+            .setAlpha(1)
+            .setDepth(999999)
+            .setInteractive({ useHandCursor: false });
+
+        // 防止遮罩阻挡输入
+        this.overlay.disableInteractive();
+    }
+
+    /**
+     * 淡入（从黑色到透明）
+     * @param duration 动画时长（毫秒）
+     */
+    fadeIn(duration = 300): Promise<void> {
+        return this.fadeTo(0, duration);
+    }
+
+    /**
+     * 淡出（从透明到黑色）
+     * @param duration 动画时长（毫秒）
+     */
+    fadeOut(duration = 300): Promise<void> {
+        return this.fadeTo(1, duration);
+    }
+
+    /**
+     * 淡入淡出到指定透明度
+     */
+    private fadeTo(targetAlpha: number, duration: number): Promise<void> {
+        if (this.isFading) {
+            console.warn('FadeScene: 正在进行过渡动画');
+        }
+
+        this.isFading = true;
+        this.overlay.setAlpha(targetAlpha === 1 ? 0 : 1);
+
+        return new Promise<void>((resolve) => {
+            this.tweens.add({
+                targets: this.overlay,
+                alpha: targetAlpha,
+                duration,
+                ease: 'Linear',
+                onComplete: () => {
+                    this.isFading = false;
+                    resolve();
+                },
+            });
+        });
+    }
+}
+
+// 导出常量供 PhaserGame 使用
+export const FADE_SCENE_KEY = '__fade__';

packages/framework/src/scenes/GameHostScene.ts

@@ -1,22 +1,16 @@
-import Phaser from 'phaser';
-import { effect } from '@preact/signals-core';
 import type { GameHost } from 'boardgame-core';
-import { DisposableBag, type IDisposable } from '../utils';
-
-type CleanupFn = void | (() => void);
+import { ReactiveScene } from './ReactiveScene';
 
 export interface GameHostSceneOptions<TState extends Record<string, unknown>> {
     gameHost: GameHost<TState>;
+    [key: string]: unknown;
 }
 
 export abstract class GameHostScene<TState extends Record<string, unknown>>
-    extends Phaser.Scene
-    implements IDisposable
+    extends ReactiveScene<GameHostSceneOptions<TState>>
 {
-    protected disposables = new DisposableBag();
-    private _gameHost!: GameHost<TState>;
     public get gameHost(): GameHost<TState> {
-        return this._gameHost;
+        return this.initData.gameHost as GameHost<TState>;
     }
 
     public get state(): TState {
@@ -32,24 +26,4 @@ export abstract class GameHostScene<TState extends Record<string, unknown>>
             resolve => tween.once('complete', resolve)
         ));
     }
-
-    init(data: GameHostSceneOptions<TState>): void {
-        this._gameHost = data.gameHost;
-    }
-
-    create(): void {
-        this.events.on('shutdown', this.dispose, this);
-    }
-
-    dispose(): void {
-        this.disposables.dispose();
-    }
-
-    public addDisposable(disposable: IDisposable){
-        this.disposables.add(disposable);
-    }
-    /** 注册响应式监听（场景关闭时自动清理） */
-    public addEffect(fn: () => CleanupFn): void {
-        this.disposables.add(effect(fn));
-    }
 }

packages/framework/src/scenes/ReactiveScene.ts

@@ -0,0 +1,80 @@
+import Phaser from 'phaser';
+import { effect, type ReadonlySignal } from '@preact/signals-core';
+import { DisposableBag, type IDisposable } from '../utils';
+
+type CleanupFn = void | (() => void);
+
+// 前向声明，避免循环导入
+export interface SceneController {
+    launch(sceneKey: string): Promise<void>;
+    currentScene: ReadonlySignal<string | null>;
+    isTransitioning: ReadonlySignal<boolean>;
+}
+
+export interface ReactiveScenePhaserData {
+    phaserGame: ReadonlySignal<{ game: Phaser.Game }>;
+    sceneController: SceneController;
+}
+
+export interface ReactiveSceneOptions<TData extends Record<string, unknown> = {}> {
+    key?: string;
+}
+
+/**
+ * 通用的响应式 Scene 基类
+ * @typeparam TData - 通过 init(data) 接收的数据类型（必须包含 phaserGame 和 sceneController）
+ */
+export abstract class ReactiveScene<TData extends Record<string, unknown> = {}>
+    extends Phaser.Scene
+    implements IDisposable
+{
+    protected disposables = new DisposableBag();
+    private _initData!: TData & ReactiveScenePhaserData;
+
+    /**
+     * 获取通过 init() 注入的数据
+     * 在 create() 阶段保证可用
+     */
+    public get initData(): TData & ReactiveScenePhaserData {
+        return this._initData;
+    }
+
+    /**
+     * 获取 Phaser game 实例的响应式信号
+     */
+    public get phaserGame(): ReadonlySignal<{ game: Phaser.Game }> {
+        return this._initData.phaserGame;
+    }
+
+    /**
+     * 获取场景控制器
+     */
+    public get sceneController(): SceneController {
+        return this._initData.sceneController;
+    }
+
+    constructor(key?: string) {
+        super(key);
+    }
+
+    init(data: TData & ReactiveScenePhaserData): void {
+        this._initData = data;
+    }
+
+    create(): void {
+        this.events.on('shutdown', this.dispose, this);
+    }
+
+    dispose(): void {
+        this.disposables.dispose();
+    }
+
+    public addDisposable(disposable: IDisposable): void {
+        this.disposables.add(disposable);
+    }
+
+    /** 注册响应式监听（场景关闭时自动清理） */
+    public addEffect(fn: () => CleanupFn): void {
+        this.disposables.add(effect(fn));
+    }
+}

packages/framework/src/scenes/index.ts

@@ -1,2 +1,8 @@
+export { ReactiveScene } from './ReactiveScene';
+export type { ReactiveSceneOptions, ReactiveScenePhaserData, SceneController } from './ReactiveScene';
+
+export { FadeScene, FADE_SCENE_KEY } from './FadeScene';
+export type { FadeSceneData } from './FadeScene';
+
 export { GameHostScene } from './GameHostScene';
 export type { GameHostSceneOptions } from './GameHostScene';

packages/framework/src/ui/PhaserBridge.tsx

@@ -3,8 +3,24 @@ import { signal, useSignal, useSignalEffect } from '@preact/signals';
 import { createContext, h } from 'preact';
 import { useContext } from 'preact/hooks';
 import {ReadonlySignal} from "@preact/signals-core";
+import type { ReactiveScene } from '../scenes';
+import { FadeScene as FadeSceneClass, FADE_SCENE_KEY } from '../scenes/FadeScene';
 
-export const phaserContext = createContext<ReadonlySignal<Phaser.Game | undefined>>(signal(undefined));
+export interface SceneController {
+    /** 启动场景（带淡入淡出过渡） */
+    launch(sceneKey: string): Promise<void>;
+    /** 当前活跃场景 key */
+    currentScene: ReadonlySignal<string | null>;
+    /** 是否正在过渡 */
+    isTransitioning: ReadonlySignal<boolean>;
+}
+
+export interface PhaserGameContext {
+    game: Phaser.Game;
+    sceneController: SceneController;
+}
+
+export const phaserContext = createContext<ReadonlySignal<PhaserGameContext> | null>(null);
 
 export const defaultPhaserConfig: Phaser.Types.Core.GameConfig = {
     type: Phaser.AUTO,
@@ -17,11 +33,14 @@ export const defaultPhaserConfig: Phaser.Types.Core.GameConfig = {
 
 export interface PhaserGameProps {
     config?: Partial<Phaser.Types.Core.GameConfig>;
+    /** 初始启动的场景 key */
+    initialScene?: string;
     children?: any;
 }
 
 export function PhaserGame(props: PhaserGameProps) {
-    const gameSignal = useSignal<Phaser.Game>();
+    const gameSignal = useSignal<PhaserGameContext>({ game: undefined!, sceneController: undefined! });
+    const initialSceneLaunched = useSignal(false);
 
     useSignalEffect(() => {
         const config: Phaser.Types.Core.GameConfig = {
@@ -29,14 +48,63 @@ export function PhaserGame(props: PhaserGameProps) {
             ...props.config,
         };
         const phaserGame = new Phaser.Game(config);
-        gameSignal.value = phaserGame;
+
+        // 添加 FadeScene
+        const fadeScene = new FadeSceneClass();
+        phaserGame.scene.add(FADE_SCENE_KEY, fadeScene, false);
+
+        // 创建 SceneController
+        const currentScene = signal<string | null>(null);
+        const isTransitioning = signal(false);
+
+        const sceneController: SceneController = {
+            async launch(sceneKey: string) {
+                if (isTransitioning.value) {
+                    console.warn('SceneController: 正在进行场景切换');
+                    return;
+                }
+
+                isTransitioning.value = true;
+                const fade = phaserGame.scene.getScene(FADE_SCENE_KEY) as FadeSceneClass;
+
+                // 淡出到黑色
+                await fade.fadeOut(300);
+
+                // 停止当前场景
+                if (currentScene.value) {
+                    phaserGame.scene.stop(currentScene.value);
+                }
+
+                // 启动新场景
+                phaserGame.scene.start(sceneKey);
+                currentScene.value = sceneKey;
+
+                // 淡入
+                await fade.fadeIn(300);
+                isTransitioning.value = false;
+            },
+            currentScene,
+            isTransitioning,
+        };
+
+        gameSignal.value = { game: phaserGame, sceneController };
 
         return () => {
-            gameSignal.value = undefined;
+            gameSignal.value = { game: undefined!, sceneController: undefined! };
+            initialSceneLaunched.value = false;
             phaserGame.destroy(true);
         };
     });
 
+    // 启动初始场景
+    useSignalEffect(() => {
+        const ctx = gameSignal.value;
+        if (!initialSceneLaunched.value && props.initialScene && ctx?.sceneController) {
+            initialSceneLaunched.value = true;
+            ctx.sceneController.launch(props.initialScene);
+        }
+    });
+
     return (
         <div id="phaser-container" className="w-full h-full">
             <phaserContext.Provider value={gameSignal}>
@@ -46,30 +114,41 @@ export function PhaserGame(props: PhaserGameProps) {
     );
 }
 
-export interface PhaserSceneProps {
+export interface PhaserSceneProps<TData extends Record<string, unknown> = {}> {
     sceneKey: string;
-    scene: Phaser.Scene;
-    autoStart: boolean;
-    data?: object;
+    scene: ReactiveScene<TData>;
+    data?: TData;
     children?: any;
 }
 
-export const phaserSceneContext = createContext<ReadonlySignal<Phaser.Scene | undefined>>(signal(undefined));
-export function PhaserScene(props: PhaserSceneProps) {
-    const context = useContext(phaserContext);
-    const sceneSignal = useSignal<Phaser.Scene>();
+export const phaserSceneContext = createContext<ReadonlySignal<ReactiveScene> | null>(null);
+export function PhaserScene<TData extends Record<string, unknown> = {}>(props: PhaserSceneProps<TData>) {
+    const phaserGameSignal = useContext(phaserContext);
+    const sceneSignal = useSignal<ReactiveScene<TData>>();
 
     useSignalEffect(() => {
-        const game = context.value;
-        if (!game) return;
+        if (!phaserGameSignal) return;
+        const ctx = phaserGameSignal.value;
+        if (!ctx?.game) return;
+
+        const game = ctx.game;
+        const initData = {
+            ...props.data,
+            phaserGame: phaserGameSignal,
+            sceneController: ctx.sceneController,
+        };
+
+        // 注册场景但不启动
+        if (!game.scene.getScene(props.sceneKey)) {
+            game.scene.add(props.sceneKey, props.scene, false, initData);
+        }
+        sceneSignal.value = props.scene;
 
-        game.scene.add(props.sceneKey, props.scene, props.autoStart, props.data);
-        sceneSignal.value = game.scene.getScene(props.sceneKey);
         return () => {
             sceneSignal.value = undefined;
-            game.scene.remove(props.sceneKey);
+            // 不在这里移除场景，让 SceneController 管理生命周期
         };
     });
 
-    return <phaserSceneContext.Provider value={sceneSignal}>{props.children}</phaserSceneContext.Provider>;
+    return <phaserSceneContext.Provider value={sceneSignal as ReadonlySignal<ReactiveScene>}>{props.children}</phaserSceneContext.Provider>;
 }

packages/framework/src/ui/index.ts

@@ -1,5 +1,5 @@
 export { GameUI } from './GameUI';
 export type { GameUIOptions } from './GameUI';
 
-export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig } from './PhaserBridge';
+export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig, type PhaserGameContext, type SceneController } from './PhaserBridge';
 export type { PhaserGameProps, PhaserSceneProps } from './PhaserBridge';

packages/onitama-game/vite.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': path.resolve(__dirname, 'src'),
+      'boardgame-phaser': path.resolve(__dirname, '../framework/src/index.ts'),
     },
   },
 });

packages/regicide-game/vite.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': resolve(__dirname, 'src'),
+      'boardgame-phaser': resolve(__dirname, '../framework/src/index.ts'),
     },
   },
 });

packages/sample-game/src/main.tsx

@@ -1,13 +1,11 @@
 import { h } from 'preact';
 import { GameUI } from 'boardgame-phaser';
-import * as gameModule from './game/tic-tac-toe';
 import './style.css';
 import App from "@/ui/App";
-import {GameScene} from "@/scenes/GameScene";
 
 const ui = new GameUI({
   container: document.getElementById('ui-root')!,
-  root: <App gameModule={gameModule} gameScene={GameScene}/>,
+  root: <App/>,
 });
 
 ui.mount();

packages/sample-game/src/scenes/GameScene.ts

@@ -13,6 +13,9 @@ export class GameScene extends GameHostScene<TicTacToeState> {
   private gridGraphics!: Phaser.GameObjects.Graphics;
   private turnText!: Phaser.GameObjects.Text;
   private winnerOverlay?: Phaser.GameObjects.Container;
+  private menuButton!: Phaser.GameObjects.Container;
+  private menuButtonText!: Phaser.GameObjects.Text;
+  private menuButtonBg!: Phaser.GameObjects.Rectangle;
 
   constructor() {
     super('GameScene');
@@ -24,6 +27,7 @@ export class GameScene extends GameHostScene<TicTacToeState> {
     this.boardContainer = this.add.container(0, 0);
     this.gridGraphics = this.add.graphics();
     this.drawGrid();
+    this.createMenuButton();
 
     this.disposables.add(spawnEffect(new TicTacToePartSpawner(this)));
 
@@ -49,6 +53,42 @@ export class GameScene extends GameHostScene<TicTacToeState> {
     return !!this.state.board.partMap[`${row},${col}`];
   }
 
+  private createMenuButton(): void {
+    const buttonX = this.game.scale.width - 80;
+    const buttonY = 30;
+
+    this.menuButtonBg = this.add.rectangle(buttonX, buttonY, 120, 40, 0x6b7280)
+      .setInteractive({ useHandCursor: true });
+
+    this.menuButtonText = this.add.text(buttonX, buttonY, 'Menu', {
+      fontSize: '18px',
+      fontFamily: 'Arial',
+      color: '#ffffff',
+    }).setOrigin(0.5);
+
+    this.menuButton = this.add.container(buttonX, buttonY, [
+      this.menuButtonBg,
+      this.menuButtonText,
+    ]);
+
+    // 按钮交互
+    this.menuButtonBg.on('pointerover', () => {
+      this.menuButtonBg.setFillStyle(0x4b5563);
+    });
+
+    this.menuButtonBg.on('pointerout', () => {
+      this.menuButtonBg.setFillStyle(0x6b7280);
+    });
+
+    this.menuButtonBg.on('pointerdown', () => {
+      this.goToMenu();
+    });
+  }
+
+  private async goToMenu(): Promise<void> {
+    await this.sceneController.launch('MenuScene');
+  }
+
   private setupInput(): void {
     for (let row = 0; row < BOARD_SIZE; row++) {
       for (let col = 0; col < BOARD_SIZE; col++) {

packages/sample-game/src/scenes/MenuScene.ts

@@ -0,0 +1,84 @@
+import { ReactiveScene } from 'boardgame-phaser';
+
+export class MenuScene extends ReactiveScene {
+  private titleText!: Phaser.GameObjects.Text;
+  private startButton!: Phaser.GameObjects.Container;
+  private startButtonText!: Phaser.GameObjects.Text;
+  private startButtonBg!: Phaser.GameObjects.Rectangle;
+
+  constructor() {
+    super('MenuScene');
+  }
+
+  create(): void {
+    super.create();
+
+    const centerX = this.game.scale.width / 2;
+    const centerY = this.game.scale.height / 2;
+
+    // 标题
+    this.titleText = this.add.text(centerX, centerY - 100, 'Tic-Tac-Toe', {
+      fontSize: '48px',
+      fontFamily: 'Arial',
+      color: '#1f2937',
+    }).setOrigin(0.5);
+
+    // 添加标题动画
+    this.titleText.setScale(0);
+    this.tweens.add({
+      targets: this.titleText,
+      scale: 1,
+      duration: 600,
+      ease: 'Back.easeOut',
+    });
+
+    // 开始按钮
+    this.startButtonBg = this.add.rectangle(centerX, centerY + 40, 200, 60, 0x3b82f6)
+      .setInteractive({ useHandCursor: true });
+
+    this.startButtonText = this.add.text(centerX, centerY + 40, 'Start Game', {
+      fontSize: '24px',
+      fontFamily: 'Arial',
+      color: '#ffffff',
+    }).setOrigin(0.5);
+
+    this.startButton = this.add.container(centerX, centerY + 40, [
+      this.startButtonBg,
+      this.startButtonText,
+    ]);
+
+    // 按钮交互
+    this.startButtonBg.on('pointerover', () => {
+      this.startButtonBg.setFillStyle(0x2563eb);
+      this.tweens.add({
+        targets: this.startButton,
+        scale: 1.05,
+        duration: 100,
+      });
+    });
+
+    this.startButtonBg.on('pointerout', () => {
+      this.startButtonBg.setFillStyle(0x3b82f6);
+      this.tweens.add({
+        targets: this.startButton,
+        scale: 1,
+        duration: 100,
+      });
+    });
+
+    this.startButtonBg.on('pointerdown', () => {
+      this.startGame();
+    });
+
+    // 副标题
+    this.add.text(centerX, centerY + 140, 'Click to start playing', {
+      fontSize: '16px',
+      fontFamily: 'Arial',
+      color: '#6b7280',
+    }).setOrigin(0.5);
+  }
+
+  private async startGame(): Promise<void> {
+    await this.sceneController.launch('GameScene');
+  }
+}

packages/sample-game/src/ui/App.tsx

@@ -1,36 +1,22 @@
-import {useComputed} from '@preact/signals';
-import { createGameHost, type GameModule } from 'boardgame-core';
-import Phaser from 'phaser';
-import { h } from 'preact';
-import { PhaserGame, PhaserScene } from 'boardgame-phaser';
+import { h } from 'preact';
+import {PhaserGame, PhaserScene } from 'boardgame-phaser';
+import {MenuScene} from "@/scenes/MenuScene";
+import {useMemo} from "preact/hooks";
+import * as gameModule from '../game/tic-tac-toe';
+import {GameScene} from "@/scenes/GameScene";
+import {createGameHost} from "boardgame-core";
 
-export default function App<TState extends Record<string, unknown>>(props: { gameModule: GameModule<TState>, gameScene: { new(): Phaser.Scene } }) {
-
-    const gameHost = useComputed(() => {
-        const gameHost = createGameHost(props.gameModule);
-        return { gameHost };
-    });
-
-    const scene = useComputed(() => new props.gameScene());
-
-    const handleReset = () => {
-        gameHost.value.gameHost.start();
-    };
-    const label = useComputed(() => gameHost.value.gameHost.status.value === 'running' ? 'Restart' : 'Start');
+export default function App() {
+    const gameHost = useMemo(() => createGameHost(gameModule), []);
+    const gameScene = useMemo(() => new GameScene(), []);
+    const menuScene = useMemo(() => new MenuScene(), []);
 
     return (
         <div className="flex flex-col h-screen">
-            <div className="p-4 bg-gray-100 border-t border-gray-200">
-                <button
-                    onClick={handleReset}
-                    className="px-6 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:bg-gray-400 disabled:cursor-not-allowed transition-colors font-medium"
-                >
-                    {label}
-                </button>
-            </div>
             <div className="flex-1 flex relative justify-center items-center">
-                <PhaserGame>
-                    <PhaserScene sceneKey="GameScene" scene={scene.value} autoStart data={gameHost.value} />
+                <PhaserGame initialScene="MenuScene">
+                    <PhaserScene sceneKey="MenuScene" scene={menuScene} />
+                    <PhaserScene sceneKey="GameScene" scene={gameScene} data={{gameHost}}/>
                 </PhaserGame>
             </div>
         </div>

packages/sample-game/vite.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': path.resolve(__dirname, 'src'),
+      'boardgame-phaser': path.resolve(__dirname, '../framework/src/index.ts'),
     },
   },
 });