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

sonolus/script/internal/builtin_impls.py

@@ -1,6 +1,7 @@
 from collections.abc import Iterable
 from typing import overload
 
+from sonolus.script.array import Array
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.dict_impl import DictImpl
@@ -129,6 +130,8 @@ def _max(*args, key: callable = _identity):
         (iterable,) = args
         if isinstance(iterable, ArrayLike):
             return compile_and_call(iterable._max_, key=key)
+        elif isinstance(iterable, TupleImpl) and all(_is_num(v) for v in iterable.value):
+            return compile_and_call(Array(*iterable.value)._max_, key=key)
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for max")
     else:
@@ -169,6 +172,8 @@ def _min(*args, key: callable = _identity):
         (iterable,) = args
         if isinstance(iterable, ArrayLike):
             return compile_and_call(iterable._min_, key=key)
+        elif isinstance(iterable, TupleImpl) and all(_is_num(v) for v in iterable.value):
+            return compile_and_call(Array(*iterable.value)._min_, key=key)
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for min")
     else:
@@ -221,12 +226,12 @@ def _float(value=0.0):
     return value
 
 
-@meta_fn
 def _bool(value=False):
-    value = validate_value(value)
-    if not _is_num(value):
-        raise TypeError("Only numeric arguments to bool() are supported")
-    return value != 0
+    # Relies on the compiler to perform the conversion in a boolean context
+    if value:  # noqa: SIM103
+        return True
+    else:
+        return False
 
 
 _int._type_mapping_ = Num

sonolus/script/internal/context.py

@@ -291,7 +291,11 @@ class ReadOnlyMemory:
     _lock: Lock
 
     def __init__(self):
-        self.values = []
+        self.values = [
+            float("nan"),
+            float("inf"),
+            float("-inf"),
+        ]
         self.indexes = {}
         self._lock = Lock()
 

sonolus/script/internal/math_impls.py

@@ -97,6 +97,22 @@ def _log(x: float, base: float | None = None) -> float:
         return _ln(x) / _ln(base)
 
 
+def _sqrt(x: float) -> float:
+    return x**0.5
+
+
+@native_function(Op.Degree)
+def _degrees(x: float) -> float:
+    """Convert radians to degrees."""
+    return math.degrees(x)
+
+
+@native_function(Op.Radian)
+def _radians(x: float) -> float:
+    """Convert degrees to radians."""
+    return math.radians(x)
+
+
 @native_function(Op.Rem)
 def _remainder(x: float, y: float) -> float:
     # This is different from math.remainder in Python's math package, which could be confusing
@@ -119,4 +135,5 @@ MATH_BUILTIN_IMPLS = {
     id(math.trunc): _trunc,
     id(round): _round,
     id(math.log): _log,
+    id(math.sqrt): _sqrt,
 }

sonolus/script/internal/native.py

@@ -9,7 +9,7 @@ from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.num import Num, _is_num
 
 
-def native_call(op: Op, *args: Num) -> Num:
+def native_call(op: Op, *args: int | float | bool) -> Num:
     if not ctx():
         raise RuntimeError("Unexpected native call")
     args = tuple(validate_value(arg) for arg in args)
@@ -21,12 +21,12 @@ def native_call(op: Op, *args: Num) -> Num:
 
 
 def native_function[**P, R](op: Op) -> Callable[[Callable[P, R]], Callable[P, R]]:
-    def decorator(fn: Callable[P, Num]) -> Callable[P, Num]:
+    def decorator(fn: Callable[P, int | float | bool]) -> Callable[P, Num]:
         signature = inspect.signature(fn)
 
         @functools.wraps(fn)
         @meta_fn
-        def wrapper(*args: Num) -> Num:
+        def wrapper(*args: int | float | bool) -> Num:
             if len(args) < sum(1 for p in signature.parameters.values() if p.default == inspect.Parameter.empty):
                 raise TypeError(f"Expected {len(signature.parameters)} arguments, got {len(args)}")
             if ctx():

sonolus/script/internal/range.py

@@ -1,15 +1,17 @@
-from sonolus.script.array_like import ArrayLike
+from sonolus.script.array_like import ArrayLike, get_positive_index
+from sonolus.script.internal.context import ctx
+from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.record import Record
 
 
-class Range(Record, ArrayLike[Num]):
+class Range(Record, ArrayLike[int]):
     start: int
     stop: int
     step: int
 
