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

sonolus/script/archetype.py

@@ -8,10 +8,9 @@ from enum import Enum, StrEnum
 from types import FunctionType
 from typing import Annotated, Any, ClassVar, Self, TypedDict, get_origin
 
-from sonolus.backend.ir import IRConst, IRInstr
+from sonolus.backend.ir import IRConst, IRExpr, IRInstr, IRPureInstr, IRStmt
 from sonolus.backend.mode import Mode
 from sonolus.backend.ops import Op
-from sonolus.backend.place import BlockPlace
 from sonolus.script.bucket import Bucket, Judgment
 from sonolus.script.internal.callbacks import PLAY_CALLBACKS, PREVIEW_CALLBACKS, WATCH_ARCHETYPE_CALLBACKS, CallbackInfo
 from sonolus.script.internal.context import ctx
@@ -20,9 +19,9 @@ from sonolus.script.internal.generic import validate_concrete_type
 from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_call
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingValue, DataValue, Value
 from sonolus.script.num import Num
-from sonolus.script.pointer import _deref
+from sonolus.script.pointer import _backing_deref, _deref
 from sonolus.script.record import Record
 from sonolus.script.values import zeros
 
@@ -44,6 +43,17 @@ class _ArchetypeFieldInfo:
     storage: _StorageType
 
 
+class _ExportBackingValue(BackingValue):
+    def __init__(self, index: IRExpr):
+        self.index = index
+
+    def read(self) -> IRExpr:
+        raise NotImplementedError("Exported fields are write-only")
+
+    def write(self, value: IRExpr) -> IRStmt:
+        return IRInstr(Op.ExportValue, [self.index, value])
+
+
 class _ArchetypeField(SonolusDescriptor):
     def __init__(self, name: str, data_name: str, storage: _StorageType, offset: int, type_: type[Value]):
         self.name = name
@@ -70,7 +80,20 @@ class _ArchetypeField(SonolusDescriptor):
                     case _ArchetypeLevelData(values=values):
                         result = values[self.name]
             case _StorageType.EXPORTED:
-                raise RuntimeError("Exported fields are write-only")
+                match instance._data_:
+                    case _ArchetypeSelfData():
+
+                        def backing_source(i: IRExpr):
+                            return _ExportBackingValue(IRPureInstr(Op.Add, [i, IRConst(self.offset)]))
+
+                        result = _backing_deref(
+                            backing_source,
+                            self.type,
+                        )
+                    case _ArchetypeReferenceData():
+                        raise RuntimeError("Exported fields of other entities are not accessible")
+                    case _ArchetypeLevelData():
+                        raise RuntimeError("Exported fields are not available in level data")
             case _StorageType.MEMORY:
                 match instance._data_:
                     case _ArchetypeSelfData():
@@ -584,6 +607,7 @@ class _BaseArchetype:
         cls._spawn_signature_ = inspect.Signature(
             [inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in cls._memory_fields_]
         )
+        cls._post_init_fields()
 
     @property
     @abstractmethod
@@ -609,6 +633,10 @@ class _BaseArchetype:
             case _:
                 raise RuntimeError("Invalid entity data")
 
+    @classmethod
+    def _post_init_fields(cls):
+        pass
+
 
 class PlayArchetype(_BaseArchetype):
     """Base class for play mode archetypes.
@@ -885,6 +913,11 @@ class WatchArchetype(_BaseArchetype):
             case _:
                 raise RuntimeError("Result is only accessible from the entity itself")
 
+    @classmethod
+    def _post_init_fields(cls):
+        if cls._exported_fields_:
+            raise RuntimeError("Watch archetypes cannot have exported fields")
+
 
 class PreviewArchetype(_BaseArchetype):
     """Base class for preview mode archetypes.
@@ -934,6 +967,11 @@ class PreviewArchetype(_BaseArchetype):
         """The index of this entity."""
         return self._info.index
 
+    @classmethod
+    def _post_init_fields(cls):
+        if cls._exported_fields_:
+            raise RuntimeError("Preview archetypes cannot have exported fields")
+
 
 @meta_fn
 def entity_info_at(index: Num) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
