Foundry Virtual Tabletop API Documentation

https://foundryvtt.com/api
Admin
Foundry Virtual Tabletop API provides client-side interfaces for developers to extend Foundry...
Tokens:152,931
Snippets:1,048
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### DataModel Localization Setup - Foundry VTT

Source: https://foundryvtt.com/api/classes/foundry.config

Demonstrates how to define a custom DataModel class with localization support using the LOCALIZATION_PREFIXES property. Shows both the JavaScript class definition and corresponding JSON localization file structure. The example extends foundry.abstract.DataModel and uses automatic localization mapping through the i18nInit hook.

```javascript
class MyDataModel extends foundry.abstract.DataModel {  
  static defineSchema() {  
    return {  
      foo: new foundry.data.fields.StringField(),  
      bar: new foundry.data.fields.NumberField()  
    };  
  }  
  static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];  
}  
  
Hooks.on("i18nInit", () => {  
  // Foundry will attempt to automatically localize models registered for a document subtype, so this step is only  
  // needed for other data model usage, e.g. for a Setting.  
  Localization.localizeDataModel(MyDataModel);  
});
```

```json
{  
  "MYMODULE": {  
    "MYDATAMODEL": {  
      "FIELDS" : {  
        "foo": {  
          "label": "Foo",  
          "hint": "Instructions for foo"  
        },  
        "bar": {  
          "label": "Bar",  
          "hint": "Instructions for bar"  
        }  
      }  
    }  
  }  
}
```

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

### Document Creation API

Source: https://foundryvtt.com/api/classes/foundry.documents

Provides examples for creating documents, both embedded within a parent and within a compendium pack.

```APIDOC
## POST /documents/{documentType}

### Description
Creates one or more new documents. This can be done either embedded within a parent document or as standalone documents within a compendium pack.

### Method
POST

### Endpoint
/documents/{documentType}

### Parameters
#### Query Parameters
- **parent** (Document) - Optional - The parent document within which to create the new documents.
- **pack** (string) - Optional - The name of the compendium pack (e.g., "mymodule.mypack") in which to create the new documents.

#### Request Body
- **data** (Array<object>) - Required - An array of data objects, where each object defines the properties of a document to be created.

### Request Example
```json
{
  "data": [
    {"name": "Sword", "type": "weapon"},
    {"name": "Breastplate", "type": "equipment"}
  ]
}
```

### Response
#### Success Response (200)
- **createdDocuments** (Array<Document>) - An array of the newly created document instances.

#### Response Example
```json
{
  "createdDocuments": [
    // ... array of created document objects ...
  ]
}
```
```

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

### Drag Start

Source: https://foundryvtt.com/api/classes/foundry.canvas.placeables

Begins a drag operation from the perspective of a preview clone. This protected method modifies the appearance of both the clone and the original object during a drag.

```APIDOC
## Protected _onDragStart

### Description
Begin a drag operation from the perspective of the preview clone. Modify the appearance of both the clone (this) and the original (_original) object.

### Method
Protected

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (void)
Returns void.

#### Response Example
None
```

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

### Check Drag Start (Protected)

Source: https://foundryvtt.com/api/classes/foundry.appv1.api

Protected method to define whether a user is able to begin a dragstart workflow for a given selector. Returns a boolean.

```javascript
_canDragStart(selector: string): boolean
```

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

### Document Instance Configuration and Initialization (FoundryVTT API)

Source: https://foundryvtt.com/api/classes/foundry.documents

Details methods for configuring and initializing a Document instance. `_configure` allows for internal setup, `_getParentCollection` identifies the parent collection, and `_initialize` handles data copying from a source object.

```typescript
class Document {
  _configure(options?: { pack?: null; parentCollection?: null }): void;
  _getParentCollection(parentCollection?: null | string): null | string;
  _initialize(options: any): void;
}
```

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

### Canvas State and Methods Examples

Source: https://foundryvtt.com/api/classes/foundry.canvas

Illustrates how to check the readiness of the canvas, access the current scene and dimensions, and demonstrates common canvas manipulation methods.

```APIDOC
## Canvas State and Methods Examples

### Canvas State
- `canvas.ready;` // Is the canvas ready for use?
- `canvas.scene;` // The currently viewed Scene document.
- `canvas.dimensions;` // The dimensions of the current Scene.

### Canvas Methods
- `canvas.draw();` // Completely re-draw the game canvas (this is usually unnecessary).
- `canvas.pan(x, y, zoom);` // Pan the canvas to new coordinates and scale.
- `canvas.recenter();` // Re-center the canvas on the currently controlled Token.
```

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

### Handle Drag Start

Source: https://foundryvtt.com/api/classes/foundry.canvas.placeables

Handles the beginning of a drag event on a resize handle. This protected method is called when the user initiates a drag on a resizing control.

```APIDOC
## Protected _onHandleDragStart

### Description
Handle the beginning of a drag event on a resize handle.

### Method
Protected

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (void)
Returns void.

#### Response Example
None
```

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

