sonolus.py 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

sonolus/script/internal/impl.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from enum import Enum
-from types import FunctionType, MethodType, ModuleType, NoneType, NotImplementedType, UnionType
+from types import EllipsisType, FunctionType, MethodType, ModuleType, NoneType, NotImplementedType, UnionType
 from typing import TYPE_CHECKING, Annotated, Any, Literal, TypeVar, get_origin, overload
 
 if TYPE_CHECKING:
@@ -42,7 +42,7 @@ def validate_value(value: Any) -> Value:
 
 def try_validate_value(value: Any) -> Value | None:
     from sonolus.script.globals import _GlobalPlaceholder
-    from sonolus.script.internal.constant import MiscConstantValue
+    from sonolus.script.internal.constant import BasicConstantValue
     from sonolus.script.internal.dict_impl import DictImpl
     from sonolus.script.internal.generic import PartialGeneric
     from sonolus.script.internal.tuple_impl import TupleImpl
@@ -65,8 +65,8 @@ def try_validate_value(value: Any) -> Value | None:
             return value
         case type():
             if value in {int, float, bool}:
-                return MiscConstantValue.of(Num)
-            return MiscConstantValue.of(value)
+                return BasicConstantValue.of(Num)
+            return BasicConstantValue.of(value)
         case int() | float() | bool():
             return Num._accept_(value)
         case tuple():
@@ -78,17 +78,18 @@ def try_validate_value(value: Any) -> Value | None:
             | TypeVar()
             | FunctionType()
             | MethodType()
-            | NotImplementedType()
             | str()
-            | NoneType()
             | ModuleType()
+            | NoneType()
+            | NotImplementedType()
+            | EllipsisType()
         ):
-            return MiscConstantValue.of(value)
+            return BasicConstantValue.of(value)
         case other_type if get_origin(value) in {Literal, Annotated, UnionType, tuple}:
-            return MiscConstantValue.of(other_type)
+            return BasicConstantValue.of(other_type)
         case _GlobalPlaceholder():
             return value.get()
         case comptime_value if getattr(comptime_value, "_is_comptime_value_", False):
-            return MiscConstantValue.of(comptime_value)
+            return BasicConstantValue.of(comptime_value)
         case _:
             return None

sonolus/script/internal/transient.py

@@ -2,7 +2,7 @@ from collections.abc import Iterable
 from typing import Any, Self
 
 from sonolus.backend.place import BlockPlace
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import DataValue, Value
 
 
 class TransientValue(Value):
@@ -23,10 +23,10 @@ class TransientValue(Value):
         raise TypeError(f"{cls.__name__} cannot be dereferenced")
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         raise TypeError(f"{cls.__name__} cannot be constructed from list")
 
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         raise TypeError(f"{type(self).__name__} cannot be deconstructed to list")
 
     @classmethod

sonolus/script/internal/value.py

@@ -1,10 +1,36 @@
 from abc import abstractmethod
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from typing import Any, Self
 
+from sonolus.backend.ir import IRConst, IRExpr, IRStmt
 from sonolus.backend.place import BlockPlace
 
 
+class BackingValue:
+    def read(self) -> IRExpr:
+        raise NotImplementedError()
+
+    def write(self, value: IRExpr) -> IRStmt:
+        raise NotImplementedError()
+
+
+class ExprBackingValue(BackingValue):
+    """A backing value that is backed by an expression."""
+
+    def __init__(self, expr: IRExpr):
+        self._expr = expr
+
+    def read(self) -> IRExpr:
+        return self._expr
+
+    def write(self, value: IRExpr) -> IRStmt:
+        raise RuntimeError("Value is read-only, cannot write to it")
+
+
+type DataValue = BlockPlace | BackingValue | float | int | bool
+type BackingSource = Callable[[IRExpr], BackingValue]
+
+
 class Value:
     """Base class for values."""
 
