---
name: draw
description: Draw on collaborative pixel canvas rooms. Supports shapes, freehand strokes, layers, and per-pixel drawing.
---

# Drawing on Collaborative Canvases

Base URL: `https://dice.fyi`

## Quick Start

```bash
# 1. Get room info + layers
curl -s 'https://dice.fyi/api/rooms/settings?slug=SLUG'
curl -s 'https://dice.fyi/api/layers?slug=SLUG'

# 2. Create a layer for your drawing
curl -s -X POST 'https://dice.fyi/api/layers?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"Background"}'
# Response: {"id":2,"slug":"SLUG","name":"Background",...}

# 3. Draw on it
curl -s -X POST 'https://dice.fyi/api/draw?slug=SLUG&layer_id=2&key=MOD_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type":"rect","x":10,"y":10,"w":50,"h":30,"color":"#FF0000","fill":true}'
# Response: {"status":"ok"}

# 4. Verify by downloading the PNG
curl -s -o /tmp/canvas.png 'https://dice.fyi/SLUG/png?scale=1'
```

## Authentication

All rooms have moderation. Without a mod API key, draws go to a **pending queue**:
```json
{"status":"pending"}
```

With a mod key, draws apply immediately:
```json
{"status":"ok"}
```

**Always append `&key=MOD_KEY` to draw/pixel/clear/layer endpoints.** The key is provided in the prompt when available. If not, ask the user for it — they can generate one from the AI draw button in the toolbar.

## Using Multiple Layers

**Use separate layers for different parts of your drawing.** This lets the user rearrange, hide, or delete parts independently. For example, drawing a character:

```
Layer "Background" — sky, ground, scenery
Layer "Body"       — torso, limbs
Layer "Details"    — face, accessories, outlines
```

Create each layer, draw on it, then move to the next. Layers stack bottom-to-top (lowest z_order = bottom).

```bash
# Create layers for each component
curl -s -X POST 'https://dice.fyi/api/layers?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"Background"}'
# Returns {"id":2,...} — use this id as layer_id

curl -s -X POST 'https://dice.fyi/api/layers?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"Body"}'
# Returns {"id":3,...}

curl -s -X POST 'https://dice.fyi/api/layers?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"Details"}'
# Returns {"id":4,...}

# Draw background shapes on layer 2
curl -s -X POST 'https://dice.fyi/api/draw?slug=SLUG&layer_id=2&key=MOD_KEY' ...

# Draw body shapes on layer 3
curl -s -X POST 'https://dice.fyi/api/draw?slug=SLUG&layer_id=3&key=MOD_KEY' ...

# Draw detail shapes on layer 4
curl -s -X POST 'https://dice.fyi/api/draw?slug=SLUG&layer_id=4&key=MOD_KEY' ...
```

## Drawing Shapes

`POST https://dice.fyi/api/draw?slug=SLUG&layer_id=N&key=MOD_KEY`  
Content-Type: `application/json`

**IMPORTANT — use the exact field names shown below. The API will silently ignore unknown fields.**

### Rectangle
Fields: `type`, `x`, `y`, `w`, `h`, `color`, `fill`
```json
{"type":"rect", "x":10, "y":10, "w":50, "h":30, "color":"#FF0000", "fill":true}
```
- `x`,`y` = top-left corner. `w`,`h` = width, height. `fill`: true=solid, false=outline.

### Circle
Fields: `type`, `cx`, `cy`, `r`, `color`, `fill`
```json
{"type":"circle", "cx":100, "cy":80, "r":25, "color":"#00FF00", "fill":true}
```
- `cx`,`cy` = center. `r` = radius. **NOT x/y/radius — must use cx/cy/r.**

### Line
Fields: `type`, `x1`, `y1`, `x2`, `y2`, `color`, `stroke_width`
```json
{"type":"line", "x1":0, "y1":0, "x2":100, "y2":50, "color":"#0000FF", "stroke_width":2}
```
- `x1`,`y1` = start. `x2`,`y2` = end. `stroke_width` = thickness (default 1).