### SidebarTour Constructor

Source: https://foundryvtt.com/api/classes/foundry.nue.tours

Constructs a new SidebarTour instance. It requires a TourConfig object and accepts optional id and namespace for further configuration. This is the primary method for initializing a guided tour.

```typescript
new SidebarTour(
  config: TourConfig,
  options?: { id?: string; namespace?: string },
): SidebarTour
```

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

### Setup event listeners with eventListeners method

Source: https://foundryvtt.com/api/classes/foundry.prosemirror

Initializes global event handlers for drop-down menu interactions. Manages user interactions with menu components across the editor interface. Returns nothing and sets up persistent listeners.

```typescript
eventListeners(): void
```

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

### Actors Collection Methods Documentation

Source: https://foundryvtt.com/api/classes/foundry.documents.collections

Structured API documentation for methods in the Foundry VTT Actors Collection class, including descriptions, parameters, returns, and examples.

```APIDOC
## Method: importFromCompendium

### Description
Import an actor from a CompendiumCollection.

### Signature
importFromCompendium(pack: CompendiumCollection<any>, id: string, updateData?: object, options?: object): Promise<documents.Actor>

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

#### Query Parameters
- None

#### Request Body
- **pack** (CompendiumCollection<any>) - Required - The CompendiumCollection instance from which to import
- **id** (string) - Required - The ID of the compendium entry to import
- **updateData** (object) - Optional - Optional additional data used to modify the imported Document before it is created
- **options** (object) - Optional - Optional arguments passed to the foundry.documents.abstract.WorldCollection#fromCompendium and foundry.abstract.Document.create methods

### Request Example
No JSON request body.

### Response
#### Success Response (Promise<documents.Actor>)
- The imported Document instance

#### Response Example
The resolved Promise value is the imported documents.Actor object.

## Method: map

### Description
Transform each element of the Collection into a new form, returning an Array of transformed values.

### Signature
map(transformer: (arg0: documents.Actor, arg1: number, arg2: Collection) => any): any[]

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

#### Query Parameters
- None

#### Request Body
- **transformer** (function) - Required - A transformation function applied to each entry value. Positional arguments are the value, the index of iteration, and the collection being mapped.

### Request Example
No JSON request body.

### Response
#### Success Response (any[])
- An Array of transformed values

#### Response Example
An array of the transformed elements.

## Method: reduce

### Description
Reduce the Collection by applying an evaluator function and accumulating entries.

### Signature
reduce(reducer: (arg0: any, arg1: documents.Actor, arg2: number, arg3: Collection) => any, initial: any): any

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

#### Query Parameters
- None

#### Request Body
- **reducer** (function) - Required - A reducer function applied to each entry value. Positional arguments are the accumulator, the value, the index of iteration, and the collection being reduced.
- **initial** (any) - Required - An initial value which accumulates with each iteration

### Request Example
No JSON request body.

### Response
#### Success Response (any)
- The accumulated result

#### Response Example
The final accumulated value.

#### Example
Reduce a collection to an array of transformed values:
```
let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
let letters = c.reduce((s, l) => {
  return s + l;
}, ""); // "ABC"
```

## Method: render

### Description
Render any Applications associated with this DocumentCollection.

### Signature
render(force?: boolean, options?: object): void

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

#### Query Parameters
- None

#### Request Body
- **force** (boolean) - Optional - Force rendering
- **options** (object) - Optional - Optional options

### Request Example
No JSON request body.

### Response
#### Success Response (void)
- No return value

#### Response Example
No response.

## Method: search

### Description
Find all Documents which match a given search term using a full-text search against their indexed HTML fields and their name. If filters are provided, results are filtered to only those that match the provided values.

### Signature
search(search: { exclude?: string[]; filters?: FieldFilter[]; query?: string }): object[] | documents.Actor[]

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

#### Query Parameters
- None

#### Request Body
- **search** (object) - Required - An object configuring the search
  - **exclude** (string[]) - Optional - An array of document IDs to exclude from search results
  - **filters** (FieldFilter[]) - Optional - An array of filters to apply
  - **query** (string) - Optional - A case-insensitive search string

### Request Example
No JSON request body.

### Response
#### Success Response (object[] | documents.Actor[])
- An array of matching documents or objects

#### Response Example
An array of documents.Actor instances or plain objects matching the search.

## Method: set

### Description
Set a document in the collection.

### Signature
set(id: any, document: any): void

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

#### Query Parameters
- None

#### Request Body
- **id** (any) - Required - The ID for the document
- **document** (any) - Required - The document to set

### Request Example
No JSON request body.

### Response
#### Success Response (void)
- No return value

#### Response Example
No response.

## Method: some

### Description
Test whether a condition is met by some entry in the Collection.

### Signature
some(condition: (arg0: documents.Actor, arg1: number, arg2: Collection) => boolean): boolean

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

#### Query Parameters
- None

#### Request Body
- **condition** (function) - Required - The functional condition to test. Positional arguments are the value, the index of iteration, and the collection being tested.

### Request Example
No JSON request body.

### Response
#### Success Response (boolean)
- Was the test condition passed by at least one entry?

#### Response Example
true or false.

## Method: toJSON

### Description
Convert the Collection to a primitive array of its contents.

### Signature
toJSON(): object[]

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

#### Query Parameters
- None

#### Request Body
- None

### Request Example
No JSON request body.

### Response
#### Success Response (object[])
- An array of contained values

#### Response Example
An array of objects representing the collection elements.

## Method: updateAll

### Description
Update all objects in this DocumentCollection with a provided transformation. Conditionally filter to only apply to Entities which match a certain condition.

### Signature
updateAll(transformation: object | Function, condition?: null | Function, options?: object): Promise<documents.Actor[]>

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

#### Query Parameters
- None

#### Request Body
- **transformation** (object | Function) - Required - An object of data or function to apply to all matched objects
- **condition** (Function | null) - Optional - A function which tests whether to target each object
- **options** (object) - Optional - Additional options passed to Document.updateDocuments

### Request Example
No JSON request body.

### Response
#### Success Response (Promise<documents.Actor[]>)
- An array of updated data once the operation is complete

#### Response Example
The resolved Promise value is an array of updated documents.Actor objects.

## Method: _initialize

### Description
Initialize the DocumentCollection by constructing any initially provided Document instances.

### Signature
_initialize(): void

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

#### Query Parameters
- None

#### Request Body
- None

### Request Example
No JSON request body.

### Response
#### Success Response (void)
- No return value

#### Response Example
No response.

## Static Method: getSearchableFields

### Description
Get the searchable fields for a given document or index, based on its data model.

### Signature
static getSearchableFields(documentName: string, type?: string): Record<string, SearchableField>

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

#### Query Parameters
- None

#### Request Body
- **documentName** (string) - Required - The document name
- **type** (string) - Optional - A document subtype

### Request Example
No JSON request body.

### Response
#### Success Response (Record<string, SearchableField>)
- A record of searchable fields

#### Response Example
An object with searchable field names as keys.
```

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

