@ignifx/particles 0.21.0 → 0.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/skills/particles/SKILL.md +74 -74
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/particles",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.22.0",
|
|
4
4
|
"description": "ignifx particles: stateless GPU particle systems driven by declarative .particles.json definitions.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ignifx",
|
|
@@ -44,11 +44,11 @@
|
|
|
44
44
|
"typescript-native": "npm:typescript@7.0.2",
|
|
45
45
|
"vitest": "^5.0.0",
|
|
46
46
|
"wgsl_reflect": "^1.6.0",
|
|
47
|
-
"@ignifx/core": "0.
|
|
47
|
+
"@ignifx/core": "0.22.0"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
50
|
"@babylonjs/lite": "1.34.0",
|
|
51
|
-
"@ignifx/core": "0.
|
|
51
|
+
"@ignifx/core": "0.22.0"
|
|
52
52
|
},
|
|
53
53
|
"ignifx": {
|
|
54
54
|
"extension": true,
|
|
@@ -3,7 +3,7 @@ name: particles
|
|
|
3
3
|
description: Builds GPU particle effects in ignifx with @ignifx/particles: fire, smoke, sparks, explosions, weather and magic, declared in .particles.json and evaluated on the GPU from CPU-written spawn records. Use when adding or editing a particle effect, an emitter, or a .particles.json document in an ignifx project, or when the user mentions @ignifx/particles, ParticleSystem, particleDefinition, or app.particles.
|
|
4
4
|
license: Apache-2.0
|
|
5
5
|
metadata:
|
|
6
|
-
ignifx-version: "0.
|
|
6
|
+
ignifx-version: "0.22.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# @ignifx/particles
|
|
@@ -21,7 +21,7 @@ trades those away, and "Gotchas" below says what to do instead. For 2D sprite pa
|
|
|
21
21
|
|
|
22
22
|
## Environment
|
|
23
23
|
|
|
24
|
-
- Engine: ignifx `0.
|
|
24
|
+
- Engine: ignifx `0.22.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
|
|
25
25
|
- Requires nothing but `@ignifx/core`. `@ignifx/physics` is optional: when it is registered, an
|
|
26
26
|
effect that asks for "the world's gravity" reads the `physics` settings section.
|
|
27
27
|
- WebGPU only, browser and Electron. Babylon Lite `1.34.0` is a peer dependency, and this package
|
|
@@ -56,10 +56,10 @@ emit() ──▶ spawn record ──▶ ring buffer (capacity records)
|
|
|
56
56
|
vertex shader: state(t) = f(record, clock) ──▶ one instanced draw
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
| Thing
|
|
60
|
-
|
|
|
61
|
-
| Emission (`ParticleUpdateSystem`)
|
|
62
|
-
| Upload and uniforms (`ParticleRenderSystem`) | `PreRender` | `880` | Before core's shader-uniform and render-sync systems
|
|
59
|
+
| Thing | Phase | Order | Why there |
|
|
60
|
+
| --- | --- | --- | --- |
|
|
61
|
+
| Emission (`ParticleUpdateSystem`) | `Update` | `900` | After every script's `update`, so `emit()` from a script draws this frame |
|
|
62
|
+
| Upload and uniforms (`ParticleRenderSystem`) | `PreRender` | `880` | Before core's shader-uniform and render-sync systems |
|
|
63
63
|
|
|
64
64
|
What follows from being stateless:
|
|
65
65
|
|
|
@@ -108,37 +108,37 @@ app.dispose();
|
|
|
108
108
|
|
|
109
109
|
### `ParticleSystem`
|
|
110
110
|
|
|
111
|
-
| Member
|
|
112
|
-
|
|
|
113
|
-
| `definition`
|
|
114
|
-
| `playOnAwake`
|
|
115
|
-
| `seed`
|
|
116
|
-
| `play()`
|
|
117
|
-
| `stop({ clear })`
|
|
118
|
-
| `pause()` / `resume()`
|
|
119
|
-
| `emit(count)`
|
|
120
|
-
| `simulate(seconds)`
|
|
121
|
-
| `isPlaying` / `isPaused` | Playback state.
|
|
122
|
-
| `aliveCount`
|
|
123
|
-
| `drawCount`
|
|
124
|
-
| `droppedCount`
|
|
125
|
-
| `time`
|
|
126
|
-
| `capacity`
|
|
127
|
-
| `onStopped`
|
|
128
|
-
| `evaluate(slot, out)`
|
|
111
|
+
| Member | What it does |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| `definition` | The `.particles.json` handle it plays. Assigning a different one rebuilds the effect. |
|
|
114
|
+
| `playOnAwake` | Play the first frame the component is enabled. The document's own `main.playOnAwake` must agree. |
|
|
115
|
+
| `seed` | The emission seed. `0` uses the document's, and `0` there picks one at random on `play()`. |
|
|
116
|
+
| `play()` | Start, or resume after `stop()`. A `prewarm` document fast-forwards one cycle first. |
|
|
117
|
+
| `stop({ clear })` | Stop emitting. Live particles finish their lives unless `clear` is `true`. |
|
|
118
|
+
| `pause()` / `resume()` | Hold and release the system clock. Everything freezes in place. |
|
|
119
|
+
| `emit(count)` | Spawn `count` particles at the current clock, playing or not. `qualityScale` does not apply. |
|
|
120
|
+
| `simulate(seconds)` | Fast-forward in sixtieths, emitting as it goes. What `prewarm` uses. |
|
|
121
|
+
| `isPlaying` / `isPaused` | Playback state. |
|
|
122
|
+
| `aliveCount` | How many particles are alive. Exact, on the CPU, headless too. |
|
|
123
|
+
| `drawCount` | How many records the GPU draws: the newest back to the oldest still alive. |
|
|
124
|
+
| `droppedCount` | Spawns that displaced a particle that was still alive, because the capacity is too small for the rate. |
|
|
125
|
+
| `time` | The system's own clock, in seconds. `app.time` is never read. |
|
|
126
|
+
| `capacity` | The records it holds, after `app.particles.maxParticles` clamped the document's. |
|
|
127
|
+
| `onStopped` | Emitted once when a non-looping system runs out of cycle and particles. |
|
|
128
|
+
| `evaluate(slot, out)` | The CPU twin of the shader: one record's world state at the current clock. `@beta`, for tools. |
|
|
129
129
|
|
|
130
130
|
Several effects may share one entity: `ParticleSystem` is `allowMultiple`.
|
|
131
131
|
|
|
132
132
|
### `app.particles`
|
|
133
133
|
|
|
134
|
-
| Member
|
|
135
|
-
|
|
|
136
|
-
| `maxParticles`
|
|
137
|
-
| `qualityScale`
|
|
138
|
-
| `gravity`
|
|
139
|
-
| `systems`
|
|
140
|
-
| `capacityInUse` | How much of the budget the attached systems hold.
|
|
141
|
-
| `counters`
|
|
134
|
+
| Member | What it does |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| `maxParticles` | The budget every system's `capacity` is counted against. Default `100_000`. |
|
|
137
|
+
| `qualityScale` | A `0`–`1` multiplier on every emission rate and burst count, read each frame. For settings screens. |
|
|
138
|
+
| `gravity` | The world gravity a document's `forces.gravityMultiplier` scales. Defaults to `(0, -9.81, 0)`. |
|
|
139
|
+
| `systems` | Every attached `ParticleSystem`, in attach order. |
|
|
140
|
+
| `capacityInUse` | How much of the budget the attached systems hold. |
|
|
141
|
+
| `counters` | The `particles` diagnostics group: `systems`, `alive`, `emitted`, `uploadBytes`, `drawCalls`. |
|
|
142
142
|
|
|
143
143
|
### Presets
|
|
144
144
|
|
|
@@ -157,15 +157,15 @@ export const bigFire = particleDefinition("fire", {
|
|
|
157
157
|
|
|
158
158
|
### The module set
|
|
159
159
|
|
|
160
|
-
| Module
|
|
161
|
-
|
|
|
162
|
-
| `main`
|
|
163
|
-
| `emission`
|
|
164
|
-
| `shape`
|
|
165
|
-
| `start`
|
|
166
|
-
| `forces`
|
|
167
|
-
| `overLifetime` | `color` (gradient), `size`, `sizeY`, `sizeZ`, `rotation` (angular speed)
|
|
168
|
-
| `renderer`
|
|
160
|
+
| Module | Fields |
|
|
161
|
+
| --- | --- |
|
|
162
|
+
| `main` | `capacity`, `duration`, `looping`, `prewarm`, `startDelay`, `simulationSpace`, `seed`, `playOnAwake`, `timeScale`, `renderOrder` |
|
|
163
|
+
| `emission` | `rateOverTime`, `rateOverDistance`, `bursts: [{ time, count, cycles, interval, probability }]` |
|
|
164
|
+
| `shape` | `kind` (`point`, `sphere`, `hemisphere`, `cone`, `box`, `circle`, `edge`, `mesh`), `radius`, `thickness`, `arc`, `angle`, `length`, `size`, `emitFrom`, `randomDirection`, `spherizeDirection`, `vertices` |
|
|
165
|
+
| `start` | `lifetime`, `speed`, `size`, `size3D`, `rotation`, `color` |
|
|
166
|
+
| `forces` | `gravity`, `gravityMultiplier`, `drag`, `constantForce`, `orbit: { axis, speed }`, `noise: { strength, frequency, scroll, octaves, influenceOverLife }` |
|
|
167
|
+
| `overLifetime` | `color` (gradient), `size`, `sizeY`, `sizeZ`, `rotation` (angular speed) |
|
|
168
|
+
| `renderer` | `mode` (`billboard`, `stretched`, `horizontal`, `vertical`, `mesh`), `mesh`, `texture`, `sheet`, `blend`, `lit`, `pivot`, `speedScale`, `lengthScale` |
|
|
169
169
|
|
|
170
170
|
A **value** is a number, `{ "min": a, "max": b }` (rolled once per particle), or
|
|
171
171
|
`{ "curve": { "keys": [[t, v, inTangent, outTangent], …] } }` (read at the particle's age). A
|
|
@@ -177,15 +177,15 @@ GPU read the same way.
|
|
|
177
177
|
one sends particles along local `+Y`. Rotate the entity to aim it; a negative `start.speed` reverses
|
|
178
178
|
it. Two of them lie flat in the ground plane, which is the usual surprise:
|
|
179
179
|
|
|
180
|
-
| Shape
|
|
181
|
-
|
|
|
182
|
-
| `circle`
|
|
183
|
-
| `edge`
|
|
184
|
-
| `box`
|
|
185
|
-
| `cone`
|
|
186
|
-
| `sphere`, `hemisphere` | X, Y and Z by `radius`
|
|
187
|
-
| `point`
|
|
188
|
-
| `mesh`
|
|
180
|
+
| Shape | Spread | Direction |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| `circle` | X and Z, nothing in Y | Radially outward in the XZ plane — a ring seen from above |
|
|
183
|
+
| `edge` | X only | `+Y` |
|
|
184
|
+
| `box` | X, Y and Z by `size` | `+Y` |
|
|
185
|
+
| `cone` | X and Z on the base disc by `radius` | `+Y`, opening out by `angle` — a wide `angle` spreads in X/Z |
|
|
186
|
+
| `sphere`, `hemisphere` | X, Y and Z by `radius` | Radially outward (`hemisphere` keeps `y >= 0`) |
|
|
187
|
+
| `point` | Nothing | `+Y` |
|
|
188
|
+
| `mesh` | The triangles you supply | Along each face normal |
|
|
189
189
|
|
|
190
190
|
A camera looking down `-Z` at a scene laid out in X and Y therefore sees a `circle` edge-on, as a
|
|
191
191
|
horizontal line, and sees a wide `cone` spread sideways while it travels up. For a fan in the camera
|
|
@@ -194,11 +194,11 @@ emitter ninety degrees about X so the circle faces the camera.
|
|
|
194
194
|
|
|
195
195
|
### Choosing a blend
|
|
196
196
|
|
|
197
|
-
| Blend
|
|
198
|
-
|
|
|
197
|
+
| Blend | Use it for | Why |
|
|
198
|
+
| --- | --- | --- |
|
|
199
199
|
| `premultiplied` | Smoke, dust, mixed effects (default) | Fire and smoke can share one draw and still composite front to back correctly. |
|
|
200
|
-
| `additive`
|
|
201
|
-
| `alpha`
|
|
200
|
+
| `additive` | Fire, sparks, glints, magic | Light adds; overlapping particles get brighter, and black is transparent. |
|
|
201
|
+
| `alpha` | Rain, leaves, anything with an edge | Straight alpha over the background, with no brightening. |
|
|
202
202
|
|
|
203
203
|
Particles never write depth and are never depth-sorted against each other. `main.renderOrder` orders
|
|
204
204
|
whole systems within the transparent phase; lower draws first.
|
|
@@ -329,9 +329,9 @@ export const exhaust = particleDefinition("smoke", {
|
|
|
329
329
|
|
|
330
330
|
## File formats
|
|
331
331
|
|
|
332
|
-
| Format
|
|
333
|
-
|
|
|
334
|
-
| `ignifx.particles` | `.particles.json` | `skills/ignifx/references/formats
|
|
332
|
+
| Format | Extension | Reference |
|
|
333
|
+
| --- | --- | --- |
|
|
334
|
+
| `ignifx.particles` | `.particles.json` | `skills/ignifx/references/formats/ignifx.particles.md` in the `ignifx` package |
|
|
335
335
|
|
|
336
336
|
Every module and every field is optional; `defineParticles` fills in the defaults and refuses a
|
|
337
337
|
document it cannot read with `IGX-1701`, naming the exact path — `start.lifetime.min`, not "invalid
|
|
@@ -339,19 +339,19 @@ document". A misspelled key is an error, not a silent no-op.
|
|
|
339
339
|
|
|
340
340
|
## Gotchas
|
|
341
341
|
|
|
342
|
-
| Trap
|
|
343
|
-
|
|
|
344
|
-
| Expecting particles to collide, or to spawn more particles | Neither is a function of the particle's age, so the shader cannot compute it. There is no collision module and no sub-emitter.
|
|
345
|
-
| Expecting particles to sort against each other
|
|
346
|
-
| A looping effect that starts empty and fills in
|
|
347
|
-
| A rate the capacity cannot hold
|
|
348
|
-
| A system that draws nothing after a while
|
|
349
|
-
| `app.pause()` and an effect that keeps moving
|
|
350
|
-
| `emit()` before the definition has loaded
|
|
351
|
-
| The first frames of a new effect drawing nothing
|
|
352
|
-
| Reading `app.time.time` to age particles
|
|
353
|
-
| A gradient authored in linear colour
|
|
354
|
-
| Expecting `stop()` to clear the screen
|
|
342
|
+
| Trap | What happens | Do this instead |
|
|
343
|
+
| --- | --- | --- |
|
|
344
|
+
| Expecting particles to collide, or to spawn more particles | Neither is a function of the particle's age, so the shader cannot compute it. There is no collision module and no sub-emitter. | Hit an effect at the point your own code decides: play a second `ParticleSystem` there, or drive a `Rigidbody` for the few pieces that matter. |
|
|
345
|
+
| Expecting particles to sort against each other | They never write depth and are never depth-sorted, so two overlapping systems composite in draw order. | Use `additive` (order-independent), or set `main.renderOrder` to order whole systems. |
|
|
346
|
+
| A looping effect that starts empty and fills in | Without `prewarm` the first cycle is the effect filling up; a campfire the player walks up to should already be burning. | `"main": { "prewarm": true }` on a looping document, or call `system.simulate(seconds)` after `play()`. |
|
|
347
|
+
| A rate the capacity cannot hold | The ring overwrites the oldest live particle, so the effect visibly thins out. `droppedCount` counts each one. | `capacity` at least `rateOverTime × the longest lifetime`. Check `system.droppedCount` after a few seconds. |
|
|
348
|
+
| A system that draws nothing after a while | `app.particles.maxParticles` ran out and the system was clamped; `IGX-1702` was logged once, naming the entity. | Raise `maxParticles` in `ignifx.config.ts`, or give the document a smaller `capacity`. |
|
|
349
|
+
| `app.pause()` and an effect that keeps moving | It cannot: the system clock advances only while `time.paused` is false. An effect that _should_ keep moving while paused has no switch. | Nothing to do — pause is exact. For a menu background, keep it in its own app or run it with `main.timeScale` and your own `simulate()`. |
|
|
350
|
+
| `emit()` before the definition has loaded | `IGX-1705`: the system has no document, so it cannot spawn anything. | Await the handle, or emit from `update` and let the first frames pass; `aliveCount` stays `0` until the document arrives. |
|
|
351
|
+
| The first frames of a new effect drawing nothing | The generated program is loaded as an asset and compiled on first draw, which takes a few frames. | Expect it, or warm the effect up during a loading screen by adding the system while the screen is still showing. |
|
|
352
|
+
| Reading `app.time.time` to age particles | A system's clock is its own: `timeScale`, `pause()` and `simulate()` all move it independently. | Read `system.time`. |
|
|
353
|
+
| A gradient authored in linear colour | Document colours are sRGB in `0`–`1`, decoded on the way to the GPU, so linear values come out dark. | Author the numbers you would type into a colour picker. |
|
|
354
|
+
| Expecting `stop()` to clear the screen | It stops emission; the live particles finish their lives, which is what a torch being put out looks like. | `stop({ clear: true })` to drop them all at once. |
|
|
355
355
|
|
|
356
356
|
- `simulate(seconds)` advances the records at once, but `aliveCount` and the draw count refresh in the next `app.step()`, when the update system runs its census.
|
|
357
357
|
- In an edit-mode app (`createApp({ editMode: true })`) a system still plays on awake and shows its first frame, but its clock stands still. `simulate(seconds)` previews it.
|
|
@@ -362,7 +362,7 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
|
|
|
362
362
|
|
|
363
363
|
## Where to look next
|
|
364
364
|
|
|
365
|
-
`skills/ignifx/SKILL.md`
|
|
366
|
-
the
|
|
367
|
-
`
|
|
368
|
-
`
|
|
365
|
+
The entry skill is `skills/ignifx/SKILL.md` in the `ignifx` package: `node_modules/ignifx/` in an
|
|
366
|
+
installed project, the repository root in the engine repository. Under it, `references/api/particles.md` has every exact signature and
|
|
367
|
+
`references/formats/ignifx.particles.md` the document's fields. The `@ignifx/particles-2d` skill
|
|
368
|
+
(`skills/particles-2d/SKILL.md` in that package) draws the same documents as sprites.
|