@@ -59,15 +85,20 @@ class Value:
         """
         raise NotImplementedError
 
+    @classmethod
+    def _from_backing_source_(cls, source: BackingSource) -> Self:
+        """Creates a value from a backing source."""
+        return cls._from_list_(source(IRConst(i)) for i in range(cls._size_()))
+
     @classmethod
     @abstractmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
-        """Creates a value from a list of floats."""
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
+        """Creates a value from a list of data values."""
         raise NotImplementedError
 
     @abstractmethod
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
-        """Converts this value to a list of floats."""
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
+        """Converts this value to a list of data values."""
         raise NotImplementedError
 
     @classmethod
@@ -76,9 +107,7 @@ class Value:
         """Returns the keys to a flat representation of this value."""
         raise NotImplementedError
 
-    def _to_flat_dict_(
-        self, prefix: str, level_refs: dict[Any, str] | None = None
-    ) -> dict[str, float | str | BlockPlace]:
+    def _to_flat_dict_(self, prefix: str, level_refs: dict[Any, str] | None = None) -> dict[str, DataValue | str]:
         """Converts this value to a flat dictionary."""
         return dict(zip(self._flat_keys_(prefix), self._to_list_(level_refs), strict=False))
 
@@ -96,12 +125,12 @@ class Value:
             v: Num
 
         a = 1
-        b = X(a) # (1) _get() is called on a
-        c = b.v # (2) _get() is called on the value for v
+        b = X(a) # (1) _get_() is called on a
+        c = b.v # (2) _get_() is called on the value for v
 
         # (1) prevents this from changing the value of a
         # (2) prevents this from changing the value of c
-        # Thus, both calls to _get() are necessary to ensure values behave immutably.
+        # Thus, both calls to _get_() are necessary to ensure values behave immutably.
         b.v = 2
         ```
         """

sonolus/script/interval.py

@@ -1,7 +1,7 @@
 from typing import Self
 
 from sonolus.backend.ops import Op
-from sonolus.script.debug import error
+from sonolus.script.debug import static_error
 from sonolus.script.internal.native import native_function
 from sonolus.script.num import Num
 from sonolus.script.record import Record
@@ -24,17 +24,6 @@ class Interval(Record):
         """Get an empty interval."""
         return cls(0, 0)
 
-    def then(self, length: float) -> Self:
-        """Get the interval after this one with a given length.
-
-        Args:
-            length: The length of the interval.
-
-        Returns:
-            An interval that has the end of this interval as the start and has the given length.
-        """
-        return Interval(self.end, self.end + length)
-
     @property
     def length(self) -> float:
         """The length of the interval.
@@ -45,7 +34,7 @@ class Interval(Record):
 
     @property
     def is_empty(self) -> bool:
-        """Whether the interval has length of zero or less."""
+        """Whether the has a start greater than its end."""
         return self.start > self.end
 
     @property
@@ -73,7 +62,7 @@ class Interval(Record):
             case Num(value):
                 return self.start <= value <= self.end
             case _:
-                error("Invalid type for interval check")
+                static_error("Invalid type for interval check")
 
     def __add__(self, other: float | int) -> Self:
         """Add a value to both ends of the interval.

sonolus/script/num.py

@@ -5,13 +5,13 @@ import operator
 from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING, Any, Self, TypeGuard, final, runtime_checkable
 
-from sonolus.backend.ir import IRConst, IRGet, IRPureInstr, IRSet
+from sonolus.backend.ir import IRConst, IRExpr, IRGet, IRPureInstr, IRSet
 from sonolus.backend.ops import Op
-from sonolus.backend.place import BlockPlace, Place
+from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.error import InternalError
 from sonolus.script.internal.impl import meta_fn
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingValue, DataValue, ExprBackingValue, Value
 
 
 class _NumMeta(type):
@@ -30,15 +30,19 @@ class _Num(Value, metaclass=_NumMeta):
     # Since we don't support complex numbers, real is equal to the original number
     __match_args__ = ("real",)
 
-    data: BlockPlace | float | int | bool
+    data: DataValue
 
-    def __init__(self, data: Place | float | int | bool):
+    def __init__(self, data: DataValue | IRExpr):
         if isinstance(data, complex):
             raise TypeError("Cannot create a Num from a complex number")
         if isinstance(data, int):
             data = float(data)
