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

sonolus/script/archetype.py

@@ -1,16 +1,16 @@
 from __future__ import annotations
 
 import inspect
+from abc import abstractmethod
 from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum, StrEnum
 from types import FunctionType
 from typing import Annotated, Any, ClassVar, Self, TypedDict, get_origin
 
-from sonolus.backend.ir import IRConst, IRInstr
+from sonolus.backend.ir import IRConst, IRExpr, IRInstr, IRPureInstr, IRStmt
 from sonolus.backend.mode import Mode
 from sonolus.backend.ops import Op
-from sonolus.backend.place import BlockPlace
 from sonolus.script.bucket import Bucket, Judgment
 from sonolus.script.internal.callbacks import PLAY_CALLBACKS, PREVIEW_CALLBACKS, WATCH_ARCHETYPE_CALLBACKS, CallbackInfo
 from sonolus.script.internal.context import ctx
@@ -19,9 +19,9 @@ from sonolus.script.internal.generic import validate_concrete_type
 from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_call
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import BackingValue, DataValue, Value
 from sonolus.script.num import Num
-from sonolus.script.pointer import _deref
+from sonolus.script.pointer import _backing_deref, _deref
 from sonolus.script.record import Record
 from sonolus.script.values import zeros
 
@@ -43,6 +43,17 @@ class _ArchetypeFieldInfo:
     storage: _StorageType
 
 
+class _ExportBackingValue(BackingValue):
+    def __init__(self, index: IRExpr):
+        self.index = index
+
+    def read(self) -> IRExpr:
+        raise NotImplementedError("Exported fields are write-only")
+
+    def write(self, value: IRExpr) -> IRStmt:
+        return IRInstr(Op.ExportValue, [self.index, value])
+
+
 class _ArchetypeField(SonolusDescriptor):
     def __init__(self, name: str, data_name: str, storage: _StorageType, offset: int, type_: type[Value]):
         self.name = name
@@ -69,7 +80,20 @@ class _ArchetypeField(SonolusDescriptor):
                     case _ArchetypeLevelData(values=values):
                         result = values[self.name]
             case _StorageType.EXPORTED:
-                raise RuntimeError("Exported fields are write-only")
+                match instance._data_:
+                    case _ArchetypeSelfData():
+
+                        def backing_source(i: IRExpr):
+                            return _ExportBackingValue(IRPureInstr(Op.Add, [i, IRConst(self.offset)]))
+
+                        result = _backing_deref(
+                            backing_source,
+                            self.type,
+                        )
+                    case _ArchetypeReferenceData():
+                        raise RuntimeError("Exported fields of other entities are not accessible")
+                    case _ArchetypeLevelData():
+                        raise RuntimeError("Exported fields are not available in level data")
             case _StorageType.MEMORY:
                 match instance._data_:
                     case _ArchetypeSelfData():
@@ -177,6 +201,23 @@ def imported(*, name: str | None = None) -> Any:
     return _ArchetypeFieldInfo(name, _StorageType.IMPORTED)
 
 
