sonolus.py 0.2.1__tar.gz → 0.3.0__tar.gz

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.2.1
+Version: 0.3.0
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/docs/concepts/builtins.md

@@ -11,7 +11,8 @@ Sonolus.py comes with support for a number of built-in functions.
 - `isinstance(object, classinfo)`
 - `issubclass(class, classinfo)`
 - `len(s)`
-- `map(function, iterable)`
+- `map(function, iterable)` (note: may differ from standard Python behavior, see 
+  [`map`](../reference/builtins.md#doc_stubs.builtins.map))
 - `max(iterable, *, key=None)`, `max(arg1, arg2, *args, key=None)`
 - `min(iterable, *, key=None)`, `min(arg1, arg2, *args, key=None)`
 - `range(stop)`, `range(start, stop[, step])`

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/docs/concepts/constructs.md

@@ -30,8 +30,8 @@ The following constructs are supported in Sonolus.py:
         - Unary: `+`, `-`, `not`, `~`
         - Binary: `+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `|`, `^`, `<<`, `>>`
         - Comparison: `==`, `!=`, `>`, `<`, `>=`, `<=`, `is`, `is not`, `in`, `not in`
-        - Logical: `and`, `or` (for `Num` arguments only)
-        - Ternary: `a if <condition> else b` (for `Num` conditions only)
+        - Logical: `and`, `or` (for [`Num`](types.md#num) arguments only)
+        - Ternary: `a if <condition> else b` (for [`Num`](types.md#num) conditions only)
         - Attribute: `a.b`
         - Indexing: `a[b]`
         - Call: `f(a, b, c)`
@@ -185,7 +185,7 @@ h = g[0] + g[1] + g[2]
 (i := 1)
 ```
 
-The ternary operator is supported for, but the condition must be a `Num`. If the operands are not nums,
+The ternary operator is supported for, but the condition must be a [`Num`](types.md#num). If the operands are not nums,
 the condition must be a compile-time constant or this will be considered an error:
 
 ```python
@@ -448,7 +448,7 @@ Outside of functions returning `None` or a num, most functions should have a sin
 
 ### Classes
 
-Classes are supported at the module level. User defined classes should subclass `Record` or have a supported
+Classes are supported at the module level. User defined classes should subclass [`Record`][sonolus.script.record.Record] or have a supported
 Sonolus.py decorator such as `@level_memory`.
 
 Methods may have the `@staticmethod`, `@classmethod`, or `@property` decorators.

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/docs/concepts/project.md

@@ -54,7 +54,9 @@ resources/
 ```
 
 ## Modes
-Modes are defined using the `PlayMode`, `WatchMode`, `PreviewMode`, and `TutorialMode` classes:
+Modes are defined using the [`PlayMode`][sonolus.script.engine.PlayMode], [`WatchMode`][sonolus.script.engine.WatchMode], [`PreviewMode`][sonolus.script.engine.PreviewMode], and [`TutorialMode`][sonolus.script.engine.TutorialMode] classes.
+
+### Play Mode
 
 ```python
 from sonolus.script.engine import PlayMode
@@ -78,6 +80,14 @@ play_mode = PlayMode(
 
 ```
 
+Play mode archetypes subclass [`PlayArchetype`][sonolus.script.archetype.PlayArchetype] and should implement the [`should_spawn`][sonolus.script.archetype.PlayArchetype.should_spawn] callback. They may also implement 
+the [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess], [`spawn_order`][sonolus.script.archetype.PlayArchetype.spawn_order], [`initialize`][sonolus.script.archetype.PlayArchetype.initialize], [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential], [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel], [`touch`][sonolus.script.archetype.PlayArchetype.touch], and 
+[`terminate`][sonolus.script.archetype.PlayArchetype.terminate] callbacks.
+
+Archetypes for scored notes should have the [`is_scored`][sonolus.script.archetype.PlayArchetype.is_scored] class variable set to `True`.
+
+### Watch Mode
+
 ```python
 from sonolus.script.engine import WatchMode
 
@@ -100,6 +110,16 @@ watch_mode = WatchMode(
 )
 ```
 
+Watch mode archetypes subclass [`WatchArchetype`][sonolus.script.archetype.WatchArchetype] and should implement the [`spawn_time`][sonolus.script.archetype.WatchArchetype.spawn_time] and [`despawn_time`][sonolus.script.archetype.WatchArchetype.despawn_time] callbacks. 
+They may also implement the [`preprocess`][sonolus.script.archetype.WatchArchetype.preprocess], [`initialize`][sonolus.script.archetype.WatchArchetype.initialize], [`update_sequential`][sonolus.script.archetype.WatchArchetype.update_sequential], [`update_parallel`][sonolus.script.archetype.WatchArchetype.update_parallel], and 
+[`terminate`][sonolus.script.archetype.WatchArchetype.terminate] callbacks.
+
+Watch mode also has the `update_spawn` global callback, which is invoked every frame and should return the reference
+time to compare against spawn and despawn times of archetypes. Typically, this can be either the current time or the
+current scaled time.
+
+### Preview Mode
+
 ```python
 from sonolus.script.engine import PreviewMode
 
@@ -115,6 +135,10 @@ preview_mode = PreviewMode(
 )
 ```
 
+Preview mode archetypes subclass [`PreviewArchetype`][sonolus.script.archetype.PreviewArchetype] and may implement the [`preprocess`][sonolus.script.archetype.PreviewArchetype.preprocess] and [`render`][sonolus.script.archetype.PreviewArchetype.render] callbacks.
+
+### Tutorial Mode
+
 ```python
 from sonolus.script.engine import TutorialMode
 
@@ -138,8 +162,16 @@ tutorial_mode = TutorialMode(
 )
 ```
 
+Tutorial mode does not have archetypes, but it has `preprocess`, `navigate`, and `update` global callbacks.
+
+`preprocess` is invoked once before the tutorial starts.
+
+`navigate` is invoked when the player navigates forward or backward in the tutorial.
+
+`update` is invoked every frame and should handle most of the drawing logic.
+
 ## Levels
-Levels are defined using the `Level` class:
+Levels are defined using the [`Level`][sonolus.script.level.Level] class:
 
 ```python
 from sonolus.script.level import LevelData, BpmChange, Level, TimescaleChange

sonolus_py-0.3.0/docs/concepts/resources.md

@@ -0,0 +1,304 @@
+# Resources & Declarations
+
+## Level Memory & Level Data
+Level memory and level data are defined with the [`@level_memory`][sonolus.script.globals.level_memory] and [`@level_data`][sonolus.script.globals.level_data] class decorators, respectively:
+
+```python
+from sonolus.script.globals import level_memory, level_data
+
+
+@level_memory
+class LevelMemory:
+    value: int
+    
+
+@level_data
+class LevelData:
+    value: int
+```
+
+Alternatively, they may be called as functions as well by passing the type as an argument:
+```python
+from sonolus.script.globals import level_memory, level_data
+from sonolus.script.vec import Vec2
+
+
+level_memory_value = level_memory(Vec2)
+level_data_value = level_data(Vec2)
+```
+
+## Streams
+Streams are defined with the [`@streams`][sonolus.script.stream.streams] decorator:
+
+```python
+from sonolus.script.stream import streams, Stream, StreamGroup
+from sonolus.script.num import Num
+from sonolus.script.vec import Vec2
+
+@streams
+class Streams:
+    stream_1: Stream[Num]  # A stream of Num values
+    stream_2: Stream[Vec2]  # A stream of Vec2 values
+    group_1: StreamGroup[Num, 10]  # A group of 10 Num streams
+    group_2: StreamGroup[Vec2, 5]  # A group of 5 Vec2 streams
+    
+    data_field_1: Num  # A data field of type Num
+    data_field_2: Vec2  # A data field of type Vec2
+```
+    
+Streams and stream groups are declared by annotating class attributes with [`Stream`][sonolus.script.stream.Stream] or [`StreamGroup`][sonolus.script.stream.StreamGroup].
+
+Other types are also supported in the form of data fields. They may be used to store additional data to export from
+Play to Watch mode.
+
+In either case, data is write-only in Play mode and read-only in Watch mode.
+
+This should only be used once in most projects, as multiple decorated classes will overlap with each other and
+interfere when both are used at the same time.
+
+For backwards compatibility, new streams and stream groups should be added to the end of existing ones, and
+lengths and element types of existing streams and stream groups should not be changed. Otherwise, old replays may
+not work on new versions of the engine.
+
+## Skins
+Skins are defined with the [`@skin`][sonolus.script.sprite.skin] decorator:
+
+```python
+from sonolus.script.sprite import skin, StandardSprite, sprite, Sprite, RenderMode
+
+
+@skin
+class Skin:
+    render_mode: RenderMode = RenderMode.DEFAULT
+
+    note: StandardSprite.NOTE_HEAD_RED
+    other: Sprite = sprite("other")
+```
+
+Standard sprites are defined by annotating the field with the corresponding value from [`StandardSprite`][sonolus.script.sprite.StandardSprite].
+
+Custom sprites are defined by annotating the field with [`Sprite`][sonolus.script.sprite.Sprite] and calling [`sprite`][sonolus.script.sprite.sprite] with the sprite name.
+
+To set the render mode for the skin, set the `render_mode` field to the desired value from [`RenderMode`][sonolus.script.sprite.RenderMode].
+
+## Sound Effects
+Sound effects are defined with the [`@effects`][sonolus.script.effect.effects] decorator:
+
+```python
+from sonolus.script.effect import effects, StandardEffect, Effect, effect
+
+
+@effects
+class Effects:
+    tap_perfect: StandardEffect.PERFECT
+    other: Effect = effect("other")
+```
+
+Standard sound effects are defined by annotating the field with the corresponding value from [`StandardEffect`][sonolus.script.effect.StandardEffect].
+
+Custom sound effects are defined by annotating the field with [`Effect`][sonolus.script.effect.Effect] and calling [`effect`][sonolus.script.effect.effect] with the effect name.
+
+## Particles
+Particles are defined with the [`@particles`][sonolus.script.particle.particles] decorator:
+
+```python
+from sonolus.script.particle import particles, StandardParticle, Particle, particle
+
+
+@particles
+class Particles:
+    tap: StandardParticle.NOTE_CIRCULAR_TAP_RED
+    other: Particle = particle("other")
+```
+
+Standard particles are defined by annotating the field with the corresponding value from [`StandardParticle`][sonolus.script.particle.StandardParticle].
+
+Custom particles are defined by annotating the field with [`Particle`][sonolus.script.particle.Particle] and calling [`particle`][sonolus.script.particle.particle] with the particle name.
+
+## Buckets
+Buckets are defined with the [`@buckets`][sonolus.script.bucket.buckets] decorator:
+
+```python
+from sonolus.script.bucket import buckets, bucket_sprite, bucket, Bucket
+from sonolus.script.text import StandardText
+from my_engine.common.skin import Skin
+
+@buckets
+class Buckets:
+    note: Bucket = bucket(
+        sprites=[
+            bucket_sprite(
+                sprite=Skin.note,
+                x=0,
+                y=0,
+                w=2,
+                h=2,
+            )
+        ],
+        unit=StandardText.MILLISECOND_UNIT,
+    )
+```
+
+Buckets are defined by annotating the field with [`Bucket`][sonolus.script.bucket.Bucket] and calling [`bucket`][sonolus.script.bucket.bucket] with the bucket name.
+
+## Tutorial Instructions
+Tutorial instructions are defined with the [`@instructions`][sonolus.script.instruction.instructions] decorator:
+
+```python
+from sonolus.script.instruction import instructions, StandardInstruction, Instruction, instruction
+
+
+@instructions
+class Instructions:
+    tap: StandardInstruction.TAP
+    other: Instruction = instruction("other")
+```
+
+Standard instructions are defined by annotating the field with the corresponding value from [`StandardInstruction`][sonolus.script.instruction.StandardInstruction].
+
+Custom instructions are defined by annotating the field with [`Instruction`][sonolus.script.instruction.Instruction] and calling [`instruction`][sonolus.script.instruction.instruction] with the instruction name.
+
+## Tutorial Instruction Icons
+Tutorial instruction icons are defined with the [`@instruction_icons`][sonolus.script.instruction.instruction_icons] decorator:
+
+```python
+from sonolus.script.instruction import instruction_icons, StandardInstructionIcon, InstructionIcon, instruction_icon
+
+
+@instruction_icons
+class InstructionIcons:
+    hand: StandardInstructionIcon.HAND
+    other: InstructionIcon = instruction_icon("other")
+```
+
+Standard instruction icons are defined by annotating the field with the corresponding value from [`StandardInstructionIcon`][sonolus.script.instruction.StandardInstructionIcon].
+
+Custom instruction icons are defined by annotating the field with [`InstructionIcon`][sonolus.script.instruction.InstructionIcon] and calling [`instruction_icon`][sonolus.script.instruction.instruction_icon] with the icon name.
+
+## Options
+Engine options are defined with the [`@options`][sonolus.script.options.options] decorator:
+
+```python
+from sonolus.script.options import options, select_option, slider_option, toggle_option
+
+
+@options
+class Options:
+    slider_option: float = slider_option(
+        name="Slider Option",
+        standard=True,
+        advanced=False,
+        default=0.5,
+        min=0,
+        max=1,
+        step=0.1,
+        unit="unit",
+        scope="scope",
+    )
+    toggle_option: bool = toggle_option(
+        name="Toggle Option",
+        standard=True,
+        advanced=False,
+        default=True,
+        scope="scope",
+    )
+    select_option: int = select_option(
+        name="Select Option",
+        standard=True,
+        advanced=False,
+        default="value",
+        values=["value"],
+        scope="scope",
+    )
+```
+
+There are three types of options available:
+
+1. [`slider_option`][sonolus.script.options.slider_option]: A slider control for numeric values
+2. [`toggle_option`][sonolus.script.options.toggle_option]: A toggle switch for boolean values
+3. [`select_option`][sonolus.script.options.select_option]: A dropdown menu for selecting from predefined values
+
+## UI
+Ui configuration is defined with the [`UiConfig`][sonolus.script.ui.UiConfig] class:
+
+```python
+from sonolus.script.ui import (
+    EaseType,
+    UiAnimation,
+    UiAnimationTween,
+    UiConfig,
+    UiJudgmentErrorPlacement,
+    UiJudgmentErrorStyle,
+    UiMetric,
+    UiVisibility,
+)
+
+ui_config = UiConfig(
+    scope="my_engine",
+    primary_metric=UiMetric.ARCADE,
+    secondary_metric=UiMetric.LIFE,
+    menu_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    judgment_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    combo_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    primary_metric_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    secondary_metric_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    progress_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    tutorial_navigation_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    tutorial_instruction_visibility=UiVisibility(
+        scale=1.0,
+        alpha=1.0,
+    ),
+    judgment_animation=UiAnimation(
+        scale=UiAnimationTween(
+            start=1.0,
+            end=1.0, 
+            duration=0.0,
+            ease=EaseType.NONE,
+        ),
+        alpha=UiAnimationTween(
+            start=1.0,
+            end=1.0,
+            duration=0.0,
+            ease=EaseType.NONE,
+        ),
+    ),
+    combo_animation=UiAnimation(
+        scale=UiAnimationTween(
+            start=1.2, 
+            end=1.0, 
+            duration=0.2,
+            ease=EaseType.IN_CUBIC,
+        ),
+        alpha=UiAnimationTween(
+            start=1.0,
+            end=1.0, 
+            duration=0.0,
+            ease=EaseType.NONE,
+        ),
+    ),
+    judgment_error_style=UiJudgmentErrorStyle.LATE,
+    judgment_error_placement=UiJudgmentErrorPlacement.TOP,
+    judgment_error_min=0.0,
+)
+```

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/docs/concepts/types.md

@@ -1,5 +1,7 @@
+from sonolus.script.archetype import PlayArchetype
+
 # Types
-Sonolus.py has 3 core types: `Num`, `Array`, and `Record`. representing numeric values, fixed-size arrays, 
+Sonolus.py has 3 core types: [`Num`](#num), [`Array`](#array), and [`Record`](#record). representing numeric values, fixed-size arrays, 
 and custom data structures, respectively. Arrays and records can be nested within each other to create complex data
 structures.
 
@@ -89,13 +91,14 @@ Details:
 
 ## Array
 
-`Array[T, Size]` stores a fixed number of elements of the same type.
+[`Array[T, Size]`][sonolus.script.array.Array] stores a fixed number of elements of the same type.
 
 It has two type parameters:
+
 - `T`: The type of the elements.
 - `Size`: The number of elements.
 
-You can import `Array` from `sonolus.script.array`:
+You can import [`Array`][sonolus.script.array.Array] from `sonolus.script.array`:
 
 ```python
 from sonolus.script.array import Array
@@ -116,7 +119,7 @@ If at least one element is provided, the element type and size can be inferred:
 a3 = Array(1, 2, 3)
 ```
 
-Since `Array` takes type parameters, it is considered a generic type. A version of `Array` with type parameters provided
+Since [`Array`][sonolus.script.array.Array] takes type parameters, it is considered a generic type. A version of [`Array`][sonolus.script.array.Array] with type parameters provided
 is considered a concrete type.
 
 ```python
@@ -184,7 +187,7 @@ assert a == Array(4, 2, 3)
 ```
 
 !!! warning
-    If a value in an array is not a `Num`, updating it will copy the given value into the corresponding element
+    If a value in an array is not a [`Num`](#num), updating it will copy the given value into the corresponding element
     of the array. However, that element remains independent of the original value, which may lead to unexpected
     results when updating either value.
 
@@ -200,7 +203,7 @@ assert a == Array(4, 2, 3)
     ```
     
     For clarity, it's recommended to use the copy from operator (`@=`) when updating elements that are known to be
-    an array or record (see the next section).
+    an array or record.
 
     ```python
     a[0] @= pair
@@ -223,18 +226,18 @@ for element in a:
 
 Other functionality:
 
-`Array` inherits from [ArrayLike][sonolus.script.array_like.ArrayLike] and supports all of its methods.
+[`Array`][sonolus.script.array.Array] inherits from [`ArrayLike`][sonolus.script.array_like.ArrayLike] and supports all of its methods.
 
 ### Instance Checks
 
-Any array is considered an instance of the generic `Array` type.
+Any array is considered an instance of the generic [`Array`][sonolus.script.array.Array] type.
 
 ```python
 a = Array(1, 2, 3)
 assert isinstance(a, Array)
 ```
 
-Only an array with the exact element type and size is considered an instance of a concrete `Array[T, Size]` type.
+Only an array with the exact element type and size is considered an instance of a concrete [`Array[T, Size]`][sonolus.script.array.Array] type.
 
 ```python
 a = Array(1, 2, 3)
@@ -245,8 +248,8 @@ assert not isinstance(a, Array[Pair, 3])
 
 ### Enums
 
-There is limited support for enums containing `Num` values. Methods on enums are not supported. 
-When used as a type, any enum class is treated as `Num` and no enforcement is done on the values.
+There is limited support for enums containing [`Num`](#num) values. Methods on enums are not supported. 
+When used as a type, any enum class is treated as [`Num`](#num) and no enforcement is done on the values.
 
 ```python
 class MyEnum(IntEnum):
@@ -259,9 +262,9 @@ b = Array[MyEnum, 2](1, 2)
 
 ## Record
 
-`Record` is the base class for user-defined types in Sonolus.py. It functions similarly to dataclasses.
+[`Record`][sonolus.script.record.Record] is the base class for user-defined types in Sonolus.py. It functions similarly to dataclasses.
 
-You can import `Record` from `sonolus.script.record`:
+You can import [`Record`][sonolus.script.record.Record] from `sonolus.script.record`:
 
 ```python
 from sonolus.script.record import Record
@@ -269,7 +272,7 @@ from sonolus.script.record import Record
 
 ### Declaration
 
-A record can be defined by inheriting from `Record` and defining zero or more fields as class attributes:
+A record can be defined by inheriting from [`Record`][sonolus.script.record.Record] and defining zero or more fields as class attributes:
 
 ```python
 class MyPair(Record):
@@ -277,7 +280,7 @@ class MyPair(Record):
     second: int
 ```
 
-Fields must be annotated by `Num` (or equivalently `int`, `float`, or `bool`), 
+Fields must be annotated by [`Num`](#num) (or equivalently `int`, `float`, or `bool`), 
 a concrete array type, or a concrete record type.
 
 ```python
@@ -286,7 +289,7 @@ class MyRecord(Record):
     array: Array  # Array is not concrete since it has unspecified type parameters
 ```
 
-A `Record` subclass cannot be further subclassed.
+A [`Record`][sonolus.script.record.Record] subclass cannot be further subclassed.
 
 ```python
 # Not ok:
@@ -296,7 +299,7 @@ class MyPairSubclass(MyPair):
 
 ### Instantiation
 
-A constructor is automatically generated for the `Record` class:
+A constructor is automatically generated for the [`Record`][sonolus.script.record.Record] class:
 
 ```python
 pair_1 = MyPair(1, 2)
@@ -305,7 +308,7 @@ pair_2 = MyPair(first=1, second=2)
 
 ### Generics
 
-`Record` supports generics. If at least one type parameter is provided in the class definition, a generic 
+[`Record`][sonolus.script.record.Record] supports generics. If at least one type parameter is provided in the class definition, a generic 
 record type is created.
 
 ```python
@@ -324,7 +327,7 @@ pair_1 = MyGenericPair[int, int](1, 2)
 pair_2 = MyGenericPair(1, 2)
 ```
 
-The value of a type parameter can be accessed via the `type_var_value()` classmethod.
+The value of a type parameter can be accessed via the [`type_var_value()`][sonolus.script.record.Record.type_var_value] classmethod.
     
 ```python
 class MyGenericRecord[T](Record):
@@ -368,7 +371,7 @@ class MyAddablePair(Record):
 ```
 
 If a dunder method has an in-place variant and the in-place method is not explicitly implemented
-(e.g. `__iadd__` is the in-place variant of `__add__`), `Record` will automatically generate one that 
+(e.g. `__iadd__` is the in-place variant of `__add__`), [`Record`][sonolus.script.record.Record] will automatically generate one that 
 modifies the instance in place:
 
 ```python
@@ -378,7 +381,7 @@ pair += MyAddablePair(3, 4)
 assert pair == reference == MyAddablePair(4, 6)  # The instance is modified in place
 ```
 
-Regular methods, properties, classmethods, and staticmethods can also be defined in a `Record` subclass.
+Regular methods, properties, classmethods, and staticmethods can also be defined in a [`Record`][sonolus.script.record.Record] subclass.
 
 ```python
 class MyRecord(Record):
@@ -414,7 +417,7 @@ assert pair == MyPair(3, 2)
 ```
 
 !!! warning
-    If a value in a record is not a `Num`, updating it will copy the given value into the corresponding field
+    If a value in a record is not a [`Num`](#num), updating it will copy the given value into the corresponding field
     of the record. However, that field remains independent of the original value.
 
     ```python
@@ -437,7 +440,7 @@ assert pair == MyPair(3, 2)
 
 ### Instance Checks
 
-Any record is considered an instance of the generic `Record` type:
+Any record is considered an instance of the generic [`Record`][sonolus.script.record.Record] type:
 
 ```python
 pair = MyPair(1, 2)
@@ -451,7 +454,7 @@ pair = MyGenericPair[int, int](1, 2)
 assert isinstance(pair, MyGenericPair)
 ```
 
-Only an instance of a record with the exact field types is considered an instance of a concrete `Record` type:
+Only an instance of a record with the exact field types is considered an instance of a concrete [`Record`][sonolus.script.record.Record] type:
 
 ```python
 pair = MyPair(1, 2)
@@ -460,10 +463,24 @@ assert not isinstance(pair, MyPair[int, Array[int, 2]])
 ```
 
 ## Transient Types
-In addition to the standard types, the following transient types are available.
-Compared to the standard types, these types come with the restriction that they cannot be used as type parameters
-or as a Record field's type. Otherwise, they can be used like any other type, including passing instances of them as 
-arguments to functions.
+In addition to the core types, the following transient types are available.
+There are some restrictions on how they can be used:
+
+- They cannot be used as type arguments:
+    ```python
+    # Not ok:
+    Array[str, 3]
+    ```
+- They cannot be used as a field types:
+    ```python
+    # Not ok:
+    class MyRecord(Record):
+        field: str
+  
+    # Not ok:
+    class MyArchetype(PlayArchetype):
+        field: str = imported()
+    ```
 
 ### tuple
 

sonolus_py-0.3.0/docs/reference/sonolus.script.stream.md

@@ -0,0 +1,3 @@
+# sonolus.script.stream
+
+::: sonolus.script.stream

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/mkdocs.yml

@@ -9,6 +9,7 @@ theme:
     - navigation.expand
     - navigation.path
     - navigation.indexes
+    - navigation.footer
     - toc.follow
     - navigation.top
   palette:
@@ -106,6 +107,7 @@ nav:
       - reference/sonolus.script.record.md
       - reference/sonolus.script.runtime.md
       - reference/sonolus.script.sprite.md
+      - reference/sonolus.script.stream.md
       - reference/sonolus.script.text.md
       - reference/sonolus.script.timing.md
       - reference/sonolus.script.transform.md

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonolus.py"
-version = "0.2.1"
+version = "0.3.0"
 description = "Sonolus engine development in Python"
 readme = "README.md"
 requires-python = ">=3.12"

{sonolus_py-0.2.1 → sonolus_py-0.3.0}/sonolus/backend/ops.py

@@ -180,6 +180,12 @@ class Op(StrEnum):
     StackSetPointer = ("StackSetPointer", True, False, False)
     StopLooped = ("StopLooped", True, False, False)
     StopLoopedScheduled = ("StopLoopedScheduled", True, False, False)
+    # Streams are immutable when they're readable, so we can treat read operations as pure.
+    StreamGetNextKey = ("StreamGetNextKey", False, True, False)
+    StreamGetPreviousKey = ("StreamGetPreviousKey", False, True, False)
+    StreamGetValue = ("StreamGetValue", False, True, False)
+    StreamHas = ("StreamHas", False, True, False)
+    StreamSet = ("StreamSet", True, False, False)
     Subtract = ("Subtract", False, True, False)
     Switch = ("Switch", False, True, True)
     SwitchInteger = ("SwitchInteger", False, True, True)