Quickstart

To start with, we’ll create a new Python file.

The minimal boilerplate for a wasabi2d game is this:

import wasabi2d as w2d

scene = w2d.Scene()

# The rest of your code goes here.

w2d.run()  # keep this at the end of the file

Here we create an empty scene/window, and then we start the game.

This program will pop open a black window but do nothing else. You can quit it by clicking on the X icon or by pressing Ctrl-Q.

Let’s give ourselves something to see. We’ll create a green circle in the middle of the screen. In between creating the scene and calling run(), add this code:

circle = scene.layers[0].add_circle(
    radius=30,
    pos=(scene.width / 2, scene.height / 2),
    color='green',
)

All objects in wasabi2d are created in layers. Layers are drawn from lowest to highest and are created on demand. So the choice of scene.layers[0] is arbitrary - but 0 is a good a place as any to start. Layers are added when you access them, you don’t need to create them. Scene coordinates run from (0, 0) in the top left to (width, height) in the bottom right.

When you run the game, you’ll now see a green circle in the center of the screen. We’re making progress, but this still isn’t very interesting! To start building a game we need to respond to player input. In this case, let’s make it accept mouse clicks. To do this we need to import the @event decorator and define a function to handle a click event. We’ll also use the animate function to animate an attribute over time:

from math import hypot

@w2d.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
        w2d.animate(circle, 'bounce_end', radius=30)

Quickstart with coroutines

Wasabi2D has an extensive coroutine based programming model and this is the style we recommend for most programs.

Let’s use coroutines to create a circle that follows the mouse.

Instead of defining event handlers, we can pass run() a coroutine object, and await events as we choose:

import wasabi2d as w2d
import pygame
scene = w2d.Scene()

particles = scene.layers[0].add_particle_group(
    max_age=2,
    grow=0.1,
)

async def main():
    while True:
        ev = await w2d.next_event(pygame.MOUSEBUTTONDOWN)
        particles.emit(50, pos=ev.pos, vel_spread=30, size=6, color='cyan')

w2d.run(main())

This example creates showers of particles wherever we click the mouse button.

We could instead create an emitter that tracks the mouse.

import wasabi2d as w2d
import pygame


scene = w2d.Scene()

particles = scene.layers[0].add_particle_group(
    max_age=2,
    grow=0.1,
)

async def particle_spray():
    ev = await w2d.next_event(pygame.MOUSEBUTTONDOWN)
    emitter = particles.add_emitter(
        pos=ev.pos,
        rate=50,
        color='cyan',
        size=6,
        vel_spread=30
    )
    async for ev in w2d.events.subscribe(pygame.MOUSEMOTION, pygame.MOUSEBUTTONUP):
        if ev.type == pygame.MOUSEBUTTONUP:
            emitter.delete()
            return
        else:
            emitter.pos = ev.pos

async def main():
    while True:
        await particle_spray()

w2d.run(main())