sonolus.py 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

sonolus/script/runtime.py

@@ -259,6 +259,382 @@ class _TutorialRuntimeUi:
     instruction: BasicRuntimeUiLayout
 
 
+class UiLayout[T](Record):
+    """The layout of a UI element."""
+
+    _underlying: T
+
+    def update(
+        self,
+        anchor: Vec2 | None = None,
+        pivot: Vec2 | None = None,
+        dimensions: Vec2 | None = None,
+        rotation: float | None = None,
+        alpha: float | None = None,
+        horizontal_align: HorizontalAlign | None = None,
+        background: bool | None = None,
+    ):
+        """Update the layout properties if it's available in the current mode and do nothing otherwise."""
+        match self._underlying:
+            case RuntimeUiLayout():
+                self._underlying.update(
+                    anchor=anchor,
+                    pivot=pivot,
+                    dimensions=dimensions,
+                    rotation=rotation,
+                    alpha=alpha,
+                    horizontal_align=horizontal_align,
+                    background=background,
+                )
+            case BasicRuntimeUiLayout():
+                self._underlying.update(
+                    anchor=anchor,
+                    pivot=pivot,
+                    dimensions=dimensions,
+                    rotation=rotation,
+                    alpha=alpha,
+                    background=background,
+                )
+            case _:
+                pass  # do nothing
+
+    @property
+    def is_available(self) -> bool:
+        """Check if the layout is available in the current mode."""
+        return self._underlying is not None
+
+
+class UiConfig[T](Record):
+    """The user configuration for a UI element."""
+
+    _underlying: T
+
+    @property
+    def scale(self) -> float:
+        """The scale of the UI element."""
+        match self._underlying:
+            case RuntimeUiConfig():
+                return self._underlying.scale
+            case _:
+                return 1.0  # Default scale if not available
+
+    @property
+    def alpha(self) -> float:
+        """The alpha (opacity) of the UI element."""
+        match self._underlying:
+            case RuntimeUiConfig():
+                return self._underlying.alpha
+            case _:
+                return 1.0  # Default alpha if not available
+
+    @property
+    def is_available(self) -> bool:
+        """Check if the config is available in the current mode."""
+        return self._underlying is not None
+
+
+class RuntimeUi(Record):
+    """Holds the layouts for different UI elements across all modes."""
+
+    @property
+    @meta_fn
+    def menu(self) -> UiLayout:
+        """The configuration for the menu UI element.
+
+        Available in play, watch, preview, and tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.menu)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.menu)
+            case Mode.PREVIEW:
+                return UiLayout(_PreviewRuntimeUi.menu)
+            case Mode.TUTORIAL:
+                return UiLayout(_TutorialRuntimeUi.menu)
+            case _:
+                raise RuntimeError("Unsupported mode for menu UI layout")
+
+    @property
+    @meta_fn
+    def menu_config(self) -> UiConfig:
+        """The configuration for the menu UI element.
+
+        Available in play, watch, preview, and tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiConfig(_PlayRuntimeUiConfigs.menu)
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.menu)
+            case Mode.PREVIEW:
+                return UiConfig(_PreviewRuntimeUiConfigs.menu)
+            case Mode.TUTORIAL:
+                return UiConfig(_TutorialRuntimeUiConfigs.menu)
+            case _:
+                raise RuntimeError("Unsupported mode for menu UI configuration")
+
+    @property
+    @meta_fn
+    def judgment(self) -> UiLayout:
+        """The configuration for the judgment UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.judgment)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.judgment)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def judgment_config(self) -> UiConfig:
+        """The configuration for the judgment UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiConfig(_PlayRuntimeUiConfigs.judgment)
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.judgment)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def combo_value(self) -> UiLayout:
+        """The configuration for the combo value UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.combo_value)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.combo_value)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def combo_text(self) -> UiLayout:
+        """The configuration for the combo text UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.combo_text)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.combo_text)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def combo_config(self) -> UiConfig:
+        """The configuration for the combo UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiConfig(_PlayRuntimeUiConfigs.combo)
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.combo)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def primary_metric_bar(self) -> UiLayout:
+        """The configuration for the primary metric bar UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.primary_metric_bar)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.primary_metric_bar)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def primary_metric_value(self) -> UiLayout:
+        """The configuration for the primary metric value UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.primary_metric_value)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.primary_metric_value)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def primary_metric_config(self) -> UiConfig:
+        """The configuration for the primary metric UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiConfig(_PlayRuntimeUiConfigs.primary_metric)
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.primary_metric)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def secondary_metric_bar(self) -> UiLayout:
+        """The configuration for the secondary metric bar UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.secondary_metric_bar)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.secondary_metric_bar)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def secondary_metric_value(self) -> UiLayout:
+        """The configuration for the secondary metric value UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiLayout(_PlayRuntimeUi.secondary_metric_value)
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.secondary_metric_value)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def secondary_metric_config(self) -> UiConfig:
+        """The configuration for the secondary metric UI element.
+
+        Available in play and watch mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.PLAY:
+                return UiConfig(_PlayRuntimeUiConfigs.secondary_metric)
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.secondary_metric)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def progress(self) -> UiLayout:
+        """The configuration for the progress UI element.
+
+        Available in watch and preview mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.WATCH:
+                return UiLayout(_WatchRuntimeUi.progress)
+            case Mode.PREVIEW:
+                return UiLayout(_PreviewRuntimeUi.progress)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def progress_config(self) -> UiConfig:
+        """The configuration for the progress UI element.
+
+        Available in watch and preview mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.WATCH:
+                return UiConfig(_WatchRuntimeUiConfigs.progress)
+            case Mode.PREVIEW:
+                return UiConfig(_PreviewRuntimeUiConfigs.progress)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def previous(self) -> UiLayout:
+        """The configuration for the previous navigation UI element.
+
+        Available in tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.TUTORIAL:
+                return UiLayout(_TutorialRuntimeUi.previous)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def next(self) -> UiLayout:
+        """The configuration for the next navigation UI element.
+
+        Available in tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.TUTORIAL:
+                return UiLayout(_TutorialRuntimeUi.next)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def navigation_config(self) -> UiConfig:
+        """The configuration for the navigation UI element.
+
+        Available in tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.TUTORIAL:
+                return UiConfig(_TutorialRuntimeUiConfigs.navigation)
+            case _:
+                return UiConfig(None)
+
+    @property
+    @meta_fn
+    def instruction(self) -> UiLayout:
+        """The configuration for the instruction UI element.
+
+        Available in tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.TUTORIAL:
+                return UiLayout(_TutorialRuntimeUi.instruction)
+            case _:
+                return UiLayout(None)
+
+    @property
+    @meta_fn
+    def instruction_config(self) -> UiConfig:
+        """The configuration for the instruction UI element.
+
+        Available in tutorial mode.
+        """
+        match ctx().global_state.mode:
+            case Mode.TUTORIAL:
+                return UiConfig(_TutorialRuntimeUiConfigs.instruction)
+            case _:
+                return UiConfig(None)
+
+
 class Touch(Record):
     """Data of a touch event."""
 
@@ -733,6 +1109,13 @@ preview_ui_configs = _PreviewRuntimeUiConfigs
 tutorial_ui = _TutorialRuntimeUi
 tutorial_ui_configs = _TutorialRuntimeUiConfigs
 
+_runtime_ui = RuntimeUi()
+
+
+def runtime_ui() -> RuntimeUi:
+    """Get the runtime UI configuration."""
+    return _runtime_ui
+
 
 def canvas() -> _PreviewRuntimeCanvas:
     """Get the preview canvas."""

sonolus/script/stream.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import cast, dataclass_transform
 
-from sonolus.backend.ir import IRExpr, IRInstr, IRPureInstr, IRConst
+from sonolus.backend.ir import IRConst, IRExpr, IRInstr, IRPureInstr
 from sonolus.backend.mode import Mode
 from sonolus.backend.ops import Op
 from sonolus.script.internal.context import ctx
@@ -14,6 +14,7 @@ from sonolus.script.internal.value import BackingValue, Value
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.record import Record
+from sonolus.script.runtime import delta_time, time
 from sonolus.script.values import sizeof
 
 
@@ -174,10 +175,11 @@ class _SparseStreamBacking(BackingValue):
         )
 
 
-class Stream[T](Record, BackingValue):
+class Stream[T](Record):
     """Represents a stream.
 
