# Games (pyzed.game)

> API reference for pyzed.game: held keys, movement, collisions, pixel sprites, particles and screen shake for real-time games on a pz.canvas.

Source: https://albakore.github.io/pyzed/reference/game/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

`pyzed.game` holds small helpers for real-time games: held keys, movement, collisions, pixel
sprites, particles and screen shake. They are plain Python built on [`pyzed.draw`](https://albakore.github.io/pyzed/reference/draw/),
so they also work in screenshots and tests. See [Making games](https://albakore.github.io/pyzed/games/) for complete examples.

```python
from pyzed import draw, game

def tick(self, dt):                      # pz.frames(self.tick) in subscriptions()
    self.x += game.axis(("left", "a"), ("right", "d")) * 300 * dt
    self.sparks.update(dt)

def view(self):
    return pz.canvas([draw.background("#0b0e14"), *game.glow(self.x, 200, 18, "#74ade8"),
                      *self.sparks.shapes()], width=400, height=300)
```

## Keys

### `pressed`

```python
pressed()
```

The keys held down right now, as a `frozenset` of names without modifiers (`"left"`, `"space"`, `"a"`…). Also available as `pz.pressed()`.

### `is_pressed`

```python
is_pressed(*keys, held=None)
```

Whether any of `keys` is held down (`held` replaces `pressed()`, for tests). Also available as `pz.is_pressed()`.

### `axis`

```python
axis(negative, positive, *, held=None)
```

`-1`, `0` or `1` from two groups of keys: `axis(("left", "a"), ("right", "d"))`.

### `vector`

```python
vector(
    left=('left', 'a'),
    right=('right', 'd'),
    up=('up', 'w'),
    down=('down', 's'),
    *,
    held=None,
)
```

A direction `(x, y)` of length 0 or 1 from four groups of keys (arrows and WASD by default); diagonals are normalized.

## Math

### `clamp`

```python
clamp(value, low, high)
```

`value` limited to `[low, high]`.

### `lerp`

```python
lerp(a, b, t)
```

The value `t` of the way from `a` to `b` (`t` from 0 to 1).

## Collisions

### `Rect`

```python
@dataclass
class Rect(x, y, w, h)
```

An axis-aligned box (`x`, `y` is the top-left corner) with `left`, `right`, `top`, `bottom`, `center`, `overlaps(other)`, `contains(x, y)`, `moved(dx, dy)` and `shape(**paint)` (a `draw.rect`).

### `circle_rect`

```python
circle_rect(cx, cy, r, rect)
```

Where a circle hits a `Rect`: the push-out direction `(nx, ny)`, or `None`. A ball bounces with `if nx: vx = abs(vx) * nx` and `if ny: vy = abs(vy) * ny`.

## Drawing

### `rgba`

```python
rgba(color, alpha=1.0)
```

`color` (`"#rrggbb[aa]"` or a tuple) as an `(r, g, b, a)` tuple with `alpha` applied.

### `glow`

```python
glow(x, y, radius, color, *, layers=4, strength=0.5, core=True)
```

A soft light: translucent circles growing around `(x, y)` (bloom on a canvas). `strength` is the opacity of the innermost halo; `core=False` leaves out the solid circle.

### `sprite`

```python
sprite(rows, palette, x=0.0, y=0.0, *, scale=1.0, flip=False)
```

Pixel art from text: each character of `rows` is a pixel colored by `palette` (missing characters are transparent). One shape per color, so a sprite stays cheap whatever its size.

## Effects

### `Particles`

```python
class Particles
```

Sparks, smoke, explosions: short-lived dots that move, fall and fade out. Call `burst(x, y, …)` when something happens, `update(dt)` every frame and draw `shapes()`; `gravity`, `drag` and `limit` tune them.

### `Shake`

```python
class Shake
```

Screen shake: `kick(8)` on a hit, `update(dt)` every frame, and start the canvas shapes with `*shake.shapes()` (a translate) so everything moves together.