@@ -1066,7 +1104,7 @@ class EntityRef[A: _BaseArchetype](Record):
         """Check if entity at the index is precisely of the archetype."""
         return self.index >= 0 and self.archetype().is_at(self.index)
 
-    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]:
         ref = getattr(self, "_ref_", None)
         if ref is None:
             return [self.index]

sonolus/script/array.py

@@ -12,7 +12,7 @@ from sonolus.script.internal.context import ctx
 from sonolus.script.internal.error import InternalError
 from sonolus.script.internal.generic import GenericValue
 from sonolus.script.internal.impl import meta_fn, validate_value
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import DataValue, Value
 from sonolus.script.num import Num
 
 
@@ -108,11 +108,11 @@ class Array[T, Size](GenericValue, ArrayLike[T]):
         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(*(cls.element_type()._from_list_(iterator) for _ in range(cls.size())))
 
-    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]:
         match self._value:
             case list():
                 return [entry for value in self._value for entry in value._to_list_(level_refs)]

sonolus/script/array_like.py

@@ -158,10 +158,14 @@ class ArrayLike[T](Sequence, ABC):
         return min_index
 
     def _max_(self, key: Callable[T, Any] | None = None) -> T:
-        return self[self.index_of_max(key=key)]
+        index = self.index_of_max(key=key)
+        assert index != -1
+        return self[index]
 
     def _min_(self, key: Callable[T, Any] | None = None) -> T:
-        return self[self.index_of_min(key=key)]
+        index = self.index_of_min(key=key)
+        assert index != -1
+        return self[index]
 
     def swap(self, i: Num, j: Num, /):
         """Swap the values at the given indices.

sonolus/script/containers.py

@@ -1,13 +1,44 @@
 from __future__ import annotations
 
+from sonolus.backend.visitor import compile_and_call
 from sonolus.script.array import Array
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import error
+from sonolus.script.internal.context import ctx
+from sonolus.script.internal.impl import meta_fn
 from sonolus.script.iterator import SonolusIterator
+from sonolus.script.num import Num
+from sonolus.script.pointer import _deref
 from sonolus.script.record import Record
 from sonolus.script.values import alloc, copy
 
 
+class Box[T](Record):
+    """A box that contains a value.
+
+    This can be helpful for generic code that can handle both Num and non-Num types.
+
+    Usage:
+        ```python
+        Box[T](value: T)
+        ```
+
+    Examples:
+        ```python
+        box = Box(1)
+        box = Box[int](2)
+
+        x: T = ...
+        y: T = ...
+        box = Box(x)
+        box.value = y  # Works regardless of whether x is a Num or not
+        ```
+    """
+
+    value: T
+    """The value contained in the box."""
+
+
 class Pair[T, U](Record):
     """A generic pair of values.
 
@@ -129,6 +160,17 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
         self._array[self._size] = value
         self._size += 1
 
