sonolus.py 0.4.2__tar.gz → 0.5.1__tar.gz

sonolus_py-0.5.1/.python-version

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

{sonolus_py-0.4.2 → sonolus_py-0.5.1}/PKG-INFO

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

{sonolus_py-0.4.2 → sonolus_py-0.5.1}/doc_stubs/builtins.pyi

@@ -287,3 +287,13 @@ def zip[T](*iterables: Iterable[T]) -> Iterator[tuple[T, ...]]:
         An iterator of aggregated tuples.
     """
     ...
+
+def super(cls: type = ..., instance: Any = ...) -> Any:
+    """Return a proxy object that delegates method calls to a parent or sibling class.
+
+    Args:
+        cls: The class to delegate
+        instance: The instance to delegate to.
+    Returns:
+        A proxy object that can be used to call methods from the parent or sibling class.
+    """

{sonolus_py-0.4.2 → sonolus_py-0.5.1}/docs/concepts/builtins.md

@@ -21,6 +21,7 @@ The supported functions and parameters are listed below.
 - `range(stop)`, `range(start, stop[, step])`
 - `reversed(seq)`
 - `round(number[, ndigits])`
+- `super(type[, object-or-type])`
 - `zip(*iterables)`
 
 ## Standard library modules

sonolus_py-0.5.1/docs/guides/bucket.md

@@ -0,0 +1,80 @@
+# Buckets & Judgement
+
+## Declaring Buckets
+
+[Buckets][sonolus.script.bucket.Bucket] define how notes are displayed on the results screen. Typically, each kind of
+note has its own bucket and therefore its own entry on the results screen. Buckets are defined using the
+[`@buckets`][sonolus.script.bucket.buckets] decorator and the [`bucket`][sonolus.script.bucket.bucket] function:
+
+```python
+from sonolus.script.bucket import buckets, bucket, Bucket, bucket_sprite
+from sonolus.script.text import StandardText
+
+Skin = ...
+
+@buckets
+class Buckets:
+    tap_note: Bucket = bucket(
+        sprites=[
+            bucket_sprite(
+                sprite=Skin.tap_note,
+                x=0,
+                y=0,
+                w=2,
+                h=2,
+                rotation=-90,
+            ),
+        ],
+        unit=StandardText.MILLISECOND_UNIT,
+    )
+```
+
+Buckets have sprites used for diplay on the results screen, which are defined using the
+[`bucket_sprite`][sonolus.script.bucket.bucket_sprite] function. They may also have a unit, which can either be
+a built-in from [`StandardText`][sonolus.script.text.StandardText] or a custom string. Conventionally, the unit for
+most engines should be set to
+[`StandardText.MILLISECOND_UNIT`][sonolus.script.text.StandardText] to indicate that the bucket is
+measured in milliseconds.
+
+## Judgement Windows
+
+Sonolus notes are judged on a scale from best to worst of:
+
+- [`Judgement.PERFECT`][sonolus.script.bucket.Judgment.PERFECT]
+- [`Judgement.GREAT`][sonolus.script.bucket.Judgment.GREAT]
+- [`Judgement.GOOD`][sonolus.script.bucket.Judgment.GOOD]
+- [`Judgement.MISS`][sonolus.script.bucket.Judgment.MISS]
+
+The [`JudgmentWindow`][sonolus.script.bucket.JudgmentWindow] class is useful for defining the judgement windows of a
+note in seconds, and judging a note based on the actual and expected (target) hit times:
+
+```python
+from sonolus.script.bucket import JudgmentWindow, Judgment
+from sonolus.script.interval import Interval
+
+note_judgment_window = JudgmentWindow(
+    perfect=Interval(-0.05, 0.05),
+    great=Interval(-0.1, 0.1),
+    good=Interval(-0.15, 0.15),
+)
+
+actual_time: float = ...
+expected_time: float = ...
+judgment = note_judgment_window.judge(actual=actual_time, expected=expected_time)
+```
+
+## Bucket Window
+
+For each bucket, the [`window`][sonolus.script.bucket.Bucket.window] attribute should be set during preprocessing to
+define the judgment windows for the bucket:
+
+```python
+from sonolus.script.bucket import JudgmentWindow
+
+note_judgment_window: JudgmentWindow = ...
+Buckets = ...
+
+def init_buckets():
+    # Multiply by 1000 so buckets are in milliseconds.
+    Buckets.tap_note.window @= note_judgment_window * 1000
+```

sonolus_py-0.5.1/docs/guides/coming-soon.md

@@ -0,0 +1,3 @@
+# Coming Soon
+
+More guides are coming soon!

sonolus_py-0.5.1/docs/guides/effect.md

@@ -0,0 +1,99 @@
+# Sound Effects
+
+[Sound effects][sonolus.script.effect.Effect] are used to play audio, typically short clips, during the course of
+a level.
+
+## Declaration
+
+Effects are declared with the [`@effects`][sonolus.script.effect.effects] decorator. Standard Sonolus effects are
+declared by using a value from [`StandardEffect`][sonolus.script.effect.StandardEffect] as the type hint.
+Custom effects may also be defined using the [`Effect`][sonolus.script.effect.Effect] type hint and the
+[`effect`][sonolus.script.effect.effect] function.
+
+```python
+from sonolus.script.effect import effects, effect, StandardEffect, Effect
+
+
+@effects
+class Effects:
+    perfect: StandardEffect.PERFECT
+    great: StandardEffect.GREAT
+
+    custom_effect: Effect = effect("name_of_custom_effect")
+```
+
+## Playing an Effect
+
+To play an effect, you can use the [`play`][sonolus.script.effect.Effect.play] method of the effect. This method
+accepts an optional distance parameter to prevent the effect from playing if it was already played within the specified
+time in seconds:
+
+```python
+from sonolus.script.effect import Effect
+
+my_effect: Effect = ...
+my_effect.play()
+my_effect.play(distance=0.1)
+```
+
+Using a small non-zero distance is recommended as two instances of the same effect played in quick
+succession can be unpleasant to hear.
+
+## Scheduling an Effect
+
+An effect can be scheduled to play at a specific time using the [`schedule`][sonolus.script.effect.Effect.schedule]
+method:
+
+```python
+from sonolus.script.effect import Effect
+
+my_effect: Effect = ...
+my_effect.schedule(time=5.0)
+my_effect.schedule(time=5.0, distance=0.1)
+```
+
+Scheduling is not suitable for real-time effects such as responses to user input and may not work if the scheduled
+time is too close to the current time. Use [`play`][sonolus.script.effect.Effect.play] instead for real-time effects.
+
+## Looping an Effect
+
+An effect can be played in a loop using the [`loop`][sonolus.script.effect.Effect.loop] method, which returns a
+[`LoopedEffectHandle`][sonolus.script.effect.LoopedEffectHandle] that can be used to stop the loop:
+
+```python
+from sonolus.script.effect import Effect, LoopedEffectHandle
+
+my_effect: Effect = ...
+loop_handle: LoopedEffectHandle = my_effect.loop()
+
+# Later, stop the loop
+loop_handle.stop()
+```
+
+Similarly, an effect can be scheduled to loop using the [`schedule_loop`][sonolus.script.effect.Effect.schedule_loop]
+method:
+
+```python
+from sonolus.script.effect import Effect
+
+my_effect: Effect = ...
+my_effect.schedule_loop(start_time=3.0).stop(end_time=10.0)
+```
+
+## Checking Effect Availability
+
+Some effects may not be available depending on which effect packs a user has selected. To check if an effect is
+available, you can use the [`is_available`][sonolus.script.effect.Effect.is_available] method:
+
+```python
+from sonolus.script.effect import Effect
+
+my_effect: Effect = ...
+
+if my_effect.is_available():
+    # The effect is available, you can use it.
+    ...
+else:
+    # Do something else, such as using a fallback.
+    ...
+```

sonolus_py-0.5.1/docs/guides/index.md

@@ -0,0 +1,5 @@
+# Guides
+
+This sections contains guides on Sonolus.py features. By going through this section, you'll learn the essential
+concepts needed to understand how existing engines like [pydori](https://github.com/qwewqa/pydori) work and
+to create new engines.

sonolus_py-0.5.1/docs/guides/particle.md

@@ -0,0 +1,93 @@
+# Particles
+
+[Particle effects][sonolus.script.particle.Particle] are typically used for visuals such as the
+effect when a note is hit. They are somewhat similar to sprites, but may contain their own animations
+and support functionality such as looping. However, they come with the restriction that they do not have
+their own z-indexes, and thus are always drawn on top of sprites while having no set order between themselves.
+
+## Declaration
+
+Particles are declared with the [`@particles`][sonolus.script.particle.particles] decorator. Standard Sonolus particles
+are declared by using a value from [`StandardParticle`][sonolus.script.particle.StandardParticle] as the type hint.
+Custom particles may also be defined using the [`Particle`][sonolus.script.particle.Particle] type hint and the
+[`particle`][sonolus.script.particle.particle] function.
+
+```python
+from sonolus.script.particle import particles, particle, StandardParticle, Particle
+
+@particles
+class Particle:
+    tap_note_hit_linear: StandardParticle.NOTE_LINEAR_TAP_CYAN
+    tap_note_hit_circular: StandardParticle.NOTE_CIRCULAR_TAP_CYAN
+
+    custom_particle: Particle = particle("name_of_custom_particle")
+```
+
+## Spawning a Particle
+
+To spawn a particle, you can use the [`spawn`][sonolus.script.particle.Particle.spawn] method of the particle. This 
+method accepts a [`Quad`][sonolus.script.quad.Quad] object that defines the position of the particle on the screen,
+a duration in seconds determining how quick the particle animation should play, and optionally whether the particle
+should loop:
+
+```python
+from sonolus.script.particle import Particle
+from sonolus.script.quad import Quad
+
+my_particle: Particle = ...
+my_quad = Quad(
+    tl=Vec2(-0.5, 0.5),
+    tr=Vec2(0.5, 0.5),
+    bl=Vec2(-0.5, -0.5),
+    br=Vec2(0.5, -0.5),
+)
+handle = my_particle.spawn(my_quad, duration=0.5, loop=False)
+```
+
+The call to [`spawn`][sonolus.script.particle.Particle.spawn] will return a
+[`ParticleHandle`][sonolus.script.particle.ParticleHandle] that can be used to control the particle after it has been 
+spawned.
+
+## Moving a Particle
+
+A particle can be moved using the [`move`][sonolus.script.particle.ParticleHandle.move] method of the
+[`ParticleHandle`][sonolus.script.particle.ParticleHandle]:
+
+```python
+from sonolus.script.particle import ParticleHandle
+from sonolus.script.quad import Quad
+
+my_particle_handle: ParticleHandle = ...
+new_position: Quad = ...
+my_particle_handle.move(new_position)
+```
+
+## Destroying a Particle
+
+A particle can be destroyed using the [`destroy`][sonolus.script.particle.ParticleHandle.destroy] method of the
+[`ParticleHandle`][sonolus.script.particle.ParticleHandle]:
+
+```python
+from sonolus.script.particle import ParticleHandle
+
+my_particle_handle: ParticleHandle = ...
+my_particle_handle.destroy()
+```
+
+## Checking Particle Availability
+
+A particle effect may not be available depending on which effects a user has selected. To check if a particle is
+available, you can use the [`is_available`][sonolus.script.particle.Particle.is_available] method of a 
+[`Particle`][sonolus.script.particle.Particle]:
+
+```python
+from sonolus.script.particle import Particle
+
+my_particle: Particle = ...
+if my_particle.is_available():
+    # The particle is available, you can spawn it.
+    ...
+else:
+    # Do something else, such as using a fallback particle.
+    ...
+```

sonolus_py-0.5.1/docs/guides/play.md

@@ -0,0 +1,102 @@
+# Play
+
+Play mode is generally the most important mode of a Sonolus engine, as it defines the interactive gameplay experience.
+
+## Configuration
+
+Play mode is configured using the [`PlayMode`][sonolus.script.engine.PlayMode] class:
+
+```python
+from sonolus.script.engine import PlayMode
+
+# ... import your archetypes, skin, effects, particles, and buckets
+
+play_mode = PlayMode(
+    archetypes=[
+        Stage,
+        Note,
+        # etc.
+    ],
+    skin=Skin,
+    effects=Effects,
+    particles=Particles,
+    buckets=Buckets,
+)
+```
+
+## Play Archetypes
+
+Gameplay logic in play mode is defined via archetypes. Archetypes may correspond to individual notes, or other gameplay
+elements such as the stage. They may also be dedicated to special purposes such as initializing, input handing, and
+so forth depending on the needs of an engine.
+
+In play mode, archetypes inherit from the [`PlayArchetype`][sonolus.script.archetype.PlayArchetype] class:
+
+```python
+from sonolus.script.archetype import PlayArchetype
+
+
+class Note(PlayArchetype):
+    is_score = True
+
+    # All of these methods are optional
+
+    def preprocess(self):
+        ...
+
+    def spawn_order(self) -> float:
+        ...
+
+    def should_spawn(self) -> bool:
+        ...
+
+    def initialize(self):
+        ...
+
+    def update_sequential(self):
+        ...
+
+    def touch(self):
+        ...
+
+    def update_parallel(self):
+        ...
+
+    def terminate(self):
+        ...
+
+```
+
+Archetypes that correspond to notes and contribute to scoring should set the `is_score` attribute to `True`.
+
+### Entities
+
+Entities are instances of archetypes. For example an engine may have a `Note` archetype, and each individual note is
+considered an entity.
+
+### Callbacks
+
+Callbacks determine the behavior of entities in play mode:
+
+- [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess]:
+  Called as the level is loaded
+- [`spawn_order`][sonolus.script.archetype.PlayArchetype.spawn_order]:
+  Called after preprocessing is done to determine which order entities. should be spawned in.
+  Smaller values are spawned first; a common approach is to use the spawn time of the entity.
+- [`should_spawn`][sonolus.script.archetype.PlayArchetype.should_spawn]:
+  Called to determine whether the entity should be spawned. Called each frame if the previous entity is spawned.
+- [`initialize`][sonolus.script.archetype.PlayArchetype.initialize]:
+  Called when the entity is spawned at the start of the frame. Runs in parallel with other `initialize` calls.
+- [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential]:
+  Called each frame an entity is active after `initialize` callbacks are done.
+  Since it's called sequentially, it can update shared state.
+- [`touch`][sonolus.script.archetype.PlayArchetype.touch]:
+  Called sequentially each frame after `update_sequential` if there's touch input. Has access to touch input data.
+- [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel]:
+  Called after `touch` and `update_sequential` callbacks are done. Runs in parallel with other `update_parallel` calls.
+  Has better performance due to parallel execution, so most logic such as drawing sprites should be done here.
+- [`terminate`][sonolus.script.archetype.PlayArchetype.terminate]:
+  Called after `update_parallel` callbacks are done when an entity is being despawned.
+  Runs in parallel with other `terminate` calls.
+
+If not defined in an archetype, the default behavior of each callback is to do nothing.

sonolus_py-0.5.1/docs/guides/project-structure.md

@@ -0,0 +1,70 @@
+# Project Structure
+
+Typically, a Sonolus.py project will have something resembling the following structure:
+
+```
+<project_name>/
+├── lib/          # Common code shared between modes
+├── play/         # Code for play mode
+├── watch/        # Code for watch mode
+├── preview/      # Code for preview mode
+├── tutorial/     # Code for tutorial mode
+├── .../           # Additional code e.g. for converting charts from other formats
+├── project.py    # Project configuration
+└── level.py      # Level configuration (for development server levels)
+resources/        # Resources for the engine
+```
+
+When starting a new project, you'll probably want to use the
+[template project](https://github.com/qwewqa/sonolus.py-template-project) to initialize your project structure.
+
+## Resources
+
+The `resources/` directory contains the resources used by the engine, and its contents are used by the development
+server. It supports resource source code (like the contents of
+[sonolus-free-pack](https://github.com/Sonolus/sonolus-free-pack)) sonolus collection (`.scp`) files, and raw
+image and audio files.
+
+## Project Configuration
+
+By default, Sonolus.py searches for a module named `project` in the root package of the project (i.e. the
+`<project_name>/project.py` file). This module should contain the project configuration and typically should
+contain the engine configuration as well. For example, pydori's project.py contains the following:
+
+??? note "[pydori/project.py](https://github.com/qwewqa/pydori/blob/master/pydori/project.py)"
+    ```python
+    from sonolus.script.engine import Engine, EngineData
+    from sonolus.script.project import Project
+    
+    from pydori.level import load_levels
+    from pydori.lib.options import Options
+    from pydori.lib.ui import ui_config
+    from pydori.play.mode import play_mode
+    from pydori.preview.mode import preview_mode
+    from pydori.tutorial.mode import tutorial_mode
+    from pydori.watch.mode import watch_mode
+    
+    engine = Engine(
+        name="pydori",
+        title="pydori",
+        skin="pixel",
+        particle="pixel",
+        background="darkblue",
+        data=EngineData(
+            ui=ui_config,
+            options=Options,
+            play=play_mode,
+            watch=watch_mode,
+            preview=preview_mode,
+            tutorial=tutorial_mode,
+        ),
+    )
+    
+    project = Project(
+        engine=engine,
+        levels=load_levels,
+    )
+    ```
+
+This file defines the name and title of the engine, some defaults for players, and links to the various modes as
+well as the ui and option configurations. It also links to the levels to load for the development server.

sonolus_py-0.5.1/docs/guides/screen.md

@@ -0,0 +1,30 @@
+# Screen
+
+Sonolus has a screen coordinate-system with y-coordinates ranging from `+1` at the top of the screen to `-1` at the 
+bottom of the screen. The x-coordinate in the screen depend on the aspect ratio of a device, with `-aspect_ratio` 
+at the left and `+aspect_ratio` at the right. When designing engines, it's important to keep in mind that aspect ratios
+typically range from narrow (e.g. 4:3) to wide (e.g. 21:9) to ensure that nothing is cut off on devices with some
+aspect ratios.
+
+The screen coordinate system is used for drawing sprites, positioning particles, and positioning UI elements.
+
+## Checking Screen Size
+
+You can check aspect ratio using the [`aspect_ratio`][sonolus.script.runtime.aspect_ratio] function:
+
+```python
+from sonolus.script.runtime import aspect_ratio
+
+
+the_aspect_ratio = aspect_ratio()
+```
+
+For convenience, the [`screen`][sonolus.script.runtime.screen] function returns a [`Rect`][sonolus.script.quad.Rect] 
+that can be used to check the coordinates of each corner of the screen:
+
+```python
+from sonolus.script.runtime import screen
+
+the_screen = screen()
+top_left = the_screen.tl
+```

sonolus_py-0.5.1/docs/guides/setup.md

@@ -0,0 +1,15 @@
+# Setup
+
+Sonolus.py is published on [PyPI](https://pypi.org/project/sonolus.py/), and can be installed with any package manager.
+
+For example, you can use pip to install it:
+
+```bash
+pip install sonolus.py
+```
+
+Or add it to a project using [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv add sonolus.py
+```

sonolus_py-0.5.1/docs/guides/skin.md

@@ -0,0 +1,128 @@
+# Skins & Sprites
+
+[Skins][sonolus.script.sprite.skin] define [sprites][sonolus.script.sprite.Sprite] (images) that can be drawn in 
+Sonolus. An engine typically has a single skin used by all modes.
+
+## Declaration
+
+Skins are declared with the [`@skin`][sonolus.script.sprite.skin] decorator. Standard Sonolus sprites are declared by
+using a value from [`StandardSprite`][sonolus.script.sprite.StandardSprite] as the type hint. Custom sprites may also be
+defined using the [`Sprite`][sonolus.script.sprite.Sprite] type hint and the [`sprite`][sonolus.script.sprite.sprite]
+function.
+
+```python
+from sonolus.script.sprite import skin, StandardSprite, sprite, Sprite
+
+
+@skin
+class Skin:
+    tap_note: StandardSprite.NOTE_HEAD_CYAN
+
+    custom_sprite: Sprite = sprite("name_of_custom_sprite")
+```
+
+## Render Mode
+
+The skin also defines the render mode for sprites. This is done by defining a `render_mode` attribute in a skin class
+to a value from [`RenderMode`][sonolus.script.sprite.RenderMode].
+
+```python
+from sonolus.script.sprite import skin, RenderMode
+
+
+@skin
+class Skin:
+    render_mode = RenderMode.LIGHTWEIGHT
+    ...
+```
+
+The three render modes available are:
+
+- [`RenderMode.LIGHTWEIGHT`][sonolus.script.sprite.RenderMode.LIGHTWEIGHT]: Less taxing and well suited for
+engines implementing realistic 3D-like graphs, but is less accurate for some engines.
+- [`RenderMode.STANDARD`][sonolus.script.sprite.RenderMode.STANDARD]: Slower, but more accurate for some engines and
+works better with some special cases such as drawing sprites in a triangular shape.
+- [`RenderMode.DEFAULT`][sonolus.script.sprite.RenderMode.DEFAULT]: Use either `LIGHTWEIGHT` or `STANDARD` based on
+the user's preferences. This is the default mode, and is suitable for engines where `STANDARD` is preferred, but
+are still playable in `LIGHTWEIGHT` when more performance is desired.
+
+## Drawing a Sprite
+
+To draw a sprite, you can use the [`draw`][sonolus.script.sprite.Sprite.draw] method of the sprite. This method
+accepts a [`Quad`][sonolus.script.quad.Quad] object that defines the position of the sprite on the screen, as well as
+an optional z-index to control the rendering order of the sprite and an alpha (transparency) value:
+
+```python
+from sonolus.script.sprite import Sprite
+from sonolus.script.quad import Quad
+from sonolus.script.vec import Vec2
+
+my_sprite: Sprite = ...
+my_quad = Quad(
+    tl=Vec2(-0.5, 0.5),
+    tr=Vec2(0.5, 0.5),
+    bl=Vec2(-0.5, -0.5),
+    br=Vec2(0.5, -0.5),
+)
+my_sprite.draw(my_quad, z=123.4, a=1.0)
+```
+
+Z-index (`z`) is important to set correctly, as it ensures that sprites overlap in the correct order. It's especially
+important for two sprites that may overlap to have different z-index values, or they may conflict and render 
+incorrectly ([z-fighting](https://en.wikipedia.org/wiki/Z-fighting)).
+
+Alpha (`a`) is a value between `0.0` (fully transparent) and `1.0` (fully opaque). It controls the transparency of the
+sprite when drawn. If not provided, it defaults to `1.0`.
+
+## Checking Sprite Availability
+
+Some skins may not have some sprites available, especially custom sprites. To check if a sprite is available, you can
+use the [`is_available`][sonolus.script.sprite.Sprite.is_available] property:
+
+```python
+from sonolus.script.sprite import Sprite
+
+my_sprite: Sprite = ...
+
+if my_sprite.is_available:
+    # The sprite is available, you can use it.
+    ...
+else:
+    # Do something else, such as using a fallback.
+    ...
+```
+
+## Layers
+
+To manage z-indexes, most engines will probably want to have some concept of a "layer" to categorize which
+sprites should be drawn on top of others. Additionally, some offset computed based on position is useful to ensure
+that two sprites on the same layer always have distinct z-indexes to prevent z-fighting.
+
+For example, the pydori engine uses the following code to define layers:
+
+```python
+LAYER_STAGE = 0
+LAYER_LANE = 1
+LAYER_JUDGE_LINE = 2
+
+LAYER_CONNECTOR = 10
+
+LAYER_PREVIEW_COVER = 20
+LAYER_MEASURE_LINE = 21
+LAYER_SIM_LINE = 22
+LAYER_TIME_LINE = 23
+LAYER_BPM_CHANGE_LINE = 24
+LAYER_TIMESCALE_CHANGE_LINE = 25
+
+LAYER_NOTE_HEAD = 30
+LAYER_NOTE = 31
+LAYER_ARROW = 32
+
+
+def get_z(layer: int, lane: float = 0, y: float = 0) -> float:
+    """Calculate z-index based on layer, lane, and y-coordinate.
+
+    Lane and y are used to prevent z-fighting between sprites in the same layer.
+    """
+    return layer * 10000 + lane * 100 + y
+```