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

sonolus/script/level.py

@@ -1,7 +1,44 @@
 from __future__ import annotations
 
-from sonolus.build.collection import Asset
+import json
+from collections.abc import Iterator
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+from sonolus.build.collection import Asset, load_asset
 from sonolus.script.archetype import PlayArchetype, StandardArchetypeName, StandardImport
+from sonolus.script.metadata import AnyText, Tag, as_localization_text
+
+
+class ExportedLevel:
+    """An exported Sonolus level."""
+
+    def __init__(
+        self,
+        *,
+        item: dict,
+        cover: bytes,
+        bgm: bytes,
+        preview: bytes | None,
+        data: bytes,
+    ):
+        self.item = item
+        self.cover = cover
+        self.bgm = bgm
+        self.preview = preview
+        self.data = data
+
+    def write_to_dir(self, path: PathLike):
+        """Write the exported level 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 / "cover").write_bytes(self.cover)
+        (path / "bgm").write_bytes(self.bgm)
+        if self.preview is not None:
+            (path / "preview").write_bytes(self.preview)
+        (path / "data").write_bytes(self.data)
 
 
 class Level:
@@ -16,6 +53,13 @@ class Level:
         cover: The cover of the level.
         bgm: The background music of the level.
         data: The data of the level.
+        use_skin: The skin to use, overriding the engine skin.
+        use_background: The background to use, overriding the engine background.
+        use_effect: The effect to use, overriding the engine effect.
+        use_particle: The particle to use, overriding the engine particle.
+        tags: The tags of the level.
+        description: The description of the level.
+        meta: Additional metadata of the level.
     """
 
     version = 1
@@ -24,35 +68,94 @@ class Level:
         self,
         *,
         name: str,
-        title: str | None = None,
+        title: AnyText | None = None,
         rating: int = 0,
-        artists: str = "Unknown",
-        author: str = "Unknown",
+        artists: AnyText = "Unknown",
+        author: AnyText = "Unknown",
         cover: Asset | None = None,
         bgm: Asset | None = None,
+        preview: Asset | None = None,
         data: LevelData,
+        use_skin: str | None = None,
+        use_background: str | None = None,
+        use_effect: str | None = None,
+        use_particle: str | None = None,
+        tags: list[Tag] | None = None,
+        description: AnyText | None = None,
+        meta: Any = None,
     ) -> None:
         self.name = name
-        self.title = title or name
+        self.title = as_localization_text(title or name)
         self.rating = rating
-        self.artists = artists
-        self.author = author
+        self.artists = as_localization_text(artists)
+        self.author = as_localization_text(author)
         self.cover = cover
         self.bgm = bgm
+        self.preview = preview
         self.data = data
+        self.use_skin = use_skin
+        self.use_background = use_background
+        self.use_effect = use_effect
+        self.use_particle = use_particle
+        self.tags = tags or []
+        self.description = as_localization_text(description) if description is not None else None
+        self.meta = meta
+
+    def export(self, engine_name: str) -> ExportedLevel:
+        """Export the level in a sonolus-pack compatible format.
+
+        Args:
+            engine_name: The name of the engine this level is for.
+
+        Returns:
+            The exported level.
+        """
+        from sonolus.build.level import package_level_data
+        from sonolus.build.project import BLANK_AUDIO, BLANK_PNG
+
+        item = {
+            "version": self.version,
+            "rating": self.rating,
+            "engine": engine_name,
+            "useSkin": {"useDefault": True} if self.use_skin is None else {"useDefault": False, "item": self.use_skin},
+            "useBackground": {"useDefault": True}
+            if self.use_background is None
+            else {"useDefault": False, "item": self.use_background},
+            "useEffect": {"useDefault": True}
+            if self.use_effect is None
+            else {"useDefault": False, "item": self.use_effect},
+            "useParticle": {"useDefault": True}
+            if self.use_particle is None
+            else {"useDefault": False, "item": self.use_particle},
+            "title": self.title,
+            "artists": self.artists,
+            "author": self.author,
+            "tags": [tag.as_dict() for tag in self.tags],
+        }
+        if self.description is not None:
+            item["description"] = self.description
+        if self.meta is not None:
+            item["meta"] = self.meta
+        return ExportedLevel(
+            item=item,
+            cover=load_asset(self.cover) if self.cover is not None else BLANK_PNG,
+            bgm=load_asset(self.bgm) if self.bgm is not None else BLANK_AUDIO,
+            preview=load_asset(self.preview) if self.preview is not None else None,
+            data=package_level_data(self.data),
+        )
 
 
 type EntityListArg = list[PlayArchetype | EntityListArg]
 
 