-    def __new__(cls, start: Num, stop: Num | None = None, step: Num = 1):
+    def __new__(cls, start: int, stop: int | None = None, step: int = 1):
         if stop is None:
             start, stop = 0, start
         return super().__new__(cls, start, stop, step)
@@ -35,14 +37,14 @@ class Range(Record, ArrayLike[Num]):
                 return 0
             return (diff - self.step - 1) // -self.step
 
-    def __getitem__(self, index: Num) -> Num:
-        return self.start + index * self.step
+    def __getitem__(self, index: int) -> int:
+        return self.start + get_positive_index(index, len(self)) * self.step
 
-    def __setitem__(self, index: Num, value: Num):
+    def __setitem__(self, index: int, value: int):
         raise TypeError("Range does not support item assignment")
 
     @property
-    def last(self) -> Num:
+    def last(self) -> int:
         return self[len(self) - 1]
 
     def __eq__(self, other):
@@ -79,3 +81,24 @@ class RangeIterator(Record, SonolusIterator):
 
     def advance(self):
         self.value += self.step
+
+
+@meta_fn
+def range_or_tuple(start: int, stop: int | None = None, step: int = 1) -> Range | tuple[int, ...]:
+    if stop is None:
+        start, stop = 0, start
+    if not ctx():
+        return range(start, stop, step)  # type: ignore
+    start = Num._accept_(start)
+    stop = Num._accept_(stop) if stop is not None else None
+    step = Num._accept_(step)
+    if start._is_py_() and stop._is_py_() and step._is_py_():
+        start_int = start._as_py_()
+        stop_int = stop._as_py_() if stop is not None else None
+        if stop_int is None:
+            start_int, stop_int = 0, start_int
+        step_int = step._as_py_()
+        if start_int % 1 != 0 or stop_int % 1 != 0 or step_int % 1 != 0:
+            raise TypeError("Range arguments must be integers")
+        return validate_value(tuple(range(int(start_int), int(stop_int), int(step_int))))  # type: ignore
+    return Range(start, stop, step)

sonolus/script/internal/tuple_impl.py

@@ -21,8 +21,10 @@ class TupleImpl(TransientValue):
             raise TypeError(f"Cannot index tuple with {item}")
         if int(item) != item:
             raise TypeError(f"Cannot index tuple with non-integer {item}")
-        if not (0 <= item < len(self.value)):
+        if not (-len(self.value) <= item < len(self.value)):
             raise IndexError(f"Tuple index out of range: {item}")
+        if item < 0:
+            item += len(self.value)
         return self.value[int(item)]
 
     @meta_fn

sonolus/script/internal/value.py

