01 Overview

This section adds a looping tap-note tutorial with navigation, instructions, sound, and particles. Complete the Play, Watch, and Preview sections first, then continue in the same checkout.

Scripted Video

An engine tutorial works like a scripted video. The engine draws each frame, and players use the navigation UI to move between demonstrations.

Typically, each note type has a phase with several parts:

• The intro shows the note enlarged.
• The fall shows the note moving toward the judgment line.
• The frozen part pauses the note and uses instruction text and icons to teach the player how to hit it.
• The hit plays effects when the frozen part ends.
• A short pause follows the effects before the phase repeats.

Callbacks and Phases

TutorialMode uses three callbacks in this guide:

• preprocess sets up the UI, layout, and phase clock.
• update draws each frame and advances the demonstration.
• navigate runs when the player presses either navigation button.

guide/tutorial/mode.py already connects these callbacks. You do not need to edit that file in this section.

Keep these timing terms in mind:

• A phase is one complete note demonstration, from its intro through the pause before it repeats.
• The phase clock measures seconds since the current phase started.
• A range is a span on that clock, such as the two seconds used for the falling note.
• A boundary is one instant between ranges. The hit occurs at a boundary because it must run once, not throughout a range.

This structure keeps the sequence and its timing in one place. The stage is drawn every frame, while the active phase draws the note and plays its hit effects.

We will implement the tutorial-specific drawing in guide/tutorial/stage.py and guide/tutorial/note.py, then connect it in guide/tutorial/update.py.

Testing Tutorial Mode

With the development server running, open the tutorial in Sonolus. The following chapters add its UI, drawing, instructions, sound, and particle effect.