sonolus.py 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

sonolus/script/graphics.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Protocol
+from typing import Protocol, Self
 
 from sonolus.script.record import Record
 from sonolus.script.vec import Vec2
@@ -20,21 +20,12 @@ class Rect(Record):
     l: float  # noqa: E741
 
     @classmethod
-    def from_xywh(cls, x: float, y: float, w: float, h: float) -> Rect:
+    def from_center(cls, center: Vec2, dimensions: Vec2) -> Rect:
         return cls(
-            t=y + h,
-            r=x + w,
-            b=y,
-            l=x,
-        )
-
-    @classmethod
-    def from_center(cls, x: float, y: float, w: float, h: float) -> Rect:
-        return cls(
-            t=y + h / 2,
-            r=x + w / 2,
-            b=y - h / 2,
-            l=x - w / 2,
+            t=center.y + dimensions.y / 2,
+            r=center.x + dimensions.x / 2,
+            b=center.y - dimensions.y / 2,
+            l=center.x - dimensions.x / 2,
         )
 
     @property
@@ -99,19 +90,37 @@ class Rect(Record):
             br=self.br,
         )
 
-    def scale(self, x: float, y: float | None, /):
-        if y is None:
-            y = x
-        self.l *= x
-        self.r *= x
-        self.t *= y
-        self.b *= y
-
-    def translate(self, x: float, y: float, /):
-        self.l += x
-        self.r += x
-        self.t += y
-        self.b += y
+    def scale(self, factor: Vec2, /) -> Self:
+        return Rect(
+            t=self.t * factor.y,
+            r=self.r * factor.x,
+            b=self.b * factor.y,
+            l=self.l * factor.x,
+        )
+
+    def expand(self, expansion: Vec2, /) -> Self:
+        return Rect(
+            t=self.t + expansion.y,
+            r=self.r + expansion.x,
+            b=self.b - expansion.y,
+            l=self.l - expansion.x,
+        )
+
+    def shrink(self, shrinkage: Vec2, /) -> Self:
+        return Rect(
+            t=self.t - shrinkage.y,
+            r=self.r - shrinkage.x,
+            b=self.b + shrinkage.y,
+            l=self.l + shrinkage.x,
+        )
+
+    def translate(self, translation: Vec2, /) -> Self:
+        return Rect(
+            t=self.t + translation.y,
+            r=self.r + translation.x,
+            b=self.b + translation.y,
+            l=self.l + translation.x,
+        )
 
 
 class QuadLike(Protocol):

sonolus/script/internal/builtin_impls.py

@@ -5,7 +5,7 @@ from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.iterator import ArrayLike, Enumerator, SonolusIterator
 from sonolus.script.math import MATH_BUILTIN_IMPLS
-from sonolus.script.num import Num
+from sonolus.script.num import is_num
 from sonolus.script.range import Range
 
 
@@ -74,7 +74,7 @@ def _max(*args):
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for max")
     else:
-        if not all(isinstance(arg, Num) for arg in args):
+        if not all(is_num(arg) for arg in args):
             raise TypeError("Arguments to max must be numbers")
         if ctx():
             result = compile_and_call(_max2, args[0], args[1])
@@ -114,7 +114,7 @@ def _min(*args):
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for min")
     else:
-        if not all(isinstance(arg, Num) for arg in args):
+        if not all(is_num(arg) for arg in args):
             raise TypeError("Arguments to min must be numbers")
         if ctx():
             result = compile_and_call(_min2, args[0], args[1])

sonolus/script/internal/native.py

@@ -6,14 +6,14 @@ from sonolus.backend.ir import IRInstr, IRPureInstr, IRSet
 from sonolus.backend.ops import Op
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn, validate_value
-from sonolus.script.num import Num
+from sonolus.script.num import Num, is_num
 
 
 def native_call(op: Op, *args: Num) -> Num:
     if not ctx():
         raise RuntimeError("Unexpected native call")
     args = tuple(validate_value(arg) for arg in args)
-    if not all(isinstance(arg, Num) for arg in args):
+    if not all(is_num(arg) for arg in args):
         raise RuntimeError("All arguments must be of type Num")
     result = ctx().alloc(size=1)
     ctx().add_statements(IRSet(result, (IRPureInstr if op.pure else IRInstr)(op, [arg.ir() for arg in args])))

sonolus/script/interval.py

@@ -55,6 +55,12 @@ class Interval(Record):
     def __and__(self, other: Self) -> Self:
         return Interval(max(self.start, other.start), min(self.end, other.end))
 
