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

sonolus/script/archetype.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+from abc import abstractmethod
 from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum, StrEnum
@@ -177,6 +178,23 @@ def imported(*, name: str | None = None) -> Any:
     return _ArchetypeFieldInfo(name, _StorageType.IMPORTED)
 
 
+def entity_data() -> Any:
+    """Declare a field as entity data.
+
+    Entity data is accessible from other entities, but may only be updated in the `preprocess` callback
+    and is read-only in other callbacks.
+
+    It functions like `imported`, except that it is not loaded from the level data.
+
+    Usage:
+        ```
+        class MyArchetype(PlayArchetype):
+            field: int = entity_data()
+        ```
+    """
+    return _ArchetypeFieldInfo(None, _StorageType.IMPORTED)
+
+
 def exported(*, name: str | None = None) -> Any:
     """Declare a field as exported.
 
@@ -418,7 +436,11 @@ class _BaseArchetype:
         bound.apply_defaults()
         data = []
         for field in cls._memory_fields_.values():
-            data.extend(field.type._accept_(bound.arguments[field.name] or zeros(field.type))._to_list_())
+            data.extend(
+                field.type._accept_(
+                    bound.arguments[field.name] if field.name in bound.arguments else zeros(field.type)
+                )._to_list_()
+            )
         native_call(Op.Spawn, archetype_id, *(Num(x) for x in data))
 
     @classmethod
@@ -446,9 +468,7 @@ class _BaseArchetype:
                 raise TypeError("Cannot directly subclass Archetype, use the Archetype subclass for your mode")
             cls._default_callbacks_ = {getattr(cls, cb_info.py_name) for cb_info in cls._supported_callbacks_.values()}
             return
-        if getattr(cls, "_callbacks_", None) is not None:
-            raise TypeError("Cannot subclass Archetypes")
-        if cls.name is None:
+        if cls.name is None or cls.name in {getattr(mro_entry, "name", None) for mro_entry in cls.mro()[1:]}:
             cls.name = cls.__name__
         cls._callbacks_ = []
         for name in cls._supported_callbacks_:
@@ -463,17 +483,32 @@ class _BaseArchetype:
         if cls._field_init_done:
             return
         cls._field_init_done = True
+        for mro_entry in cls.mro()[1:]:
+            if hasattr(mro_entry, "_field_init_done"):
+                mro_entry._init_fields()
         field_specifiers = get_field_specifiers(
             cls, skip={"name", "is_scored", "_callbacks_", "_field_init_done"}
         ).items()
-        cls._imported_fields_ = {}
-        cls._exported_fields_ = {}
-        cls._memory_fields_ = {}
-        cls._shared_memory_fields_ = {}
-        imported_offset = 0
-        exported_offset = 0
-        memory_offset = 0
-        shared_memory_offset = 0
+        if not hasattr(cls, "_imported_fields_"):
+            cls._imported_fields_ = {}
+        else:
+            cls._imported_fields_ = {**cls._imported_fields_}
+        if not hasattr(cls, "_exported_fields_"):
+            cls._exported_fields_ = {}
+        else:
+            cls._exported_fields_ = {**cls._exported_fields_}
+        if not hasattr(cls, "_memory_fields_"):
+            cls._memory_fields_ = {}
+        else:
+            cls._memory_fields_ = {**cls._memory_fields_}
+        if not hasattr(cls, "_shared_memory_fields_"):
+            cls._shared_memory_fields_ = {}
+        else:
+            cls._shared_memory_fields_ = {**cls._shared_memory_fields_}
+        imported_offset = sum(field.type._size_() for field in cls._imported_fields_.values())
+        exported_offset = sum(field.type._size_() for field in cls._exported_fields_.values())
+        memory_offset = sum(field.type._size_() for field in cls._memory_fields_.values())
+        shared_memory_offset = sum(field.type._size_() for field in cls._shared_memory_fields_.values())
         for name, value in field_specifiers:
             if value is ClassVar or get_origin(value) is ClassVar:
                 continue
@@ -504,24 +539,32 @@ class _BaseArchetype:
                         name, field_info.name or name, field_info.storage, imported_offset, field_type
                     )
                     imported_offset += field_type._size_()
+                    if imported_offset > _ENTITY_DATA_SIZE:
+                        raise ValueError("Imported fields exceed entity data size")
                     setattr(cls, name, cls._imported_fields_[name])
                 case _StorageType.EXPORTED:
                     cls._exported_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, exported_offset, field_type
                     )
                     exported_offset += field_type._size_()
+                    if exported_offset > _ENTITY_DATA_SIZE:
+                        raise ValueError("Exported fields exceed entity data size")
                     setattr(cls, name, cls._exported_fields_[name])
                 case _StorageType.MEMORY:
                     cls._memory_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, memory_offset, field_type
                     )
                     memory_offset += field_type._size_()
+                    if memory_offset > _ENTITY_MEMORY_SIZE:
+                        raise ValueError("Memory fields exceed entity memory size")
                     setattr(cls, name, cls._memory_fields_[name])
                 case _StorageType.SHARED:
                     cls._shared_memory_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, shared_memory_offset, field_type
                     )
                     shared_memory_offset += field_type._size_()
+                    if shared_memory_offset > _ENTITY_SHARED_MEMORY_SIZE:
+                        raise ValueError("Shared memory fields exceed entity shared memory size")
                     setattr(cls, name, cls._shared_memory_fields_[name])
         cls._imported_keys_ = {
             name: i
@@ -542,6 +585,30 @@ class _BaseArchetype:
             [inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in cls._memory_fields_]
         )
 
+    @property
+    @abstractmethod
+    def index(self) -> int:
+        """The index of this entity."""
+        raise NotImplementedError
+
+    @meta_fn
+    def ref(self) -> EntityRef[Self]:
+        """Get a reference to this entity.
+
+        Valid both in level data and in callbacks.
+        """
+        match self._data_:
+            case _ArchetypeSelfData():
+                return EntityRef[type(self)](index=self.index)
+            case _ArchetypeReferenceData(index=index):
+                return EntityRef[type(self)](index=index)
+            case _ArchetypeLevelData():
+                result = EntityRef[type(self)](index=-1)
+                result._ref_ = self
+                return result
+            case _:
+                raise RuntimeError("Invalid entity data")
+
 
 class PlayArchetype(_BaseArchetype):
     """Base class for play mode archetypes.
