sonolus.script.particle

EmptyParticles

A particle set with no particles, used as the default when a mode declares none.

Particle

Bases: Record

A particle effect.

is_available: bool property

Check if the particle effect is available.

spawn(quad: QuadLike, duration: float, loop: bool = False) -> ParticleHandle

Spawn the particle effect.

Parameters:

Name	Type	Description	Default
quad	QuadLike	The quad to spawn the particle effect on.	required
duration	float	The duration of the particle effect.	required
loop	bool	Whether to loop the particle effect.	False

Returns:

Type	Description
ParticleHandle	A handle to the spawned particle effect.

ParticleGroup

Bases: Record, ArrayLike[Particle]

A group of particle effects.

Does not support negative indexes.

Usage

ParticleGroup(start_id: int, size: int)

__getitem__(index: int) -> Particle

Return the particle effect at the given index.

Parameters:

Name	Type	Description	Default
index	int	The index of the particle effect. Must be an integer between 0 and len(self) - 1.	required

__len__() -> int

Return the number of particle effects in the group.

__setitem__(index: int, value: Particle) -> None

Raise a compile-time error; particle groups are read-only.

get_unchecked(index: int) -> Particle

Return the particle effect at the given index, possibly without bounds checking.

ParticleHandle

Bases: Record

A handle to a spawned particle effect.

destroy() -> None

Destroy the particle effect.

move(quad: QuadLike) -> None

Move the particle effect to a new location.

Parameters:

Name	Type	Description	Default
quad	QuadLike	The new quad to move the particle effect to.	required

StandardParticle

Standard particles.

particle(name: str) -> Any

Define a particle with the given name.

particle_group(names: Iterable[str]) -> Any

Define a particle group with the given names.

particles(cls: type[T]) -> T | Particles

Decorator to define particles.

Usage

@particles
class Particles:
    tap: StandardParticle.NOTE_CIRCULAR_TAP_RED
    other: Particle = particle("other")
    group_1: ParticleGroup = particle_group(["one", "two", "three"])
    group_2: ParticleGroup = particle_group(f"name_{i}" for i in range(10))