@@ -122,7 +122,7 @@ class Value:
         For instance:
         ```
         class X(Record):
-            v: Num
+            v: int
 
         a = 1
         b = X(a) # (1) _get_() is called on a

sonolus/script/interval.py

@@ -1,8 +1,10 @@
 from typing import Self
 
 from sonolus.backend.ops import Op
+from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import static_error
 from sonolus.script.internal.native import native_function
+from sonolus.script.internal.range import range_or_tuple
 from sonolus.script.num import Num
 from sonolus.script.record import Record
 
@@ -34,7 +36,7 @@ class Interval(Record):
 
     @property
     def is_empty(self) -> bool:
-        """Whether the has a start greater than its end."""
+        """Whether the interval has a start greater than its end."""
         return self.start > self.end
 
     @property
@@ -296,7 +298,7 @@ def unlerp_clamped(a: float, b: float, x: float, /) -> float:
 
 @native_function(Op.Remap)
 def remap(a: float, b: float, c: float, d: float, x: float, /) -> float:
-    """Remap a value from one interval to another.
+    """Linearly remap a value from one interval to another.
 
     Args:
         a: The start of the input interval.
@@ -313,7 +315,7 @@ def remap(a: float, b: float, c: float, d: float, x: float, /) -> float:
 
 @native_function(Op.RemapClamped)
 def remap_clamped(a: float, b: float, c: float, d: float, x: float, /) -> float:
-    """Remap a value from one interval to another, clamped to the output interval.
+    """Linearly remap a value from one interval to another, clamped to the output interval.
 
     Args:
         a: The start of the input interval.
@@ -341,3 +343,59 @@ def clamp(x: float, a: float, b: float, /) -> float:
         The clamped value.
     """
     return max(a, min(b, x))
+
+
+def interp(
+    xp: ArrayLike[float] | tuple[float, ...],
+    fp: ArrayLike[float] | tuple[float, ...],
+    x: float,
+) -> float:
+    """Linearly interpolate a value within a sequence of points.
+
+    The sequence must have at least 2 elements and be sorted in increasing order of x-coordinates.
+    For values of x outside the range of xp, the slope of the first or last segment is used to extrapolate.
+
+    Args:
+        xp: The x-coordinates of the points in increasing order.
+        fp: The y-coordinates of the points.
+        x: The x-coordinate to interpolate.
+
+    Returns:
+        The interpolated value.
+    """
+    assert len(xp) == len(fp)
+    assert len(xp) >= 2
+    for i in range_or_tuple(1, len(xp) - 1):
+        # At i == 1, x may be less than x[0], but since we're extrapolating, we use the first segment regardless.
+        if x <= xp[i]:
+            return remap(xp[i - 1], xp[i], fp[i - 1], fp[i], x)
+    # x > xp[-2] so we can just use the last segment regardless of whether x is in it or to the right of it.
+    return remap(xp[-2], xp[-1], fp[-2], fp[-1], x)
+
+
+def interp_clamped(
+    xp: ArrayLike[float] | tuple[float, ...],
+    fp: ArrayLike[float] | tuple[float, ...],
+    x: float,
+) -> float:
+    """Linearly interpolate a value within a sequence of points.
+
+    The sequence must have at least 2 elements and be sorted in increasing order of x-coordinates.
+    For x-coordinates outside the range of the sequence, the respective endpoint of fp is returned.
+
+    Args:
+        xp: The x-coordinates of the points in increasing order.
+        fp: The y-coordinates of the points.
+        x: The x-coordinate to interpolate.
+
+    Returns:
+        The interpolated value.
+    """
+    assert len(xp) == len(fp)
+    assert len(xp) >= 2
+    if x <= xp[0]:
+        return fp[0]
+    for i in range_or_tuple(1, len(xp)):
+        if x <= xp[i]:
+            return remap(xp[i - 1], xp[i], fp[i - 1], fp[i], x)
+    return fp[-1]

sonolus/script/num.py

@@ -439,17 +439,17 @@ if TYPE_CHECKING:
 
     @runtime_checkable
     class Num[T](Protocol, int, bool, float):
-        def __add__(self, other: T, /) -> Num: ...
-        def __sub__(self, other: T, /) -> Num: ...
-        def __mul__(self, other: T, /) -> Num: ...
-        def __truediv__(self, other: T, /) -> Num: ...
-        def __floordiv__(self, other: T, /) -> Num: ...
-        def __mod__(self, other: T, /) -> Num: ...
-        def __pow__(self, other: T, /) -> Num: ...
-
-        def __neg__(self, /) -> Num: ...
-        def __pos__(self, /) -> Num: ...
-        def __abs__(self, /) -> Num: ...
+        def __add__(self, other: T, /) -> Num | int | bool | float: ...
+        def __sub__(self, other: T, /) -> Num | int | bool | float: ...
+        def __mul__(self, other: T, /) -> Num | int | bool | float: ...
+        def __truediv__(self, other: T, /) -> Num | int | bool | float: ...
+        def __floordiv__(self, other: T, /) -> Num | int | bool | float: ...
+        def __mod__(self, other: T, /) -> Num | int | bool | float: ...
+        def __pow__(self, other: T, /) -> Num | int | bool | float: ...
+
+        def __neg__(self, /) -> Num | int | bool | float: ...
+        def __pos__(self, /) -> Num | int | bool | float: ...
+        def __abs__(self, /) -> Num | int | bool | float: ...
 
         def __eq__(self, other: Any, /) -> bool: ...
         def __ne__(self, other: Any, /) -> bool: ...
@@ -461,10 +461,10 @@ if TYPE_CHECKING:
         def __hash__(self, /) -> int: ...
 
         @property
-        def real(self) -> Num: ...
+        def real(self) -> Num | int | bool | float: ...
 
         @property
-        def imag(self) -> Num: ...
+        def imag(self) -> Num | int | bool | float: ...
 else:
     # Need to do this to satisfy type checkers (especially Pycharm)
     _Num.__name__ = "Num"

sonolus/script/pointer.py

@@ -6,7 +6,7 @@ from sonolus.script.num import Num, _is_num
 
 
 @meta_fn
-def _deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
+def _deref[T: Value](block: int, offset: int, type_: type[T]) -> T:
     block = Num._accept_(block)
     offset = Num._accept_(offset)
     type_ = validate_value(type_)._as_py_()

sonolus/script/quad.py

@@ -28,6 +28,20 @@ class Quad(Record):
     br: Vec2
     """The bottom-right corner of the quad."""
 
+    @classmethod
+    def zero(cls) -> Quad:
+        """Return a quad with all corners set to (0, 0).
+
+        Returns:
+            A new quad with all corners at the origin.
+        """
+        return cls(
+            bl=Vec2.zero(),
+            tl=Vec2.zero(),
+            tr=Vec2.zero(),
+            br=Vec2.zero(),
+        )
+
     @classmethod
     def from_quad(cls, value: QuadLike, /) -> Quad:
         """Create a quad from a quad-like value."""
@@ -80,7 +94,14 @@ class Quad(Record):
         ).translate(self.center * (Vec2(1, 1) - factor))
 
     def rotate(self, angle: float, /) -> Self:
-        """Rotate the quad by the given angle about the origin and return a new quad."""
+        """Rotate the quad by the given angle about the origin and return a new quad.
+
+        Args:
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
+
+        Returns:
+            A new quad rotated by the given angle.
+        """
         return Quad(
             bl=self.bl.rotate(angle),
             tl=self.tl.rotate(angle),
@@ -94,7 +115,15 @@ class Quad(Record):
         /,
         pivot: Vec2,
     ) -> Self:
-        """Rotate the quad by the given angle about the given pivot and return a new quad."""
+        """Rotate the quad by the given angle about the given pivot and return a new quad.
+
+        Args:
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
+            pivot: The pivot point for rotation.
+
+        Returns:
+            A new quad rotated about the pivot by the given angle.
+        """
         return Quad(
             bl=self.bl.rotate_about(angle, pivot),
             tl=self.tl.rotate_about(angle, pivot),
@@ -103,7 +132,14 @@ class Quad(Record):
         )
 
     def rotate_centered(self, angle: float, /) -> Self:
-        """Rotate the quad by the given angle about its center and return a new quad."""
+        """Rotate the quad by the given angle about its center and return a new quad.
+
+        Args:
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
+
+        Returns:
+            A new quad rotated about its center by the given angle.
+        """
         return self.rotate_about(angle, self.center)
 
     def permute(self, count: int = 1, /) -> Self:

sonolus/script/record.py

@@ -23,6 +23,7 @@ from sonolus.script.num import Num
 class RecordMeta(type):
     @meta_fn
     def __pos__[T](cls: type[T]) -> T:
+        """Create a zero-initialized record instance."""
         return cls._zero_()
 
 
@@ -53,6 +54,11 @@ class Record(GenericValue, metaclass=RecordMeta):
         record_4 = +MyRecord  # Create a zero-initialized record
         record_5 = +MyGenericRecord[int, int]
         ```