+    def shrink(self, value: float | int) -> Self:
+        return Interval(self.start + value, self.end - value)
+
+    def expand(self, value: float | int) -> Self:
+        return Interval(self.start - value, self.end + value)
+
     def lerp(self, x: float, /) -> float:
         return lerp(self.start, self.end, x)
 
@@ -67,6 +73,9 @@ class Interval(Record):
     def unlerp_clamped(self, x: float, /) -> float:
         return unlerp_clamped(self.start, self.end, x)
 
+    def clamp(self, x: float, /) -> float:
+        return clamp(x, self.start, self.end)
+
 
 @native_function(Op.Lerp)
 def lerp(a, b, x, /):
@@ -96,3 +105,8 @@ def remap(a, b, c, d, x, /):
 @native_function(Op.RemapClamped)
 def remap_clamped(a, b, c, d, x, /):
     return c + (d - c) * max(0, min(1, (x - a) / (b - a)))
+
+
+@native_function(Op.Clamp)
+def clamp(x, a, b, /):
+    return max(a, min(b, x))

sonolus/script/level.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from sonolus.build.collection import Asset
-from sonolus.script.archetype import PlayArchetype, StandardImport
+from sonolus.script.archetype import PlayArchetype, StandardArchetypeName, StandardImport
 
 
 class Level:
@@ -39,14 +39,14 @@ class LevelData:
 
 
 class BpmChange(PlayArchetype):
-    name = "#BPM_CHANGE"
+    name = StandardArchetypeName.BPM_CHANGE
 
-    beat: StandardImport.Beat
-    bpm: StandardImport.Bpm
+    beat: StandardImport.BEAT
+    bpm: StandardImport.BPM
 
 
 class TimescaleChange(PlayArchetype):
-    name = "#TIMESCALE_CHANGE"
+    name = StandardArchetypeName.TIMESCALE_CHANGE
 
-    beat: StandardImport.Beat
-    timescale: StandardImport.Timescale
+    beat: StandardImport.BEAT
+    timescale: StandardImport.TIMESCALE

sonolus/script/num.py

@@ -1,7 +1,9 @@
 # ruff: noqa: N801
+from __future__ import annotations
+
 import operator
 from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Any, Self, final
+from typing import TYPE_CHECKING, Any, Self, TypeIs, final
 
 from sonolus.backend.ir import IRConst, IRGet, IRPureInstr, IRSet
 from sonolus.backend.ops import Op
@@ -12,14 +14,30 @@ from sonolus.script.internal.impl import meta_fn
 from sonolus.script.internal.value import Value
 
 
+class NumMeta(type):
+    def __instancecheck__(cls, instance):
+        return isinstance(instance, float | int | bool) or is_num(instance)
+
+
+def is_num(value: Any) -> TypeIs[Num]:
+    """Check if a value is a precisely Num instance."""
+    return type.__instancecheck__(Num, value)  # type: ignore # noqa: PLC2801
+
+
 @final
-class _Num(Value):
+class _Num(Value, metaclass=NumMeta):
+    # This works for ints, floats, and bools
+    # Since we don't support complex numbers, real is equal to the original number
+    __match_args__ = ("real",)
+
     data: BlockPlace | float | int | bool
 
     def __init__(self, data: Place | float | int | bool):
+        if isinstance(data, complex):
+            raise TypeError("Cannot create a Num from a complex number")
         if isinstance(data, int):
             data = float(data)
-        if isinstance(data, _Num):
+        if is_num(data):
             raise InternalError("Cannot create a Num from a Num")
         self.data = data
 
@@ -55,7 +73,7 @@ class _Num(Value):
     def _accept_(cls, value: Any) -> Self:
         if not cls._accepts_(value):
             raise TypeError(f"Cannot accept {value}")
-        if isinstance(value, Num):
+        if is_num(value):
             return value
         return cls(value)
 
@@ -368,6 +386,14 @@ class _Num(Value):
     def not_(self) -> Self:
         return self._unary_op(operator.not_, Op.Not)
 
+    @property
+    def real(self) -> Self:
+        return self
+
+    @property
+    def imag(self) -> Self:
+        return 0
+
 
 if TYPE_CHECKING:
 

sonolus/script/options.py

@@ -1,6 +1,6 @@
 # ruff: noqa: A002
 from dataclasses import dataclass
-from typing import Annotated, Any, ClassVar, Protocol, dataclass_transform, get_origin
+from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.mode import Mode
 from sonolus.backend.place import BlockPlace
