Wasabi2D

https://wasabi2d.readthedocs.io/en/stable/
Admin
Wasabi2D is a 2D game engine for Python that makes it easy to use fast, modern graphical effects...
Tokens:24,460
Snippets:339
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Scene.record_video(filename=None)

Source: https://wasabi2d.readthedocs.io/en/stable/scene.html

Starts recording the scene to a video file.

```APIDOC
## Scene.record_video(filename=None)

### Description
Start recording a video in MPEG4 format. Requires ffmpeg to be installed and on the system PATH. If no filename is provided, it saves to a file named video_<time>.mp4 in the current directory.

### Parameters
- **filename** (str) - Optional - The path/name of the file to save the video to.
```

--------------------------------

### wasabi2d.Scene.record_video()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Starts recording the scene to a video file.

```APIDOC
## wasabi2d.Scene.record_video()

### Description
Starts recording the scene to a video file. Requires ffmpeg to be installed and available on the system $PATH.
```

--------------------------------

### Launch a coroutine instance

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Basic usage of clock.coro.run to start a coroutine.

```python3
async def myroutine(param):
    ...

task = clock.coro.run(myroutine(param))
```

--------------------------------

### Play music track

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Start playing a music track from the music directory without needing the file extension.

```python
music.play('handel')
```

--------------------------------

### Initialize a Wasabi2D game

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/intro.rst.txt

The minimal boilerplate required to initialize a scene and start the game loop.

```python
from wasabi2d import Scene, run

scene = Scene()

# The rest of your code goes here.

run()  # keep this at the end of the file
```

--------------------------------

### get(key, default=None)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Retrieves a value or returns a default if the key is missing.

```APIDOC
## get(key, default=None)

### Description
Get a value from the storage. If there is no such key, return default, or None if no default was given.

### Parameters
- **key** (str) - Required - The key to retrieve.
- **default** (any) - Optional - The value to return if the key is missing.
```

--------------------------------

### music.get_volume()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Gets the current volume of the music system.

```APIDOC
## music.get_volume()

### Description
Get the current volume of the music system.
```

--------------------------------

### wasabi2d.chain.LayerRange

Source: https://wasabi2d.readthedocs.io/en/stable/effects.html

Renders a range of layers from back to front, inclusive of start and stop indices.

```APIDOC
## class wasabi2d.chain.LayerRange(start, stop)

### Description
Render a range of layers, in order of lowest id to highest id. Only existing layers are rendered.

### Parameters
- **start** (int, optional) - The starting layer ID (inclusive).
- **stop** (int, optional) - The ending layer ID (inclusive).
```

--------------------------------

### Create a Scene

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Initialize a new scene with specified dimensions.

```python
from wasabi2d import Scene

scene = Scene(width, height)
```

--------------------------------

### Initialize a procedural TileMap

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Create a tile map instance to be used for procedural generation.

```python
tm = scene.layers[0].add_tile_map()
```

--------------------------------

### Initialize storage defaults

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Use setdefault to ensure keys exist with initial values before accessing them.

```python
storage.setdefault('highscore', 0)
```

```python
storage.setdefault('level', 1)
storage.setdefault('player_name', 'Anonymous')
storage.setdefault('inventory', [])
```

--------------------------------

### Create a Scaled Scene

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Configure a scene with a small viewport size and nearest-neighbor scaling for a retro aesthetic.

```python
scene = Scene(
    width=200,
    height=120,
    scaler=True
)
```

--------------------------------

### Interpolate Values

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Iterate through interpolated values between a start and end point over a duration.

```python
async for v in clock.coro.interpolate(1, 20):
    sprite.scale = v
```

--------------------------------

### Scene Constructor

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Initializes a new Scene object with specified dimensions and optional scaling or pixel art settings.

```APIDOC
## Scene(width, height, pixel_art=False, scaler=None)

### Description
Creates a new scene instance. The scene manages graphical primitives and layers.

### Parameters
- **width** (int) - Required - The width of the scene in pixels.
- **height** (int) - Required - The height of the scene in pixels.
- **pixel_art** (bool) - Optional - If True, turns off bilinear interpolation for textures.
- **scaler** (str/bool) - Optional - Scaling mode for the scene (e.g., True, 'nearest', 'linear').
```

--------------------------------

### clock.coro.interpolate(start, end, duration=1.0, tween='linear')

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Interpolates between two values over a specified duration.

```APIDOC
## clock.coro.interpolate(start, end, duration=1.0, tween='linear')

### Description
Interpolate between the values start and end over the given duration.

### Parameters
- **start** (number/tuple) - Required - Starting value.
- **end** (number/tuple) - Required - Ending value.
- **duration** (float) - Optional - Duration in seconds (default 1.0).
- **tween** (string) - Optional - Tweening function name (default 'linear').

### Example
```python
async for v in clock.coro.interpolate(1, 20):
    sprite.scale = v
```
```

--------------------------------

### Create and set tiles in a TileMap

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Initialize a tile map on a layer and assign an image name to specific grid coordinates.

```python
tiles = scene.layers[3].add_tile_map()
tiles[3, 5] = 'tile_sand'
```

