simvx.core.particle_trail

Particle trail data — ring-buffer position history with ribbon mesh generation.

Module Contents

Classes

ParticleTrailData

Stores per-particle position history and generates ribbon mesh vertices.

Data

__all__
TRAIL_VERTEX_FLOATS

API

simvx.core.particle_trail.__all__

[‘ParticleTrailData’]

simvx.core.particle_trail.TRAIL_VERTEX_FLOATS

9

class simvx.core.particle_trail.ParticleTrailData(max_particles: int, trail_length: int = 5, trail_width: float = 0.1)

Stores per-particle position history and generates ribbon mesh vertices.

Each particle maintains a ring buffer of recent positions. The trail renderer reads these to produce a camera-facing ribbon strip that narrows and fades toward the tail.

Args: max_particles: Maximum number of particles to track. trail_length: Number of history samples per particle. trail_width: Base width of the ribbon at the head.

Initialization

__slots__

(‘_max_particles’, ‘_trail_length’, ‘_trail_width’, ‘_history’, ‘_head’, ‘_counts’)

property trail_length: int

property trail_width: float

property history: numpy.ndarray

Raw history buffer (max_particles, trail_length, 3).

property counts: numpy.ndarray

Number of valid trail samples per particle.

clear()

Reset all trail data.

update(alive_particles: numpy.ndarray)

Record current positions of alive particles into the ring buffer.

Args: alive_particles: Structured array slice with ‘position’ field.

get_ordered_positions(particle_idx: int) → numpy.ndarray

Get trail positions for one particle in chronological order (oldest first).

Returns: Array of shape (count, 3) with positions from oldest to newest.

get_trail_vertices(alive_particles: numpy.ndarray | None = None) → numpy.ndarray | None

Generate ribbon mesh vertices from trail history.

Each trail segment becomes a quad (2 triangles, 6 verts). The ribbon faces up (Y-axis billboard) and tapers from trail_width at the head to zero at the tail. Color fades from particle color to transparent.

Args: alive_particles: Alive particle structured array (needs ‘color’ field). If None, uses white color.

Returns: Float32 array of shape (N, 9) with [x,y,z, r,g,b,a, u,v] per vertex, or None if no trails to render.