### Freehand Stroke
Fields: `type`, `points`, `color`, `brush_size`, `erase`
```json
{"type":"freehand", "points":[[10,10],[12,11],[15,13],[20,18]], "color":"#000000", "brush_size":2}
```
- `points` = array of `[x,y]` pairs. Server draws Bresenham lines between consecutive points.
- `brush_size` = square brush width (default 1).
- `erase` = true to erase pixels on non-Main layers (optional).

### Flood Fill
Fields: `type`, `x`, `y`, `color`
```json
{"type":"fill", "x":50, "y":50, "color":"#FF0000"}
```
- `x`,`y` = seed point. Fills all connected pixels of the same color.

### Field Reference

| type | required fields | optional |
|------|----------------|----------|
| `rect` | `x`, `y`, `w`, `h`, `color` | `fill` (default false) |
| `circle` | `cx`, `cy`, `r`, `color` | `fill` (default false) |
| `line` | `x1`, `y1`, `x2`, `y2`, `color` | `stroke_width` (default 1) |
| `freehand` | `points`, `color` | `brush_size` (default 1), `erase` |
| `fill` | `x`, `y`, `color` | — |

## Setting Individual Pixels

`POST https://dice.fyi/api/pixels?slug=SLUG&layer_id=N&key=MOD_KEY`

```json
[{"x":0,"y":0,"r":255,"g":0,"b":0},{"x":1,"y":0,"r":0,"g":255,"b":0}]
```

Erase on non-Main layers: add `&erase=1`.

## Viewing the Canvas

```bash
# Composited PNG (all visible layers), default 4x scale
curl -s -o /tmp/canvas.png 'https://dice.fyi/SLUG/png'

# Native resolution (1:1)
curl -s -o /tmp/canvas.png 'https://dice.fyi/SLUG/png?scale=1'

# Single layer PNG
curl -s -o /tmp/layer.png 'https://dice.fyi/api/layers/1/png?slug=SLUG&scale=1'
```

Always download and view the PNG after drawing to verify.

## Layer Management

Layer IDs are per-room starting at 0 (Main). Additional layers: 1, 2, 3...

```bash
# List layers
curl -s 'https://dice.fyi/api/layers?slug=SLUG'

# Create layer
curl -s -X POST 'https://dice.fyi/api/layers?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"My Layer"}'

# Delete / rename / toggle visibility
curl -s -X DELETE 'https://dice.fyi/api/layers/2?slug=SLUG&key=MOD_KEY'
curl -s -X PATCH 'https://dice.fyi/api/layers/2?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"New Name","visible":false}'

# Reorder (z_order ascending)
curl -s -X POST 'https://dice.fyi/api/layers/reorder?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"order":[0,2,1]}'

# Merge layer down
curl -s -X POST 'https://dice.fyi/api/layers/2/merge?slug=SLUG&key=MOD_KEY'
```

## Clear Canvas

```bash
curl -s -X POST 'https://dice.fyi/api/clear?slug=SLUG&key=MOD_KEY'
curl -s -X POST 'https://dice.fyi/api/clear?slug=SLUG&key=MOD_KEY' \
  -H 'Content-Type: application/json' -d '{"color":"#000000"}'
```

## Canvas Details

- **Coordinates**: (0,0) = top-left, (width-1, height-1) = bottom-right
- **Colors**: hex `#RRGGBB` for shapes, `{r,g,b}` 0-255 for pixels
- **Layers**: Main (id=0, RGB, bottom) + transparent RGBA layers on top. Max 16 per room.
- **Dimensions**: configurable per room (16-512 per side). Canvas size is provided in the prompt.

## Tips

- **Write a script** to send all your draws in a loop rather than one curl at a time. Use any language (Python, bash, etc.).
- **Check status**: every draw response should be `{"status":"ok"}`. If you get `"pending"`, you need a mod API key.
- **Verify visually**: always download the PNG after drawing to confirm the result.
- **Use layers**: separate parts into layers so they can be edited independently.