sonolus.py 0.3.4__py3-none-any.whl → 0.4.1__py3-none-any.whl

sonolus/build/engine.py

@@ -6,7 +6,6 @@ from collections.abc import Callable
 from concurrent.futures import Executor
 from concurrent.futures.thread import ThreadPoolExecutor
 from dataclasses import dataclass
-from os import process_cpu_count
 from pathlib import Path
 
 from sonolus.backend.mode import Mode
@@ -74,6 +73,9 @@ def package_engine(
     rom = ReadOnlyMemory()
     configuration = build_engine_configuration(engine.options, engine.ui)
     if no_gil():
+        # process_cpu_count is available in Python 3.13+
+        from os import process_cpu_count
+
         thread_pool = ThreadPoolExecutor(process_cpu_count() or 1)
     else:
         thread_pool = None
@@ -189,6 +191,65 @@ def package_engine(
     )
 
 
+def validate_engine(
+    engine: EngineData,
+    config: BuildConfig | None = None,
+):
+    config = config or BuildConfig()
+    rom = ReadOnlyMemory()
+
+    play_mode = engine.play if config.build_play else empty_play_mode()
+    watch_mode = engine.watch if config.build_watch else empty_watch_mode()
+    preview_mode = engine.preview if config.build_preview else empty_preview_mode()
+    tutorial_mode = engine.tutorial if config.build_tutorial else empty_tutorial_mode()
+
+    build_play_mode(
+        archetypes=play_mode.archetypes,
+        skin=play_mode.skin,
+        effects=play_mode.effects,
+        particles=play_mode.particles,
+        buckets=play_mode.buckets,
+        rom=rom,
+        config=config,
+        thread_pool=None,
+        validate_only=True,
+    )
+    build_watch_mode(
+        archetypes=watch_mode.archetypes,
+        skin=watch_mode.skin,
+        effects=watch_mode.effects,
+        particles=watch_mode.particles,
+        buckets=watch_mode.buckets,
+        rom=rom,
+        update_spawn=watch_mode.update_spawn,
+        config=config,
+        thread_pool=None,
+        validate_only=True,
+    )
+    build_preview_mode(
+        archetypes=preview_mode.archetypes,
+        skin=preview_mode.skin,
+        rom=rom,
+        config=config,
+        thread_pool=None,
+        validate_only=True,
+    )
+    build_tutorial_mode(
+        skin=tutorial_mode.skin,
+        effects=tutorial_mode.effects,
+        particles=tutorial_mode.particles,
+        instructions=tutorial_mode.instructions,
+        instruction_icons=tutorial_mode.instruction_icons,
+        preprocess=tutorial_mode.preprocess,
+        navigate=tutorial_mode.navigate,
+        update=tutorial_mode.update,
+        rom=rom,
+        config=config,
+        thread_pool=None,
+        validate_only=True,
+    )
+
+
 def build_engine_configuration(
     options: Options,
     ui: UiConfig,
@@ -208,6 +269,7 @@ def build_play_mode(
     rom: ReadOnlyMemory,
     config: BuildConfig,
     thread_pool: Executor | None = None,
+    validate_only: bool = False,
 ):
     return {
         **compile_mode(
@@ -217,6 +279,7 @@ def build_play_mode(
             global_callbacks=None,
             passes=config.passes,
             thread_pool=thread_pool,
+            validate_only=validate_only,
         ),
         "skin": build_skin(skin),
         "effect": build_effects(effects),
@@ -235,6 +298,7 @@ def build_watch_mode(
     update_spawn: Callable[[], float],
     config: BuildConfig,
     thread_pool: Executor | None = None,
+    validate_only: bool = False,
 ):
     return {
         **compile_mode(
@@ -244,6 +308,7 @@ def build_watch_mode(
             global_callbacks=[(update_spawn_callback, update_spawn)],
             passes=config.passes,
             thread_pool=thread_pool,
+            validate_only=validate_only,
         ),
         "skin": build_skin(skin),
         "effect": build_effects(effects),
@@ -258,6 +323,7 @@ def build_preview_mode(
     rom: ReadOnlyMemory,
     config: BuildConfig,
     thread_pool: Executor | None = None,
+    validate_only: bool = False,
 ):
     return {
         **compile_mode(
@@ -267,6 +333,7 @@ def build_preview_mode(
             global_callbacks=None,
             passes=config.passes,
             thread_pool=thread_pool,
+            validate_only=validate_only,
         ),
         "skin": build_skin(skin),
     }
@@ -284,6 +351,7 @@ def build_tutorial_mode(
     rom: ReadOnlyMemory,
     config: BuildConfig,
     thread_pool: Executor | None = None,
+    validate_only: bool = False,
 ):
     return {
         **compile_mode(
@@ -297,6 +365,7 @@ def build_tutorial_mode(
             ],
             passes=config.passes,
             thread_pool=thread_pool,
+            validate_only=validate_only,
         ),
         "skin": build_skin(skin),
         "effect": build_effects(effects),

sonolus/build/level.py

@@ -1,16 +1,16 @@
-from sonolus.build.engine import package_output
+from sonolus.build.engine import JsonValue, package_output
 from sonolus.script.level import LevelData
 
 
 def package_level_data(
     level_data: LevelData,
-):
+) -> bytes:
     return package_output(build_level_data(level_data))
 
 
 def build_level_data(
     level_data: LevelData,
-):
+) -> JsonValue:
     level_refs = {entity: f"{i}_{entity.name}" for i, entity in enumerate(level_data.entities)}
     return {
         "bgmOffset": level_data.bgm_offset,

sonolus/build/project.py

@@ -17,7 +17,7 @@ BLANK_AUDIO = (
 )
 
 
-def build_project_to_collection(project: Project, config: BuildConfig):
+def build_project_to_collection(project: Project, config: BuildConfig | None):
     collection = load_resources_files_to_collection(project.resources)
     add_engine_to_collection(collection, project, project.engine, config)
     for level in project.levels:
@@ -26,7 +26,7 @@ def build_project_to_collection(project: Project, config: BuildConfig):
     return collection
 
 
-def add_engine_to_collection(collection: Collection, project: Project, engine: Engine, config: BuildConfig):
+def add_engine_to_collection(collection: Collection, project: Project, engine: Engine, config: BuildConfig | None):
     packaged_engine = package_engine(engine.data, config)
     item = {
         "name": engine.name,

sonolus/script/archetype.py

@@ -1,3 +1,4 @@
+# type: ignore
 from __future__ import annotations
 
 import inspect
@@ -117,7 +118,7 @@ class _ArchetypeField(SonolusDescriptor):
         if result is None:
             raise RuntimeError("Invalid storage type")
         if ctx():
-            return result._get_()
+            return result._get_readonly_()
         else:
             return result._as_py_()
 
@@ -327,7 +328,7 @@ def callback[T: Callable](*, order: int = 0) -> Callable[[T], T]:
     """
 
     def decorator(func: T) -> T:
-        func._callback_order_ = order
+        func._callback_order_ = order  # type: ignore
         return func
 
     return decorator
@@ -635,11 +636,11 @@ class _BaseArchetype:
         """
         match self._data_:
             case _ArchetypeSelfData():
-                return EntityRef[type(self)](index=self.index)
+                return EntityRef[type(self)](index=self.index)  # type: ignore
             case _ArchetypeReferenceData(index=index):
-                return EntityRef[type(self)](index=index)
+                return EntityRef[type(self)](index=index)  # type: ignore
             case _ArchetypeLevelData():
-                result = EntityRef[type(self)](index=-1)
+                result = EntityRef[type(self)](index=-1)  # type: ignore
                 result._ref_ = self
                 return result
             case _:
@@ -1016,8 +1017,8 @@ def archetype_life_of(archetype: type[_BaseArchetype] | _BaseArchetype) -> Arche
 
     Available in play and watch mode.
     """
-    archetype = validate_value(archetype)
-    archetype = archetype._as_py_()
+    archetype = validate_value(archetype)  # type: ignore
+    archetype = archetype._as_py_()  # type: ignore
     if not ctx():
         raise RuntimeError("Calling archetype_life_of is only allowed within a callback")
     match ctx().global_state.mode:
@@ -1110,7 +1111,7 @@ class EntityRef[A: _BaseArchetype](Record):
         """Get the archetype type."""
         return cls.type_var_value(A)
 
-    def with_archetype(self, archetype: type[A]) -> EntityRef[A]:
+    def with_archetype[T: _BaseArchetype](self, archetype: type[T]) -> EntityRef[T]:
         """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
@@ -1137,11 +1138,13 @@ class EntityRef[A: _BaseArchetype](Record):
         if ref is None:
             return Num._accept_(self.index)._to_list_()
         else:
+            if level_refs is None:
+                raise RuntimeError("Unexpected missing level_refs")
             if ref not in level_refs:
                 raise KeyError("Reference to entity not in level data")
             return [level_refs[ref]]
 
-    def _copy_from_(self, value: Self):
+    def _copy_from_(self, value: Any):
         super()._copy_from_(value)
         if hasattr(value, "_ref_"):
             self._ref_ = value._ref_

sonolus/script/array.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+from abc import ABCMeta
 from collections.abc import Iterable
-from typing import Any, Self, final
+from typing import Any, Literal, Self, final
 
 from sonolus.backend.ir import IRConst, IRSet
 from sonolus.backend.place import BlockPlace
@@ -14,8 +15,11 @@ from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.value import BackingSource, DataValue, Value
 from sonolus.script.num import Num
 
+Dim = Literal
+"""Shorthand for `Literal` intended for use in array dimensions for type checker compatibility."""
 
-class ArrayMeta(type):
+
+class ArrayMeta(ABCMeta):
     @meta_fn
     def __pos__[T](cls: type[T]) -> T:
         """Create a zero-initialized array instance."""
@@ -31,7 +35,8 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         array_1 = Array(1, 2, 3)
         array_2 = Array[int, 0]()
         array_3 = +Array[int, 3]  # Create a zero-initialized array
-        array_4 = +array_1  # Create a copy of array_1
+        array_4 = +Array[int, Dim[3]]  # Alternative syntax for compliance with type checkers
+        array_5 = +array_1  # Create a copy of array_1
         ```
     """
 
@@ -78,7 +83,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         super().__init__()
 
     @classmethod
-    def _with_value(cls, value) -> Self:
+    def _with_value(cls, value) -> Array[T, Size]:
         result = object.__new__(cls)
         result._value = value
         return result
@@ -92,11 +97,11 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return False
 
     @classmethod
-    def _from_backing_source_(cls, source: BackingSource) -> Self:
+    def _from_backing_source_(cls, source: BackingSource) -> Array[T, Size]:
         return cls._with_value(source)
 
     @classmethod
-    def _from_place_(cls, place: BlockPlace) -> Self:
+    def _from_place_(cls, place: BlockPlace) -> Array[T, Size]:
         return cls._with_value(place)
 
     @classmethod
@@ -104,7 +109,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return isinstance(value, cls)
 
     @classmethod
-    def _accept_(cls, value: Any) -> Self:
+    def _accept_(cls, value: Any) -> Array[T, Size]:
         if not cls._accepts_(value):
             raise TypeError(f"Cannot accept value {value} as {cls.__name__}")
         return value
@@ -118,7 +123,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return self
 
     @classmethod
-    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Array[T, Size]:
         iterator = iter(values)
         return cls(*(cls.element_type()._from_list_(iterator) for _ in range(cls.size())))
 
@@ -143,19 +148,19 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
     def _flat_keys_(cls, prefix: str) -> list[str]:
         return [entry for i in range(cls.size()) for entry in cls.element_type()._flat_keys_(f"{prefix}[{i}]")]
 
-    def _get_(self) -> Self:
+    def _get_(self) -> Array[T, Size]:
         return self
 
-    def _set_(self, value: Self):
+    def _set_(self, value: Any):
         raise TypeError("Array does not support _set_")
 
-    def _copy_from_(self, value: Self):
+    def _copy_from_(self, value: Any):
         if not isinstance(value, type(self)):
             raise TypeError("Cannot copy from different type")
         for i in range(self.size()):
             self[i] = value[i]
 
-    def _copy_(self) -> Self:
+    def _copy_(self) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=self._size_())
             result: Self = self._from_place_(place)
@@ -166,7 +171,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return self._with_value([value._copy_() for value in self._value])
 
     @classmethod
-    def _alloc_(cls) -> Self:
+    def _alloc_(cls) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=cls._size_())
             return cls._from_place_(place)
@@ -174,7 +179,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return cls._with_value([cls.element_type()._alloc_() for _ in range(cls.size())])
 
     @classmethod
-    def _zero_(cls) -> Self:
+    def _zero_(cls) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=cls._size_())
             result: Self = cls._from_place_(place)
@@ -207,7 +212,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
                 )
             elif callable(self._value):
                 return self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + Num(const_index * self.element_type()._size_())).ir())
+                    lambda offset: self._value((Num(offset) + Num(const_index * self.element_type()._size_())).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
@@ -225,7 +230,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             elif callable(self._value):
                 base_offset = index * Num(self.element_type()._size_())
                 return self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + base_offset).ir())
+                    lambda offset: self._value((Num(offset) + base_offset).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
@@ -252,7 +257,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             elif callable(self._value):
                 base_offset = index * Num(self.element_type()._size_())
                 dst = self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + base_offset).ir())
+                    lambda offset: self._value((Num(offset) + base_offset).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
@@ -306,6 +311,6 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return f"{type(self).__name__}({', '.join(repr(self[i]) for i in range(self.size()))})"
 
     @meta_fn
-    def __pos__(self) -> Self:
+    def __pos__(self) -> Array[T, Size]:
         """Return a copy of the array."""
         return self._copy_()

sonolus/script/array_like.py

@@ -2,12 +2,13 @@ from __future__ import annotations
 
 import random
 from abc import abstractmethod
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from typing import Any
 
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn
 from sonolus.script.iterator import SonolusIterator
+from sonolus.script.maybe import Maybe, Nothing, Some
 from sonolus.script.num import Num
 from sonolus.script.record import Record
 from sonolus.script.values import copy
@@ -15,7 +16,7 @@ from sonolus.script.values import copy
 # Note: we don't use Range in this file because Range itself inherits from ArrayLike
 
 
-class ArrayLike[T]:
+class ArrayLike[T](Sequence):
     """Mixin for array-like objects.
 
     Inheritors must implement `__len__`, `__getitem__`, and `__setitem__`.
@@ -134,11 +135,11 @@ class ArrayLike[T]:
         if len(self) == 0:
             return -1
         if key is None:
-            key = _identity
+            key = _identity  # type: ignore
         max_index = 0
         i = 1
         while i < len(self):
-            if key(self[i]) > key(self[max_index]):
+            if key(self[i]) > key(self[max_index]):  # type: ignore
                 max_index = i
             i += 1
         return max_index
@@ -152,11 +153,11 @@ class ArrayLike[T]:
         if len(self) == 0:
             return -1
         if key is None:
-            key = _identity
+            key = _identity  # type: ignore
         min_index = 0
         i = 1
         while i < len(self):
-            if key(self[i]) < key(self[min_index]):
+            if key(self[i]) < key(self[min_index]):  # type: ignore
                 min_index = i
             i += 1
         return min_index
@@ -191,12 +192,12 @@ class ArrayLike[T]:
         """
         if len(self) < 15 or key is not None:
             if key is None:
-                key = _identity
+                key = _identity  # type: ignore
             # May be worth adding a block sort variant for better performance on large arrays in the future
-            _insertion_sort(self, 0, len(self), key, reverse)
+            _insertion_sort(self, 0, len(self), key, reverse)  # type: ignore
         else:
             # Heap sort is unstable, so if there's a key, we can't rely on it
-            _heap_sort(self, 0, len(self), reverse)
+            _heap_sort(self, 0, len(self), reverse)  # type: ignore
 
     def shuffle(self):
         """Shuffle the values in the array in place."""
@@ -221,14 +222,14 @@ def _insertion_sort[T](array: ArrayLike[T], start: int, end: int, key: Callable[
     if reverse:
         while i < end:
             j = i
-            while j > start and key(array[j - 1]) < key(array[j]):
+            while j > start and key(array[j - 1]) < key(array[j]):  # type: ignore
                 array.swap(j - 1, j)
                 j -= 1
             i += 1
     else:
         while i < end:
             j = i
-            while j > start and key(array[j - 1]) > key(array[j]):
+            while j > start and key(array[j - 1]) > key(array[j]):  # type: ignore
                 array.swap(j - 1, j)
                 j -= 1
             i += 1
@@ -239,9 +240,9 @@ def _heapify[T](array: ArrayLike[T], end: int, index: int, reverse: bool):
         left = index * 2 + 1
         right = left + 1
         largest = index
-        if left < end and (array[left] > array[largest]) != reverse:
+        if left < end and (array[left] > array[largest]) != reverse:  # type: ignore
             largest = left
-        if right < end and (array[right] > array[largest]) != reverse:
+        if right < end and (array[right] > array[largest]) != reverse:  # type: ignore
             largest = right
         if largest == index:
             break
@@ -265,14 +266,12 @@ class _ArrayIterator[V: ArrayLike](Record, SonolusIterator):
     i: int
     array: V
 
-    def has_next(self) -> bool:
-        return self.i < len(self.array)
-
-    def get(self) -> V:
-        return self.array[self.i]
-
-    def advance(self):
-        self.i += 1
+    def next(self) -> Maybe[V]:
+        if self.i < len(self.array):
+            value = self.array[self.i]
+            self.i += 1
+            return Some(value)
+        return Nothing
 
 
 class _ArrayReverser[V: ArrayLike](Record, ArrayLike):
@@ -296,14 +295,12 @@ class _ArrayEnumerator[V: ArrayLike](Record, SonolusIterator):
     offset: int
     array: V
 
-    def has_next(self) -> bool:
-        return self.i < len(self.array)
-
-    def get(self) -> tuple[int, Any]:
-        return self.i + self.offset, self.array[self.i]
-
-    def advance(self):
-        self.i += 1
+    def next(self) -> Maybe[tuple[int, Any]]:
+        if self.i < len(self.array):
+            result = (self.i + self.offset, self.array[self.i])
+            self.i += 1
+            return Some(result)
+        return Nothing
 
 
 @meta_fn

sonolus/script/bucket.py

@@ -220,7 +220,7 @@ def bucket(*, sprites: list[_BucketSprite], unit: str | None = None) -> Any:
     return _BucketInfo(sprites, unit)
 
 
-type Buckets = NewType("Buckets", Any)
+type Buckets = NewType("Buckets", Any)  # type: ignore
 
 
 @dataclass_transform()

sonolus/script/containers.py

@@ -8,6 +8,7 @@ from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn
 from sonolus.script.interval import clamp
 from sonolus.script.iterator import SonolusIterator
+from sonolus.script.maybe import Maybe, Nothing, Some
 from sonolus.script.num import Num
 from sonolus.script.pointer import _deref
 from sonolus.script.record import Record
@@ -335,7 +336,8 @@ class ArrayPointer[T](Record, ArrayLike[T]):
         if not ctx():
             raise TypeError("ArrayPointer values cannot be accessed outside of a context")
         return _deref(
-            self.block,
+            # Allows a compile time constant block so we can warn based on callback read/write access
+            (self._value_["block"]._is_py_() and self._value_["block"]._as_py_()) or self.block,
             self.offset + Num._accept_(item) * Num._accept_(self.element_type()._size_()),
             self.element_type(),
         )
@@ -600,40 +602,34 @@ class _ArrayMapKeyIterator[K, V, Capacity](Record, SonolusIterator):
     _map: ArrayMap[K, V, Capacity]
     _index: int
 
-    def has_next(self) -> bool:
-        return self._index < len(self._map)
-
-    def get(self) -> K:
-        return self._map._array[self._index].key
-
-    def advance(self):
-        self._index += 1
+    def next(self) -> Maybe[K]:
+        if self._index < len(self._map):
+            key = self._map._array[self._index].key
+            self._index += 1
+            return Some(key)
+        return Nothing
 
 
 class _ArrayMapValueIterator[K, V, Capacity](Record, SonolusIterator):
     _map: ArrayMap[K, V, Capacity]
     _index: int
 
-    def has_next(self) -> bool:
-        return self._index < len(self._map)
-
-    def get(self) -> V:
-        return self._map._array[self._index].value
-
-    def advance(self):
-        self._index += 1
+    def next(self) -> Maybe[V]:
+        if self._index < len(self._map):
+            value = self._map._array[self._index].value
+            self._index += 1
+            return Some(value)
+        return Nothing
 
 
 class _ArrayMapEntryIterator[K, V, Capacity](Record, SonolusIterator):
     _map: ArrayMap[K, V, Capacity]
     _index: int
 
-    def has_next(self) -> bool:
-        return self._index < len(self._map)
-
-    def get(self) -> tuple[K, V]:
-        entry = self._map._array[self._index]
-        return entry.key, entry.value
-
-    def advance(self):
-        self._index += 1
+    def next(self) -> Maybe[tuple[K, V]]:
+        if self._index < len(self._map):
+            entry = self._map._array[self._index]
+            result = (entry.key, entry.value)
+            self._index += 1
+            return Some(result)
+        return Nothing