@@ -682,6 +749,7 @@ class PlayArchetype(_BaseArchetype):
         return self._info.state == 2
 
     @property
+    @meta_fn
     def life(self) -> ArchetypeLife:
         """How this entity contributes to life."""
         if not ctx():
@@ -693,6 +761,7 @@ class PlayArchetype(_BaseArchetype):
                 raise RuntimeError("Life is not available in level data")
 
     @property
+    @meta_fn
     def result(self) -> PlayEntityInput:
         """The result of this entity.
 
@@ -706,17 +775,6 @@ class PlayArchetype(_BaseArchetype):
             case _:
                 raise RuntimeError("Result is only accessible from the entity itself")
 
-    def ref(self):
-        """Get a reference to this entity for creating level data.
-
-        Not valid elsewhere.
-        """
-        if not isinstance(self._data_, _ArchetypeLevelData):
-            raise RuntimeError("Entity is not level data")
-        result = EntityRef[type(self)](index=-1)
-        result._ref_ = self
-        return result
-
 
 class WatchArchetype(_BaseArchetype):
     """Base class for watch mode archetypes.
@@ -801,6 +859,7 @@ class WatchArchetype(_BaseArchetype):
         return self._info.state == 1
 
     @property
+    @meta_fn
     def life(self) -> ArchetypeLife:
         """How this entity contributes to life."""
         if not ctx():
@@ -812,6 +871,7 @@ class WatchArchetype(_BaseArchetype):
                 raise RuntimeError("Life is not available in level data")
 
     @property
+    @meta_fn
     def result(self) -> WatchEntityInput:
         """The result of this entity.
 
@@ -857,6 +917,7 @@ class PreviewArchetype(_BaseArchetype):
         """
 
     @property
+    @meta_fn
     def _info(self) -> PreviewEntityInfo:
         if not ctx():
             raise RuntimeError("Calling info is only allowed within a callback")