+
+        Copying a record:
+        ```python
+        record_copy = +record
+        ```
     """
 
     _value: dict[str, Value]
@@ -283,6 +289,7 @@ class Record(GenericValue, metaclass=RecordMeta):
     def __hash__(self):
         return hash(tuple(field.__get__(self) for field in self._fields))
 
+    @meta_fn
     def __pos__(self) -> Self:
         """Return a copy of the record."""
         return self._copy_()

sonolus/script/runtime.py

@@ -988,6 +988,25 @@ def time() -> float:
             return 0
 
 
+@meta_fn
+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.
+    """
+    if not ctx():
+        return 0
+    match ctx().global_state.mode:
+        case Mode.PLAY:
+            return _PlayRuntimeUpdate.time - _PlayRuntimeEnvironment.input_offset
+        case Mode.WATCH:
+            return _WatchRuntimeUpdate.time - _WatchRuntimeEnvironment.input_offset
+        case Mode.TUTORIAL:
+            return _TutorialRuntimeUpdate.time
+        case _:
+            return 0
+
+
 @meta_fn
 def delta_time() -> float:
     """Get the time elapsed since the last frame.
@@ -1026,6 +1045,15 @@ def scaled_time() -> float:
             return 0
 
 
+@meta_fn
+def prev_time() -> float:
+    """Get the time of the previous frame.
+
+    Returns 0 in preview mode.
+    """
+    return time() - delta_time()
+
+
 @meta_fn
 def touches() -> ArrayLike[Touch]:
     """Get the current touches of the game."""

sonolus/script/stream.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from math import inf
 from typing import cast, dataclass_transform
 
 from sonolus.backend.ir import IRConst, IRExpr, IRInstr, IRPureInstr
@@ -14,7 +15,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.runtime import prev_time, time
 from sonolus.script.values import sizeof
 
 
@@ -79,12 +80,12 @@ def streams[T](cls: type[T]) -> T:
         ```python
         @streams
         class Streams:
-            stream_1: Stream[Num]  # A stream of Num values
+            stream_1: Stream[int]  # A stream of int values
             stream_2: Stream[Vec2]  # A stream of Vec2 values
-            group_1: StreamGroup[Num, 10]  # A group of 10 Num streams
+            group_1: StreamGroup[int, 10]  # A group of 10 int streams
             group_2: StreamGroup[Vec2, 5]  # A group of 5 Vec2 streams
 
-            data_field_1: Num  # A data field of type Num
+            data_field_1: int  # A data field of type int
             data_field_2: Vec2  # A data field of type Vec2
         ```
     """