### Prompt for Input with DialogV2 (Foundry VTT)

Source: https://foundryvtt.com/api/classes/foundry.applications.api

Shows how to use DialogV2 to prompt the user for input. This example uses an input field within the dialog to collect numerical input from the user and validates the input.

```javascript
let guess;

try {
  guess = await foundry.applications.api.DialogV2.prompt({
    window: { title: "Guess a number between 1 and 10" },
    content: '<input name="guess" type="number" min="1" max="10" step="1" autofocus>',
    ok: {
      label: "Submit Guess",
      callback: (event, button, dialog) => button.form.elements.guess.valueAsNumber
    }
  });
} catch {
  console.log("User did not make a guess.");
  return;
}

const n = Math.ceil(CONFIG.Dice.randomUniform() * 10);
if ( n === guess ) console.log("User guessed correctly.");
else console.log("User guessed incorrectly.");
```

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

### DataModel Localization Implementation Example

Source: https://foundryvtt.com/api/classes/foundry.canvas.placeables.tokens

Demonstrates extending DataModel with custom schema fields and localization prefixes in Foundry VTT. The JavaScript code defines a model with string and number fields, while the companion JSON file provides localized labels and hints. This pattern automatically maps field names to translation keys under the specified prefix path for internationalization support.

```javascript
class MyDataModel extends foundry.abstract.DataModel {
  static defineSchema() {
    return {
      foo: new foundry.data.fields.StringField(),
      bar: new foundry.data.fields.NumberField()
    };
  }
  static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
}

Hooks.on("i18nInit", () => {
  // Foundry will attempt to automatically localize models registered for a document subtype, so this step is only
  // needed for other data model usage, e.g. for a Setting.
  Localization.localizeDataModel(MyDataModel);
});
```

```json
{
  "MYMODULE": {
    "MYDATAMODEL": {
      "FIELDS" : {
        "foo": {
          "label": "Foo",
          "hint": "Instructions for foo"
        },
        "bar": {
          "label": "Bar",
          "hint": "Instructions for bar"
        }
      }
    }
  }
}
```

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

### Constructor: ToursManagement

Source: https://foundryvtt.com/api/classes/foundry.applications.sidebar.apps

Initializes a new instance of the ToursManagement application. Applications are constructed by providing an object of configuration options.

```APIDOC
## Constructor: ToursManagement

### Description
Initializes a new instance of the ToursManagement application. Applications are constructed by providing an object of configuration options.

### Method
`new ToursManagement(options?: Partial<ApplicationConfiguration & CategoryBrowserConfiguration>): ToursManagement`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Request Example
```json
{
  "options": { /* Configuration options */ }
}
```

### Response
#### Success Response (200)
* **ToursManagement** - The newly created ToursManagement instance.

#### Response Example
```json
{ 
  "instance": "ToursManagement object"
}
```
```

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

