7.2 KiB

Raw Blame History

PixiJS 游戏开发框架 - 重构设计

项目背景

这是一个基于 PixiJS v8 的个人游戏开发框架，目标是打造对自己来说好用的开发体验。框架目前处于演化阶段，尚未锁定具体游戏类型，需要良好的扩展性来适应未来需求。

设计目标

满足四个核心需求：

类型安全 - 完整 TypeScript 类型定义，良好的 IDE 自动补全
简洁易用 - 减少样板代码，API 直观易懂
可扩展性 - 模块化设计，易于渐进式添加功能
性能优化 - 正确的资源管理，避免内存泄漏

架构设计

采用模块化分层架构，清晰划分职责，依赖方向明确：

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

7.2 KiB Raw Blame History

PixiJS 游戏开发框架 - 重构设计

项目背景

设计目标

架构设计

模块详细设计

1. Core Layer 核心层

Game (应用主类)

EventBus (事件总线)

AssetManager (资源管理器)

Logger (日志工具)

2. Scene Layer 场景层

SceneManager

BaseScene

SceneTransition (可选)