sonolus.py 0.1.8__py3-none-any.whl → 0.2.0__py3-none-any.whl

sonolus/build/project.py

@@ -5,7 +5,7 @@ from sonolus.build.engine import package_engine
 from sonolus.build.level import package_level_data
 from sonolus.script.engine import Engine
 from sonolus.script.level import Level
-from sonolus.script.project import Project, ProjectSchema
+from sonolus.script.project import BuildConfig, Project, ProjectSchema
 
 BLANK_PNG = (
     b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x01\x00\x00\x00\x007n\xf9$"
@@ -17,24 +17,24 @@ BLANK_AUDIO = (
 )
 
 
-def build_project_to_collection(project: Project):
+def build_project_to_collection(project: Project, config: BuildConfig):
     collection = load_resources_files_to_collection(project.resources)
-    add_engine_to_collection(collection, project, project.engine)
+    add_engine_to_collection(collection, project, project.engine, config)
     for level in project.levels:
         add_level_to_collection(collection, project, level)
     collection.name = f"{project.engine.name}"
     return collection
 
 
-def add_engine_to_collection(collection: Collection, project: Project, engine: Engine):
-    packaged_engine = package_engine(engine.data)
+def add_engine_to_collection(collection: Collection, project: Project, engine: Engine, config: BuildConfig):
+    packaged_engine = package_engine(engine.data, config)
     item = {
         "name": engine.name,
         "version": engine.version,
         "title": engine.title,
         "subtitle": engine.subtitle,
         "author": engine.author,
-        "tags": [],
+        "tags": [tag.as_dict() for tag in engine.tags],
         "skin": collection.get_item("skins", engine.skin) if engine.skin else collection.get_default_item("skins"),
         "background": collection.get_item("backgrounds", engine.background)
         if engine.background
@@ -53,6 +53,8 @@ def add_engine_to_collection(collection: Collection, project: Project, engine: E
         "rom": collection.add_asset(packaged_engine.rom),
         "configuration": collection.add_asset(packaged_engine.configuration),
     }
+    if engine.description is not None:
+        item["description"] = engine.description
     collection.add_item("engines", engine.name, item)
 
 
@@ -65,16 +67,28 @@ def add_level_to_collection(collection: Collection, project: Project, level: Lev
         "title": level.title,
         "artists": level.artists,
         "author": level.author,
-        "tags": [],
+        "tags": [tag.as_dict() for tag in level.tags],
         "engine": collection.get_item("engines", project.engine.name),
-        "useSkin": {"useDefault": True},
-        "useBackground": {"useDefault": True},
-        "useEffect": {"useDefault": True},
-        "useParticle": {"useDefault": True},
+        "useSkin": {"useDefault": True}
+        if level.use_skin is None
+        else {"useDefault": False, "item": collection.get_item("skins", level.use_skin)},
+        "useBackground": {"useDefault": True}
+        if level.use_background is None
+        else {"useDefault": False, "item": collection.get_item("backgrounds", level.use_background)},
+        "useEffect": {"useDefault": True}
+        if level.use_effect is None
+        else {"useDefault": False, "item": collection.get_item("effects", level.use_effect)},
+        "useParticle": {"useDefault": True}
+        if level.use_particle is None
+        else {"useDefault": False, "item": collection.get_item("particles", level.use_particle)},
         "cover": load_resource(collection, level.cover, project.resources, BLANK_PNG),
         "bgm": load_resource(collection, level.bgm, project.resources, BLANK_AUDIO),
         "data": collection.add_asset(packaged_level_data),
     }
+    if level.description is not None:
+        item["description"] = level.description
+    if level.preview is not None:
+        item["preview"] = load_resource(collection, level.preview, project.resources, BLANK_AUDIO)
     collection.add_item("levels", level.name, item)
 
 
@@ -97,6 +111,7 @@ def load_resources_files_to_collection(base_path: Path) -> Collection:
 def get_project_schema(project: Project) -> ProjectSchema:
     by_archetype: dict[str, dict[str, bool]] = {}
     for archetype in project.engine.data.play.archetypes:
+        archetype._init_fields()
         fields = by_archetype.setdefault(archetype.name, {})
         # If a field is exported, we should exclude it if it's imported in watch mode
         for field in archetype._exported_keys_:
@@ -104,11 +119,15 @@ def get_project_schema(project: Project) -> ProjectSchema:
         for field in archetype._imported_keys_:
             fields[field] = True
     for archetype in project.engine.data.watch.archetypes:
+        archetype._init_fields()
         fields = by_archetype.setdefault(archetype.name, {})
         for field in archetype._imported_keys_:
+            if field in {"#ACCURACY", "#JUDGMENT"}:
+                continue
             if field not in fields:
                 fields[field] = True
     for archetype in project.engine.data.preview.archetypes:
+        archetype._init_fields()
         fields = by_archetype.setdefault(archetype.name, {})
         for field in archetype._imported_keys_:
             fields[field] = True

sonolus/script/archetype.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+from abc import abstractmethod
 from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum, StrEnum
@@ -62,7 +63,9 @@ class _ArchetypeField(SonolusDescriptor):
                         result = _deref(ctx().blocks.EntityData, self.offset, self.type)
                     case _ArchetypeReferenceData(index=index):
                         result = _deref(
-                            ctx().blocks.EntityDataArray, self.offset + index * _ENTITY_DATA_SIZE, self.type
+                            ctx().blocks.EntityDataArray,
+                            Num._accept_(self.offset) + index * _ENTITY_DATA_SIZE,
+                            self.type,
                         )
                     case _ArchetypeLevelData(values=values):
                         result = values[self.name]
@@ -108,7 +111,9 @@ class _ArchetypeField(SonolusDescriptor):
                         target = _deref(ctx().blocks.EntityData, self.offset, self.type)
                     case _ArchetypeReferenceData(index=index):
                         target = _deref(
-                            ctx().blocks.EntityDataArray, self.offset + index * _ENTITY_DATA_SIZE, self.type
+                            ctx().blocks.EntityDataArray,
+                            Num._accept_(self.offset) + index * _ENTITY_DATA_SIZE,
+                            self.type,
                         )
                     case _ArchetypeLevelData(values=values):
                         target = values[self.name]
@@ -119,7 +124,7 @@ class _ArchetypeField(SonolusDescriptor):
                             raise TypeError(f"Expected {self.type}, got {type(value)}")
                         for k, v in value._to_flat_dict_(self.data_name).items():
                             index = instance._exported_keys_[k]
-                            ctx().add_statements(IRInstr(Op.ExportValue, [IRConst(index), Num._accept_(v).ir()]))
+                            ctx().add_statements(IRInstr(Op.ExportValue, [IRConst(index), Num(v).ir()]))
                         return
                     case _ArchetypeReferenceData():
                         raise RuntimeError("Exported fields of other entities are not accessible")
@@ -173,6 +178,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.
 
@@ -342,6 +364,7 @@ class _BaseArchetype:
     is_scored: ClassVar[bool] = False
 
     def __init__(self, *args, **kwargs):
+        self._init_fields()
         if ctx():
             raise RuntimeError("The Archetype constructor is only for defining level data")
         bound = self._data_constructor_signature_.bind_partial(*args, **kwargs)
@@ -354,10 +377,12 @@ class _BaseArchetype:
 
     @classmethod
     def _new(cls):
+        cls._init_fields()
         return object.__new__(cls)
 
     @classmethod
     def _for_compilation(cls):
+        cls._init_fields()
         result = cls._new()
         result._data_ = _ArchetypeSelfData()
         return result
@@ -369,6 +394,13 @@ class _BaseArchetype:
         result._data_ = _ArchetypeReferenceData(index=Num._accept_(index))
         return result
 
+    @classmethod
+    @meta_fn
+    def is_at(cls, index: Num) -> bool:
+        if not ctx():
+            raise RuntimeError("is_at is only available during compilation")
+        return entity_info_at(index).archetype_id == cls.id()
+
     @classmethod
     @meta_fn
     def id(cls):
@@ -396,6 +428,7 @@ class _BaseArchetype:
         Args:
             **kwargs: Entity memory values to inject by field name as defined in the Archetype.
         """
+        cls._init_fields()
         if not ctx():
             raise RuntimeError("Spawn is only allowed within a callback")
         archetype_id = cls.id()
@@ -403,21 +436,30 @@ 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
     def schema(cls) -> ArchetypeSchema:
+        cls._init_fields()
         return {"name": cls.name or "unnamed", "fields": list(cls._imported_fields_)}
 
-    def _level_data_entries(self, level_refs: dict[Any, int] | None = None):
+    def _level_data_entries(self, level_refs: dict[Any, str] | None = None):
+        self._init_fields()
         if not isinstance(self._data_, _ArchetypeLevelData):
             raise RuntimeError("Entity is not level data")
         entries = []
         for name, value in self._data_.values.items():
             field_info = self._imported_fields_.get(name)
             for k, v in value._to_flat_dict_(field_info.data_name, level_refs).items():
-                entries.append({"name": k, "value": v})
+                if isinstance(v, str):
+                    entries.append({"name": k, "ref": v})
+                else:
+                    entries.append({"name": k, "value": v})
         return entries
 
     def __init_subclass__(cls, **kwargs):
@@ -426,19 +468,47 @@ 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__
-        field_specifiers = get_field_specifiers(cls, skip={"name", "is_scored"}).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
+        cls._callbacks_ = []
+        for name in cls._supported_callbacks_:
+            cb = getattr(cls, name)
+            if cb in cls._default_callbacks_:
+                continue
+            cls._callbacks_.append(cb)
+        cls._field_init_done = False
+
+    @classmethod
+    def _init_fields(cls):
+        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()
+        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
@@ -469,24 +539,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
@@ -506,12 +584,30 @@ class _BaseArchetype:
         cls._spawn_signature_ = inspect.Signature(
             [inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in cls._memory_fields_]
         )
-        cls._callbacks_ = []
-        for name in cls._supported_callbacks_:
-            cb = getattr(cls, name)
-            if cb in cls._default_callbacks_:
-                continue
-            cls._callbacks_.append(cb)
+
+    @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")
 
 
 class PlayArchetype(_BaseArchetype):
@@ -653,6 +749,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():
@@ -664,6 +761,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.
 
@@ -677,17 +775,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.
@@ -772,6 +859,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():
@@ -783,6 +871,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.
 
@@ -796,20 +885,6 @@ class WatchArchetype(_BaseArchetype):
             case _:
                 raise RuntimeError("Result is only accessible from the entity itself")
 
-    @property
-    def target_time(self) -> float:
-        """The target time of this entity.
-
-        Only meaningful for scored entities. Determines when combo and score are updated.
-
-        Alias of `result.target_time`.
-        """
-        return self.result.target_time
-
-    @target_time.setter
-    def target_time(self, value: float):
-        self.result.target_time = value
-
 
 class PreviewArchetype(_BaseArchetype):
     """Base class for preview mode archetypes.
@@ -842,6 +917,7 @@ class PreviewArchetype(_BaseArchetype):
         """
 
     @property
+    @meta_fn
     def _info(self) -> PreviewEntityInfo:
         if not ctx():
             raise RuntimeError("Calling info is only allowed within a callback")
@@ -959,18 +1035,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 _to_list_(self, level_refs: dict[Any, int] | None = None) -> list[float | BlockPlace]:
+    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]:
         ref = getattr(self, "_ref_", None)
         if ref is None:
             return [self.index]
@@ -979,6 +1075,28 @@ 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))
+            or (issubclass(type(value), EntityRef) and issubclass(value.archetype(), cls.archetype()))
+        )
+
+    @classmethod
+    def _accept_(cls, value: Any) -> Self:
+        if not cls._accepts_(value):
+            raise TypeError(f"Expected {cls}, got {type(value)}")
+        result = value.with_archetype(cls.archetype())
+        if hasattr(value, "_ref_"):
+            result._ref_ = value._ref_
+        return result
+
 
 class StandardArchetypeName(StrEnum):
     """Standard archetype names."""

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
@@ -111,7 +112,7 @@ class Array[T, Size](GenericValue, ArrayLike[T]):
         iterator = iter(values)
         return cls(*(cls.element_type()._from_list_(iterator) for _ in range(cls.size())))
 
-    def _to_list_(self, level_refs: dict[Any, int] | None = None) -> list[float | BlockPlace]:
+    def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[float | str | BlockPlace]:
         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/bucket.py

@@ -80,6 +80,24 @@ class JudgmentWindow(Record):
             self.good * other,
         )
 
+    def __add__(self, other: float | int) -> JudgmentWindow:
+        """Add a scalar to the intervals."""
+        return JudgmentWindow(
+            self.perfect + other,
+            self.great + other,
+            self.good + other,
+        )
+
+    @property
+    def start(self) -> float:
+        """The start time of the good interval."""
+        return self.good.start
+
+    @property
+    def end(self) -> float:
+        """The end time of the good interval."""
+        return self.good.end
+
 
 class Judgment(IntEnum):
     """The judgment of a hit."""
@@ -147,10 +165,10 @@ class Bucket(Record):
 class _BucketSprite:
     id: int
     fallback_id: int | None
-    x: int
-    y: int
-    w: int
-    h: int
+    x: float
+    y: float
+    w: float
+    h: float
     rotation: float
 
     def to_dict(self):
@@ -185,10 +203,10 @@ def bucket_sprite(
     *,
     sprite: Sprite,
     fallback_sprite: Sprite | None = None,
-    x: int,
-    y: int,
-    w: int,
-    h: int,
+    x: float,
+    y: float,
+    w: float,
+    h: float,
     rotation: float = 0,
 ) -> _BucketSprite:
     """Define a sprite for a bucket."""

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
 
@@ -75,7 +75,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.