-    Most users should use `@stream` to declare streams and stream groups rather than using this class directly.
+    Most users should use [`@streams`][sonolus.script.stream.streams] to declare streams and stream groups rather than
+    using this class directly.
 
     If used directly, it is important that streams do not overlap. No other streams should have an offset in
     `range(self.offset, self.offset + max(1, sizeof(self.element_type())))`, or they will overlap and interfere
@@ -248,6 +250,12 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _stream_get_next_key(self.offset, key)
 
+    def next_key_or_default(self, key: int | float, default: int | float) -> int:
+        """Get the next key, or the default value if there is no next key."""
+        _check_can_read_stream()
+        next_key = self.next_key(key)
+        return next_key if next_key > key else default
+
     def previous_key(self, key: int | float) -> int:
         """Get the previous key, or the key unchanged if it is the first key or the stream is empty.
 
@@ -256,6 +264,12 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _stream_get_previous_key(self.offset, key)
 
+    def previous_key_or_default(self, key: int | float, default: int | float) -> int:
+        """Get the previous key, or the default value if there is no previous key."""
+        _check_can_read_stream()
+        previous_key = self.previous_key(key)
+        return previous_key if previous_key < key else default
+
     def has_next_key(self, key: int | float) -> bool:
         """Check if there is a next key after the given key in the stream."""
         _check_can_read_stream()
@@ -317,6 +331,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscIterator(self, self.next_key_inclusive(start))
 
+    def iter_items_since_previous_frame(self) -> SonolusIterator[tuple[int | float, T]]:
+        """Iterate over the items in the stream since the last frame.
+
+        This is a convenience method that iterates over the items in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for key, value in stream.iter_items_since_previous_frame():
+            do_something(key, value)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscIterator(self, self.next_key(time() - delta_time()), time())
+
     def iter_items_from_desc(self, start: int | float, /) -> SonolusIterator[tuple[int | float, T]]:
         """Iterate over the items in the stream in descending order starting from the given key.
 
@@ -347,6 +377,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscKeyIterator(self, self.next_key_inclusive(start))
 
+    def iter_keys_since_previous_frame(self) -> SonolusIterator[int | float]:
+        """Iterate over the keys in the stream since the last frame.
+
+        This is a convenience method that iterates over the keys in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for key in stream.iter_keys_since_previous_frame():
+            do_something(key)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscKeyIterator(self, self.next_key(time() - delta_time()), time())
+
     def iter_keys_from_desc(self, start: int | float, /) -> SonolusIterator[int | float]:
         """Iterate over the keys in the stream in descending order starting from the given key.
 
@@ -377,6 +423,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscValueIterator(self, self.next_key_inclusive(start))
 
+    def iter_values_since_previous_frame(self) -> SonolusIterator[T]:
+        """Iterate over the values in the stream since the last frame.
+
+        This is a convenience method that iterates over the values in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for value in stream.iter_values_since_previous_frame():
+            do_something(value)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscValueIterator(self, self.next_key(time() - delta_time()), time())
+
     def iter_values_from_desc(self, start: int | float, /) -> SonolusIterator[T]:
         """Iterate over the values in the stream in descending order starting from the given key.
 
@@ -396,7 +458,8 @@ class Stream[T](Record, BackingValue):
 class StreamGroup[T, Size](Record):
     """Represents a group of streams.
 