-def flatten_entities(entities: EntityListArg):
+def flatten_entities(entities: EntityListArg) -> Iterator[PlayArchetype]:
     """Flatten a list of entities.
 
     Args:
         entities: The list of entities.
 
-    Returns:
-        The flattened list of entities.
+    Yields:
+        The flattened entities.
     """
     if isinstance(entities, list):
         for entity in entities:

sonolus/script/metadata.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+type LocalizationText = dict[str, str]
+type AnyText = str | LocalizationText
+
+
+def as_localization_text(text: AnyText) -> LocalizationText:
+    if isinstance(text, str):
+        return {"en": text}
+    return text
+
+
+class Tag:
+    """A tag for an engine or level.
+
+    Args:
+        title: The title of the tag.
+        icon: The icon of the tag.
+    """
+
+    title: LocalizationText
+    icon: str | None
+
+    def __init__(self, title: AnyText, icon: str | None = None) -> None:
+        self.title = as_localization_text(title)
+        self.icon = icon
+
+    def as_dict(self) -> dict[str, Any]:
+        result = {"title": self.title}
+        if self.icon is not None:
+            result["icon"] = self.icon
+        return result

sonolus/script/num.py

@@ -7,11 +7,11 @@ from typing import TYPE_CHECKING, Any, Self, TypeGuard, final, runtime_checkable
 
 from sonolus.backend.ir import IRConst, IRGet, IRPureInstr, IRSet
 from sonolus.backend.ops import Op
-from sonolus.backend.place import BlockPlace, Place
+from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.error import InternalError
 from sonolus.script.internal.impl import meta_fn
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingValue, DataValue, Value
 
 
 class _NumMeta(type):
@@ -30,15 +30,17 @@ class _Num(Value, metaclass=_NumMeta):
     # Since we don't support complex numbers, real is equal to the original number
     __match_args__ = ("real",)
 
-    data: BlockPlace | float | int | bool
+    data: DataValue
 
-    def __init__(self, data: Place | float | int | bool):
+    def __init__(self, data: DataValue):
         if isinstance(data, complex):
             raise TypeError("Cannot create a Num from a complex number")
         if isinstance(data, int):
             data = float(data)
         if _is_num(data):
             raise InternalError("Cannot create a Num from a Num")
+        if not isinstance(data, BlockPlace | BackingValue | float | int | bool):
+            raise TypeError(f"Cannot create a Num from {type(data)}")
         self.data = data
 
     def __str__(self) -> str:
@@ -78,7 +80,7 @@ class _Num(Value, metaclass=_NumMeta):
         return cls(value)
 
     def _is_py_(self) -> bool:
-        return not isinstance(self.data, BlockPlace)
+        return isinstance(self.data, float | int | bool)
 
     def _as_py_(self) -> Any:
         if not self._is_py_():
@@ -88,11 +90,11 @@ class _Num(Value, metaclass=_NumMeta):
         return self.data
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         value = next(iter(values))
         return Num(value)
 
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue]:
         return [self.data]
 
     @classmethod
@@ -111,10 +113,14 @@ class _Num(Value, metaclass=_NumMeta):
 
     def _set_(self, value: Self):
         if ctx():
-            if not isinstance(self.data, BlockPlace):
-                raise ValueError("Cannot set a compile time constant value")
-            ctx().check_writable(self.data)
-            ctx().add_statements(IRSet(self.data, value.ir()))
+            match self.data:
+                case BackingValue():
+                    ctx().add_statements(self.data.write(value))
+                case BlockPlace():
+                    ctx().check_writable(self.data)
+                    ctx().add_statements(IRSet(self.data, value.ir()))
+                case _:
+                    raise ValueError("Cannot set a read-only value")
         else:
             self.data = value.data
 