### POST /websites/foundryvtt_api/_preStep

Source: https://foundryvtt.com/api/classes/foundry.nue

Executes set-up operations before a tour step is displayed. This is a protected method.

```APIDOC
## POST /websites/foundryvtt_api/_preStep

### Description
Protected method to set-up operations performed before a step is shown.

### Method
POST

### Endpoint
/websites/foundryvtt_api/_preStep

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **void** - Indicates successful completion of the operation.

#### Response Example
None
```

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

### Get Submit Data (Protected)

Source: https://foundryvtt.com/api/classes/foundry.appv1.api

Protected method to get an object of update data used to update the form's target object.

```javascript
_getSubmitData(updateData?: object): object
```

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

### Get Secret Content (Protected)

Source: https://foundryvtt.com/api/classes/foundry.appv1.api

Protected method to get the HTML content that a given secret block is embedded in. Accepts an HTMLElement representing the secret block.

```javascript
_getSecretContent(secret: HTMLElement): string | void
```

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

### AVSettings Methods

Source: https://foundryvtt.com/api/classes/foundry.av

Documentation for methods that handle user activity changes and register world and client WebRTC settings.

```APIDOC
## Methods

### handleUserActivity
- **Description**: Handles changes to another connected user's AV settings.
- **Method**: `handleUserActivity`
- **Parameters**:
  - `userId` (string) - The ID of the user whose settings have changed.
  - `settings` (AVSettingsData) - The new AV settings for the user.
- **Returns**: `void`

### `Static`register
- **Description**: Registers the world and client WebRTC settings.
- **Method**: `register`
- **Returns**: `void`
```

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

### Handle Ruler Drag Start - TypeScript

Source: https://foundryvtt.com/api/classes/foundry.canvas.interaction

Protected method that initiates a new ruler measurement workflow. Takes a drag start event as input and returns void. Begins the measurement process.

```typescript
_onDragStart(event: FederatedEvent<UIEvent | PixiTouch>): void
```

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

### AVSettings Class Overview

Source: https://foundryvtt.com/api/classes/foundry.av

This section provides an overview of the AVSettings class, detailing its properties, accessors, and methods for managing audio and video settings within Foundry Virtual Tabletop.

```APIDOC
## Class AVSettings

### Properties
- activity: Record<string, AVSettingsData>
- changed: () => void
- `Static`AV_MODES: { AUDIO: number; AUDIO_VIDEO: number; DISABLED: number; VIDEO: number; }
- `Static`DOCK_POSITIONS: { BOTTOM: string; LEFT: string; RIGHT: string; TOP: string }
- `Static`NAMEPLATE_MODES: { BOTH: number; CHAR_ONLY: number; OFF: number; PLAYER_ONLY: number; }
- `Static`VOICE_MODES: { ACTIVITY: string; ALWAYS: string; PTT: string }

### Accessors
- users: object
- verticalDock: boolean
- `Static`DEFAULT_USER_SETTINGS: object
- `Static`schemaFields: { client: SchemaField; world: SchemaField }

### Methods
- handleUserActivity(userId: string, settings: AVSettingsData): void
- `Static`register(): void
```

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

### Define Data Schema and Localization Prefixes (JavaScript)

Source: https://foundryvtt.com/api/classes/foundry.canvas.perception

This example demonstrates how to define a data schema for a custom DataModel and set localization prefixes for internationalization. It includes a JavaScript class definition and an example JSON structure for localization files.

```javascript
class MyDataModel extends foundry.abstract.DataModel {
  static defineSchema() {
    return {
      foo: new foundry.data.fields.StringField(),
      bar: new foundry.data.fields.NumberField()
    };
  }
  static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
}

Hooks.on("i18nInit", () => {
  // Foundry will attempt to automatically localize models registered for a document subtype, so this step is only
  // needed for other data model usage, e.g. for a Setting.
  Localization.localizeDataModel(MyDataModel);
});
```

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

### Initialize ShowToPlayersDialog instance

Source: https://foundryvtt.com/api/classes/foundry.applications.sheets.journal

Creates a new instance of ShowToPlayersDialog with optional configuration options. The dialog allows configuring options for showing content to players. It accepts partial configuration objects extending both ApplicationConfiguration and DialogV2Configuration interfaces.

```javascript
const dialog = new ShowToPlayersDialog({
  // Optional configuration options
});
```

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

### Tour Class API

Source: https://foundryvtt.com/api/classes/foundry.nue

Documentation for the Tour class, including its constructor, properties, accessors, and methods.

