particles.py

Particle System - CPU-based with threaded physics and renderer integration
v0.2.3

class ParticleType

Description

No documentation

Attributes
FIRE: Any = 'fire'
WATER: Any = 'water'
SMOKE: Any = 'smoke'
DUST: Any = 'dust'
SPARK: Any = 'spark'
SNOW: Any = 'snow'
SAND: Any = 'sand'
EXHAUST: Any = 'exhaust'
STARFIELD: Any = 'starfield'
EXPLOSION: Any = 'explosion'
ENERGY: Any = 'energy'
PLASMA: Any = 'plasma'
ANTIMATTER: Any = 'antimatter'
RADIOACTIVE: Any = 'radioactive'
MAGIC: Any = 'magic'
BUBBLE: Any = 'bubble'
LEAF: Any = 'leaf'
RAIN: Any = 'rain'
CUSTOM: Any = 'custom'
Methods

No methods defined.

class ExitPoint

Description

No documentation

Attributes
TOP: Any = 'top'
BOTTOM: Any = 'bottom'
LEFT: Any = 'left'
RIGHT: Any = 'right'
CENTER: Any = 'center'
CIRCULAR: Any = 'circular'
Methods

No methods defined.

class PhysicsType

Description

No documentation

Attributes
TOPDOWN: Any = 'topdown'
PLATFORMER: Any = 'platformer'
SPACESHOOTER: Any = 'spaceshooter'
Methods

No methods defined.

class ParticleConfig

Description

No documentation

Attributes
color_start: Tuple[int, int, int] = (255, 255, 255)
color_end: Tuple[int, int, int] = (255, 255, 255)
size_start: float = 4.0
size_end: float = 4.0
lifetime: float = 1.0
speed: float = 100.0
gravity: float = 98.0
damping: float = 0.98
fade_out: bool = True
grow: bool = False
spread: float = 45.0
Methods

No methods defined.

class ParticleSystem

Description

CPU-based particle system using NumPy arrays.
All physics updates happen when you call update().

Methods
def __init__(self: Any, max_particles: int) -> Any
No documentation
def _init_arrays(self: Any) -> Any
(Re)initialise all particle arrays to zero size.
def get_particles_names(self: Any, sort_name: bool = False, capitalize: bool = False) -> List[str]
No documentation
def get_physics_names(self: Any, sort_name: bool = False, capitalize: bool = False) -> List[str]
No documentation
def register_custom_particle(self: Any, name: str, config: ParticleConfig) -> Any
No documentation
def get_custom_particle(self: Any, name: str) -> Optional[ParticleConfig]
No documentation
def list_custom_particles(self: Any) -> List[str]
No documentation
def update_max_particles(self: Any, new_max: int) -> Any
Resize internal arrays, preserving active particles.
def get_render_data(self: Any) -> Dict[str, Any]
Return a copy of active particle data for rendering.
def emit(self: Any, x: float, y: float, particle_type: Union[ParticleType, str], count: int = 1, exit_point: ExitPoint = ExitPoint.CENTER, physics_type: PhysicsType = PhysicsType.TOPDOWN, spread: Optional[float] = None, angle: float = 0.0, custom_config: Optional[ParticleConfig] = None) -> Any
Emit new particles.
def update(self: Any, dt: float) -> Any
Update particle physics (called from main thread in single‑threaded mode).
def clear(self: Any) -> Any
Deactivate all particles.
def get_stats(self: Any) -> Dict[str, Any]
No documentation
def _resolve_config(self: Any, particle_type: Union[ParticleType, str], custom_config: Optional[ParticleConfig]) -> Optional[ParticleConfig]
No documentation
def _get_exit_position(self: Any, x: float, y: float, exit_point: ExitPoint, offset: float) -> Tuple[float, float]
No documentation
def _get_initial_velocity(self: Any, config: ParticleConfig, exit_point: ExitPoint, spread: float, base_angle: float) -> Tuple[float, float]
No documentation
def _update_properties(self: Any, indices: np.ndarray) -> Any
Update particle color and size based on remaining life.

class ThreadedParticleSystem

Description

ParticleSystem variant that updates physics in a separate thread.
The main thread's update() call becomes a no‑op – the thread runs
continuously at a fixed timestep.

Also provides a render(camera) method that uses the renderer passed
during construction, making it a drop‑in replacement for the old
GPUParticleSystem.

Methods
def __init__(self: Any, renderer: Any, max_particles: int, target_fps: int = 60, auto_start: bool = True) -> Any
No documentation
def start_thread(self: Any) -> Any
Start the background physics thread.
def stop_thread(self: Any, join: bool = True) -> Any
Stop the background thread.
def _thread_loop(self: Any) -> Any
Thread main loop: run physics at fixed timestep.
def update(self: Any, dt: float) -> Any
In threaded mode, do nothing (thread handles updates).
def emit(self: Any, *args: tuple, **kwargs: dict) -> Any
No documentation
def clear(self: Any) -> Any
No documentation
def update_max_particles(self: Any, new_max: int) -> Any
Stop thread, resize, then restart.
def get_render_data(self: Any) -> Dict[str, Any]
Return a copy of data while holding the lock.
def get_stats(self: Any) -> Dict[str, Any]
No documentation
def render(self: Any, camera: Any) -> Any
Render all active particles using the stored renderer.
This method matches the interface expected by the engine.
def __del__(self: Any) -> Any
No documentation
Back to Graphics Module