Skip to content

sonolus.script.effect

Effect

Bases: Record

Sound effect clip.

Usage 
Effect(id: int)

id: int instance-attribute

Effect ID.

is_available: bool property

Whether the effect clip is available.

loop() -> LoopedEffectHandle

Play the effect clip in a loop until stopped.

Not available in preview mode.

Returns:

Type Description
LoopedEffectHandle

A handle to stop the loop.

play(distance: float = 0) -> None

Play the effect clip.

If the clip was already played within the specified distance, it will be skipped.

Not available in preview mode.

Parameters:

Name Type Description Default
distance float

Minimum time in seconds since the last play for the effect to play.

 0

schedule(time: float, distance: float = 0) -> None

Schedule the effect clip to play at a specific time.

This is not suitable for real-time effects such as responses to user input. Use play instead.

This may be called in preprocess to schedule effects upfront.

Schedule at least 0.5 seconds before the target time when possible. Scheduling closer to the target may cause unexpected latency.

If the clip would play within the specified distance of another play, it will be skipped.

Not available in preview mode.

Parameters:

Name Type Description Default
time float

Time in seconds when the effect should play.

 required
distance float

Minimum time in seconds after a previous play for the effect to play.

 0

schedule_loop(start_time: float) -> ScheduledLoopedEffectHandle

Schedule the effect clip to play in a loop until stopped.

This is not suitable for real-time effects such as responses to user input. Use loop instead.

Schedule at least 0.5 seconds before the target time when possible. Scheduling closer to the target may cause unexpected latency.

Not available in preview mode.

Parameters:

Name Type Description Default
start_time float

The time in seconds at which to start the effect.

 required

Returns:

Type Description
ScheduledLoopedEffectHandle

A handle to stop the loop.

EffectGroup

Bases: Record, ArrayLike[Effect]

A group of effect clips.

Does not support negative indexes.

Usage 
EffectGroup(start_id: int, size: int)

__getitem__(index: int) -> Effect

Return the effect clip at the given index.

Parameters:

Name Type Description Default
index int

The index of the effect clip. Must be an integer between 0 and len(self) - 1.

 required

__len__() -> int

Return the number of effect clips in the group.

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

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

get_unchecked(index: int) -> Effect

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

EmptyEffects

An effect set with no effects, used as the default when a mode declares none.

LoopedEffectHandle

Bases: Record

Handle to stop a looped effect.

stop() -> None

Stop the looped effect.

Not available in preview mode.

ScheduledLoopedEffectHandle

Bases: Record

Handle to stop a scheduled looped effect.

stop(end_time: float) -> None

Stop the scheduled looped effect.

Schedule at least 0.5 seconds before the target time when possible. Scheduling closer to the target may cause unexpected latency.

Not available in preview mode.

Parameters:

Name Type Description Default
end_time float

The time at which to stop the effect.

 required

StandardEffect

Standard sound effect clips.

effect(name: str) -> Any

Define a sound effect clip with the given name.

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

Define an effect group with the given names.

effects(cls: type[T]) -> T | Effects

Decorator to define effect clips.

Usage 
@effects
class Effects:
    miss: StandardEffect.MISS
    other: Effect = effect("other")
    group_1: EffectGroup = effect_group(["one", "two", "three"])
    group_2: EffectGroup = effect_group(f"name_{i}" for i in range(10))