+    def append_unchecked(self, value: T):
+        """Append the given value to the end of the array without checking the capacity.
+
+        Use with caution as this may cause hard to debug issues if the array is full.
+
+        Args:
+            value: The value to append.
+        """
+        self._array[self._size] = value
+        self._size += 1
+
     def extend(self, values: ArrayLike[T]):
         """Appends copies of the values in the given array to the end of the array.
 
@@ -258,6 +300,130 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
         raise TypeError("unhashable type: 'VarArray'")
 
 
+class ArrayPointer[T](Record, ArrayLike[T]):
+    """An array defined by a size and pointer to the first element.
+
+    This is intended to be created internally and improper use may result in hard to debug issues.
+
+    Usage:
+        ```python
+        ArrayPointer[T](size: int, block: int, offset: int)
+        ```
+    """
+
+    size: int
+    block: int
+    offset: int
+
+    def __len__(self) -> int:
+        """Return the number of elements in the array."""
+        return self.size
+
+    @classmethod
+    def element_type(cls) -> type[T]:
+        """Return the type of the elements in the array."""
+        return cls.type_var_value(T)
+
+    def _check_index(self, index: int):
+        assert 0 <= index < self.size
+
+    @meta_fn
+    def _get_item(self, item: int) -> T:
+        if not ctx():
+            raise TypeError("ArrayPointer values cannot be accessed outside of a context")
+        return _deref(
+            self.block,
+            self.offset + Num._accept_(item) * Num._accept_(self.element_type()._size_()),
+            self.element_type(),
+        )
+
+    @meta_fn
+    def __getitem__(self, item: int) -> T:
+        compile_and_call(self._check_index, item)
+        return self._get_item(item)._get_()
+
+    @meta_fn
+    def __setitem__(self, key: int, value: T):
+        compile_and_call(self._check_index, key)
+        dst = self._get_item(key)
+        if self.element_type()._is_value_type_():
+            dst._set_(value)
+        else:
+            dst._copy_from__(value)
+
+
+class ArraySet[T, Capacity](Record):
+    """A set implemented as an array with a fixed maximum capacity.
+
+    Usage:
+        ```python
+        ArraySet[T, Capacity].new()  # Create a new empty set
+        ```
+
+    Examples:
+        ```python
+        s = ArraySet[int, 10].new()
+        s.add(1)
+        s.add(2)
+        assert 1 in s
+        assert 3 not in s
+        s.remove(1)
+        assert 1 not in s
+        ```
+    """
+
+    _values: VarArray[T, Capacity]
+
+    @classmethod
+    def new(cls):
+        """Create a new empty set."""
+        element_type = cls.type_var_value(T)
+        capacity = cls.type_var_value(Capacity)
+        return cls(VarArray[element_type, capacity].new())
+
+    def __len__(self):
+        """Return the number of elements in the set."""
+        return len(self._values)
+
+    def __contains__(self, value):
+        """Return whether the given value is present in the set."""
+        return value in self._values
+
+    def __iter__(self):
+        """Return an iterator over the values in the set."""
+        return self._values.__iter__()
+
+    def add(self, value: T) -> bool:
+        """Add a copy of the given value to the set.
+
+        This has no effect and returns False if the value is already present or if the set is full.
+
+        Args:
+            value: The value to add.
+
+        Returns:
+            True if the value was added, False otherwise.
+        """
+        return self._values.set_add(value)
+
+    def remove(self, value: T) -> bool:
+        """Remove the given value from the set.
+
+        This has no effect and returns False if the value is not present.
+
+        Args:
+            value: The value to remove.
+
+        Returns:
+            True if the value was removed, False otherwise.
+        """
+        return self._values.set_remove(value)
+
+    def clear(self):
+        """Clear the set, removing all elements."""
+        self._values.clear()
+
+
 class _ArrayMapEntry[K, V](Record):
     key: K
     value: V

sonolus/script/debug.py

@@ -16,8 +16,13 @@ debug_log_callback = ContextVar[Callable[[Num], None]]("debug_log_callback")
 
 
 @meta_fn
-def error(message: str | None = None) -> None:
-    message = message._as_py_() if message is not None else "Error"
+def error(message: str | None = None) -> Never:
+    """Raise an error.
+
+    This function is used to raise an error during runtime.
+    When this happens, the game will pause in debug mode. The current callback will also immediately return 0.
+    """
+    message = validate_value(message)._as_py_() if message is not None else "Error"
     if not isinstance(message, str):
         raise ValueError("Expected a string")
     if ctx():
@@ -28,6 +33,19 @@ def error(message: str | None = None) -> None:
         raise RuntimeError(message)
 
 
+@meta_fn
+def static_error(message: str | None = None) -> Never:
+    """Raise a static error.
+
+    This function is used to raise an error during compile-time if the compiler cannot guarantee that
+    this function will not be called during runtime.
+    """
+    message = validate_value(message)._as_py_() if message is not None else "Error"
+    if not isinstance(message, str):
+        raise ValueError("Expected a string")
+    raise RuntimeError(message)
+
+
 @meta_fn
 def debug_log(value: Num):
     """Log a value in debug mode."""

sonolus/script/engine.py

@@ -4,7 +4,7 @@ import json
 from collections.abc import Callable
 from os import PathLike
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from sonolus.build.collection import Asset, load_asset
 from sonolus.script.archetype import PlayArchetype, PreviewArchetype, WatchArchetype, _BaseArchetype
@@ -81,7 +81,7 @@ class Engine:
         meta: Additional metadata of the engine.
     """
 