+def entity_data() -> Any:
+    """Declare a field as entity data.
+
+    Entity data is accessible from other entities, but may only be updated in the `preprocess` callback
+    and is read-only in other callbacks.
+
+    It functions like `imported`, except that it is not loaded from the level data.
+
+    Usage:
+        ```
+        class MyArchetype(PlayArchetype):
+            field: int = entity_data()
+        ```
+    """
+    return _ArchetypeFieldInfo(None, _StorageType.IMPORTED)
+
+
 def exported(*, name: str | None = None) -> Any:
     """Declare a field as exported.
 
@@ -418,7 +459,11 @@ class _BaseArchetype:
         bound.apply_defaults()
         data = []
         for field in cls._memory_fields_.values():
-            data.extend(field.type._accept_(bound.arguments[field.name] or zeros(field.type))._to_list_())
+            data.extend(
+                field.type._accept_(
+                    bound.arguments[field.name] if field.name in bound.arguments else zeros(field.type)
+                )._to_list_()
+            )
         native_call(Op.Spawn, archetype_id, *(Num(x) for x in data))
 
     @classmethod
@@ -446,9 +491,7 @@ class _BaseArchetype:
                 raise TypeError("Cannot directly subclass Archetype, use the Archetype subclass for your mode")
             cls._default_callbacks_ = {getattr(cls, cb_info.py_name) for cb_info in cls._supported_callbacks_.values()}
             return
-        if getattr(cls, "_callbacks_", None) is not None:
-            raise TypeError("Cannot subclass Archetypes")
-        if cls.name is None:
+        if cls.name is None or cls.name in {getattr(mro_entry, "name", None) for mro_entry in cls.mro()[1:]}:
             cls.name = cls.__name__
         cls._callbacks_ = []
         for name in cls._supported_callbacks_:
@@ -463,17 +506,32 @@ class _BaseArchetype:
         if cls._field_init_done:
             return
         cls._field_init_done = True
+        for mro_entry in cls.mro()[1:]:
+            if hasattr(mro_entry, "_field_init_done"):
+                mro_entry._init_fields()
         field_specifiers = get_field_specifiers(
             cls, skip={"name", "is_scored", "_callbacks_", "_field_init_done"}
         ).items()
-        cls._imported_fields_ = {}
-        cls._exported_fields_ = {}
-        cls._memory_fields_ = {}
-        cls._shared_memory_fields_ = {}
-        imported_offset = 0
-        exported_offset = 0
-        memory_offset = 0
-        shared_memory_offset = 0
+        if not hasattr(cls, "_imported_fields_"):
+            cls._imported_fields_ = {}
+        else:
+            cls._imported_fields_ = {**cls._imported_fields_}
+        if not hasattr(cls, "_exported_fields_"):
+            cls._exported_fields_ = {}
+        else:
+            cls._exported_fields_ = {**cls._exported_fields_}
+        if not hasattr(cls, "_memory_fields_"):
+            cls._memory_fields_ = {}
+        else:
+            cls._memory_fields_ = {**cls._memory_fields_}
+        if not hasattr(cls, "_shared_memory_fields_"):
+            cls._shared_memory_fields_ = {}
+        else:
+            cls._shared_memory_fields_ = {**cls._shared_memory_fields_}
+        imported_offset = sum(field.type._size_() for field in cls._imported_fields_.values())
+        exported_offset = sum(field.type._size_() for field in cls._exported_fields_.values())
+        memory_offset = sum(field.type._size_() for field in cls._memory_fields_.values())
+        shared_memory_offset = sum(field.type._size_() for field in cls._shared_memory_fields_.values())
         for name, value in field_specifiers:
             if value is ClassVar or get_origin(value) is ClassVar:
                 continue
@@ -504,24 +562,32 @@ class _BaseArchetype:
                         name, field_info.name or name, field_info.storage, imported_offset, field_type
                     )
                     imported_offset += field_type._size_()
+                    if imported_offset > _ENTITY_DATA_SIZE:
+                        raise ValueError("Imported fields exceed entity data size")
                     setattr(cls, name, cls._imported_fields_[name])
                 case _StorageType.EXPORTED:
                     cls._exported_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, exported_offset, field_type
                     )
                     exported_offset += field_type._size_()
+                    if exported_offset > _ENTITY_DATA_SIZE:
+                        raise ValueError("Exported fields exceed entity data size")
                     setattr(cls, name, cls._exported_fields_[name])
                 case _StorageType.MEMORY:
                     cls._memory_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, memory_offset, field_type
                     )
                     memory_offset += field_type._size_()
+                    if memory_offset > _ENTITY_MEMORY_SIZE:
+                        raise ValueError("Memory fields exceed entity memory size")
                     setattr(cls, name, cls._memory_fields_[name])
                 case _StorageType.SHARED:
                     cls._shared_memory_fields_[name] = _ArchetypeField(
                         name, field_info.name or name, field_info.storage, shared_memory_offset, field_type
                     )
                     shared_memory_offset += field_type._size_()
+                    if shared_memory_offset > _ENTITY_SHARED_MEMORY_SIZE:
+                        raise ValueError("Shared memory fields exceed entity shared memory size")
                     setattr(cls, name, cls._shared_memory_fields_[name])
         cls._imported_keys_ = {
             name: i
@@ -541,6 +607,35 @@ class _BaseArchetype:
         cls._spawn_signature_ = inspect.Signature(
             [inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in cls._memory_fields_]
         )
+        cls._post_init_fields()
+
+    @property
+    @abstractmethod
+    def index(self) -> int:
+        """The index of this entity."""
+        raise NotImplementedError
+
+    @meta_fn
+    def ref(self) -> EntityRef[Self]:
+        """Get a reference to this entity.
+
+        Valid both in level data and in callbacks.
+        """
+        match self._data_:
+            case _ArchetypeSelfData():
+                return EntityRef[type(self)](index=self.index)
+            case _ArchetypeReferenceData(index=index):
+                return EntityRef[type(self)](index=index)
+            case _ArchetypeLevelData():
+                result = EntityRef[type(self)](index=-1)
+                result._ref_ = self
+                return result
+            case _:
+                raise RuntimeError("Invalid entity data")
+
+    @classmethod
+    def _post_init_fields(cls):
+        pass
 
 
 class PlayArchetype(_BaseArchetype):
@@ -682,6 +777,7 @@ class PlayArchetype(_BaseArchetype):
         return self._info.state == 2
 
     @property
+    @meta_fn
     def life(self) -> ArchetypeLife:
         """How this entity contributes to life."""
         if not ctx():
@@ -693,6 +789,7 @@ class PlayArchetype(_BaseArchetype):
                 raise RuntimeError("Life is not available in level data")
 
     @property
+    @meta_fn
     def result(self) -> PlayEntityInput:
         """The result of this entity.
 