--------------------------------

### tone.create(pitch, duration *, waveform='sin', volume=1.0)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Creates and returns a Sound object for later playback.

```APIDOC
## tone.create(pitch, duration *, waveform='sin', volume=1.0)

### Description
Creates and returns a Sound object. Creating notes, particularly long notes, takes time; this function allows you to create notes ahead of time to prevent performance slowdowns during game execution.

### Parameters
- **pitch** (string/number) - Required - The pitch of the note.
- **duration** (number) - Required - The duration of the note.
- **waveform** (string) - Optional - The waveform type (default: 'sin').
- **volume** (number) - Optional - The volume level (default: 1.0).

### Usage Example
```python
beep = tone.create('A3', 0.5)

def on_mouse_down():
    beep.play()
```
```

--------------------------------

### Manage Coroutine Lifecycle

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Demonstrates running a coroutine, handling cancellation, and cleaning up resources.

```python
async def myroutine():
    sprite = ...
    try:
        while True:
            ...
    except clock.coro.Cancelled:
        sprite.delete()

task = clock.coro.run(myroutine())
...
if player.dead:
    task.cancel()
```

--------------------------------

### Pre-creating a sound object

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Use tone.create to generate a Sound object ahead of time, then trigger it using the play method within an event handler.

```python
beep = tone.create('A3', 0.5)

def on_mouse_down():
    beep.play()
```

--------------------------------

### clock.coro.run(coro)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Launches a coroutine instance. The coroutine executes until its first await statement.

```APIDOC
## clock.coro.run(coro)

### Description
Launch the given coroutine instance. The coroutine will be executed as far as its first await at this point.

### Parameters
- **coro** (coroutine) - Required - The coroutine instance to run.

### Returns
- **Task** - A task instance representing the running coroutine.

### Example
```python
async def myroutine(param):
    ...

task = clock.coro.run(myroutine(param))
```
```

--------------------------------

### on_key_up(key, mod)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Called when a key is released.

```APIDOC
## on_key_up(key, mod)

### Description
Called when a key is released.

### Parameters
- **key** (int) - Optional - An integer indicating the key that was released.
- **mod** (int) - Optional - A bitmask of modifier keys that were depressed.
```

--------------------------------

### save()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Manually triggers a save to disk.

```APIDOC
## save()

### Description
Saves the data to disk now. This is typically not required unless reloading a checkpoint.
```

--------------------------------

### Music System Methods

Source: https://wasabi2d.readthedocs.io/en/stable/sound.html

Methods for controlling the music playback system.

```APIDOC
## music.play(name)

### Description
Play a music track from the music directory on an indefinite loop.

## music.play_once(name)

### Description
Play a music track once and then stop.

## music.queue(name)

### Description
Queue a music track to play after the current track finishes.

## music.stop()

### Description
Stop the music.

## music.pause()

### Description
Pause the music temporarily.

## music.unpause()

### Description
Resume paused music.

## music.is_playing()

### Description
Returns True if music is playing, False otherwise.

## music.fadeout(duration)

### Description
Fade out and stop the current music.

### Parameters
- **duration** (float) - Required - Duration in seconds for the fade out.

## music.set_volume(volume)

### Description
Set the music volume.

### Parameters
- **volume** (float) - Required - A number between 0 (silent) and 1 (full volume).

## music.get_volume()

### Description
Get the current music volume.
```

--------------------------------

### Chain multiple animations with coroutines

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Demonstrates chaining sequential animations using await, which is cleaner than nested callbacks.

```python3
async def explode(pos):
    """Create an explosion at pos."""
    sprite = scene.layers[1].add_sprite('explosion', pos=pos)
    sprite.color = (1, 1, 1, 0.3)

    # Explode phase
    await animate(
        sprite,
        duration=0.3,
        tween='accel',
        scale=10,
        angle=2,
        color=(1, 1, 1, 1),
    )

    # Twist phase
    await animate(
        sprite,
        duration=0.1,
        tween='accel_decel',
        angle=10,
    )

    # Collapse phase
    await animate(
        sprite,
        duration=1,
        tween='accel_decel',
        scale=1,
        pos=(pos[0] + 50, pos[1] - 50),
        color=(0, 0, 0, 0)
    )

    # Delete it again
    sprite.delete()

clock.coro.run(explode((400, 400)))
```

--------------------------------

### wasabi2d.Scene

Source: https://wasabi2d.readthedocs.io/en/stable/scene.html

Constructor for the Scene class, which initializes the graphics subsystem and window.

```APIDOC
## class wasabi2d.Scene(width=800, height=600, title='wasabi2d', *, fullscreen=False, icon=None, rootdir=None, scaler=False, background='black', pixel_art=False)

### Description
Initializes the top-level interface for renderable objects and creates the application window.

### Parameters
- **width** (int) - Optional - The width of the window in pixels.
- **height** (int) - Optional - The height of the window in pixels.
- **title** (int) - Optional - The initial window title.
- **fullscreen** (bool) - Optional - Whether to launch in fullscreen mode.
- **icon** (str) - Optional - The icon for the window, as an image name without extension.
- **rootdir** (str) - Optional - The root directory for asset loading.
- **scaler** (Union[str, bool]) - Optional - Activates scene scaling.
- **background** (Union[str, Tuple[float, float, float]]) - Optional - Initial background color.
- **pixel_art** (bool) - Optional - If True, turns off texture filtering.
```