+        if isinstance(data, IRConst | IRPureInstr | IRGet):
+            data = ExprBackingValue(data)
         if _is_num(data):
             raise InternalError("Cannot create a Num from a Num")
+        if not isinstance(data, BlockPlace | BackingValue | float | int | bool):
+            raise TypeError(f"Cannot create a Num from {type(data)}")
         self.data = data
 
     def __str__(self) -> str:
@@ -78,7 +82,7 @@ class _Num(Value, metaclass=_NumMeta):
         return cls(value)
 
     def _is_py_(self) -> bool:
-        return not isinstance(self.data, BlockPlace)
+        return isinstance(self.data, float | int | bool)
 
     def _as_py_(self) -> Any:
         if not self._is_py_():
@@ -88,11 +92,11 @@ class _Num(Value, metaclass=_NumMeta):
         return self.data
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         value = next(iter(values))
         return Num(value)
 
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue]:
         return [self.data]
 
     @classmethod
@@ -111,10 +115,14 @@ class _Num(Value, metaclass=_NumMeta):
 
     def _set_(self, value: Self):
         if ctx():
-            if not isinstance(self.data, BlockPlace):
-                raise ValueError("Cannot set a compile time constant value")
-            ctx().check_writable(self.data)
-            ctx().add_statements(IRSet(self.data, value.ir()))
+            match self.data:
+                case BackingValue():
+                    ctx().add_statements(self.data.write(value))
+                case BlockPlace():
+                    ctx().check_writable(self.data)
+                    ctx().add_statements(IRSet(self.data, value.ir()))
+                case _:
+                    raise ValueError("Cannot set a read-only value")
         else:
             self.data = value.data
 
@@ -144,12 +152,17 @@ class _Num(Value, metaclass=_NumMeta):
             return cls(0)
 
     def ir(self):
-        if isinstance(self.data, BlockPlace):
-            return IRGet(self.data)
-        else:
-            return IRConst(self.data)
+        match self.data:
+            case BlockPlace():
+                return IRGet(self.data)
+            case BackingValue():
+                return self.data.read()
+            case _:
+                return IRConst(self.data)
 
     def index(self) -> int | BlockPlace:
+        if isinstance(self.data, BlockPlace):
+            return self._get_().data
         return self.data
 
     def _bin_op(self, other: Self, const_fn: Callable[[Self, Self], Self | None], ir_op: Op) -> Self:

sonolus/script/options.py

@@ -15,6 +15,7 @@ from sonolus.script.num import Num
 @dataclass
 class _SliderOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
@@ -35,6 +36,8 @@ class _SliderOption:
             "max": self.max,
             "step": self.step,
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         if self.unit is not None:
@@ -45,6 +48,7 @@ class _SliderOption:
 @dataclass
 class _ToggleOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
@@ -58,6 +62,8 @@ class _ToggleOption:
             "advanced": self.advanced,
             "def": int(self.default),
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         return result
@@ -66,6 +72,7 @@ class _ToggleOption:
 @dataclass
 class _SelectOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
@@ -81,6 +88,8 @@ class _SelectOption:
             "def": self.default,
             "values": self.values,
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         return result
@@ -89,6 +98,7 @@ class _SelectOption:
 def slider_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
     default: float,