@@ -706,17 +803,6 @@ class PlayArchetype(_BaseArchetype):
             case _:
                 raise RuntimeError("Result is only accessible from the entity itself")
 
-    def ref(self):
-        """Get a reference to this entity for creating level data.
-
-        Not valid elsewhere.
-        """
-        if not isinstance(self._data_, _ArchetypeLevelData):
-            raise RuntimeError("Entity is not level data")
-        result = EntityRef[type(self)](index=-1)
-        result._ref_ = self
-        return result
-
 
 class WatchArchetype(_BaseArchetype):
     """Base class for watch mode archetypes.
@@ -801,6 +887,7 @@ class WatchArchetype(_BaseArchetype):
         return self._info.state == 1
 
     @property
+    @meta_fn
     def life(self) -> ArchetypeLife:
         """How this entity contributes to life."""
         if not ctx():
@@ -812,6 +899,7 @@ class WatchArchetype(_BaseArchetype):
                 raise RuntimeError("Life is not available in level data")
 
     @property
+    @meta_fn
     def result(self) -> WatchEntityInput:
         """The result of this entity.
 
@@ -825,6 +913,11 @@ class WatchArchetype(_BaseArchetype):
             case _:
                 raise RuntimeError("Result is only accessible from the entity itself")
 
+    @classmethod
+    def _post_init_fields(cls):
+        if cls._exported_fields_:
+            raise RuntimeError("Watch archetypes cannot have exported fields")
+
 
 class PreviewArchetype(_BaseArchetype):
     """Base class for preview mode archetypes.
@@ -857,6 +950,7 @@ class PreviewArchetype(_BaseArchetype):
         """
 
     @property
+    @meta_fn
     def _info(self) -> PreviewEntityInfo:
         if not ctx():
             raise RuntimeError("Calling info is only allowed within a callback")
@@ -873,6 +967,11 @@ class PreviewArchetype(_BaseArchetype):
         """The index of this entity."""
         return self._info.index
 
+    @classmethod
+    def _post_init_fields(cls):
+        if cls._exported_fields_:
+            raise RuntimeError("Preview archetypes cannot have exported fields")
+
 
 @meta_fn
 def entity_info_at(index: Num) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
