sonolus.py 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

sonolus/backend/visitor.py

@@ -14,7 +14,16 @@ from sonolus.backend.utils import get_function, scan_writes
 from sonolus.script.debug import assert_true
 from sonolus.script.internal.builtin_impls import BUILTIN_IMPLS, _bool, _float, _int, _len, _super
 from sonolus.script.internal.constant import ConstantValue
-from sonolus.script.internal.context import Context, EmptyBinding, Scope, ValueBinding, ctx, set_ctx, using_ctx
+from sonolus.script.internal.context import (
+    ConflictBinding,
+    Context,
+    EmptyBinding,
+    Scope,
+    ValueBinding,
+    ctx,
+    set_ctx,
+    using_ctx,
+)
 from sonolus.script.internal.descriptor import SonolusDescriptor
 from sonolus.script.internal.error import CompilationError
 from sonolus.script.internal.impl import meta_fn, validate_value
@@ -22,7 +31,7 @@ from sonolus.script.internal.transient import TransientValue
 from sonolus.script.internal.tuple_impl import TupleImpl
 from sonolus.script.internal.value import Value
 from sonolus.script.iterator import SonolusIterator
-from sonolus.script.maybe import Maybe
+from sonolus.script.maybe import Maybe, Nothing
 from sonolus.script.num import Num, _is_num
 from sonolus.script.record import Record
 
@@ -312,13 +321,16 @@ class Visitor(ast.NodeVisitor):
                 yield_merge_ctx = Context.meet(yield_between_ctxs)
             else:
                 yield_merge_ctx = before_ctx.new_empty_disconnected()
-                # Making it default to a number for convenience when used with stuff like min, etc.
-                yield_merge_ctx.scope.set_value("$yield", validate_value(0))
             yield_binding = yield_merge_ctx.scope.get_binding("$yield")
-            if not isinstance(yield_binding, ValueBinding):
-                raise ValueError("Function has conflicting yield values")
-            with using_ctx(yield_merge_ctx):
-                is_present_var._set_(1)
+            match yield_binding:
+                case ValueBinding():
+                    with using_ctx(yield_merge_ctx):
+                        is_present_var._set_(1)
+                    yield_value = Maybe(present=is_present_var, value=yield_binding.value)
+                case EmptyBinding():
+                    yield_value = Nothing
+                case ConflictBinding():
+                    raise ValueError("Function has conflicting yield values")
             next_result_ctx = Context.meet([yield_merge_ctx, return_ctx])
             set_ctx(before_ctx)
             return_test = Num._alloc_()
@@ -327,7 +339,7 @@ class Visitor(ast.NodeVisitor):
                 return_test,
                 entry,
                 next_result_ctx,
-                Maybe(present=is_present_var, value=yield_binding.value),
+                yield_value,
                 self.used_parent_binding_values,
                 self,
             )
@@ -739,11 +751,17 @@ class Visitor(ast.NodeVisitor):
                         test = validate_value(subject._is_py_() and subject._as_py_() is None)
                     case _:
                         raise NotImplementedError("Unsupported match singleton")
-                ctx_init = ctx()
-                ctx_init.test = test.ir()
-                true_ctx = ctx_init.branch(None)
-                false_ctx = ctx_init.branch(0)
-                return true_ctx, false_ctx
+                if test._is_py_():
+                    if test._as_py_():
+                        return ctx(), ctx().into_dead()
+                    else:
+                        return ctx().into_dead(), ctx()
+                else:
+                    ctx_init = ctx()
+                    ctx_init.test = test.ir()
+                    true_ctx = ctx_init.branch(None)
+                    false_ctx = ctx_init.branch(0)
+                    return true_ctx, false_ctx
             case ast.MatchSequence(patterns=patterns):
                 target_len = len(patterns)
                 if not (isinstance(subject, Sequence | TupleImpl)):

sonolus/build/collection.py

@@ -4,6 +4,7 @@ import gzip
 import hashlib
 import json
 import urllib.request
+import warnings
 import zipfile
 from io import BytesIO
 from os import PathLike
@@ -116,6 +117,7 @@ class Collection:
                 try:
                     item_data = json.loads(item_json_path.read_text(encoding="utf-8"))
                 except json.JSONDecodeError:
+                    warnings.warn(f"Invalid JSON in {item_json_path}, skipping item.", stacklevel=2)
                     continue
 
                 item_data = self._localize_item(item_data)
@@ -129,7 +131,7 @@ class Collection:
                         resource_data = resource_path.read_bytes()
 
                         if resource_path.suffix.lower() in {".json", ".bin"}:
-                            resource_data = gzip.compress(resource_data)
+                            resource_data = gzip.compress(resource_data, mtime=0)
 
                         srl = self.add_asset(resource_data)
                         item_data[resource_path.stem] = srl

sonolus/build/compile.py

