Pandona-Engine/IFLOW.md

Pandona Engine (PE) - IFLOW 上下文

项目概述

Pandona Engine (PE) 是一个功能完整的 JavaScript 2D 游戏引擎，基于 DOM 实现，用于创建各种类型的 2D 游戏和动画。现在支持现代编译时架构，使用 Vite 作为构建工具。

核心特性

1. 完整的游戏开发功能：支持创建各种类型的2D游戏
2. 模块化架构：核心功能拆分为独立模块，易于扩展和维护
3. 插件系统：支持自定义插件扩展引擎功能
4. 多种元素类型：支持精灵、容器、文本、HTML 和 SVG 元素
5. 高级动画系统：内置补间动画、帧动画、动画序列和时间轴
6. 音频管理：支持音效和背景音乐播放
7. 场景管理：支持多场景切换和过渡效果
8. 事件系统：增强的事件总线，支持全局和局部事件
9. 内存管理：完善的资源清理机制
10. 碰撞检测：矩形碰撞检测系统
11. 输入处理：键盘和鼠标输入处理
12. UI系统：按钮、标签、图像、滑块等UI组件
13. 摄像机系统：支持跟随、缩放、旋转和震动效果
14. 粒子系统：创建各种视觉效果
15. 组件系统：基于组件的游戏对象系统
16. 游戏循环：固定时间步长的游戏循环
17. 编译时架构：使用 Vite 构建工具，支持热重载和代码优化

项目结构

cssEngine/
├── index.html            # 主页面
├── main.js               # 应用入口文件
├── vite.config.js        # Vite配置文件
├── package.json          # 项目配置
├── README.md             # 项目说明文档
├── IFLOW.md              # IFLOW上下文文件
├── public/               # 静态资源
│   └── sprite.css        # 精灵样式文件
├── style/                # 全局样式
│   └── base.less         # 基础样式
├── examples/             # 示例项目
│   ├── spaceShooter.js   # 太空射击游戏示例
│   └── spaceShooter.html # 示例游戏HTML文件
├── src/
│   ├── core/             # 核心模块
│   │   └── Engine.js     # 引擎主类
│   ├── elements/         # 元素类
│   │   ├── BaseElement.js
│   │   ├── Sprite.js
│   │   ├── Box.js
│   │   ├── TextElement.js
│   │   ├── HtmlElement.js
│   │   ├── SvgElement.js
│   │   ├── GameObject.js
│   │   └── Component.js
│   ├── managers/         # 管理器
│   │   ├── ResourceManager.js
│   │   ├── SceneManager.js
│   │   ├── AudioManager.js
│   │   ├── TransitionManager.js
│   │   └── Camera.js
│   ├── animation/        # 动画系统
│   │   ├── Tween.js
│   │   ├── AnimationSystem.js
│   │   └── AnimationController.js
│   ├── effects/          # 特效系统
│   │   └── ParticleSystem.js
│   ├── ui/               # UI系统
│   │   └── UI.js
│   ├── utils/            # 工具类
│   │   └── EventBus.js   # 事件总线
│   └── scenes/           # 场景目录
│       └── index/        # 主场景
│           ├── index.js  # 场景结构和逻辑
│           └── index.less # 场景样式
└── test/                 # 测试文件
    └── ...               # 各模块测试

核心类和API

Engine 引擎主类

• constructor(element, options) - 创建引擎实例
• use(plugin, options) - 安装插件
• load(src) - 加载资源
• loadSound(name, src, options) - 加载音效
• loadMusic(name, src, options) - 加载音乐
• playSound(name, options) - 播放音效
• playMusic(name, options) - 播放音乐
• createScene(name) - 创建场景
• switchScene(name) - 切换场景
• tween(target, duration, easing) - 创建补间动画
• createFrameAnimation(name, frames, frameRate) - 创建帧动画
• playFrameAnimation(sprite, animationName, loop) - 播放帧动画
• addGameObject(obj) - 添加游戏对象
• removeGameObject(obj) - 移除游戏对象
• checkCollision(obj1, obj2) - 碰撞检测
• setCameraPosition(x, y) - 设置摄像机位置
• follow(target, offset) - 跟随目标
• setCameraZoom(zoom) - 设置摄像机缩放
• shakeCamera(intensity, duration) - 屏幕震动
• addUIElement(element) - 添加UI元素
• removeUIElement(element) - 移除UI元素

GameObject 游戏对象基类

• setPosition(x, y) - 设置位置
• setSize(width, height) - 设置尺寸
• setRotation(rotation) - 设置旋转角度
• setScale(scaleX, scaleY) - 设置缩放
• setVisible(visible) - 显示/隐藏
• addChild(child) - 添加子对象
• removeChild(child) - 移除子对象
• addComponent(name, component) - 添加组件
• getComponent(name) - 获取组件
• removeComponent(name) - 移除组件

Component 组件基类

• onAdd(gameObject) - 当组件被添加到游戏对象时调用
• onRemove(gameObject) - 当组件从游戏对象中移除时调用
• update(deltaTime) - 更新方法
• onDestroy(gameObject) - 销毁方法

预定义组件

• PhysicsComponent - 物理组件
• ColliderComponent - 碰撞组件
• AnimationComponent - 动画组件
• InputComponent - 输入组件
• LifecycleComponent - 生命周期组件

UI组件

• UIButton - 按钮
• UILabel - 标签
• UIImage - 图像
• UISlider - 滑块

编译时架构

构建工具

• 使用 Vite 作为构建工具
• 支持 ES6 模块系统
• 支持 Less CSS 预处理器
• 支持代码压缩和优化
• 支持开发服务器热重载

开发命令

# 启动开发服务器（热重载）
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

场景化开发

• 使用 src/scenes/ 目录组织不同场景
• 每个场景包含 index.js（场景逻辑）和 index.less（场景样式）
• 支持类似HTML的标签语法定义场景结构

开发约定

1. 使用ES6模块系统
2. 遵循面向对象编程原则
3. 使用JSDoc注释重要函数和类
4. 保持代码简洁和可读性
5. 遵循现有的代码风格和命名约定
6. 使用 Less 作为 CSS 预处理器
7. 遵循场景化组织结构

示例项目

项目包含一个完整的太空射击游戏示例，展示了引擎的各种功能，位于 examples/spaceShooter.js 和 examples/spaceShooter.html。