@@ -974,21 +1035,35 @@ class WatchEntityInput(Record):
 
 
 class EntityRef[A: _BaseArchetype](Record):
-    """Reference to another entity."""
+    """Reference to another entity.
+
+    May be used with `Any` to reference an unknown archetype.
+
+    Usage:
+        ```
+        class MyArchetype(PlayArchetype):
+            ref_1: EntityRef[OtherArchetype] = imported()
+            ref_2: EntityRef[Any] = imported()
+        ```
+    """
 
     index: int
 
     @classmethod
     def archetype(cls) -> type[A]:
+        """Get the archetype type."""
         return cls.type_var_value(A)
 
     def with_archetype(self, archetype: type[A]) -> EntityRef[A]:
+        """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
     def get(self) -> A:
+        """Get the entity."""
         return self.archetype().at(self.index)
 
-    def is_valid(self) -> bool:
+    def archetype_matches(self) -> bool:
+        """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]:
@@ -1000,9 +1075,18 @@ class EntityRef[A: _BaseArchetype](Record):
                 raise KeyError("Reference to entity not in level data")
             return [level_refs[ref]]
 
+    def _copy_from_(self, value: Self):
+        super()._copy_from_(value)
+        if hasattr(value, "_ref_"):
+            self._ref_ = value._ref_
+
     @classmethod
     def _accepts_(cls, value: Any) -> bool:
-        return super()._accepts_(value) or (cls._type_args_ and cls.archetype() is Any and isinstance(value, EntityRef))
+        return (
+            super()._accepts_(value)
+            or (cls._type_args_ and cls.archetype() is Any and isinstance(value, EntityRef))
+            or (issubclass(type(value), EntityRef) and issubclass(value.archetype(), cls.archetype()))
+        )
 
     @classmethod
     def _accept_(cls, value: Any) -> Self:

sonolus/script/array.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Iterable
 from typing import Any, Self, final
 
+from sonolus.backend.ir import IRConst, IRSet
 from sonolus.backend.place import BlockPlace
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import assert_unreachable
@@ -159,6 +160,16 @@ class Array[T, Size](GenericValue, ArrayLike[T]):
         else:
             return cls._with_value([cls.element_type()._alloc_() for _ in range(cls.size())])
 
+    @classmethod
+    def _zero_(cls) -> Self:
+        if ctx():
+            place = ctx().alloc(size=cls._size_())
+            result: Self = cls._from_place_(place)
+            ctx().add_statements(*[IRSet(place.add_offset(i), IRConst(0)) for i in range(cls._size_())])
+            return result
+        else:
+            return cls._with_value([cls.element_type()._zero_() for _ in range(cls.size())])
+
     def __len__(self):
         return self.size()
 

sonolus/script/debug.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from contextvars import ContextVar
 from typing import Any, Never
 
@@ -75,7 +75,7 @@ def terminate():
         raise RuntimeError("Terminated")
 
 
-def visualize_cfg(fn: Callable[[], Any], passes: list[CompilerPass] | None = None) -> str:
+def visualize_cfg(fn: Callable[[], Any], passes: Sequence[CompilerPass] | None = None) -> str:
     from sonolus.build.compile import callback_to_cfg
 
     if passes is None:

sonolus/script/effect.py

@@ -25,7 +25,7 @@ class Effect(Record):
         """Return whether the effect clip is available."""
         return _has_effect_clip(self.id)
 
-    def play(self, distance: float) -> None:
+    def play(self, distance: float = 0) -> None:
         """Play the effect clip.
 
         If the clip was already played within the specified distance, it will be skipped.
@@ -35,7 +35,7 @@ class Effect(Record):
         """
         _play(self.id, distance)
 