@@ -974,24 +1073,38 @@ class WatchEntityInput(Record):
 
 
 class EntityRef[A: _BaseArchetype](Record):
-    """Reference to another entity."""
+    """Reference to another entity.
+
+    May be used with `Any` to reference an unknown archetype.
+
+    Usage:
+        ```
+        class MyArchetype(PlayArchetype):
+            ref_1: EntityRef[OtherArchetype] = imported()
+            ref_2: EntityRef[Any] = imported()
+        ```
+    """
 
     index: int
 
     @classmethod
     def archetype(cls) -> type[A]:
+        """Get the archetype type."""
         return cls.type_var_value(A)
 
     def with_archetype(self, archetype: type[A]) -> EntityRef[A]:
+        """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
     def get(self) -> A:
+        """Get the entity."""
         return self.archetype().at(self.index)
 
-    def is_valid(self) -> bool:
+    def archetype_matches(self) -> bool:
+        """Check if entity at the index is precisely of the archetype."""
         return self.index >= 0 and self.archetype().is_at(self.index)
 
-    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]:
         ref = getattr(self, "_ref_", None)
         if ref is None:
             return [self.index]
@@ -1000,9 +1113,18 @@ class EntityRef[A: _BaseArchetype](Record):
                 raise KeyError("Reference to entity not in level data")
             return [level_refs[ref]]
 
+    def _copy_from_(self, value: Self):
+        super()._copy_from_(value)
+        if hasattr(value, "_ref_"):
+            self._ref_ = value._ref_
+
     @classmethod
     def _accepts_(cls, value: Any) -> bool:
-        return super()._accepts_(value) or (cls._type_args_ and cls.archetype() is Any and isinstance(value, EntityRef))
+        return (
+            super()._accepts_(value)
+            or (cls._type_args_ and cls.archetype() is Any and isinstance(value, EntityRef))
+            or (issubclass(type(value), EntityRef) and issubclass(value.archetype(), cls.archetype()))
+        )
 
     @classmethod
     def _accept_(cls, value: Any) -> Self:

sonolus/script/array.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Iterable
 from typing import Any, Self, final
 
+from sonolus.backend.ir import IRConst, IRSet
 from sonolus.backend.place import BlockPlace
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import assert_unreachable
@@ -11,7 +12,7 @@ from sonolus.script.internal.context import ctx
 from sonolus.script.internal.error import InternalError
 from sonolus.script.internal.generic import GenericValue
 from sonolus.script.internal.impl import meta_fn, validate_value
-from sonolus.script.internal.value import Value
+from sonolus.script.internal.value import DataValue, Value
 from sonolus.script.num import Num
 
 
@@ -107,11 +108,11 @@ class Array[T, Size](GenericValue, ArrayLike[T]):
         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(*(cls.element_type()._from_list_(iterator) for _ in range(cls.size())))
 
-    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]:
         match self._value:
             case list():
                 return [entry for value in self._value for entry in value._to_list_(level_refs)]
@@ -159,6 +160,16 @@ class Array[T, Size](GenericValue, ArrayLike[T]):
         else:
             return cls._with_value([cls.element_type()._alloc_() for _ in range(cls.size())])
 
+    @classmethod
+    def _zero_(cls) -> Self:
+        if ctx():
+            place = ctx().alloc(size=cls._size_())
+            result: Self = cls._from_place_(place)
+            ctx().add_statements(*[IRSet(place.add_offset(i), IRConst(0)) for i in range(cls._size_())])
+            return result
+        else:
+            return cls._with_value([cls.element_type()._zero_() for _ in range(cls.size())])
+
     def __len__(self):
         return self.size()
 

sonolus/script/array_like.py

@@ -158,10 +158,14 @@ class ArrayLike[T](Sequence, ABC):
         return min_index
 
     def _max_(self, key: Callable[T, Any] | None = None) -> T:
-        return self[self.index_of_max(key=key)]
+        index = self.index_of_max(key=key)
+        assert index != -1
+        return self[index]
 
     def _min_(self, key: Callable[T, Any] | None = None) -> T:
-        return self[self.index_of_min(key=key)]
+        index = self.index_of_min(key=key)
+        assert index != -1
+        return self[index]
 
     def swap(self, i: Num, j: Num, /):
         """Swap the values at the given indices.

