SubEmitterConfig Class
Definition
Namespace: Brine2D.Systems.Rendering
Describes a secondary burst of particles that ParticleSystem spawns at the position where a parent particle dies or spawns. Assign one or more instances to DeathSubEmitters or BirthSubEmitters.
Each SubEmitterConfig is self-contained: it carries its own visual and physics settings and does not require a separate entity or component in the ECS. The ParticleSystem creates a transient SubEmitterState internally and drives it for the lifetime of those sub-particles.
Inheritance System.Object → SubEmitterConfig
| Properties | |
|---|---|
| BoxAngle | Rotation angle in \<b>radians\</b> applied to the spawn box when Shape is Box. 0 \(default\) = axis-aligned. |
| BurstCount | Number of particles to burst at the trigger position. |
| ConeAngle | Full cone spread angle in \<b>degrees\</b> when Shape is Cone. Each particle's direction is randomised within �ConeAngle/2 of InitialVelocity. |
| EnableTrails | When true, sub-particles render a positional trail behind them. Requires TrailLength > 0. |
| EndSpeedMultiplier | Multiplier applied to the spawn-speed of each sub-particle at t = 1 \(death\). Default 1 \(no change\). Set to 0 to decelerate sub-particles to a halt over their lifetime. |
| Forces | Optional list of extra forces \(attractors, wind zones, etc\.\) applied to every live sub-particle during the update pass. Forces are evaluated in order and their results are summed into BaseVelocity, making them subject to subsequent damping and speed-over-lifetime scaling. |
| InitialVelocity | Base velocity given to each sub-particle. VelocitySpread randomises the direction; a zero vector combined with a non-zero spread produces an omnidirectional burst. Always world-space. Unlike Brine2D.Systems.Rendering.ParticleEmitterComponent.InitialVelocity, this vector is never rotated by an entity's Rotation because sub-emitters have no entity context. Sub-particles always spray in the configured world direction regardless of the orientation of the entity that owns the parent emitter. |
| LineAngle | Rotation angle in \<b>radians\</b> for the spawn line when Shape is Line. 0 = horizontal, MathF.PI / 2 = vertical. |
| LineLength | Length of the spawn segment in world units when Shape is Line. When 0 \(default\), falls back to ShapeSize.X. |
| MaxParticles | Hard cap on the total number of live sub-particles across \<em>all\</em> active SubEmitterState entries that share this config instance. When the cap is reached, new bursts for this config are skipped until existing sub-particles expire. Prevents runaway particle counts when the parent emitter's death rate is very high. Important: the cap is enforced by reference equality on the config instance. If the same SubEmitterConfig object is assigned to multiple parent emitters (e.g. both their BirthSubEmitters and DeathSubEmitters lists, or across different entities), all of those emitters share this single cap. Bursts from any one of them count against the limit and can starve the others. Create a separate SubEmitterConfig instance per parent emitter if independent caps are needed. |
| OnParticleDied | Optional callback invoked when a sub-particle expires naturally. The particle is passed with its final state and is returned to the pool immediately after the callback returns. Do not hold a reference to the particle. |
| OnParticleSpawned | Optional callback invoked immediately after a sub-particle is spawned and added to the active list. Do not hold a reference to the particle beyond the callback. |
| ParticleFrames | An ordered array of atlas regions used as animation frames over the sub-particle's lifetime. When set, takes priority over Brine2D.Systems.Rendering.SubEmitterConfig.ParticleAtlasRegion. Frames are distributed evenly across the lifetime \(frame 0 at birth, last frame at death\). |
| Shape | Shape of the area from which sub-particles are scattered relative to the trigger position. Defaults to Point \(all particles spawn at the exact trigger position\). Use Circle with SpawnRadius to scatter particles outward from an impact area. |
| ShapeSize | Width and height of the spawn area when Shape is Box. Has no effect for other shapes. |
| SpawnOnPerimeter | When true and Shape is Circle or Cone, particles spawn exactly on the perimeter of the circle rather than distributed within it. Useful for ring bursts. |
| SpawnRadius | Radius in world units used when Shape is Circle or Cone. Has no effect for other shapes. |
| StartSpeedMultiplier | Multiplier applied to the spawn-speed of each sub-particle at t = 0 \(birth\). Linearly interpolated toward EndSpeedMultiplier over the sub-particle's lifetime. Default 1 \(no change\). When either multiplier differs from 1, speed-over-lifetime is active and takes priority over Brine2D.Systems.Rendering.SubEmitterConfig.Damping for the non-gravity component of velocity. |
| TrailHeadAlpha | Alpha of the trail segment nearest to the particle head \(t = 1, newest position\). |
| TrailHeadSizeRatio | Size multiplier for the trail segment nearest to the particle head \(t = 1, newest position\). |
| TrailLength | Number of trail history slots. Only used when EnableTrails is true. |
| TrailMode | Controls how the trail history is rendered. Defaults to Sprites. Use Lines for a continuous ribbon on untextured particles. |
| TrailTailAlpha | Alpha of the trail segment farthest from the particle head \(t = 0, oldest position\). |
| TrailTailSizeRatio | Size multiplier for the trail segment farthest from the particle head \(t = 0, oldest position\). |
| TurbulenceFrequency | Spatial frequency of the turbulence noise field. Higher values produce tighter, higher-frequency swirls. Default is 0.02 \(world\-unit scale\). |
| TurbulenceStrength | Strength of per-particle velocity noise applied every frame using coherent value noise, frame-rate independently. 0 \(default\) disables turbulence. |
| VelocityInheritance | Fraction of the triggering particle's velocity added to each newly-spawned sub-particle's velocity at birth. 0 \(default\) means no inheritance. 1 means the sub-particle fully inherits the parent particle's velocity at the moment of the trigger \(death, birth, or lifetime\-fraction\). Useful for sparks or debris that should carry the momentum of the particle that produced them. Note:InitialVelocity is always in world space (no entity transform is applied to sub-emitters). The inherited velocity is added in world space on top of InitialVelocity after spread randomisation. |
| VelocitySpread | Random angular spread in \<b>degrees\</b> applied to InitialVelocity. |