--------------------------------

### music.play(name)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Plays a music track from the music directory on a loop.

```APIDOC
## music.play(name)

### Description
Play a music track from the given file. The track will loop indefinitely. This replaces the currently playing track and cancels any queued tracks.

### Parameters
- **name** (str) - Required - The filename of the music track without the extension.
```

--------------------------------

### music.play_once(name)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Plays a music track once and then stops.

```APIDOC
## music.play_once(name)

### Description
Plays the music track once and stops after completion.

### Parameters
- **name** (str) - Required - The filename of the music track without the extension.
```

--------------------------------

### music.queue(name)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Queues a music track to play after the current track finishes.

```APIDOC
## music.queue(name)

### Description
Queues the track to play after the current track finishes or after any other previously queued tracks.

### Parameters
- **name** (str) - Required - The filename of the music track without the extension.
```

--------------------------------

### Scene.screenshot(filename=None)

Source: https://wasabi2d.readthedocs.io/en/stable/scene.html

Captures a screenshot of the current scene.

```APIDOC
## Scene.screenshot(filename=None)

### Description
Take a screenshot of the current scene. If no filename is provided, it saves to a file named screenshot_<time>.png in the current directory.

### Parameters
- **filename** (str) - Optional - The path/name of the file to save the screenshot to.

### Returns
- **str** - The filename of the saved screenshot.
```

--------------------------------

### Configure Default Scene Chain

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/effects.rst.txt

Sets the default rendering strategy for a new scene, which renders all layers from back to front.

```python
scene.chain = [wasabi2d.chain.LayerRange()]
```

--------------------------------

### Defining flexible event handler signatures

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Wasabi2d supports multiple parameter variations for the same event; parameters are matched by name.

```python
@event
def on_mouse_down():
    print("Mouse button clicked")

@event
def on_mouse_down(pos):
    print("Mouse button clicked at", pos)

@event
def on_mouse_down(button):
    print("Mouse button", button, "clicked")

@event
def on_mouse_down(pos, button):
    print("Mouse button", button, "clicked at", pos)
```

--------------------------------

### Sound Class Methods

Source: https://wasabi2d.readthedocs.io/en/stable/sound.html

Methods available on sound objects loaded from the sounds directory.

```APIDOC
## Sound.play()

### Description
Play the sound.

## Sound.play(loops)

### Description
Play the sound, looping it a specified number of times.

### Parameters
- **loops** (int) - Required - The number of times to loop. Pass -1 to loop forever.

## Sound.stop()

### Description
Stop playing the sound.

## Sound.get_length()

### Description
Get the duration of the sound in seconds.
```

--------------------------------

### Sound.play()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Plays a loaded sound effect. Optionally accepts a loops parameter to repeat the sound.

```APIDOC
## Sound.play(loops=None)

### Description
Plays the sound. If loops is provided, the sound will repeat that many times. Passing -1 will loop the sound indefinitely.

### Parameters
- **loops** (int) - Optional - The number of times to loop the sound. Use -1 for infinite looping.
```

--------------------------------

### Procedural Tile Map Helper Functions

Source: https://wasabi2d.readthedocs.io/en/stable/tile_maps.html

Helper functions for programmatically inserting platform and ladder tiles into a TileMap object.

```python
tm = scene.layers[0].add_tile_map()

def platform(xs, y):
    """Insert a platform into the tile map."""
    x1, x2 = sorted(xs)
    tm[x1, y] = 'platform_left'
    for x in range(x1 + 1, x2):
        tm[x, y] = 'platform_mid'
    tm[x2, y] = 'platform_right'

def ladder(x, ys):
    """Insert a ladder into the tile map."""
    y1, y2 = sorted(ys)
    tm[x, y1] = 'ladder_top'
    for y in range(y1 + 1, y2):
        tm[x, y] = 'ladder_mid'
    tm[x, y2] = 'ladder_btm'

platform((1, 4), 7)
platform((8, 11), 10)
platform((13, 17), 6)
ladder(7, (9, 13))
ladder(18, (5, 12))
```

--------------------------------

### tone.play(pitch, duration, *, waveform='sin', volume=1.0)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Plays a synthesized tone.

```APIDOC
## tone.play(pitch, duration, *, waveform='sin', volume=1.0)

### Description
Play a note at the given pitch for the given duration.

### Parameters
- **pitch** (int/str) - Required - Frequency in Hz or note name (e.g., 'E4').
- **duration** (float) - Required - Duration in seconds.
- **waveform** (str) - Optional - 'sin', 'square', or 'saw'. Defaults to 'sin'.
- **volume** (float) - Optional - Volume level. Defaults to 1.0.
```

--------------------------------

