粒子系统

粒子系统组件 绘制确定性的 2D 粒子效果。粒子运动不是在每一帧推进并为每个粒子保存变换，而是从描述符、种子和时间中通过解析方式采样得到。

快速开始

添加组件并播放一个内置预设：

particles := entity.add_component(Particle_System_Component);
particles.play(Particle_System_Desc.preset_explosion());

play 会验证并复制一个描述符，重置确定性种子和开始时间，并启用该组件。调用 restart() 来重新播放当前激活的描述符：

particles.restart();

调用 stop() 以禁用该效果。一个没有描述符的空 粒子系统组件 在调用 play() 之前是无效的，因此添加它时不会先启动一个不可见的默认效果。

爆发式预设会在最长可能的粒子寿命结束后自动禁用其组件。连续式预设会保持启用，直到你禁用或移除该组件。

预设

每次预设调用都会返回一个全新的描述符，可安全自定义：

desc := Particle_System_Desc.preset_smoke();
desc.color_over_lifetime = Particle_System_Desc.over_lifetime_v4(
    {0.4, 0.15, 0.7, 0.8},
    {0.05, 0.01, 0.1, 0}
);
desc.spawn_position_radius = 0.3;
particles.play(desc);

组件当前活动的 desc 是只读的。 get_desc() 返回一个值副本，可安全自定义后再传回给 play()；因此运行中的粒子绝不会观察到一半生效的描述符更改。

内置预设包括：

• preset_default

• preset_shotgun

• preset_firework

• preset_explosion

• preset_sparks

• preset_smoke

• preset_dust

• preset_fountain

• preset_embers

• preset_snow

• preset_rain

• preset_confetti

• preset_magic_aura

本地与世界仿真空间

根据 simulation_space 设置，以决定发射器移动时已生成粒子应如何反应：

desc.simulation_space = .LOCAL; // 现有粒子跟随发射器。
desc.simulation_space = .WORLD; // 现有粒子保持在其生成位置。

两种模式都使用同样的确定性解析采样器。它们仅在恢复粒子起源所需的运行时信息上有所不同：

• 本地空间 保持恒定大小的发射器状态。新建的本地空间系统不分配逐粒子的仿真状态。

• 世界空间 为每个可复用的粒子槽存储一条很小的出生记录：其出生时的发射器位置和生命索引。位置、速度、旋转、大小和颜色仍然通过解析方式计算。

这使得本地空间的状态为 O(1)，而世界空间的状态为 O(desc.get_particle_count())。将现有的世界空间组件切换为本地空间会清空槽位数量，不过托管数组可能保留其先前容量以便复用。

爆发式与连续式发射

爆发式发射会一次性启动请求数量的粒子：

desc.emission = Particle_Emission.burst(32);
desc.prewarm = false;
desc.auto_disable_when_finished = true;

连续式发射会按每秒请求数量调度粒子：

desc.emission = Particle_Emission.continuous(20);
desc.prewarm = true;
desc.auto_disable_when_finished = false;

将 emission, prewarm和 auto_disable_when_finished 视为切换预设时的一组生命周期配置。预设返回完整的描述符，赋值新的 emission 不会重置其他任一字段。特别是，像 preset_magic_aura() 这样的环境类预设已经具有 prewarm = true；在把它们改为爆发式发射之前请显式清除，否则 play() 将拒绝该描述符。

引擎会自动推导出最小且安全的可复用槽位池：

slot_count = ceil(emission.rate * lifetime.max)

使用 desc.get_particle_count() 来查看生成的爆发数量或连续槽位数量。连续容量不是可编辑参数：发射速率和寿命已经决定了可同时符合条件的粒子最大数量。

prewarm 通过解析方式让连续调度推进一个完整的池周期，使环境效果看起来像是已经在运行，而无需模拟更早的帧。WORLD 空间的预热没有更早的发射器轨迹可供检查，因此它会有意假定在激活之前发射器一直静止在当前位置。

常见描述符字段

范围和值随生命周期变化的参数使用辅助构造器：

desc.speed = Particle_System_Desc.range_float(2, 5);
desc.lifetime = Particle_System_Desc.range_float(0.5, 1.2);
desc.size_over_lifetime = Particle_System_Desc.over_lifetime_v2(
    {0.2, 0.06},
    {0.04, 0.01}
);

size_over_lifetime 包含完整的世界空间宽度和高度。提供两个维度是有意为之，可让拖尾和矩形粒子进行拉伸。若要保持精灵源图的宽高比，请指定其视觉高度：

desc.size_over_lifetime = Particle_System_Desc.size_from_sprite_height(
    desc.sprite,
    0.2,
    0.5
);

主要描述符字段有：

• spawn_offset, spawn_rect_size和 spawn_position_radius：粒子相对于发射器的生成位置。

• direction 和 direction_spread_degrees：基础移动方向和随机角度扩散。采样器会对方向进行归一化。

• speed, gravity和 friction：解析运动控制。

• lifetime, fade_in_seconds和 fade_out_seconds：生命周期和不透明度包络。

• color_over_lifetime：RGBA 颜色插值。淡入淡出会乘以插值后的 alpha，而不是替换它。

• initial_rotation_degrees 和 angular_velocity_degrees：旋转范围和角速度范围。

• face_direction：让每个粒子沿其当前速度方向，而不是应用角速度。

• size_over_lifetime：粒子生命周期内独立的完整宽高。

• sprite：渲染纹理。

• seed_salt：混入激活种子的、按描述符稳定变化的扰动。

layer 和 z_offset 位于 粒子系统组件 上并控制渲染顺序。

验证

play() 和 restart() 会对无效描述符进行断言，使程序员错误在源头就失败。编辑器和其他创作工具可以在不启动效果的情况下进行验证：

error: string;
if !desc.try_validate(ref error) {
    // 向创作者显示错误。
}

validation_error() 会直接返回相同的错误；若描述符有效，则返回空字符串。无效值不会被悄悄钳制。

确定性与插值

每次采样都由粒子系统种子、槽位索引、生命索引和当前时间推导而来。绘制不会修改仿真状态。当前和之前的解析样本会传递给插值四边形渲染器，包括位置、大小和旋转，因此粒子在固定仿真更新之间依然平滑。

世界空间中的出生位置是在共享更新路径中捕获的，而不是在绘制期间捕获。绘制采样不会晚于最近一次完成的出生位置更新，因此启动和重新启用的时机会在其起点存在之前暴露一个刚好符合条件的槽位。这使得效果与预测和重模拟兼容，同时避免仅渲染端的状态变化。