```APIDOC
## Class Tour
A Tour that shows a series of guided steps.

### Constructors
#### `constructor(config: TourConfig, options?: { id?: string; namespace?: string }): Tour`
Construct a Tour by providing a configuration.

##### Parameters
* **config** (TourConfig) - Required - The configuration of the Tour
* **options** (object) - Optional - Additional options for configuring the tour
  * **id** (string) - Optional - A tour ID that supercedes TourConfig#id
  * **namespace** (string) - Optional - A tour namespace that supercedes TourConfig#namespace

### Properties
* **config** (TourConfig) - Configuration of the tour. This object is cloned to avoid mutating the original configuration.
* **fadeElement** (HTMLElement) - The HTMLElement that fades out the rest of the screen
* **overlayElement** (any) - The HTMLElement that blocks input while a Tour is active
* **targetElement** (HTMLElement) - The HTMLElement which is the focus of the current tour step.
* **HIGHLIGHT_PADDING** (number) - `Static` Padding around a Highlighted Element. Default: 10

### Accessors
* **canStart** (boolean) - `get` Return whether this Tour is currently eligible to be started? This is useful for tours which can only be used in certain circumstances, like if the canvas is active.
* **currentStep** (null | TourStep) - `get` Return the current Step, or null if the tour has not yet started.
* **description** (string) - `get` The human-readable description of the tour.
* **hasNext** (boolean) - `get` Returns True if there is a next TourStep
* **hasPrevious** (boolean) - `get` Returns True if there is a previous TourStep
* **id** (string) - `get` The unique identifier of the tour.
* **key** (string) - `get` The key the Tour is stored under in game.tours, of the form `${namespace}.${id}`
* **namespace** (string) - `get` The package namespace for the tour.
* **status** (TourStatus) - `get` The current status of the Tour
* **stepIndex** (null | number) - `get` The index of the current step; -1 if the tour has not yet started, or null if the tour is finished.
* **steps** (TourStep[]) - `get` The configuration of tour steps
* **title** (string) - `get` The human-readable title for the tour.
* **activeTour** (null | Tour) - `get` `Static` Returns the active Tour, if any
* **tourInProgress** (boolean) - `get` `Static` Indicates if a Tour is currently in progress.

### Methods
* **_reloadProgress(): void** - `Internal` Reloads the Tour's current step from the saved progress.
* **complete(): Promise<any>** - Advance the tour to a completed state.
* **exit(): void** - Exit the tour at the current step.
* **next(): Promise<any>** - Progress the Tour to the next step.
* **previous(): Promise<any>** - Rewind the Tour to the previous step.
* **progress(stepIndex: number): Promise<any>** - Progresses to a given Step.
  * **Parameters**:
    * **stepIndex** (number) - Required - The step to progress to
* **reset(): Promise<any>** - Reset the Tour to an un-started state.
* **start(): Promise<any>** - Start the Tour at its current step, or at the beginning if the tour has not yet been started.
* **_getTargetElement(selector: string): null | Element** - `Protected` Query the DOM for the target element using the provided selector.
  * **Parameters**:
    * **selector** (string) - Required - A CSS selector
  * **Returns** null | Element - The target element, or null if not found
```

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

### toNearest Function

Source: https://foundryvtt.com/api/functions/primitives.Number

Describes the toNearest function, its parameters, return value, and provides examples of its usage.

```APIDOC
## Function toNearest

### Description
Round a number to the closest number which substracted from the base is a multiple of the provided interval. This is a convenience function intended to humanize issues of floating point precision. The interval is treated as a standard string representation to determine the amount of decimal truncation applied.

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
- **interval** (number) - Optional - The step interval
- **method** (string) - Optional - The rounding method. Valid values: "round", "floor", "ceil". Defaults to "round"
- **base** (number) - Optional - The step base. Defaults to 0

### Request Example

### Response
#### Success Response (number)
- **Returns** (number) - The rounded number

#### Response Example
```
let n = 17.18;
  
  n.toNearest(5); // 15  
  n.toNearest(10); // 20  
  n.toNearest(10, "floor"); // 10  
  n.toNearest(10, "ceil"); // 20  
  n.toNearest(0.25); // 17.25  
  n.toNearest(2, "round", 1); // 17
```
```

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

### POST /websites/foundryvtt_api/fromJSON

Source: https://foundryvtt.com/api/classes/foundry.nue

Creates and returns a Tour object by loading its configuration from a JSON file.

```APIDOC
## POST /websites/foundryvtt_api/fromJSON

### Description
Creates and returns a Tour by loading a JSON file.

### Method
POST

### Endpoint
/websites/foundryvtt_api/fromJSON

### Parameters
#### Query Parameters
- **filepath** (string) - Required - The path to the JSON file

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Tour** (object) - The created Tour object

#### Response Example
{
  "example": "{\"id\": \"tour-1\", \"steps\": [{\"id\": \"step-1\", \"content\": \"Welcome!\"}]}"
}
```

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

### Context and Tab Preparation Methods

Source: https://foundryvtt.com/api/classes/foundry.applications.api

Documentation for protected methods related to preparing application context and tab data.

