sonolus.py 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

sonolus/backend/mode.py

@@ -7,10 +7,10 @@ from sonolus.backend.blocks import Block, PlayBlock, PreviewBlock, TutorialBlock
 class Mode(Enum):
     blocks: type[Block]
 
-    Play = (PlayBlock,)
-    Watch = (WatchBlock,)
-    Preview = (PreviewBlock,)
-    Tutorial = (TutorialBlock,)
+    PLAY = (PlayBlock,)
+    WATCH = (WatchBlock,)
+    PREVIEW = (PreviewBlock,)
+    TUTORIAL = (TutorialBlock,)
 
     def __init__(self, blocks: type[Block]):
         self.blocks = blocks

sonolus/backend/visitor.py

@@ -17,7 +17,7 @@ from sonolus.script.internal.error import CompilationError
 from sonolus.script.internal.impl import try_validate_value, validate_value
 from sonolus.script.internal.value import Value
 from sonolus.script.iterator import SonolusIterator
-from sonolus.script.num import Num
+from sonolus.script.num import Num, is_num
 
 _compiler_internal_ = True
 
@@ -622,6 +622,8 @@ class Visitor(ast.NodeVisitor):
 
     def visit_Call(self, node):
         fn = self.visit(node.func)
+        if fn is Num:
+            raise ValueError("Calling int/bool/float is not supported")
         args = []
         kwargs = {}
         for arg in node.args:
@@ -833,7 +835,7 @@ class Visitor(ast.NodeVisitor):
 
     def ensure_boolean_num(self, value) -> Num:
         # This just checks the type for now, although we could support custom __bool__ implementations in the future
-        if not isinstance(value, Num):
+        if not is_num(value):
             raise TypeError(f"Invalid type where a bool (Num) was expected: {type(value).__name__}")
         return value
 

sonolus/build/compile.py

@@ -19,7 +19,7 @@ from sonolus.script.internal.context import (
     ctx,
     using_ctx,
 )