-    version = 12
+    version: Literal[13] = 13
 
     def __init__(
         self,

sonolus/script/internal/constant.py

@@ -3,7 +3,7 @@ from typing import Any, ClassVar, Self
 
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.impl import meta_fn
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import DataValue, Value
 
 
 class _Missing:
@@ -94,10 +94,10 @@ class ConstantValue(Value):
         return self.value()
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         return cls()
 
-    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]:
         return []
 
     @classmethod

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,23 @@
 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()
+
+
+type DataValue = BlockPlace | BackingValue | float | int | bool
+type BackingSource = Callable[[IRExpr], BackingValue]
+
+
 class Value:
     """Base class for values."""
 
@@ -59,15 +72,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 +94,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 +112,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

@@ -7,11 +7,11 @@ from typing import TYPE_CHECKING, Any, Self, TypeGuard, final, runtime_checkable
 
 from sonolus.backend.ir import IRConst, 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, Value
 
 
 class _NumMeta(type):
@@ -30,15 +30,17 @@ 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):
         if isinstance(data, complex):
             raise TypeError("Cannot create a Num from a complex number")
         if isinstance(data, int):
             data = float(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 +80,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 +90,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 +113,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 +150,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/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
 
 
@@ -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.
 
@@ -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 DataValue, Value
 from sonolus.script.num import Num
 
 
@@ -182,11 +182,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))

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

sonolus/script/text.py

@@ -157,6 +157,15 @@ class StandardText(StrEnum):
     SIMLINE_COLOR = "#SIMLINE_COLOR"
     SIMLINE_ALPHA = "#SIMLINE_ALPHA"
     SIMLINE_ANIMATION = "#SIMLINE_ANIMATION"
+    PREVIEW_SCALE_VERTICAL = "#PREVIEW_SCALE_VERTICAL"
+    PREVIEW_SCALE_HORIZONTAL = "#PREVIEW_SCALE_HORIZONTAL"
+    PREVIEW_TIME = "#PREVIEW_TIME"
+    PREVIEW_SCORE = "#PREVIEW_SCORE"
+    PREVIEW_BPM = "#PREVIEW_BPM"
+    PREVIEW_TIMESCALE = "#PREVIEW_TIMESCALE"
+    PREVIEW_BEAT = "#PREVIEW_BEAT"
+    PREVIEW_MEASURE = "#PREVIEW_MEASURE"
+    PREVIEW_COMBO = "#PREVIEW_COMBO"
     NONE = "#NONE"
     ANY = "#ANY"
     ALL = "#ALL"

sonolus/script/ui.py

@@ -20,9 +20,14 @@ class UiMetric(StrEnum):
 
 
 class UiJudgmentErrorStyle(StrEnum):
-    """The style of the judgment error."""
+    """The style of the judgment error.
+
+    The name of each member refers to what's used for positive (late) judgment errors.
+    """
 
     NONE = "none"
+    LATE = "late"
+    EARLY = "early"  # Not really useful
     PLUS = "plus"
     MINUS = "minus"
     ARROW_UP = "arrowUp"
@@ -38,9 +43,13 @@ class UiJudgmentErrorStyle(StrEnum):
 class UiJudgmentErrorPlacement(StrEnum):
     """The placement of the judgment error."""
 
-    BOTH = "both"
     LEFT = "left"
     RIGHT = "right"
+    LEFT_RIGHT = "leftRight"
+    TOP = "top"
+    BOTTOM = "bottom"
+    TOP_BOTTOM = "topBottom"
+    CENTER = "center"
 
 
 class EaseType(StrEnum):
@@ -193,8 +202,8 @@ class UiConfig:
             scale=UiAnimationTween(1.2, 1, 0.2, EaseType.IN_CUBIC), alpha=UiAnimationTween(1, 1, 0, EaseType.NONE)
         )
     )