@@ -102,6 +112,7 @@ def slider_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
@@ -111,12 +122,13 @@ def slider_option(
         unit: The unit of the option.
         scope: The scope of the option.
     """
-    return _SliderOption(name, standard, advanced, scope, default, min, max, step, unit)
+    return _SliderOption(name, description, standard, advanced, scope, default, min, max, step, unit)
 
 
 def toggle_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
     default: bool,
@@ -126,17 +138,19 @@ def toggle_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
         scope: The scope of the option.
     """
-    return _ToggleOption(name, standard, advanced, scope, default)
+    return _ToggleOption(name, description, standard, advanced, scope, default)
 
 
 def select_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
     default: str | int,
@@ -147,6 +161,7 @@ def select_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
@@ -155,7 +170,7 @@ def select_option(
     """
     if isinstance(default, str):
         default = values.index(default)
-    return _SelectOption(name, standard, advanced, scope, default, values)
+    return _SelectOption(name, description, standard, advanced, scope, default, values)
 
 
 type Options = NewType("Options", Any)

sonolus/script/particle.py

@@ -91,6 +91,7 @@ class _ParticleInfo:
 
 
 def particle(name: str) -> Any:
+    """Define a particle with the given name."""
     return _ParticleInfo(name)
 
 

sonolus/script/pointer.py

@@ -1,7 +1,7 @@
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn, validate_value
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingSource, Value
 from sonolus.script.num import Num, _is_num
 
 
@@ -30,3 +30,11 @@ def _deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
     if not (isinstance(type_, type) and issubclass(type_, Value)):
         raise TypeError("type_ must be a Value")
     return type_._from_place_(BlockPlace(block, offset))
+
+
+@meta_fn
+def _backing_deref[T: Value](source: BackingSource, type_: type[T]) -> T:
+    type_ = validate_value(type_)._as_py_()
+    if not isinstance(type_, type) or not issubclass(type_, Value):
+        raise TypeError("type_ must be a Value")
+    return type_._from_backing_source_(source)

sonolus/script/quad.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Protocol, Self
 
 from sonolus.script.record import Record
+from sonolus.script.values import zeros
 from sonolus.script.vec import Vec2, pnpoly
 
 
@@ -10,7 +11,7 @@ class Quad(Record):
     """A quad defined by its four corners.
 
     Usage:
-        ```
+        ```python
         Quad(bl: Vec2, tl: Vec2, tr: Vec2, br: Vec2)
         ```
     """
@@ -27,6 +28,16 @@ class Quad(Record):
     br: Vec2
     """The bottom-right corner of the quad."""
 
+    @classmethod
+    def from_quad(cls, value: QuadLike, /) -> Quad:
+        """Create a quad from a quad-like value."""
+        return cls(
+            bl=value.bl,
+            tl=value.tl,
+            tr=value.tr,
+            br=value.br,
+        )
+
     @property
     def center(self) -> Vec2:
         """The center of the quad."""
@@ -95,6 +106,44 @@ class Quad(Record):
         """Rotate the quad by the given angle about its center and return a new quad."""
         return self.rotate_about(angle, self.center)
 
+    def permute(self, count: int = 1, /) -> Self:
+        """Perform a cyclic permutation of the quad's vertices and return a new quad.
+
+        On a square, this operation is equivalent to rotating the square counterclockwise 90 degrees `count` times.
+
+        Negative values of `count` are allowed and will rotate the quad clockwise.
+
+        Args:
+            count: The number of vertices to shift. Defaults to 1.
+
+        Returns:
+            The permuted quad.
+        """
+        count = int(count % 4)
+        result = zeros(Quad)
+        match count:
+            case 0:
+                result.bl @= self.bl
+                result.tl @= self.tl
+                result.tr @= self.tr
+                result.br @= self.br
+            case 1:
+                result.bl @= self.br
+                result.tl @= self.bl
+                result.tr @= self.tl
+                result.br @= self.tr
+            case 2:
+                result.bl @= self.tr
+                result.tl @= self.br
+                result.tr @= self.bl
+                result.br @= self.tl
+            case 3:
+                result.bl @= self.tl
+                result.tl @= self.tr
+                result.tr @= self.br
+                result.br @= self.bl
+        return result
+
     def contains_point(self, point: Vec2, /) -> bool:
         """Check if the quad contains the given point.
 
@@ -111,7 +160,7 @@ class Rect(Record):
     """A rectangle defined by its top, right, bottom, and left edges.
 
     Usage:
-        ```
+        ```python
         Rect(t: float, r: float, b: float, l: float)
         ```
     """
@@ -174,7 +223,7 @@ class Rect(Record):
         return Vec2((self.l + self.r) / 2, (self.t + self.b) / 2)
 
     def as_quad(self) -> Quad:
-        """Convert the rectangle to a quad."""
+        """Convert the rectangle to a [`Quad`][sonolus.script.quad.Quad]."""
         return Quad(
             bl=self.bl,
             tl=self.tl,
@@ -248,7 +297,7 @@ class Rect(Record):
         return self.l <= point.x <= self.r and self.b <= point.y <= self.t
 
 
-class QuadLike(Protocol):
+class _QuadLike(Protocol):
     """A protocol for types that can be used as quads."""
 
     @property
@@ -268,6 +317,11 @@ class QuadLike(Protocol):
         """The bottom-right corner of the quad."""
 
 
+# PyCharm doesn't recognize attributes as satisfying the protocol.
+type QuadLike = _QuadLike | Quad
+"""A type that can be used as a quad."""
+
+
 def flatten_quad(quad: QuadLike) -> tuple[float, float, float, float, float, float, float, float]:
     bl = quad.bl
     tl = quad.tl

sonolus/script/record.py

@@ -16,7 +16,7 @@ from sonolus.script.internal.generic import (
     validate_type_spec,
 )
 from sonolus.script.internal.impl import meta_fn
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingSource, DataValue, Value
 from sonolus.script.num import Num
 
 
@@ -157,6 +157,17 @@ class Record(GenericValue):
     def _is_value_type_(cls) -> bool:
         return False
 
+    @classmethod
+    def _from_backing_source_(cls, source: BackingSource) -> Self:
+        result = object.__new__(cls)
+        result._value = {
+            field.name: field.type._from_backing_source_(
+                lambda offset, field_offset=field.offset: source((Num(offset) + Num(field_offset)).ir())
+            )
+            for field in cls._fields
+        }
+        return result
+
     @classmethod
     def _from_place_(cls, place: BlockPlace) -> Self:
         result = object.__new__(cls)
@@ -182,11 +193,11 @@ class Record(GenericValue):
         return self
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         iterator = iter(values)
         return cls(**{field.name: field.type._from_list_(iterator) for field in cls._fields})
 
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         result = []
         for field in self._fields:
             result.extend(self._value[field.name]._to_list_(level_refs))
@@ -203,7 +214,7 @@ class Record(GenericValue):
         return self
 
     def _set_(self, value: Self):
-        raise TypeError("Record does not support set_")
+        raise TypeError("Record does not support _set_")
 
     def _copy_from_(self, value: Self):
         value = self._accept_(value)

sonolus/script/runtime.py

@@ -2,7 +2,8 @@ from enum import IntEnum
 
 from sonolus.backend.mode import Mode
 from sonolus.script.array import Array
-from sonolus.script.containers import VarArray
+from sonolus.script.array_like import ArrayLike
+from sonolus.script.containers import ArrayPointer
 from sonolus.script.globals import (
     _level_life,
     _level_score,
@@ -315,7 +316,8 @@ class Touch(Record):
 
 @_runtime_touch_array
 class _TouchArray:
-    touches: Array[Touch, 999]
+    # Handled specially, see touches()
+    pass
 
 
 @_runtime_skin_transform
@@ -500,6 +502,15 @@ def is_tutorial() -> bool:
     return ctx() and ctx().global_state.mode == Mode.TUTORIAL
 
 
+@meta_fn
+def is_preprocessing() -> bool:
+    """Check if the game is in the preprocessing stage.
+
+    Returns True if the current callback is one of preprocess, spawn_order, spawn_time, or despawn_time.
+    """
+    return ctx() and ctx().callback in {"preprocess", "spawnOrder", "spawnTime", "despawnTime"}
+
+
 @meta_fn
 def aspect_ratio() -> float:
     """Get the aspect ratio of the game."""
@@ -640,15 +651,15 @@ def scaled_time() -> float:
 
 
 @meta_fn
-def touches() -> VarArray[Touch, 999]:
+def touches() -> ArrayLike[Touch]:
     """Get the current touches of the game."""
     if not ctx():
-        return VarArray(0, Array[Touch, 0]())
+        return Array[Touch, 0]()
     match ctx().global_state.mode:
         case Mode.PLAY:
-            return VarArray(_PlayRuntimeUpdate.touch_count, _TouchArray.touches)
+            return ArrayPointer[Touch](_PlayRuntimeUpdate.touch_count, ctx().blocks.RuntimeTouchArray, 0)
         case _:
-            return VarArray(0, Array[Touch, 0]())
+            return Array[Touch, 0]()
 
 
 @meta_fn