> ## Documentation Index
> Fetch the complete documentation index at: https://rive.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Artboard

Represents a Rive artboard instance, providing drawing, advancing,
interaction handling, and access to named nodes and data.

## Fields

### `frameOrigin`

If true, the artboard’s origin is treated as the frame origin.

```lua highlight={6} theme={null}
function init(self: RenderInstance, context: Context): boolean
  local vm = Data.Character.new()

  self.instance = self.character:instance(vm)
  if self.instance then
    self.instance.frameOrigin = true
  end

  return true
end
```

### `data`

The typed data associated with the artboard.

```lua highlight={9,10,11,12} theme={null}
function init(self: RenderInstance, context: Context): boolean
  local vm = Data.Character.new()

  self.instance = self.character:instance(vm)

  if self.instance then
    self.instance.frameOrigin = true

    local data = self.instance.data
    if data then
      print(data.nickname)
    end
  end

  return true
end
```

### `width`

The width of the artboard.

```lua theme={null}
self.instance = self.character:instance(vm)
  if self.instance then
    print(self.instance.width)
  end
end
```

### `height`

The height of the artboard.

```lua theme={null}
self.instance = self.character:instance(vm)
  if self.instance then
    print(self.instance.height)
  end
end
```

## Methods

### `draw`

<div class="signature">
  ```lua theme={null}
  draw(renderer: Renderer) -> ()
  ```
</div>

Draws the artboard using the provided renderer.

```lua highlight={20} theme={null}
type RenderInstances = {
  character: Input<Artboard<Data.Character>>,

  instance: Artboard<Data.Character>?,
}

function init(self: RenderInstances, context: Context): boolean
  local vm = Data.Character.new()

  self.instance = self.character:instance(vm)

  return true
end

function draw(self: RenderInstances, renderer: Renderer)
  local instance = self.instance

  if instance then
    renderer:save()
    instance:draw(renderer)
    renderer:restore()
  end
end

return function(): Node<RenderInstances>
  return {
    character = late(),
    instance = nil,
    init = init,
    draw = draw,
  }
end
```

### `drawCanvas`

<div class="signature">
  ```lua theme={null}
  drawCanvas() -> ()
  ```
</div>

Use this method to call drawCanvas on instances that
are created dynamically. This must only be called during an active
canvas drawing phase, such as from within a drawCanvas callback.

### `advance`

<div class="signature">
  ```lua theme={null}
  advance(seconds: number) -> boolean
  ```
</div>

Advances the artboard by the given time in seconds. Returns true if the
artboard should continue receiving advance calls.

```lua highlight={17} theme={null}
type RenderInstances = {
  character: Input<Artboard<Data.Character>>,

  instance: Artboard<Data.Character>?,
}

function init(self: RenderInstances, context: Context): boolean
  local vm = Data.Character.new()

  self.instance = self.character:instance(vm)

  return true
end

function advance(self: RenderInstances, seconds: number): boolean
  if self.instance then
    return self.instance:advance(seconds)
  end
  return true
end

return function(): Node<RenderInstances>
  return {
    character = late(),
    instance = nil,
    init = init,
    advance = advance,
  }
end
```

### `instance`

<div class="signature">
  ```lua theme={null}
  instance(viewModel: ViewModel?) -> Artboard<T>
  ```
</div>

Creates a new instance of the artboard with independent state.

```lua highlight={8} theme={null}
type ViewModelExample = {
  character: Input<Artboard<Data.Character>>,
  instance: Artboard<Data.Character>?,
}

function init(self: ViewModelExample, context: Context): boolean
  local vm = Data.Character.new()
  self.instance = self.character:instance(vm)
  return true
end

return function(): Node<ViewModelExample>
  return {
    character = late(),
    instance = nil,
    init = init,
  }
end
```

### `animation`

<div class="signature">
  ```lua theme={null}
  animation(name: string) -> Animation?
  ```
</div>

Creates an animation instance linked to the artboard instance

### `bounds`

<div class="signature">
  ```lua theme={null}
  bounds() -> (Vector, Vector)
  ```
</div>

Returns the bounding box of the artboard as two [Vector](/scripting/api-reference/vector/vector) values: the
minimum point and the maximum point.

```lua theme={null}
local minPt, maxPt = self.instance:bounds()
print("Bounds width", maxPt.x - minPt.x)
print("Bounds height", maxPt.y - minPt.y)
```

### `node`

<div class="signature">
  ```lua theme={null}
  node(name: string) -> NodeData?
  ```
</div>

Returns the node with the given name, or nil if no such node exists.

```lua highlight={2} theme={null}
if self.instance then
  local node = self.instance:node('Root')
  if node then
    local m = Mat2D.withTranslation(100, 100)
    node:decompose(m)
  end
end
```

### `pointerDown`

<div class="signature">
  ```lua theme={null}
  pointerDown(event: PointerEvent) -> number
  ```
</div>

Pointer event down handler. Returns a hit-test result (0 = no hit).
Only returns a non-zero value if a hit-testable object inside the nested
artboard is hit.

```lua highlight={3} theme={null}
function handlePointerDown(self: PointerExample, event: PointerEvent)
  if self.instance then
    local hit = self.instance:pointerDown(event)
    if hit ~= 0 then
      print(event.id)
      print(event.position)
    end
  end
end
```

### `pointerUp`

<div class="signature">
  ```lua theme={null}
  pointerUp(event: PointerEvent) -> number
  ```
</div>

Pointer event up handler. Returns a hit-test result (0 = no hit).
Only returns a non-zero value if a hit-testable object inside the nested
artboard is hit.

```lua highlight={3} theme={null}
function handlePointerUp(self: PointerExample, event: PointerEvent)
  if self.instance then
    local hit = self.instance:pointerUp(event)
    if hit ~= 0 then
      print(event.id)
      print(event.position)
    end
  end
end
```

### `pointerMove`

<div class="signature">
  ```lua theme={null}
  pointerMove(event: PointerEvent) -> number
  ```
</div>

Pointer event move handler. Returns a hit-test result (0 = no hit).
Only returns a non-zero value if a hit-testable object inside the nested
artboard is hit.

```lua highlight={3} theme={null}
function handlePointerMove(self: PointerExample, event: PointerEvent)
  if self.instance then
    local hit = self.instance:pointerMove(event)
    if hit ~= 0 then
      print(event.id)
      print(event.position)
    end
  end
end
```

### `pointerExit`

<div class="signature">
  ```lua theme={null}
  pointerExit(event: PointerEvent) -> number
  ```
</div>

Pointer event exit handler. Returns a hit-test result (0 = no hit).
Only returns a non-zero value if a hit-testable object inside the nested
artboard is hit.

```lua highlight={3} theme={null}
function handlePointerExit(self: PointerExample, event: PointerEvent)
  if self.instance then
    local hit = self.instance:pointerExit(event)
    if hit ~= 0 then
      print(event.id)
      print(event.position)
    end
  end
end
```

### `addToPath`

<div class="signature">
  ```lua theme={null}
  addToPath(path: Path, transform: Mat2D?) -> ()
  ```
</div>

Adds the artboard’s geometry to the given path, optionally transformed
by the provided matrix.

For a complete working example, see the [Add to Path](https://rive.app/community/files/27188-51290-add-to-path-scripting-demo?utm_source=docs\&utm_medium=scripting_api\&utm_campaign=docs_to_marketplace_links) demo.

```lua highlight={18} theme={null}
function draw(self: AddToPathExample, renderer: Renderer)
  local instance = self.instance
  if not instance then
    return
  end

  -- Draw the artboard normally first.
  renderer:save()
  instance:draw(renderer)
  renderer:restore()

  -- Reset the path each frame, then rebuild it from the artboard's geometry.
  self.outlinePath:reset()

  -- Add the artboard's geometry into the path with an optional transform.
  -- Here we apply a slight offset via Mat2D to show the transform parameter.
  local transform = Mat2D.withTranslation(8, 8)
  instance:addToPath(self.outlinePath, transform)

  -- Draw the extracted path with a custom stroke paint as an outline / shadow effect.
  renderer:drawPath(self.outlinePath, self.outlinePaint)
end
```

### `gamepadConnected`

<div class="signature">
  ```lua theme={null}
  gamepadConnected(event: GamepadConnected) -> number
  ```
</div>

### `gamepadEvent`

<div class="signature">
  ```lua theme={null}
  gamepadEvent(event: GamepadEvent) -> number
  ```
</div>

### `gamepadDisconnected`

<div class="signature">
  ```lua theme={null}
  gamepadDisconnected(event: GamepadDisconnected) -> number
  ```
</div>