### Draw lines of tiles

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Use bulk drawing operations to fill a line with tiles, optionally providing a list for random selection.

```python
tiles = scene.layers[0].add_tile_map()
tiles.line(
    ['fence1', 'fence2'],  # randomly pick fence tile images
    start=(0, 0),
    end=(20, 0),
)
```

--------------------------------

### music.set_volume(volume)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Sets the volume for the music system.

```APIDOC
## music.set_volume(volume)

### Description
Set the volume of the music system.

### Parameters
- **volume** (float) - Required - A number between 0 (silent) and 1 (full volume).
```

--------------------------------

### wasabi2d.Scene.toggle_recording()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Toggles the video recording state.

```APIDOC
## wasabi2d.Scene.toggle_recording()

### Description
Toggles the video recording state between active and inactive.
```

--------------------------------

### Define platform and ladder generation functions

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Helper functions to populate a tile map with platform and ladder segments based on coordinate ranges.

```python
def platform(xs, y):
    """Insert a platform into the tile map."""
    x1, x2 = sorted(xs)
    tm[x1, y] = 'platform_left'
    for x in range(x1 + 1, x2):
        tm[x, y] = 'platform_mid'
    tm[x2, y] = 'platform_right'

def ladder(x, ys):
    """Insert a ladder into the tile map."""
    y1, y2 = sorted(ys)
    tm[x, y1] = 'ladder_top'
    for y in range(y1 + 1, y2):
        tm[x, y] = 'ladder_mid'
    tm[x, y2] = 'ladder_btm'

platform((1, 4), 7)
platform((8, 11), 10)
platform((13, 17), 6)
ladder(7, (9, 13))
ladder(18, (5, 12))
```

--------------------------------

### Registering a basic mouse event handler

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Use the @event decorator to define a function that triggers on mouse clicks.

```python
@event
def on_mouse_down(pos):
    print(pos)
```

--------------------------------

### update(t, dt, keyboard)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Called repeatedly (60 times per second) to step game logic.

```APIDOC
## update(t, dt, keyboard)

### Description
Called by wasabi2d to step your game logic. This will be called repeatedly, 60 times a second.

### Parameters
- **t** (float) - Optional - The current game time, in seconds
- **dt** (float) - Optional - The time since the last frame, in seconds
- **keyboard** (object) - Optional - The current state of the keyboard
```

--------------------------------

### load()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Reloads storage data from the save file.

```APIDOC
## load()

### Description
Reload the contents of the storage with data from the save file. This will replace any existing data in the storage.
```

--------------------------------

### storage[key] = value

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Sets a value in the persistent storage.

```APIDOC
## storage[key] = value

### Description
Sets a value in the storage. The value is preserved across game sessions.

### Parameters
- **key** (str) - Required - The key to associate with the value.
- **value** (list/tuple/dict/str/float/int/bool/None) - Required - The value to store.
```

--------------------------------

### music.pause()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Pauses the music playback.

```APIDOC
## music.pause()

### Description
Pause the music temporarily. It can be resumed by calling unpause().
```

--------------------------------

### wasabi2d.Scene.screenshot()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Captures a screenshot of the current scene.

```APIDOC
## wasabi2d.Scene.screenshot()

### Description
Captures a screenshot of the current scene and saves it with an automatic filename.
```

--------------------------------

### Manage sprite lifecycle with callbacks

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Alternative approach using on_finished callbacks instead of coroutines.

```python3
def explode(pos):
    """Create an explosion at pos."""
    sprite = scene.layers[1].add_sprite('explosion', pos=pos)

    # Grow, rotate, and fade the sprite
    animate(
        sprite,
        duration=0.3,
        tween='accel',
        scale=10,
        angle=10,
        color=(1, 1, 1, 0),
        on_finished=sprite.delete
    )


explode((400, 400))
```

--------------------------------

### Layer.add_label(...)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/primitives.rst.txt

Creates and returns a text label on the layer.

```APIDOC
## Layer.add_label(...)

### Description
Creates and returns a text label. Fonts must be located in the 'fonts/' directory in TTF format.

### Parameters
- **text** (str) - Required - The content of the label.
- **font** (str) - Required - The name of the font to load.
- **fontsize** (float) - Required - The size of the font in pixels.
- **align** (str) - Required - Text alignment: 'left', 'center', or 'right'.
```

--------------------------------

### Spawn entities using an infinite loop coroutine

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Uses an infinite loop within a coroutine to spawn enemies at regular intervals.

```python3
async def spawn_baddies():
    while True:
        clock.coro.run(enemy())
        await clock.coro.sleep(3)

clock.coro.run(spawn_baddies())
```

--------------------------------

### music.is_playing()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Checks if music is currently playing.

```APIDOC
## music.is_playing()

### Description
Returns True if the music is playing (and is not paused), False otherwise.
```

--------------------------------

### storage[key]

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Retrieves a value from the persistent storage.

```APIDOC
## storage[key]

### Description
Get a value from the storage. Raises a KeyError if the key does not exist.

### Parameters
- **key** (str) - Required - The key to retrieve.
```

--------------------------------

