sonolus.py 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

sonolus/script/easing.py

@@ -1,3 +1,4 @@
+# ruff: noqa: E501
 import math
 
 from sonolus.backend.ops import Op
@@ -7,6 +8,7 @@ from sonolus.script.interval import clamp
 
 @native_function(Op.EaseInBack)
 def ease_in_back(x: float) -> float:
+    """Interpolate between 0 and 1, starting slow and ending fast, overshooting below 0 at the start."""
     x = clamp(x, 0, 1)
     c1 = 1.70158
     c3 = c1 + 1
@@ -15,6 +17,7 @@ def ease_in_back(x: float) -> float:
 
 @native_function(Op.EaseOutBack)
 def ease_out_back(x: float) -> float:
+    """Interpolate between 0 and 1, starting fast and ending slow, overshooting above 1 at the end."""
     x = clamp(x, 0, 1)
     c1 = 1.70158
     c3 = c1 + 1
@@ -23,6 +26,7 @@ def ease_out_back(x: float) -> float:
 
 @native_function(Op.EaseInOutBack)
 def ease_in_out_back(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending slow with overshooting, fast in the middle."""
     x = clamp(x, 0, 1)
     c1 = 1.70158
     c2 = c1 * 1.525
@@ -32,20 +36,35 @@ def ease_in_out_back(x: float) -> float:
         return ((2 * x - 2) ** 2 * ((c2 + 1) * (2 * x - 2) + c2) + 2) / 2
 
 
+@native_function(Op.EaseOutInBack)
+def ease_out_in_back(x: float) -> float:
+    """Interpolate between 0 and 1, fast at the start and end, slow in the middle with overshooting."""
+    x = clamp(x, 0, 1)
+    c1 = 1.70158
+    c3 = c1 + 1
+    if x < 0.5:
+        return (1 + c3 * (2 * x - 1) ** 3 + c1 * (2 * x - 1) ** 2) / 2
+    else:
+        return (c3 * (2 * x - 1) ** 3 - c1 * (2 * x - 1) ** 2) / 2 + 0.5
+
+
 @native_function(Op.EaseInCirc)
 def ease_in_circ(x: float) -> float:
+    """Interpolate between 0 and 1, starting slow and ending very fast."""
     x = clamp(x, 0, 1)
     return 1 - math.sqrt(1 - x**2)
 
 
 @native_function(Op.EaseOutCirc)
 def ease_out_circ(x: float) -> float:
+    """Interpolate between 0 and 1, starting very fast and ending slow."""
     x = clamp(x, 0, 1)
     return math.sqrt(1 - (x - 1) ** 2)
 
 
 @native_function(Op.EaseInOutCirc)
 def ease_in_out_circ(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending slow, very fast in the middle."""
     x = clamp(x, 0, 1)
     if x < 0.5:
         return (1 - math.sqrt(1 - (2 * x) ** 2)) / 2
@@ -53,20 +72,33 @@ def ease_in_out_circ(x: float) -> float:
         return (math.sqrt(1 - (2 * x - 2) ** 2) + 1) / 2
 
 
+@native_function(Op.EaseOutInCirc)
+def ease_out_in_circ(x: float) -> float:
+    """Interpolate between 0 and 1, very fast at the start and end, slow in the middle."""
+    x = clamp(x, 0, 1)
+    if x < 0.5:
+        return math.sqrt(1 - (2 * x - 1) ** 2) / 2
+    else:
+        return (1 - math.sqrt(1 - (2 * x - 1) ** 2)) / 2 + 0.5
+
+
 @native_function(Op.EaseInCubic)
 def ease_in_cubic(x: float) -> float:
+    """Interpolate between 0 and 1, starting slow and ending fast with cubic easing."""
     x = clamp(x, 0, 1)
     return x**3
 
 
 @native_function(Op.EaseOutCubic)
 def ease_out_cubic(x: float) -> float:
+    """Interpolate between 0 and 1, starting fast and ending slow with cubic easing."""
     x = clamp(x, 0, 1)
     return 1 - (1 - x) ** 3
 
 
 @native_function(Op.EaseInOutCubic)
 def ease_in_out_cubic(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending slow with cubic easing, fast in the middle."""
     x = clamp(x, 0, 1)
     if x < 0.5:
         return 4 * x**3
@@ -74,8 +106,19 @@ def ease_in_out_cubic(x: float) -> float:
         return 1 - (-2 * x + 2) ** 3 / 2
 
 
+@native_function(Op.EaseOutInCubic)
+def ease_out_in_cubic(x: float) -> float:
+    """Interpolate between 0 and 1, fast at the start and end, slow in the middle with cubic easing."""
+    x = clamp(x, 0, 1)
+    if x < 0.5:
+        return (1 - (1 - 2 * x) ** 3) / 2
+    else:
+        return ((2 * x - 1) ** 3) / 2 + 0.5
+
+
 @native_function(Op.EaseInElastic)
 def ease_in_elastic(x: float) -> float:
+    """Interpolate between 0 and 1 with oscillations, starting slow and ending fast."""
     x = clamp(x, 0, 1)
     c4 = (2 * math.pi) / 3
     if x in {0, 1}:
@@ -86,6 +129,7 @@ def ease_in_elastic(x: float) -> float:
 
 @native_function(Op.EaseOutElastic)
 def ease_out_elastic(x: float) -> float:
+    """Interpolate between 0 and 1 with oscillations, starting fast and ending slow."""
     x = clamp(x, 0, 1)
     c4 = (2 * math.pi) / 3
     if x in {0, 1}:
@@ -96,6 +140,7 @@ def ease_out_elastic(x: float) -> float:
 
 @native_function(Op.EaseInOutElastic)
 def ease_in_out_elastic(x: float) -> float:
+    """Interpolate between 0 and 1 with oscillations, slow at the start and end, fast in the middle."""
     x = clamp(x, 0, 1)
     c5 = (2 * math.pi) / 4.5
     if x in {0, 1}:
@@ -106,20 +151,39 @@ def ease_in_out_elastic(x: float) -> float:
         return (2 ** (-20 * x + 10) * math.sin((20 * x - 11.125) * c5)) / 2 + 1
 
 
+@native_function(Op.EaseOutInElastic)
+def ease_out_in_elastic(x: float) -> float:
+    """Interpolate between 0 and 1 with oscillations, fast at the start and end, slow in the middle."""
+    x = clamp(x, 0, 1)
+    c4 = (2 * math.pi) / 3
+    if x < 0.5:
+        if x == 0:
+            return 0
+        else:
+            return (2 ** (-20 * x + 10) * math.sin((20 * x - 0.75) * c4)) / 2 + 0.5
+    elif x == 1:
+        return 1
+    else:
+        return (-(2 ** (10 * (2 * x - 1) - 10)) * math.sin((20 * x - 10.75) * c4)) / 2 + 0.5
+
+
 @native_function(Op.EaseInExpo)
 def ease_in_expo(x: float) -> float:
+    """Interpolate between 0 and 1, starting extremely slow and ending extremely fast."""
     x = clamp(x, 0, 1)
     return 0 if x == 0 else 2 ** (10 * x - 10)
 
 
 @native_function(Op.EaseOutExpo)
 def ease_out_expo(x: float) -> float:
+    """Interpolate between 0 and 1, starting extremely fast and ending extremely slow."""
     x = clamp(x, 0, 1)
     return 1 if x == 1 else 1 - 2 ** (-10 * x)
 
 
 @native_function(Op.EaseInOutExpo)
 def ease_in_out_expo(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending extremely slow, fast in the middle."""
     x = clamp(x, 0, 1)
     if x in {0, 1}:
         return x
@@ -129,195 +193,173 @@ def ease_in_out_expo(x: float) -> float:
         return (2 - 2 ** (-20 * x + 10)) / 2
 
 
-@native_function(Op.EaseInOutQuad)
-def ease_in_out_quad(x: float) -> float:
-    x = clamp(x, 0, 1)
-    if x < 0.5:
-        return 2 * x**2
-    else:
-        return 1 - (-2 * x + 2) ** 2 / 2
-
-
-@native_function(Op.EaseInOutQuart)
-def ease_in_out_quart(x: float) -> float:
-    x = clamp(x, 0, 1)
-    if x < 0.5:
-        return 8 * x**4
-    else:
-        return 1 - (-2 * x + 2) ** 4 / 2
-
-
-@native_function(Op.EaseInOutQuint)
-def ease_in_out_quint(x: float) -> float:
+@native_function(Op.EaseOutInExpo)
+def ease_out_in_expo(x: float) -> float:
+    """Interpolate between 0 and 1, extremely fast at the start and end, extremely slow in the middle."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return 16 * x**5
+    if x in {0, 1}:
+        return x
+    elif x < 0.5:
+        return (1 - 2 ** (-20 * x)) / 2
     else:
-        return 1 - (-2 * x + 2) ** 5 / 2
-
-
-@native_function(Op.EaseInOutSine)
-def ease_in_out_sine(x: float) -> float:
-    x = clamp(x, 0, 1)
-    return -(math.cos(math.pi * x) - 1) / 2
+        return (2 ** (20 * x - 20)) / 2 + 0.5
 
 
 @native_function(Op.EaseInQuad)
 def ease_in_quad(x: float) -> float:
+    """Interpolate between 0 and 1, starting slow and ending fast with quadratic easing."""
     x = clamp(x, 0, 1)
     return x**2
 
 
 @native_function(Op.EaseOutQuad)
 def ease_out_quad(x: float) -> float:
+    """Interpolate between 0 and 1, starting fast and ending slow with quadratic easing."""
     x = clamp(x, 0, 1)
     return 1 - (1 - x) ** 2
 
 
-@native_function(Op.EaseInQuart)
-def ease_in_quart(x: float) -> float:
-    x = clamp(x, 0, 1)
-    return x**4
-
-
-@native_function(Op.EaseOutQuart)
-def ease_out_quart(x: float) -> float:
+@native_function(Op.EaseInOutQuad)
+def ease_in_out_quad(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending slow with quadratic easing, fast in the middle."""
     x = clamp(x, 0, 1)
-    return 1 - (1 - x) ** 4
+    if x < 0.5:
+        return 2 * x**2
+    else:
+        return 1 - (-2 * x + 2) ** 2 / 2
 
 
-@native_function(Op.EaseInQuint)
-def ease_in_quint(x: float) -> float:
+@native_function(Op.EaseOutInQuad)
+def ease_out_in_quad(x: float) -> float:
+    """Interpolate between 0 and 1, fast at the start and end, slow in the middle with quadratic easing."""
     x = clamp(x, 0, 1)
-    return x**5
+    if x < 0.5:
+        return (1 - (1 - 2 * x) ** 2) / 2
+    else:
+        return ((2 * x - 1) ** 2) / 2 + 0.5
 
 
-@native_function(Op.EaseOutQuint)
-def ease_out_quint(x: float) -> float:
+@native_function(Op.EaseInQuart)
+def ease_in_quart(x: float) -> float:
+    """Interpolate between 0 and 1, starting very slow and ending very fast with quartic easing."""
     x = clamp(x, 0, 1)
-    return 1 - (1 - x) ** 5
+    return x**4
 
 
-@native_function(Op.EaseInSine)
-def ease_in_sine(x: float) -> float:
+@native_function(Op.EaseOutQuart)
+def ease_out_quart(x: float) -> float:
+    """Interpolate between 0 and 1, starting very fast and ending very slow with quartic easing."""
     x = clamp(x, 0, 1)
-    return 1 - math.cos((x * math.pi) / 2)
+    return 1 - (1 - x) ** 4
 
 
-@native_function(Op.EaseOutSine)
-def ease_out_sine(x: float) -> float:
+@native_function(Op.EaseInOutQuart)
+def ease_in_out_quart(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending very slow with quartic easing, very fast in the middle."""
     x = clamp(x, 0, 1)
-    return math.sin((x * math.pi) / 2)
+    if x < 0.5:
+        return 8 * x**4
+    else:
+        return 1 - (-2 * x + 2) ** 4 / 2
 
 
-@native_function(Op.EaseOutInBack)
-def ease_out_in_back(x: float) -> float:
+@native_function(Op.EaseOutInQuart)
+def ease_out_in_quart(x: float) -> float:
+    """Interpolate between 0 and 1, very fast at the start and end, very slow in the middle with quartic easing."""
     x = clamp(x, 0, 1)
-    c1 = 1.70158
-    c3 = c1 + 1
     if x < 0.5:
-        return (1 + c3 * (2 * x - 1) ** 3 + c1 * (2 * x - 1) ** 2) / 2
+        return (1 - (1 - 2 * x) ** 4) / 2
     else:
-        return (c3 * (2 * x - 1) ** 3 - c1 * (2 * x - 1) ** 2) / 2 + 0.5
+        return ((2 * x - 1) ** 4) / 2 + 0.5
 
 
-@native_function(Op.EaseOutInCirc)
-def ease_out_in_circ(x: float) -> float:
+@native_function(Op.EaseInQuint)
+def ease_in_quint(x: float) -> float:
+    """Interpolate between 0 and 1, starting extremely slow and ending extremely fast with quintic easing."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return (math.sqrt(1 - (2 * x - 1) ** 2)) / 2
-    else:
-        return (1 - math.sqrt(1 - (2 * x - 1) ** 2)) / 2 + 0.5
+    return x**5
 
 
-@native_function(Op.EaseOutInCubic)
-def ease_out_in_cubic(x: float) -> float:
+@native_function(Op.EaseOutQuint)
+def ease_out_quint(x: float) -> float:
+    """Interpolate between 0 and 1, starting extremely fast and ending extremely slow with quintic easing."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return (1 - (1 - 2 * x) ** 3) / 2
-    else:
-        return ((2 * x - 1) ** 3) / 2 + 0.5
+    return 1 - (1 - x) ** 5
 
 
-@native_function(Op.EaseOutInElastic)
-def ease_out_in_elastic(x: float) -> float:
+@native_function(Op.EaseInOutQuint)
+def ease_in_out_quint(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending extremely slow with quintic easing, extremely fast in the middle."""
     x = clamp(x, 0, 1)
-    c4 = (2 * math.pi) / 3
     if x < 0.5:
-        if x == 0:
-            return 0
-        else:
-            return (2 ** (-20 * x + 10) * math.sin((20 * x - 0.75) * c4)) / 2 + 0.5
-    elif x == 1:
-        return 1
+        return 16 * x**5
     else:
-        return (-(2 ** (10 * (2 * x - 1) - 10)) * math.sin((20 * x - 10.75) * c4)) / 2 + 0.5
+        return 1 - (-2 * x + 2) ** 5 / 2
 
 
-@native_function(Op.EaseOutInExpo)
-def ease_out_in_expo(x: float) -> float:
+@native_function(Op.EaseOutInQuint)
+def ease_out_in_quint(x: float) -> float:
+    """Interpolate between 0 and 1, extremely fast at the start and end, extremely slow in the middle with quintic easing."""
     x = clamp(x, 0, 1)
-    if x in {0, 1}:
-        return x
-    elif x < 0.5:
-        return (1 - 2 ** (-20 * x)) / 2
+    if x < 0.5:
+        return (1 - (1 - 2 * x) ** 5) / 2
     else:
-        return (2 ** (20 * x - 20)) / 2 + 0.5
+        return ((2 * x - 1) ** 5) / 2 + 0.5
 
 
-@native_function(Op.EaseOutInQuad)
-def ease_out_in_quad(x: float) -> float:
+@native_function(Op.EaseInSine)
+def ease_in_sine(x: float) -> float:
+    """Interpolate between 0 and 1, starting slow and ending fast with sine easing."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return (1 - (1 - 2 * x) ** 2) / 2
-    else:
-        return ((2 * x - 1) ** 2) / 2 + 0.5
+    return 1 - math.cos((x * math.pi) / 2)
 
 
-@native_function(Op.EaseOutInQuart)
-def ease_out_in_quart(x: float) -> float:
+@native_function(Op.EaseOutSine)
+def ease_out_sine(x: float) -> float:
+    """Interpolate between 0 and 1, starting fast and ending slow with sine easing."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return (1 - (1 - 2 * x) ** 4) / 2
-    else:
-        return ((2 * x - 1) ** 4) / 2 + 0.5
+    return math.sin((x * math.pi) / 2)
 
 
-@native_function(Op.EaseOutInQuint)
-def ease_out_in_quint(x: float) -> float:
+@native_function(Op.EaseInOutSine)
+def ease_in_out_sine(x: float) -> float:
+    """Interpolate between 0 and 1, starting and ending slow with sine easing, fast in the middle."""
     x = clamp(x, 0, 1)
-    if x < 0.5:
-        return (1 - (1 - 2 * x) ** 5) / 2
-    else:
-        return ((2 * x - 1) ** 5) / 2 + 0.5
+    return -(math.cos(math.pi * x) - 1) / 2
 
 
 @native_function(Op.EaseOutInSine)
 def ease_out_in_sine(x: float) -> float:
+    """Interpolate between 0 and 1, fast at the start and end, slow in the middle with sine easing."""
     x = clamp(x, 0, 1)
     if x < 0.5:
-        return (math.sin(math.pi * x)) / 2
+        return math.sin(math.pi * x) / 2
     else:
         return (1 - math.cos(math.pi * x)) / 2
 
 
 def linstep(x: float) -> float:
+    """Linear interpolation between 0 and 1."""
     return clamp(x, 0.0, 1.0)
 
 
 def smoothstep(x: float) -> float:
+    """Interpolate between 0 and 1 using smoothstep."""
     x = clamp(x, 0.0, 1.0)
     return x * x * (3 - 2 * x)
 
 
 def smootherstep(x: float) -> float:
+    """Interpolate between 0 and 1 using smootherstep."""
     x = clamp(x, 0.0, 1.0)
     return x * x * x * (x * (x * 6 - 15) + 10)
 
 
 def step_start(x: float) -> float:
-    return 1.0 if x >= 0 else 0.0
+    """Step function returning 1.0 if x > 0, otherwise 0.0."""
+    return 1.0 if x > 0 else 0.0
 
 
 def step_end(x: float) -> float:
+    """Step function returning 1.0 if x >= 1, otherwise 0.0."""
     return 1.0 if x >= 1 else 0.0

sonolus/script/effect.py

@@ -10,35 +10,82 @@ from sonolus.script.record import Record
 
 
 class Effect(Record):
+    """Sound effect clip.
+
+    Usage:
+        ```python
+        Effect(id: int)
+        ```
+    """
+
     id: int
+    """Effect ID."""
 
     def is_available(self) -> bool:
+        """Return whether the effect clip is available."""
         return _has_effect_clip(self.id)
 
     def play(self, distance: float) -> None:
+        """Play the effect clip.
+
+        If the clip was already played within the specified distance, it will be skipped.
+
+        Arguments:
+            distance: Minimum time in seconds since the last play for the effect to play.
+        """
         _play(self.id, distance)
 
     def schedule(self, time: float, distance: float) -> 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.
+
+        If the clip would play within the specified distance of another play, it will be skipped.
+
+        Arguments:
+            time: Time in seconds when the effect should play.
+            distance: Minimum time in seconds after a previous play for the effect to play.
+        """
         _play_scheduled(self.id, time, distance)
 
     def loop(self) -> LoopedEffectHandle:
+        """Play the effect clip in a loop until stopped.
+
+        Returns:
+            A handle to stop the loop.
+        """
         return LoopedEffectHandle(_play_looped(self.id))
 
     def schedule_loop(self, 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.
+
+        Returns:
+            A handle to stop the loop.
+        """
         return ScheduledLoopedEffectHandle(_play_looped_scheduled(self.id, start_time))
 
 
 class LoopedEffectHandle(Record):
+    """Handle to stop a looped effect."""
+
     id: int
 
     def stop(self) -> None:
+        """Stop the looped effect."""
         _stop_looped(self.id)
 
 
 class ScheduledLoopedEffectHandle(Record):
+    """Handle to stop a scheduled looped effect."""
+
     id: int
 
     def stop(self, end_time: float) -> None:
+        """Stop the scheduled looped effect."""
         _stop_looped_scheduled(self.id, end_time)
 
 
@@ -83,6 +130,7 @@ class EffectInfo:
 
 
 def effect(name: str) -> Any:
+    """Define a sound effect clip with the given name."""
     return EffectInfo(name)
 
 
@@ -91,6 +139,16 @@ type Effects = NewType("Effects", Any)
 
 @dataclass_transform()
 def effects[T](cls: type[T]) -> T | Effects:
+    """Decorator to define effect clips.
+
+    Usage:
+        ```python
+        @effects
+        class Effects:
+            miss: StandardEffect.MISS
+            other: Effect = effect("other")
+        ```
+    """
     if len(cls.__bases__) != 1:
         raise ValueError("Effects class must not inherit from any class (except object)")
     instance = cls()
@@ -113,6 +171,8 @@ def effects[T](cls: type[T]) -> T | Effects:
 
 
 class StandardEffect:
+    """Standard sound effect clips."""
+
     MISS = Annotated[Effect, effect("#MISS")]
     PERFECT = Annotated[Effect, effect("#PERFECT")]
     GREAT = Annotated[Effect, effect("#GREAT")]

sonolus/script/engine.py

@@ -4,7 +4,7 @@ from collections.abc import Callable
 from typing import Any
 
 from sonolus.build.collection import Asset
-from sonolus.script.archetype import BaseArchetype, PlayArchetype, PreviewArchetype, WatchArchetype
+from sonolus.script.archetype import PlayArchetype, PreviewArchetype, WatchArchetype, _BaseArchetype
 from sonolus.script.bucket import Buckets, EmptyBuckets
 from sonolus.script.effect import Effects, EmptyEffects
 from sonolus.script.instruction import (
@@ -20,6 +20,21 @@ from sonolus.script.ui import UiConfig
 
 
 class Engine:
+    """A Sonolus.py engine.
+
+    Args:
+        name: The name of the engine.
+        title: The title of the engine.
+        subtitle: The subtitle of the engine.
+        author: The author of the engine.
+        skin: The default skin for the engine.
+        background: The default background for the engine.
+        effect: The default effect for the engine.
+        particle: The default particle for the engine.
+        thumbnail: The thumbnail for the engine.
+        data: The engine's modes and configurations.
+    """
+
     version = 12
 
     def __init__(
@@ -53,10 +68,20 @@ def default_callback() -> Any:
 
 
 class PlayMode:
+    """A play mode definition.
+
+    Args:
+        archetypes: A list of play archetypes.
+        skin: The skin for the play mode.
+        effects: The effects for the play mode.
+        particles: The particles for the play mode.
+        buckets: The buckets for the play mode.
+    """
+
     def __init__(
         self,
         *,
-        archetypes: list[type[BaseArchetype]] | None = None,
+        archetypes: list[type[_BaseArchetype]] | None = None,
         skin: Skin = EmptySkin,
         effects: Effects = EmptyEffects,
         particles: Particles = EmptyParticles,
@@ -74,10 +99,21 @@ class PlayMode:
 
 
 class WatchMode:
+    """A watch mode definition.
+
+    Args:
+        archetypes: A list of watch archetypes.
+        skin: The skin for the watch mode.
+        effects: The effects for the watch mode.
+        particles: The particles for the watch mode.
+        buckets: The buckets for the watch mode.
+        update_spawn: A callback returning the spawn time used by archetypes.
+    """
+
     def __init__(
         self,
         *,
-        archetypes: list[type[BaseArchetype]] | None = None,
+        archetypes: list[type[_BaseArchetype]] | None = None,
         skin: Skin = EmptySkin,
         effects: Effects = EmptyEffects,
         particles: Particles = EmptyParticles,
@@ -97,10 +133,17 @@ class WatchMode:
 
 
 class PreviewMode:
+    """A preview mode definition.
+
+    Args:
+        archetypes: A list of preview archetypes.
+        skin: The skin for the preview mode.
+    """
+
     def __init__(
         self,
         *,
-        archetypes: list[type[BaseArchetype]] | None = None,
+        archetypes: list[type[_BaseArchetype]] | None = None,
         skin: Skin = EmptySkin,
     ) -> None:
         self.archetypes = archetypes or []
@@ -112,6 +155,19 @@ class PreviewMode:
 
 
 class TutorialMode:
+    """A tutorial mode definition.
+
+    Args:
+        skin: The skin for the tutorial mode.
+        effects: The effects for the tutorial mode.
+        particles: The particles for the tutorial mode.
+        instructions: The instructions for the tutorial mode.
+        instruction_icons: The instruction icons for the tutorial mode.
+        preprocess: A callback to be called before the tutorial starts.
+        navigate: A callback to be called when the user navigates.
+        update: A callback to be called each frame.
+    """
+
     def __init__(
         self,
         *,
@@ -135,6 +191,17 @@ class TutorialMode:
 
 
 class EngineData:
+    """A Sonolus.py engine's modes and configurations.
+
+    Args:
+        ui: The UI configuration.
+        options: The options for the engine.
+        play: The play mode configuration.
+        watch: The watch mode configuration.
+        preview: The preview mode configuration.
+        tutorial: The tutorial mode configuration.
+    """
+
     def __init__(
         self,
         *,