-from sonolus.script.num import Num
+from sonolus.script.num import is_num
 
 
 def compile_mode(
@@ -43,7 +43,7 @@ def compile_mode(
             archetype_data["imports"] = [
                 {"name": name, "index": index} for name, index in archetype._imported_keys_.items()
             ]
-            if mode == Mode.Play:
+            if mode == Mode.PLAY:
                 archetype_data["exports"] = [
                     {"name": name, "index": index} for name, index in archetype._exported_keys_.items()
                 ]
@@ -85,6 +85,6 @@ def callback_to_cfg(
             result = compile_and_call(callback, archetype._for_compilation())
         else:
             result = compile_and_call(callback)
-        if isinstance(result, Num):
+        if is_num(result):
             ctx().add_statements(IRInstr(Op.Break, [IRConst(1), result.ir()]))
     return context_to_cfg(context)

sonolus/build/engine.py

@@ -7,12 +7,15 @@ from pathlib import Path
 
 from sonolus.backend.mode import Mode
 from sonolus.build.compile import compile_mode
-from sonolus.build.defaults import EMPTY_ENGINE_PREVIEW_DATA, EMPTY_ENGINE_TUTORIAL_DATA
 from sonolus.script.archetype import BaseArchetype
 from sonolus.script.bucket import Buckets
-from sonolus.script.callbacks import update_spawn_callback
+from sonolus.script.callbacks import navigate_callback, preprocess_callback, update_callback, update_spawn_callback
 from sonolus.script.effect import Effects
 from sonolus.script.engine import EngineData
+from sonolus.script.instruction import (
+    TutorialInstructionIcons,
+    TutorialInstructions,
+)
 from sonolus.script.internal.context import ReadOnlyMemory
 from sonolus.script.options import Options
 from sonolus.script.particle import Particles
@@ -61,12 +64,28 @@ def package_engine(engine: EngineData):
         rom=rom,
         update_spawn=engine.watch.update_spawn,
     )
+    preview_data = build_preview_mode(
+        archetypes=engine.preview.archetypes,
+        skin=engine.preview.skin,
+        rom=rom,
+    )
+    tutorial_data = build_tutorial_mode(
+        skin=engine.tutorial.skin,
+        effects=engine.tutorial.effects,
+        particles=engine.tutorial.particles,
+        instructions=engine.tutorial.instructions,
+        instruction_icons=engine.tutorial.instruction_icons,
+        preprocess=engine.tutorial.preprocess,
+        navigate=engine.tutorial.navigate,
+        update=engine.tutorial.update,
+        rom=rom,
+    )
     return PackagedEngine(
         configuration=package_output(configuration),
         play_data=package_output(play_data),
         watch_data=package_output(watch_data),
-        preview_data=package_output(EMPTY_ENGINE_PREVIEW_DATA),
-        tutorial_data=package_output(EMPTY_ENGINE_TUTORIAL_DATA),
+        preview_data=package_output(preview_data),
+        tutorial_data=package_output(tutorial_data),
         rom=package_rom(rom),
     )
 
@@ -90,7 +109,7 @@ def build_play_mode(
     rom: ReadOnlyMemory,
 ):
     return {
-        **compile_mode(mode=Mode.Play, rom=rom, archetypes=archetypes, global_callbacks=None),
+        **compile_mode(mode=Mode.PLAY, rom=rom, archetypes=archetypes, global_callbacks=None),
         "skin": build_skin(skin),
         "effect": build_effects(effects),
         "particle": build_particles(particles),
@@ -109,7 +128,7 @@ def build_watch_mode(
 ):
     return {
         **compile_mode(
-            mode=Mode.Watch, rom=rom, archetypes=archetypes, global_callbacks=[(update_spawn_callback, update_spawn)]
+            mode=Mode.WATCH, rom=rom, archetypes=archetypes, global_callbacks=[(update_spawn_callback, update_spawn)]
         ),
         "skin": build_skin(skin),
         "effect": build_effects(effects),
@@ -118,6 +137,46 @@ def build_watch_mode(
     }
 
 
+def build_preview_mode(
+    archetypes: list[type[BaseArchetype]],
+    skin: Skin,
+    rom: ReadOnlyMemory,
+):
+    return {
+        **compile_mode(mode=Mode.PREVIEW, rom=rom, archetypes=archetypes, global_callbacks=None),
+        "skin": build_skin(skin),
+    }
+
+
+def build_tutorial_mode(
+    skin: Skin,
+    effects: Effects,
+    particles: Particles,
+    instructions: TutorialInstructions,
+    instruction_icons: TutorialInstructionIcons,
+    preprocess: Callable[[], None],
+    navigate: Callable[[int], None],
+    update: Callable[[], None],
+    rom: ReadOnlyMemory,
+):
+    return {
+        **compile_mode(
+            mode=Mode.TUTORIAL,
+            rom=rom,
+            archetypes=[],
+            global_callbacks=[
+                (preprocess_callback, preprocess),
+                (navigate_callback, navigate),
+                (update_callback, update),
+            ],
+        ),
+        "skin": build_skin(skin),
+        "effect": build_effects(effects),
+        "particle": build_particles(particles),
+        "instruction": build_instructions(instructions, instruction_icons),
+    }
+
+
 def build_skin(skin: Skin) -> JsonValue:
     return {"sprites": [{"name": name, "id": i} for i, name in enumerate(skin._sprites_)]}
 
@@ -134,6 +193,13 @@ def build_buckets(buckets: Buckets) -> JsonValue:
     return [bucket.to_dict() for bucket in buckets._buckets_]
 
 
+def build_instructions(instructions: TutorialInstructions, instruction_icons: TutorialInstructionIcons) -> JsonValue:
+    return {
+        "texts": [{"name": name, "id": i} for i, name in enumerate(instructions._instructions_)],
+        "icons": [{"name": name, "id": i} for i, name in enumerate(instruction_icons._instruction_icons_)],
+    }
+
+
 def package_rom(rom: ReadOnlyMemory) -> bytes:
     values = rom.values or [0]
     output = bytearray()

sonolus/script/archetype.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import inspect
 from collections.abc import Callable
 from dataclasses import dataclass
-from enum import Enum
+from enum import Enum, StrEnum
 from types import FunctionType
 from typing import Annotated, Any, ClassVar, Self, get_origin
 
@@ -11,7 +11,7 @@ from sonolus.backend.ir import IRConst, IRInstr
 from sonolus.backend.mode import Mode
 from sonolus.backend.ops import Op
 from sonolus.script.bucket import Bucket, Judgment
-from sonolus.script.callbacks import PLAY_CALLBACKS, WATCH_ARCHETYPE_CALLBACKS, CallbackInfo
+from sonolus.script.callbacks import PLAY_CALLBACKS, PREVIEW_CALLBACKS, WATCH_ARCHETYPE_CALLBACKS, CallbackInfo
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.descriptor import SonolusDescriptor
 from sonolus.script.internal.generic import validate_concrete_type
@@ -174,11 +174,11 @@ _annotation_defaults: dict[Callable, ArchetypeFieldInfo] = {
 
 
 class StandardImport:
-    Beat = Annotated[float, imported(name="#BEAT")]
-    Bpm = Annotated[float, imported(name="#BPM")]
-    Timescale = Annotated[float, imported(name="#TIMESCALE")]
-    Judgment = Annotated[int, imported(name="#JUDGMENT")]
-    Accuracy = Annotated[float, imported(name="#ACCURACY")]
+    BEAT = Annotated[float, imported(name="#BEAT")]
+    BPM = Annotated[float, imported(name="#BPM")]
+    TIMESCALE = Annotated[float, imported(name="#TIMESCALE")]
+    JUDGMENT = Annotated[int, imported(name="#JUDGMENT")]
+    ACCURACY = Annotated[float, imported(name="#ACCURACY")]
 
 
 def callback[T: Callable](order: int) -> Callable[[T], T]:
@@ -559,16 +559,42 @@ class WatchArchetype(BaseArchetype):
         self.result.target_time = value
 
 
+class PreviewArchetype(BaseArchetype):
+    _supported_callbacks_ = PREVIEW_CALLBACKS
+
+    def preprocess(self):
+        pass
+
+    def render(self):
+        pass
+
+    @property
+    def _info(self) -> PreviewEntityInfo:
+        if not ctx():
+            raise RuntimeError("Calling info is only allowed within a callback")
+        match self._data_:
+            case ArchetypeSelfData():
+                return deref(ctx().blocks.EntityInfo, 0, PreviewEntityInfo)
+            case ArchetypeReferenceData(index=index):
+                return deref(ctx().blocks.EntityInfoArray, index * PreviewEntityInfo._size_(), PreviewEntityInfo)
+            case _:
+                raise RuntimeError("Info is only accessible from the entity itself")
+
+    @property
+    def index(self) -> int:
+        return self._info.index
+
+
 @meta_fn
 def entity_info_at(index: Num) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
     if not ctx():
         raise RuntimeError("Calling entity_info_at is only allowed within a callback")
     match ctx().global_state.mode:
-        case Mode.Play:
+        case Mode.PLAY:
             return deref(ctx().blocks.EntityInfoArray, index * PlayEntityInfo._size_(), PlayEntityInfo)
-        case Mode.Watch:
+        case Mode.WATCH:
             return deref(ctx().blocks.EntityInfoArray, index * WatchEntityInfo._size_(), WatchEntityInfo)
-        case Mode.Preview:
+        case Mode.PREVIEW:
             return deref(ctx().blocks.EntityInfoArray, index * PreviewEntityInfo._size_(), PreviewEntityInfo)
         case _:
             raise RuntimeError(f"Entity info is not available in mode '{ctx().global_state.mode}'")
@@ -581,7 +607,7 @@ def archetype_life_of(archetype: type[BaseArchetype] | BaseArchetype) -> Archety
     if not ctx():
         raise RuntimeError("Calling archetype_life_of is only allowed within a callback")
     match ctx().global_state.mode:
-        case Mode.Play | Mode.Watch:
+        case Mode.PLAY | Mode.WATCH:
             return deref(ctx().blocks.ArchetypeLife, archetype.id() * ArchetypeLife._size_(), ArchetypeLife)
         case _:
             raise RuntimeError(f"Archetype life is not available in mode '{ctx().global_state.mode}'")
@@ -649,3 +675,8 @@ class EntityRef[A: BaseArchetype](Record):
 
     def get(self) -> A:
         return self.archetype().at(Num(self.index))
+
+
+class StandardArchetypeName(StrEnum):
+    BPM_CHANGE = "#BPM_CHANGE"
+    TIMESCALE_CHANGE = "#TIMESCALE_CHANGE"

sonolus/script/bucket.py

@@ -88,9 +88,9 @@ class Bucket(Record):
         if not ctx():
             raise RuntimeError("Bucket window access outside of compilation")
         match ctx().global_state.mode:
-            case Mode.Play:
+            case Mode.PLAY:
                 return deref(ctx().blocks.LevelBucket, self.id * JudgmentWindow._size_(), JudgmentWindow)
-            case Mode.Watch:
+            case Mode.WATCH:
                 return deref(ctx().blocks.LevelBucket, self.id * JudgmentWindow._size_(), JudgmentWindow)
             case _:
                 raise RuntimeError("Invalid mode for bucket window access")

sonolus/script/callbacks.py

@@ -75,6 +75,24 @@ update_spawn_callback = CallbackInfo(
     supports_order=False,
     returns_value=True,
 )
+render_callback = CallbackInfo(
+    name="render",
+    py_name="render",
+    supports_order=False,
+    returns_value=False,
+)
+navigate_callback = CallbackInfo(
+    name="navigate",
+    py_name="navigate",
+    supports_order=False,
+    returns_value=False,
+)
+update_callback = CallbackInfo(
+    name="update",
+    py_name="update",
+    supports_order=False,
+    returns_value=False,
+)
 
 
 def _by_name(*callbacks: CallbackInfo) -> dict[str, CallbackInfo]:
@@ -103,3 +121,7 @@ WATCH_ARCHETYPE_CALLBACKS = _by_name(
 WATCH_GLOBAL_CALLBACKS = _by_name(
     update_spawn_callback,
 )
+PREVIEW_CALLBACKS = _by_name(
+    preprocess_callback,
+    render_callback,
+)

sonolus/script/comptime.py

@@ -3,6 +3,7 @@ from typing import TYPE_CHECKING, Any, Self, TypeVar, final
 
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.generic import GenericValue
+from sonolus.script.internal.impl import meta_fn, validate_value
 
 
 @final
@@ -92,6 +93,19 @@ class _Comptime[T, V](GenericValue):
     def _copy_(self) -> Self:
         return self
 
+    @meta_fn
+    def __eq__(self, other):
+        other = validate_value(other)
+        match self.value():
+            case str():
+                return other._is_py_() and other._as_py_() == self.value()
+            case _:
+                raise TypeError("Unsupported comparison with comptime value")
+
+    @meta_fn
+    def __hash__(self):
+        return hash(self.value())
+
     @classmethod
     def _alloc_(cls) -> Self:
         return cls._instance

sonolus/script/debug.py

@@ -65,6 +65,6 @@ def terminate():
 def visualize_cfg(fn: Callable[[], Any]) -> str:
     from sonolus.build.compile import callback_to_cfg
 
-    cfg = callback_to_cfg(GlobalContextState(Mode.Play), fn, "")
+    cfg = callback_to_cfg(GlobalContextState(Mode.PLAY), fn, "")
     cfg = CoalesceFlow().run(cfg)
     return cfg_to_mermaid(cfg)

sonolus/script/effect.py

@@ -113,17 +113,17 @@ def effects[T](cls: type[T]) -> T | Effects:
 
 
 class StandardEffect:
-    Miss = Annotated[Effect, effect("#MISS")]
-    Perfect = Annotated[Effect, effect("#PERFECT")]
-    Great = Annotated[Effect, effect("#GREAT")]
-    Good = Annotated[Effect, effect("#GOOD")]
-    Hold = Annotated[Effect, effect("#HOLD")]
-    MissAlternative = Annotated[Effect, effect("#MISS_ALTERNATIVE")]
-    PerfectAlternative = Annotated[Effect, effect("#PERFECT_ALTERNATIVE")]
-    GreatAlternative = Annotated[Effect, effect("#GREAT_ALTERNATIVE")]
-    GoodAlternative = Annotated[Effect, effect("#GOOD_ALTERNATIVE")]
-    HoldAlternative = Annotated[Effect, effect("#HOLD_ALTERNATIVE")]
-    Stage = Annotated[Effect, effect("#STAGE")]
+    MISS = Annotated[Effect, effect("#MISS")]
+    PERFECT = Annotated[Effect, effect("#PERFECT")]
+    GREAT = Annotated[Effect, effect("#GREAT")]
+    GOOD = Annotated[Effect, effect("#GOOD")]
+    HOLD = Annotated[Effect, effect("#HOLD")]
+    MISS_ALTERNATIVE = Annotated[Effect, effect("#MISS_ALTERNATIVE")]
+    PERFECT_ALTERNATIVE = Annotated[Effect, effect("#PERFECT_ALTERNATIVE")]
+    GREAT_ALTERNATIVE = Annotated[Effect, effect("#GREAT_ALTERNATIVE")]
+    GOOD_ALTERNATIVE = Annotated[Effect, effect("#GOOD_ALTERNATIVE")]
+    HOLD_ALTERNATIVE = Annotated[Effect, effect("#HOLD_ALTERNATIVE")]
+    STAGE = Annotated[Effect, effect("#STAGE")]
 
 
 @effects

sonolus/script/engine.py

@@ -1,11 +1,18 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from typing import Any
 
 from sonolus.build.collection import Asset
-from sonolus.script.archetype import BaseArchetype
+from sonolus.script.archetype import BaseArchetype, PlayArchetype, PreviewArchetype, WatchArchetype
 from sonolus.script.bucket import Buckets, EmptyBuckets
 from sonolus.script.effect import Effects, EmptyEffects
+from sonolus.script.instruction import (
+    EmptyInstructionIcons,
+    EmptyInstructions,
+    TutorialInstructionIcons,
+    TutorialInstructions,
+)
 from sonolus.script.options import EmptyOptions, Options
 from sonolus.script.particle import EmptyParticles, Particles
 from sonolus.script.sprite import EmptySkin, Skin
@@ -41,7 +48,7 @@ class Engine:
         self.data = data
 
 
-def default_callback() -> float:
+def default_callback() -> Any:
     return 0.0
 
 
@@ -61,6 +68,10 @@ class PlayMode:
         self.particles = particles
         self.buckets = buckets
 
+        for archetype in self.archetypes:
+            if not issubclass(archetype, PlayArchetype):
+                raise ValueError(f"archetype {archetype} is not a PlayArchetype")
+
 
 class WatchMode:
     def __init__(
@@ -80,13 +91,50 @@ class WatchMode:
         self.buckets = buckets
         self.update_spawn = update_spawn
 
+        for archetype in self.archetypes:
+            if not issubclass(archetype, WatchArchetype):
+                raise ValueError(f"archetype {archetype} is not a PlayArchetype")
+
+
+class PreviewMode:
+    def __init__(
+        self,
+        *,
+        archetypes: list[type[BaseArchetype]] | None = None,
+        skin: Skin = EmptySkin,
+    ) -> None:
+        self.archetypes = archetypes or []
+        self.skin = skin
+
+        for archetype in self.archetypes:
+            if not issubclass(archetype, PreviewArchetype):
+                raise ValueError(f"archetype {archetype} is not a BaseArchetype")
 
-class EngineData:
-    ui: UiConfig
-    options: Options
-    play: PlayMode
-    watch: WatchMode
 
+class TutorialMode:
+    def __init__(
+        self,
+        *,
+        skin: Skin = EmptySkin,
+        effects: Effects = EmptyEffects,
+        particles: Particles = EmptyParticles,
+        instructions: TutorialInstructions = EmptyInstructions,
+        instruction_icons: TutorialInstructionIcons = EmptyInstructionIcons,
+        preprocess: Callable[[], None],
+        navigate: Callable[[], None],
+        update: Callable[[], None],
+    ) -> None:
+        self.skin = skin
+        self.effects = effects
+        self.particles = particles
+        self.instructions = instructions
+        self.instruction_icons = instruction_icons
+        self.preprocess = preprocess
+        self.navigate = navigate
+        self.update = update
+
+
+class EngineData:
     def __init__(
         self,
         *,
@@ -94,8 +142,16 @@ class EngineData:
         options: Options = EmptyOptions,
         play: PlayMode | None = None,
         watch: WatchMode | None = None,
+        preview: PreviewMode | None = None,
+        tutorial: TutorialMode | None = None,
     ) -> None:
         self.ui = ui or UiConfig()
         self.options = options
         self.play = play or PlayMode()
         self.watch = watch or WatchMode(update_spawn=default_callback)
+        self.preview = preview or PreviewMode()
+        self.tutorial = tutorial or TutorialMode(
+            preprocess=default_callback,
+            navigate=default_callback,
+            update=default_callback,
+        )