02 Archetypes and Entities

This chapter introduces archetypes and entities.

Archetypes

An archetype defines the behavior shared by one kind of entity. An entity is one occurrence of that archetype in a level. In object-oriented terms, an archetype is like a class and an entity is like an instance of that class.

By the end of the Play section, play mode will have four archetypes. Initialization sets up the level. Input Manager coordinates player input. Stage handles the judgment line. Note handles each playable note.

In Sonolus.py, a play archetype is represented by a Python class derived from PlayArchetype. Sonolus calls callback methods at specific points in an entity's lifetime. For example, the Stage class in guide/play/stage.py includes these callbacks:

from sonolus.script.archetype import PlayArchetype
from sonolus.script.debug import debug_log
from sonolus.script.runtime import time

from guide.play.initialization import Initialization


class Stage(PlayArchetype):
    def spawn_order(self) -> int:
        return -9

    def should_spawn(self) -> bool:
        return Initialization.at(0).is_despawned

    def update_parallel(self):
        debug_log(time())

The callback names use Python's usual snake_case naming convention. Initialization.at(0) accesses the entity at index 0 in the level's entity list. The template keeps Initialization at that index, so Stage can wait for it to despawn before Stage spawns. After Stage spawns, update_parallel logs the current time once per frame.

Entities

Levels define their gameplay as a list of entities. The template level in guide/level.py, for example, contains one Initialization entity and one Stage entity:

entities=[Initialization(), Stage()]

Later, the level will contain many Note entities. They will all run the behavior defined by the Note archetype, but each entity can carry different values, such as its beat.

Sonolus.py focuses on engine authoring rather than chart creation, but it supports defining levels for testing an engine.