sonolus.py 0.2.0__tar.gz → 0.3.0__tar.gz

sonolus_py-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13t

sonolus_py-0.3.0/.run/Python tests in tests.run.xml

@@ -0,0 +1,21 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Python tests in tests" type="tests" factoryName="Autodetect" nameIsGenerated="true">
+    <module name="sonolus" />
+    <option name="ENV_FILES" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHON_JIT" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="_new_additionalArguments" value="&quot;-n 32 --cov sonolus --cov tests --cov-report xml&quot;" />
+    <option name="_new_target" value="&quot;$PROJECT_DIR$/tests&quot;" />
+    <option name="_new_targetType" value="&quot;PATH&quot;" />
+    <method v="2" />
+  </configuration>
+</component>

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.2.0
+Version: 0.3.0
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
 # Sonolus.py
-Sonolus engine development in Python.
+Sonolus engine development in Python. See [docs](https://sonolus.py.qwewqa.xyz) for more information.

sonolus_py-0.3.0/README.md

@@ -0,0 +1,2 @@
+# Sonolus.py
+Sonolus engine development in Python. See [docs](https://sonolus.py.qwewqa.xyz) for more information.

{sonolus_py-0.2.0 → sonolus_py-0.3.0}/doc_stubs/builtins.pyi

@@ -148,6 +148,9 @@ def len(s: object) -> builtins.int:
 def map[T, S](function: Callable[[T], S], iterable: Iterable[T]) -> Iterator[S]:
     """Apply a function to every item of an iterable and return an iterator.
 
+    Unlike the standard Python map function, it is possible that the function may be called more than once on the
+    same item.
+
     Args:
         function: The function to apply.
         iterable: The iterable to process.

{sonolus_py-0.2.0 → 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.0 → sonolus_py-0.3.0}/docs/concepts/constructs.md

@@ -18,6 +18,8 @@ Most standard Python constructs are supported in Sonolus.py.
 
 ## Overview
 
+The following constructs are supported in Sonolus.py:  
+
 - Expressions:
     - Literals:
         - Numbers (excluding complex numbers): `0`, `1`, `1.0`, `1e3`, `0x1`, `0b1`, `0o1`
@@ -28,8 +30,8 @@ Most standard Python 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)`
@@ -80,18 +82,20 @@ Some expressions can be evaluated at compile time:
 - Comparison: for compile time constant operands: `a == b`, `a != b`, `a > b`, `a < b`, `a >= b`, `a <= b`, ...
 - Variables assigned to compile time constants: `a = 1`, `b = a + 1`, ...
 
-The compiler can make additional inferences when compile time constants are used in certain contexts like control flow:
+Some values like array sizes must be compile-time constants.
+
+The compiler will eliminate branches known to be unreachable at compile time:
 
 ```python
-x = ...
+def f(a):
+    if isinstance(a, Num):
+        debug_log(a)
+    else:
+        debug_log(a.x + a.y)
 
-# This code works because the compiler knows which branch will be taken based on the type of 'x'
-if isinstance(x, Num):
-    debug_log(x)
-elif isinstance(x, Vec2):
-    debug_log(x.x + x.y)
-else:
-    debug_log(-1)
+# This works because `isinstance` is evaluated at compile time and only the first (if) branch is reachable.
+# The second (else) branch is eliminated, so we don't get an error that a does not have 'x' and 'y' attributes.
+f(123)
 ```
 
 ## Variables
@@ -181,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
@@ -385,7 +389,8 @@ def g(a):
 ```
 
 Function returns follow the same rules as variable access. If a function returns a non-num value, it most only
-return that value. There is no restriction of a function only returns a num.
+return that value. If the function always returns a num, it may have any number of returns. Similarly, if a function
+always returns None (`return None` or just `return`), it may have any number of returns.
 
 The following are allowed:
 
@@ -439,11 +444,11 @@ def k():
         return Vec2(1, 2)
 ```
 
-Most functions returning a non-num value should have a single `return` statement at the end.
+Outside of functions returning `None` or a num, most functions should have a single `return` statement at the end.
 
 ### 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.
@@ -475,8 +480,8 @@ Imports are supported at the module level, but not within functions.
 
 ### assert
 
-Assertions are supported. Since error handling is not supported, assertion failures will terminate the current
-callback when running in the Sonolus app.
+Assertions are supported. Assertion failures cannot be handled and will terminate the current
+callback when running in the Sonolus app. In debug mode, the game will also pause to indicate the error.
 
 ```python
 assert a > 0, 'a must be positive'

{sonolus_py-0.2.0 → 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,
+)
+```