sonolus.py 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

sonolus/backend/finalize.py

@@ -1,7 +1,7 @@
 from math import isfinite, isinf, isnan
 
 from sonolus.backend.ir import IRConst, IRGet, IRInstr, IRPureInstr, IRSet
-from sonolus.backend.node import ConstantNode, EngineNode, FunctionNode
+from sonolus.backend.node import EngineNode, FunctionNode
 from sonolus.backend.ops import Op
 from sonolus.backend.optimize.flow import BasicBlock, traverse_cfg_reverse_postorder
 from sonolus.backend.place import BlockPlace
@@ -18,18 +18,18 @@ def cfg_to_engine_node(entry: BasicBlock):
         }
         match outgoing:
             case {**other} if not other:
-                statements.append(ConstantNode(value=len(block_indexes)))
+                statements.append(len(block_indexes))
             case {None: target, **other} if not other:
-                statements.append(ConstantNode(value=block_indexes[target]))
+                statements.append(block_indexes[target])
             case {0: f_branch, None: t_branch, **other} if not other:
                 statements.append(
                     FunctionNode(
                         func=Op.If,
-                        args=[
+                        args=(
                             ir_to_engine_node(block.test),
-                            ConstantNode(value=block_indexes[t_branch]),
-                            ConstantNode(value=block_indexes[f_branch]),
-                        ],
+                            block_indexes[t_branch],
+                            block_indexes[f_branch],
+                        ),
                     )
                 )
             case {None: default_branch, **other} if len(other) == 1:
@@ -37,11 +37,11 @@ def cfg_to_engine_node(entry: BasicBlock):
                 statements.append(
                     FunctionNode(
                         func=Op.If,
-                        args=[
+                        args=(
                             ir_to_engine_node(IRPureInstr(Op.Equal, args=[block.test, IRConst(cond)])),
-                            ConstantNode(value=block_indexes[cond_branch]),
-                            ConstantNode(value=block_indexes[default_branch]),
-                        ],
+                            block_indexes[cond_branch],
+                            block_indexes[default_branch],
+                        ),
                     )
                 )
             case dict() as targets:
@@ -49,23 +49,23 @@ def cfg_to_engine_node(entry: BasicBlock):
                 default = len(block_indexes)
                 conds = [cond for cond in targets if cond is not None]
                 if min(conds) == 0 and max(conds) == len(conds) - 1 and all(int(cond) == cond for cond in conds):
-                    args.extend(ConstantNode(value=block_indexes[targets[cond]]) for cond in range(len(conds)))
+                    args.extend(block_indexes[targets[cond]] for cond in range(len(conds)))
                     if None in targets:
                         default = block_indexes[targets[None]]
-                    args.append(ConstantNode(value=default))
-                    statements.append(FunctionNode(Op.SwitchIntegerWithDefault, args))
+                    args.append(default)
+                    statements.append(FunctionNode(Op.SwitchIntegerWithDefault, tuple(args)))
                 else:
                     for cond, target in targets.items():
                         if cond is None:
                             default = block_indexes[target]
                             continue
-                        args.append(ConstantNode(value=cond))
-                        args.append(ConstantNode(value=block_indexes[target]))
-                    args.append(ConstantNode(value=default))
-                    statements.append(FunctionNode(Op.SwitchWithDefault, args))
-        block_statements.append(FunctionNode(Op.Execute, statements))
-    block_statements.append(ConstantNode(value=0))
-    result = FunctionNode(Op.Block, [FunctionNode(Op.JumpLoop, block_statements)])
+                        args.append(cond)
+                        args.append(block_indexes[target])
+                    args.append(default)
+                    statements.append(FunctionNode(Op.SwitchWithDefault, tuple(args)))
+        block_statements.append(FunctionNode(Op.Execute, tuple(statements)))
+    block_statements.append(0)
+    result = FunctionNode(Op.Block, (FunctionNode(Op.JumpLoop, tuple(block_statements)),))
     for block in block_indexes:
         # Clean up without relying on gc
         del block.incoming
@@ -81,32 +81,30 @@ def ir_to_engine_node(stmt) -> EngineNode:
         case int(value) | float(value) | IRConst(value=int(value) | float(value)):
             value = float(value)
             if value.is_integer():
-                return ConstantNode(value=int(value))
+                return int(value)
             elif isfinite(value):
-                return ConstantNode(value=value)
+                return value
             elif isinf(value):
                 # Read values from ROM
-                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=1 if value > 0 else 2)])
+                return FunctionNode(Op.Get, args=(3000, 1 if value > 0 else 2))
             elif isnan(value):
                 # Read value from ROM
-                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=0)])
+                return FunctionNode(Op.Get, args=(3000, 0))
             else:
                 raise ValueError(f"Invalid constant value: {value}")
         case IRPureInstr(op=op, args=args) | IRInstr(op=op, args=args):
-            return FunctionNode(func=op, args=[ir_to_engine_node(arg) for arg in args])
+            return FunctionNode(func=op, args=tuple(ir_to_engine_node(arg) for arg in args))
         case IRGet(place=place):
             return ir_to_engine_node(place)
         case BlockPlace() as place:
             if place.offset == 0:
                 index = ir_to_engine_node(place.index)
             elif place.index == 0:
-                index = ConstantNode(value=place.offset)
+                index = place.offset
             else:
-                index = FunctionNode(
-                    func=Op.Add, args=[ir_to_engine_node(place.index), ConstantNode(value=place.offset)]
-                )
-            return FunctionNode(func=Op.Get, args=[ir_to_engine_node(place.block), index])
+                index = FunctionNode(func=Op.Add, args=(ir_to_engine_node(place.index), place.offset))
+            return FunctionNode(func=Op.Get, args=(ir_to_engine_node(place.block), index))
         case IRSet(place=place, value=value):
-            return FunctionNode(func=Op.Set, args=[*ir_to_engine_node(place).args, ir_to_engine_node(value)])
+            return FunctionNode(func=Op.Set, args=(*ir_to_engine_node(place).args, ir_to_engine_node(value)))
         case _:
             raise TypeError(f"Unsupported IR statement: {stmt}")

sonolus/backend/interpret.py

@@ -2,7 +2,7 @@ import math
 import operator
 import random
 
-from sonolus.backend.node import ConstantNode, EngineNode
+from sonolus.backend.node import EngineNode, FunctionNode
 from sonolus.backend.ops import Op
 
 
@@ -24,8 +24,8 @@ class Interpreter:
         self.log = []
 
     def run(self, node: EngineNode) -> float:
-        if isinstance(node, ConstantNode):
-            return node.value
+        if not isinstance(node, FunctionNode):
+            return node
         func = node.func
         args = node.args
         match func:

sonolus/backend/node.py

@@ -1,40 +1,18 @@
 import textwrap
-from dataclasses import dataclass, field
+from typing import NamedTuple
 
 from sonolus.backend.ops import Op
 
-type EngineNode = ConstantNode | FunctionNode
+type EngineNode = int | float | FunctionNode
 
 
-@dataclass(slots=True)
-class ConstantNode:
-    value: float
-    _hash: int = field(init=False, repr=False)
-
-    def __post_init__(self):
-        self._hash = hash(self.value)
-
-    def __hash__(self):
-        return hash(self.value)
-
-
-@dataclass(slots=True)
-class FunctionNode:
+class FunctionNode(NamedTuple):
     func: Op
-    args: list[EngineNode]
-    _hash: int = field(init=False, repr=False)
-
-    def __post_init__(self):
-        self._hash = hash((self.func, tuple(self.args)))
-
-    def __hash__(self):
-        return self._hash
+    args: tuple[EngineNode, ...]
 
 
 def format_engine_node(node: EngineNode) -> str:
-    if isinstance(node, ConstantNode):
-        return str(node.value)
-    elif isinstance(node, FunctionNode):
+    if isinstance(node, FunctionNode):
         match len(node.args):
             case 0:
                 return f"{node.func.name}()"
@@ -45,4 +23,4 @@ def format_engine_node(node: EngineNode) -> str:
                     textwrap.indent('\n'.join(format_engine_node(arg) for arg in node.args), '  ')
                 }\n)"
     else:
-        raise ValueError(f"Invalid engine node: {node}")
+        return str(node)

sonolus/build/compile.py

@@ -32,9 +32,11 @@ class CompileCache:
         self._cache = {}
         self._lock = Lock()
         self._event = Event()
+        self._accessed_hashes = set()
 
     def get(self, entry_hash: int) -> EngineNode | None:
         with self._lock:
+            self._accessed_hashes.add(entry_hash)
             if entry_hash not in self._cache:
                 self._cache[entry_hash] = None  # Mark as being compiled
                 return None
@@ -47,10 +49,21 @@ class CompileCache:
 
     def set(self, entry_hash: int, node: EngineNode) -> None:
         with self._lock:
+            self._accessed_hashes.add(entry_hash)
             self._cache[entry_hash] = node
             self._event.set()
             self._event.clear()
 
