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

sonolus/script/project.py

@@ -6,6 +6,14 @@ from sonolus.script.level import Level
 
 
 class Project:
+    """A Sonolus.py project.
+
+    Args:
+        engine: The engine of the project.
+        levels: The levels of the project.
+        resources: The path to the resources of the project.
+    """
+
     def __init__(
         self,
         engine: Engine,

sonolus/script/{graphics.py → quad.py}

@@ -7,16 +7,33 @@ from sonolus.script.vec import Vec2
 
 
 class Quad(Record):
+    """A quad defined by its four corners.
+
+    Usage:
+        ```
+        Quad(bl: Vec2, tl: Vec2, tr: Vec2, br: Vec2)
+        ```
+    """
+
     bl: Vec2
+    """The bottom-left corner of the quad."""
+
     tl: Vec2
+    """The top-left corner of the quad."""
+
     tr: Vec2
+    """The top-right corner of the quad."""
+
     br: Vec2
+    """The bottom-right corner of the quad."""
 
     @property
     def center(self) -> Vec2:
+        """The center of the quad."""
         return (self.bl + self.tr + self.tl + self.br) / 4
 
     def translate(self, translation: Vec2, /) -> Self:
+        """Translate the quad by the given translation and return a new quad."""
         return Quad(
             bl=self.bl + translation,
             tl=self.tl + translation,
@@ -25,6 +42,7 @@ class Quad(Record):
         )
 
     def scale(self, factor: Vec2, /) -> Self:
+        """Scale the quad by the given factor about the origin and return a new quad."""
         return Quad(
             bl=self.bl * factor,
             tl=self.tl * factor,
@@ -33,6 +51,7 @@ class Quad(Record):
         )
 
     def scale_about(self, factor: Vec2, /, pivot: Vec2) -> Self:
+        """Scale the quad by the given factor about the given pivot and return a new quad."""
         return Quad(
             bl=(self.bl - pivot) * factor + pivot,
             tl=(self.tl - pivot) * factor + pivot,
@@ -41,6 +60,7 @@ class Quad(Record):
         )
 
     def scale_centered(self, factor: Vec2, /) -> Self:
+        """Scale the quad by the given factor about its center and return a new quad."""
         return Quad(
             bl=self.bl * factor,
             tl=self.tl * factor,
@@ -49,6 +69,7 @@ class Quad(Record):
         ).translate(self.center * (Vec2(1, 1) - factor))
 
     def rotate(self, angle: float, /) -> Self:
+        """Rotate the quad by the given angle about the origin and return a new quad."""
         return Quad(
             bl=self.bl.rotate(angle),
             tl=self.tl.rotate(angle),
@@ -62,6 +83,7 @@ class Quad(Record):
         /,
         pivot: Vec2,
     ) -> Self:
+        """Rotate the quad by the given angle about the given pivot and return a new quad."""
         return Quad(
             bl=self.bl.rotate_about(angle, pivot),
             tl=self.tl.rotate_about(angle, pivot),
@@ -70,17 +92,34 @@ class Quad(Record):
         )
 
     def rotate_centered(self, angle: float, /) -> Self:
+        """Rotate the quad by the given angle about its center and return a new quad."""
         return self.rotate_about(angle, self.center)
 
 
 class Rect(Record):
+    """A rectangle defined by its top, right, bottom, and left edges.
+
+    Usage:
+        ```
+        Rect(t: float, r: float, b: float, l: float)
+        ```
+    """
+
     t: float
+    """The top edge of the rectangle."""
+
     r: float
+    """The right edge of the rectangle."""
+
     b: float
+    """The bottom edge of the rectangle."""
+
     l: float  # noqa: E741
+    """The left edge of the rectangle."""
 
     @classmethod
     def from_center(cls, center: Vec2, dimensions: Vec2) -> Rect:
+        """Create a rectangle from its center and dimensions."""
         return cls(
             t=center.y + dimensions.y / 2,
             r=center.x + dimensions.x / 2,
@@ -90,33 +129,41 @@ class Rect(Record):
 
     @property
     def w(self) -> float:
+        """The width of the rectangle."""
         return self.r - self.l
 
     @property
     def h(self) -> float:
+        """The height of the rectangle."""
         return self.t - self.b
 
     @property
     def bl(self) -> Vec2:
+        """The bottom-left corner of the rectangle."""
         return Vec2(self.l, self.b)
 
     @property
     def tl(self) -> Vec2:
+        """The top-left corner of the rectangle."""
         return Vec2(self.l, self.t)
 
     @property
     def tr(self) -> Vec2:
+        """The top-right corner of the rectangle."""
         return Vec2(self.r, self.t)
 
     @property
     def br(self) -> Vec2:
+        """The bottom-right corner of the rectangle."""
         return Vec2(self.r, self.b)
 
     @property
     def center(self) -> Vec2:
+        """The center of the rectangle."""
         return Vec2((self.l + self.r) / 2, (self.t + self.b) / 2)
 
     def as_quad(self) -> Quad:
+        """Convert the rectangle to a quad."""
         return Quad(
             bl=self.bl,
             tl=self.tl,
@@ -125,6 +172,7 @@ class Rect(Record):
         )
 
     def translate(self, translation: Vec2, /) -> Self:
+        """Translate the rectangle by the given translation and return a new rectangle."""
         return Rect(
             t=self.t + translation.y,
             r=self.r + translation.x,
@@ -133,6 +181,7 @@ class Rect(Record):
         )
 
     def scale(self, factor: Vec2, /) -> Self:
+        """Scale the rectangle by the given factor about the origin and return a new rectangle."""
         return Rect(
             t=self.t * factor.y,
             r=self.r * factor.x,
@@ -141,6 +190,7 @@ class Rect(Record):
         )
 
     def scale_about(self, factor: Vec2, /, pivot: Vec2) -> Self:
+        """Scale the rectangle by the given factor about the given pivot and return a new rectangle."""
         return Rect(
             t=(self.t - pivot.y) * factor.y + pivot.y,
             r=(self.r - pivot.x) * factor.x + pivot.x,
@@ -149,6 +199,7 @@ class Rect(Record):
         )
 
     def scale_centered(self, factor: Vec2, /) -> Self:
+        """Scale the rectangle by the given factor about its center and return a new rectangle."""
         return Rect(
             t=self.t * factor.y,
             r=self.r * factor.x,
@@ -157,6 +208,7 @@ class Rect(Record):
         ).translate(self.center * (Vec2(1, 1) - factor))
 
     def expand(self, expansion: Vec2, /) -> Self:
+        """Expand the rectangle by the given amount and return a new rectangle."""
         return Rect(
             t=self.t + expansion.y,
             r=self.r + expansion.x,
@@ -165,6 +217,7 @@ class Rect(Record):
         )
 
     def shrink(self, shrinkage: Vec2, /) -> Self:
+        """Shrink the rectangle by the given amount and return a new rectangle."""
         return Rect(
             t=self.t - shrinkage.y,
             r=self.r - shrinkage.x,
@@ -174,27 +227,37 @@ class Rect(Record):
 
 
 class QuadLike(Protocol):
+    """A protocol for types that can be used as quads."""
+
     @property
-    def bl(self) -> Vec2: ...
+    def bl(self) -> Vec2:
+        """The bottom-left corner of the quad."""
 
     @property
-    def tl(self) -> Vec2: ...
+    def tl(self) -> Vec2:
+        """The top-left corner of the quad."""
 
     @property
-    def tr(self) -> Vec2: ...
+    def tr(self) -> Vec2:
+        """The top-right corner of the quad."""
 
     @property
-    def br(self) -> Vec2: ...
+    def br(self) -> Vec2:
+        """The bottom-right corner of the quad."""
 
 
 def flatten_quad(quad: QuadLike) -> tuple[float, float, float, float, float, float, float, float]:
+    bl = quad.bl
+    tl = quad.tl
+    tr = quad.tr
+    br = quad.br
     return (
-        quad.bl.x,
-        quad.bl.y,
-        quad.tl.x,
-        quad.tl.y,
-        quad.tr.x,
-        quad.tr.y,
-        quad.br.x,
-        quad.br.y,
+        bl.x,
+        bl.y,
+        tl.x,
+        tl.y,
+        tr.x,
+        tr.y,
+        br.x,
+        br.y,
     )

sonolus/script/record.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import inspect
 from collections.abc import Iterable
 from inspect import getmro
-from typing import Any, ClassVar, Self, dataclass_transform, get_origin
+from typing import Any, ClassVar, Self, TypeVar, dataclass_transform, get_origin
 
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.context import ctx
@@ -22,15 +22,33 @@ from sonolus.script.num import Num
 
 @dataclass_transform(eq_default=True)
 class Record(GenericValue):
+    """Base class for user-defined data structures.
+
+    Usage:
+        A regular record:
+        ```python
+        class MyRecord(Record):
+            field1: int
+            field2: bool
+        ```
+
+        A generic record:
+        ```python
+        class MyGenericRecord[T, U](Record):
+            field1: T
+            field2: U
+        ```
+    """
+
     _value: dict[str, Value]
-    _fields: ClassVar[list[RecordField] | None] = None
+    _fields: ClassVar[list[_RecordField] | None] = None
     _constructor_signature: ClassVar[inspect.Signature]
 
     @classmethod
-    def _validate__type_args_(cls, args: tuple[Any, ...]) -> tuple[Any, ...]:
+    def _validate_type_args_(cls, args: tuple[Any, ...]) -> tuple[Any, ...]:
         if cls._fields is None:
             raise TypeError("Base Record class cannot have type arguments")
-        return super()._validate__type_args_(args)
+        return super()._validate_type_args_(args)
 
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__()
@@ -43,7 +61,7 @@ class Record(GenericValue):
             for generic_field in cls._fields:
                 resolved_type = validate_and_resolve_type(generic_field.type, cls._type_vars_to_args_)
                 resolved_type = validate_concrete_type(resolved_type)
-                field = RecordField(generic_field.name, resolved_type, generic_field.index, offset)
+                field = _RecordField(generic_field.name, resolved_type, generic_field.index, offset)
                 fields.append(field)
                 setattr(cls, field.name, field)
                 offset += resolved_type._size_()
@@ -70,7 +88,7 @@ class Record(GenericValue):
             if hasattr(cls, name):
                 raise TypeError("Default values are not supported for Record fields")
             type_ = validate_type_spec(hint)
-            fields.append(RecordField(name, type_, index, offset))
+            fields.append(_RecordField(name, type_, index, offset))
             if isinstance(type_, type) and issubclass(type_, Value) and type_._is_concrete_():
                 offset += type_._size_()
             setattr(cls, name, fields[-1])
@@ -194,7 +212,7 @@ class Record(GenericValue):
             field.__set__(self, field.__get__(value))
 
     def _copy_(self) -> Self:
-        return type(self)(**{field.name: self._value[field.name]._copy_() for field in self._fields})
+        return type(self)._raw(**{field.name: self._value[field.name]._copy_() for field in self._fields})
 
     @classmethod
     def _alloc_(cls) -> Self:
@@ -214,7 +232,7 @@ class Record(GenericValue):
         )
 
     @meta_fn
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         if not isinstance(other, type(self)):
             return False
         result: Num = Num._accept_(True)
@@ -223,7 +241,7 @@ class Record(GenericValue):
         return result
 
     @meta_fn
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         if not isinstance(other, type(self)):
             return True
         result: Num = Num._accept_(False)
@@ -232,10 +250,23 @@ class Record(GenericValue):
         return result
 
     def __hash__(self):
-        raise TypeError("Record is not hashable")
+        return hash(tuple(field.__get__(self) for field in self._fields))
+
+    @classmethod
+    @meta_fn
+    def type_var_value(cls, var: TypeVar, /) -> Any:
+        """Return the value of a type variable.
+
+        Args:
+            var: The type variable to get the value of.
+
+        Returns:
+            The value of the type variable.
+        """
+        return super().type_var_value(var)
 
 
-class RecordField(SonolusDescriptor):
+class _RecordField(SonolusDescriptor):
     def __init__(self, name: str, type_: type[Value], index: int, offset: int):
         self.name = name
         self.type = type_
@@ -259,7 +290,7 @@ class RecordField(SonolusDescriptor):
             instance._value[self.name]._copy_from_(value)
 
 
-ops_to_inplace_ops = {
+_ops_to_inplace_ops = {
     "__add__": "__iadd__",
     "__sub__": "__isub__",
     "__mul__": "__imul__",
@@ -277,7 +308,7 @@ ops_to_inplace_ops = {
 
 
 def _add_inplace_ops(cls):
-    for op, inplace_op in ops_to_inplace_ops.items():
+    for op, inplace_op in _ops_to_inplace_ops.items():
         if hasattr(cls, op) and not hasattr(cls, inplace_op):
             setattr(cls, inplace_op, _make_inplace_op(op))
     return cls

sonolus/script/runtime.py

@@ -28,10 +28,10 @@ from sonolus.script.globals import (
     _watch_runtime_ui_configuration,
     _watch_runtime_update,
 )
-from sonolus.script.graphics import Quad, Rect
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn
 from sonolus.script.num import Num
+from sonolus.script.quad import Quad, Rect
 from sonolus.script.record import Record
 from sonolus.script.transform import Transform2d
 from sonolus.script.vec import Vec2
@@ -433,6 +433,7 @@ class _TutorialInstruction:
 
 @meta_fn
 def is_debug() -> bool:
+    """Check if the game is running in debug mode."""
     if not ctx():
         return False
     match ctx().global_state.mode:
@@ -450,6 +451,7 @@ def is_debug() -> bool:
 
 @meta_fn
 def aspect_ratio() -> float:
+    """Get the aspect ratio of the game."""
     if not ctx():
         return 16 / 9
     match ctx().global_state.mode:
@@ -465,6 +467,10 @@ def aspect_ratio() -> float:
 
 @meta_fn
 def audio_offset() -> float:
+    """Get the audio offset of the game.
+
+    Returns 0 in preview mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -480,6 +486,10 @@ def audio_offset() -> float:
 
 @meta_fn
 def input_offset() -> float:
+    """Get the input offset of the game.
+
+    Returns 0 in preview mode and tutorial mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -493,6 +503,10 @@ def input_offset() -> float:
 
 @meta_fn
 def is_multiplayer() -> bool:
+    """Check if the game is running in multiplayer mode.
+
+    Returns False if not in play mode.
+    """
     if not ctx():
         return False
     match ctx().global_state.mode:
@@ -504,6 +518,10 @@ def is_multiplayer() -> bool:
 
 @meta_fn
 def is_replay() -> bool:
+    """Check if the game is running in replay mode.
+
+    Returns False if not in watch mode.
+    """
     if not ctx():
         return False
     match ctx().global_state.mode:
@@ -515,6 +533,10 @@ def is_replay() -> bool:
 
 @meta_fn
 def time() -> float:
+    """Get the current time of the game.
+
+    Returns 0 in preview mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -530,6 +552,10 @@ def time() -> float:
 
 @meta_fn
 def delta_time() -> float:
+    """Get the time elapsed since the last frame.
+
+    Returns 0 in preview mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -545,6 +571,10 @@ def delta_time() -> float:
 
 @meta_fn
 def scaled_time() -> float:
+    """Get the current time of the game affected by the time scale.
+
+    Returns the unscaled time in tutorial mode and 0 in preview mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -560,6 +590,7 @@ def scaled_time() -> float:
 
 @meta_fn
 def touches() -> VarArray[Touch, 999]:
+    """Get the current touches of the game."""
     if not ctx():
         return VarArray(0, Array[Touch, 0]())
     match ctx().global_state.mode:
@@ -571,6 +602,10 @@ def touches() -> VarArray[Touch, 999]:
 
 @meta_fn
 def is_skip() -> bool:
+    """Check if there was a time skip this frame.
+
+    Returns False if not in watch mode.
+    """
     if not ctx():
         return False
     match ctx().global_state.mode:
@@ -582,6 +617,10 @@ def is_skip() -> bool:
 
 @meta_fn
 def navigation_direction() -> int:
+    """Get the navigation direction of the tutorial.
+
+    Returns 0 if not in tutorial mode.
+    """
     if not ctx():
         return 0
     match ctx().global_state.mode:
@@ -592,28 +631,34 @@ def navigation_direction() -> int:
 
 
 def skin_transform() -> Transform2d:
+    """Get the global skin transform."""
     return _SkinTransform.transform
 
 
 @meta_fn
 def set_skin_transform(value: Transform2d):
+    """Set the global skin transform."""
     _SkinTransform.transform._copy_from_(value)
 
 
 def particle_transform() -> Transform2d:
+    """Get the global particle transform."""
     return _ParticleTransform.transform
 
 
 @meta_fn
 def set_particle_transform(value: Transform2d):
+    """Set the global particle transform."""
     _ParticleTransform.transform._copy_from_(value)
 
 
 def background() -> Quad:
+    """Get the background quad."""
     return _Background.value
 
 
 def set_background(value: Quad):
+    """Set the background quad."""
     _Background.value = value
 
 
@@ -628,16 +673,20 @@ tutorial_ui_configs = _TutorialRuntimeUiConfigs
 
 
 def canvas() -> _PreviewRuntimeCanvas:
+    """Get the preview canvas."""
     return _PreviewRuntimeCanvas
 
 
 def screen() -> Rect:
+    """Get the screen boundaries as a rectangle."""
     return Rect(t=1, r=aspect_ratio(), b=-1, l=-aspect_ratio())
 
 
 def level_score() -> _LevelScore:
+    """Get the level score configuration."""
     return _LevelScore
 
 
 def level_life() -> _LevelLife:
+    """Get the level life configuration."""
     return _LevelLife