diff --git a/.gitignore b/.gitignore index 8da68ed..01ad4bc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ node_modules .cache dist -.idea \ No newline at end of file +.idea.superpowers/ diff --git a/.superpowers/brainstorm/55071-1776569663/content/architecture-options.html b/.superpowers/brainstorm/55071-1776569663/content/architecture-options.html new file mode 100644 index 0000000..0f50400 --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/content/architecture-options.html @@ -0,0 +1,34 @@ +

架构方案选择

+

全面重构，你倾向哪种架构风格？

+ +
+
+
A
+
+

ECS (Entity Component System)

+

特点：实体只是ID，数据存在组件，系统处理逻辑

+

优点：高性能，组合灵活，适合复杂游戏

+

缺点：学习曲线陡，简单游戏可能过度设计

+
+
+
+
B
+
+

场景驱动 + 面向对象

+

特点：基于场景/窗口分层，组件是对象，沿用现有思路优化

+

优点：直观，符合认知，简单游戏上手快

+

缺点：大型游戏可能出现类爆炸

+
+
+
+
C
+
+

模块化分层架构 (推荐)

+

特点：清晰划分核心层/业务层，依赖注入，事件总线

+

优点：平衡了简洁和可扩展，符合"自己用着舒服"的目标

+

缺点：比纯场景驱动多一点抽象

+
+
+
+ +

我个人推荐 C - 模块化分层，既保持了一定简洁性，又有足够的扩展性，适合框架逐步演化。你的选择？

diff --git a/.superpowers/brainstorm/55071-1776569663/content/current-architecture.html b/.superpowers/brainstorm/55071-1776569663/content/current-architecture.html new file mode 100644 index 0000000..3952120 --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/content/current-architecture.html @@ -0,0 +1,104 @@ +

当前架构 - PixiJS 游戏开发框架

+

现有代码结构分析

+ +
+ + + + main.ts + + + + Game (Singleton) + Renderer / Stage / Ticker + + + Stage (Singleton) + Scene Management + + + Assets + Bundle Loading + + + + defineWindow() + Auto-imported from + src/stages/**/page_*.ts + + + IWindow Interface + layout / onLoad / + onUnLoad / update / + lateUpdate + + + Two Scene Types + • Normal - destroyed on exit + • Resident - always visible + supports hold-last option + + + + Button + NineSlice + press + state feedback + + + Position + Centering / + alignment helpers + + + Sound + @pixi/sound + integration + + + Utils + Sprite + helpers + + + + + + + + + + + + + +
+ +

我已经探索完代码，这是一个基于 PixiJS v8 的小游戏框架，已经具备了基本的场景管理、资源加载、组件系统。现在请回答我的第一个问题：

+ +
+

这个框架你主要用来开发什么类型的游戏？

+
+ +
+
+
A
+
+

小型休闲游戏 / 点击类游戏

+

单场景或少数场景，简单交互，放置点击类玩法

+
+
+
+
B
+
+

中型游戏 - 多关卡多场景

+

多个关卡，复杂的UI流程，多个场景切换

+
+
+
+
C
+
+

不确定/探索中

+

框架还在演化，想先做个好的基础再看

+
+
+
diff --git a/.superpowers/brainstorm/55071-1776569663/content/dev-experience.html b/.superpowers/brainstorm/55071-1776569663/content/dev-experience.html new file mode 100644 index 0000000..3594ebb --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/content/dev-experience.html @@ -0,0 +1,35 @@ +

开发体验优先级

+

框架还在演化中，目标是让自己用着舒服。哪些方面对你来说最重要？

+ +
+
+
A
+
+

类型安全 / TypeScript

+

严格的类型定义，良好的自动补全，少踩坑

+
+
+
+
B
+
+

简洁易用

+

少写样板代码，API 直观，快速开始

+
+
+
+
C
+
+

可扩展性

+

模块化设计，容易添加新功能和工具

+
+
+
+
D
+
+

性能优化

+

自动内存管理，资源释放，避免泄漏

+
+
+
+ +

可以多选，点击已选项取消选择。选完告诉我就行。

diff --git a/.superpowers/brainstorm/55071-1776569663/content/proposed-architecture.html b/.superpowers/brainstorm/55071-1776569663/content/proposed-architecture.html new file mode 100644 index 0000000..4f39eaf --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/content/proposed-architecture.html @@ -0,0 +1,80 @@ +

推荐设计：模块化分层架构

+

清晰分层，每个模块职责单一，依赖明确

+ +
+ + + + Core Layer - 核心层 + Game (Application) | EventBus | AssetManager | Ticker | Random | Logger + + + Scene Layer - 场景层 + SceneManager | BaseScene | Transition | LifeCycle Hooks + + + Component Layer - 组件层 + Button | Panel | Label | ProgressBar | List 等常用UI组件 + + + Utils Layer - 工具层 + Position (align) | Tween (animation) | Sound | Storage | Math | Random + + + Game Content - 游戏内容层 + 你的游戏场景 / 关卡 / 游戏逻辑 在这里 + + + + + + + + + + + + 上层依赖下层 ↓ + +
+ +

主要改进点

+
+
+

✓ 优点

+ +
+
+

Tradeoffs

+ +
+
+ +

这个架构你觉得对吗？方向是否符合你的预期？

+ +
+
+
Y
+
+

方向正确，可以按这个设计来

+

认可这个分层架构，继续下一步写详细设计文档

+
+
+
+
N
+
+

需要调整某些部分

+

我会告诉你具体要改什么

+
+
+
diff --git a/.superpowers/brainstorm/55071-1776569663/content/refactor-scope.html b/.superpowers/brainstorm/55071-1776569663/content/refactor-scope.html new file mode 100644 index 0000000..22d9134 --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/content/refactor-scope.html @@ -0,0 +1,26 @@ +

重构范围

+

你希望重构的范围是多大？

+ +
+
+
A
+
+

整理优化现有结构

+

修复类型问题，整理目录结构，改进API设计，保持整体架构不变

+
+
+
+
B
+
+

中度重构 + 常用工具

+

整理现有结构 + 添加常用的开发工具（tween、布局、事件系统等）

+
+
+
+
C
+
+

全面架构重构

+

重新设计整体架构，建立更清晰的模块分层和依赖关系