-    def schedule(self, time: float, distance: float) -> None:
+    def schedule(self, time: float, distance: float = 0) -> None:
         """Schedule the effect clip to play at a specific time.
 
         This is not suitable for real-time effects such as responses to user input. Use `play` instead.

sonolus/script/engine.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+import json
 from collections.abc import Callable
+from os import PathLike
+from pathlib import Path
 from typing import Any
 
-from sonolus.build.collection import Asset
+from sonolus.build.collection import Asset, load_asset
 from sonolus.script.archetype import PlayArchetype, PreviewArchetype, WatchArchetype, _BaseArchetype
 from sonolus.script.bucket import Buckets, EmptyBuckets
 from sonolus.script.effect import Effects, EmptyEffects
@@ -13,12 +16,52 @@ from sonolus.script.instruction import (
     TutorialInstructionIcons,
     TutorialInstructions,
 )
+from sonolus.script.metadata import AnyText, Tag, as_localization_text
 from sonolus.script.options import EmptyOptions, Options
 from sonolus.script.particle import EmptyParticles, Particles
 from sonolus.script.sprite import EmptySkin, Skin
 from sonolus.script.ui import UiConfig
 
 
+class ExportedEngine:
+    """An exported Sonolus.py engine."""
+
+    def __init__(
+        self,
+        *,
+        item: dict,
+        thumbnail: bytes,
+        play_data: bytes,
+        watch_data: bytes,
+        preview_data: bytes,
+        tutorial_data: bytes,
+        rom: bytes | None = None,
+        configuration: bytes,
+    ) -> None:
+        self.item = item
+        self.thumbnail = thumbnail
+        self.play_data = play_data
+        self.watch_data = watch_data
+        self.preview_data = preview_data
+        self.tutorial_data = tutorial_data
+        self.rom = rom
+        self.configuration = configuration
+
+    def write_to_dir(self, path: PathLike):
+        """Write the exported engine to a directory."""
+        path = Path(path)
+        path.mkdir(parents=True, exist_ok=True)
+        (path / "item.json").write_text(json.dumps(self.item, ensure_ascii=False), encoding="utf-8")
+        (path / "thumbnail").write_bytes(self.thumbnail)
+        (path / "playData").write_bytes(self.play_data)
+        (path / "watchData").write_bytes(self.watch_data)
+        (path / "previewData").write_bytes(self.preview_data)
+        (path / "tutorialData").write_bytes(self.tutorial_data)
+        if self.rom is not None:
+            (path / "rom").write_bytes(self.rom)
+        (path / "configuration").write_bytes(self.configuration)
+
+
 class Engine:
     """A Sonolus.py engine.
 
@@ -33,6 +76,9 @@ class Engine:
         particle: The default particle for the engine.
         thumbnail: The thumbnail for the engine.
         data: The engine's modes and configurations.
+        tags: The tags of the engine.
+        description: The description of the engine.
+        meta: Additional metadata of the engine.
     """
 
     version = 12
@@ -41,26 +87,68 @@ class Engine:
         self,
         *,
         name: str,
-        title: str | None = None,
-        subtitle: str = "Sonolus.py Engine",
-        author: str = "Unknown",
+        title: AnyText | None = None,
+        subtitle: AnyText = "Sonolus.py Engine",
+        author: AnyText = "Unknown",
         skin: str | None = None,
         background: str | None = None,
         effect: str | None = None,
         particle: str | None = None,
         thumbnail: Asset | None = None,
         data: EngineData,
+        tags: list[Tag] | None = None,
+        description: AnyText | None = None,
+        meta: Any = None,
     ) -> None:
         self.name = name
-        self.title = title or name
-        self.subtitle = subtitle
-        self.author = author
+        self.title = as_localization_text(title or name)
+        self.subtitle = as_localization_text(subtitle)
+        self.author = as_localization_text(author)
         self.skin = skin
         self.background = background
         self.effect = effect
         self.particle = particle
         self.thumbnail = thumbnail
         self.data = data
+        self.tags = tags or []
+        self.description = as_localization_text(description) if description is not None else None
+        self.meta = meta
+
+    def export(self) -> ExportedEngine:
+        """Export the engine in a sonolus-pack compatible format.
+
+        Returns:
+            An exported engine.
+        """
+        from sonolus.build.engine import package_engine
+        from sonolus.build.project import BLANK_PNG
+
+        item = {
+            "version": self.version,
+            "title": self.title,
+            "subtitle": self.subtitle,
+            "author": self.author,
+            "tags": [tag.as_dict() for tag in self.tags],
+            "skin": self.skin,
+            "background": self.background,
+            "effect": self.effect,
+            "particle": self.particle,
+        }
+        packaged = package_engine(self.data)
+        if self.description is not None:
+            item["description"] = self.description
+        if self.meta is not None:
+            item["meta"] = self.meta
+        return ExportedEngine(
+            item=item,
+            thumbnail=load_asset(self.thumbnail) if self.thumbnail is not None else BLANK_PNG,
+            play_data=packaged.play_data,
+            watch_data=packaged.watch_data,
+            preview_data=packaged.preview_data,
+            tutorial_data=packaged.tutorial_data,
+            rom=packaged.rom,
+            configuration=packaged.configuration,
+        )
 
 
 def default_callback() -> Any:
@@ -190,6 +278,30 @@ class TutorialMode:
         self.update = update
 
 
+def empty_play_mode() -> PlayMode:
+    """Create an empty play mode."""
+    return PlayMode()
+
+
+def empty_watch_mode() -> WatchMode:
+    """Create an empty watch mode."""
+    return WatchMode(update_spawn=default_callback)
+
+
+def empty_preview_mode() -> PreviewMode:
+    """Create an empty preview mode."""
+    return PreviewMode()
+
+
+def empty_tutorial_mode() -> TutorialMode:
+    """Create an empty tutorial mode."""
+    return TutorialMode(
+        preprocess=default_callback,
+        navigate=default_callback,
+        update=default_callback,
+    )
+
+
 class EngineData:
     """A Sonolus.py engine's modes and configurations.
 
