feat(particle): 添加完整粒子系统和粒子编辑器 (#284)

* feat(editor-core): 添加用户系统自动注册功能

- IUserCodeService 新增 registerSystems/unregisterSystems/getRegisteredSystems 方法
- UserCodeService 实现系统检测、实例化和场景注册逻辑
- ServiceRegistry 在预览开始时注册用户系统,停止时移除
- 热更新时自动重新加载用户系统
- 更新 System 脚本模板添加 @ECSSystem 装饰器

* feat(editor-core): 添加编辑器脚本支持(Inspector/Gizmo)

- registerEditorExtensions 实际注册用户 Inspector 和 Gizmo
- 添加 unregisterEditorExtensions 方法
- ServiceRegistry 在项目加载时编译并加载编辑器脚本
- 项目关闭时自动清理编辑器扩展
- 添加 Inspector 和 Gizmo 脚本创建模板

* feat(particle): 添加粒子系统和粒子编辑器

新增两个包:
- @esengine/particle: 粒子系统核心库
- @esengine/particle-editor: 粒子编辑器 UI

粒子系统功能:
- ECS 组件架构,支持播放/暂停/重置控制
- 7种发射形状:点、圆、环、矩形、边缘、线、锥形
- 5个动画模块:颜色渐变、缩放曲线、速度控制、旋转、噪声
- 纹理动画模块支持精灵表动画
- 3种混合模式:Normal、Additive、Multiply
- 11个内置预设:火焰、烟雾、爆炸、雨、雪等
- 对象池优化,支持粒子复用

编辑器功能:
- 实时 Canvas 预览,支持全屏和鼠标跟随
- 点击触发爆发效果(用于测试爆炸类特效)
- 渐变编辑器:可视化颜色关键帧编辑
- 曲线编辑器:支持缩放曲线和缓动函数
- 预设浏览器:快速应用内置预设
- 模块开关:独立启用/禁用各个模块
- Vector2 样式输入(重力 X/Y)

* feat(particle): 完善粒子系统核心功能

1. Burst 定时爆发系统
   - BurstConfig 接口支持时间、数量、循环次数、间隔
   - 运行时自动处理定时爆发
   - 支持无限循环爆发

2. 速度曲线模块 (VelocityOverLifetimeModule)
   - 6种曲线类型:Constant、Linear、EaseIn、EaseOut、EaseInOut、Custom
   - 自定义关键帧曲线支持
   - 附加速度 X/Y
   - 轨道速度和径向速度

3. 碰撞边界模块 (CollisionModule)
   - 矩形和圆形边界类型
   - 3种碰撞行为:Kill、Bounce、Wrap
   - 反弹系数和最小速度阈值
   - 反弹时生命损失

* feat(particle): 添加力场模块、碰撞模块和世界/本地空间支持

- 新增 ForceFieldModule 支持风力、吸引点、漩涡、湍流四种力场类型
- 新增 SimulationSpace 枚举支持世界空间和本地空间切换
- ParticleSystemComponent 集成力场模块和空间模式
- 粒子编辑器添加 Collision 和 ForceField 模块的 UI 编辑支持
- 新增 Vortex、Leaves、Bouncing 三个预设展示新功能
- 编辑器预览实现完整的碰撞和力场效果

* fix(particle): 移除未使用的 transform 循环变量
This commit is contained in:
YHH
2025-12-05 23:03:31 +08:00
committed by GitHub
parent 690d7859c8
commit 32d35ef2ee
43 changed files with 9704 additions and 0 deletions

View File

@@ -0,0 +1,212 @@
import type { ParticleSystemComponent } from '../ParticleSystemComponent';
import { Color } from '@esengine/ecs-framework-math';
/**
* 粒子渲染数据(与 EngineRenderSystem 兼容)
* Particle render data (compatible with EngineRenderSystem)
*
* This interface is compatible with ProviderRenderData from EngineRenderSystem.
* 此接口与 EngineRenderSystem 的 ProviderRenderData 兼容。
*/
export interface ParticleProviderRenderData {
transforms: Float32Array;
textureIds: Uint32Array;
uvs: Float32Array;
colors: Uint32Array;
tileCount: number;
sortingOrder: number;
texturePath?: string;
}
/**
* Transform 接口(避免直接依赖 engine-core
* Transform interface (avoid direct dependency on engine-core)
*/
interface ITransformLike {
worldPosition?: { x: number; y: number };
position: { x: number; y: number };
}
/**
* 渲染数据提供者接口(与 EngineRenderSystem 兼容)
* Render data provider interface (compatible with EngineRenderSystem)
*
* This interface matches IRenderDataProvider from @esengine/ecs-engine-bindgen.
* 此接口与 @esengine/ecs-engine-bindgen 的 IRenderDataProvider 匹配。
*/
export interface IRenderDataProvider {
getRenderData(): readonly ParticleProviderRenderData[];
}
/**
* 粒子渲染数据提供者
* Particle render data provider
*
* Collects render data from all active particle systems.
* 从所有活跃的粒子系统收集渲染数据。
*
* Implements IRenderDataProvider for integration with EngineRenderSystem.
* 实现 IRenderDataProvider 以便与 EngineRenderSystem 集成。
*/
export class ParticleRenderDataProvider implements IRenderDataProvider {
private _particleSystems: Map<ParticleSystemComponent, ITransformLike> = new Map();
private _renderDataCache: ParticleProviderRenderData[] = [];
private _dirty: boolean = true;
// 预分配的缓冲区 | Pre-allocated buffers
private _maxParticles: number = 0;
private _transforms: Float32Array = new Float32Array(0);
private _textureIds: Uint32Array = new Uint32Array(0);
private _uvs: Float32Array = new Float32Array(0);
private _colors: Uint32Array = new Uint32Array(0);
/**
* 注册粒子系统
* Register particle system
*/
register(component: ParticleSystemComponent, transform: ITransformLike): void {
this._particleSystems.set(component, transform);
this._dirty = true;
}
/**
* 注销粒子系统
* Unregister particle system
*/
unregister(component: ParticleSystemComponent): void {
this._particleSystems.delete(component);
this._dirty = true;
}
/**
* 标记为脏
* Mark as dirty
*/
markDirty(): void {
this._dirty = true;
}
/**
* 获取渲染数据
* Get render data
*/
getRenderData(): readonly ParticleProviderRenderData[] {
this._updateRenderData();
return this._renderDataCache;
}
private _updateRenderData(): void {
this._renderDataCache.length = 0;
// 计算总粒子数 | Calculate total particle count
let totalParticles = 0;
for (const [component] of this._particleSystems) {
if (component.isPlaying && component.pool) {
totalParticles += component.pool.activeCount;
}
}
if (totalParticles === 0) return;
// 确保缓冲区足够大 | Ensure buffers are large enough
if (totalParticles > this._maxParticles) {
this._maxParticles = Math.max(totalParticles, this._maxParticles * 2, 1000);
this._transforms = new Float32Array(this._maxParticles * 7);
this._textureIds = new Uint32Array(this._maxParticles);
this._uvs = new Float32Array(this._maxParticles * 4);
this._colors = new Uint32Array(this._maxParticles);
}
// 按 sortingOrder 分组 | Group by sortingOrder
const groups = new Map<number, {
component: ParticleSystemComponent;
transform: ITransformLike;
}[]>();
for (const [component, transform] of this._particleSystems) {
if (!component.isPlaying || !component.pool || component.pool.activeCount === 0) {
continue;
}
const order = component.sortingOrder;
if (!groups.has(order)) {
groups.set(order, []);
}
groups.get(order)!.push({ component, transform });
}
// 为每个 sortingOrder 组生成渲染数据 | Generate render data for each sortingOrder group
for (const [sortingOrder, systems] of groups) {
let particleIndex = 0;
for (const { component } of systems) {
const pool = component.pool!;
const size = component.particleSize;
const textureId = component.textureId;
// 世界偏移 | World offset (particles are already in world space after emission)
// 不需要额外偏移,因为粒子发射时已经使用了世界坐标
// No additional offset needed since particles use world coords at emission
pool.forEachActive((p) => {
const tOffset = particleIndex * 7;
const uvOffset = particleIndex * 4;
// Transform: x, y, rotation, scaleX, scaleY, originX, originY
this._transforms[tOffset] = p.x;
this._transforms[tOffset + 1] = p.y;
this._transforms[tOffset + 2] = p.rotation;
this._transforms[tOffset + 3] = size * p.scaleX;
this._transforms[tOffset + 4] = size * p.scaleY;
this._transforms[tOffset + 5] = 0.5; // originX
this._transforms[tOffset + 6] = 0.5; // originY
// Texture ID
this._textureIds[particleIndex] = textureId;
// UV (full texture)
this._uvs[uvOffset] = 0;
this._uvs[uvOffset + 1] = 0;
this._uvs[uvOffset + 2] = 1;
this._uvs[uvOffset + 3] = 1;
// Color (packed ABGR for WebGL)
this._colors[particleIndex] = Color.packABGR(
Math.round(p.r * 255),
Math.round(p.g * 255),
Math.round(p.b * 255),
p.alpha
);
particleIndex++;
});
}
if (particleIndex > 0) {
// 创建当前组的渲染数据 | Create render data for current group
const renderData: ParticleProviderRenderData = {
transforms: this._transforms.subarray(0, particleIndex * 7),
textureIds: this._textureIds.subarray(0, particleIndex),
uvs: this._uvs.subarray(0, particleIndex * 4),
colors: this._colors.subarray(0, particleIndex),
tileCount: particleIndex,
sortingOrder,
texturePath: systems[0]?.component.texture || undefined
};
this._renderDataCache.push(renderData);
}
}
this._dirty = false;
}
/**
* 清理
* Cleanup
*/
dispose(): void {
this._particleSystems.clear();
this._renderDataCache.length = 0;
}
}

View File

@@ -0,0 +1,5 @@
export {
ParticleRenderDataProvider,
type ParticleProviderRenderData,
type IRenderDataProvider
} from './ParticleRenderDataProvider';