09 Particle Effect

In this chapter, we will add a particle effect to the tap phase's hit event.

Existing Particle

The shared Particles class already declares the standard cyan circular tap particle from play mode. This code is for reference. Do not edit guide/lib/particle.py:

from sonolus.script.particle import StandardParticle, particles


@particles
class Particles:
    # ...

    note: StandardParticle.NOTE_CIRCULAR_TAP_CYAN

Particle Effect

In guide/tutorial/note.py, add this import with the other guide imports:

from guide.lib.particle import Particles

Then replace play_note_hit_effects with:

def play_note_hit_effects():
    layout = Rect.from_center(
        Vec2(0, 1),
        Vec2(4 * Config.note_radius, -4 * Config.note_radius),
    )
    Effects.perfect.play()
    Particles.note.spawn(layout, duration=0.3)

Sprites and particles use the engine coordinate system, so setting the particle's center to Vec2(0, 1) places it on the judgment line.

Checkpoint

Open the tutorial in Sonolus. Confirm that:

• The judgment line remains visible throughout the phase.
• The note appears enlarged, falls to the judgment line, and freezes there with the tap text and animated hand.
• The sound and particle play once when the frozen range ends.
• A one-second pause follows the hit. The particle remains visible for the first 0.3 seconds of that pause. The phase restarts when the full second ends.
• Either navigation button restarts the phase immediately.

When these checks pass, rebuild the complete project with the finished tutorial:

uv run sonolus-py build

Supporting more note types requires additional drawing functions, phase functions, resources, and state that selects the active phase. Those extensions are outside the scope of this guide.