Documentation
Docs/en/reference/particle-format/runtime.md
Particle Runtime Contract
Generated reference. Do not edit this page directly. Update
BuildTools/ParticleFormatInterface.json, then runpython BuildTools/docs_particle_format.py --write.
| Reference index | Source rules | Formats and backends | Rendering | Tooling | Runtime | Integration | Validation | Canonical JSON model | Guide | Authoring tools |
| Stable ID | Rule | Requirement | Why | Source |
|---|---|---|---|---|
particle-format.runtime.backend-composition |
Backend composition | Compile only the particle backends selected by FO_SPARK_PARTICLES and FO_EFFEKSEER_PARTICLES. | CreateParticleRuntimeBackends is the single feature-aware composition point. | Source/Client/ParticleRuntime.cpp |
particle-format.runtime.extension-routing |
Runtime extension routing | Reference baked .spk or .efk paths; ParticleManager selects a backend by its advertised extension. | Authored source extensions are not runtime sprite formats. | Source/Client/VisualParticles.cpp |
particle-format.runtime.seed |
Seeded respawn | Use an explicit seed when deterministic replay or comparison is required. | The neutral facade forwards the seed to the selected backend. | Source/Client/VisualParticles.cpp |
particle-format.runtime.scale |
Runtime scale | Apply finite positive scale through ParticleSystem and revalidate bounds, depth, and attachment placement. | Scale is part of the backend-neutral runtime setup and forces a transform refresh. | Source/Client/VisualParticles.cpp |
particle-format.runtime.baked-bounds |
Mandatory baked bounds | Bake each particle system’s simulated position box and maximum billboard radius into the runtime resource. SPARK rejects a system that never shows a particle; Effekseer appends and validates a mandatory bounds trailer. | Static measured bounds replace manual draw dimensions and avoid recomputing a particle AABB every frame. | Source/Tools/ParticleBaker.cpp Source/Client/EffekseerExtension.cpp |
particle-format.runtime.bounds-semantics |
Position box and billboard radius | Treat ParticleBounds3D.PositionMin/PositionMax as world positions transformed by the full placement matrix, and BillboardRadius as camera-facing padding transformed by placement scale only. | Rotating or sweeping billboard radius as a world point overstates the frame and can still misrepresent its screen footprint. | Source/Client/ParticleRuntime.h |
particle-format.runtime.live-bounds |
Live bounds | GetLiveBounds returns transformed baked bounds only while the backend has live particles or instances; dormant and finished systems reserve no model-frame space. | Occasional attached effects must expand their owning model only while visible. | Source/Client/SparkExtension.cpp Source/Client/EffekseerExtension.cpp Source/Client/ModelInstance.cpp |
particle-format.runtime.sprite-frame |
Automatic particle sprite frame | ParticleSystem projects baked bounds through the map-camera tilt, adds billboard and antialiasing margins, and derives atlas size, emitter offset, and world transform automatically. Invalid or unavailable bounds fall back to Render.DefaultParticleDrawWidth/Height. | ParticleSprite allocation follows measured effect content without an authored draw-size field. | Source/Client/VisualParticles.cpp Source/Client/ParticleSprites.cpp |
particle-format.runtime.prewarm |
Prewarm | Use prewarm only when the effect must enter already simulated, and include its cost in the project performance gate. | The runtime advances the selected backend and resets facade timing to the reported elapsed time. | Source/Client/VisualParticles.cpp |
particle-format.runtime.update-cadence |
Update cadence | Render.Animation3dFPS sets the millisecond particle update threshold; zero leaves the threshold at zero and therefore permits an update every frame. | Particle simulation cadence shares the 3D animation setting rather than owning an independent particle FPS. | Source/Client/VisualParticles.cpp Source/Common/Settings.inc |
particle-format.runtime.atlas-path |
Default offscreen-atlas path | With draw in scene false, updates render the SPARK system into an intermediate render target and copy it into the sprite atlas; normal sprite batching draws the resulting quad. | The default path preserves ordinary sprite ordering and batching at the cost of flattening particle depth. | Source/Client/ParticleSprites.cpp |
particle-format.runtime.scene-path |
Direct map-scene path | With draw in scene true, ParticleSprite is direct-draw and renders SPARK geometry against the map projection and shared depth target instead of refreshing its atlas region. | World-space particles can be occluded by standing sprites and models according to the selected .fofx depth state. | Source/Client/ParticleSprites.h Source/Client/ParticleSprites.cpp |
particle-format.runtime.sprite-semantics |
ParticleSprite animation semantics | ParticleSprite is non-copyable and never hit-tests; Play respawns, Stop is a no-op, SetTime and SetDir are ignored, and IsPlaying mirrors SPARK active state. | Generic Sprite animation controls do not map to SPARK timeline or direction selection. | Source/Client/ParticleSprites.h Source/Client/ParticleSprites.cpp |
particle-format.runtime.world-scale |
Shared model and particle scale | Render.ModelProjFactor is screen pixels per 3D world unit for models and in-scene particles. The Engine default is 40.0; embedding projects may override it consistently. | ParticleSprite and model projection use the same scale setting, so project overrides affect both. | Source/Common/Settings.inc Source/Client/ParticleSprites.cpp |