448 lines
26 KiB
Markdown
448 lines
26 KiB
Markdown
# 粒子模块
|
||
|
||
**脚本入口：** `eve.Particles()`
|
||
|
||
用代码或 JSON 创建发射器，配置运动、颜色、寿命并进行更新和渲染。
|
||
|
||
## 基本用法
|
||
|
||
```squirrel
|
||
local particles = eve.Particles();
|
||
local fire = particles.newEmitterFromFile("particles/fire.json");
|
||
fire.setPosition(320, 420);
|
||
fire.start();
|
||
particles.update(dt);
|
||
particles.render(gfx);
|
||
```
|
||
|
||
## 配置热重载观察
|
||
|
||
`setAutoReload(true)`（默认开启）后，模块会在 `pollConfigs()` 或模块更新阶段
|
||
观察绑定配置文件的修改时间。`getConfigReloadObservation()` 返回最近一次明确观察
|
||
到的状态字符串：`"unbound"`（没有绑定配置文件）、
|
||
`"mtime_polling_unchanged"`（文件未改变）、`"mtime_polling_reloaded"`（已重新加载）、
|
||
`"mtime_unavailable"`（无法取得文件修改时间）或
|
||
`"mtime_polling_reload_failed"`（检测到变化但重新加载失败）。该接口只报告观察结果，
|
||
不会代替 `reloadConfig()`；读取失败时发射器仍保留原配置，调用方可据此记录诊断或重试。
|
||
|
||
## 版本化多发射器特效资产
|
||
|
||
复杂特效应保存为 `eve.particle-effect` 资产，而不是让玩法脚本逐个拼装发射器。版本 1 支持命名层、嵌入式发射器配置或外部 `config` 引用、局部偏移/旋转、禁用层、资产参数默认值和逐层参数覆盖。
|
||
|
||
```json
|
||
{
|
||
"type": "eve.particle-effect",
|
||
"version": 1,
|
||
"parameters": { "intensity": 1.0 },
|
||
"emitters": [
|
||
{
|
||
"name": "core",
|
||
"offset": [0, -6],
|
||
"emitter": {
|
||
"buffer": 128,
|
||
"preset": "fire",
|
||
"parameterBindings": [
|
||
{ "parameter": "intensity", "target": "size", "scale": 1.0 }
|
||
]
|
||
}
|
||
},
|
||
{ "name": "smoke", "config": "emitters/smoke.json" }
|
||
]
|
||
}
|
||
```
|
||
|
||
```squirrel
|
||
local impact = particles.newEffectFromFile("effects/impact.effect.json");
|
||
if (impact == null) {
|
||
print(particles.getLastEffectError() + "\n");
|
||
} else {
|
||
impact.setPosition(480, 320);
|
||
impact.setRotation(0.5);
|
||
impact.setFloatParameter("intensity", 1.4);
|
||
impact.start();
|
||
local sparks = impact.getEmitterByName("sparks"); // 仍可精调单层
|
||
}
|
||
```
|
||
|
||
`newEffectFromText()` 供编辑器预览未落盘的 JSON。组对象提供 `setPosition`、`setRotation`、`setScale`、`setLayer`、`setVisible`、`start`、`pause`、`stop`、`reset` 和命名层 `emit`；组销毁时会一起回收所拥有的发射器。未知版本、重名层和无效配置会拒绝实例化，并通过 `getLastEffectError()` 返回可展示的诊断。
|
||
|
||
## 绑定到动态骨骼
|
||
|
||
粒子仍是 2D。支持多种运行时骨骼源；每帧 `particles.update` 会自动 `syncAttach`。
|
||
|
||
| 源 | API | 说明 |
|
||
|----|-----|------|
|
||
| 3D `AnimPose` | `attachToBone` / `attachToBoneByName` | 骨骼世界坐标经 `plane`（`xy`/`xz`/`yz`）与 `scale` 投影 |
|
||
| 2D Spine | `attachToSpineBone` / `attachToSpineBoneByName` | 像素空间；`scale` 仍生效，`plane` 忽略 |
|
||
| IK `Skeleton2D` | `attachToSkeleton2D` | FABRIK 链骨位置（像素/世界单位 × `scale`） |
|
||
| IK `Skeleton3D` | `attachToSkeleton3D` | 3D 骨位置经 `plane`+`scale` 投影 |
|
||
|
||
```squirrel
|
||
local anim = eve.Animation();
|
||
// … player/sm 驱动 pose，并 pose.computeWorld(sk) …
|
||
local spark = particles.newEmitter(128);
|
||
spark.applyPreset("spark");
|
||
spark.setAttachScale(100); // 米 → 像素
|
||
spark.setAttachPlane("xy");
|
||
spark.setAttachOffset(0, 0.05, 0);
|
||
spark.setFollowBoneRotation(true);
|
||
spark.attachToBoneByName(pose, sk, "LeftHand");
|
||
spark.start();
|
||
```
|
||
|
||
Spine（2D）示例：
|
||
|
||
```squirrel
|
||
local spine = anim.newSpineSkeleton(data);
|
||
spine.updateWorldTransform();
|
||
local dust = particles.newEmitter(64);
|
||
dust.attachToSpineBoneByName(spine, "hand");
|
||
dust.start();
|
||
```
|
||
|
||
IK 2D/3D 示例：
|
||
|
||
```squirrel
|
||
local ik = eve.IK();
|
||
local sk2 = ik.newSkeleton2D();
|
||
// … createBone / solve …
|
||
local tipFx = particles.newEmitter(32);
|
||
tipFx.attachToSkeleton2D(sk2, tipBoneId);
|
||
tipFx.setFollowBoneRotation(true);
|
||
```
|
||
|
||
`detach()` 解除绑定；`getAttachKind()` 返回 `"anim"` / `"spine"` / `"ik2d"` / `"ik3d"` / `"none"`；也可手动 `syncAttach()`。
|
||
|
||
## 蒙皮表面发射（人物皮肤粒子）
|
||
|
||
从 CPU 蒙皮后的顶点采样发射位置，适合身体表面的火花、灰尘、能量层：
|
||
|
||
```squirrel
|
||
local skin = anim.newSkinFromModel(model, meshIndex, sk);
|
||
pose.computeWorld(sk);
|
||
local aura = particles.newEmitter(512);
|
||
aura.applyPreset("smoke");
|
||
aura.setSkinScale(100);
|
||
aura.setSkinPlane("xy");
|
||
aura.setSkinSource(skin, pose);
|
||
// 可选：只从某根骨附近的顶点发射
|
||
aura.setSkinBoneFilterByName(sk, "Spine", 0.2);
|
||
aura.start();
|
||
// 或瞬时爆发：
|
||
aura.emitFromSkin(80);
|
||
```
|
||
|
||
脚本侧也可主动刷新蒙皮缓存：`skin.updateSkinnedPositions(pose)`，再用 `getSkinnedPositionX/Y/Z(i)` 读取。
|
||
|
||
## 外观增强：混合模式、序列帧与生命周期曲线
|
||
|
||
发射器支持加法混合、精灵表序列帧动画、多段颜色渐变与大小/旋转曲线，均可通过 JSON 或脚本配置。
|
||
|
||
```squirrel
|
||
// 加法混合 + 序列帧（4x2 精灵表，12 帧/秒，随机起始帧 0~25%）
|
||
local burst = particles.newEmitter(256);
|
||
burst.setBlendMode("additive");
|
||
burst.setFlipbook(4, 2, 12, 0.25);
|
||
burst.setTexture(tex); // 精灵表贴图
|
||
burst.start();
|
||
|
||
// 多段颜色渐变 + 大小曲线 + 初始随机旋转
|
||
burst.clearColorGradient();
|
||
burst.addColorStop(0.0, 1.0, 0.9, 0.4, 1.0); // 白热
|
||
burst.addColorStop(0.5, 1.0, 0.3, 0.0, 0.8); // 橙红
|
||
burst.addColorStop(1.0, 0.1, 0.0, 0.0, 0.0); // 熄灭
|
||
burst.clearSizeCurve();
|
||
burst.addSizeCurvePoint(0.0, 0.3);
|
||
burst.addSizeCurvePoint(0.7, 1.0);
|
||
burst.addSizeCurvePoint(1.0, 0.1);
|
||
burst.setStartRotation(-30, 30); // 度
|
||
```
|
||
|
||
JSON 等价配置：
|
||
|
||
```json
|
||
{
|
||
"blendMode": "additive",
|
||
"flipbook": { "hframes": 4, "vframes": 2, "frameRate": 12, "frameRandomStart": 0.25 },
|
||
"startRotation": [-30, 30],
|
||
"colorOverLifetime": [
|
||
{ "t": 0.0, "r": 1.0, "g": 0.9, "b": 0.4, "a": 1.0 },
|
||
{ "t": 0.5, "r": 1.0, "g": 0.3, "b": 0.0, "a": 0.8 },
|
||
{ "t": 1.0, "r": 0.1, "g": 0.0, "b": 0.0, "a": 0.0 }
|
||
],
|
||
"sizeOverLifetime": [[0.0, 0.3], [0.7, 1.0], [1.0, 0.1]],
|
||
"rotationOverLifetime": [[0.0, 0.0], [1.0, 120.0]]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `blendMode`：`"alpha"`（默认）/ `"additive"` / `"opaque"`。加法混合适合火焰、火花、魔法等自发光效果。
|
||
- `flipbook`：`hframes`/`vframes` 为精灵表行列数；`frameRate` 为每秒帧数（0 = 静止第一帧）；`frameRandomStart`（0~1）随机化起始帧。
|
||
- `colorOverLifetime` / `sizeOverLifetime` / `rotationOverLifetime` 为按归一化寿命采样的多段渐变/曲线；不配置时回退到 `colorStart`/`colorEnd` 与 `sizes` 的两端线性插值。`rotationOverLifetime` 单位为度，叠加在初始旋转与自旋之上。
|
||
|
||
## 发射控制与受力增强
|
||
|
||
发射器支持定时爆发、预热、重力/阻尼/限速、速度曲线、继承速度与本地/世界仿真空间：
|
||
|
||
```squirrel
|
||
// 定时爆发 + 预热（一次性爆炸，开场即满）
|
||
local boom = particles.newEmitter(256);
|
||
boom.addBurst(0.0, 60); // 第 0 秒爆发 60 个
|
||
boom.addBurst(0.15, 30); // 第 0.15 秒再爆 30 个
|
||
boom.setEmitterLifetime(0.3); // 单次效果
|
||
boom.setPrewarm(0.5); // start() 时预模拟 0.5 秒
|
||
boom.start();
|
||
|
||
// 重力 + 阻尼 + 限速 + 继承发射器移动速度（角色跑动扬尘）
|
||
local dust = particles.newEmitter(128);
|
||
dust.setGravity(0, 40);
|
||
dust.setDamping(0.8);
|
||
dust.setLimitVelocity(120);
|
||
dust.setInheritVelocity(0.6);
|
||
dust.setSimulationSpace("local"); // 粒子跟随发射器（本地空间）
|
||
dust.start();
|
||
```
|
||
|
||
JSON 等价配置：
|
||
|
||
```json
|
||
{
|
||
"bursts": [ { "time": 0.0, "count": 60 }, { "time": 0.15, "count": 30 } ],
|
||
"prewarm": 0.5,
|
||
"gravity": [0, 40],
|
||
"damping": 0.8,
|
||
"limitVelocity": 120,
|
||
"velocityOverLifetime": [[0.0, 1.0], [1.0, 0.2]],
|
||
"inheritVelocity": 0.6,
|
||
"simulationSpace": "local",
|
||
"noise": { "strength": 8, "frequency": 0.05, "speed": 1.5 },
|
||
"maxDeltaTime": 0.1
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `bursts`：按发射器运行时间触发的爆发（数组元素为 `{time, count}` 或 `[time, count]`），每个爆发只触发一次。
|
||
- `prewarm`：`start()` 时按 1/60 步长预模拟，让循环效果在首帧就是满的。
|
||
- `gravity` 每步作为加速度叠加；`damping` 为每秒速度衰减比例（0~1）；`limitVelocity` 为速度上限（0 = 不限）；`velocityOverLifetime` 为速度倍率曲线。
|
||
- `inheritVelocity`（0~1）把发射器当前移动速度按比例附加到新粒子；`simulationSpace: "local"` 时粒子随发射器平移（默认 `"world"`）。
|
||
- `noise` 为 CPU 值噪声湍流（强度/频率/时间流速），适合烟雾、火焰的自然扰动。
|
||
- `maxDeltaTime` 限制单帧模拟步长，防止卡顿后的粒子爆炸。
|
||
|
||
## 可复现播放、固定步进与按距离发射
|
||
|
||
需要录制回放、网络同步、慢动作或稳定拖尾时，可显式控制粒子时间线：
|
||
|
||
```squirrel
|
||
local trail = particles.newEmitter(512);
|
||
trail.setRandomSeed(20260826); // 每次 start() 重放相同随机序列
|
||
trail.setAutoRandomSeed(false);
|
||
trail.setEmitterLifetime(1.5);
|
||
trail.setLooping(true); // 有限时间线循环，burst 也会重新触发
|
||
trail.setPlaybackSpeed(0.5); // 半速播放；0 = 冻结
|
||
trail.setFixedTimeStep(1.0 / 120.0, 8); // 固定步长 + 每帧最多追 8 步
|
||
trail.setEmissionRateOverDistance(0.25); // 每移动 4 个世界单位发射 1 个
|
||
trail.start();
|
||
```
|
||
|
||
JSON 等价配置：
|
||
|
||
```json
|
||
{
|
||
"randomSeed": 20260826,
|
||
"autoRandomSeed": false,
|
||
"emitterLife": 1.5,
|
||
"looping": true,
|
||
"playbackSpeed": 0.5,
|
||
"fixedTimeStep": 0.008333333,
|
||
"maxSubSteps": 8,
|
||
"emissionRateOverDistance": 0.25
|
||
}
|
||
```
|
||
|
||
- 固定种子会让寿命、速度、方向、大小、旋转、发射形状和序列帧起点等随机采样可复现；`autoRandomSeed: true`（默认）则每次 `start()` 生成新序列。
|
||
- 固定步进由 `maxSubSteps` 限制追帧工作量，超过上限的时间债务会被丢弃，避免暂停恢复后形成长时间尖峰。
|
||
- 按距离发射会沿上一位置到当前位置的线段均匀插值，世界空间拖尾不会因帧率变化形成粒子团。第一次更新只建立运动基线，不会补发创建前的路径。
|
||
|
||
## 质量等级、预算、剔除与性能统计
|
||
|
||
大规模战斗或天气效果应通过运行时预算稳定降级，而不是等粒子缓冲溢出：
|
||
|
||
```squirrel
|
||
particles.setQualityLevel(2); // 0=最低，3=最高
|
||
particles.setBudget(50000, 256); // 全局存活粒子软上限、每帧模拟发射器上限；0=不限
|
||
|
||
local heroFx = particles.newEmitter(2048);
|
||
heroFx.setPriority(100); // 高优先级先获得模拟/生成预算
|
||
heroFx.setMinimumQuality(0); // 所有质量等级都保留
|
||
heroFx.setCullingMode("always"); // 即使离屏也继续模拟
|
||
heroFx.setMaxSpawnPerFrame(256);
|
||
|
||
local ambience = particles.newEmitter(8192);
|
||
ambience.setPriority(-10);
|
||
ambience.setMinimumQuality(2);
|
||
ambience.setCullingMode("pause"); // 离屏或超出距离时冻结
|
||
ambience.setCullDistance(1800);
|
||
ambience.setMaxSpawnPerFrame(96);
|
||
```
|
||
|
||
JSON 发射器策略：
|
||
|
||
```json
|
||
{
|
||
"priority": -10,
|
||
"minimumQuality": 2,
|
||
"cullingMode": "pause",
|
||
"cullDistance": 1800,
|
||
"maxSpawnPerFrame": 96
|
||
}
|
||
```
|
||
|
||
- 发射器按 `priority` 从高到低分配每帧模拟器数量和剩余粒子空间；总粒子数是软上限，调低预算不会立即删除已经存活的粒子，但会停止超额生成，让它们自然死亡。
|
||
- `cullingMode`：`"automatic"`（默认，仅跳过离屏且为空的发射器）、`"pause"`（离屏时冻结全部模拟）、`"always"`（关键玩法效果始终模拟）。渲染阶段仍会跳过确定不可见的粒子。
|
||
- `minimumQuality` 高于当前全局质量等级时，发射器冻结且不渲染；恢复质量后继续运行，不破坏已有粒子状态。
|
||
- 每次 `update`/`render` 后可读取 `getLastSimulatedEmitters()`、`getLastCulledEmitters()`、`getLastBudgetSkippedEmitters()`、`getLastParticleCount()`、`getLastSpawnedParticles()`、`getLastDroppedSpawns()`、`getLastRenderedParticles()`、`getLastSimulationMs()` 与 `getLastRenderMs()`，用于 HUD、自动伸缩和性能回归。
|
||
|
||
## 碰撞与子发射器
|
||
|
||
```squirrel
|
||
// 世界边界反弹（雨滴落地溅射）
|
||
local rain = particles.newEmitter(512);
|
||
rain.setCollision("bounce", 2, 0.4, 0.1); // 半径 2、弹性 0.4、每次碰撞损失 10% 寿命
|
||
rain.setCollisionBounds(true, 0, 0, 960, 640);
|
||
rain.setWorldCollision(true); // 可选：查询引擎级碰撞解析器（tilemap/Box2D）
|
||
|
||
// 子发射器：出生时喷火花，死亡时冒烟
|
||
local sparks = particles.newEmitter(128);
|
||
local smoke = particles.newEmitter(128);
|
||
sparks.addSubEmitter(smoke, "death", 0.3); // 继承 30% 速度
|
||
```
|
||
|
||
JSON：`collision: {mode, radius, restitution, lifetimeLoss}`、`collisionBounds: {enabled, minX, minY, maxX, maxY}`、`worldCollision: true`。子发射器目前通过脚本 `addSubEmitter(target, trigger, inherit)` 关联（trigger 为 `"birth"` / `"death"` / `"collision"`）。
|
||
|
||
精灵朝向统一由 `setRenderMode` 控制：`"billboard"` 使用粒子自身旋转，`"axis"` 配合 `setRenderAxis(degrees)` 固定到屏幕空间轴，`"stretched"`（也接受 `"velocity"`）按速度方向拉伸。JSON 对应 `renderMode`、`renderAxis` 和 `stretch`。
|
||
|
||
透明粒子可用 `setSortMode("none" | "oldest" | "youngest" | "distance")` 选择稳定的逐发射器提交顺序，`getSortMode()` 返回规范化后的策略。`distance` 在有相机时按远到近排列。当前 GPU 常驻后端只支持 `none`；其他策略明确保留在 CPU 后端，避免宣称排序已在 GPU 上完成。
|
||
|
||
连续拖尾使用 `setRibbon(width, minSegmentLength)`，它按稳定的粒子出生顺序连接相邻控制点，跳过过短段，并沿段方向生成带宽度的纹理四边形；JSON 为 `ribbon: {width, minSegmentLength}`。Ribbon 当前明确使用 CPU 渲染后端，适合配合 `setEmissionRateOverDistance` 制作弹道、刀光和移动轨迹。
|
||
|
||
`setSoftParticles(true, depth, fadeDistance)` 让常驻粒子采样当前 G-buffer 的线性场景深度，在与几何相交或被遮挡时平滑衰减 alpha；JSON 为 `softParticles: {enabled, depth, fadeDistance}`，深度值均为 `[0,1]` 线性深度。`isSoftParticlesActive()` 只有在 GPU 常驻渲染器已激活且当前帧确实产生场景深度时才返回 true；纯 2D 帧不会伪造深度，而是保持普通粒子外观。
|
||
|
||
粒子材质默认是 `unlit`，不受场景灯光影响。`setMaterialMode("lit")` 会让粒子接收现有 2D 环境光和点光/方向光；配合 `setNormalTexture(normalTex)` 时使用切线空间法线贴图，否则使用无贴图的逐粒子中心光照。JSON 可写为：
|
||
|
||
```json
|
||
{
|
||
"material": {
|
||
"mode": "lit",
|
||
"normalTexture": "particles/smoke-normal.png"
|
||
}
|
||
}
|
||
```
|
||
|
||
Lit/法线贴图目前明确使用 CPU 粒子模拟加 GPU 2D lit 绘制；即使请求了 `gpuSimulation`，也会安全回退，不会静默忽略灯光。切回 `unlit` 后可重新满足 GPU 常驻条件。
|
||
|
||
`setMaterialMode("distortion")` 把粒子纹理解释为屏幕空间位移场：R/G 的 0.5 表示零偏移，0/1 表示负/正方向，A 控制羽化覆盖；`setDistortionStrength(pixels)`（`getDistortionStrength()` 可读回）设置最大折射像素数。它采样同一帧已解析的 3D 场景颜色，因此纯 2D 帧或离屏 Canvas 不会伪造背景。JSON 示例：`material: {mode: "distortion", distortionStrength: 12}`。Distortion 当前使用 CPU 粒子模拟和专用 GPU 合成管线。
|
||
|
||
运行时诊断可读取 `getSimulationBackend()`（`"cpu"` / `"gpu"`）和 `getGpuFallbackReason()`。后者在 GPU 已激活时为空；可返回 `disabled`、`backend_unavailable`、`pending_activation`，或具体功能原因：`canvas`、`custom_shader`、`collision`、`force_fields`、`sub_emitters`、`particle_lights`、`curves`、`sorting`、`ribbon`、`lit_material`、`distortion_material`。`isGpuFeatureSetSupported()` 只检查当前功能组合，不把机器是否支持 Vulkan resident 后端混在一起。
|
||
|
||
玩法和效果资产可通过命名浮点参数实时驱动 emitter，无需重建或覆盖基础配置：
|
||
|
||
```squirrel
|
||
fire.setFloatParameter("intensity", 1.5);
|
||
fire.bindFloatParameter("intensity", "emission", 1.0, 0.0);
|
||
fire.bindFloatParameter("intensity", "speed", 0.5, 0.25);
|
||
fire.bindFloatParameter("intensity", "size", 0.35, 0.65);
|
||
```
|
||
|
||
支持的 target 是 `emission`、`speed`、`size`、`playback`，解析公式为 `max(0, value * scale + offset)`；参数缺失或未绑定时倍率为 1。JSON 使用 `parameters` 对象和 `parameterBindings` 数组。这些值在 CPU 与 GPU resident 的生成输入上保持一致，适合武器充能、天气强度、角色状态与关卡脚本驱动。
|
||
|
||
健壮性：`overflowMode`（`"drop"` 默认 / `"pause"` 暂停发射直到有空位 / `"warn"` 日志提示）；`setMaxDeltaTime` 限制单帧步长；带相机的发射器在屏幕外且无存活粒子时会跳过模拟。
|
||
|
||
## 力场、自定义 Shader 与粒子灯光
|
||
|
||
```squirrel
|
||
// 径向力场：黑洞（吸引）/ 斥力场；strength > 0 吸引，< 0 排斥
|
||
local vortex = particles.newEmitter(512);
|
||
vortex.addForceField(400, 300, 180, 90, 1.5); // 中心 (400,300)，半径 180，强度 90，衰减指数 1.5
|
||
|
||
// 自定义粒子 Shader（仅作用于带贴图的粒子；需要先创建 Shader）
|
||
local glow = particles.newEmitter(256);
|
||
glow.setShader(myShader);
|
||
|
||
// 粒子灯光：跟随存活粒子的 2D 点光源（每个发射器最多 8 盏，引擎单画布每帧最多 8 盏）
|
||
local torch = particles.newEmitter(128);
|
||
torch.setLights(true, 120, 1.2, 1.0, 0.6, 0.2, 4);
|
||
```
|
||
|
||
JSON：`forceFields: [{x, y, radius, strength, falloff}]`；`lights: {enabled, max, radius, intensity, color: [r,g,b]}`。粒子灯光由 `ParticleLightSystem`（随 `particles.update` 自动调用）维护一盏 `Light2D` 池，位置与最前面的存活粒子同步。
|
||
|
||
## GPU 加速模拟
|
||
|
||
`setGpuSimulation(true)` 或 JSON `"gpuSimulation": true` 会请求常驻 GPU 后端。首次可提交帧把当前新生粒子上传到后端拥有的多帧 SSBO；之后更新、死亡剔除、存活压缩和 `VkDrawIndirectCommand` 都在同一帧命令缓冲内完成。渲染直接读取压缩后的 SSBO，不逐帧回读粒子状态，也不为每个发射器单独提交或等待队列。CPU 只维护确定性的发射调度、预算和寿命数量估计。
|
||
|
||
```squirrel
|
||
local embers = particles.newEmitter(20000); // 上万粒子场景
|
||
embers.setGpuSimulation(true);
|
||
embers.setGravity(0, 30);
|
||
embers.start();
|
||
```
|
||
|
||
调用 `isGpuSimulationActive()` 可区分“资产请求 GPU”与“本帧已经迁移到 GPU”。`particles.getLastGpuResidentEmitters()` 和 `particles.getLastGpuResidentParticles()` 可用于性能 HUD 和自动质量伸缩。后者是 CPU 侧精确寿命估计；后端的存活、生成、死亡、丢弃和间接实例计数采用帧槽延迟读数，不会阻塞当前帧。
|
||
|
||
当前常驻 GPU 后端覆盖基础点/线/矩形/椭圆发射、重力、线性/径向/切向加速度、阻尼、限速、噪声、本地/世界空间、旋转、尺寸和起止颜色、flipbook、拉伸与常用混合模式。需要玩法回调或逐粒子 CPU 状态的功能会自动保留在确定性 CPU 后端，包括碰撞、力场、子发射器、粒子灯光、自定义 shader/canvas，以及自定义速度/尺寸/旋转曲线和多段颜色渐变。没有可用图形后端时也安全回退 CPU。
|
||
|
||
着色器源位于 `graphics/shaders/particle_resident.*`；修改后运行 `python scripts/compile_particle_gpu_shaders.py` 更新随引擎编译的 SPIR-V 与 include 文件。
|
||
|
||
## 对象关系与调用时机
|
||
|
||
`Particles` 管理 Emitter 及配置、模拟、渲染系统；Emitter 持有容量、发射配置与运行状态。模块 update 统一推进所有 emitter（含骨骼绑定同步与蒙皮表面采样），render 按 layer 提交。
|
||
|
||
帧序建议：动画 `computeWorld` → `particles.update(dt)` → `particles.render(gfx)`。
|
||
|
||
## 目标导向指南
|
||
|
||
### 从 JSON 创建火焰
|
||
|
||
配置 buffer、发射率、寿命、速度、颜色和 `autoReload`，调用 `newEmitterFromFile()`；设置位置后 `start()`。模块统一 `update(dt)` 和 `render(gfx)`，无需逐粒子操作。
|
||
|
||
### 制作一次性爆炸
|
||
|
||
创建容量足够的 emitter，设置有限 emitter life 和较高瞬时发射率，停止循环；播放结束后检查 active 状态并回收。预览时用 preset 起步，再逐项覆盖参数。
|
||
|
||
### 角色手上的拖尾 / 皮肤光晕
|
||
|
||
动画更新并 `computeWorld` 后，用 `attachToBoneByName` 绑定肢体，或用 `setSkinSource` 从蒙皮表面发射；`setAttachScale` / `setSkinScale` 把模型单位映射到像素空间。
|
||
|
||
## 常见问题
|
||
|
||
- buffer 太小导致高发射率粒子被覆盖。
|
||
- 只 render 不 update，粒子静止。
|
||
- 无限 emitter 离开场景后未 stop/回收。
|
||
- 骨骼绑定后位置不对：检查是否先更新姿态（`pose.computeWorld(sk)` / `spine.updateWorldTransform()` / IK `forwardKinematics`/`solve`），以及 `plane`/`scale` 是否匹配相机投影。
|
||
- 蒙皮表面无粒子：确认 `setSkinSource` 与 `hasBones` 网格，且过滤器未把候选顶点剔光。
|
||
|
||
## API 快查
|
||
|
||
下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 `World`、`Body`、`Source`）的方法也列在这里。
|
||
|
||
- `addBurst()`、`addColorStop()`、`addForceField()`、`addRotationCurvePoint()`、`addSizeCurvePoint()`、`addSubEmitter()`、`addVelocityCurvePoint()`、`applyConfig()`、`applyPreset()`、`attachToBone()`、`attachToBoneByName()`、`attachToSkeleton2D()`、`attachToSkeleton3D()`、`attachToSpineBone()`、`attachToSpineBoneByName()`、`bindFloatParameter()`、`clearBursts()`、`clearColorGradient()`、`clearFloatParameterBindings()`、`clearFloatParameters()`、`clearForceFields()`、`clearRotationCurve()`、`clearSizeCurve()`、`clearSkinSource()`、`clearSubEmitters()`、`clearVelocityCurve()`、`detach()`、`emit()`、`emitFromSkin()`、`getAttachBone()`、`getAttachKind()`、`getAutoRandomSeed()`、`getAutoReload()`、`getBlendMode()`、`getBufferSize()`、`getConfigPath()`、`getCount()`、`getDirection()`、`getEmissionRateOverDistance()`、`getFixedTimeStep()`、`getGpuSimulation()`、`getLightsEnabled()`、`getLooping()`、`getPlaybackSpeed()`、`getPrewarmSeconds()`、`getRandomSeed()`、`getShader()`
|
||
- `getEmissionAreaType()`、`getEmissionAreaX()`、`getEmissionAreaY()`、`getEmissionRate()`、`getEmitterCount()`、`getEmitterLifetime()`、`getEmitterName()`、`getEmitter()`、`getEmitterByName()`、`getFloatParameter()`、`getGpuFallbackReason()`、`getLastEffectError()`、`getLayer()`、`getName()`、`getPriority()`、`getMinimumQuality()`、`getCullingMode()`、`getCullDistance()`、`getMaxSpawnPerFrame()`、`getMaterialMode()`、`getDistortionStrength()`、`getNormalTexture()`、`getResolvedParameterScale()`、`getRotation()`、`getScale()`、`getSimulationBackend()`、`getSourcePath()`、`getVersion()`
|
||
- `getMaxParticles()`、`getMaxSimulatedEmitters()`、`getQualityLevel()`、`getLastSimulatedEmitters()`、`getLastCulledEmitters()`、`getLastBudgetSkippedEmitters()`、`getLastParticleCount()`、`getLastSpawnedParticles()`、`getLastDroppedSpawns()`、`getLastRenderedParticles()`、`getLastSimulationMs()`、`getLastRenderMs()`
|
||
- `getParticleHeight()`、`getParticleLifetimeMax()`、`getParticleLifetimeMin()`、`getParticleWidth()`、`getSizeVariation()`、`getSpread()`、`getX()`、`getY()`
|
||
- `hasFloatParameter()`、`hasSkinSource()`、`isActive()`、`isAttached()`、`isGpuFeatureSetSupported()`、`isPaused()`、`isStopped()`、`isVisible()`、`loadConfig()`、`moveTo()`、`newEffectFromFile()`、`newEffectFromText()`、`newEmitter()`、`newEmitterFromFile()`
|
||
- `pause()`、`pollConfigs()`、`reloadConfig()`、`render()`、`reset()`、`setAttachOffset()`、`setAttachPlane()`、`setAttachScale()`、`setAutoReload()`、`setCamera()`、`setCanvas()`、`getConfigReloadObservation()`
|
||
- `setAutoRandomSeed()`、`setBlendMode()`、`setBudget()`、`setCollision()`、`setCollisionBounds()`、`setColorEnd()`、`setColorStart()`、`setCullingMode()`、`setCullDistance()`、`setDamping()`、`setDirection()`、`setDistortionStrength()`、`setEmissionArea()`、`setEmissionRate()`、`setEmissionRateOverDistance()`、`setEmitterLife()`、`setEmitterLifetime()`、`setEmitterTime()`、`setFixedTimeStep()`、`setFlipbook()`、`setFloatParameter()`、`setGpuSimulation()`、`setGravity()`、`setInheritVelocity()`、`setLights()`、`setLimitVelocity()`、`setLooping()`、`setMaterialMode()`、`setMaxDeltaTime()`、`setMaxSpawnPerFrame()`、`setMinimumQuality()`、`setNoise()`、`setNormalTexture()`、`setOverflowMode()`、`setPlaybackSpeed()`、`setPrewarm()`、`setPriority()`、`setQualityLevel()`、`setRandomSeed()`、`setRenderMode()`、`setShader()`、`setSimulationSpace()`、`setWorldCollision()`
|
||
- `setFollowBoneRotation()`、`setLayer()`、`setLinearAcceleration()`、`setParticleLife()`、`setParticleLifetime()`、`setParticleSize()`、`setPosition()`、`setRadialAcceleration()`、`setRotation()`、`setScale()`、`setSizeVariation()`
|
||
- `setSizes()`、`setSkinBoneFilter()`、`setSkinBoneFilterByName()`、`setSkinPlane()`、`setSkinScale()`、`setSkinSource()`、`setSpeed()`、`setSpin()`、`setSpread()`、`setStartRotation()`、`setTangentialAcceleration()`、`setTexture()`、`setVisible()`、`start()`
|
||
- `stop()`、`syncAttach()`、`update()`
|
||
|
||
## 使用要点
|
||
|
||
- 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
|
||
- 带 `update(dt)` 的系统应在 `eve_update` 调用；绘制方法应在 `eve_render` 调用。
|
||
- 参数约束、默认值和返回类型以对应模块头文件及 `addFunc` 绑定为准；本文 API 快查与当前源码同步生成。
|
||
|
||
**源码：** [`src/modules/particles/`](../../../src/modules/particles/)
|
||
**相关测试：** [`test/particles.cpp`](../../../test/particles.cpp)、[`test/particles_effect_asset.cpp`](../../../test/particles_effect_asset.cpp)、[`test/particles_reference_effects.cpp`](../../../test/particles_reference_effects.cpp)、[`test/particles_attach_skin.cpp`](../../../test/particles_attach_skin.cpp)、[`test/particles_dynamic_bones.cpp`](../../../test/particles_dynamic_bones.cpp)、[`test/particles_attach_more.cpp`](../../../test/particles_attach_more.cpp)、[`test/particles_attach_extra.cpp`](../../../test/particles_attach_extra.cpp)。
|