+    def reset_accessed(self) -> None:
+        with self._lock:
+            self._accessed_hashes.clear()
+
+    def prune_unaccessed(self) -> None:
+        with self._lock:
+            unaccessed_hashes = set(self._cache.keys()) - self._accessed_hashes
+            for h in unaccessed_hashes:
+                del self._cache[h]
+
 
 def compile_mode(
     mode: Mode,
@@ -67,7 +80,7 @@ def compile_mode(
 
     mode_state = ModeContextState(
         mode,
-        {a: i for i, a in enumerate(archetypes)} if archetypes is not None else None,
+        archetypes,
     )
     nodes = OutputNodeGenerator()
     results = {}
@@ -134,9 +147,10 @@ def compile_mode(
                 archetype_data["exports"] = [*archetype._exported_keys_]
 
             callback_items = [
-                (cb_name, cb_info, getattr(archetype, cb_name))
+                (cb_name, cb_info, archetype._callbacks_[cb_name])
                 for cb_name, cb_info in archetype._supported_callbacks_.items()
-                if getattr(archetype, cb_name) not in archetype._default_callbacks_
+                if cb_name in archetype._callbacks_
+                and archetype._callbacks_[cb_name] not in archetype._default_callbacks_
             ]
 
             if thread_pool is not None:

sonolus/build/dev_server.py

@@ -119,6 +119,7 @@ class RebuildCommand:
         print("Rebuilding...")
         try:
             start_time = perf_counter()
+            server_state.cache.reset_accessed()
             server_state.project_state = ProjectContextState.from_build_config(server_state.config)
             server_state.project = project_module.project
             build_collection(
@@ -128,6 +129,7 @@ class RebuildCommand:
                 cache=server_state.cache,
                 project_state=server_state.project_state,
             )
+            server_state.cache.prune_unaccessed()
             end_time = perf_counter()
             print(f"Rebuild completed in {end_time - start_time:.2f} seconds")
         except CompilationError:

sonolus/build/node.py

@@ -1,7 +1,7 @@
 from threading import Lock
 from typing import TypedDict
 
-from sonolus.backend.node import ConstantNode, EngineNode, FunctionNode
+from sonolus.backend.node import EngineNode, FunctionNode
 
 
 class ValueOutputNode(TypedDict):
@@ -32,19 +32,17 @@ class OutputNodeGenerator:
             return self.indexes[node]
 
         match node:
-            case ConstantNode(value):
-                index = len(self.nodes)
-                self.nodes.append({"value": value})
-                self.indexes[node] = index
-                return index
             case FunctionNode(func, args):
                 arg_indexes = [self._add(arg) for arg in args]
                 index = len(self.nodes)
                 self.nodes.append({"func": func.value, "args": arg_indexes})
                 self.indexes[node] = index
                 return index
-            case _:
-                raise ValueError("Invalid node")
+            case constant:
+                index = len(self.nodes)
+                self.nodes.append({"value": constant})
+                self.indexes[node] = index
+                return index
 
     def get(self):
         return self.nodes

sonolus/script/archetype.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import inspect
 from abc import abstractmethod
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from enum import Enum, StrEnum
 from types import FunctionType
@@ -11,7 +11,9 @@ from typing import Annotated, Any, ClassVar, Self, TypedDict, get_origin
 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.visitor import compile_and_call
 from sonolus.script.bucket import Bucket, Judgment
+from sonolus.script.debug import runtime_checks_enabled, static_error
 from sonolus.script.internal.callbacks import PLAY_CALLBACKS, PREVIEW_CALLBACKS, WATCH_ARCHETYPE_CALLBACKS, CallbackInfo
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.descriptor import SonolusDescriptor
@@ -207,7 +209,7 @@ class _IsScoredDescriptor(SonolusDescriptor):
         if instance is None:
             return self.value
         elif ctx():
-            return ctx().mode_state.is_scored_by_archetype_id[instance.id]
+            return ctx().mode_state.is_scored_by_archetype_id.get_unchecked(instance.id)
         else:
             return self.value
 
@@ -221,7 +223,7 @@ class _IdDescriptor(SonolusDescriptor):
             raise RuntimeError("Archetype id is only available during compilation")
         if instance is None:
             result = ctx().mode_state.archetypes.get(owner)
-            if result is None:
+            if result is None or owner in ctx().mode_state.compile_time_only_archetypes:
                 raise RuntimeError("Archetype is not registered")
             return result
         else:
@@ -237,7 +239,7 @@ class _KeyDescriptor(SonolusDescriptor):
 
     def __get__(self, instance, owner):
         if instance is not None and ctx():
-            return ctx().mode_state.keys_by_archetype_id[instance.id]
+            return ctx().mode_state.keys_by_archetype_id.get_unchecked(instance.id)
         else:
             return self.value
 
@@ -427,7 +429,7 @@ class _BaseArchetype:
 
     _imported_keys_: ClassVar[dict[str, int]]
     _exported_keys_: ClassVar[dict[str, int]]
-    _callbacks_: ClassVar[list[Callable]]
+    _callbacks_: ClassVar[dict[str, Callable]]
     _data_constructor_signature_: ClassVar[inspect.Signature]
     _spawn_signature_: ClassVar[inspect.Signature]
 
@@ -491,17 +493,67 @@ class _BaseArchetype:
 
     @classmethod
     @meta_fn
-    def at(cls, index: int) -> Self:
+    def _compile_time_id(cls):
+        if not ctx():
+            raise RuntimeError("Archetype id is only available during compilation")
+        result = ctx().mode_state.archetypes.get(cls)
+        if result is None:
+            raise RuntimeError("Archetype is not registered")
+        return result
+
+    @classmethod
+    @meta_fn
+    def at(cls, index: int, check: bool = True) -> Self:
+        """Access the entity of this archetype at the given index.
+
+        Args:
+            index: The index of the entity to reference.
+            check: If true, raises an error if the entity at the index is not of this archetype or of a subclass of
+            this archetype. If false, no validation is performed.
+
+        Returns:
+            The entity at the given index.
+        """
+        if not ctx():
+            raise RuntimeError("Archetype.at is only available during compilation")
+        compile_and_call(cls._check_is_at, index, check=check)
         result = cls._new()
         result._data_ = _ArchetypeReferenceData(index=Num._accept_(index))
         return result
 
     @classmethod
+    def is_at(cls, index: int, strict: bool = False) -> bool:
+        """Return whether the entity at the given index is of this archetype.
+
+        Args:
+            index: The index of the entity to check.
+            strict: If true, only returns true if the entity is exactly of this archetype. If false, also returns true
+            if the entity is of a subclass of this archetype.
+
+        Returns:
+            Whether the entity at the given index is of this archetype.
+        """
+        if strict:
+            return index >= 0 and cls._compile_time_id() == entity_info_at(index).archetype_id
+        else:
+            mro_ids = cls._get_mro_id_array(entity_info_at(index).archetype_id)
+            return index >= 0 and cls._compile_time_id() in mro_ids
+
+    @classmethod
+    def _check_is_at(cls, index: int, check: bool):
+        if not check or not runtime_checks_enabled():
+            return
+        assert index >= 0, "Entity index must be non-negative"
+        assert cls._compile_time_id() in cls._get_mro_id_array(entity_info_at(index).archetype_id), (
+            "Entity at index is not of the expected archetype"
+        )
+
+    @staticmethod
     @meta_fn
-    def is_at(cls, index: int) -> bool:
+    def _get_mro_id_array(archetype_id: int) -> Sequence[int]:
         if not ctx():
-            raise RuntimeError("is_at is only available during compilation")
-        return entity_info_at(index).archetype_id == cls.id
+            raise RuntimeError("Archetype._get_mro_id_array is only available during compilation")
+        return ctx().get_archetype_mro_id_array(archetype_id)
 
     @classmethod
     @meta_fn
@@ -562,13 +614,16 @@ class _BaseArchetype:
             return
         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__.removeprefix(cls._removable_prefix)
-        cls._callbacks_ = []
+        cls._callbacks_ = {}
         for name in cls._supported_callbacks_:
-            cb = getattr(cls, name)
-            if cb in cls._default_callbacks_:
-                continue
-            cls._callbacks_.append(cb)
+            for mro_entry in cls.mro():
+                if name in mro_entry.__dict__:
+                    cb = mro_entry.__dict__[name]
+                    if cb not in cls._default_callbacks_:
+                        cls._callbacks_[name] = cb
+                        break
         cls._field_init_done = False
+        cls._is_concrete_archetype_ = True
         cls.id = _IdDescriptor()
         cls._key_ = cls.key
         cls.key = _KeyDescriptor(cls.key)
@@ -584,6 +639,14 @@ class _BaseArchetype:
         for mro_entry in cls.mro()[1:]:
             if hasattr(mro_entry, "_field_init_done"):
                 mro_entry._init_fields()
+        if sum(issubclass(base, _BaseArchetype) for base in cls.__bases__) > 1:
+            raise TypeError("Multiple inheritance of Archetypes is not supported")
+        mro_from_archetype_parents = set(
+            type("Dummy", tuple(base for base in cls.__bases__ if issubclass(base, _BaseArchetype)), {}).mro()
+        )
+        # Archetype parents would have already initialized relevant fields, so only consider the current class
+        # and mixins that were not already included via an archetype parent
+        mro_excluding_archetype_parents = [entry for entry in cls.mro() if entry not in mro_from_archetype_parents]
         field_specifiers = get_field_specifiers(
             cls,
             skip={
@@ -599,7 +662,9 @@ class _BaseArchetype:
                 "_default_callbacks_",
                 "_callbacks_",
                 "_field_init_done",
+                "_is_concrete_archetype_",
             },
+            included_classes=mro_excluding_archetype_parents,
         ).items()
         if not hasattr(cls, "_imported_fields_"):
             cls._imported_fields_ = {}
@@ -652,6 +717,13 @@ class _BaseArchetype:
                     f"Missing field annotation for '{name}', "
                     f"expected exactly one of imported, exported, entity_memory, or shared_memory"
                 )
+            if (
+                name in cls._imported_fields_
+                or name in cls._exported_fields_
+                or name in cls._memory_fields_
+                or name in cls._shared_memory_fields_
+            ):
+                raise ValueError(f"Field '{name}' is already defined in a superclass")
             field_type = validate_concrete_type(value.__args__[0])
             match field_info.storage:
                 case _StorageType.IMPORTED:
@@ -770,6 +842,18 @@ class _BaseArchetype:
         new_cls = type(name, (cls,), cls_dict)
         return new_cls
 
+    @meta_fn
+    def _delegate(self, name: str, default: int | float | None = None):
+        name = validate_value(name)._as_py_()
+        if hasattr(super(), name):
+            fn = getattr(super(), name)
+            if ctx():
+                return compile_and_call(fn)
+            else:
+                return fn()
+        else:
+            return default
+
 
 class PlayArchetype(_BaseArchetype):
     """Base class for play mode archetypes.
@@ -807,26 +891,28 @@ class PlayArchetype(_BaseArchetype):
 
         Runs first when the level is loaded.
         """
+        self._delegate("preprocess")
 
     def spawn_order(self) -> float:
         """Return the spawn order of the entity.
 
         Runs when the level is loaded after [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess].
         """
-        return 0.0
+        return self._delegate("spawn_order", default=0.0)
 
     def should_spawn(self) -> bool:
         """Return whether the entity should be spawned.
 
         Runs each frame while the entity is the first entity in the spawn queue.
         """
-        return True
+        return self._delegate("should_spawn", default=True)
 
     def initialize(self):
         """Initialize this entity.
 
         Runs when this entity is spawned.
         """
+        self._delegate("initialize")
 
     def update_sequential(self):
         """Perform non-parallel actions for this frame.
@@ -838,6 +924,7 @@ class PlayArchetype(_BaseArchetype):
         [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel]
         for better performance.
         """
+        self._delegate("update_sequential")
 
     def update_parallel(self):
         """Perform parallel actions for this frame.
@@ -846,18 +933,21 @@ class PlayArchetype(_BaseArchetype):
 
         This is where most gameplay logic should be placed.
         """
+        self._delegate("update_parallel")
 
     def touch(self):
         """Handle user input.
 
         Runs after [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential] each frame.
         """
+        self._delegate("touch")
 
     def terminate(self):
         """Finalize before despawning.
 
         Runs when the entity is despawned.
         """
+        self._delegate("terminate")
 
     @property
     @meta_fn
@@ -965,20 +1055,22 @@ class WatchArchetype(_BaseArchetype):
 
         Runs first when the level is loaded.
         """
+        self._delegate("preprocess")
 
     def spawn_time(self) -> float:
         """Return the spawn time of the entity."""
-        return 0.0
+        return self._delegate("spawn_time", default=0.0)
 
     def despawn_time(self) -> float:
         """Return the despawn time of the entity."""
-        return 0.0
+        return self._delegate("despawn_time", default=0.0)
 
     def initialize(self):
         """Initialize this entity.
 
         Runs when this entity is spawned.
         """
+        self._delegate("initialize")
 
     def update_sequential(self):
         """Perform non-parallel actions for this frame.
@@ -989,6 +1081,7 @@ class WatchArchetype(_BaseArchetype):
         Other logic should typically be placed in
         [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel] for better performance.
         """
+        self._delegate("update_sequential")
 
     def update_parallel(self):
         """Parallel update callback.
@@ -997,12 +1090,14 @@ class WatchArchetype(_BaseArchetype):
 
         This is where most gameplay logic should be placed.
         """
+        self._delegate("update_parallel")
 
     def terminate(self):
         """Finalize before despawning.
 
         Runs when the entity is despawned.
         """
+        self._delegate("terminate")
 
     @property
     @meta_fn
@@ -1073,12 +1168,14 @@ class PreviewArchetype(_BaseArchetype):
 
         Runs first when the level is loaded.
         """
+        self._delegate("preprocess")
 
     def render(self):
         """Render the entity.
 
         Runs after `preprocess`.
         """
+        self._delegate("render")
 
     @property
     @meta_fn
@@ -1210,6 +1307,8 @@ class EntityRef[A: _BaseArchetype](Record):
 
     Usage:
         ```python
+        ref = EntityRef[MyArchetype](index=123)
+
         class MyArchetype(PlayArchetype):
             ref_1: EntityRef[OtherArchetype] = imported()
             ref_2: EntityRef[Any] = imported()
@@ -1239,11 +1338,25 @@ class EntityRef[A: _BaseArchetype](Record):
         return super().__hash__()
 
     @meta_fn
-    def get(self) -> A:
-        """Get the entity."""
+    def __bool__(self):
+        if ctx():
+            static_error("EntityRef cannot be used in a boolean context. Check index directly instead.")
+        return True
+
+    @meta_fn
+    def get(self, *, check: bool = True) -> A:
+        """Get the entity this reference points to.
+
+        Args:
+            check: If true, raises an error if the referenced entity is not of this archetype or of a subclass of
+            this archetype. If false, no validation is performed.
+
+        Returns:
+            The entity this reference points to.
+        """
         if ref := getattr(self, "_ref_", None):
             return ref
-        return self.archetype().at(self.index)
+        return self.archetype().at(self.index, check=check)
 
     @meta_fn
     def get_as(self, archetype: type[_BaseArchetype]) -> _BaseArchetype:
@@ -1252,9 +1365,17 @@ class EntityRef[A: _BaseArchetype](Record):
             raise TypeError("Using get_as in level data is not supported.")
         return self.with_archetype(archetype).get()
 
-    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 archetype_matches(self, strict: bool = False) -> bool:
+        """Check if entity at the index is of this archetype.
+
+        Args:
+            strict: If true, only returns true if the entity is exactly of this archetype. If false, also returns true
+            if the entity is of a subclass of this archetype.
+
+        Returns:
+            Whether the entity at the given index is of this archetype.
+        """
+        return self.archetype().is_at(self.index, strict=strict)
 
     def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         ref = getattr(self, "_ref_", None)

sonolus/script/containers.py

@@ -468,11 +468,8 @@ class FrozenNumSet[Size](Record):
         return len(self._values)
 
     def __contains__(self, value: Num) -> bool:
-        if len(self) < 15:
-            for i in range(len(self)):  # noqa: SIM110
-                if self._values.get_unchecked(i) == value:
-                    return True
-            return False
+        if len(self) < 8:
+            return value in self._as_tuple()
         else:
             left = 0
             right = len(self) - 1
@@ -490,6 +487,10 @@ class FrozenNumSet[Size](Record):
     def __iter__(self) -> SonolusIterator[Num]:
         return self._values.__iter__()
 
+    @meta_fn
+    def _as_tuple(self) -> tuple[Num, ...]:
+        return tuple(self._values.get_unchecked(i) for i in range(Num._accept_(len(self))._as_py_()))
+
 
 class _ArrayMapEntry[K, V](Record):
     key: K

sonolus/script/debug.py

@@ -102,6 +102,14 @@ def notify(message: str):
         print(f"[NOTIFY] {message}")
 
 
+@meta_fn
+def runtime_checks_enabled() -> bool:
+    if ctx():
+        return ctx().project_state.runtime_checks != RuntimeChecks.NONE
+    else:
+        return True
+
+
 @meta_fn
 def require(value: int | float | bool, message: str | None = None):
     """Require a condition to be true, or raise an error.
@@ -212,7 +220,7 @@ def visualize_cfg(
     project_state = ProjectContextState()
     mode_state = ModeContextState(
         mode,
-        {a: i for i, a in enumerate(archetypes)} if archetypes is not None else None,
+        archetypes,
     )
 
     cfg = callback_to_cfg(project_state, mode_state, fn, callback, archetype=archetype)  # type: ignore

sonolus/script/internal/context.py

@@ -94,25 +94,36 @@ class ProjectContextState:
 
 class ModeContextState:
     archetypes: dict[type, int]
+    compile_time_only_archetypes: set[type]
     archetypes_by_name: dict[str, type]
     keys_by_archetype_id: Sequence[int]
     is_scored_by_archetype_id: Sequence[bool]
+    archetype_mro_id_array_rom_indexes: Sequence[int] | None = None
     environment_mappings: dict[_GlobalInfo, int]
     environment_offsets: dict[Block, int]
     mode: Mode
     lock: Lock
 
-    def __init__(self, mode: Mode, archetypes: dict[type, int] | None = None):
+    def __init__(self, mode: Mode, archetypes: list[type] | None = None):
         from sonolus.script.array import Array
 
-        self.archetypes = archetypes or {}
+        archetypes = [*archetypes] if archetypes is not None else []
+        seen_archetypes = {*archetypes}
+        compile_time_only_archetypes = set()
+        for type_ in [*archetypes]:
+            for entry in type_.mro():
+                if getattr(entry, "_is_concrete_archetype_", False) and entry not in seen_archetypes:
+                    archetypes.append(entry)
+                    seen_archetypes.add(entry)
+                    compile_time_only_archetypes.add(entry)
+        self.archetypes = {type_: idx for idx, type_ in enumerate(archetypes)}
+        self.compile_time_only_archetypes = compile_time_only_archetypes
         self.archetypes_by_name = {type_.name: type_ for type_, _ in self.archetypes.items()}  # type: ignore
-        ordered_archetypes = sorted(self.archetypes, key=lambda a: self.archetypes[a])
         self.keys_by_archetype_id = (
-            Array(*((getattr(a, "_key_", -1)) for a in ordered_archetypes)) if archetypes else Array[int, Literal[0]]()
+            Array(*((getattr(a, "_key_", -1)) for a in archetypes)) if archetypes else Array[int, Literal[0]]()
         )
         self.is_scored_by_archetype_id = (
-            Array(*((getattr(a, "_is_scored_", False)) for a in ordered_archetypes))
+            Array(*((getattr(a, "_is_scored_", False)) for a in archetypes))
             if archetypes
             else Array[bool, Literal[0]]()
         )
@@ -121,6 +132,27 @@ class ModeContextState:
         self.mode = mode
         self.lock = Lock()
 
+    def _init_archetype_mro_info(self, rom: ReadOnlyMemory):
+        from sonolus.script.array import Array
+        from sonolus.script.num import Num
+
+        with self.lock:
+            if self.archetype_mro_id_array_rom_indexes is not None:
+                return
+            archetype_mro_id_values = []
+            archetype_mro_id_offsets = []
+            for type_ in self.archetypes:
+                mro_ids = [self.archetypes[entry] for entry in type_.mro() if entry in self.archetypes]
+                archetype_mro_id_offsets.append(len(archetype_mro_id_values))
+                archetype_mro_id_values.append(len(mro_ids))
+                archetype_mro_id_values.extend(mro_ids)
+            archetype_mro_id_array_place = rom[tuple(archetype_mro_id_values)]
+
+            archetype_mro_id_rom_indexes = Array[int, len(archetype_mro_id_offsets)]._with_value(
+                [Num._accept_(offset + archetype_mro_id_array_place.index) for offset in archetype_mro_id_offsets]
+            )
+            self.archetype_mro_id_array_rom_indexes = archetype_mro_id_rom_indexes
+
 
 class CallbackContextState:
     callback: str
@@ -371,6 +403,15 @@ class Context:
                 self.mode_state.archetypes[type_] = len(self.mode_state.archetypes)
             return self.mode_state.archetypes[type_]
 
+    def get_archetype_mro_id_array(self, archetype_id: int) -> Sequence[int]:
+        from sonolus.script.containers import ArrayPointer
+        from sonolus.script.num import Num
+        from sonolus.script.pointer import _deref
+
+        self.mode_state._init_archetype_mro_info(self.rom)
+        rom_index = self.mode_state.archetype_mro_id_array_rom_indexes[archetype_id]
+        return ArrayPointer[int](_deref(self.blocks.EngineRom, rom_index, Num), self.blocks.EngineRom, rom_index + 1)
+
 
 def ctx() -> Context | Any:  # Using Any to silence type checker warnings if it's None
     return context_var.get()

sonolus/script/internal/introspection.py

@@ -1,4 +1,5 @@
 import inspect
+from collections.abc import Sequence
 from typing import Annotated
 
 _missing = object()
@@ -11,9 +12,15 @@ def get_field_specifiers(
     globals=None,  # noqa: A002
     locals=None,  # noqa: A002
     eval_str=True,
+    included_classes: Sequence[type] | None = None,
 ):
     """Like inspect.get_annotations, but also turns class attributes into Annotated."""
-    results = inspect.get_annotations(cls, globals=globals, locals=locals, eval_str=eval_str)
+    if included_classes is not None:
+        results = {}
+        for entry in reversed(included_classes):
+            results.update(inspect.get_annotations(entry, eval_str=eval_str))
+    else:
+        results = inspect.get_annotations(cls, globals=globals, locals=locals, eval_str=eval_str)
     for key, value in results.items():
         class_value = getattr(cls, key, _missing)
         if class_value is not _missing and key not in skip:

{sonolus_py-0.11.0.dist-info → sonolus_py-0.12.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.11.0
+Version: 0.12.0
 Summary: Sonolus engine development in Python
 Project-URL: Documentation, https://sonolus.py.qwewqa.xyz/
 Project-URL: Repository, https://github.com/qwewqa/sonolus.py
 Project-URL: Issues, https://github.com/qwewqa/sonolus.py/issues
 Project-URL: Changelog, https://sonolus.py.qwewqa.xyz/changelog/
 License-File: LICENSE
-Requires-Python: >=3.12
+Requires-Python: >=3.12.5
 Description-Content-Type: text/markdown
 
 # Sonolus.py

{sonolus_py-0.11.0.dist-info → sonolus_py-0.12.0.dist-info}/RECORD

@@ -3,11 +3,11 @@ sonolus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/backend/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/backend/blocks.py,sha256=3peyb9eYBy0s53xNVJ1KmK4IgoyVkkwG-lqDQ_VZTHc,18531
 sonolus/backend/excepthook.py,sha256=ezsTi8hPXSUhqZ7-H0rmkWcndBQcZFAShF543zzaEPM,1912
-sonolus/backend/finalize.py,sha256=kytaqAVyoryWJTyJEbvIGysfxmt_DeCic2oxmrqAPYI,5508
-sonolus/backend/interpret.py,sha256=B0jqlLmEGoyO2mxpcvwRwV17Tq_gOE9wLNt26Q5QOfs,14306
+sonolus/backend/finalize.py,sha256=MRp_ATPreSmBGn8N6iwesS50rFWH9FIiQI6_Ea8RVTM,5090
+sonolus/backend/interpret.py,sha256=dnm0SJFfI4KIE6Ca2tKrLq10XwBC9EPSqN7OOYtA8Ws,14304
 sonolus/backend/ir.py,sha256=eyNXorOQY4zgKOvN4kO1MdJF3sU8H0Qw5RTPqbEjJHY,3854
 sonolus/backend/mode.py,sha256=NkcPZJm8dn83LX35uP24MtQOCnfRDFZ280dHeEEfauE,613
-sonolus/backend/node.py,sha256=eEzPP14jzWJp2xrZCAaPlNtokxdoqg0bSM7xQiwx1j8,1254
+sonolus/backend/node.py,sha256=w5y2GwSc2E9rQvGJNaMzvPW_FYjjfHw4QDUmKs1dAnc,714
 sonolus/backend/ops.py,sha256=5weB_vIxbkwCSJuzYZyKUk7vVXsSIEDJYRlvE-2ke8A,10572
 sonolus/backend/place.py,sha256=7qwV732hZ4WP-9GNN8FQSEKssPJZELip1wLXTWfop7Y,4717
 sonolus/backend/utils.py,sha256=OwD1EPh8j-hsfkLzeKNzPQojT_3kklpJou0WTJNoCbc,2337
@@ -28,19 +28,19 @@ sonolus/backend/optimize/ssa.py,sha256=raQO0furQQRPYb8iIBKfNrJlj-_5wqtI4EWNfLZ8Q
 sonolus/build/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/build/cli.py,sha256=uLY7JG3PTAb2a1bbjulFlgUGDzsHXyRAfkGV0lbuMgQ,10538
 sonolus/build/collection.py,sha256=6hniAzriPWBKUeGDkXabNXpbdHiHnqiK9shs6U1OExM,12748
-sonolus/build/compile.py,sha256=KOmncDKmGfgzC_FWB_LTxAl0s9w4wnaDe-luACMlCVs,8397
-sonolus/build/dev_server.py,sha256=u-p3wVdIPNTHjFLNZzPdW4JlFmeVbqqEle_O3otUhyw,10607
+sonolus/build/compile.py,sha256=m4v4wYWnI6ebot4-fJi9a7eoF0WIo3uPOPy0_NpLgK0,8855
+sonolus/build/dev_server.py,sha256=yHD3KGqzebdqcEBOC5JDlNptzlH8Sq4i-DNnh_zXWCA,10705
 sonolus/build/engine.py,sha256=jMymxbBXu-ekv71uU8TF2KbFaHs3yGjyJAztd1SoRDs,14808
 sonolus/build/level.py,sha256=KLqUAtxIuIqrzeFURJA97rdqjA5pcvYSmwNZQhElaMQ,702
-sonolus/build/node.py,sha256=gnX71RYDUOK_gYMpinQi-bLWO4csqcfiG5gFmhxzSec,1330
+sonolus/build/node.py,sha256=Dhuz_-UlRd-EJC7-AP1NuyvrjHWNo7jGssniRh4dZhI,1239
 sonolus/build/project.py,sha256=Uuz82QtTNFdklrVJ_i7EPp8hSjyOxLU1xAeOloa6G00,8579
 sonolus/script/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sonolus/script/archetype.py,sha256=J_0E6a183Spez8NTd_jyH0kjIO81Q1a3i6GrNzjyWuw,49631
+sonolus/script/archetype.py,sha256=qK1tcREt56qJPh1zw_cjZGz0UUQngLGXUDA1HmwNpY8,55083
 sonolus/script/array.py,sha256=EbrNwl_WuJ0JjjkX0s_VJNXWqvYdm_ljTbyrDEMLGUY,13348
 sonolus/script/array_like.py,sha256=E6S4TW2muXgcyVkhUASQVt7JSYUkpvdJPgHz6YiSHNo,14708
 sonolus/script/bucket.py,sha256=LNePLmCwgXfKLmH4Z7ZcTFKWR32eq4AnnagI7jacrsU,7782
-sonolus/script/containers.py,sha256=iZWPVvVr24iHBb8umuYV0LrCkr9Xgj1piWaat_he7-w,28643
-sonolus/script/debug.py,sha256=21_bvhP2cZ4kwS3Spxp8tP6ojIfmthQxlq4gtqrt0lo,7757
+sonolus/script/containers.py,sha256=KKySXTh_ON9hut1ScMS31ewRNnVd4t7OwpIZg2bPhno,28676
+sonolus/script/debug.py,sha256=sWMZ-c68GggD8eUZJUPRXxxDjtCt9j8X4-_FUgTvUNE,7856
 sonolus/script/easing.py,sha256=2FUJI_nfp990P_armCcRqHm2329O985glJAhSC6tnxs,11379
 sonolus/script/effect.py,sha256=SfJxSNF3RlPCRXnkt62ZlWhCXw3mmmRCsoMsvTErUP0,7960
 sonolus/script/engine.py,sha256=etI9dJsQ7V9YZICVNZg54WqpLijPxG8eTPHiV-_EiG8,10687
@@ -72,13 +72,13 @@ sonolus/script/internal/__init__.py,sha256=T6rzLoiOUaiSQtaHMZ88SNO-ijSjSSv33TKtU
 sonolus/script/internal/builtin_impls.py,sha256=1fo6UuWlaLoqpVwFSrFS5BabNeRCdS2T2mjsS4BPYcY,13603
 sonolus/script/internal/callbacks.py,sha256=vWzJG8uiJoEtsNnbeZPqOHogCwoLpz2D1MnHY2wVV8s,2801
 sonolus/script/internal/constant.py,sha256=3ycbGkDJVUwcrCZ96vLjAoAARgsvaqDM8rJ_YCrLrvo,4289
-sonolus/script/internal/context.py,sha256=fRvdxkx7EILU54-ogR1HSjLOZnH2PVw2gQri9m86K5Y,19852
+sonolus/script/internal/context.py,sha256=dhWQS7fFPMhb0FJyw3y--0HlBtwuYANdIYiv7u_96jk,22023
 sonolus/script/internal/descriptor.py,sha256=XRFey-EjiAm_--KsNl-8N0Mi_iyQwlPh68gDp0pKf3E,392
 sonolus/script/internal/dict_impl.py,sha256=alu_wKGSk1kZajNf64qbe7t71shEzD4N5xNIATH8Swo,1885
 sonolus/script/internal/error.py,sha256=ZNnsvQVQAnFKzcvsm6-sste2lo-tP5pPI8sD7XlAZWc,490
 sonolus/script/internal/generic.py,sha256=_3d5Rn_tn214-77fPE67vdbdqt1PQF8-2WB_XDu5YRg,7551
 sonolus/script/internal/impl.py,sha256=R88cl4nLcfF0UhA9qdYRBOsl4nMx8ucgz8l7_oRY-l8,3503
-sonolus/script/internal/introspection.py,sha256=guL9_NR2D3OJAnNpeFdyYkO_vVXk-3KQr2-y4YielM0,1133
+sonolus/script/internal/introspection.py,sha256=q6c83G_jmuLSoYSJj8ln0XtuwNEdndE0PkLbNWOhGmk,1421
 sonolus/script/internal/math_impls.py,sha256=ox2pBJ6ELRO0LdLn_RZxgHHs_PCgQOHIhmDkwmLxJaU,2975
 sonolus/script/internal/native.py,sha256=zOuRtgI3XJ_ExyR_ZkvbDABVc_JIWaKl62lFEL_bMaw,2007
 sonolus/script/internal/random.py,sha256=6Ku5edRcDUh7rtqEEYCJz0BQavw69RALsVHS25z50pI,1695
@@ -87,8 +87,8 @@ sonolus/script/internal/simulation_context.py,sha256=LGxLTvxbqBIhoe1R-SfwGajNIDw
 sonolus/script/internal/transient.py,sha256=y2AWABqF1aoaP6H4_2u4MMpNioC4OsZQCtPyNI0txqo,1634
 sonolus/script/internal/tuple_impl.py,sha256=WaI5HSF5h03ddXiSHEwzY9ttfsPUItaf86Y5VbZypek,3754
 sonolus/script/internal/value.py,sha256=OngrCdmY_h6mV2Zgwqhuo4eYFad0kTk6263UAxctZcY,6963
-sonolus_py-0.11.0.dist-info/METADATA,sha256=hhf11U7J2Zk1rkB-vixzUjS94Ygoh2R1DZ2jmdhnbC4,554
-sonolus_py-0.11.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sonolus_py-0.11.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
-sonolus_py-0.11.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
-sonolus_py-0.11.0.dist-info/RECORD,,
+sonolus_py-0.12.0.dist-info/METADATA,sha256=ncmBBjgZ1BHrxEb9xrtEIa_CiF8pK-lknGve69U3_LY,556
+sonolus_py-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sonolus_py-0.12.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
+sonolus_py-0.12.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
+sonolus_py-0.12.0.dist-info/RECORD,,