sonolus/script/containers.py

@@ -1,13 +1,44 @@
 from __future__ import annotations
 
+from sonolus.backend.visitor import compile_and_call
 from sonolus.script.array import Array
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import error
+from sonolus.script.internal.context import ctx
+from sonolus.script.internal.impl import meta_fn
 from sonolus.script.iterator import SonolusIterator
+from sonolus.script.num import Num
+from sonolus.script.pointer import _deref
 from sonolus.script.record import Record
 from sonolus.script.values import alloc, copy
 
 
+class Box[T](Record):
+    """A box that contains a value.
+
+    This can be helpful for generic code that can handle both Num and non-Num types.
+
+    Usage:
+        ```python
+        Box[T](value: T)
+        ```
+
+    Examples:
+        ```python
+        box = Box(1)
+        box = Box[int](2)
+
+        x: T = ...
+        y: T = ...
+        box = Box(x)
+        box.value = y  # Works regardless of whether x is a Num or not
+        ```
+    """
+
+    value: T
+    """The value contained in the box."""
+
+
 class Pair[T, U](Record):
     """A generic pair of values.
 
@@ -129,6 +160,17 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
         self._array[self._size] = value
         self._size += 1
 
+    def append_unchecked(self, value: T):
+        """Append the given value to the end of the array without checking the capacity.
+
+        Use with caution as this may cause hard to debug issues if the array is full.
+
+        Args:
+            value: The value to append.
+        """
+        self._array[self._size] = value
+        self._size += 1
+
     def extend(self, values: ArrayLike[T]):
         """Appends copies of the values in the given array to the end of the array.
 
@@ -258,6 +300,130 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
         raise TypeError("unhashable type: 'VarArray'")
 
 
+class ArrayPointer[T](Record, ArrayLike[T]):
+    """An array defined by a size and pointer to the first element.
+
+    This is intended to be created internally and improper use may result in hard to debug issues.
+
+    Usage:
+        ```python
+        ArrayPointer[T](size: int, block: int, offset: int)
+        ```
+    """
+
+    size: int
+    block: int
+    offset: int
+
+    def __len__(self) -> int:
+        """Return the number of elements in the array."""
+        return self.size
+
+    @classmethod
+    def element_type(cls) -> type[T]:
+        """Return the type of the elements in the array."""
+        return cls.type_var_value(T)
+
+    def _check_index(self, index: int):
+        assert 0 <= index < self.size
+
+    @meta_fn
+    def _get_item(self, item: int) -> T:
+        if not ctx():
+            raise TypeError("ArrayPointer values cannot be accessed outside of a context")
+        return _deref(
+            self.block,
+            self.offset + Num._accept_(item) * Num._accept_(self.element_type()._size_()),
+            self.element_type(),
+        )
+
+    @meta_fn
+    def __getitem__(self, item: int) -> T:
+        compile_and_call(self._check_index, item)
+        return self._get_item(item)._get_()
+
+    @meta_fn
+    def __setitem__(self, key: int, value: T):
+        compile_and_call(self._check_index, key)
+        dst = self._get_item(key)
+        if self.element_type()._is_value_type_():
+            dst._set_(value)
+        else:
+            dst._copy_from__(value)
+
+
+class ArraySet[T, Capacity](Record):
+    """A set implemented as an array with a fixed maximum capacity.
+
+    Usage:
+        ```python
+        ArraySet[T, Capacity].new()  # Create a new empty set
+        ```
+
+    Examples:
+        ```python
+        s = ArraySet[int, 10].new()
+        s.add(1)
+        s.add(2)
+        assert 1 in s
+        assert 3 not in s
+        s.remove(1)
+        assert 1 not in s
+        ```
+    """
+
+    _values: VarArray[T, Capacity]
+
+    @classmethod
+    def new(cls):
+        """Create a new empty set."""
+        element_type = cls.type_var_value(T)
+        capacity = cls.type_var_value(Capacity)
+        return cls(VarArray[element_type, capacity].new())
+
+    def __len__(self):
+        """Return the number of elements in the set."""
+        return len(self._values)
+
+    def __contains__(self, value):
+        """Return whether the given value is present in the set."""
+        return value in self._values
+
+    def __iter__(self):
+        """Return an iterator over the values in the set."""
+        return self._values.__iter__()
+
+    def add(self, value: T) -> bool:
+        """Add a copy of the given value to the set.
+
+        This has no effect and returns False if the value is already present or if the set is full.
+
+        Args:
+            value: The value to add.
+
+        Returns:
+            True if the value was added, False otherwise.
+        """
+        return self._values.set_add(value)
+
+    def remove(self, value: T) -> bool:
+        """Remove the given value from the set.
+
+        This has no effect and returns False if the value is not present.
+
+        Args:
+            value: The value to remove.
+
+        Returns:
+            True if the value was removed, False otherwise.
+        """
+        return self._values.set_remove(value)
+
+    def clear(self):
+        """Clear the set, removing all elements."""
+        self._values.clear()
+
+
 class _ArrayMapEntry[K, V](Record):
     key: K
     value: V