@@ -214,11 +326,7 @@ class EngineData:
     ) -> None:
         self.ui = ui or UiConfig()
         self.options = options
-        self.play = play or PlayMode()
-        self.watch = watch or WatchMode(update_spawn=default_callback)
-        self.preview = preview or PreviewMode()
-        self.tutorial = tutorial or TutorialMode(
-            preprocess=default_callback,
-            navigate=default_callback,
-            update=default_callback,
-        )
+        self.play = play or empty_play_mode()
+        self.watch = watch or empty_watch_mode()
+        self.preview = preview or empty_preview_mode()
+        self.tutorial = tutorial or empty_tutorial_mode()

sonolus/script/internal/builtin_impls.py

@@ -52,9 +52,11 @@ def _enumerate(iterable, start=0):
     from sonolus.backend.visitor import compile_and_call
 
     iterable = validate_value(iterable)
-    if not hasattr(iterable, "__iter__"):
+    if isinstance(iterable, TupleImpl):
+        return TupleImpl._accept_(tuple((start + i, value) for i, value in enumerate(iterable._as_py_(), start=start)))
+    elif not hasattr(iterable, "__iter__"):
         raise TypeError(f"'{type(iterable).__name__}' object is not iterable")
-    if isinstance(iterable, ArrayLike):
+    elif isinstance(iterable, ArrayLike):
         return compile_and_call(iterable._enumerate_, start)
     else:
         iterator = compile_and_call(iterable.__iter__)
@@ -232,10 +234,27 @@ _int._type_mapping_ = Num
 _float._type_mapping_ = Num
 _bool._type_mapping_ = Num
 
+
+def _any(iterable):
+    for value in iterable:  # noqa: SIM110
+        if value:
+            return True
+    return False
+
+
+def _all(iterable):
+    for value in iterable:  # noqa: SIM110
+        if not value:
+            return False
+    return True
+
+
 # classmethod, property, staticmethod are supported as decorators, but not within functions
 
 BUILTIN_IMPLS = {
     id(abs): _abs,
+    id(all): _all,
+    id(any): _any,
     id(bool): _bool,
     id(callable): _callable,
     id(enumerate): _enumerate,

sonolus/script/internal/constant.py

@@ -107,7 +107,7 @@ class ConstantValue(Value):
     def _get_(self) -> Self:
         return self
 
-    def _set_(self, value: Any) -> Self:
+    def _set_(self, value: Any):
         if value is not self:
             raise ValueError(f"{type(self).__name__} is immutable")
 
@@ -122,6 +122,10 @@ class ConstantValue(Value):
     def _alloc_(cls) -> Self:
         return cls()
 
+    @classmethod
+    def _zero_(cls) -> Self:
+        return cls()
+
     @meta_fn
     def __eq__(self, other):
         return self is other