sonolus.py 0.2.0__tar.gz → 0.2.1__tar.gz

sonolus_py-0.2.1/.python-version

@@ -0,0 +1 @@
+3.13t

sonolus_py-0.2.1/.run/Python tests in tests.run.xml

@@ -0,0 +1,21 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Python tests in tests" type="tests" factoryName="Autodetect" nameIsGenerated="true">
+    <module name="sonolus" />
+    <option name="ENV_FILES" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHON_JIT" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="_new_additionalArguments" value="&quot;-n 32 --cov sonolus --cov tests --cov-report xml&quot;" />
+    <option name="_new_target" value="&quot;$PROJECT_DIR$/tests&quot;" />
+    <option name="_new_targetType" value="&quot;PATH&quot;" />
+    <method v="2" />
+  </configuration>
+</component>

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/PKG-INFO

@@ -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.1/README.md

@@ -0,0 +1,2 @@
+# Sonolus.py
+Sonolus engine development in Python. See [docs](https://sonolus.py.qwewqa.xyz) for more information.

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/doc_stubs/builtins.pyi

@@ -148,6 +148,9 @@ def len(s: object) -> builtins.int:
 def map[T, S](function: Callable[[T], S], iterable: Iterable[T]) -> Iterator[S]:
     """Apply a function to every item of an iterable and return an iterator.
 
+    Unlike the standard Python map function, it is possible that the function may be called more than once on the
+    same item.
+
     Args:
         function: The function to apply.
         iterable: The iterable to process.

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/docs/concepts/constructs.md

@@ -18,6 +18,8 @@ Most standard Python constructs are supported in Sonolus.py.
 
 ## Overview
 
+The following constructs are supported in Sonolus.py:  
+
 - Expressions:
     - Literals:
         - Numbers (excluding complex numbers): `0`, `1`, `1.0`, `1e3`, `0x1`, `0b1`, `0o1`
@@ -80,18 +82,20 @@ Some expressions can be evaluated at compile time:
 - Comparison: for compile time constant operands: `a == b`, `a != b`, `a > b`, `a < b`, `a >= b`, `a <= b`, ...
 - Variables assigned to compile time constants: `a = 1`, `b = a + 1`, ...
 
-The compiler can make additional inferences when compile time constants are used in certain contexts like control flow:
+Some values like array sizes must be compile-time constants.
+
+The compiler will eliminate branches known to be unreachable at compile time:
 
 ```python
-x = ...
+def f(a):
+    if isinstance(a, Num):
+        debug_log(a)
+    else:
+        debug_log(a.x + a.y)
 
-# This code works because the compiler knows which branch will be taken based on the type of 'x'
-if isinstance(x, Num):
-    debug_log(x)
-elif isinstance(x, Vec2):
-    debug_log(x.x + x.y)
-else:
-    debug_log(-1)
+# This works because `isinstance` is evaluated at compile time and only the first (if) branch is reachable.
+# The second (else) branch is eliminated, so we don't get an error that a does not have 'x' and 'y' attributes.
+f(123)
 ```
 
 ## Variables
@@ -385,7 +389,8 @@ def g(a):
 ```
 
 Function returns follow the same rules as variable access. If a function returns a non-num value, it most only
-return that value. There is no restriction of a function only returns a num.
+return that value. If the function always returns a num, it may have any number of returns. Similarly, if a function
+always returns None (`return None` or just `return`), it may have any number of returns.
 
 The following are allowed:
 
@@ -439,7 +444,7 @@ def k():
         return Vec2(1, 2)
 ```
 
-Most functions returning a non-num value should have a single `return` statement at the end.
+Outside of functions returning `None` or a num, most functions should have a single `return` statement at the end.
 
 ### Classes
 
@@ -475,8 +480,8 @@ Imports are supported at the module level, but not within functions.
 
 ### assert
 
-Assertions are supported. Since error handling is not supported, assertion failures will terminate the current
-callback when running in the Sonolus app.
+Assertions are supported. Assertion failures cannot be handled and will terminate the current
+callback when running in the Sonolus app. In debug mode, the game will also pause to indicate the error.
 
 ```python
 assert a > 0, 'a must be positive'

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/docs/concepts/resources.md

@@ -153,6 +153,7 @@ class Options:
 ```
 
 There are three types of options available:
+
 1. `slider_option`: A slider control for numeric values
 2. `toggle_option`: A toggle switch for boolean values
 3. `select_option`: A dropdown menu for selecting from predefined values
@@ -236,8 +237,8 @@ ui_config = UiConfig(
             ease=EaseType.NONE,
         ),
     ),
-    judgment_error_style=UiJudgmentErrorStyle.NONE,
-    judgment_error_placement=UiJudgmentErrorPlacement.BOTH,
+    judgment_error_style=UiJudgmentErrorStyle.LATE,
+    judgment_error_placement=UiJudgmentErrorPlacement.TOP,
     judgment_error_min=0.0,
 )
 ```

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/docs/concepts/types.md

@@ -124,7 +124,8 @@ Array  # The Generic Array type
 Array[int, 3]  # A concrete Array type
 ```
 
-The element type of an array must be concrete (not generic) and the size must be a non-negative integer:
+The element type of an array must be concrete (not generic) and the size must be a non-negative compile-time 
+constant integer:
 
 ```python
 # Ok

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/docs/index.md

@@ -14,7 +14,7 @@ Sonolus.py is available on PyPI and can be installed using a package manager lik
     ```
 
 ## Getting Started
-...
+Coming soon!
 
 ## Documentation
 See [Concepts](concepts/index.md) for an overview of usage details.

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonolus.py"
-version = "0.2.0"
+version = "0.2.1"
 description = "Sonolus engine development in Python"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -9,16 +9,7 @@ requires-python = ">=3.12"
 sonolus-py = "sonolus.build.cli:main"
 
 [tool.uv]
-dev-dependencies = [
-    "hypothesis>=6.115.3",
-    "pre-commit>=4.0.1",
-    "pytest-xdist>=3.6.1",
-    "pytest>=8.3.3",
-    "ruff>=0.6.9",
-    "pytest-cov>=6.0.0",
-    "tox>=4.23.2",
-    "tox-uv>=1.16.0",
-]
+default-groups = ["dev", "docs"]
 
 [tool.ruff]
 line-length = 120
@@ -37,6 +28,16 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [dependency-groups]
+dev = [
+    "hypothesis>=6.115.3",
+    "pre-commit>=4.0.1",
+    "pytest-xdist>=3.6.1",
+    "pytest>=8.3.3",
+    "ruff>=0.6.9",
+    "pytest-cov>=6.0.0",
+    "tox>=4.23.2",
+    "tox-uv>=1.16.0",
+]
 docs = [
     "mkdocs-material>=9.5.45",
     "mkdocs>=1.6.1",

{sonolus_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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_py-0.2.0 → sonolus_py-0.2.1}/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