# 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 编译零错误
- 开发时有完整的类型提示
- 切换场景后资源正确释放，无内存泄漏
- 原有示例场景能正常运行