### on_mouse_move(pos, rel, buttons)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Called when the mouse is moved.

```APIDOC
## on_mouse_move(pos, rel, buttons)

### Description
Called when the mouse is moved.

### Parameters
- **pos** (tuple) - Optional - A tuple (x, y) that gives the location that the mouse pointer moved to.
- **rel** (tuple) - Optional - A tuple (delta_x, delta_y) that represent the change in the mouse pointer's position.
- **buttons** (set) - Optional - A set of mouse enum values indicating the buttons that were depressed during the move.
```

--------------------------------

### Storage Methods

Source: https://wasabi2d.readthedocs.io/en/stable/storage.html

Methods available on the storage object for managing persistent data.

```APIDOC
## storage[key] = value

### Description
Sets a value in the storage. The value is persisted across game sessions.

## storage[key]

### Description
Retrieves a value from the storage. Raises a KeyError if the key does not exist.

## setdefault(key, default)

### Description
Inserts a default value into the storage only if the key does not already exist.

## get(key, default=None)

### Description
Retrieves a value from the storage. Returns the provided default value (or None) if the key does not exist.

## clear()

### Description
Removes all stored values from the storage.

## save()

### Description
Forces the storage data to be written to disk immediately.

## load()

### Description
Reloads the storage contents from the save file, overwriting current in-memory data.

## path

### Description
The file system path where the storage data is persisted.
```

--------------------------------

### setdefault(key, default)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Inserts a default value if the key does not exist.

```APIDOC
## setdefault(key, default)

### Description
Insert a default value into the storage, only if no value already exists for this key.

### Parameters
- **key** (str) - Required - The key to check.
- **default** (any) - Required - The value to set if the key is missing.
```

--------------------------------

### wasabi2d.scene.HeadlessScene

Source: https://wasabi2d.readthedocs.io/en/stable/scene.html

Constructor for the HeadlessScene class, used for testing and automated applications without a window.

```APIDOC
## class wasabi2d.scene.HeadlessScene(width=800, height=600, rootdir=None)

### Description
Creates a scene instance that does not create a window, suitable for automated environments.

### Parameters
- **width** (int) - Optional - The width of the scene in pixels.
- **height** (int) - Optional - The height of the scene in pixels.
- **rootdir** (str) - Optional - The root directory for asset loading.
```

--------------------------------

### Handle mouse input and animate objects

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/intro.rst.txt

Uses the event decorator to detect mouse clicks and the animate function to transition object attributes.

```python
from math import hypot
from wasabi2d import animate, event

@event
def on_mouse_down(pos):
    mouse_x, mouse_y = pos
    cx, cy = circle.pos

    hit = hypot(mouse_x - cx, mouse_y - cy) < circle.radius

    if hit:
        circle.radius = 50
        animate(circle, 'bounce_end', radius=30)
```

--------------------------------

### TileMap Access Methods

Source: https://wasabi2d.readthedocs.io/en/stable/tile_maps.html

Methods for accessing, setting, and clearing individual tiles within a TileMap.

```APIDOC
## TileMap.__setitem__(pos, value)
### Description
Sets the tile at the specified position.
### Parameters
- **pos** (Tuple[int, int]) - The coordinate position.
- **value** (str) - The tile identifier.

## TileMap.__getitem__(pos)
### Description
Retrieves the tile at the specified position.
### Parameters
- **pos** (Tuple[int, int]) - The coordinate position.

## TileMap.get(pos, default=None)
### Description
Retrieves the tile at the specified position, returning the default value if no tile exists.
### Parameters
- **pos** (Tuple[int, int]) - The coordinate position.
- **default** (T) - Optional default value.

## TileMap.setdefault(pos, value)
### Description
Sets a tile at the position only if it is not already set, returning the resulting tile value.
### Parameters
- **pos** (Tuple[int, int]) - The coordinate position.
- **value** (str) - The tile identifier.

## TileMap.__delitem__(pos)
### Description
Clears the tile at the specified position.
### Parameters
- **pos** (Tuple[int, int]) - The coordinate position.

## TileMap.clear()
### Description
Clears all tiles in the tile map.
```

--------------------------------

### clock.schedule_interval(callback, interval, strong=False)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/clock.rst.txt

Schedules a callback to be called repeatedly at a fixed interval.

```APIDOC
## clock.schedule_interval(callback, interval, strong=False)

### Description
Schedule callback to be called repeatedly.

### Parameters
- **callback** (callable) - Required - A callable that takes no arguments.
- **interval** (float) - Required - The interval in seconds between calls to callback.
- **strong** (bool) - Optional - Hold a strong reference to callback. Defaults to False.
```

--------------------------------

### Play a sound on mouse click

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Trigger a sound effect when the mouse is clicked by defining an on_mouse_down function.

```python
def on_mouse_down():
    sounds.drum.play()
```

--------------------------------

### music.unpause()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Resumes paused music playback.

```APIDOC
## music.unpause()

### Description
Unpause the music.
```

--------------------------------

### Sound.get_length()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Retrieves the duration of the sound.

```APIDOC
## Sound.get_length()

### Description
Get the duration of the sound in seconds.
```