```APIDOC
## Protected Methods for Context and Tab Preparation

### `_prepareContext`

#### Description
Prepare application rendering context data for a given render request. If exactly one tab group is configured for this application, it will be prepared automatically.

#### Method
`Protected`

#### Endpoint
N/A (Internal method)

#### Parameters
- **options** (ApplicationRenderOptions) - Required - Options which configure application rendering behavior

#### Returns
- Promise<ApplicationRenderContext> - Context data for the render operation

### `_prepareTabs`

#### Description
Prepare application tab data for a single tab group.

#### Method
`Protected`

#### Endpoint
N/A (Internal method)

#### Parameters
- **group** (string) - Required - The ID of the tab group to prepare

#### Returns
- Record<string, ApplicationTab>
```

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

### Fade Volume (JavaScript)

Source: https://foundryvtt.com/api/classes/foundry.audio

Fades the volume of a sound between a current level and a target volume, offering options for duration, start volume, and easing type.

```javascript
fade(  
 volume: number,  
 options?: { duration?: number; from?: number; type?: string },  
): Promise<void>
```

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

### Initialize Settings Application

Source: https://foundryvtt.com/api/classes/foundry.applications.sidebar.tabs

Constructs a new Settings application instance with optional configuration options. The Settings class extends AbstractSidebarTab and mixes in HandlebarsApplication for rendering.

```TypeScript
new Settings(options?: Partial<ApplicationConfiguration>): Settings
```

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

### Get Document by ID - FoundryVTT API

Source: https://foundryvtt.com/api/classes/foundry.documents

Retrieves a world-level document by its ID. Can optionally include database operation parameters. Returns the document or null if not found.

```TypeScript
get(documentId: string, operation?: DatabaseGetOperation): null | Document<object, DocumentConstructionContext>
```

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

### Load Audio (JavaScript)

Source: https://foundryvtt.com/api/classes/foundry.audio

Loads the audio source and prepares it for playback, optionally triggering autoplay with specified playback options.

```javascript
load(  
 options?: { autoplay?: boolean; autoplayOptions?: SoundPlaybackOptions },  
): Promise<Sound>
```

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

### _getTabsConfig(group: string)

Source: https://foundryvtt.com/api/classes/foundry.applications.sidebar.tabs

Protected method to get the configuration for a specific tabs group in the Application.

```APIDOC
## _getTabsConfig(group: string)

### Description
`Protected` Get the configuration for a tabs group.

### Function Signature
_getTabsConfig(group: string): null | ApplicationTabsConfiguration

### Parameters
#### group
- **group** (string) - Required - The ID of a tabs group.

### Returns
- **null | ApplicationTabsConfiguration**
```

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

### Right Drag Start

Source: https://foundryvtt.com/api/classes/foundry.canvas.placeables

Initiates a right mouse drag operation. This protected method is called when the user begins a drag by pressing the right mouse button.

```APIDOC
## Protected _onDragRightStart

### Description
Callback actions which occur on a right mouse-drag operation.

### Method
Protected

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (void)
Returns void. If false, the start is prevented.

#### Response Example
None
```

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

### Application Window Management API

Source: https://foundryvtt.com/api/classes/foundry.applications.sidebar.apps

Methods for controlling the visibility and stacking order of application windows.

```APIDOC
## POST /bringToFront

### Description
Brings the Application window to the front of the rendering stack by increasing its z-index. This ensures the application is visible above other windows.

### Method
POST

### Endpoint
/bringToFront

### Parameters
None

### Request Example
```json
{
  "action": "bringToFront"
}
```

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

#### Response Example
```json
{
  "status": "Application brought to front."
}
```
```

```APIDOC
## POST /maximize

### Description
Restores the Application to its original dimensions. This is typically used to exit a minimized or adjusted state.

### Method
POST

### Endpoint
/maximize

### Parameters
None

### Request Example
```json
{
  "action": "maximize"
}
```

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

#### Response Example
```json
{
  "status": "Application maximized."
}
```
```

```APIDOC
## POST /minimize

### Description
Minimizes the Application, collapsing it to a minimal header. This reduces the application's visual footprint.

### Method
POST

### Endpoint
/minimize

### Parameters
None

### Request Example
```json
{
  "action": "minimize"
}
```

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

#### Response Example
```json
{
  "status": "Application minimized."
}
```
```

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

### Protected _preFirstRender Method

Source: https://foundryvtt.com/api/classes/foundry.applications.sheets.journal

Executes actions before the very first render of an application, preparing context and options.

```APIDOC
## Protected _preFirstRender

### Description
Actions performed before a first render of the Application.

### Method
Protected

### Endpoint
N/A (Internal Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (Promise<void>)
- No specific return value, indicates successful completion.

#### Response Example
None
```

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

### Protected _getTabsConfig

Source: https://foundryvtt.com/api/classes/foundry.applications.sheets

Gets the configuration for a tabs group. Returns null or an ApplicationTabsConfiguration object based on the provided group ID.

