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

sonolus/script/quad.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from typing import Protocol, Self
+
+from sonolus.script.record import Record
+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,
+            tr=self.tr + translation,
+            br=self.br + translation,
+        )
+
+    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,
+            tr=self.tr * factor,
+            br=self.br * factor,
+        )
+
+    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,
+            tr=(self.tr - pivot) * factor + pivot,
+            br=(self.br - pivot) * factor + pivot,
+        )
+
+    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,
+            tr=self.tr * factor,
+            br=self.br * factor,
+        ).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),
+            tr=self.tr.rotate(angle),
+            br=self.br.rotate(angle),
+        )
+
+    def rotate_about(
+        self,
+        angle: float,
+        /,
+        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),
+            tr=self.tr.rotate_about(angle, pivot),
+            br=self.br.rotate_about(angle, pivot),
+        )
+
+    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,
+            b=center.y - dimensions.y / 2,
+            l=center.x - dimensions.x / 2,
+        )
+
+    @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,
+            tr=self.tr,
+            br=self.br,
+        )
+
+    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,
+            b=self.b + translation.y,
+            l=self.l + translation.x,
+        )
+
+    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,
+            b=self.b * factor.y,
+            l=self.l * factor.x,
+        )
+
+    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,
+            b=(self.b - pivot.y) * factor.y + pivot.y,
+            l=(self.l - pivot.x) * factor.x + pivot.x,
+        )
+
+    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,
+            b=self.b * factor.y,
+            l=self.l * factor.x,
+        ).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,
+            b=self.b - expansion.y,
+            l=self.l - expansion.x,
+        )
+
+    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,
+            b=self.b + shrinkage.y,
+            l=self.l + shrinkage.x,
+        )
+
+
+class QuadLike(Protocol):
+    """A protocol for types that can be used as quads."""
+
+    @property
+    def bl(self) -> Vec2:
+        """The bottom-left corner of the quad."""
+
+    @property
+    def tl(self) -> Vec2:
+        """The top-left corner of the quad."""
+
+    @property
+    def tr(self) -> Vec2:
+        """The top-right corner of the quad."""
+
+    @property
+    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 (
+        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])
@@ -111,7 +129,7 @@ class Record(GenericValue):
             values[field.name] = value._get_()
         for type_param in cls.__type_params__:
             if type_param not in type_vars:
-                raise TypeError(f"Type parameter {type_param} is not used")
+                raise TypeError(f"Type parameter {type_param} cannot be inferred and must be provided explicitly")
         type_args = tuple(type_vars[type_param] for type_param in cls.__type_params__)
         if cls._type_args_ is not None:
             parameterized = cls
@@ -168,10 +186,10 @@ class Record(GenericValue):
         iterator = iter(values)
         return cls(**{field.name: field.type._from_list_(iterator) for field in cls._fields})
 
-    def _to_list_(self) -> list[float | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, int] | None = None) -> list[float | BlockPlace]:
         result = []
         for field in self._fields:
-            result.extend(self._value[field.name]._to_list_())
+            result.extend(self._value[field.name]._to_list_(level_refs))
         return result
 
     @classmethod
@@ -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
@@ -308,6 +308,7 @@ class _SkinTransform:
             a12=Num(values[1 * 4 + 3]),
             a20=Num(values[3 * 4 + 0]),
             a21=Num(values[3 * 4 + 1]),
+            a22=Num(values[3 * 4 + 3]),
         )
 
 
@@ -328,6 +329,7 @@ class _ParticleTransform:
             a12=Num(values[1 * 4 + 3]),
             a20=Num(values[3 * 4 + 0]),
             a21=Num(values[3 * 4 + 1]),
+            a22=Num(values[3 * 4 + 3]),
         )
 
 
@@ -431,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:
@@ -448,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:
@@ -463,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:
@@ -478,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:
@@ -491,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:
@@ -502,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:
@@ -513,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:
@@ -528,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:
@@ -543,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:
@@ -558,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:
@@ -569,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:
@@ -580,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:
@@ -590,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
 
 
@@ -626,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