--------------------------------

### Implementing a time-based update function

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Use the dt parameter to scale movement calculations based on elapsed time for smoother animation.

```python
@event
def update(dt, keyboard):
    v = 20 * dt

    if keyboard.right:
        alien.pos[0] += v
    elif keyboard.left:
        alien.pos[0] -= v
    if keyboard.up:
        alien.pos[1] -= v
    elif keyboard.down:
        alien.pos[1] += v
```

--------------------------------

### clock.schedule(callback, delay, strong=False)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/clock.rst.txt

Schedules a callback function to be executed after a specified delay.

```APIDOC
## clock.schedule(callback, delay, strong=False)

### Description
Schedules a callback to be called after the given delay. Repeated calls will schedule the callback repeatedly.

### Parameters
- **callback** (callable) - Required - A callable that takes no arguments.
- **delay** (float) - Required - The delay, in seconds, before the function should be called.
- **strong** (bool) - Optional - Hold a strong reference to callback. Defaults to False.
```

--------------------------------

### Update and read storage values

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Update persistent values during gameplay and retrieve them for display or logic.

```python
if player.colliderect(mushroom):
    score += 5
    if score > storage['highscore']:
        storage['highscore'] = score
```

```python
def draw():
    ...
    screen.draw.text('Highscore: ' + storage['highscore'], ...)
```

--------------------------------

### on_mouse_up(pos, button)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Called when a mouse button is released.

```APIDOC
## on_mouse_up(pos, button)

### Description
Called when a mouse button is released.

### Parameters
- **pos** (tuple) - Optional - A tuple (x, y) that gives the location of the mouse pointer when the button was released.
- **button** (mouse enum) - Optional - An enum value indicating the button that was released.
```

--------------------------------

### clock.call_soon(callback)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/clock.rst.txt

Schedules a callback to be called on the next tick.

```APIDOC
## clock.call_soon(callback)

### Description
Schedule callback to be called on the next tick. Callback will be strongly referenced.

### Parameters
- **callback** (callable) - Required - A one argument callable.
```

--------------------------------

### Group.extend

Source: https://wasabi2d.readthedocs.io/en/stable/groups.html

Adds a list of transformable objects to the group.

```APIDOC
## Group.extend(transformables)

### Description
Add multiple transformables to the group.

### Parameters
- **transformables** (List[wasabi2d.primitives.base.Transformable]) - Required - The list of objects to add to the group.
```

--------------------------------

### Camera.screen_shake

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/scene.rst.txt

Triggers a screen shake effect on the camera.

```APIDOC
## Camera.screen_shake(duration, magnitude)

### Description
Applies a screen shake effect to the camera for a specified duration and magnitude.

### Parameters
- **duration** (float) - Required - The duration of the shake effect.
- **magnitude** (float) - Required - The intensity of the shake.
```

--------------------------------

### music.stop()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Stops the music playback.

```APIDOC
## music.stop()

### Description
Stop the music.
```

--------------------------------

### Group(primitives)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Constructs a new group containing the specified list of primitives. Each primitive can belong to at most one group.

```APIDOC
## Group(primitives)

### Description
Constructs a group by giving it a list of the primitives it should contain. The list may be empty.

### Parameters
- **primitives** (list) - Required - A list of primitives to include in the group.
```

--------------------------------

### wasabi2d.chain.Layers

Source: https://wasabi2d.readthedocs.io/en/stable/effects.html

Renders specific layers in the order provided in the list.

```APIDOC
## class wasabi2d.chain.Layers(layers)

### Description
Render specific layers in the specified order. Only existing layers are rendered.

### Parameters
- **layers** (List[int]) - A list of layer IDs to render.
```

--------------------------------

### clock.each_tick(callback, strong=False)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/clock.rst.txt

Schedules a callback to be called every frame tick.

```APIDOC
## clock.each_tick(callback, strong=False)

### Description
Schedule callback to be called every tick. The callback is required to accept a parameter 'dt' which is the time in seconds since the last tick.

### Parameters
- **callback** (callable) - Required - A one argument callable.
- **strong** (bool) - Optional - Hold a strong reference to callback. Defaults to False.
```

--------------------------------

### on_key_down(key, mod, unicode)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Called when a key is depressed.

```APIDOC
## on_key_down(key, mod, unicode)

### Description
Called when a key is depressed.

### Parameters
- **key** (int) - Optional - An integer indicating the key that was pressed.
- **mod** (int) - Optional - A bitmask of modifier keys that were depressed.
- **unicode** (str) - Optional - The character that was typed, if relevant.
```

--------------------------------

### animate(sprite, **kwargs)

Source: https://wasabi2d.readthedocs.io/en/stable/coros.html

Awaits the completion of an animation.

```APIDOC
## animate(sprite, **kwargs)

### Description
Await the completion of an animation applied to a sprite.

### Usage
`await animate(sprite, angle=6)`
```

--------------------------------

### Layer.add_tile_map

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Creates a new, blank tile map within a layer.