-    Most users should use `@stream` to declare stream groups rather than using this class directly.
+    Most users should use [`@streams`][sonolus.script.stream.streams] to declare stream groups rather than using this
+    class directly.
 
     Usage:
         Declaring a stream group:
@@ -444,13 +507,28 @@ class _StreamAscIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> tuple[int | float, T]:
         return self.current_key, self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
+
+
+class _StreamBoundedAscIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
+
+    def get(self) -> tuple[int | float, T]:
+        return self.current_key, self.stream[self.current_key]
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
 
 
 class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
@@ -458,13 +536,13 @@ class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> tuple[int | float, T]:
         return self.current_key, self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
 
 
 class _StreamAscKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -472,13 +550,28 @@ class _StreamAscKeyIterator[T](Record, SonolusIterator[int | float]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
+
+    def get(self) -> int | float:
+        return self.current_key
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
+
+
+class _StreamBoundedAscKeyIterator[T](Record, SonolusIterator[int | float]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
 
     def get(self) -> int | float:
         return self.current_key
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
 
 
 class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -486,13 +579,13 @@ class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> int | float:
         return self.current_key
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
 
 
 class _StreamAscValueIterator[T](Record, SonolusIterator[T]):
@@ -500,13 +593,28 @@ class _StreamAscValueIterator[T](Record, SonolusIterator[T]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
+
+    def get(self) -> T:
+        return self.stream[self.current_key]
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
+
+
+class _StreamBoundedAscValueIterator[T](Record, SonolusIterator[T]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
 
     def get(self) -> T:
         return self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, self.current_key + 1)
 
 
 class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
@@ -514,13 +622,13 @@ class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> T:
         return self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
 
 
 @native_function(Op.StreamGetNextKey)