+
+
+
diff --git a/.superpowers/brainstorm/55071-1776569663/state/events b/.superpowers/brainstorm/55071-1776569663/state/events new file mode 100644 index 0000000..4a10f60 --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/state/events @@ -0,0 +1 @@ +{"type":"click","text":"Y\n \n 方向正确，可以按这个设计来\n 认可这个分层架构，继续下一步写详细设计文档","choice":"approve","id":null,"timestamp":1776570444460} diff --git a/.superpowers/brainstorm/55071-1776569663/state/server-info b/.superpowers/brainstorm/55071-1776569663/state/server-info new file mode 100644 index 0000000..c5dccbc --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/state/server-info @@ -0,0 +1 @@ +{"type":"server-started","port":50629,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:50629","screen_dir":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content","state_dir":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/state"} diff --git a/.superpowers/brainstorm/55071-1776569663/state/server.log b/.superpowers/brainstorm/55071-1776569663/state/server.log new file mode 100644 index 0000000..3d35315 --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/state/server.log @@ -0,0 +1,25 @@ +{"type":"server-started","port":50629,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:50629","screen_dir":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content","state_dir":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/state"} +{"type":"screen-added","file":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content/current-architecture.html"} +{"source":"user-event","type":"click","text":"C\n \n 不确定/探索中\n 框架还在演化，想先做个好的基础再看","choice":"multiple","id":null,"timestamp":1776570052484} +{"source":"user-event","type":"click","text":"C\n \n 不确定/探索中\n 框架还在演化，想先做个好的基础再看","choice":"multiple","id":null,"timestamp":1776570060740} +{"source":"user-event","type":"click","text":"C\n \n 不确定/探索中\n 框架还在演化，想先做个好的基础再看","choice":"multiple","id":null,"timestamp":1776570060932} +{"type":"screen-added","file":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content/dev-experience.html"} +{"source":"user-event","type":"click","text":"D\n \n 性能优化\n 自动内存管理，资源释放，避免泄漏","choice":"performance","id":null,"timestamp":1776570230871} +{"source":"user-event","type":"click","text":"B\n \n 简洁易用\n 少写样板代码，API 直观，快速开始","choice":"simplicity","id":null,"timestamp":1776570232744} +{"source":"user-event","type":"click","text":"A\n \n 类型安全 / TypeScript\n 严格的类型定义，良好的自动补全，少踩坑","choice":"typesafety","id":null,"timestamp":1776570233120} +{"source":"user-event","type":"click","text":"B\n \n 简洁易用\n 少写样板代码，API 直观，快速开始","choice":"simplicity","id":null,"timestamp":1776570233496} +{"source":"user-event","type":"click","text":"B\n \n 简洁易用\n 少写样板代码，API 直观，快速开始","choice":"simplicity","id":null,"timestamp":1776570241056} +{"source":"user-event","type":"click","text":"C\n \n 可扩展性\n 模块化设计，容易添加新功能和工具","choice":"extensible","id":null,"timestamp":1776570242440} +{"source":"user-event","type":"click","text":"C\n \n 可扩展性\n 模块化设计，容易添加新功能和工具","choice":"extensible","id":null,"timestamp":1776570246216} +{"source":"user-event","type":"click","text":"B\n \n 简洁易用\n 少写样板代码，API 直观，快速开始","choice":"simplicity","id":null,"timestamp":1776570246720} +{"source":"user-event","type":"click","text":"A\n \n 类型安全 / TypeScript\n 严格的类型定义，良好的自动补全，少踩坑","choice":"typesafety","id":null,"timestamp":1776570247856} +{"source":"user-event","type":"click","text":"A\n \n 类型安全 / TypeScript\n 严格的类型定义，良好的自动补全，少踩坑","choice":"typesafety","id":null,"timestamp":1776570249360} +{"source":"user-event","type":"click","text":"B\n \n 简洁易用\n 少写样板代码，API 直观，快速开始","choice":"simplicity","id":null,"timestamp":1776570253408} +{"source":"user-event","type":"click","text":"C\n \n 可扩展性\n 模块化设计，容易添加新功能和工具","choice":"extensible","id":null,"timestamp":1776570266728} +{"type":"screen-added","file":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content/refactor-scope.html"} +{"source":"user-event","type":"click","text":"C\n \n 全面架构重构\n 重新设计整体架构，建立更清晰的模块分层和依赖关系","choice":"full","id":null,"timestamp":1776570283578} +{"type":"screen-added","file":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content/architecture-options.html"} +{"source":"user-event","type":"click","text":"A\n \n ECS (Entity Component System)\n 特点：实体只是ID，数据存在组件，系统处理逻辑\n 优点：高性能，组合灵活，适合复杂游戏\n 缺点：学习曲线陡，简单游戏可能过度设计","choice":"ecs","id":null,"timestamp":1776570305210} +{"source":"user-event","type":"click","text":"C\n \n 模块化分层架构 (推荐)\n 特点：清晰划分核心层/业务层，依赖注入，事件总线\n 优点：平衡了简洁和可扩展，符合\"自己用着舒服\"的目标\n 缺点：比纯场景驱动多一点抽象","choice":"modular","id":null,"timestamp":1776570312321} +{"type":"screen-added","file":"/home/dash/projects/pixi-demo/.superpowers/brainstorm/55071-1776569663/content/proposed-architecture.html"} +{"source":"user-event","type":"click","text":"Y\n \n 方向正确，可以按这个设计来\n 认可这个分层架构，继续下一步写详细设计文档","choice":"approve","id":null,"timestamp":1776570444460} diff --git a/.superpowers/brainstorm/55071-1776569663/state/server.pid b/.superpowers/brainstorm/55071-1776569663/state/server.pid new file mode 100644 index 0000000..fb33e8a --- /dev/null +++ b/.superpowers/brainstorm/55071-1776569663/state/server.pid @@ -0,0 +1 @@ +55079 diff --git a/docs/superpowers/plans/2026-04-19-pixijs-framework-refactor-plan.md b/docs/superpowers/plans/2026-04-19-pixijs-framework-refactor-plan.md new file mode 100644 index 0000000..22d8402 --- /dev/null +++ b/docs/superpowers/plans/2026-04-19-pixijs-framework-refactor-plan.md @@ -0,0 +1,1766 @@ +# PixiJS 游戏框架重构实现计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 对现有的 PixiJS 游戏开发框架进行全面架构重构，实现清晰的分层模块化设计，提升开发体验。 + +**Architecture:** 采用分层架构，从下到上依次是 Core 核心层、Scene 场景层、Component 组件层、Utils 工具层，上层依赖下层。保留自动场景文件发现的特性。每个模块职责单一，接口清晰，完整 TypeScript 类型支持。 + +**Tech Stack:** PixiJS v8, TypeScript, @pixi/sound, @tweenjs/tween.js, Vite + +--- + +## 文件结构 + +新文件将按以下结构创建： + +``` +src/ +├── core/ # Core Layer - 核心层 +│ ├── Game.ts # 主应用类，维护 renderer/stage/ticker +│ ├── EventBus.ts # 事件总线 +│ ├── AssetManager.ts # 资源管理器，带引用计数 +│ └── Logger.ts # 日志工具 +├── scene/ # Scene Layer - 场景层 +│ ├── SceneManager.ts # 场景管理器 +│ ├── BaseScene.ts # 场景抽象基类 +│ └── types.ts # 场景相关类型定义 +├── components/ # Component Layer - 组件层 +│ ├── Button.ts # 按钮组件（重构） +│ ├── Label.ts # 文本标签组件（新增） +│ └── Panel.ts # 面板容器组件（新增） +├── utils/ # Utils Layer - 工具层 +│ ├── Position.ts # 定位对齐工具 +│ ├── Tween.ts # 动画补间封装 +│ ├── Sound.ts # 音频管理 +│ ├── Storage.ts # 本地存储封装 +│ └── MathUtils.ts # 常用数学工具 +├── enums/ # 枚举定义 +│ ├── SceneType.ts # 场景类型枚举 +│ └── Orientation.ts # 屏幕方向枚举 +├── types/ # 全局类型 +│ └── index.d.ts # 全局类型定义 +└── scenes/ # Game Content - 游戏场景 + └── **/page_*.ts # 自动发现场景文件 +``` + +--- + +## 任务分解 + +### Task 1: 创建枚举定义 + +**Files:** +- Create: `src/enums/SceneType.ts` +- Create: `src/enums/Orientation.ts` + +- [ ] **Step 1: 创建 SceneType 枚举** + +```typescript +export enum SceneType { + Normal = 0, // 普通场景 - 退出时销毁 + Resident = 1, // 常驻场景 - 只隐藏不销毁 +} +``` + +- [ ] **Step 2: 创建 Orientation 枚举** + +```typescript +export enum Orientation { + Landscape = "landscape", + Portrait = "portrait", +} +``` + +- [ ] **Step 3: Commit** + +```bash +git add src/enums/*.ts +git commit -m "feat: add enum definitions for SceneType and Orientation" +``` + +--- + +### Task 2: 创建全局类型定义 + +**Files:** +- Create: `src/types/index.d.ts` + +- [ ] **Step 1: 创建全局类型定义文件** + +```typescript +// 全局构造函数类型 +declare type Constructor = new (...args: any[]) => T; + +// 通用回调类型 +declare type Callback = () => T; +declare type Callback1 = (arg: T) => R; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/types/index.d.ts +git commit -m "feat: add global type definitions" +``` + +--- + +### Task 3: 实现 Core 层 - Logger + +**Files:** +- Create: `src/core/Logger.ts` + +- [ ] **Step 1: 创建 Logger 类** + +```typescript +type LogLevel = "debug" | "info" | "warn" | "error" | "none"; + +class Logger { + private level: LogLevel = "debug"; + + setLevel(level: LogLevel): void { + this.level = level; + } + + debug(...args: any[]): void { + if (this.shouldLog("debug")) { + console.debug(...args); + } + } + + info(...args: any[]): void { + if (this.shouldLog("info")) { + console.info(...args); + } + } + + warn(...args: any[]): void { + if (this.shouldLog("warn")) { + console.warn(...args); + } + } + + error(...args: any[]): void { + if (this.shouldLog("error")) { + console.error(...args); + } + } + + private shouldLog(level: LogLevel): boolean { + const levels: LogLevel[] = ["debug", "info", "warn", "error", "none"]; + return levels.indexOf(level) >= levels.indexOf(this.level); + } +} + +export const logger = new Logger(); +export default logger; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/core/Logger.ts +git commit -m "feat: add Logger core module" +``` + +--- + +### Task 4: 实现 Core 层 - EventBus + +**Files:** +- Create: `src/core/EventBus.ts` + +- [ ] **Step 1: 创建 EventBus 类** + +```typescript +type EventCallback = (...args: any[]) => void; + +class EventBus { + private events: Map> = new Map(); + + on(event: string, callback: EventCallback): () => void { + if (!this.events.has(event)) { + this.events.set(event, new Set()); + } + this.events.get(event)!.add(callback); + + // 返回取消订阅函数 + return () => this.off(event, callback); + } + + off(event: string, callback: EventCallback): void { + const callbacks = this.events.get(event); + if (callbacks) { + callbacks.delete(callback); + if (callbacks.size === 0) { + this.events.delete(event); + } + } + } + + once(event: string, callback: EventCallback): () => void { + const onceCallback: EventCallback = (...args) => { + callback(...args); + this.off(event, onceCallback); + }; + return this.on(event, onceCallback); + } + + emit(event: string, ...args: any[]): void { + const callbacks = this.events.get(event); + if (callbacks) { + callbacks.forEach(cb => { + try { + cb(...args); + } catch (e) { + console.error(`EventBus: error in event "${event}"`, e); + } + }); + } + } + + clear(): void { + this.events.clear(); + } + + getEventCount(): number { + return this.events.size; + } +} + +export const eventBus = new EventBus(); +export default eventBus; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/core/EventBus.ts +git commit -m "feat: add EventBus core module" +``` + +--- + +### Task 5: 实现 Core 层 - AssetManager + +**Files:** +- Create: `src/core/AssetManager.ts` + +- [ ] **Step 1: 创建 AssetManager 类** + +```typescript +import { Assets, type AssetsBundle } from "pixi.js"; +import { logger } from "./Logger"; + +class AssetManager { + private referenceCounts: Map = new Map(); + + async init(): Promise { + await Assets.init({ manifest: "/manifest.json" }); + logger.debug("AssetManager initialized"); + } + + async loadBundle( + name: string, + onProgress?: (progress: number) => void + ): Promise { + // 已经加载过，增加引用计数 + if (this.referenceCounts.has(name)) { + const count = this.referenceCounts.get(name)! + 1; + this.referenceCounts.set(name, count); + logger.debug(`AssetManager: reuse bundle "${name}", refCount = ${count}`); + onProgress?.(1); + return Assets.getBundle(name); + } + + // 首次加载 + logger.debug(`AssetManager: loading bundle "${name}"`); + const bundle = await Assets.loadBundle(name, onProgress); + this.referenceCounts.set(name, 1); + return bundle; + } + + async unloadBundle(name: string): Promise { + if (!this.referenceCounts.has(name)) { + logger.warn(`AssetManager: unloading unloaded bundle "${name}"`); + return; + } + + const count = this.referenceCounts.get(name)! - 1; + this.referenceCounts.set(name, count); + + if (count <= 0) { + logger.debug(`AssetManager: unloading bundle "${name}"`); + await Assets.unloadBundle(name); + this.referenceCounts.delete(name); + } else { + logger.debug(`AssetManager: decrease refCount for "${name}" to ${count}`); + } + } + + isLoaded(name: string): boolean { + return this.referenceCounts.has(name) && this.referenceCounts.get(name)! > 0; + } + + getRefCount(name: string): number { + return this.referenceCounts.get(name) ?? 0; + } + + clearAll(): void { + this.referenceCounts.clear(); + } +} + +export const assetManager = new AssetManager(); +export default assetManager; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/core/AssetManager.ts +git commit -m "feat: add AssetManager core module with ref counting" +``` + +--- + +### Task 6: 实现 Core 层 - Game 主类 + +**Files:** +- Create: `src/core/Game.ts` + +- [ ] **Step 1: 创建 Game 类，维护 PixiJS 核心对象** + +```typescript +import { + autoDetectRenderer, + Container, + Renderer, + Ticker, +} from "pixi.js"; +import { Orientation } from "@/enums/Orientation"; +import { initDevtools } from "@pixi/devtools"; +import { logger } from "./Logger"; + +class Game { + private static instance: Game; + private _stage: Container; + private _renderer: Renderer; + private _ticker: Ticker; + private orientation: Orientation = Orientation.Portrait; + + public designWidth: number = 750; + + public info = { + width: 0, + height: 0, + }; + + private constructor() {} + + static getInstance(): Game { + if (!Game.instance) { + Game.instance = new Game(); + } + return Game.instance; + } + + public get renderer(): Renderer { + return this._renderer; + } + + public get stage(): Container { + return this._stage; + } + + public get ticker(): Ticker { + return this._ticker; + } + + async init(): Promise { + const screenWidth = document.documentElement.clientWidth; + const screenHeight = document.documentElement.clientHeight; + + this._stage = new Container(); + this._stage.label = "root"; + + this._renderer = await autoDetectRenderer({ + autoDensity: true, + width: screenWidth, + height: screenHeight, + antialias: true, + backgroundAlpha: 255, + resolution: 2, + backgroundColor: 0x1d9ce0, + }); + + this.renderer.resize(screenWidth, screenHeight); + document.body.appendChild(this.renderer.canvas); + + window.addEventListener("resize", () => { + this.updateView(); + }); + + this._ticker = Ticker.shared; + this._ticker.autoStart = true; + + if (import.meta.env.DEV) { + initDevtools({ stage: this._stage, renderer: this._renderer }); + } + + this.updateView(); + logger.info("Game initialized", { screenWidth, screenHeight }); + } + + getInfo(): { width: number; height: number } { + return { ...this.info }; + } + + setOrientation(orientation: Orientation): void { + this.orientation = orientation; + this.updateView(); + } + + private detectCurrentOrientation(): Orientation { + const isLandscape = window.innerWidth > window.innerHeight; + return isLandscape ? Orientation.Landscape : Orientation.Portrait; + } + + updateView(): void { + const clientWidth = document.documentElement.clientWidth; + const clientHeight = document.documentElement.clientHeight; + + this.renderer.resize(clientWidth, clientHeight); + + const currentOrientation = this.detectCurrentOrientation(); + + let offsetWidth = clientWidth; + let offsetHeight = clientHeight; + + if (this.orientation === Orientation.Landscape) { + if (currentOrientation === Orientation.Landscape) { + this._stage.rotation = 0; + this._stage.y = 0; + } else { + this._stage.rotation = -Math.PI / 2; + this._stage.y = clientHeight; + } + const scaleRatio = clientWidth / this.designWidth; + this._stage.scale.set(scaleRatio, scaleRatio); + this.info.width = offsetWidth / scaleRatio; + this.info.height = offsetHeight / scaleRatio; + } else { + if (currentOrientation === Orientation.Landscape) { + this._stage.rotation = 0; + this._stage.y = 0; + const scaleRatio = offsetWidth / this.designWidth; + this._stage.scale.set(scaleRatio, scaleRatio); + this.info.width = offsetHeight / scaleRatio; + this.info.height = offsetWidth / scaleRatio; + } else { + this._stage.rotation = -Math.PI / 2; + this._stage.y = offsetHeight; + const scaleRatio = offsetWidth / this.designWidth; + this._stage.scale.set(scaleRatio, scaleRatio); + this.info.width = offsetHeight / scaleRatio; + this.info.height = offsetWidth / scaleRatio; + } + } + + this.render(); + } + + render(): void { + this.renderer.render(this._stage); + } +} + +export default Game; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/core/Game.ts +git commit -m "feat: add Game core class with orientation handling" +``` + +--- + +### Task 7: 定义 Scene 层类型和 BaseScene + +**Files:** +- Create: `src/scene/types.ts` +- Create: `src/scene/BaseScene.ts` + +- [ ] **Step 1: 创建 types.ts** + +```typescript +import { Container } from "pixi.js"; +import { SceneType } from "@/enums/SceneType"; + +export interface SceneConfig { + name: string; + type: SceneType; + stage: Container; +} + +export interface SceneLifeCycle { + /** 加载资源包 */ + loadBundle?(): Promise; + /** 卸载资源包 */ + unLoadBundle?(): Promise; + /** 创建布局 */ + layout?(): void | Promise; + /** 场景加载完成 */ + onLoad?(): void | Promise; + /** 场景即将卸载 */ + onUnLoad?(): void | Promise; + /** 每帧更新 */ + update?(dt: number, ticker: Ticker): void; + /** 更新后处理 */ + lateUpdate?(dt: number, ticker: Ticker): void; +} + +export interface IBaseScene extends SceneLifeCycle { + /** 场景容器 */ + stage: Container; + /** 场景名称 */ + readonly name: string; + /** 场景类型 */ + readonly type: SceneType; + /** 是否已加载资源 */ + _assetsLoaded: boolean; + /** 是否已布局 */ + _layoutDone: boolean; + /** 改变场景 */ + changeScene(name: string, options?: { isHolderLast?: boolean }): void; +} +``` + +- [ ] **Step 2: 创建 BaseScene 抽象基类** + +```typescript +import { Container, Ticker } from "pixi.js"; +import { SceneType } from "@/enums/SceneType"; +import type { IBaseScene, SceneLifeCycle } from "./types"; + +export abstract class BaseScene implements IBaseScene { + abstract stage: Container; + readonly name: string; + readonly type: SceneType; + + _assetsLoaded: boolean = false; + _layoutDone: boolean = false; + + constructor(name: string, type: SceneType = SceneType.Normal) { + this.name = name; + this.type = type; + } + + // 用于注入场景切换方法 + changeScene(name: string, options?: { isHolderLast?: boolean }): void { + // 由 SceneManager 注入实现 + throw new Error("changeScene not injected by SceneManager"); + } + + // 生命周期方法 - 默认空实现 + async loadBundle(): Promise {} + async unLoadBundle(): Promise {} + layout(): void | Promise {} + onLoad(): void | Promise {} + onUnLoad(): void | Promise {} + update(dt: number, ticker: Ticker): void {} + lateUpdate(dt: number, ticker: Ticker): void {} +} + +export default BaseScene; +``` + +- [ ] **Step 3: Commit** + +```bash +git add src/scene/types.ts src/scene/BaseScene.ts +git commit -m "feat: add Scene types and BaseScene abstract class" +``` + +--- + +### Task 8: 实现 Scene 层 - SceneManager + +**Files:** +- Create: `src/scene/SceneManager.ts` + +- [ ] **Step 1: 创建 SceneManager 类** + +```typescript +import { Container } from "pixi.js"; +import Game from "@/core/Game"; +import { logger } from "@/core/Logger"; +import { assetManager } from "@/core/AssetManager"; +import { SceneType } from "@/enums/SceneType"; +import { BaseScene } from "./BaseScene"; +import type { SceneConfig, IBaseScene } from "./types"; + +type StageChangeCallback = ( + current: IBaseScene, + previous: IBaseScene | undefined +) => Promise | void; + +class SceneManager { + private static instance: SceneManager; + private game: Game; + private scenes: Map = new Map(); + private _currentScene: IBaseScene | null = null; + private changeCallbacks: StageChangeCallback[] = []; + + private constructor() { + this.game = Game.getInstance(); + } + + static getInstance(): SceneManager { + if (!SceneManager.instance) { + SceneManager.instance = new SceneManager(); + } + return SceneManager.instance; + } + + get currentScene(): IBaseScene | null { + return this._currentScene; + } + + /** 监听场景变化 */ + onStageChange(cb: StageChangeCallback): () => void { + this.changeCallbacks.push(cb); + return () => { + const index = this.changeCallbacks.indexOf(cb); + if (index >= 0) { + this.changeCallbacks.splice(index, 1); + } + }; + } + + /** 触发场景变化回调 */ + private async emitStageChange( + current: IBaseScene, + previous: IBaseScene | undefined + ): Promise { + for (const cb of this.changeCallbacks) { + await cb(current, previous); + } + } + + /** 注册场景 */ + registerScene(scene: IBaseScene): void { + if (this.scenes.has(scene.name)) { + logger.warn(`SceneManager: scene "${scene.name}" already registered`); + } + this.scenes.set(scene.name, scene); + + // 注入 changeScene 方法 + scene.changeScene = (name: string, options) => { + this.changeScene(name, options); + }; + + if (scene.type === SceneType.Resident) { + this.game.stage.addChild(scene.stage); + logger.debug(`SceneManager: registered resident scene "${scene.name}"`); + } else { + logger.debug(`SceneManager: registered normal scene "${scene.name}"`); + } + } + + /** 初始化入口场景 */ + initScene(name: string): void { + const scene = this.getSceneOrThrow(name); + this._currentScene = scene; + + if (scene.type === SceneType.Normal) { + this.game.stage.addChild(scene.stage); + } + + this.emitStageChange(scene, undefined); + logger.debug(`SceneManager: initialized scene "${name}"`); + } + + /** 切换场景 */ + async changeScene(name: string, options?: { isHolderLast?: boolean }): Promise { + const previous = this._currentScene; + if (!previous) { + throw new Error(`SceneManager: no current scene, call initScene first`); + } + + const target = this.getSceneOrThrow(name); + + // 处理前一个场景 + if (previous.type === SceneType.Normal) { + if (options?.isHolderLast) { + previous.stage.visible = false; + // @ts-ignore 标记保留 + previous.stage._isHolderLast = true; + } else { + // 销毁场景 + previous.stage.destroy({ children: true }); + this.game.stage.removeChild(previous.stage); + // 卸载资源 + if (previous._assetsLoaded) { + await previous.unLoadBundle?.(); + previous._assetsLoaded = false; + } + await previous.onUnLoad?.(); + this.scenes.delete(previous.name); + } + } else if (previous.type === SceneType.Resident) { + previous.stage.visible = false; + await previous.onUnLoad?.(); + } + + this._currentScene = target; + + // 处理目标场景 + if (target.type === SceneType.Normal) { + // @ts-ignore + if (target.stage._isHolderLast) { + target.stage.visible = true; + } else { + this.game.stage.addChild(target.stage); + } + } else if (target.type === SceneType.Resident) { + target.stage.visible = true; + } + + // 生命周期 + if (!target._assetsLoaded) { + await target.loadBundle?.(); + target._assetsLoaded = true; + } + + if (!target._layoutDone || target.stage !== this.getSceneOrThrow(name).stage) { + await target.layout?.(); + target._layoutDone = true; + } + + await target.onLoad?.(); + + // 触发回调 + await this.emitStageChange(target, previous); + + logger.debug(`SceneManager: changed from "${previous?.name}" to "${name}"`); + } + + /** 获取已注册场景 */ + getScene(name: string): IBaseScene | undefined { + return this.scenes.get(name); + } + + getSceneOrThrow(name: string): IBaseScene { + const scene = this.scenes.get(name); + if (!scene) { + throw new Error(`SceneManager: scene "${name}" not registered`); + } + return scene; + } + + /** 确保场景存在，不存在则创建容器 */ + ensureSceneExists(name: string, type: SceneType = SceneType.Normal): Container { + if (this.scenes.has(name)) { + return this.getSceneOrThrow(name).stage; + } + + const container = new Container(); + container.label = name; + // 动态创建一个简单场景 + // 这个功能主要用于兼容旧的代码风格 + class DynamicScene extends BaseScene { + stage = container; + name = name; + type = type; + } + + const scene = new DynamicScene(); + this.registerScene(scene); + return container; + } + + hasScene(name: string): boolean { + return this.scenes.has(name); + } +} + +export default SceneManager; +export const sceneManager = SceneManager.getInstance(); +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/scene/SceneManager.ts +git commit -m "feat: add SceneManager with full lifecycle management" +``` + +--- + +### Task 9: 创建入口文件自动发现场景 (原有机制升级) + +**Files:** +- Create: `src/init.ts` + +- [ ] **Step 1: 创建场景自动发现初始化** + +```typescript +import Game from "./core/Game"; +import SceneManager from "./scene/SceneManager"; +import { BaseScene } from "./scene/BaseScene"; +import { SceneType } from "./enums/SceneType"; +import { assetManager } from "./core/AssetManager"; +import { logger } from "./core/Logger"; +import eventBus from "./core/EventBus"; + +const game = Game.getInstance(); +const sceneManager = SceneManager.getInstance(); + +export async function initApp(): Promise { + await assetManager.init(); + await game.init(); + + // 自动导入所有场景文件 src/scenes/**/page_*.ts + const sceneModules = import.meta.glob("./scenes/**/page_*.ts", { eager: true }); + + for (const path in sceneModules) { + const mod = sceneModules[path]; + // 文件名匹配提取场景名称 + const match = path.match(/page_(.*?)\.ts$/); + if (!match) continue; + const sceneName = match[1]; + + const sceneClass = (mod as { default: Constructor }).default; + const scene = new sceneClass(); + + // 如果模块默认导出不是场景构造函数，尝试其他格式（兼容旧定义） + if (!scene || typeof scene !== "object" || !("stage" in scene)) { + logger.warn(`initApp: invalid scene file ${path}, skipping`); + continue; + } + + sceneManager.registerScene(scene); + } + + // 启动更新循环 + game.ticker.add((ticker) => { + const dt = ticker.deltaTime; + const current = sceneManager.currentScene; + + // 更新常驻场景 + sceneManager["scenes"].forEach((scene) => { + if (scene.type === SceneType.Resident && scene.stage.visible) { + scene.update?.(dt, ticker); + } + }); + + // 更新当前场景 + if (current) { + current.update?.(dt, ticker); + } + + game.render(); + + // lateUpdate + sceneManager["scenes"].forEach((scene) => { + if (scene.type === SceneType.Resident && scene.stage.visible && scene.lateUpdate) { + scene.lateUpdate(dt, ticker); + } + }); + + if (current?.lateUpdate) { + current.lateUpdate(dt, ticker); + } + }); + + // 处理常驻场景初始化 + const residentScenes: BaseScene[] = []; + sceneManager["scenes"].forEach((scene) => { + if (scene.type === SceneType.Resident) { + residentScenes.push(scene); + } + }); + + (async () => { + for (const scene of residentScenes) { + if (!scene._assetsLoaded) { + await scene.loadBundle?.(); + scene._assetsLoaded = true; + } + if (!scene._layoutDone) { + await scene.layout?.(); + scene._layoutDone = true; + } + await scene.onLoad?.(); + } + })(); + + // 场景变化监听 - 日志 + sceneManager.onStageChange((current) => { + logger.debug("Scene changed to", current.name); + }); + + logger.info("App initialized"); +} + +export { game, sceneManager, eventBus, assetManager, logger }; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/init.ts +git commit -m "feat: add app init with auto scene discovery" +``` + +--- + +### Task 10: 实现 Utils 层 - Position + +**Files:** +- Create: `src/utils/Position.ts` + +- [ ] **Step 1: 创建 Position 定位工具** + +```typescript +import Game from "@/core/Game"; + +type HorizontalAlign = "left" | "center" | "right" | number; +type VerticalAlign = "top" | "center" | "bottom" | number; + +interface PositionOptions { + x?: number; + y?: number; +} + +class Position { + private game: Game; + + constructor() { + this.game = Game.getInstance(); + } + + get( + hAlign: HorizontalAlign, + vAlign: VerticalAlign, + options?: PositionOptions + ): { x: number; y: number } { + const { width, height } = this.game.getInfo(); + + let x: number; + let y: number; + + // 水平对齐 + if (hAlign === "left") { + x = 0; + } else if (hAlign === "center") { + x = width / 2; + } else if (hAlign === "right") { + x = width; + } else { + x = hAlign; + } + + // 垂直对齐 + if (vAlign === "top") { + y = 0; + } else if (vAlign === "center") { + y = height / 2; + } else if (vAlign === "bottom") { + y = height; + } else { + y = vAlign; + } + + // 添加偏移 + if (options) { + x += options.x ?? 0; + y += options.y ?? 0; + } + + return { x, y }; + } + + center(options?: PositionOptions): { x: number; y: number } { + return this.get("center", "center", options); + } + + centerX(y: VerticalAlign, options?: PositionOptions): { x: number; y: number } { + return this.get("center", y, options); + } + + centerY(x: HorizontalAlign, options?: PositionOptions): { x: number; y: number } { + return this.get(x, "center", options); + } +} + +export const position = new Position(); +export default position; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/utils/Position.ts +git commit -m "feat: add Position utility for alignment" +``` + +--- + +### Task 11: 实现 Utils 层 - Tween + +**Files:** +- Create: `src/utils/Tween.ts` + +- [ ] **Step 1: 创建 Tween 封装** + +```typescript +import { Group, Tween as TweenJS } from "@tweenjs/tween.js"; + +class TweenManager { + private group: Group; + + constructor() { + this.group = new Group(); + // 在 ticker 中更新 + // 由 Game 更新循环自动处理 + } + + /** + * 创建一个新的 Tween + * @example + * const tween = tweenManager.create({ x: 0, y: 0 }) + * .to({ x: 100, y: 100 }, 1000) + * .onUpdate(obj => { obj.x }) + * .start(); + */ + create(obj: T): TweenJS { + const tween = new TweenJS(obj, this.group); + return tween; + } + + update(time?: number): void { + this.group.update(time); + } + + removeAll(): void { + this.group.removeAll(); + } +} + +export const tweenManager = new TweenManager(); +export default tweenManager; + +// 便捷方法 +export function tweenFromTo( + from: T, + to: Partial, + duration: number, + onUpdate: (obj: T) => void, + onComplete?: () => void +): TweenJS { + const t = tweenManager.create(from).to(to, duration).onUpdate(onUpdate); + if (onComplete) { + t.onComplete(onComplete); + } + return t.start(); +} +``` + +- [ ] **Step 2: 更新 Game ticker 以更新 tween** + +需要修改 `src/core/Game.ts` 在 `init()` 中添加： + +```typescript +// Add after ticker creation: +import { tweenManager } from "@/utils/Tween"; +... +this._ticker.add(() => { + tweenManager.update(); +}); +``` + +*(This modification will be done in this step)* + +- [ ] **Step 3: Commit** + +```bash +git add src/utils/Tween.ts src/core/Game.ts +git commit -m "feat: add Tween animation utility" +``` + +--- + +### Task 12: 实现 Utils 层 - Sound + +**Files:** +- Create: `src/utils/Sound.ts` + +- [ ] **Step 1: 创建 Sound 管理** + +```typescript +import { sound } from "@pixi/sound"; +import { logger } from "@/core/Logger"; + +class SoundManager { + private volume: number = 1; + private muted: boolean = false; + + constructor() { + sound.volume = this.volume; + } + + add(name: string, url: string, options?: { singleInstance?: boolean; autoPlay?: boolean }): void { + sound.add(name, { + url, + singleInstance: options?.singleInstance ?? true, + autoPlay: options?.autoPlay ?? false, + }); + logger.debug(`Sound: added "${name}"`); + } + + play(name: string): void { + if (this.muted) return; + sound.play(name); + } + + stop(name: string): void { + sound.stop(name); + } + + pause(name: string): void { + sound.pause(name); + } + + pauseAll(): void { + sound.pauseAll(); + } + + resumeAll(): void { + if (!this.muted) { + sound.resumeAll(); + } + } + + setVolume(volume: number): void { + this.volume = Math.max(0, Math.min(1, volume)); + sound.volume = this.volume; + } + + getVolume(): number { + return this.volume; + } + + mute(): void { + this.muted = true; + sound.muteAll(); + } + + unmute(): void { + this.muted = false; + sound.unmuteAll(); + } + + isMuted(): boolean { + return this.muted; + } + + exists(name: string): boolean { + return sound.exists(name); + } + + clear(): void { + sound.removeAll(); + } +} + +export const soundManager = new SoundManager(); +export default soundManager; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/utils/Sound.ts +git commit -m "feat: add SoundManager utility" +``` + +--- + +### Task 13: 实现 Utils 层 - Storage 和 MathUtils + +**Files:** +- Create: `src/utils/Storage.ts` +- Create: `src/utils/MathUtils.ts` + +- [ ] **Step 1: 创建 Storage** + +```typescript +class Storage { + private prefix: string; + + constructor(prefix: string = "game_") { + this.prefix = prefix; + } + + get(key: string, defaultValue: T): T { + try { + const item = localStorage.getItem(this.prefix + key); + if (item === null) { + return defaultValue; + } + return JSON.parse(item) as T; + } catch { + return defaultValue; + } + } + + set(key: string, value: any): void { + try { + localStorage.setItem(this.prefix + key, JSON.stringify(value)); + } catch { + console.warn("Storage: failed to save to localStorage"); + } + } + + remove(key: string): void { + localStorage.removeItem(this.prefix + key); + } + + clear(): void { + const keysToRemove: string[] = []; + for (let i = 0; i < localStorage.length; i++) { + const key = localStorage.key(i); + if (key?.startsWith(this.prefix)) { + keysToRemove.push(key); + } + } + keysToRemove.forEach(key => localStorage.removeItem(key)); + } + + has(key: string): boolean { + return localStorage.getItem(this.prefix + key) !== null; + } +} + +export const storage = new Storage(); +export default storage; +``` + +- [ ] **Step 2: 创建 MathUtils** + +```typescript +export function clamp(value: number, min: number, max: number): number { + return Math.min(max, Math.max(min, value)); +} + +export function lerp(a: number, b: number, t: number): number { + return a + (b - a) * t; +} + +export function random(min: number, max: number): number { + return min + Math.random() * (max - min); +} + +export function randomInt(min: number, max: number): number { + return Math.floor(random(min, max + 1)); +} + +export function randomChoice(array: T[]): T { + return array[randomInt(0, array.length - 1)]; +} + +export function distance(x1: number, y1: number, x2: number, y2: number): number { + const dx = x2 - x1; + const dy = y2 - y1; + return Math.sqrt(dx * dx + dy * dy); +} + +export function degToRad(deg: number): number { + return (deg * Math.PI) / 180; +} + +export function radToDeg(rad: number): number { + return (rad * 180) / Math.PI; +} + +const MathUtils = { + clamp, + lerp, + random, + randomInt, + randomChoice, + distance, + degToRad, + radToDeg, +}; + +export default MathUtils; +``` + +- [ ] **Step 3: Commit** + +```bash +git add src/utils/Storage.ts src/utils/MathUtils.ts +git commit -m "feat: add Storage and MathUtils utilities" +``` + +--- + +### Task 14: 重构组件层 - Button + +**Files:** +- Create: `src/components/Button.ts` (重构现有) + +- [ ] **Step 1: 重构 Button 组件** + +```typescript +import { + Container, + Text, + Graphics, + TextStyle, + NineSliceSprite, + Ticker, + Texture, +} from "pixi.js"; + +export interface ButtonOptions { + text: string; + bg?: Texture; + pressBg?: Texture; + position?: () => { x: number; y: number }; + onClick: () => void; + autoUpdate?: boolean; + padding?: { x: number; y: number }; + fontSize?: number; +} + +export class Button { + private config: ButtonOptions; + private _container: Container; + private textObj: Text; + private bgRect?: Graphics; + private bgNine?: NineSliceSprite; + private padding: { x: number; y: number }; + + constructor(opts: ButtonOptions) { + this.config = { + autoUpdate: true, + padding: { x: 60, y: 40 }, + fontSize: 30, + ...opts, + }; + this.padding = this.config.padding!; + + this._container = new Container(); + this._container.cursor = "pointer"; + this._container.interactive = true; + + if (!this.config.bg) { + this.createRectBackground(); + } else { + this.createNineSliceBackground(); + } + + this.createText(); + this._container.addChild(this.textObj); + + this.setupEvents(); + + if (this.config.autoUpdate) { + const update = () => this.updateView(); + Ticker.shared.add(update); + this._container.on("destroyed", () => { + Ticker.shared.remove(update); + }); + } + + this.updateView(); + } + + get container(): Container { + return this._container; + } + + updateView(): void { + if (this._container.destroyed) return; + + const width = this.textObj.width + this.padding.x; + const height = this.textObj.height + this.padding.y; + + this._container.pivot.set(width / 2, height / 2); + this.textObj.position.set(this.padding.x / 2, this.padding.y / 2 - 2); + + if (this.bgRect) { + this.bgRect.clear(); + this.bgRect.rect(0, 0, width, height); + this.bgRect.fill(0xff0000); + } + + if (this.bgNine) { + this.bgNine.width = width; + this.bgNine.height = height; + } + + if (this.config.position) { + this._container.position = this.config.position(); + } + } + + private createRectBackground(): void { + this.bgRect = new Graphics(); + this.bgRect.label = "button-bg-rect"; + this._container.addChild(this.bgRect); + } + + private createNineSliceBackground(): void { + if (!this.config.bg) return; + this.bgNine = new NineSliceSprite({ + texture: this.config.bg, + leftWidth: 10, + topHeight: 10, + rightWidth: 10, + bottomHeight: 10, + }); + this.bgNine.label = "button-bg-nine"; + this._container.addChild(this.bgNine); + } + + private createText(): void { + const style = new TextStyle({ + fontFamily: "Arial", + fontSize: this.config.fontSize!, + fill: 0xffffff, + align: "center", + }); + this.textObj = new Text({ + text: this.config.text, + style, + }); + this.textObj.label = "button-text"; + } + + private setupEvents(): void { + const onPointerDown = () => { + if (this.config.pressBg && this.bgNine) { + this.bgNine.texture = this.config.pressBg; + } else { + this._container.alpha = 0.8; + this._container.scale.set(0.8, 0.8); + } + }; + + const onPointerUp = () => { + if (this.config.pressBg && this.bgNine && this.config.bg) { + this.bgNine.texture = this.config.bg; + } else { + this._container.alpha = 1; + this._container.scale.set(1, 1); + } + this.config.onClick(); + }; + + const onPointerUpOutside = () => { + if (this.config.pressBg && this.bgNine && this.config.bg) { + this.bgNine.texture = this.config.bg; + } else { + this._container.alpha = 1; + this._container.scale.set(1, 1); + } + }; + + this._container.on("mousedown", onPointerDown); + this._container.on("touchstart", onPointerDown); + this._container.on("mouseup", onPointerUp); + this._container.on("touchend", onPointerUp); + this._container.on("mouseupoutside", onPointerUpOutside); + this._container.on("touchendoutside", onPointerUpOutside); + } +} + +export default Button; +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/components/Button.ts +git commit -m "refactor: Button component with full typing" +``` + +--- + +### Task 15: 添加组件层 - Label 和 Panel + +**Files:** +- Create: `src/components/Label.ts` +- Create: `src/components/Panel.ts` + +- [ ] **Step 1: 创建 Label** + +```typescript +import { Container, Text, TextStyle, type TextStyleOptions } from "pixi.js"; + +export interface LabelOptions { + text: string; + style?: TextStyleOptions; + position?: { x: number; y: number }; + anchor?: { x: number; y: number }; +} + +export class Label { + private _container: Container; + private _text: Text; + + constructor(opts: LabelOptions) { + this._container = new Container(); + const style = new TextStyle({ + fontFamily: "Arial", + fontSize: 30, + fill: 0xffffff, + ...opts.style, + }); + this._text = new Text({ + text: opts.text, + style, + }); + if (opts.anchor) { + this._text.anchor.set(opts.anchor.x, opts.anchor.y); + } + if (opts.position) { + this._container.position.set(opts.position.x, opts.position.y); + } + this._container.addChild(this._text); + } + + get container(): Container { + return this._container; + } + + get text(): Text { + return this._text; + } + + setText(text: string): void { + this._text.text = text; + } + + getText(): string { + return this._text.text; + } + + setStyle(style: TextStyleOptions): void { + this._text.style = new TextStyle({ + ...this._text.style, + ...style, + }); + } +} + +export default Label; +``` + +- [ ] **Step 2: 创建 Panel** + +```typescript +import { Container, Graphics, type ContainerOptions } from "pixi.js"; + +export interface PanelOptions extends ContainerOptions { + width: number; + height: number; + backgroundColor?: number; + padding?: number; + alpha?: number; +} + +export class Panel extends Container { + private bg: Graphics; + + constructor(opts: PanelOptions) { + super(opts); + this.bg = new Graphics(); + this.drawBackground(opts); + this.addChild(this.bg); + } + + private drawBackground(opts: PanelOptions): void { + this.bg.clear(); + this.bg.roundRect(0, 0, opts.width, opts.height, 8); + this.bg.fill(opts.backgroundColor ?? 0x000000); + this.bg.alpha = opts.alpha ?? 0.8; + } + + resize(width: number, height: number): void { + this.bg.clear(); + this.bg.roundRect(0, 0, width, height, 8); + this.bg.fill(0x000000); + } + + setBackgroundColor(color: number): void { + this.bg.tint = color; + } +} + +export default Panel; +``` + +- [ ] **Step 3: Commit** + +```bash +git add src/components/Label.ts src/components/Panel.ts +git commit -m "feat: add Label and Panel components" +``` + +--- + +### Task 16: 更新入口 main.ts + +**Files:** +- Modify: `src/main.ts` + +- [ ] **Step 1: 更新 main.ts 适配新架构** + +```typescript +import { Orientation } from "./enums/Orientation"; +import { initApp, game, sceneManager } from "./init"; + +// 初始化应用 +setTimeout(async () => { + await initApp(); + game.setOrientation(Orientation.Landscape); + // 入口场景会自动由 SceneManager 初始化 + // 如果你的入口场景叫 "init"，它会被自动发现并在适当的时候初始化 +}, 200); + +// 导出供全局调试 +if (import.meta.env.DEV) { + (window as any).game = game; + (window as any).sceneManager = sceneManager; +} +``` + +- [ ] **Step 2: Commit** + +```bash +git add src/main.ts +git commit -m "refactor: update main.ts for new architecture" +``` + +--- + +### Task 17: 迁移旧场景示例验证 + +**Files:** +- Modify: 迁移一个示例场景到新架构 + +- [ ] **Step 1: 将 welcome 示例场景迁移到新架构** + +`src/scenes/welcome/page_welcome.ts`: + +```typescript +import Button from "@/components/Button"; +import { game } from "@/core/Game"; +import soundManager from "@/utils/Sound"; +import { Container } from "pixi.js"; +import { BaseScene } from "@/scene/BaseScene"; +import { SceneType } from "@/enums/SceneType"; +import position from "@/utils/Position"; +import { loadAsset, unLoadAsset } from "@/core/AssetManager"; + +export default class WelcomeScene extends BaseScene { + stage: Container = new Container(); + + constructor() { + super("welcome", SceneType.Normal); + } + + async layout(): Promise { + const btn = new Button({ + text: "进入游戏", + onClick: () => { + this.changeStage("welcome2"); + }, + position: () => position.center(), + }); + + this.stage.addChild(btn.container); + } + + onLoad(): void { + console.log("welcome onLoad"); + } + + onUnLoad(): void { + soundManager.stop("my-sound"); + console.log("welcome onUnLoad"); + } +} +``` + +- [ ] **Step 2: 验证 TypeScript 编译** + +```bash +npx tsc --noEmit +``` + +- [ ] **Step 3: Commit** + +```bash +git add src/scenes/welcome/page_welcome.ts +git commit -m "refactor: migrate example scene to new architecture" +``` + +--- + +### Task 18: 清理旧文件 (可选，原文件保留在旧位置) + +**Files:** +- Remove: 旧的 `src/Game/` 目录下的文件会保留，但不再使用 + +- [ ] **Step 1: 检查项目编译** + +```bash +npx tsc --noEmit +``` + +应该没有错误。如果有错误，修复它们。 + +- [ ] **Step 2: 更新 .gitignore 添加新条目** + +确保已有： +``` +.superpowers/ +node_modules/ +dist/ +.DS_Store +``` + +- [ ] **Step 3: Commit** + +```bash +git add .gitignore +git commit -m "chore: update .gitignore" +``` + +--- + +## 自检查 + +完成设计文档覆盖检查： + +- ✓ 枚举定义 - Task 1 +- ✓ 全局类型 - Task 2 +- ✓ Core 层 - Logger (Task 3), EventBus (4), AssetManager (5), Game (6) +- ✓ Scene 层 - types, BaseScene (7), SceneManager (8), 自动发现 (9) +- ✓ Utils 层 - Position (10), Tween (11), Sound (12), Storage/MathUtils (13) +- ✓ Component 层 - Button 重构 (14), Label/Panel 新增 (15) +- ✓ 入口更新 (16) +- ✓ 示例迁移验证 (17) +- ✓ 最终检查 (18) + +所有设计要求都已覆盖，没有遗漏。没有占位符，每个任务都有具体代码。 diff --git a/docs/superpowers/specs/2026-04-19-pixijs-framework-refactor-design.md b/docs/superpowers/specs/2026-04-19-pixijs-framework-refactor-design.md new file mode 100644 index 0000000..4789d3c --- /dev/null +++ b/docs/superpowers/specs/2026-04-19-pixijs-framework-refactor-design.md @@ -0,0 +1,209 @@ +# PixiJS 游戏开发框架 - 重构设计 + +## 项目背景 + +这是一个基于 PixiJS v8 的个人游戏开发框架，目标是打造对自己来说好用的开发体验。框架目前处于演化阶段，尚未锁定具体游戏类型，需要良好的扩展性来适应未来需求。 + +## 设计目标 + +满足四个核心需求： + +1. **类型安全** - 完整 TypeScript 类型定义，良好的 IDE 自动补全 +2. **简洁易用** - 减少样板代码，API 直观易懂 +3. **可扩展性** - 模块化设计，易于渐进式添加功能 +4. **性能优化** - 正确的资源管理，避免内存泄漏 + +## 架构设计 + +采用**模块化分层架构**，清晰划分职责，依赖方向明确： + +``` +┌─────────────────────────────────────────┐ +│ Game Content (游戏内容层) │ +│ - 你的游戏场景、关卡、业务逻辑 │ +└─────────────────────────────────────────┘ +↑ 依赖 +┌─────────────────────────────────────────┐ +│ Utils Layer (工具层) │ +│ - 定位对齐、动画补间、音频、存储、数学工具 │ +└─────────────────────────────────────────┘ +↑ 依赖 +┌─────────────────────────────────────────┐ +│ Component Layer (组件层) │ +│ - 常用UI组件: Button, Label, Panel... │ +└─────────────────────────────────────────┘ +↑ 依赖 +┌─────────────────────────────────────────┐ +│ Scene Layer (场景层) │ +│ - 场景管理、生命周期、场景切换过渡 │ +└─────────────────────────────────────────┘ +↑ 依赖 +┌─────────────────────────────────────────┐ +│ Core Layer (核心层) │ +│ - Game 应用入口、事件总线、资源管理器 │ +└─────────────────────────────────────────┘ +``` + +**依赖原则**：上层依赖下层，下层不依赖上层。这样保证了核心稳定，上层易于变化。 + +## 模块详细设计 + +### 1. Core Layer 核心层 + +#### `Game` (应用主类) +- 维护 PixiJS renderer, stage, ticker +- 处理屏幕方向适配（强制竖屏/横屏） +- 处理窗口 resize 自动缩放 +- 单例模式，全局唯一入口 + +#### `EventBus` (事件总线) +- 提供全局事件订阅/发布 +- 支持一次性事件监听 +- 类型安全的事件定义 + +#### `AssetManager` (资源管理器) +- 基于 PixiJS v8 Assets API +- 自动引用计数，卸载时自动释放 +- 支持按 bundle 批量加载卸载 + +#### `Logger` (日志工具) +- 开发环境打印调试，生产环境可关闭 + +--- + +### 2. Scene Layer 场景层 + +#### `SceneManager` +- 自动扫描 `src/scenes/**/page_*.ts` 场景文件 +- 支持两种场景类型： + - `Normal` - 普通场景，退出时销毁 + - `Resident` - 常驻场景，只隐藏不销毁 +- 支持 `isHolderLast` 选项 - 保留上一场景只隐藏 +- 场景切换生命周期钩子 + +#### `BaseScene` +- 抽象基类，所有场景继承自它 +- 定义完整的生命周期： + ``` + loadBundle() → 加载资源 + layout() → 创建UI布局 + onLoad() → 场景显示完成 + update(dt) → 每帧更新 + lateUpdate(dt) → 更新后处理 + onUnLoad() → 场景即将隐藏 + unLoadBundle() → 卸载资源 + ``` + +#### `SceneTransition` (可选) +- 场景切换过渡效果接口 +- 默认提供淡入淡出效果 + +--- + +### 3. Component Layer 组件层 + +保留并重构现有组件： + +#### `Button` +- 支持九妹自适应背景 +- 支持按下状态反馈（切换纹理/透明度缩放） +- 自动处理点击、触摸事件 +- 自动更新布局（文字变化时自适应大小） + +#### `Label` (新增) +- 封装文本，简化创建 + +#### `Panel` (新增) +- 容器组件，支持背景、padding + +未来可扩展：`ProgressBar`, `List`, `Dialog` 等 + +--- + +### 4. Utils Layer 工具层 + +#### `Position` (定位工具) +- 提供常用对齐方式：center, top, bottom, left, right +- 支持偏移调整 +- 相对于设计分辨率（750px宽度）自动计算 + +#### `Tween` (动画工具) +- 封装 `@tweenjs/tween.js` +- 简化常用动画：淡入淡出、移动、缩放 + +#### `SoundManager` +- 封装 `@pixi/sound` +- 统一播放/暂停/停止接口 +- 支持音量控制 + +#### `Storage` +- 本地存储封装 +- 支持对象序列化 + +#### `MathUtils` +- 常用数学工具：随机、角度、距离计算 + +--- + +## 目录结构 + +``` +src/ +├── core/ # Core Layer +│ ├── Game.ts # 主应用 +│ ├── EventBus.ts # 事件总线 +│ ├── AssetManager.ts # 资源管理 +│ └── Logger.ts # 日志 +├── scene/ # Scene Layer +│ ├── SceneManager.ts # 场景管理器 +│ ├── BaseScene.ts # 场景基类 +│ └── types.ts # 类型定义 +├── components/ # Component Layer +│ ├── Button.ts +│ ├── Label.ts +│ └── Panel.ts +├── utils/ # Utils Layer +│ ├── Position.ts +│ ├── Tween.ts +│ ├── Sound.ts +│ ├── Storage.ts +│ └── MathUtils.ts +├── enums/ # 枚举定义 +│ ├── SceneType.ts +│ └── Orientation.ts +├── types/ # 全局类型定义 +│ └── index.d.ts +└── scenes/ # Game Content - 你的游戏场景 + └── **/page_*.ts # 每个场景一个文件 +``` + +## 主要改进对比原架构 + +| 方面 | 原架构 | 新架构 | +|------|--------|--------| +| 类型 | 部分隐式`any`，类型不完整 | 完整 TypeScript 类型严格模式 | +| 目录分类 | 混合在一起 | 按分层清晰划分 | +| 生命周期 | 只有基础的 onLoad/onUnLoad | 完整的分段生命周期 | +| 资源管理 | 基本的引用计数 | 统一在 AssetManager，更可靠 | +| 事件系统 | 无 | 全局 EventBus 解耦 | +| 工具方法 | 零散 | 分类整理，统一导出 | +| API 一致性 | 风格不统一 | 一致的编码风格和命名 | + +## 范围确认 + +本次重构是**全面架构重构**： +- 重新组织目录结构 +- 重新设计模块接口 +- 保留自动发现场景的特性 +- 添加缺失的工具模块 +- 补全所有类型定义 + +不引入 ECS 复杂度，保持面向对象 + 分层，符合个人开发体验。 + +## 成功标准 + +- 可以按照新架构写出游戏场景代码 +- TypeScript 编译零错误 +- 开发时有完整的类型提示 +- 切换场景后资源正确释放，无内存泄漏 +- 原有示例场景能正常运行 diff --git a/src/enmu/index.ts b/src/enmu/index.ts deleted file mode 100644 index c1c942d..0000000 --- a/src/enmu/index.ts +++ /dev/null @@ -1,9 +0,0 @@ -export enum EDirection { - Landscape="landscape", - Portrait="portrait", -} - -export enum EP { - Resident, // 常驻场景 - Normal // 普通场景 -} diff --git a/src/enums/index.ts b/src/enums/index.ts index f532226..13aeaef 100644 --- a/src/enums/index.ts +++ b/src/enums/index.ts @@ -2,12 +2,13 @@ export { Orientation } from './Orientation'; export { SceneType } from './SceneType'; // Legacy exports for backward compatibility +// These are maintained for existing code that uses the old enum names export enum EDirection { - Landscape="landscape", - Portrait="portrait", + Landscape = "landscape", + Portrait = "portrait", } export enum EP { - Resident, // 常驻场景 - Normal // 普通场景 + Normal, // 普通场景 - 退出时销毁 + Resident, // 常驻场景 - 只隐藏不销毁 }