```APIDOC
## GET /api/application/tabs-config/{group}

### Description
Get the configuration for a tabs group.

### Method
GET

### Endpoint
/api/application/tabs-config/{group}

### Parameters
#### Path Parameters
- **group** (string) - Required - The ID of a tabs group

### Response
#### Success Response (200)
- **config** (ApplicationTabsConfiguration|null) - Tabs configuration or null

#### Response Example
{
  "config": {
    "active": "tab1",
    "tabs": []
  }
}
```

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

### Sound - _play (Protected)

Source: https://foundryvtt.com/api/classes/foundry.audio

Protected method to begin playback for the configured pipeline and playback options, allowing for subclass implementations.

```APIDOC
## _play

### Description
`Protected`
Begin playback for the configured pipeline and playback options. This method is factored out so that subclass implementations of Sound can implement alternative behavior.

### Method
`_play`

#### Returns
void
```

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

### Get Application Header Controls (TypeScript)

Source: https://foundryvtt.com/api/classes/foundry.applications.sheets.journal

Configures and returns the array of entries for the application's header control menu.

```typescript
/**
 * Configure the array of header control menu options
 * @returns {ApplicationHeaderControlsEntry[]}
 */
_getHeaderControls(): ApplicationHeaderControlsEntry[]
```

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

### Get Drag and Context Data

Source: https://foundryvtt.com/api/classes/foundry.applications.sidebar

Retrieve drag data for entries and context menu options. These methods handle data retrieval for drag operations and context menu creation.

```typescript
protected _getDroppedEntryFromData(data: object): Promise<ClientDocument>;

protected _getEntryContextOptions(): ContextMenuEntry[];

protected _getEntryDragData(entryId: string): any;
```

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

### Handle User Activity and Registration

Source: https://foundryvtt.com/api/classes/foundry.av

Methods for handling user AV activity updates and registering WebRTC settings. The handleUserActivity method processes changes from other users, while the register method sets up world and client settings.

```javascript
handleUserActivity(userId: string, settings: AVSettingsData): void { /* implementation */ }

static register(): void { /* implementation */ }
```

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

### Get Application Render State

Source: https://foundryvtt.com/api/classes/foundry.applications.ui

Retrieves the current rendering state of the Application instance. This property returns a number representing the state.

```typescript
/**
 * Get the current render state of the Application.
 * @returns {number} The current render state.
 */
get state(): number;
```

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

### Application Core Methods

Source: https://foundryvtt.com/api/classes/foundry.appv1.sheets

Core methods for activating listeners, managing views, and creating UI handlers.

```APIDOC
## Application Core Methods

### _activateCoreListeners

*   **_activateCoreListeners(html: any)**: void
    *   *Description*: Activate required listeners which must be enabled on every Application. These are internal interactions which should not be overridden by downstream subclasses.
    *   *Parameters*:
        *   `html` (any): The HTML element to attach listeners to.

### _closeView

*   **_closeView()**: void
    *   *Description*: A method called by the journal sheet when the view mode of the page sheet is closed. (Internal)

### _contextMenu

*   **_contextMenu(html: jQuery)**: void
    *   *Description*: Create a foundry.applications.ux.ContextMenu for this Application. (Internal)
    *   *Parameters*:
        *   `html` (jQuery): The Application's HTML.

### _createDragDropHandlers

*   **_createDragDropHandlers()**: DragDrop[]
    *   *Description*: Create drag-and-drop workflow handlers for this Application. (Internal)
    *   *Returns*:
        *   DragDrop[]: An array of DragDrop handlers.

### _createSearchFilters

*   **_createSearchFilters()**: SearchFilter[]
    *   *Description*: Create search filter handlers for this Application. (Internal)
    *   *Returns*:
        *   SearchFilter[]: An array of SearchFilter handlers.

### _createTabHandlers

*   **_createTabHandlers()**: Tabs[]
    *   *Description*: Create tabbed navigation handlers for this Application. (Internal)
    *   *Returns*:
        *   Tabs[]: An array of Tabs handlers.
```

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

### GET /_getHeaderControls

Source: https://foundryvtt.com/api/classes/foundry.applications.apps

Configure and retrieve the array of header control menu options for the Application. This protected method returns configuration entries for header controls.

```APIDOC
## GET /_getHeaderControls

### Description
Configure the array of header control menu options. This is a protected method that returns header control configurations.

### Method
GET

### Endpoint
/_getHeaderControls

### Parameters
No parameters required

### Request Example
{}

### Response
#### Success Response (200)
- **returns** (ApplicationHeaderControlsEntry[]) - Array of header control configuration entries

#### Response Example
[
  {
    "name": "close",
    "title": "Close Window",
    "icon": "fas fa-times"
  }
]
```

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

### Initialize DataModel Instance (Protected)

Source: https://foundryvtt.com/api/classes/foundry.config

Protected method to initialize the instance by copying data from the source object to instance attributes. Mirrors SchemaField#initialize but with added functionality.