sonolus/script/debug.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from contextvars import ContextVar
 from typing import Any, Never
 
@@ -16,8 +16,13 @@ debug_log_callback = ContextVar[Callable[[Num], None]]("debug_log_callback")
 
 
 @meta_fn
-def error(message: str | None = None) -> None:
-    message = message._as_py_() if message is not None else "Error"
+def error(message: str | None = None) -> Never:
+    """Raise an error.
+
+    This function is used to raise an error during runtime.
+    When this happens, the game will pause in debug mode. The current callback will also immediately return 0.
+    """
+    message = validate_value(message)._as_py_() if message is not None else "Error"
     if not isinstance(message, str):
         raise ValueError("Expected a string")
     if ctx():
@@ -28,6 +33,19 @@ def error(message: str | None = None) -> None:
         raise RuntimeError(message)
 
 
+@meta_fn
+def static_error(message: str | None = None) -> Never:
+    """Raise a static error.
+
+    This function is used to raise an error during compile-time if the compiler cannot guarantee that
+    this function will not be called during runtime.
+    """
+    message = validate_value(message)._as_py_() if message is not None else "Error"
+    if not isinstance(message, str):
+        raise ValueError("Expected a string")
+    raise RuntimeError(message)
+
+
 @meta_fn
 def debug_log(value: Num):
     """Log a value in debug mode."""
@@ -75,7 +93,7 @@ def terminate():
         raise RuntimeError("Terminated")
 
 
-def visualize_cfg(fn: Callable[[], Any], passes: list[CompilerPass] | None = None) -> str:
+def visualize_cfg(fn: Callable[[], Any], passes: Sequence[CompilerPass] | None = None) -> str:
     from sonolus.build.compile import callback_to_cfg
 
     if passes is None:

sonolus/script/effect.py

@@ -25,7 +25,7 @@ class Effect(Record):
         """Return whether the effect clip is available."""
         return _has_effect_clip(self.id)
 
-    def play(self, distance: float) -> None:
+    def play(self, distance: float = 0) -> None:
         """Play the effect clip.
 
         If the clip was already played within the specified distance, it will be skipped.
@@ -35,7 +35,7 @@ class Effect(Record):
         """
         _play(self.id, distance)
 
-    def schedule(self, time: float, distance: float) -> None:
+    def schedule(self, time: float, distance: float = 0) -> None:
         """Schedule the effect clip to play at a specific time.
 
         This is not suitable for real-time effects such as responses to user input. Use `play` instead.