@@ -316,6 +317,14 @@ class Stream[T](Record):
         _check_can_read_stream()
         return self[self.next_key_inclusive(key)]
 
+    def get_previous_inclusive(self, key: int | float) -> T:
+        """Get the value corresponding to the previous key, or the value at the given key if it is in the stream.
+
+        Equivalent to `self[self.previous_key_inclusive(key)]`.
+        """
+        _check_can_read_stream()
+        return self[self.previous_key_inclusive(key)]
+
     def iter_items_from(self, start: int | float, /) -> SonolusIterator[tuple[int | float, T]]:
         """Iterate over the items in the stream in ascending order starting from the given key.
 
@@ -345,7 +354,7 @@ class Stream[T](Record):
         ```
         """
         _check_can_read_stream()
-        return _StreamBoundedAscIterator(self, self.next_key(time() - delta_time()), time())
+        return _StreamBoundedAscIterator(self, self.next_key(prev_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.
@@ -391,7 +400,7 @@ class Stream[T](Record):
         ```
         """
         _check_can_read_stream()
-        return _StreamBoundedAscKeyIterator(self, self.next_key(time() - delta_time()), time())
+        return _StreamBoundedAscKeyIterator(self, self.next_key(prev_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.
@@ -437,7 +446,7 @@ class Stream[T](Record):
         ```
         """
         _check_can_read_stream()
-        return _StreamBoundedAscValueIterator(self, self.next_key(time() - delta_time()), time())
+        return _StreamBoundedAscValueIterator(self, self.next_key(prev_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.
@@ -513,7 +522,7 @@ class _StreamAscIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamBoundedAscIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
@@ -528,7 +537,7 @@ class _StreamBoundedAscIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
@@ -542,7 +551,7 @@ class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
         return self.current_key, self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 class _StreamAscKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -556,7 +565,7 @@ class _StreamAscKeyIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamBoundedAscKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -571,7 +580,7 @@ class _StreamBoundedAscKeyIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -585,7 +594,7 @@ class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
         return self.current_key
 
     def advance(self):
-        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 class _StreamAscValueIterator[T](Record, SonolusIterator[T]):
@@ -599,7 +608,7 @@ class _StreamAscValueIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamBoundedAscValueIterator[T](Record, SonolusIterator[T]):
@@ -614,7 +623,7 @@ class _StreamBoundedAscValueIterator[T](Record, SonolusIterator[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)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
@@ -628,7 +637,7 @@ class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
         return self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key_or_default(self.current_key, self.current_key - 1)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 @native_function(Op.StreamGetNextKey)

sonolus/script/transform.py

@@ -137,7 +137,7 @@ class Transform2d(Record):
         """Rotate about the origin and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
 
         Returns:
             A new transform after rotation.
@@ -160,7 +160,7 @@ class Transform2d(Record):
         """Rotate about the pivot and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
             pivot: The pivot point for rotation.
 
         Returns:
@@ -470,7 +470,7 @@ class InvertibleTransform2d(Record):
         """Rotate about the origin and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
 
         Returns:
             A new invertible transform after rotation.
@@ -484,7 +484,7 @@ class InvertibleTransform2d(Record):
         """Rotate about the pivot and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
             pivot: The pivot point for rotation.
 
         Returns: