Owlbear Rodeo

https://docs.owlbear.rodeo
Admin
Owlbear Rodeo is a web-based virtual tabletop (VTT) designed for intuitive battle-map experiences...
Tokens:79,832
Snippets:1,180
Trust Score:8.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Run Vite Project

Source: https://docs.owlbear.rodeo/extensions/tutorial-hello-world/create-your-site

Navigate into your new project directory, install dependencies, and start the development server.

```bash
$ cd hello-world  
$ npm install  
$ npm run dev  

```

--------------------------------

### Run Project with npm

Source: https://docs.owlbear.rodeo/extensions/tutorial-custom-tool/setup

Install project dependencies and start the development server using npm commands. This prepares the project for installation and testing within Owlbear Rodeo.

```bash
$ npm install
$ npm run dev
```

--------------------------------

### Create a Custom Pointer Tool with Interaction

Source: https://docs.owlbear.rodeo/extensions/apis/interaction

This example demonstrates how to create a custom tool mode that utilizes interactions for real-time updates. It starts an interaction on drag, updates the item's position during the drag, and stops the interaction on drag end or cancel. Ensure the `buildPointer` function is defined elsewhere.

```javascript
/**
 * Create a pointer tool mode that starts an interaction on drag start,
 * updates that interaction on drag move and stops the interaction
 * on drag end/cancel.
 */
let interaction = null;
OBR.tool.createMode({
  id: "com.example.pointer",
  icons: [
    {
      icon: "/icon.svg",
      label: "Custom Pointer",
      filter: {
        activeTools: ["rodeo.owlbear.tools/pointer"],
      },
    },
  ],
  async onToolDragStart(_, event) {
    const pointer = buildPointer().position(event.pointerPosition).build();
    interaction = await OBR.interaction.startItemInteraction(pointer);
  },
  onToolDragMove(_, event) {
    if (interaction) {
      const [update] = interaction;
      update((pointer) => {
        pointer.position = event.pointerPosition;
      });
    }
  },
  onToolDragEnd() {
    if (interaction) {
      const [_, stop] = interaction;
      stop();
    }
    interaction = null;
  },
  onToolDragCancel() {
    if (interaction) {
      const [_, stop] = interaction;
      stop();
    }
    interaction = null;
  },
});
```

--------------------------------

### Install Owlbear Rodeo SDK

Source: https://docs.owlbear.rodeo/extensions/tutorial-hello-world/install-the-sdk

Install the SDK in your project's root directory using npm. This command adds the SDK as a dependency.

```bash
$ npm install @owlbear-rodeo/sdk  

```

--------------------------------

### Metadata Structure Example

Source: https://docs.owlbear.rodeo/extensions/reference/metadata

Example of how to structure metadata keys using a reverse domain name notation to prevent collisions. This convention is used in tutorial and example projects.

```json
{
  "com.tutorial.initiative-tracker/metadata": {
    initiative: number,
  },
};
```

--------------------------------

### Example: Animate to Selection Bounds

Source: https://docs.owlbear.rodeo/extensions/apis/viewport

An example demonstrating how to use `animateToBounds` within a context menu item to zoom the viewport to the bounds of the current selection.

```javascript
OBR.contextMenu.create({
  id: "rodeo.owlbear.example",
  icons: [
    {
      icon: "icon.svg",
      label: "Example",
    },
  ],
  async onClick(context) {
    OBR.viewport.animateToBounds(context.selectionBounds);
  },
});

```

--------------------------------

### Example: Update Stroke Color Metadata

Source: https://docs.owlbear.rodeo/extensions/apis/tool

Demonstrates how to update a specific metadata property, like 'strokeColor', for a custom tool. This example assumes a tool with ID 'com.example.drawing'.

```typescript
async function handleChange(value: string) {
  await OBR.tool.setMetadata("com.example.drawing", {
    strokeColor: value,
  });
}
```

--------------------------------

### Full Context Menu Setup

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/implement-the-context-menu-item

The complete `contextMenu.js` file, including imports, ID definition, and the `setupContextMenu` function which creates the context menu with add/remove initiative functionality.

```javascript
import OBR from "@owlbear-rodeo/sdk";

const ID = "com.tutorial.initiative-tracker";

export function setupContextMenu() {
  OBR.contextMenu.create({
    id: `${ID}/context-menu`,
    icons: [
      {
        icon: "/add.svg",
        label: "Add to Initiative",
        filter: {
          every: [
            { key: "layer", value: "CHARACTER" },
            { key: ["metadata", `${ID}/metadata`], value: undefined },
          ],
        },
      },
      {
        icon: "/remove.svg",
        label: "Remove from Initiative",
        filter: {
          every: [{ key: "layer", value: "CHARACTER" }],
        },
      },
    ],
    onClick(context) {
      const addToInitiative = context.items.every(
        (item) => item.metadata[`${ID}/metadata`] === undefined
      );
      if (addToInitiative) {
        const initiative = window.prompt("Enter the initiative value");
        OBR.scene.items.updateItems(context.items, (items) => {
          for (let item of items) {
            item.metadata[`${ID}/metadata`] = {
              initiative,
            };
          }
        });
      } else {
        OBR.scene.items.updateItems(context.items, (items) => {
          for (let item of items) {
            delete item.metadata[`${ID}/metadata`];
          }
        });
      }
    },
  });
}
```

--------------------------------

### ImageUploadBuilder Constructor

Source: https://docs.owlbear.rodeo/extensions/reference/builders/image-upload

Initializes a new ImageUploadBuilder with a given file. This is the starting point for configuring an image upload.

```APIDOC
## constructor

### Description
Create an image upload builder for the given file.

### Parameters
#### Path Parameters
- **file** (File | Blob) - Required - The image file to upload.
```

--------------------------------

### Build and Add an Image Item

Source: https://docs.owlbear.rodeo/extensions/reference/builders/image

This example demonstrates how to create an Image item using the `buildImage` constructor and add it to the scene. It includes setting basic image properties and adding plain text to the image.

```typescript
import OBR, { buildImage } from "@owlbear-rodeo/sdk";  
  
const item = buildImage(  
  {  
    height: 300,  
    width: 300,  
    url: "https://www.example.com/test.png",  
    mime: "image/png",  
  },  
  { dpi: 300, offset: { x: 150, y: 150 } }  
)  
  .plainText("Player 1")  
  .build();  
OBR.scene.items.addItems([item]);  

```

--------------------------------

### Translation Matrix Example

Source: https://docs.owlbear.rodeo/extensions/reference/matrix

Illustrates a translation matrix shifted by x and y coordinates.

```plaintext
[ 
  1, 0, x, 
  0, 1, y, 
  0, 0, 1 
]
```

--------------------------------

### Initialize Context Menu in Main (main.js)

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/create-a-context-menu-item

Initializes the context menu setup after the Owlbear Rodeo SDK is ready. This ensures the context menu item is available when the application loads.

```javascript
import "./style.css";
import OBR from "@owlbear-rodeo/sdk";
import { setupContextMenu } from "./contextMenu";

document.querySelector("#app").innerHTML = `
  <div>
    <h1>Initiative Tracker</h1>
  </div>
`;

OBR.onReady(() => {
  setupContextMenu();
});
```

--------------------------------

### getType

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current grid type.

```APIDOC
## getType

### Description
Get the current grid type.

### Returns
- GridType: The current grid type.
```

--------------------------------

### Setup Context Menu Item (contextMenu.js)

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/create-a-context-menu-item

Creates a context menu item with an icon, label, and filter. The item only appears when a character layer is selected. Ensure the ID is unique to your extension.

```javascript
import OBR from "@owlbear-rodeo/sdk";

const ID = "com.tutorial.initiative-tracker";

export function setupContextMenu() {
  OBR.contextMenu.create({
    id: `${ID}/context-menu`,
    icons: [
      {
        icon: "/add.svg",
        label: "Add to Initiative",
        filter: {
          every: [{ key: "layer", value: "CHARACTER" }],
        },
      },
    ],
    onClick() {},
  });
}
```

--------------------------------

### Integrate Initiative List in Main Application

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/showing-the-initiative

Imports and initializes the initiative list functionality within the main application setup. This ensures the initiative tracker is active when the application is ready.

```javascript
import "./style.css";  
import OBR from "@owlbear-rodeo/sdk";  
import { setupContextMenu } from "./contextMenu";  
import { setupInitiativeList } from "./initiativeList";  
  
document.querySelector("#app").innerHTML = `  
  <div>  
    <h1>Initiative Tracker</h1>  
    <ul id="initiative-list"></ul>  
  </div>  
`;  
  
OBR.onReady(() => {  
  setupContextMenu();  
  setupInitiativeList(document.querySelector("#initiative-list"));  
});  
```

--------------------------------

### KeyFilter Examples

Source: https://docs.owlbear.rodeo/extensions/reference/filters

Demonstrates the usage of KeyFilter for checking specific key-value pairs on objects. Different operators and coordinators can be used to define complex filtering logic.

```javascript
// The visible property must be `true`
const a = [{ key: "visible", value: true }];
```

```javascript
// The visible property must be `true` and the type must not equal `DRAWING`
const b = [
  { key: "visible", value: true },
  { key: "type", value: "DRAWING", operator: "!=" },
];
```

```javascript
// The visible property must be `true` or the type must not equal `DRAWING`
const c = [
  { key: "visible", value: true, coordinator: "||" },
  { key: "type", value: "DRAWING", operator: "!=" },
];
```

--------------------------------

### startItemInteraction

Source: https://docs.owlbear.rodeo/extensions/apis/interaction

Starts an interaction with one or more items in a scene, returning an InteractionManager to update and stop the interaction. Interactions expire after 30 seconds.

```APIDOC
## startItemInteraction

### Description
Starts an interaction with an item or a list of items in a scene. These items can be newly created or be references to already existing items in the scene. Interactions expire after 30 seconds.

### Method
`async startItemInteraction(items: Item | Item[])`

### Parameters
#### Path Parameters
- **items** (Item | Item[]) - Required - The item or items to interact with.

### Returns
- **InteractionManager** - An object containing `update` and `stop` functions to manage the interaction.

### Example
```javascript
/**
 * Create a pointer tool mode that starts an interaction on drag start,
 * updates that interaction on drag move and stops the interaction
 * on drag end/cancel.
 */
let interaction = null;
OBR.tool.createMode({
  id: "com.example.pointer",
  icons: [
    {
      icon: "/icon.svg",
      label: "Custom Pointer",
      filter: {
        activeTools: ["rodeo.owlbear.tools/pointer"],
      },
    },
  ],
  async onToolDragStart(_, event) {
    const pointer = buildPointer().position(event.pointerPosition).build();
    interaction = await OBR.interaction.startItemInteraction(pointer);
  },
  onToolDragMove(_, event) {
    if (interaction) {
      const [update] = interaction;
      update((pointer) => {
        pointer.position = event.pointerPosition;
      });
    }
  },
  onToolDragEnd() {
    if (interaction) {
      const [_, stop] = interaction;
      stop();
    }
    interaction = null;
  },
  onToolDragCancel() {
    if (interaction) {
      const [_, stop] = interaction;
      stop();
    }
    interaction = null;
  },
});
```
```

--------------------------------

### Setup Initiative List Listener

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/showing-the-initiative

Initializes a listener for scene item changes to update the initiative list. This function takes an HTMLUListElement as input and registers a callback to render the list whenever items in the scene change.

```javascript
import OBR from "@owlbear-rodeo/sdk";  
  
const ID = "com.tutorial.initiative-tracker";  
  
export function setupInitiativeList(element) {
  const renderList = (items) => {  
    //  
  };
  OBR.scene.items.onChange(renderList);
}
```

--------------------------------

### Plain Text Content Example

Source: https://docs.owlbear.rodeo/extensions/reference/text-content

Represents a single paragraph with plain text. This is used when the 'PLAIN' type is set for faster rendering.

```json
[
  {
    "type": "paragraph",
    "children": [{ "text": "Owlbear Rodeo" }]
  }
]
```

--------------------------------

### Invert Red and Blue Channels with Post Process Effect

Source: https://docs.owlbear.rodeo/extensions/reference/effects

This example demonstrates how to create an effect that inverts the red and blue channels of the scene. It requires the `@owlbear-rodeo/sdk` and uses SKSL for shader programming. Ensure you replace the placeholder `attachedToId` with the actual item ID.

```typescript
import OBR, { buildEffect } from "@owlbear-rodeo/sdk";  
  
const sksl = `  
uniform shader scene;  
uniform mat3 modelView;  
  
half4 main(float2 coord) {  
  vec2 uv = (vec3(coord, 1) * modelView).xy;  
  return scene.eval(uv).bgra;  
}  
`;  
  
// Replace this with the item ID you would like to attach to  
const attachedToId = "123";  
  
const effect = buildEffect()  
  .effectType("ATTACHMENT")  
  .sksl(sksl)  
  .locked(true)  
  .disableHit(true)  
  .layer("POST_PROCESS")  
  .attachedTo(attachedToId)  
  .build();  
  
OBR.scene.local.addItems([effect]);  


```

--------------------------------

### Configuring Publish Directory in Render Settings

Source: https://docs.owlbear.rodeo/extensions/tutorial-sharing-your-extension/hosting-your-extension

If your deployment fails due to an incorrect output directory, update the 'Publish Directory' value in the Render Settings. This example shows changing it to './dist'.

```shell
./dist
```

--------------------------------

### Get all images

Source: https://docs.owlbear.rodeo/extensions/apis/scene/items

Fetches all items in the scene that are identified as images. Requires importing the `isImage` helper.

```javascript
import { isImage } from "@owlbear-rodeo/sdk";

const images = await OBR.scene.items.getItems(isImage);
```

--------------------------------

### Create Vite Project

Source: https://docs.owlbear.rodeo/extensions/tutorial-hello-world/create-your-site

Use this command to initiate a new Vite project. Follow the prompts to select your framework and variant.

```bash
$ npm create vite@latest  

```

```bash
✔ Project name: … hello-world  
✔ Select a framework: › Vanilla  
✔ Select a variant: › JavaScript  

```

--------------------------------

### Open a Custom Modal

Source: https://docs.owlbear.rodeo/extensions/apis/modal

Use this snippet to open a new modal. It requires a modal object with an ID, URL, and optional dimensions. This example demonstrates opening a modal when a context menu item is clicked.

```javascript
OBR.contextMenu.create({
  id: "rodeo.owlbear.example",
  icons: [
    {
      icon: "icon.svg",
      label: "Example",
    },
  ],
  onClick() {
    OBR.modal.open({
      id: "rodeo.owlbear.example/modal",
      url: "/modal",
      height: 300,
      width: 400,
    });
  },
});
```

--------------------------------

### Find World Position of Line Start

Source: https://docs.owlbear.rodeo/extensions/reference/math/math-m

Determines the absolute position of a line's starting point in world coordinates. This involves converting the line's transform and its start position into world space.

```javascript
const line = buildLine().build();  
  
const lineTransform = MathM.fromItem(line);  
const startTransform = MathM.fromPosition(line.startPosition);  
  
const worldTransform = MathM.multiply(lineTransform, startTransform);  
  
const worldPosition = MathM.decompose(worldTransform).position;  
```

--------------------------------

### Set Line Start Position

Source: https://docs.owlbear.rodeo/extensions/reference/builders/line

Specify the starting coordinates of the line using a `Vector2` object.

```typescript
startPosition(startPosition);
```

--------------------------------

### Initialize SDK with onReady Callback

Source: https://docs.owlbear.rodeo/extensions/apis

The `onReady` method accepts a callback function that executes once the SDK is initialized. It returns a function to unsubscribe from these events.

```javascript
onReady(callback);
```

--------------------------------

### Get Component-wise Absolute Value of a Vector2

Source: https://docs.owlbear.rodeo/extensions/reference/math/math-2

Use abs to get the absolute value of each component of a Vector2. This converts all negative components to positive.

```typescript
abs(a);
```

--------------------------------

### Build a Basic Label

Source: https://docs.owlbear.rodeo/extensions/reference/builders/label

Demonstrates how to create a simple label with plain text and add it to the scene. Requires importing OBR and the buildLabel function.

```typescript
import OBR, { buildLabel } from "@owlbear_rodeo/sdk";  
  
const item = buildLabel().plainText("Test").build();  
OBR.scene.local.addItems([item]);  

```

--------------------------------

### getColor

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current color of the grid.

```APIDOC
## getColor

### Description
Get the current color of the grid.

### Returns
- GridColor: The current color of the grid.
```

--------------------------------

### Create a Rich Text Item

Source: https://docs.owlbear.rodeo/extensions/reference/builders/text

Use buildText to create a new text item with rich text content. This example demonstrates setting a paragraph with specific text. The created item is then added to the scene.

```typescript
import OBR, { buildText } from "@owlbear-rodeo/sdk";  
  
const item = buildText()  
  .richText([  
    {  
      type: "paragraph",  
      children: [{ text: "Owlbear Rodeo" }],  
    },  
  ])  
  .build();  
OBR.scene.items.addItems([item]);  

```

--------------------------------

### getScale

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current scale of the grid.

```APIDOC
## getScale

### Description
Get the current scale of the grid.

### Returns
- GridScale: The current scale of the grid.
```

--------------------------------

### Render Build Command and Output Directory

Source: https://docs.owlbear.rodeo/extensions/tutorial-sharing-your-extension/hosting-your-extension

Configure the build command and output directory for your static site deployment on Render. The service name is permanent and cannot be changed after creation.

```shell
yarn build
./build
```

--------------------------------

### getMeasurement

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current grid measurement type.

```APIDOC
## getMeasurement

### Description
Get the current grid measurement type.

### Returns
- GridMeasurement: The current grid measurement type.
```

--------------------------------

### getLineType

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current grid line type.

```APIDOC
## getLineType

### Description
Get the current grid line type.

### Returns
- GridLineType: The current grid line type.
```

--------------------------------

### PathBuilder Usage

Source: https://docs.owlbear.rodeo/extensions/reference/builders/path

Demonstrates how to use the PathBuilder to create a Path item with various commands and styles.

```APIDOC
## PathBuilder
A builder for the Path item.

### Example
```javascript
import OBR, { buildPath, Command } from "@owlbear-rodeo/sdk";  
  
const item = buildPath()  
  .commands([
    [Command.MOVE, 0, 0],
    [Command.LINE, 150, 0],
    [Command.QUAD, 200, 75, 150, 150],
    [Command.CLOSE],
  ])  
  .build();  
OBR.scene.items.addItems([item]);  
```

## Methods

### `commands`

Set the paths `commands` array.

#### Parameters
* **commands** (PathCommand[]) - The paths commands

### `fillRule`

Set the paths `fillRule`.

#### Parameters
* **fillRule** (string) - The paths fill rule

### `style`

Set the paths `style`.

#### Parameters
* **style** (PathStyle[]) - The paths style

### `fillColor`

Set the path styles `fillColor`.

#### Parameters
* **fillColor** (string) - The paths fill color

### `fillOpacity`

Set the path styles `fillOpacity`.

#### Parameters
* **fillOpacity** (number) - The paths fill opacity

### `strokeColor`

Set the path styles `strokeColor`.

#### Parameters
* **strokeColor** (string) - The paths stroke color

### `strokeOpacity`

Set the path styles `strokeOpacity`.

#### Parameters
* **strokeOpacity** (number) - The paths stroke opacity

### `strokeWidth`

Set the path styles `strokeWidth`.

#### Parameters
* **strokeWidth** (number) - The paths stroke width

### `strokeDash`

Set the path styles `strokeDash`.

#### Parameters
* **strokeDash** (number[]) - The paths stroke dash

### `build`

Returns the final Path item.

```

--------------------------------

### getDistance

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the distance between two Vector2s on the Scenes grid.

```APIDOC
## getDistance

### Description
Get the distance between two Vector2s on the Scenes grid. Returns the shortest distance between the two inputs using the current GridMeasurement for the scene. When set to "EUCLIDEAN" this will be the exact distance. For all other measurement types this will be an integer of how many grid cells were traversed.

### Parameters
#### Path Parameters
- **from** (Vector2) - Required - The start position in pixels
- **to** (Vector2) - Required - The end position in pixels

### Returns
- number: The distance between the two points on the grid.
```

--------------------------------

### React to Party Changes with useEffect

Source: https://docs.owlbear.rodeo/extensions/apis/party

An example of how to use the `onChange` event with React's `useEffect` hook. The `useEffect` hook ensures that the subscription is properly managed, and the returned unsubscribe function is called when the component unmounts.

```javascript
useEffect(
  () =>
    OBR.party.onChange((party) => {
      // React to party changes
    }),
  []
);

```

--------------------------------

### getLineWidth

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current line width of the grid in pixels.

```APIDOC
## getLineWidth

### Description
Get the current line width of the grid in pixels.

### Returns
- number: The current line width of the grid.
```

--------------------------------

### isReady

Source: https://docs.owlbear.rodeo/extensions/apis/scene

Checks if a scene is opened and ready for interaction.

```APIDOC
## isReady

### Description
Returns true if there is a scene opened and it is ready to interact with.

### Method
```
async isReady()
```
```

--------------------------------

### Create a Custom Tool

Source: https://docs.owlbear.rodeo/extensions/tutorial-custom-tool/create-a-tool

Initializes a new custom tool with a unique ID and an icon. Default metadata can also be set here, which is persisted and can be used for communication between tool components.

```javascript
import OBR from "@owlbear-rodeo/sdk";  
  
const ID = "com.tutorial.custom-tool";  
  
function createTool() {  
  OBR.tool.create({
    id: `${ID}/tool`,
    icons: [
      {
        icon: "/line.svg",
        label: "Custom Tool",
      },
    ],
    defaultMetadata: {
      strokeColor: "red",
    },
  });
}

OBR.onReady(() => {
  createTool();
});
```

--------------------------------

### getOpacity

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Get the current opacity of the grid between 0 and 1.

```APIDOC
## getOpacity

### Description
Get the current opacity of the grid between 0 and 1.

### Returns
- number: The current opacity of the grid.
```

--------------------------------

### buildImage Constructor

Source: https://docs.owlbear.rodeo/extensions/reference/builders/image

Initializes a new ImageBuilder instance with the provided image content and grid settings.

```APIDOC
## buildImage(image, grid)

### Description
Creates an image builder with the given image and grid.

### Parameters
- **image** (ImageContent) - The image content.
- **grid** (ImageGrid) - The image grid settings.
```

--------------------------------

### Get Grid Type

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current type of the grid.

```javascript
async getType()
```

--------------------------------

### Get Grid Scale

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current scale of the grid.

```javascript
async getScale()
```

--------------------------------

### Get Player Name

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current name of the player.

```APIDOC
## getName

### Description
Get the name for this player.

### Method
`async getName()`

### Returns
- `string`: The name of the player.
```

--------------------------------

### LightBuilder Methods

Source: https://docs.owlbear.rodeo/extensions/reference/builders/light

This section details the methods available on the LightBuilder to configure a light item.

```APIDOC
## `sourceRadius`

### Description
Set the lights `sourceRadius`.

### Method
`sourceRadius(sourceRadius)`

### Parameters
#### Path Parameters
- **sourceRadius** (number) - Required - The lights sourceRadius value

### Returns
Returns the current builder.
```

```APIDOC
## `attenuationRadius`

### Description
Set the lights `attenuationRadius`.

### Method
`attenuationRadius(attenuationRadius)`

### Parameters
#### Path Parameters
- **attenuationRadius** (number) - Required - The lights attenuationRadius value

### Returns
Returns the current builder.
```

```APIDOC
## `falloff`

### Description
Set the lights `falloff`.

### Method
`falloff(falloff)`

### Parameters
#### Path Parameters
- **falloff** (number) - Required - The lights falloff value

### Returns
Returns the current builder.
```

```APIDOC
## `innerAngle`

### Description
Set the lights `innerAngle`.

### Method
`innerAngle(innerAngle)`

### Parameters
#### Path Parameters
- **innerAngle** (number) - Required - The lights innerAngle value

### Returns
Returns the current builder.
```

```APIDOC
## `outerAngle`

### Description
Set the lights `outerAngle`.

### Method
`outerAngle(outerAngle)`

### Parameters
#### Path Parameters
- **outerAngle** (number) - Required - The lights outerAngle value

### Returns
Returns the current builder.
```

```APIDOC
## `build`

### Description
Returns the final Light item.

### Method
`build()`

### Returns
The final Light item.
```

--------------------------------

### getItemBounds

Source: https://docs.owlbear.rodeo/extensions/apis/scene/local

Gets the axis-aligned bounding box for the specified items.

```APIDOC
## getItemBounds

### Description
Get the axis-aligned bounding box for the given items.

### Method
`async getItemBounds(ids: string[]): Promise<BoundingBox>`

### Parameters
#### Path Parameters
- **ids** (string[]) - Required - A list of items to look up by their IDs.

### Response
Returns a BoundingBox.
```

--------------------------------

### onReadyChange

Source: https://docs.owlbear.rodeo/extensions/apis/scene

Subscribes to changes in the scene's ready state.

```APIDOC
## onReadyChange

### Description
A callback for when the current scene changes its ready state. Returns a function that when called will unsubscribe from change events.

### Method
```
onReadyChange(callback)
```

### Parameters
#### Path Parameters
- **callback** ((ready: boolean) => void) - Required - A callback for when the current scene changes its ready state

### Request Example
```javascript
/**
 * Use an `onReadyChange` event with a React `useEffect`.
 * `onReadyChange` returns an unsubscribe event to make this easy.
 */
useEffect(
  () =>
    OBR.scene.onReadyChange((ready) => {
      if (ready) {
        // interact with the scene
      }
    }),
  []
);
```
```

--------------------------------

### Get Player Name

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current name of the player.

```javascript
async getName()
```

--------------------------------

### downloadScenes

Source: https://docs.owlbear.rodeo/extensions/apis/assets

Opens a scene picker for the user to share scenes with the extension. Returns an array of SceneDownloads.

```APIDOC
## downloadScenes

### Description
Opens a scene picker to allow a user to share scenes with the extension.
Returns an array of SceneDownloads.

### Method
`async downloadScenes(multiple, defaultSearch)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **multiple** (boolean) - Optional - If true, the user can pick multiple scenes.
- **defaultSearch** (string) - Optional - A default value for the search input in the scene picker.

### Request Example
- None explicitly documented.

### Response
#### Success Response (200)
- Returns an array of SceneDownloads.

#### Response Example
- None explicitly documented.
```

--------------------------------

### Get Player Metadata

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current metadata associated with the player.

```APIDOC
## getMetadata

### Description
Get the current metadata for this player.

### Method
`async getMetadata()`

### Returns
- `Metadata`: A Metadata object containing player-specific data.
```

--------------------------------

### Get Grid Measurement

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current measurement type of the grid.

```javascript
async getMeasurement()
```

--------------------------------

### Get Player Color

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current color associated with the player.

```APIDOC
## getColor

### Description
Get the color for this player.

### Method
`async getColor()`

### Returns
- `string`: The color of the player.
```

--------------------------------

### OBR.onReady

Source: https://docs.owlbear.rodeo/extensions/apis

The `onReady` method allows you to register a callback function that will be executed once the SDK has been loaded and is ready to send messages. It returns a function to unsubscribe from these events.

```APIDOC
## `onReady`

### Description
Registers a callback function to be executed when the SDK is ready. Returns a function to unsubscribe from the event.

### Method
`onReady(callback)`

### Parameters
#### Callback
- **callback** (() => void) - Required - A callback function to execute when the SDK is ready.

### Example
```javascript
useEffect(() =>
  OBR.onReady(() => {
    // interact with the SDK
  }),
  []
);
```
```

--------------------------------

### Get Player Metadata

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current metadata associated with the player.

```javascript
async getMetadata()
```

--------------------------------

### Get Popover Height

Source: https://docs.owlbear.rodeo/extensions/apis/popover

Retrieves the current height of a specified popover.

```javascript
async getHeight(id)
```

--------------------------------

### Get Player Color

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current color associated with the player.

```javascript
async getColor()
```

--------------------------------

### textPadding()

Source: https://docs.owlbear.rodeo/extensions/reference/builders/image

Sets the padding for the image text styles. Returns the current builder for chaining.

```APIDOC
## textPadding(padding)

### Description
Set the image text styles padding.

### Parameters
- **padding** (number) - The text padding.

### Returns
The current builder.
```

--------------------------------

### OBR.modal.open

Source: https://docs.owlbear.rodeo/extensions/apis/modal

Opens a new modal window with specified properties.

```APIDOC
## OBR.modal.open

### Description
Opens a new modal window.

### Method
`async open(modal)`

### Parameters
#### Path Parameters
- **modal** (Modal) - Required - The modal object to open.

### Request Example
```javascript
OBR.modal.open({
  id: "rodeo.owlbear.example/modal",
  url: "/modal",
  height: 300,
  width: 400
});
```

### Response
#### Success Response (200)
- **void** - This method does not return a value upon success.

### Type Definitions
#### Modal
- **id** (string) - Required - The unique identifier for the modal.
- **url** (string) - Required - The URL of the content to display in the modal.
- **width** (number) - Optional - The width of the modal in pixels.
- **height** (number) - Optional - The height of the modal in pixels.
- **fullScreen** (boolean) - Optional - If true, the modal will occupy the entire screen.
- **hideBackdrop** (boolean) - Optional - If true, the dark backdrop behind the modal will be hidden.
- **hidePaper** (boolean) - Optional - If true, the colored background of the modal will be removed.
- **disablePointerEvents** (boolean) - Optional - If true, the modal will not respond to mouse or touch events.
```

--------------------------------

### Get Popover Width

Source: https://docs.owlbear.rodeo/extensions/apis/popover

Retrieves the current width of a specified popover.

```javascript
async getWidth(id)
```

--------------------------------

### OBR.popover.open

Source: https://docs.owlbear.rodeo/extensions/apis/popover

Opens a new popover with the specified configuration. The popover can be anchored to an element or a specific position.

```APIDOC
## OBR.popover.open

### Description
Opens a new popover with the specified configuration. The popover can be anchored to an element or a specific position.

### Method
async open(popover: Popover)

### Parameters
#### Path Parameters
- **popover** (Popover) - Required - The popover configuration object to open.

### Request Example
```javascript
OBR.popover.open({
  id: "rodeo.owlbear.example/popover",
  url: "/popover",
  height: 80,
  width: 200,
  anchorElementId: "someElementId",
  anchorPosition: { left: 100, top: 100 },
  anchorReference: "POSITION",
  hidePaper: false,
  disableClickAway: false,
  marginThreshold: 10,
  anchorOrigin: { horizontal: "CENTER", vertical: "BOTTOM" },
  transformOrigin: { horizontal: "CENTER", vertical: "TOP" }
});
```

### Type Definitions
#### Popover
```typescript
type Popover = {
  id: string;
  url: string;
  width: number;
  height: number;
  anchorElementId?: string;
  anchorPosition?: { left: number; top: number };
  anchorOrigin?: { horizontal: "CENTER" | "LEFT" | "RIGHT"; vertical: "BOTTOM" | "CENTER" | "TOP" };
  anchorReference?: "ELEMENT" | "POSITION";
  hidePaper?: boolean;
  disableClickAway?: boolean;
  marginThreshold?: number;
  transformOrigin?: { horizontal: "CENTER" | "LEFT" | "RIGHT"; vertical: "BOTTOM" | "CENTER" | "TOP" };
};
```
```

--------------------------------

### Get Action Title

Source: https://docs.owlbear.rodeo/extensions/apis/action

Retrieves the title of the action. Returns a string.

```javascript
async getTitle()


```

--------------------------------

### Tool Metadata Management

Source: https://docs.owlbear.rodeo/extensions/apis/tool

Methods for getting and setting metadata associated with tools.

```APIDOC
## Tool Metadata Methods

### `OBR.tool.getMetadata(key: string): any`

Retrieves metadata associated with a given key.

### `OBR.tool.setMetadata(key: string, value: any): void`

Sets metadata for a given key.
```

--------------------------------

### downloadImages

Source: https://docs.owlbear.rodeo/extensions/apis/assets

Opens an image picker for the user to share images with the extension. Returns an array of ImageDownloads.

```APIDOC
## downloadImages

### Description
Opens an image picker to allow a user to share images with the extension.
Returns an array of ImageDownloads.

### Method
`async downloadImages(multiple, defaultSearch, typeHint)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **multiple** (boolean) - Optional - If true, the user can pick multiple images.
- **defaultSearch** (string) - Optional - A default value for the search input in the image picker.
- **typeHint** (ImageAssetType) - Optional - A hint for which image type to select.

### Request Example
- None explicitly documented.

### Response
#### Success Response (200)
- Returns an array of ImageDownloads.

#### Response Example
- None explicitly documented.
```

--------------------------------

### Build and Add a Light

Source: https://docs.owlbear.rodeo/extensions/reference/builders/light

Use this snippet to create a light source attached to a character, with its radius determined by the grid DPI. Ensure the OBR SDK is imported and the target item ID is available.

```typescript
import OBR, { buildLight } from "@owlbear-rodeo/sdk";  
  
const gridDpi = await OBR.scene.grid.getDpi();  
// 12 grid squares or 60ft in a 5ft grid system  
const visionRadius = gridDpi * 12;  
  
const myCharacter = await OBR.scene.items.get(id);  
const item = buildLight()  
  .position(myCharacter.position)  
  .attenuationRadius(visionRadius)  
  .attachedTo(myCharacter.id)  
  .build();  
OBR.scene.local.addItems([item]);  
```

--------------------------------

### Get Player Role

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current role of the player, which can be 'GM' or 'PLAYER'.

```APIDOC
## getRole

### Description
Get the current role for this player.

### Method
`async getRole()`

### Returns
- `"GM" | "PLAYER"`: The current role of the player.
```

--------------------------------

### Get Grid Line Type

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current line type of the grid.

```javascript
async getLineType()
```

--------------------------------

### MoveCommand

Source: https://docs.owlbear.rodeo/extensions/reference/items/path

Begins a new sub-path at the specified (x, y) coordinates.

```APIDOC
### MoveCommand

#### Description
Begins a new sub-path at the given (x, y).

#### Type
```json
["MOVE", x, y]
```

#### Parameters
- **x** (number): The x-coordinate.
- **y** (number): The y-coordinate.
```

--------------------------------

### Build a Circle Shape

Source: https://docs.owlbear.rodeo/extensions/reference/builders/shape

Demonstrates how to create a basic circle shape with specified dimensions and add it to the scene.

```typescript
import OBR, { buildShape } from "@owlbear-rodeo/sdk";  
  
const item = buildShape().width(10).height(10).shapeType("CIRCLE").build();  
OBR.scene.items.addItems([item]);  
```

--------------------------------

### Get Fog Filled State

Source: https://docs.owlbear.rodeo/extensions/apis/scene/fog

Checks if the scene is currently filled with fog.

```APIDOC
## getFilled

### Description
Returns true if the scene if filled with fog.

### Method
`async getFilled()`

### Returns
- boolean: True if the scene is filled with fog, false otherwise.
```

--------------------------------

### Vite Configuration for New Routes

Source: https://docs.owlbear.rodeo/extensions/tutorial-custom-tool/implement-the-color-picker

Configures Vite to recognize and build the 'color-picker.html' as a separate page entry point.

```javascript
import { resolve } from "path";
import { defineConfig } from "vite";

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, "index.html"),
        "color-picker": resolve(__dirname, "color-picker.html"),
      },
    },
  },
});

```

--------------------------------

### Get Fog Color

Source: https://docs.owlbear.rodeo/extensions/apis/scene/fog

Retrieves the current color of the scene's fog.

```APIDOC
## getColor

### Description
Get the color of the scenes fog.

### Method
`async getColor()`

### Returns
- string: The color of the fog.
```

--------------------------------

### Get Player Role

Source: https://docs.owlbear.rodeo/extensions/apis/player

Retrieves the current role of the player, which can be 'GM' or 'PLAYER'.

```javascript
async getRole()
```

--------------------------------

### Import Line Builder

Source: https://docs.owlbear.rodeo/extensions/tutorial-custom-tool/implement-the-line-mode

Import the necessary buildLine function from the Owlbear Rodeo SDK to create line items.

```javascript
import OBR, { buildLine } from "@owlbear-rodeo/sdk";  
```

--------------------------------

### Get Action Icon

Source: https://docs.owlbear.rodeo/extensions/apis/action

Retrieves the icon associated with the action. Returns a string.

```javascript
async getIcon()


```

--------------------------------

### Action Methods

Source: https://docs.owlbear.rodeo/extensions/apis/action

This section details the various methods available for interacting with extension actions.

```APIDOC
## `OBR.action.getWidth()`

### Description
Get the action popover's width.

### Method
`async getWidth()`

### Returns
- `number | undefined`: The current width of the popover, or undefined if not set.
```

```APIDOC
## `OBR.action.setWidth(width)`

### Description
Set the action popover's width.

### Method
`async setWidth(width: number)`

### Parameters
#### Path Parameters
- **width** (number) - Required - The new width of the popover.
```

```APIDOC
## `OBR.action.getHeight()`

### Description
Get the action popover's height.

### Method
`async getHeight()`

### Returns
- `number | undefined`: The current height of the popover, or undefined if not set.
```

```APIDOC
## `OBR.action.setHeight(height)`

### Description
Set the action popover's height.

### Method
`async setHeight(height: number)`

### Parameters
#### Path Parameters
- **height** (number) - Required - The new height of the popover.
```

```APIDOC
## `OBR.action.getBadgeText()`

### Description
Get the action's badge text.

### Method
`async getBadgeText()`

### Returns
- `string | undefined`: The current badge text, or undefined if no badge is set.
```

```APIDOC
## `OBR.action.setBadgeText(badgeText)`

### Description
Set the action's badge text.

### Method
`async setBadgeText(badgeText: string)`

### Parameters
#### Path Parameters
- **badgeText** (string) - Required - The new badge text. Set to `undefined` to remove the badge.
```

```APIDOC
## `OBR.action.getBadgeBackgroundColor()`

### Description
Get the action's badge background color.

### Method
`async getBadgeBackgroundColor()`

### Returns
- `string | undefined`: The current badge background color, or undefined if not set.
```

```APIDOC
## `OBR.action.setBadgeBackgroundColor(badgeBackgroundColor)`

### Description
Set the action's badge background color.

### Method
`async setBadgeBackgroundColor(badgeBackgroundColor: string)`

### Parameters
#### Path Parameters
- **badgeBackgroundColor** (string) - Required - The new badge background color.
```

```APIDOC
## `OBR.action.getIcon()`

### Description
Get the action's icon.

### Method
`async getIcon()`

### Returns
- `string`: The current icon identifier.
```

```APIDOC
## `OBR.action.setIcon(icon)`

### Description
Set the action's icon.

### Method
`async setIcon(icon: string)`

### Parameters
#### Path Parameters
- **icon** (string) - Required - The new icon identifier.
```

```APIDOC
## `OBR.action.getTitle()`

### Description
Get the action's title.

### Method
`async getTitle()`

### Returns
- `string`: The current title of the action.
```

```APIDOC
## `OBR.action.setTitle(title)`

### Description
Set the action's title.

### Method
`async setTitle(title: string)`

### Parameters
#### Path Parameters
- **title** (string) - Required - The new title for the action.
```

```APIDOC
## `OBR.action.open()`

### Description
Open the action popover.

### Method
`async open()`
```

```APIDOC
## `OBR.action.close()`

### Description
Close the action popover.

### Method
`async close()`
```

```APIDOC
## `OBR.action.isOpen()`

### Description
Check if the action popover is currently open.

### Method
`async isOpen()`

### Returns
- `boolean`: True if the action is open, false otherwise.
```

```APIDOC
## `OBR.action.onOpenChange(callback)`

### Description
Subscribe to changes in the action's open state.

### Method
`onOpenChange(callback: (isOpen: boolean) => void)`

### Parameters
#### Path Parameters
- **callback** ((isOpen: boolean) => void) - Required - A function that will be called when the action is opened or closed. It receives a boolean indicating the new open state.

### Returns
- `function`: A function that, when called, will unsubscribe the callback from future events.
```

--------------------------------

### Get Tool Metadata

Source: https://docs.owlbear.rodeo/extensions/apis/tool

Retrieves the metadata associated with a specific tool using its ID.

```javascript
async getMetadata(id)
```

--------------------------------

### Get Grid Line Width

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current line width of the grid in pixels.

```javascript
async getLineWidth()
```

--------------------------------

### Create Extension Manifest

Source: https://docs.owlbear.rodeo/extensions/tutorial-hello-world/create-your-manifest

Define your extension's properties and behavior using a JSON manifest file. This file is essential for Owlbear Rodeo to load and recognize your extension.

```json
{
  "name": "Hello, World!",
  "version": "1.0.0",
  "manifest_version": 1,
  "action": {
    "title": "Hello, World!",
    "icon": "/icon.svg",
    "popover": "/",
    "height": 600,
    "width": 400
  }
}

```

--------------------------------

### Get Sync View State

Source: https://docs.owlbear.rodeo/extensions/apis/player

Checks if the player currently has synchronized view enabled.

```APIDOC
## getSyncView

### Description
Get whether this player currently has sync view enabled.

### Method
`async getSyncView()`

### Returns
- `boolean`: True if sync view is enabled, false otherwise.
```

--------------------------------

### Get Grid Opacity

Source: https://docs.owlbear.rodeo/extensions/apis/scene/grid

Retrieves the current opacity of the grid, a number between 0 and 1.

```javascript
async getOpacity()
```

--------------------------------

### Get Viewport Height

Source: https://docs.owlbear.rodeo/extensions/apis/viewport

Retrieves the current height of the viewport in pixels. Returns a number.

```javascript
async getHeight()

```

--------------------------------

### Configure Context Menu Icons and Filters

Source: https://docs.owlbear.rodeo/extensions/tutorial-initiative-tracker/implement-the-context-menu-item

Defines the icons and filters for the context menu. It includes logic to show 'Add to Initiative' when no initiative is set and 'Remove from Initiative' when it is.

```javascript
icons: [
  {
    icon: "/add.svg",
    label: "Add to Initiative",
    filter: {
      every: [
        { key: "layer", value: "CHARACTER" },
        { key: ["metadata", `${ID}/metadata`], value: undefined },
      ],
    },
  },
  {
    icon: "/remove.svg",
    label: "Remove from Initiative",
    filter: {
      every: [{ key: "layer", value: "CHARACTER" }],
    },
  },
],
```

--------------------------------

### Set Scene Grid Type

Source: https://docs.owlbear.rodeo/extensions/reference/builders/scene-upload

Configures the type of the scene's grid. Returns the current builder instance.

```javascript
gridType(type);
```

--------------------------------

### Get Viewport Width

Source: https://docs.owlbear.rodeo/extensions/apis/viewport

Retrieves the current width of the viewport in pixels. Returns a number.

```javascript
async getWidth()

```

--------------------------------

### Get Sync View State

Source: https://docs.owlbear.rodeo/extensions/apis/player

Checks if the player currently has synchronized view enabled.

```javascript
async getSyncView()
```

--------------------------------

### OBR.contextMenu.create

Source: https://docs.owlbear.rodeo/extensions/apis/context-menu

Creates a new context menu item. This function takes a ContextMenuItem object as input, which defines the appearance and behavior of the menu item.

```APIDOC
## OBR.contextMenu.create

### Description
Create a context menu item.

### Method
`async create(contextMenu)`

### Parameters
#### Path Parameters
- **contextMenu** (ContextMenuItem) - Required - The context menu item to create
```

--------------------------------

### Get Fog Stroke Width

Source: https://docs.owlbear.rodeo/extensions/apis/scene/fog

Retrieves the current stroke width of the scene's fog.

```APIDOC
## getStrokeWidth

### Description
Get the stroke width of the scenes fog.

### Method
`async getStrokeWidth()`

### Returns
- number: The stroke width of the fog.
```

--------------------------------

### uploadImages

Source: https://docs.owlbear.rodeo/extensions/apis/assets

Opens a folder picker for the user to upload images. Accepts an array of ImageUpload objects and an optional type hint.

```APIDOC
## uploadImages

### Description
Opens a folder picker to allow a user to upload the given `images`.

### Method
`async uploadImages(images, typeHint)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **images** (ImageUpload[]) - Required - The images to upload.
- **typeHint** (ImageAssetType) - Optional - An optional hint for which image type to use when uploading.

### Request Example
```javascript
import OBR, { buildImageUpload } from "@owlbear-rodeo/sdk";

<input
  type="file"
  onChange={async (e) => {
    const files = e.target.files;
    if (files) {
      const uploads = [];
      for (const file of files) {
        const data = await file.arrayBuffer();
        const newFile = new File([data], file.name, { type: file.type });
        uploads.push(buildImageUpload(newFile).build());
      }
      await OBR.assets.uploadImages(uploads);
    }
  }}
/>;
```

### Response
#### Success Response (200)
- None explicitly documented.

#### Response Example
- None explicitly documented.
```

--------------------------------

### build

Source: https://docs.owlbear.rodeo/extensions/reference/builders/image

Finalizes the image builder and returns the created image item.

```APIDOC
## `build`

### Description
Returns the final Image item.

### Method
```
build();
```

### Returns
The final Image item.
```
Tokens:
Raw