@@ -124,10 +124,7 @@ def select_option(
     return SelectOption(name, standard, advanced, scope, default, values)
 
 
-class Options(Protocol):
-    _options_: ClassVar[list[SliderOption | ToggleOption | SelectOption]]
-
-
+type Options = NewType("Options", Any)
 type OptionInfo = SliderOption | ToggleOption | SelectOption
 
 
@@ -142,13 +139,13 @@ class OptionField(SonolusDescriptor):
     def __get__(self, instance, owner):
         if ctx():
             match ctx().global_state.mode:
-                case Mode.Play:
+                case Mode.PLAY:
                     block = ctx().blocks.LevelOption
-                case Mode.Watch:
+                case Mode.WATCH:
                     block = ctx().blocks.LevelOption
-                case Mode.Preview:
+                case Mode.PREVIEW:
                     block = ctx().blocks.PreviewOption
-                case Mode.Tutorial:
+                case Mode.TUTORIAL:
                     block = None
                 case _:
                     assert_unreachable()

sonolus/script/particle.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Annotated, Any, Protocol, dataclass_transform, get_origin
+from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.ops import Op
 from sonolus.script.graphics import QuadLike, flatten_quad
@@ -73,8 +73,7 @@ def particle(name: str) -> Any:
     return ParticleInfo(name)
 
 
-class Particles(Protocol):
-    _particles_: list[str]
+type Particles = NewType("Particles", Any)
 
 
 @dataclass_transform()
@@ -103,54 +102,54 @@ def particles[T](cls: type[T]) -> T | Particles:
 
 
 class StandardParticle:
-    NoteCircularTapNeutral = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_NEUTRAL")]
-    NoteCircularTapRed = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_RED")]
-    NoteCircularTapGreen = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_GREEN")]
-    NoteCircularTapBlue = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_BLUE")]
-    NoteCircularTapYellow = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_YELLOW")]
-    NoteCircularTapPurple = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_PURPLE")]
-    NoteCircularTapCyan = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_CYAN")]
-    NoteCircularAlternativeNeutral = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_NEUTRAL")]
-    NoteCircularAlternativeRed = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_RED")]
-    NoteCircularAlternativeGreen = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_GREEN")]
-    NoteCircularAlternativeBlue = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_BLUE")]
-    NoteCircularAlternativeYellow = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_YELLOW")]
-    NoteCircularAlternativePurple = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_PURPLE")]
-    NoteCircularAlternativeCyan = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_CYAN")]
-    NoteCircularHoldNeutral = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_NEUTRAL")]
-    NoteCircularHoldRed = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_RED")]
-    NoteCircularHoldGreen = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_GREEN")]
-    NoteCircularHoldBlue = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_BLUE")]
-    NoteCircularHoldYellow = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_YELLOW")]
-    NoteCircularHoldPurple = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_PURPLE")]
-    NoteCircularHoldCyan = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_CYAN")]
-    NoteLinearTapNeutral = Annotated[Particle, particle("#NOTE_LINEAR_TAP_NEUTRAL")]
-    NoteLinearTapRed = Annotated[Particle, particle("#NOTE_LINEAR_TAP_RED")]
-    NoteLinearTapGreen = Annotated[Particle, particle("#NOTE_LINEAR_TAP_GREEN")]
-    NoteLinearTapBlue = Annotated[Particle, particle("#NOTE_LINEAR_TAP_BLUE")]
-    NoteLinearTapYellow = Annotated[Particle, particle("#NOTE_LINEAR_TAP_YELLOW")]
-    NoteLinearTapPurple = Annotated[Particle, particle("#NOTE_LINEAR_TAP_PURPLE")]
-    NoteLinearTapCyan = Annotated[Particle, particle("#NOTE_LINEAR_TAP_CYAN")]
-    NoteLinearAlternativeNeutral = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_NEUTRAL")]
-    NoteLinearAlternativeRed = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_RED")]
-    NoteLinearAlternativeGreen = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_GREEN")]
-    NoteLinearAlternativeBlue = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_BLUE")]
-    NoteLinearAlternativeYellow = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_YELLOW")]
-    NoteLinearAlternativePurple = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_PURPLE")]
-    NoteLinearAlternativeCyan = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_CYAN")]
-    NoteLinearHoldNeutral = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_NEUTRAL")]
-    NoteLinearHoldRed = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_RED")]
-    NoteLinearHoldGreen = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_GREEN")]
-    NoteLinearHoldBlue = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_BLUE")]
-    NoteLinearHoldYellow = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_YELLOW")]
-    NoteLinearHoldPurple = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_PURPLE")]
-    NoteLinearHoldCyan = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_CYAN")]
-    LaneCircular = Annotated[Particle, particle("#LANE_CIRCULAR")]
-    LaneLinear = Annotated[Particle, particle("#LANE_LINEAR")]
-    SlotCircular = Annotated[Particle, particle("#SLOT_CIRCULAR")]
-    SlotLinear = Annotated[Particle, particle("#SLOT_LINEAR")]
-    JudgeLineCircular = Annotated[Particle, particle("#JUDGE_LINE_CIRCULAR")]
-    JudgeLineLinear = Annotated[Particle, particle("#JUDGE_LINE_LINEAR")]
+    NOTE_CIRCULAR_TAP_NEUTRAL = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_NEUTRAL")]
+    NOTE_CIRCULAR_TAP_RED = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_RED")]
+    NOTE_CIRCULAR_TAP_GREEN = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_GREEN")]
+    NOTE_CIRCULAR_TAP_BLUE = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_BLUE")]
+    NOTE_CIRCULAR_TAP_YELLOW = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_YELLOW")]
+    NOTE_CIRCULAR_TAP_PURPLE = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_PURPLE")]
+    NOTE_CIRCULAR_TAP_CYAN = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_CYAN")]
+    NOTE_CIRCULAR_ALTERNATIVE_NEUTRAL = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_NEUTRAL")]
+    NOTE_CIRCULAR_ALTERNATIVE_RED = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_RED")]
+    NOTE_CIRCULAR_ALTERNATIVE_GREEN = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_GREEN")]
+    NOTE_CIRCULAR_ALTERNATIVE_BLUE = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_BLUE")]
+    NOTE_CIRCULAR_ALTERNATIVE_YELLOW = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_YELLOW")]
+    NOTE_CIRCULAR_ALTERNATIVE_PURPLE = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_PURPLE")]
+    NOTE_CIRCULAR_ALTERNATIVE_CYAN = Annotated[Particle, particle("#NOTE_CIRCULAR_ALTERNATIVE_CYAN")]
+    NOTE_CIRCULAR_HOLD_NEUTRAL = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_NEUTRAL")]
+    NOTE_CIRCULAR_HOLD_RED = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_RED")]
+    NOTE_CIRCULAR_HOLD_GREEN = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_GREEN")]
+    NOTE_CIRCULAR_HOLD_BLUE = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_BLUE")]
+    NOTE_CIRCULAR_HOLD_YELLOW = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_YELLOW")]
+    NOTE_CIRCULAR_HOLD_PURPLE = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_PURPLE")]
+    NOTE_CIRCULAR_HOLD_CYAN = Annotated[Particle, particle("#NOTE_CIRCULAR_HOLD_CYAN")]
+    NOTE_LINEAR_TAP_NEUTRAL = Annotated[Particle, particle("#NOTE_LINEAR_TAP_NEUTRAL")]
+    NOTE_LINEAR_TAP_RED = Annotated[Particle, particle("#NOTE_LINEAR_TAP_RED")]
+    NOTE_LINEAR_TAP_GREEN = Annotated[Particle, particle("#NOTE_LINEAR_TAP_GREEN")]
+    NOTE_LINEAR_TAP_BLUE = Annotated[Particle, particle("#NOTE_LINEAR_TAP_BLUE")]
+    NOTE_LINEAR_TAP_YELLOW = Annotated[Particle, particle("#NOTE_LINEAR_TAP_YELLOW")]
+    NOTE_LINEAR_TAP_PURPLE = Annotated[Particle, particle("#NOTE_LINEAR_TAP_PURPLE")]
+    NOTE_LINEAR_TAP_CYAN = Annotated[Particle, particle("#NOTE_LINEAR_TAP_CYAN")]
+    NOTE_LINEAR_ALTERNATIVE_NEUTRAL = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_NEUTRAL")]
+    NOTE_LINEAR_ALTERNATIVE_RED = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_RED")]
+    NOTE_LINEAR_ALTERNATIVE_GREEN = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_GREEN")]
+    NOTE_LINEAR_ALTERNATIVE_BLUE = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_BLUE")]
+    NOTE_LINEAR_ALTERNATIVE_YELLOW = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_YELLOW")]
+    NOTE_LINEAR_ALTERNATIVE_PURPLE = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_PURPLE")]
+    NOTE_LINEAR_ALTERNATIVE_CYAN = Annotated[Particle, particle("#NOTE_LINEAR_ALTERNATIVE_CYAN")]
+    NOTE_LINEAR_HOLD_NEUTRAL = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_NEUTRAL")]
+    NOTE_LINEAR_HOLD_RED = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_RED")]
+    NOTE_LINEAR_HOLD_GREEN = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_GREEN")]
+    NOTE_LINEAR_HOLD_BLUE = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_BLUE")]
+    NOTE_LINEAR_HOLD_YELLOW = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_YELLOW")]
+    NOTE_LINEAR_HOLD_PURPLE = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_PURPLE")]
+    NOTE_LINEAR_HOLD_CYAN = Annotated[Particle, particle("#NOTE_LINEAR_HOLD_CYAN")]
+    LANE_CIRCULAR = Annotated[Particle, particle("#LANE_CIRCULAR")]
+    LANE_LINEAR = Annotated[Particle, particle("#LANE_LINEAR")]
+    SLOT_CIRCULAR = Annotated[Particle, particle("#SLOT_CIRCULAR")]
+    SLOT_LINEAR = Annotated[Particle, particle("#SLOT_LINEAR")]
+    JUDGE_LINE_CIRCULAR = Annotated[Particle, particle("#JUDGE_LINE_CIRCULAR")]
+    JUDGE_LINE_LINEAR = Annotated[Particle, particle("#JUDGE_LINE_LINEAR")]
 
 
 @particles

sonolus/script/pointer.py

@@ -1,7 +1,7 @@
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.value import Value
-from sonolus.script.num import Num
+from sonolus.script.num import Num, is_num
 
 
 @meta_fn
@@ -14,7 +14,7 @@ def deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
         if not isinstance(block, int):
             raise TypeError("block must be an integer")
     else:
-        if not isinstance(block, Num):
+        if not is_num(block):
             raise TypeError("block must be a Num")
         block = block.index()
     if offset._is_py_():
@@ -22,7 +22,7 @@ def deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
         if not isinstance(offset, int):
             raise TypeError("offset must be an integer")
     else:
-        if not isinstance(offset, Num):
+        if not is_num(offset):
             raise TypeError("offset must be a Num")
         offset = offset.index()
     if not (isinstance(type_, type) and issubclass(type_, Value)):

sonolus/script/preview.py

@@ -0,0 +1,81 @@
+from enum import IntEnum
+
+from sonolus.backend.ops import Op
+from sonolus.script.internal.native import native_function
+from sonolus.script.runtime import HorizontalAlign
+from sonolus.script.vec import Vec2
+
+
+class PrintFormat(IntEnum):
+    NUMBER = 0
+    PERCENTAGE = 1
+    TIME = 10
+    SCORE = 11
+    BPM = 20
+    TIMESCALE = 21
+    BEAT_COUNT = 30
+    MEASURE_COUNT = 31
+    ENTITY_COUNT = 32
+
+
+class PrintColor(IntEnum):
+    THEME = -1
+    NEUTRAL = 0
+    RED = 1
+    GREEN = 2
+    BLUE = 3
+    YELLOW = 4
+    PURPLE = 5
+    CYAN = 6
+
+
+@native_function(Op.Print)
+def _print(
+    value: int | float,
+    format: PrintFormat,  # noqa: A002
+    decimal_places: int,
+    anchor_x: float,
+    anchor_y: float,
+    pivot_x: float,
+    pivot_y: float,
+    width: float,
+    height: float,
+    rotation: float,
+    color: PrintColor,
+    alpha: float,
+    horizontal_align: HorizontalAlign,
+    background: bool,
+):
+    raise NotImplementedError
+
+
+def print_number(
+    value: int | float,
+    *,
+    fmt: PrintFormat,
+    decimal_places: int = 0,
+    anchor: Vec2,
+    pivot: Vec2,
+    dimensions: Vec2,
+    rotation: float = 0,
+    color: PrintColor = PrintColor.THEME,
+    alpha: float = 1,
+    horizontal_align: HorizontalAlign = HorizontalAlign.LEFT,
+    background: bool = False,
+):
+    _print(
+        value,
+        fmt,
+        decimal_places,
+        anchor.x,
+        anchor.y,
+        pivot.x,
+        pivot.y,
+        dimensions.x,
+        dimensions.y,
+        rotation,
+        color,
+        alpha,
+        horizontal_align,
+        background,
+    )