@@ -134,13 +140,27 @@ class _Num(Value, metaclass=_NumMeta):
         else:
             return Num(-1)
 
-    def ir(self):
-        if isinstance(self.data, BlockPlace):
-            return IRGet(self.data)
+    @classmethod
+    def _zero_(cls) -> Self:
+        if ctx():
+            result_place = ctx().alloc(size=1)
+            ctx().add_statements(IRSet(result_place, IRConst(0)))
+            return cls(result_place)
         else:
-            return IRConst(self.data)
+            return cls(0)
+
+    def ir(self):
+        match self.data:
+            case BlockPlace():
+                return IRGet(self.data)
+            case BackingValue():
+                return self.data.read()
+            case _:
+                return IRConst(self.data)
 
     def index(self) -> int | BlockPlace:
+        if isinstance(self.data, BlockPlace):
+            return self._get_().data
         return self.data
 
     def _bin_op(self, other: Self, const_fn: Callable[[Self, Self], Self | None], ir_op: Op) -> Self:

sonolus/script/options.py

@@ -15,6 +15,7 @@ from sonolus.script.num import Num
 @dataclass
 class _SliderOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
@@ -35,6 +36,8 @@ class _SliderOption:
             "max": self.max,
             "step": self.step,
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         if self.unit is not None:
@@ -45,6 +48,7 @@ class _SliderOption:
 @dataclass
 class _ToggleOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
@@ -58,6 +62,8 @@ class _ToggleOption:
             "advanced": self.advanced,
             "def": int(self.default),
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         return result
@@ -66,10 +72,11 @@ class _ToggleOption:
 @dataclass
 class _SelectOption:
     name: str | None
+    description: str | None
     standard: bool
     advanced: bool
     scope: str | None
-    default: str
+    default: int
     values: list[str]
 
     def to_dict(self):
@@ -78,9 +85,11 @@ class _SelectOption:
             "name": self.name,
             "standard": self.standard,
             "advanced": self.advanced,
-            "def": self.values.index(self.default),
+            "def": self.default,
             "values": self.values,
         }
+        if self.description is not None:
+            result["description"] = self.description
         if self.scope is not None:
             result["scope"] = self.scope
         return result
@@ -89,6 +98,7 @@ class _SelectOption:
 def slider_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
     default: float,