```javascript
/**
 * Protected: Initialize the instance by copying data from the source object to instance attributes.
 * @param {object} [options={}] - Options provided to the model constructor.
 * @returns {void}
 */
_initialize(options?: object): void
```

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

### Get Application Tabs Configuration (TypeScript)

Source: https://foundryvtt.com/api/classes/foundry.applications.sheets.journal

Retrieves the configuration for a specified tabs group within the Application. Returns null if the group does not exist or has no configuration.

```typescript
/**
 * Get the configuration for a tabs group.
 * @param {string} group - The ID of a tabs group
 * @returns {null | ApplicationTabsConfiguration}
 */
_getTabsConfig(group: string): null | ApplicationTabsConfiguration
```

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

### Get Collection Name - FoundryVTT API

Source: https://foundryvtt.com/api/classes/foundry.documents

Returns the name of an embedded collection within a document. Accepts either a collection name or document name. Returns the collection name if found, or null otherwise.

```TypeScript
getCollectionName(name: string): null | string
```

```TypeScript
Actor.implementation.getCollectionName("items");
```

```TypeScript
Actor.implementation.getCollectionName("Item");
```

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

### Get Ruler Waypoint Style - TypeScript

Source: https://foundryvtt.com/api/classes/foundry.canvas.interaction

Protected method that returns the visual style properties for a ruler waypoint. Includes optional alpha and color properties with required radius. Takes a waypoint as input.

```typescript
_getWaypointStyle(waypoint: DeepReadonly<RulerWaypoint>): { alpha?: number; color?: ColorSource; radius: number }
```

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

### WorldCollection Constructor

Source: https://foundryvtt.com/api/classes/foundry.documents.abstract

Details on how to construct a new WorldCollection instance.

```APIDOC
## Constructors

### constructor
  * new WorldCollection<  
TDocument extends Document<object, DocumentConstructionContext>,  
>(  
data?: object[],  
): WorldCollection<TDocument>
#### Type Parameters
    * TDocument extends Document<object, DocumentConstructionContext>
#### Parameters
    * data: object[] = []
An array of data objects from which to create document instances
#### Returns WorldCollection<TDocument>
```

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

### DataModel Instantiation from Source

Source: https://foundryvtt.com/api/classes/foundry.documents

Explains how to create a new DataModel instance from a source object using the `fromSource` static method.

```APIDOC
## Static Method: fromSource

### Description
Creates a new instance of this DataModel from a source record. The source is presumed to be trustworthy and is not strictly validated.

### Method
Static

### Endpoint
N/A (Class method)

### Parameters
- **source** (object) - Required - The source data object.
- **context** (object) - Optional - Construction context options.

### Returns
- **dataModelInstance** (DataModel) - A newly created data model instance.

### Example
```javascript
const sourceData = { foo: 'baz' };
const model = SomeModel.fromSource(sourceData);
console.log(model.foo); // Output: baz
```
```

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

### Handle Document Update Event

Source: https://foundryvtt.com/api/classes/foundry.data.regionBehaviors

Invoked when document updates occur. Gets diff changes, update options, and user who initiated change. No return value expected.

```typescript
protected _onUpdate(changed: object, options: object, userId: string): void {
  // Post-update logic
}
```

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

### Get Application Window Title

Source: https://foundryvtt.com/api/classes/foundry.applications.ui

Provides a convenience reference to the title of the Application window. This string property allows easy access to the window's title.

```typescript
/**
 * Get a convenience reference to the title of the Application window.
 * @returns {string} The title of the application window.
 */
get title(): string;
```

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

### Sound - _connectPipeline (Protected)

Source: https://foundryvtt.com/api/classes/foundry.audio

Protected method to create the audio pipeline used for playing the Sound.

```APIDOC
## _connectPipeline

### Description
`Protected`
Create the audio pipeline used to play this Sound. The GainNode is reused each time to link volume changes across multiple playbacks. The AudioSourceNode is re-created every time that Sound#play is called.

### Method
`_connectPipeline`

#### Returns
void
```

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

### Static testAvailability

Source: https://foundryvtt.com/api/classes/foundry.packages

Checks compatibility data against the current installation and determines availability. This method assesses modules, systems, and releases to return an availability number for package management.

```APIDOC
## Static testAvailability

### Description
Check the given compatibility data against the current installation state and determine its availability.

### Method
Static Method

### Endpoint
testAvailability(data: Partial<WorldManifestData>, options?: { modules?: any; release?: any; systemAvailabilityThreshold?: number; systems?: any; })

### Parameters
#### Request Body
- **data** (object) - Required - Partial manifest data
- **options.modules** (any) - Optional
- **options.release** (any) - Optional
- **options.systemAvailabilityThreshold** (number) - Optional
- **options.systems** (any) - Optional

### Request Example
{
  "data": {}
}

### Response
#### Success Response
- **number** - Availability number

#### Response Example
1
```
Tokens:
Raw