@@ -77,7 +77,13 @@ def compile_mode(
     base_archetype_entries = {}
 
     if archetypes is not None:
-        base_archetypes = {getattr(a, "_derived_base_", a) for a in archetypes}
+        base_archetypes = []
+        seen_base_archetypes = set()
+        for a in archetypes:
+            base = getattr(a, "_derived_base_", a)
+            if base not in seen_base_archetypes:
+                seen_base_archetypes.add(base)
+                base_archetypes.append(base)
 
         for archetype in base_archetypes:
             archetype._init_fields()

sonolus/build/engine.py

@@ -407,12 +407,12 @@ def package_rom(rom: ReadOnlyMemory) -> bytes:
     for value in values:
         output.extend(struct.pack("<f", value))
 
-    return gzip.compress(bytes(output))
+    return gzip.compress(bytes(output), mtime=0)
 
 
 def package_data(value: JsonValue) -> bytes:
     json_data = json.dumps(value, separators=(",", ":")).encode("utf-8")
-    return gzip.compress(json_data)
+    return gzip.compress(json_data, mtime=0)
 
 
 def unpackage_data(data: bytes) -> JsonValue:

sonolus/build/project.py

@@ -39,7 +39,7 @@ def build_project_to_collection(project: Project, config: BuildConfig | None):
 
 
 def apply_converter_to_collection(
-    self, src_engine: str | None, converter: Callable[[ExternalLevelData], LevelData]
+    self, src_engine: str | None, converter: Callable[[ExternalLevelData], LevelData | None]
 ) -> None:
     for level_details in self.categories.get("levels", {}).values():
         level = level_details["item"]
@@ -56,6 +56,8 @@ def apply_converter_to_collection(
             raise ValueError(f"Level data for level '{level['name']}' is not valid")
         parsed_data = parse_external_level_data(cast(ExternalLevelDataDict, data))
         new_data = converter(parsed_data)
+        if new_data is None:
+            continue
         packaged_new_data = package_level_data(new_data)
         new_data_srl = self.add_asset(packaged_new_data)
         level["data"] = new_data_srl

sonolus/script/archetype.py

@@ -1233,6 +1233,11 @@ class EntityRef[A: _BaseArchetype](Record):
             return self._ref_ is other._ref_
         return super().__eq__(other)
 
+    def __hash__(self) -> int:
+        if not ctx() and hasattr(self, "_ref_"):
+            return hash(id(self._ref_))
+        return super().__hash__()
+
     @meta_fn
     def get(self) -> A:
         """Get the entity."""

sonolus/script/debug.py

@@ -80,6 +80,20 @@ def assert_false(value: int | float | bool, message: str | None = None):
         error(message)
 
 
+def static_assert(value: int | float | bool, message: str | None = None):
+    message = message if message is not None else "Static assertion failed"
+    if not _is_static_true(value):
+        static_error(message)
+
+
+def try_static_assert(value: int | float | bool, message: str | None = None):
+    message = message if message is not None else "Static assertion failed"
+    if _is_static_false(value):
+        static_error(message)
+    if not value:
+        error(message)
+
+
 @meta_fn
 def assert_unreachable(message: str | None = None) -> Never:
     # This works a bit differently from assert_never from typing in that it throws an error if the Sonolus.py
@@ -140,3 +154,21 @@ def visualize_cfg(
 
 def simulation_context() -> SimulationContext:
     return SimulationContext()
+
+
+@meta_fn
+def _is_static_true(value: int | float | bool) -> bool:
+    if ctx() is None:
+        return bool(value)
+    else:
+        value = validate_value(value)
+        return value._is_py_() and value._as_py_()
+
+
+@meta_fn
+def _is_static_false(value: int | float | bool) -> bool:
+    if ctx() is None:
+        return not bool(value)
+    else:
+        value = validate_value(value)
+        return value._is_py_() and not value._as_py_()

sonolus/script/effect.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.ops import Op
+from sonolus.script.array_like import ArrayLike
+from sonolus.script.debug import static_error
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_function
 from sonolus.script.record import Record
@@ -92,6 +95,29 @@ class ScheduledLoopedEffectHandle(Record):
         _stop_looped_scheduled(self.id, end_time)
 
 
+class EffectGroup(Record, ArrayLike[Effect]):
+    """A group of effect clips.
+
+    Usage:
+        ```python
+        EffectGroup(start_id: int, size: int)
+        ```
+    """
+
+    start_id: int
+    size: int
+
+    def __len__(self) -> int:
+        return self.size
+
+    def __getitem__(self, index: int) -> Effect:
+        assert 0 <= index < self.size
+        return Effect(self.start_id + index)
+
+    def __setitem__(self, index: int, value: Effect) -> None:
+        static_error("EffectGroup is read-only")
+
+
 @native_function(Op.HasEffectClip)
 def _has_effect_clip(effect_id: int) -> bool:
     raise NotImplementedError
@@ -132,11 +158,21 @@ class EffectInfo:
     name: str
 
 
+@dataclass
+class EffectGroupInfo:
+    names: list[str]
+
+
 def effect(name: str) -> Any:
     """Define a sound effect clip with the given name."""
     return EffectInfo(name)
 
 
+def effect_group(names: Iterable[str]) -> Any:
+    """Define an effect group with the given names."""
+    return EffectGroupInfo(list(names))
+
+
 type Effects = NewType("Effects", Any)  # type: ignore
 
 
@@ -150,24 +186,45 @@ def effects[T](cls: type[T]) -> T | Effects:
         class Effects:
             miss: StandardEffect.MISS
             other: Effect = effect("other")
+            group_1: EffectGroup = effect_group(["one", "two", "three"])
+            group_2: EffectGroup = effect_group(f"name_{i}" for i in range(10))
         ```
     """
     if len(cls.__bases__) != 1:
         raise ValueError("Effects class must not inherit from any class (except object)")
     instance = cls()
     names = []
-    for i, (name, annotation) in enumerate(get_field_specifiers(cls).items()):
+    i = 0
+    for name, annotation in get_field_specifiers(cls).items():
         if get_origin(annotation) is not Annotated:
-            raise TypeError(f"Invalid annotation for effects: {annotation}")
+            raise TypeError(f"Invalid annotation for effects: {annotation} on field {name}")
         annotation_type = annotation.__args__[0]
         annotation_values = annotation.__metadata__
-        if annotation_type is not Effect:
-            raise TypeError(f"Invalid annotation for effects: {annotation}, expected annotation of type Effect")
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], EffectInfo):
-            raise TypeError(f"Invalid annotation for effects: {annotation}, expected a single string annotation value")
-        effect_name = annotation_values[0].name
-        names.append(effect_name)
-        setattr(instance, name, Effect(i))
+        if len(annotation_values) != 1:
+            raise TypeError(f"Invalid annotation for effects: {annotation} on field {name}, too many annotation values")
+        effect_info = annotation_values[0]
+        match effect_info:
+            case EffectInfo(name=effect_name):
+                if annotation_type is not Effect:
+                    raise TypeError(f"Invalid annotation for effects: {annotation} on field {name}, expected Effect")
+                names.append(effect_name)
+                setattr(instance, name, Effect(i))
+                i += 1
+            case EffectGroupInfo(names=effect_names):
+                if annotation_type is not EffectGroup:
+                    raise TypeError(
+                        f"Invalid annotation for effects: {annotation} on field {name}, expected EffectGroup"
+                    )
+                start_id = i
+                count = len(effect_names)
+                names.extend(effect_names)
+                setattr(instance, name, EffectGroup(start_id, count))
+                i += count
+            case _:
+                raise TypeError(
+                    f"Invalid annotation for effects: {annotation} on field {name}, unknown effect info, "
+                    f"expected an effect() or effect_group() specifier"
+                )
     instance._effects_ = names
     instance._is_comptime_value_ = True
     return instance

sonolus/script/level.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import gzip
 import json
 from collections.abc import Iterator
 from os import PathLike
@@ -229,7 +230,21 @@ class ExternalEntityData(NamedTuple):
     data: dict[str, Any]
 
 
-def parse_external_level_data(raw_data: ExternalLevelDataDict) -> ExternalLevelData:
+def parse_external_level_data(raw_data: ExternalLevelDataDict | str | bytes, /) -> ExternalLevelData:
+    """Parse level data from an external source.
+
+    If given a string, it is parsed as JSON. If given bytes, it is un-gzipped and then parsed as JSON.
+
+    Args:
+        raw_data: The raw level data to parse.
+
+    Returns:
+        The parsed level data.
+    """
+    if isinstance(raw_data, bytes):
+        raw_data = gzip.decompress(raw_data).decode("utf-8")
+    if isinstance(raw_data, str):
+        raw_data = json.loads(raw_data)
     bgm_offset = raw_data["bgmOffset"]
     raw_entities = raw_data["entities"]
     entity_name_to_index = {e["name"]: i for i, e in enumerate(raw_entities) if "name" in e}

sonolus/script/num.py

@@ -131,6 +131,8 @@ class _Num(Value, metaclass=_NumMeta):
                 if isinstance(self.data.block, BlockData) and not ctx().is_writable(self.data):
                     # This block is immutable in the current callback, so no need to copy it in case it changes.
                     return Num(self.data)
+            if isinstance(self.data, int | float | bool):
+                return Num(self.data)
             place = ctx().alloc(size=1)
             ctx().add_statements(IRSet(place, self.ir()))
             return Num(place)

sonolus/script/particle.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.ops import Op
+from sonolus.script.array_like import ArrayLike
+from sonolus.script.debug import static_error
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_function
 from sonolus.script.quad import QuadLike, flatten_quad
@@ -52,6 +55,29 @@ class ParticleHandle(Record):
         _destroy_particle_effect(self.id)
 
 
+class ParticleGroup(Record, ArrayLike[Particle]):
+    """A group of particle effects.
+
+    Usage:
+        ```python
+        ParticleGroup(start_id: int, size: int)
+        ```
+    """
+
+    start_id: int
+    size: int
+
+    def __len__(self) -> int:
+        return self.size
+
+    def __getitem__(self, index: int) -> Particle:
+        assert 0 <= index < self.size
+        return Particle(self.start_id + index)
+
+    def __setitem__(self, index: int, value: Particle) -> None:
+        static_error("ParticleGroup is read-only")
+
+
 @native_function(Op.HasParticleEffect)
 def _has_particle_effect(particle_id: int) -> bool:
     raise NotImplementedError
@@ -91,11 +117,21 @@ class _ParticleInfo:
     name: str
 
 
+@dataclass
+class _ParticleGroupInfo:
+    names: list[str]
+
+
 def particle(name: str) -> Any:
     """Define a particle with the given name."""
     return _ParticleInfo(name)
 
 
+def particle_group(names: Iterable[str]) -> Any:
+    """Define a particle group with the given names."""
+    return _ParticleGroupInfo(list(names))
+
+
 type Particles = NewType("Particles", Any)  # type: ignore
 
 
@@ -109,26 +145,49 @@ def particles[T](cls: type[T]) -> T | Particles:
         class Particles:
             tap: StandardParticle.NOTE_CIRCULAR_TAP_RED
             other: Particle = particle("other")
+            group_1: ParticleGroup = particle_group(["one", "two", "three"])
+            group_2: ParticleGroup = particle_group(f"name_{i}" for i in range(10))
         ```
     """
     if len(cls.__bases__) != 1:
         raise ValueError("Particles class must not inherit from any class (except object)")
     instance = cls()
     names = []
-    for i, (name, annotation) in enumerate(get_field_specifiers(cls).items()):
+    i = 0
+    for name, annotation in get_field_specifiers(cls).items():
         if get_origin(annotation) is not Annotated:
-            raise TypeError(f"Invalid annotation for particles: {annotation}")
+            raise TypeError(f"Invalid annotation for particles: {annotation} on field {name}")
         annotation_type = annotation.__args__[0]
         annotation_values = annotation.__metadata__
-        if annotation_type is not Particle:
-            raise TypeError(f"Invalid annotation for particles: {annotation}, expected annotation of type Particle")
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], _ParticleInfo):
+        if len(annotation_values) != 1:
             raise TypeError(
-                f"Invalid annotation for particles: {annotation}, expected a single string annotation value"
+                f"Invalid annotation for particles: {annotation} on field {name}, too many annotation values"
             )
-        particle_name = annotation_values[0].name
-        names.append(particle_name)
-        setattr(instance, name, Particle(i))
+        particle_info = annotation_values[0]
+        match particle_info:
+            case _ParticleInfo(name=particle_name):
+                if annotation_type is not Particle:
+                    raise TypeError(
+                        f"Invalid annotation for particles: {annotation} on field {name}, expected Particle"
+                    )
+                names.append(particle_name)
+                setattr(instance, name, Particle(i))
+                i += 1
+            case _ParticleGroupInfo(names=particle_names):
+                if annotation_type is not ParticleGroup:
+                    raise TypeError(
+                        f"Invalid annotation for particles: {annotation} on field {name}, expected ParticleGroup"
+                    )
+                start_id = i
+                count = len(particle_names)
+                names.extend(particle_names)
+                setattr(instance, name, ParticleGroup(start_id, count))
+                i += count
+            case _:
+                raise TypeError(
+                    f"Invalid annotation for particles: {annotation} on field {name}, unknown particle info, "
+                    f"expected a particle() or particle_group() specifier"
+                )
     instance._particles_ = names
     instance._is_comptime_value_ = True
     return instance

sonolus/script/project.py

@@ -28,7 +28,7 @@ class Project:
         engine: Engine,
         levels: Iterable[Level] | Callable[[], Iterable[Level]] | None = None,
         resources: PathLike | None = None,
-        converters: dict[str | None, Callable[[ExternalLevelData], LevelData]] | None = None,
+        converters: dict[str | None, Callable[[ExternalLevelData], LevelData | None]] | None = None,
     ):
         self.engine = engine
         match levels:

sonolus/script/quad.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Protocol
+from typing import Protocol, Self, assert_never, overload
 
 from sonolus.script.record import Record
 from sonolus.script.values import zeros
@@ -57,6 +57,26 @@ class Quad(Record):
         """The center of the quad."""
         return (self.bl + self.tr + self.tl + self.br) / 4
 
+    @property
+    def mt(self) -> Vec2:
+        """The midpoint of the top edge of the quad."""
+        return (self.tl + self.tr) / 2
+
+    @property
+    def mr(self) -> Vec2:
+        """The midpoint of the right edge of the quad."""
+        return (self.tr + self.br) / 2
+
+    @property
+    def mb(self) -> Vec2:
+        """The midpoint of the bottom edge of the quad."""
+        return (self.bl + self.br) / 2
+
+    @property
+    def ml(self) -> Vec2:
+        """The midpoint of the left edge of the quad."""
+        return (self.bl + self.tl) / 2
+
     def translate(self, translation: Vec2, /) -> Quad:
         """Translate the quad by the given translation and return a new quad."""
         return Quad(
@@ -212,7 +232,7 @@ class Rect(Record):
     b: float
     """The bottom edge of the rectangle."""
 
-    l: float  # noqa: E741
+    l: float
     """The left edge of the rectangle."""
 
     @classmethod
@@ -225,6 +245,57 @@ class Rect(Record):
             l=center.x - dimensions.x / 2,
         )
 
+    @overload
+    @classmethod
+    def from_margin(cls, trbl: float, /) -> Rect: ...
+
+    @overload
+    @classmethod
+    def from_margin(cls, tb: float, lr: float, /) -> Rect: ...
+
+    @overload
+    @classmethod
+    def from_margin(cls, t: float, lr: float, b: float, /) -> Rect: ...
+
+    @overload
+    @classmethod
+    def from_margin(cls, t: float, r: float, b: float, l: float, /) -> Rect: ...
+
+    @classmethod
+    def from_margin(cls, a: float, b: float | None = None, c: float | None = None, d: float | None = None, /) -> Self:
+        """Create a rectangle based on margins (edge distances) from the origin.
+
+        Compared to the regular [`Rect`][sonolus.script.quad.Rect] constructor, this method negates the bottom and
+        left values, and supports shorthands when fewer than four arguments are provided.
+
+        The following signatures are supported:
+
+        - `from_margin(trbl)`: All margins set to `trbl`.
+        - `from_margin(tb, lr)`: Top and bottom margins set to `tb`, left and right margins set to `lr`.
+        - `from_margin(t, lr, b)`: Top margin set to `t`, left and right margins set to `lr`, bottom margin set to `b`.
+        - `from_margin(t, r, b, l)`: Top, right, bottom, and left margins set to `t`, `r`, `b`, and `l` respectively.
+
+        Usage:
+            ```python
+            Rect.from_margin(1)  # Rect(t=1, r=1, b=-1, l=-1)
+            Rect.from_margin(1, 2)  # Rect(t=1, r=2, b=-1, l=-2)
+            Rect.from_margin(1, 2, 3)  # Rect(t=1, r=2, b=-3, l=-2)
+            Rect.from_margin(1, 2, 3, 4)  # Rect(t=1, r=2, b=-3, l=-4)
+            ```
+        """
+        args = (a, b, c, d)
+        match args:
+            case (a, None, None, None):
+                return cls(t=a, r=a, b=-a, l=-a)
+            case (a, b, None, None):
+                return cls(t=a, r=b, b=-a, l=-b)
+            case (a, b, c, None):
+                return cls(t=a, r=b, b=-c, l=-b)
+            case (a, b, c, d):
+                return cls(t=a, r=b, b=-c, l=-d)
+            case _:
+                assert_never(args)
+
     @property
     def w(self) -> float:
         """The width of the rectangle."""
@@ -260,6 +331,26 @@ class Rect(Record):
         """The center of the rectangle."""
         return Vec2((self.l + self.r) / 2, (self.t + self.b) / 2)
 
+    @property
+    def mt(self) -> Vec2:
+        """The middle-top point of the rectangle."""
+        return Vec2((self.l + self.r) / 2, self.t)
+
+    @property
+    def mr(self) -> Vec2:
+        """The middle-right point of the rectangle."""
+        return Vec2(self.r, (self.t + self.b) / 2)
+
+    @property
+    def mb(self) -> Vec2:
+        """The middle-bottom point of the rectangle."""
+        return Vec2((self.l + self.r) / 2, self.b)
+
+    @property
+    def ml(self) -> Vec2:
+        """The middle-left point of the rectangle."""
+        return Vec2(self.l, (self.t + self.b) / 2)
+
     def as_quad(self) -> Quad:
         """Convert the rectangle to a [`Quad`][sonolus.script.quad.Quad]."""
         return Quad(

sonolus/script/runtime.py

@@ -992,7 +992,7 @@ def time() -> float:
 def offset_adjusted_time() -> float:
     """Get the current time of the game adjusted by the input offset.
 
-    Returns 0 in preview mode and tutorial mode.
+    Returns 0 in preview mode and the current time without adjustment in tutorial mode.
     """
     if not ctx():
         return 0

sonolus/script/sprite.py

@@ -1,8 +1,11 @@
+from collections.abc import Iterable
 from dataclasses import dataclass
 from enum import StrEnum
 from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.ops import Op
+from sonolus.script.array_like import ArrayLike
+from sonolus.script.debug import static_error
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_function
 from sonolus.script.quad import QuadLike, flatten_quad
@@ -111,6 +114,29 @@ class Sprite(Record):
         _draw_curved_lr(self.id, *flatten_quad(quad), z, a, n, *cp1.tuple, *cp2.tuple)
 
 
+class SpriteGroup(Record, ArrayLike[Sprite]):
+    """A group of sprites.
+
+    Usage:
+        ```python
+        SpriteGroup(start_id: int, size: int)
+        ```
+    """
+
+    start_id: int
+    size: int
+
+    def __len__(self) -> int:
+        return self.size
+
+    def __getitem__(self, index: int) -> Sprite:
+        assert 0 <= index < self.size
+        return Sprite(self.start_id + index)
+
+    def __setitem__(self, index: int, value: Sprite) -> None:
+        static_error("SpriteGroup is read-only")
+
+
 @native_function(Op.HasSkinSprite)
 def _has_skin_sprite(sprite_id: int) -> bool:
     raise NotImplementedError
@@ -262,11 +288,21 @@ class SkinSprite:
     name: str
 
 
+@dataclass
+class SkinSpriteGroup:
+    names: list[str]
+
+
 def sprite(name: str) -> Any:
     """Define a sprite with the given name."""
     return SkinSprite(name)
 
 
+def sprite_group(names: Iterable[str]) -> Any:
+    """Define a sprite group with the given names."""
+    return SkinSpriteGroup(list(names))
+
+
 type Skin = NewType("Skin", Any)  # type: ignore
 
 
@@ -294,25 +330,44 @@ def skin[T](cls: type[T]) -> T | Skin:
             render_mode: RenderMode = RenderMode.LIGHTWEIGHT
 
             note: StandardSprite.NOTE_HEAD_RED
-            other: Sprite = skin_sprite("other")
+            other: Sprite = sprite("other")
+            group_1: SpriteGroup = sprite_group(["one", "two", "three"])
+            group_2: SpriteGroup = sprite_group(f"name_{i}" for i in range(10))
         ```
     """
     if len(cls.__bases__) != 1:
         raise ValueError("Skin class must not inherit from any class (except object)")
     instance = cls()
     names = []
-    for i, (name, annotation) in enumerate(get_field_specifiers(cls, skip={"render_mode"}).items()):
+    i = 0
+    for name, annotation in get_field_specifiers(cls, skip={"render_mode"}).items():
         if get_origin(annotation) is not Annotated:
-            raise TypeError(f"Invalid annotation for skin: {annotation}")
+            raise TypeError(f"Invalid annotation for skin: {annotation} on field {name}")
         annotation_type = annotation.__args__[0]
         annotation_values = annotation.__metadata__
-        if annotation_type is not Sprite:
-            raise TypeError(f"Invalid annotation for skin: {annotation}, expected annotation of type Sprite")
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], SkinSprite):
-            raise TypeError(f"Invalid annotation for skin: {annotation}, expected a single string annotation value")
-        sprite_name = annotation_values[0].name
-        names.append(sprite_name)
-        setattr(instance, name, Sprite(i))
+        if len(annotation_values) != 1:
+            raise TypeError(f"Invalid annotation for skin: {annotation} on field {name}, too many annotation values")
+        sprite_info = annotation_values[0]
+        match sprite_info:
+            case SkinSprite(name=sprite_name):
+                if annotation_type is not Sprite:
+                    raise TypeError(f"Invalid annotation for skin: {annotation} on field {name}, expected Sprite")
+                names.append(sprite_name)
+                setattr(instance, name, Sprite(i))
+                i += 1
+            case SkinSpriteGroup(names=sprite_names):
+                if annotation_type is not SpriteGroup:
+                    raise TypeError(f"Invalid annotation for skin: {annotation} on field {name}, expected SpriteGroup")
+                start_id = i
+                count = len(sprite_names)
+                names.extend(sprite_names)
+                setattr(instance, name, SpriteGroup(start_id, count))
+                i += count
+            case _:
+                raise TypeError(
+                    f"Invalid annotation for skin: {annotation} on field {name}, unknown sprite info, "
+                    f"expected a skin() or sprite_group() specifier"
+                )
     instance._sprites_ = names
     instance.render_mode = RenderMode(getattr(instance, "render_mode", RenderMode.DEFAULT))
     instance._is_comptime_value_ = True

{sonolus_py-0.7.0.dist-info → sonolus_py-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.7.0
+Version: 0.8.0
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12

{sonolus_py-0.7.0.dist-info → sonolus_py-0.8.0.dist-info}/RECORD

@@ -11,7 +11,7 @@ sonolus/backend/node.py,sha256=eEzPP14jzWJp2xrZCAaPlNtokxdoqg0bSM7xQiwx1j8,1254
 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
-sonolus/backend/visitor.py,sha256=oq8IhuuhigXMZtNgxD9ZjI_ZLVrp9ikFm9Yz636F5Fo,63102
+sonolus/backend/visitor.py,sha256=SIkrr7JOOQ4is9ov2siBpczpb_vWZZyckBQQr2BojrQ,63437
 sonolus/backend/optimize/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/backend/optimize/allocate.py,sha256=CuumoMphkpQlGRNeKLHT4FBGE0XVj5pwhfNdrqiLFSs,7535
 sonolus/backend/optimize/constant_evaluation.py,sha256=U--9moGsXFzrgweWWwHIiEuuMzwetd1IOjjtrCscoNM,21450
@@ -27,39 +27,39 @@ sonolus/backend/optimize/simplify.py,sha256=RDNVTKfC7ByRyxY5z30_ShimOAKth_pKlVFV
 sonolus/backend/optimize/ssa.py,sha256=raQO0furQQRPYb8iIBKfNrJlj-_5wqtI4EWNfLZ8QFo,10834
 sonolus/build/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/build/cli.py,sha256=-_lTN8zT7nQB2lySM8itAEPVutcEQI-TJ13BcPIfGb4,10113
-sonolus/build/collection.py,sha256=sMYLfEIVn6UydLy7iEnNwrpIXDs7bGG32uQQgHXyhSI,12289
-sonolus/build/compile.py,sha256=Yex-ZbSZmv9ujyAOVaMcfq-0NnZzFIqtmNYYaplF4Uc,6761
-sonolus/build/engine.py,sha256=xPhNnaFkfAuflp7CYb2NrXTgh9xCNN2h_hT_uWAYl1g,13445
+sonolus/build/collection.py,sha256=KgMfdLsCA7bheT-E2wmdB2OBEWolbsECm8vrwAhGC1c,12415
+sonolus/build/compile.py,sha256=mrbKTlhgu1x0YWijd1pIGHcOg0UTHPx4rEECPZuCRSM,6968
+sonolus/build/engine.py,sha256=YQ2Sc2zC56N2Y5S5zE3QCoUzwKcVHSPl14iQE0tkm6Q,13463
 sonolus/build/level.py,sha256=KLqUAtxIuIqrzeFURJA97rdqjA5pcvYSmwNZQhElaMQ,702
 sonolus/build/node.py,sha256=gnX71RYDUOK_gYMpinQi-bLWO4csqcfiG5gFmhxzSec,1330
-sonolus/build/project.py,sha256=h-9tcC60KqrpUOxGHFCK9trGVhGPUkciXiibasBEzu4,8097
+sonolus/build/project.py,sha256=__sOJas3RTwn4aizq16rYCvZgG8aX-JbQaxmfVhRnc4,8154
 sonolus/script/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sonolus/script/archetype.py,sha256=xoBVt4sQcC0e1ikyaM4NfcDZrMrJ0lHHUrxznl6dsU4,49492
+sonolus/script/archetype.py,sha256=xhdm1jO_p32V1NtGjgV0SGPm7X9GnJ6Z7hXi2zT69Ww,49647
 sonolus/script/array.py,sha256=9uOUHZIDMyMT9q3APcXJWXWt97yG-AZoRlxwrvSY6SU,12367
 sonolus/script/array_like.py,sha256=hUDdDaP306kflVv9YomdHIMXogrVjxsBXCrLvB9QpuE,9681
 sonolus/script/bucket.py,sha256=SNqnfLGpnO_u-3LFFazdgzNk332OdDUIlmZHsuoVZuE,7674
 sonolus/script/containers.py,sha256=L3rzPfN1cDb2m02k9qRyjnGxJx07X3q3MccCaL5tNJ8,18773
-sonolus/script/debug.py,sha256=Vi97opuk9fMB5bdpzPCBpa2oZeTff7FQ4WzdeDE5trk,4557
+sonolus/script/debug.py,sha256=KNc2zhzLzQr_YZV9BkZCX4GP00Sev2O23jb6PDpHC4w,5472
 sonolus/script/easing.py,sha256=2FUJI_nfp990P_armCcRqHm2329O985glJAhSC6tnxs,11379
-sonolus/script/effect.py,sha256=RQdsABqfi3sIku1jJDwyeD81devVyBhWQ47HIjfiMy0,5978
+sonolus/script/effect.py,sha256=pYihzdVOS3ekiiTwPVg6czUW1UNv0CJNIk-xBsYRdq8,7792
 sonolus/script/engine.py,sha256=etI9dJsQ7V9YZICVNZg54WqpLijPxG8eTPHiV-_EiG8,10687
 sonolus/script/globals.py,sha256=nlXSNS4NRXsgQU2AJImVIs752h1WqsMnShSKgU011c4,10270
 sonolus/script/instruction.py,sha256=Dd-14D5Amo8nhPBr6DNyg2lpYw_rqZkT8Kix3HkfE7k,6793
 sonolus/script/interval.py,sha256=dj6F2wn5uP6I6_mcZn-wIREgRUQbsLzhvhzB0oEyAdU,11290
 sonolus/script/iterator.py,sha256=_ICY_yX7FG0Zbgs3NhVnaIBdVDpAeXjxJ_CQtq30l7Y,3774
-sonolus/script/level.py,sha256=5M_XTzvXpFZTY-ODlS6M3GOiCIYN3F8rFuUgOiGxVBI,7824
+sonolus/script/level.py,sha256=X3-V99ihruYYCcPdch66dHi_ydCWXXn7epviLLjxW8w,8288
 sonolus/script/maybe.py,sha256=VYvTWgEfPzoXqI3i3zXhc4dz0pWBVoHmW8FtWH0GQvM,8194
 sonolus/script/metadata.py,sha256=ttRK27eojHf3So50KQJ-8yj3udZoN1bli5iD-knaeLw,753
-sonolus/script/num.py,sha256=924kWWZusW7oaWuvtQzdAMzkb4ZItWSJwNj3W9XrqZU,16041
+sonolus/script/num.py,sha256=s3Sl4nxZAjkOg-UwzJiWkUsV0lyJQPTOyjhAfzWFTf8,16137
 sonolus/script/options.py,sha256=XVN-mL7Rwhd2Tu9YysYq9YDGpH_LazdmhqzSYE6nR3Q,9455
-sonolus/script/particle.py,sha256=RTfamg_ZTq7-qJ6j9paduNVUHCkw3hzkBK1QUbwwN7I,8403
+sonolus/script/particle.py,sha256=rCEJGT7frqJqZLi4EBCqDs4QBvLW6Ys640nD1FxiVec,10326
 sonolus/script/pointer.py,sha256=FoOfyD93r0G5d_2BaKfeOT9SqkOP3hq6sqtOs_Rb0c8,1511
 sonolus/script/printing.py,sha256=mNYu9QWiacBBGZrnePZQMVwbbguoelUps9GiOK_aVRU,2096
-sonolus/script/project.py,sha256=a9bRY5T8deRMR35iC-6cuqn4HiKwZHvVy9K-np-rAfI,4432
-sonolus/script/quad.py,sha256=XoAjaUqR60zIrC_CwheZs7HwS-DRS58yUmlj9GIjX7k,11179
+sonolus/script/project.py,sha256=gG6mYsGlIqznY_RODyFMiXVBh0tVbXLAWZ5LHCiBIuU,4439
+sonolus/script/quad.py,sha256=9qUCOVirSShSE_hP9G0ZIkewNX990sw476PNwwJlWdU,14377
 sonolus/script/record.py,sha256=igmawc0hqb98YVcZnPTThHvnIP88Qelhoge4cNJx45Q,12770
-sonolus/script/runtime.py,sha256=rJZM_KbKmnwpjhDEpR0DrM6EMSEu46apIErWA_pfLJA,33321
-sonolus/script/sprite.py,sha256=kqFESwQjR-tTJ3EEMnXmMBxX-gCjtPYwF5Pgx1OInNM,16317
+sonolus/script/runtime.py,sha256=VwmW-8fy-uKyfUNewtXQhphmLZP7ugQeMWBFA8zi28w,33360
+sonolus/script/sprite.py,sha256=J4rA558MSNjNkI3KPnDp3R5RyJRmpi5P5cDfg6dKlIU,18065
 sonolus/script/stream.py,sha256=qVljaCxJJtQs7aBwfUG15pYvztb4jFYzSLGDh5t4DTA,24713
 sonolus/script/text.py,sha256=wxujIgKYcCfl2AD2_Im8g3vh0lDEHYwTSRZg9wsBPEU,13402
 sonolus/script/timing.py,sha256=DklMvuxcFg3MzXsecUo6Yhdk7pScOJ7STwXvAiTvLKM,3067
@@ -86,8 +86,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=DPNdmmRmupU8Ah4_XKq6-PdT336l4nt15_uCJKQGkkk,3587
 sonolus/script/internal/value.py,sha256=OngrCdmY_h6mV2Zgwqhuo4eYFad0kTk6263UAxctZcY,6963
-sonolus_py-0.7.0.dist-info/METADATA,sha256=aTrZv-zipIgHI36FFgSO_bmIjPOAixQa4-CdHcq7Cvc,302
-sonolus_py-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sonolus_py-0.7.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
-sonolus_py-0.7.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
-sonolus_py-0.7.0.dist-info/RECORD,,
+sonolus_py-0.8.0.dist-info/METADATA,sha256=Q-mtT3V7JhxLurDNDQyLmz5Hre95CGj-T-NHbh0hTMk,302
+sonolus_py-0.8.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sonolus_py-0.8.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
+sonolus_py-0.8.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
+sonolus_py-0.8.0.dist-info/RECORD,,