```APIDOC
## Layer.add_tile_map(*, tile_size: Tuple[int, int] = None, any_size_tile: bool = False) -> TileMap

### Description
Creates a new, blank tile map within a layer. The tile size can be inferred from the first inserted tile or explicitly defined.

### Parameters
- **tile_size** (Tuple[int, int]) - Optional - The dimensions of each tile. If omitted, it is inferred from the first tile inserted.
- **any_size_tile** (bool) - Optional - If True, allows setting images of any size and resizes them; if True, tile_size is required.
```

--------------------------------

### wasabi2d.chain.Fill

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/effects.rst.txt

A class used to fill the scene with a specific color, overwriting existing content.

```APIDOC
## wasabi2d.chain.Fill

### Description
Fills the scene with a color. This overwrites everything, even if the color has partial transparency, and is primarily useful as input to effects like Mask.

### Attributes
- **color** (color) - The color that will be used to fill the buffer.
```

--------------------------------

### Constructing and Transforming a Group

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Create a group from multiple sprites and apply transformations to the group as a whole.

```python
ship = wasabi2d.Group([
    scene.layers[0].add_sprite('ship'),
    scene.layers[1].add_sprite('ship_exhaust', pos=(-10, 0))
])

ship.pos = 500, 300
ship.scale = 2
```

--------------------------------

### Create a Sprite

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/primitives.rst.txt

Adds a sprite to the first layer of the scene at a specified position.

```python
ship = scene.layers[0].add_sprite(
    'ship',
    pos=(scene.width / 2, scene.height / 2)
)
```

--------------------------------

### Managing Group Items as a List

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Groups support standard list operations for accessing, replacing, and deleting contained objects.

```python
group = Group([
    scene.layers[0].add_sprite('ship'),
    scene.layers[1].add_sprite('ship_exhaust', pos=(-10, 0))
])

print(len(group))  # count the items in a group
ship, exhaust = group  # iterate over the items

ship = group[0]  # get an item
group[1] = scene.layers[1].add_sprite('ship_boost')  # replace
del group[0]  # delete an item
```

--------------------------------

### Await Animation

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Wait for an animation to complete.

```python
await animate(sprite, angle=6)
```

--------------------------------

### Define enemy movement behavior with coroutines

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Individual enemy behavior managed by a coroutine that iterates over frames.

```python3
target = (400, 400)  # update this


async def enemy():
    # Spawn a blob
    pos = random_pos()
    e = scene.layers[0].add_circle(
        radius=10,
        color=random_color()
        pos=pos,
    )

    # Move inexorably towards target
    async for dt in clock.coro.frames_dt():
        to_target = target - pos
        if to_target.magnitude() < e.radius:
            # We hit!
            break
        pos += to_target.normalize() * 100 * dt
        e.pos = pos

    # Explode, using the effect above
    e.delete()
    await explode(pos)
```

--------------------------------

### on_music_end()

Source: https://wasabi2d.readthedocs.io/en/stable/events.html

Called when a music track finishes.

```APIDOC
## on_music_end()

### Description
Called when a music track finishes. Note that this will not be called if the track is configured to loop.
```

--------------------------------

### wasabi2d.Group

Source: https://wasabi2d.readthedocs.io/en/stable/groups.html

Constructor for creating a new Group instance to manage a collection of transformable primitives.

```APIDOC
## class wasabi2d.Group(transformables, *, pos=(0.0, 0.0), angle=0.0, scale=1.0)

### Description
Constructs a group containing a list of primitives. A group acts as a separate local coordinate system for its contents, allowing collective transformations.

### Parameters
- **transformables** (List[wasabi2d.primitives.base.Transformable]) - Required - A list of primitives to include in the group.
- **pos** (Tuple[float, float]) - Optional - The initial position of the group (default: 0.0, 0.0).
- **angle** (float) - Optional - The initial rotation angle of the group (default: 0.0).
- **scale** (float) - Optional - The initial scale factor of the group (default: 1.0).
```

--------------------------------

### Layer.add_star

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/primitives.rst.txt

Creates and adds a star primitive to a layer.

```APIDOC
## Layer.add_star(*, points, [options])

### Description
Creates and returns a star object.

### Parameters
- **points** (int) - Required - Number of points for the star.
- **outer_radius** (float) - Optional - Radius of the tips.
- **inner_radius** (float) - Optional - Radius of the inner corners.
- **fill** (bool) - Optional - If True, the shape is filled.
- **stroke_width** (int) - Optional - The width of the outline if not filled.
```

--------------------------------

### Sound.stop()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/sound.rst.txt

Stops the playback of a sound.

```APIDOC
## Sound.stop()

### Description
Stops playing the sound.
```

--------------------------------

### Manage sprite lifecycle with coroutines

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/coros.rst.txt

Uses a single coroutine to handle sprite creation, animation, and deletion.

```python3
async def explode(pos):
    """Create an explosion at pos."""
    sprite = scene.layers[1].add_sprite('explosion', pos=pos)

    # Grow, rotate, and fade the sprite
    await animate(
        sprite,
        duration=0.3,
        tween='accel',
        scale=10,
        angle=10,
        color=(1, 1, 1, 0),
    )

    # Delete it again
    sprite.delete()

clock.coro.run(explode((400, 400)))
```