-    judgment_error_style: UiJudgmentErrorStyle = UiJudgmentErrorStyle.NONE
-    judgment_error_placement: UiJudgmentErrorPlacement = UiJudgmentErrorPlacement.BOTH
+    judgment_error_style: UiJudgmentErrorStyle = UiJudgmentErrorStyle.LATE
+    judgment_error_placement: UiJudgmentErrorPlacement = UiJudgmentErrorPlacement.TOP
     judgment_error_min: float = 0.0
 
     def to_dict(self):

sonolus/script/values.py

@@ -33,7 +33,7 @@ def copy[T](value: T) -> T:
 
 
 def swap[T](a: T, b: T):
-    """Swap the values of the given variables."""
+    """Swap the values of the two given arguments."""
     temp = copy(a)
     a @= b
     b @= temp

{sonolus_py-0.2.0.dist-info → sonolus_py-0.2.1.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.2.0
+Version: 0.2.1
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
 # Sonolus.py
-Sonolus engine development in Python.
+Sonolus engine development in Python. See [docs](https://sonolus.py.qwewqa.xyz) for more information.

{sonolus_py-0.2.0.dist-info → sonolus_py-0.2.1.dist-info}/RECORD

@@ -34,41 +34,41 @@ sonolus/build/level.py,sha256=AjvK4725nqDcg7oGn5kWocBdG-AcirXpku74T7c2epA,673
 sonolus/build/node.py,sha256=gnX71RYDUOK_gYMpinQi-bLWO4csqcfiG5gFmhxzSec,1330
 sonolus/build/project.py,sha256=DhNqgHnm73qKUOhrg1JPlWEL0Vg7VxcGUbNokpMWzVE,6315
 sonolus/script/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sonolus/script/archetype.py,sha256=UbIAn6xmCOUpp6Aa8Y_Bd85LhWglinG6o-TE0sRdLPw,38716
-sonolus/script/array.py,sha256=mUOY0cbjbSBssQNwmJ4EbySmyUGg2I-lnLmqDKu8Vh8,9798
-sonolus/script/array_like.py,sha256=OVOLMadS-Jj941S-EgoxlFPdaQLT6ZrHzaMnKtB6PfU,8346
+sonolus/script/archetype.py,sha256=I-K9uT4l6S5w4toDplzG8v01w0KTM4TsZZPgiZgwOrA,40098
+sonolus/script/array.py,sha256=l-KdtHvxF4NpCSZAw4t7MG4N5aZ_gOTGkemDobC6mQY,9791
+sonolus/script/array_like.py,sha256=nCIt_TxV7Ck6ovbSXyViqUkxsO9BksFOjUhpwF0uuxA,8444
 sonolus/script/bucket.py,sha256=oaaB7OXtBWzr8sLzPOpm8-GMhs7FzEhYrI1uVcM0DHM,7453
-sonolus/script/containers.py,sha256=tf0-UUSq8NH6k9jIKq6qgXRxanFQ0f5olH6uHghTynk,13171
-sonolus/script/debug.py,sha256=-rFPOgtmGLjfBsCPzPKObb4t-x5VN3QYb2BznZGDMgI,2457
+sonolus/script/containers.py,sha256=QUFUk1lDwM2AzIPH6uHkZtZXT2D4_xT3P6pJIp6i7Ew,17640
+sonolus/script/debug.py,sha256=aYyFm8DuoifK0L0pY4G7ZZEEeSqbig90Yogy6Z_M8Yg,3135
 sonolus/script/easing.py,sha256=7zaDKIfM_whUpb4FBz1DAF4NNG2vk_nDjl8kL2Y90aU,11396
 sonolus/script/effect.py,sha256=V9bJvMzs1O4C1PjTOKgsAXov-l4AnDb2h38-DzmeWpI,5838
-sonolus/script/engine.py,sha256=_5ZYPT4irTePjki16sFI7A8dzdm3kXAS7tvrp_ocG7Y,10661
+sonolus/script/engine.py,sha256=BhhQTrHuGAAAD6JPQ3R0jvHdimwW83PPghEIdAdtGMA,10683
 sonolus/script/globals.py,sha256=Z8RfLkgDuXPIKiq-aOqblP0s__ALGmvcKdlyWZH21EM,9166
 sonolus/script/instruction.py,sha256=PNfxC1dhT_hB0BxhDV3KXMn_kKxfI0t1iZmg8m6ddMU,6725
-sonolus/script/interval.py,sha256=H-xedXbiLia-JU-Tafxq2rSoQ7pBOAeNOnyovrQyp14,9462
+sonolus/script/interval.py,sha256=IYNgJx0ngREnEVu_yMAu0MrA_Q7mZuToT8U3fbdb3Sc,9122
 sonolus/script/iterator.py,sha256=OHnIOKRchzVCMaN33Tubo6EzqV61ZYUxDWIJ2S5G6iQ,4590
 sonolus/script/level.py,sha256=wR23xk-NOcW_JMRb3R12sqIXCLSZL-7cM3y7IpMF1J0,6333
 sonolus/script/metadata.py,sha256=ttRK27eojHf3So50KQJ-8yj3udZoN1bli5iD-knaeLw,753
-sonolus/script/num.py,sha256=5PmfugfKtQ8Mobt9Ul_agv4XyqZr_EtNNPYMQcL14xQ,14178
-sonolus/script/options.py,sha256=AljmjEyWH_Aquv_Jj-sx3GA3l5ZoOSl9acDv19FMHNA,7576
+sonolus/script/num.py,sha256=FpMi-w_rdkozZSFxraNQ4IkOzQpTr4YAH3hbqMIFYy8,14612
+sonolus/script/options.py,sha256=ZD9I898wMrpPQ8IyuDoYef804rZzhSvPoC_0bxovIec,8245
 sonolus/script/particle.py,sha256=K06ArT9tstRNdbuGIviDmDDWcK3-ieA53LHg0Xvizow,8304
-sonolus/script/pointer.py,sha256=Rlu3fW4odvJzZRFNwk6pGA8JLrp4J-PlONBOg3mSA8A,1203
+sonolus/script/pointer.py,sha256=IH2_a0XE76uG_UyYM9jAYIf7qZ5LhUNc9ksXDIvAPZA,1511
 sonolus/script/printing.py,sha256=mNYu9QWiacBBGZrnePZQMVwbbguoelUps9GiOK_aVRU,2096
 sonolus/script/project.py,sha256=jLndgGJHdkqFYe-lDl_IzTjQ4gOSuy80en8WoSWXnB8,3340
-sonolus/script/quad.py,sha256=e2kXKSp9K46Q9qstLsGLFPxaW7Z2kfVfignA8Ka2-Pw,8375
-sonolus/script/record.py,sha256=jHt2RjDD7FZ_eWAukEOZePu9VJaH-rwRqHdoEJpxCNY,11339
-sonolus/script/runtime.py,sha256=xmf4HLShrcAqQ8qK3N-hGyVzEolgp34j_JSJH9orwIY,19930
+sonolus/script/quad.py,sha256=7uhBwRSvA4tZ_JFjc3Y9n8C9AwQirX5E8MAA0QaHCak,10067
+sonolus/script/record.py,sha256=EV4wywagBl3RU40Bqo9DRdx7Ta8xBgwKtgKlDF02X0o,11332
+sonolus/script/runtime.py,sha256=MIGqDqNitlI6vFtZ2SP32D6LCLJ3RAuGKSxKKl-1tJw,20303
 sonolus/script/sprite.py,sha256=CMcRAZ2hejXnaBmY2_n1_rj6hGOgPP5zEW-BpyaEVOY,16256
-sonolus/script/text.py,sha256=IsoINZJXefjReYDjJFwVaFsUCdgeQvPBDeywljM2dWo,13025
+sonolus/script/text.py,sha256=wxujIgKYcCfl2AD2_Im8g3vh0lDEHYwTSRZg9wsBPEU,13402
 sonolus/script/timing.py,sha256=ZR0ypV2PIoDCMHHGOMfCeezStCsBQdzomdqaz5VKex0,2981
 sonolus/script/transform.py,sha256=hH6KSRQC8vV-Z10CRCrGewMYqQwUMH3mQIEmniuC2Zw,10760
-sonolus/script/ui.py,sha256=R5J1QSvul-cFCUCjuEHbnzp4-CA2I8u608_wfJRr80s,7277
-sonolus/script/values.py,sha256=GWl_gmNzwEBwm5fqj2LErfwOz8iWTJEAoFyOUnkBRS0,1028
+sonolus/script/ui.py,sha256=DYPGWIjHj1IFPxW1zaEuIUQx0b32FJPXtiwCvrtJ6oo,7528
+sonolus/script/values.py,sha256=bwh_9ikxuKyrO_m3_lTKIvZDze4j88Fz-_HT_jB657g,1032
 sonolus/script/vec.py,sha256=4ntfJ96zxKR-nVZluUgHd-Ud4vNfButfiv7EsroZxfE,7002
 sonolus/script/internal/__init__.py,sha256=T6rzLoiOUaiSQtaHMZ88SNO-ijSjSSv33TKtUwu-Ms8,136
 sonolus/script/internal/builtin_impls.py,sha256=w9QqxJQ2YR5pVy820qWmAy0utbsW4hcSzMvA_yNgsvg,8186
 sonolus/script/internal/callbacks.py,sha256=vWzJG8uiJoEtsNnbeZPqOHogCwoLpz2D1MnHY2wVV8s,2801
-sonolus/script/internal/constant.py,sha256=4kJpLek7PcdB0aTL8ygV4GYDZSDuHoWHljaIZpTtRrY,3842
+sonolus/script/internal/constant.py,sha256=XljC1bXpjmQsekFFDNbaCLoHLPXzDeE17QDHf-rY70Q,3835
 sonolus/script/internal/context.py,sha256=xW7yFWr13yf77Uk4C_F7v9Kp4ZP1o30uZuBkvK1KyLA,14157
 sonolus/script/internal/descriptor.py,sha256=XRFey-EjiAm_--KsNl-8N0Mi_iyQwlPh68gDp0pKf3E,392
 sonolus/script/internal/dict_impl.py,sha256=alu_wKGSk1kZajNf64qbe7t71shEzD4N5xNIATH8Swo,1885
@@ -80,11 +80,11 @@ sonolus/script/internal/math_impls.py,sha256=Xk7tLMnV2npzPJWtHlspONQHt09Gh2YLdHh
 sonolus/script/internal/native.py,sha256=XKlNnWSJ-lxbwVGWhGj_CSSoWsVN18imqT5sAsDJT1w,1551
 sonolus/script/internal/random.py,sha256=6Ku5edRcDUh7rtqEEYCJz0BQavw69RALsVHS25z50pI,1695
 sonolus/script/internal/range.py,sha256=lrTanQFHU7RuQxSSPwDdoC30Y8FnHGxcP1Ahditu3zU,2297
-sonolus/script/internal/transient.py,sha256=c_Jg4yJJ_xvxMGNx9XECHCdiDlMhjfClf5ntzrPr6uc,1643
+sonolus/script/internal/transient.py,sha256=d6iYhM9f6DPUX5nkYQGm-x0b9XEfZUmB4AtUNnyhixo,1636
 sonolus/script/internal/tuple_impl.py,sha256=vjXmScLVdeTkDn3t9fgIRqtW31iwngnaP2rmA6nlsLw,3431
-sonolus/script/internal/value.py,sha256=hEq0YhXMj4uaGQA-r_W8PDOp_MY97nW30JKlpj-aZLM,4496
-sonolus_py-0.2.0.dist-info/METADATA,sha256=LOjlu1hCu6r3VgzL7DbplSaBsjabZ2GWzsDsilNdSFc,238
-sonolus_py-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sonolus_py-0.2.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
-sonolus_py-0.2.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
-sonolus_py-0.2.0.dist-info/RECORD,,
+sonolus/script/internal/value.py,sha256=St7OqBX-Tad_qBfu6aWMFU4lDXRyFnvzzkb-yFmOzg0,5042
+sonolus_py-0.2.1.dist-info/METADATA,sha256=OZkz271-5AHDS0iRKllUD5f3Wb5FL9s7BQghhIhI6Nw,302
+sonolus_py-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sonolus_py-0.2.1.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
+sonolus_py-0.2.1.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
+sonolus_py-0.2.1.dist-info/RECORD,,