---
title: "draw2d"
type: docs
---

# draw2d

A collection of retained-mode 2D drawing factories. Each factory creates an object that auto-registers with `film2d` and renders via the compositor. Destroy objects when no longer needed.

```javascript
var draw = use('draw2d')
```

## Factories

### draw.sprite(props)

Create a sprite from an image. Auto-registers with `film2d`.

```javascript
var s = draw.sprite({
  image: "hero.png",
  pos: {x: 100, y: 200},
  width: 32, height: 32,
  plane: 'game', layer: 0
})
s.destroy()  // remove from renderer
```

See `sprite.cm` for full property list: `pos`, `image`, `width`, `height`, `anchor_x`, `anchor_y`, `rotation`, `color`, `opacity`, `tint`, `filter`, `plane`, `layer`, `groups`, `visible`, `flip`, `fit`, `uv`.

### draw.shape.rect(props) / circle(props) / ellipse(props) / pill(props)

Create SDF shapes. Supports fill, stroke, rounded corners, dashing, feathering, and texture fill.

```javascript
var box = draw.shape.rect({
  pos: {x: 50, y: 50}, width: 100, height: 60,
  fill: {r: 1, g: 0, b: 0, a: 1},
  stroke: {r: 1, g: 1, b: 1, a: 1}, stroke_thickness: 2,
  radius: 8,
  plane: 'game'
})

var ball = draw.shape.circle({
  pos: {x: 200, y: 200}, radius: 16,
  fill: {r: 0, g: 1, b: 0, a: 1},
  plane: 'game', groups: ['glow']
})
```

Properties: `shape_type`, `pos`, `width`, `height`, `radius`, `corner_style`, `feather`, `stroke_thickness`, `stroke_align`, `dash_len`, `gap_len`, `dash_offset`, `cap`, `join`, `fill`, `stroke`, `blend`, `opacity`, `fill_tex`, `uv`, `plane`, `layer`, `groups`, `visible`.

### draw.text(props)

Create a text label. Updates live when you change `.text`.

```javascript
var label = draw.text({
  text: "Score: 0",
  pos: {x: 10, y: 500},
  font: "fonts/dos", size: 16,
  color: {r: 1, g: 1, b: 1, a: 1},
  plane: 'hud'
})
label.text = "Score: 42"  // updates on next frame
```

### draw.tilemap(props)

Create a tile-based map. See `tilemap2d.cm`.

### draw.anim(props)

Create an animated sprite from an aseprite/gif file. Auto-plays if the image has frames.

```javascript
var anim = draw.anim({
  image: "hero.aseprite",
  pos: {x: 100, y: 100},
  plane: 'game'
})
anim.play("walk")   // play named animation
anim.stop()         // pause
anim.resume()       // resume
anim.update(dt)     // advance frame (call from update loop)
```

## Lifecycle

All draw2d objects register with `film2d` on creation. Call `.destroy()` to unregister and remove from rendering. Set `.visible = false` to hide without destroying.

## Planes and Groups

Every drawable has a `plane` (string) and optional `groups` (array of strings). The compositor renders drawables per-plane. Groups route drawables through effects (bloom, mask, etc.).