@@ -102,6 +112,7 @@ def slider_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
@@ -111,12 +122,13 @@ def slider_option(
         unit: The unit of the option.
         scope: The scope of the option.
     """
-    return _SliderOption(name, standard, advanced, scope, default, min, max, step, unit)
+    return _SliderOption(name, description, standard, advanced, scope, default, min, max, step, unit)
 
 
 def toggle_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
     default: bool,
@@ -126,20 +138,22 @@ def toggle_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
         scope: The scope of the option.
     """
-    return _ToggleOption(name, standard, advanced, scope, default)
+    return _ToggleOption(name, description, standard, advanced, scope, default)
 
 
 def select_option(
     *,
     name: str | None = None,
+    description: str | None = None,
     standard: bool = False,
     advanced: bool = False,
-    default: str,
+    default: str | int,
     values: list[str],
     scope: str | None = None,
 ) -> Any:
@@ -147,13 +161,16 @@ def select_option(
 
     Args:
         name: The name of the option.
+        description: The description of the option.
         standard: Whether the option is standard.
         advanced: Whether the option is advanced.
         default: The default value of the option.
         values: The values of the option.
         scope: The scope of the option.
     """
-    return _SelectOption(name, standard, advanced, scope, default, values)
+    if isinstance(default, str):
+        default = values.index(default)
+    return _SelectOption(name, description, standard, advanced, scope, default, values)
 
 
 type Options = NewType("Options", Any)

sonolus/script/pointer.py

@@ -1,6 +1,7 @@
 from sonolus.backend.place import BlockPlace
+from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn, validate_value
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingSource, Value
 from sonolus.script.num import Num, _is_num
 
 
@@ -13,6 +14,7 @@ def _deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
         block = block._as_py_()
         if not isinstance(block, int):
             raise TypeError("block must be an integer")
+        block = ctx().blocks(block)
     else:
         if not _is_num(block):
             raise TypeError("block must be a Num")
@@ -28,3 +30,11 @@ def _deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
     if not (isinstance(type_, type) and issubclass(type_, Value)):
         raise TypeError("type_ must be a Value")
     return type_._from_place_(BlockPlace(block, offset))
+
+
+@meta_fn
+def _backing_deref[T: Value](source: BackingSource, type_: type[T]) -> T:
+    type_ = validate_value(type_)._as_py_()
+    if not isinstance(type_, type) or not issubclass(type_, Value):
+        raise TypeError("type_ must be a Value")
+    return type_._from_backing_source_(source)

sonolus/script/project.py

@@ -1,9 +1,13 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
+from dataclasses import dataclass
 from os import PathLike
 from pathlib import Path
-from typing import Self, TypedDict
+from typing import ClassVar, Self, TypedDict
 
+from sonolus.backend.optimize import optimize
+from sonolus.backend.optimize.passes import CompilerPass
 from sonolus.script.archetype import ArchetypeSchema
 from sonolus.script.engine import Engine
 from sonolus.script.level import Level
@@ -39,27 +43,30 @@ class Project:
         """
         return Project(self.engine, levels, self.resources)
 
-    def dev(self, build_dir: PathLike, port: int = 8080):
+    def dev(self, build_dir: PathLike, port: int = 8080, config: BuildConfig | None = None):
         """Start a development server for the project.
 
         Args:
             build_dir: The path to the build directory.
             port: The port of the development server.
+            config: The build configuration.
         """
         from sonolus.build.cli import build_collection, run_server
 
-        build_collection(self, Path(build_dir))
+        build_collection(self, Path(build_dir), config)
         run_server(Path(build_dir) / "site", port=port)
 
-    def build(self, build_dir: PathLike):
+    def build(self, build_dir: PathLike, config: BuildConfig | None = None):
         """Build the project.
 
         Args:
             build_dir: The path to the build directory.
+            config: The build configuration.
         """
         from sonolus.build.cli import build_project
 
-        build_project(self, Path(build_dir))
+        config = config or BuildConfig()
+        build_project(self, Path(build_dir), config)
 
     def schema(self) -> ProjectSchema:
         """Generate the schema of the project.
@@ -74,3 +81,32 @@ class Project:
 
 class ProjectSchema(TypedDict):
     archetypes: list[ArchetypeSchema]
+
+
+@dataclass
+class BuildConfig:
+    """A configuration for building an engine package."""
+
+    MINIMAL_PASSES: ClassVar[Sequence[CompilerPass]] = optimize.MINIMAL_PASSES
+    """The minimal list of compiler passes."""
+
+    FAST_PASSES: ClassVar[Sequence[CompilerPass]] = optimize.FAST_PASSES
+    """The list of compiler passes for faster builds."""
+
+    STANDARD_PASSES: ClassVar[Sequence[CompilerPass]] = optimize.STANDARD_PASSES
+    """The standard list of compiler passes."""
+
+    passes: Sequence[CompilerPass] = optimize.STANDARD_PASSES
+    """The list of compiler passes to use."""
+
+    build_play: bool = True
+    """Whether to build the play package."""
+
+    build_watch: bool = True
+    """Whether to build the watch package."""
+
+    build_preview: bool = True
+    """Whether to build the preview package."""
+
+    build_tutorial: bool = True
+    """Whether to build the tutorial package."""

sonolus/script/quad.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Protocol, Self
 
 from sonolus.script.record import Record
+from sonolus.script.values import zeros
 from sonolus.script.vec import Vec2, pnpoly
 
 
@@ -27,6 +28,16 @@ class Quad(Record):
     br: Vec2
     """The bottom-right corner of the quad."""
 
+    @classmethod
+    def from_quad(cls, value: QuadLike, /) -> Quad:
+        """Create a quad from a quad-like value."""
+        return cls(
+            bl=value.bl,
+            tl=value.tl,
+            tr=value.tr,
+            br=value.br,
+        )
+
     @property
     def center(self) -> Vec2:
         """The center of the quad."""
@@ -95,6 +106,44 @@ class Quad(Record):
         """Rotate the quad by the given angle about its center and return a new quad."""
         return self.rotate_about(angle, self.center)
 
+    def permute(self, count: int = 1, /) -> Self:
+        """Perform a cyclic permutation of the quad's vertices and return a new quad.
+
+        On a square, this operation is equivalent to rotating the square counterclockwise 90 degrees `count` times.
+
+        Negative values of `count` are allowed and will rotate the quad clockwise.
+
+        Args:
+            count: The number of vertices to shift. Defaults to 1.
+
+        Returns:
+            The permuted quad.
+        """
+        count = int(count % 4)
+        result = zeros(Quad)
+        match count:
+            case 0:
+                result.bl @= self.bl
+                result.tl @= self.tl
+                result.tr @= self.tr
+                result.br @= self.br
+            case 1:
+                result.bl @= self.br
+                result.tl @= self.bl
+                result.tr @= self.tl
+                result.br @= self.tr
+            case 2:
+                result.bl @= self.tr
+                result.tl @= self.br
+                result.tr @= self.bl
+                result.br @= self.tl
+            case 3:
+                result.bl @= self.tl
+                result.tl @= self.tr
+                result.tr @= self.br
+                result.br @= self.bl
+        return result
+
     def contains_point(self, point: Vec2, /) -> bool:
         """Check if the quad contains the given point.
 
@@ -248,7 +297,7 @@ class Rect(Record):
         return self.l <= point.x <= self.r and self.b <= point.y <= self.t
 
 
-class QuadLike(Protocol):
+class _QuadLike(Protocol):
     """A protocol for types that can be used as quads."""
 
     @property
@@ -268,6 +317,11 @@ class QuadLike(Protocol):
         """The bottom-right corner of the quad."""
 
 
+# PyCharm doesn't recognize attributes as satisfying the protocol.
+type QuadLike = _QuadLike | Quad
+"""A type that can be used as a quad."""
+
+
 def flatten_quad(quad: QuadLike) -> tuple[float, float, float, float, float, float, float, float]:
     bl = quad.bl
     tl = quad.tl

sonolus/script/record.py

@@ -16,7 +16,7 @@ from sonolus.script.internal.generic import (
     validate_type_spec,
 )
 from sonolus.script.internal.impl import meta_fn
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import DataValue, Value
 from sonolus.script.num import Num
 
 
@@ -182,11 +182,11 @@ class Record(GenericValue):
         return self
 
     @classmethod
-    def _from_list_(cls, values: Iterable[float | BlockPlace]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
         iterator = iter(values)
         return cls(**{field.name: field.type._from_list_(iterator) for field in cls._fields})
 
-    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         result = []
         for field in self._fields:
             result.extend(self._value[field.name]._to_list_(level_refs))
@@ -206,8 +206,7 @@ class Record(GenericValue):
         raise TypeError("Record does not support set_")
 
     def _copy_from_(self, value: Self):
-        if not isinstance(value, type(self)):
-            raise TypeError("Cannot copy from different type")
+        value = self._accept_(value)
         for field in self._fields:
             field.__set__(self, field.__get__(value))
 
@@ -221,6 +220,12 @@ class Record(GenericValue):
         result._value = {field.name: field.type._alloc_() for field in cls._fields}
         return result
 
+    @classmethod
+    def _zero_(cls) -> Self:
+        result = object.__new__(cls)
+        result._value = {field.name: field.type._zero_() for field in cls._fields}
+        return result
+
     def __str__(self):
         return (
             f"{self.__class__.__name__}({", ".join(f"{field.name}={field.__get__(self)}" for field in self._fields)})"