--------------------------------

### Group.local_to_world(pos)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Converts a position from the group's local coordinate system to the world coordinate system.

```APIDOC
## Group.local_to_world(pos)

### Description
Converts a position from the group's local coordinate system to the world coordinate system.

### Parameters
- **pos** (tuple) - Required - The local position (x, y).
```

--------------------------------

### Tile Drawing Operations

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Bulk operations for drawing lines, rectangles, and flood fills on the tile map.

```APIDOC
## Tile Drawing Operations

### Description
Methods to update the map in bulk. These accept a single tile name or a list of names to randomly pick from.

### Methods
- **fill_rect(rect, tile)** - Fills a rectangular area with the specified tile(s).
- **line(tile, start, end)** - Draws a line of tiles between two coordinates.
- **flood_fill(coord, tile)** - Performs a flood fill operation starting from the given coordinate.
```

--------------------------------

### Apply Mask Effect via Chain

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/effects.rst.txt

Demonstrates using a specific layer as a mask for other layers within the scene chain.

```python
scene.chain = [
    w2d.chain.Mask(
        w2d.chain.Layers([1]),
        w2d.chain.LayerRange(stop=0),
    )
]
```

--------------------------------

### Group.from_objects(objects)

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Creates a group from a list of objects already in the scene, keeping them in their current world positions.

```APIDOC
## Group.from_objects(objects)

### Description
Builds a group by moving in objects already in the scene while maintaining their world positions.
```

--------------------------------

### Extending a Group

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/groups.rst.txt

Add multiple items to an existing group using local coordinate positioning.

```python
# Add additional items to the group
group.extend([
    scene.layers[0].add_sprite('mega_gun', pos=(-5, -10)),
    scene.layers[0].add_sprite('mega_gun', pos=(-5, 10)),
])
```

--------------------------------

### Add a color gradient to a particle group

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/particles.rst.txt

Define color transitions over the lifetime of particles by adding multiple color stops to a particle group.

```python
group.add_color_stop(0, (1, 0, 0, 1))
group.add_color_stop(2, (1, 0, 0, 0))
```

--------------------------------

### clear()

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/storage.rst.txt

Removes all stored values.

```APIDOC
## clear()

### Description
Remove all stored values from the storage.
```

--------------------------------

### Querying Keyboard State

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/events.rst.txt

Access the wasabi2d.keyboard object to check if specific keys are currently held down.

```python
keyboard.a  # The 'A' key
keyboard.left  # The left arrow key
keyboard.rshift  # The right shift key
keyboard.kp0  # The '0' key on the keypad
keyboard.k_0  # The main '0' key
```

--------------------------------

### TileMap Operations

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/tile_maps.rst.txt

Methods for manipulating tiles within a TileMap instance.

```APIDOC
## TileMap Operations

### Description
Standard dictionary-like operations to get, set, or delete tiles at specific coordinates.

### Methods
- **__setitem__(coord, value)** - Sets the tile image name at the specified coordinate.
- **__getitem__(coord)** - Retrieves the tile image name at the specified coordinate.
- **get(coord, default=None)** - Returns the tile image name at the coordinate or a default value.
- **setdefault(coord, default)** - Sets the tile at the coordinate if it is not already set.
- **__delitem__(coord)** - Removes the tile at the specified coordinate.
- **clear()** - Removes all tiles from the map.
```

--------------------------------

### Schedule a function call

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/clock.rst.txt

Use the clock to trigger a function after a specified delay in seconds.

```python
def on_mouse_down():
    clock.schedule(fire_laser, 1.0)
```

--------------------------------

### Group.capture

Source: https://wasabi2d.readthedocs.io/en/stable/groups.html

Captures objects into the group while preserving their existing world transformations.

```APIDOC
## Group.capture(*objects: Tuple[wasabi2d.primitives.base.Transformable])

### Description
Capture the given objects into the group, maintaining their world transformation.

### Parameters
- **objects** (Tuple[wasabi2d.primitives.base.Transformable]) - Required - The objects to capture.
```

--------------------------------

### Scene.stop_recording()

Source: https://wasabi2d.readthedocs.io/en/stable/scene.html

Stops the current video recording.

```APIDOC
## Scene.stop_recording()

### Description
Finish recording the current video.
```

--------------------------------

### Layer.add_polygon(vertices, *, [options])

Source: https://wasabi2d.readthedocs.io/en/stable/_sources/primitives.rst.txt

Creates and returns a closed polygon shape on the layer.

```APIDOC
## Layer.add_polygon(vertices, *, [options])

### Description
Creates and returns a closed polygon. The vertices are provided as a sequence of (float, float) tuples and cannot be updated after creation.

### Parameters
- **vertices** (sequence of (float, float)) - Required - The coordinates of the polygon vertices.
- **fill** (bool) - Optional - If True, the shape is drawn filled; otherwise, it is drawn as an outline.
- **stroke_width** (int) - Optional - The width of the line if fill is False.
```
Tokens:
Raw