Options
All
  • Public
  • Public/Protected
  • All
Menu

Foundry Virtual Tabletop - API Documentation - Version 10

Welcome to the documentation for the client-side API of Foundry Virtual Tabletop, a JavaScript application for running tabletop role-playing games within a self-hosted web framework. The goal of this documentation is to empower developers to create amazing game systems, add-on modules, and scripts which augment and extend the base functionality of the Foundry Virtual Tabletop platform.

Table of Contents

Reading these API Docs

Public vs Private API

The Public API

The Public API is our set of methods and properties that we officially support and recommend Package developers to use in their integrations. The Public API comes with a set of promises from Foundry:

  1. We will provide guidance, documentation, and help with using the Public API
  2. We will provide deprecation periods when breaking changes are made when possible
  3. We will make breaking changes to the public API only during certain Phases of a Version, as outlined here

As a team we endeavour to maintain the public API in a state that is as stable and reliable as possible.

/**
* Part of the Public API, call externally
* @public
*/
async doThing() {}

/**
* Part of the Public API, don't call externally
* @protected
*/
async _doThing() {}

The Private API

The Private API is the set of methods and properties that Foundry uses internally to power the software, and explicitly do not support and recommend against Package developers using.

  1. We may not provide guidance nor help, and documentation will only be our internal docs
  2. We will not provide deprecation periods
  3. We will make breaking changes at any point in a Version

Though we recognize that our truly fantastic development community are capable of using the Foundry VTT API to achieve astounding feats, many of the most diverse and wondrous modules do so by leveraging the Private API. We have no interest in disallowing packages from overriding or changing these Private API functions, but there are a number of reasons why these functions are marked as Private. As the Private API is subject to change at any time, those Game Systems and Add-on Modules which do modify private functions will be impacted more when the software updates than those which keep only to the Public API.

/**
* Part of the Private API, don't call at all
* @private
*/
async _doThing() {}

/**
* Implied part of the Private API, don't call at all
*/
async _doThing() {}

/**
* Part of the Private API, JS prevents you from calling
* @private
*/
async #doThing() {}

What about things that are unclear?

A lot of the Foundry codebase is not explicitly annotated one way or another as to which API it belongs to. The following Code Guidelines will help you navigate our API. As always, please reach out to us on Discord for clarification as well.

Code Guidelines

Annotations

@public

Methods and properties marked @public may be called both externally and internally. They may only be modified within the class that defines them or a subclass of that parent class.

@protected

Methods and properties marked @protected may only be used or modified within the class that defines them or a subclass of that parent class. We do intend for API users to override @protected properties when they are defining a subclass which replaces or extends the behavior of its parent class.

@private

Methods and properties marked @private should not be used or modified except by the class which defined them. For API users, this means that you should not reference or override this property. We may make breaking changes to the code for @private attributes without warning or advance notice, even in software versions which are marked "Stable".

@internal

Methods and properties marked @internal should only be used by the core Foundry VTT codebase and should not be referenced or overridden by external code. This is effectively similar to @private except that @internal methods may be called outside of the context of the class which defines them.

Naming Conventions

_ naming

Methods and properties which begin with an underscore _ and are not otherwise documented with one of the above tags should be treated as @private.

# naming

Methods and properties which begin with a # are hard-private, and are not able to be accessed outside of their declaring class. This is enforced by Javascript itself - any attempt to read or write these will cause a syntax error. MDN reference

FAQ

What is a breaking change?

A breaking change is one that makes existing calls to the API incompatible with the new version.

Periodically it is necessary to make breaking changes to Public API functions in order to introduce new features or correct bugs in existing ones. These breaking changes can make an existing call to the Public API invalid, such as change in return type, removing a parameter, or renaming a method without providing an alias.

Adding a new optional parameter or updating TypeDocs are not considered to be "Breaking" changes. Interior implementation or behavioral changes are also not considered to be "Breaking" changes, such as changing the order elements in a list are returned in, or refactoring a large method to have smaller interior methods.

How can I request changes and expansions to the Public API?

If something you would like to do can only be done via the Private API, please reach out to us via our Discord channels such as #dev-support and/or create an Issue on our Github outlining what you're trying to do and what issues you're facing, and we will try our best to help or scope future work to better enable what you're doing.

Documents and Data

Data in Foundry Virtual Tabletop is organized around the concept of Documents. Each document represents a single coherent piece of data which represents a specific object within the framework. The term Document refers to both the definition of a specific type of data (the Document class) as well as a uniquely identified instance of that data type (an instance of that class).

Document Abstraction
  • DataModel - The abstract base class which defines a data model with corresponding schema and state.
  • Document - The abstract base class shared by both client and server-side which defines the model for a single document type.

Database Operations
  • DatabaseBackend - An interface shared by both the client and server-side which defines how creation, update, and deletion operations are transacted.
  • ClientDatabaseBackend - An implementation of the abstract backend which performs client-side CRUD operations.

Collections
  • DocumentCollection - An abstract subclass of the Collection container which defines a collection of Document instances.
  • WorldCollection - A collection of world-level Document objects with a singleton instance per primary Document type.
  • CompendiumCollection - A collection of Document objects contained within a specific compendium pack.

Primary Document Types

Foundry Virtual Tabletop includes the following primary Document types, each of which is saved to its own database table with within the active World.

Actor
  • BaseActor - The base Actor model definition which defines common behavior of an Actor document between both client and server.
  • Actor - The client-side Actor document which extends the common BaseActor model.
  • Actors - The singleton collection of Actor documents which exist within the active World.
  • ActorSheet - The Application responsible for displaying and editing a single Actor document.
  • ActorDirectory - The sidebar directory which organizes and displays world-level Actor documents.

Cards
  • BaseCards - The base Cards model definition which defines common behavior of an Cards document between both client and server.
  • Cards - The client-side Cards document which extends the common BaseCards model.
  • CardStacks - The singleton collection of Cards documents which exist within the active World.
  • CardsConfig - The base Application responsible for displaying and editing a single Cards document.
  • CardsDirectory - The sidebar directory which organizes and displays world-level Cards documents.

Chat Message
  • BaseChatMessage - The base ChatMessage model definition which defines common behavior of an ChatMessage document between both client and server.
  • ChatMessage - The client-side ChatMessage document which extends the common BaseChatMessage model.
  • Messages - The singleton collection of ChatMessage documents which exist within the active World.
  • ChatLog - The sidebar directory which organizes and displays world-level ChatMessage documents.

Combat Encounter
  • BaseCombat - The base Combat model definition which defines common behavior of an Combat document between both client and server.
  • Combat - The client-side Combat document which extends the common BaseCombat model.
  • CombatEncounters - The singleton collection of Combat documents which exist within the active World.
  • CombatTracker - The sidebar directory which organizes and displays world-level Combat documents.
  • CombatTracker - The Application responsible for configuring the CombatTracker and its contents.

Item
  • BaseItem - The base Item model definition which defines common behavior of an Item document between both client and server.
  • Item - The client-side Item document which extends the common BaseItem model.
  • Items - The singleton collection of Item documents which exist within the active World.
  • ItemSheet - The Application responsible for displaying and editing a single Item document.
  • ItemDirectory - The sidebar directory which organizes and displays world-level Item documents.

Fog Exploration
  • BaseFogExploration - The base FogExploration model definition which defines common behavior of an FogExploration document between both client and server.
  • FogExploration - The client-side FogExploration document which extends the common BaseFogExploration model.
  • FogExplorations - The singleton collection of FogExploration documents which exist within the active World.

Folder
  • BaseFolder - The base Folder model definition which defines common behavior of an Folder document between both client and server.
  • Folder - The client-side Folder document which extends the common BaseFolder model.
  • Folders - The singleton collection of Folder documents which exist within the active World.
  • FolderConfig - The Application responsible for configuring a single Folder document.

Journal Entry
  • BaseJournalEntry - The base JournalEntry model definition which defines common behavior of an JournalEntry document between both client and server.
  • JournalEntry - The client-side JournalEntry document which extends the common BaseJournalEntry model.
  • Journal - The singleton collection of JournalEntry documents which exist within the active World.
  • JournalSheet - The Application responsible for displaying and editing a single JournalEntry document.
  • JournalDirectory - The sidebar directory which organizes and displays world-level JournalEntry documents.

Macro
  • BaseMacro - The base Macro model definition which defines common behavior of an Macro document between both client and server.
  • Macro - The client-side Macro document which extends the common BaseMacro model.
  • Macros - The singleton collection of Macro documents which exist within the active World.
  • MacroConfig - The Application responsible for displaying and editing a single Macro document.
  • MacroDirectory - The directory, not displayed in the sidebar, which organizes and displays world-level Macro documents.

Playlist
  • BasePlaylist - The base Playlist model definition which defines common behavior of an Playlist document between both client and server.
  • Playlist - The client-side Playlist document which extends the common BasePlaylist model.
  • Playlists - The singleton collection of Playlist documents which exist within the active World.
  • PlaylistConfig - The Application responsible for configuring a single Playlist document.
  • PlaylistDirectory - The sidebar directory which organizes and displays world-level Playlist documents.

Rollable Table
  • BaseRollTable - The base RollTable model definition which defines common behavior of an RollTable document between both client and server.
  • RollTable - The client-side RollTable document which extends the common BaseRollTable model.
  • RollTables - The singleton collection of RollTable documents which exist within the active World.
  • RollTableConfig - The Application responsible for displaying and editing a single RollTable document.
  • RollTableDirectory - The sidebar directory which organizes and displays world-level RollTable documents.

Scene
  • BaseScene - The base Scene model definition which defines common behavior of an Scene document between both client and server.
  • Scene - The client-side Scene document which extends the common BaseScene model.
  • Scenes - The singleton collection of Scene documents which exist within the active World.
  • SceneConfig - The Application responsible for configuring a single Scene document.
  • SceneDirectory - The sidebar directory which organizes and displays world-level Scene documents.
  • SceneNavigation - The UI element which displays the Scene documents which are currently enabled for quick navigation.

Setting
  • BaseSetting - The base Setting model definition which defines common behavior of an Setting document between both client and server.
  • ClientSettings - A class responsible for managing defined game settings or settings menus.
  • Settings - The sidebar tab which displays various game settings, help messages, and configuration options.
  • SettingConfig - The Application responsible for displaying and configuring registered game Setting documents.

User
  • BaseUser - The base User model definition which defines common behavior of an User document between both client and server.
  • User - The client-side User document which extends the common BaseUser model.
  • Users - The singleton collection of User documents which exist within the active World.
  • UserConfig - The Application responsible for configuring a single User document.
  • PlayerList - The UI element which displays the list of Users who are currently playing within the active World.

Embedded Document Types

In addition to the above primary document types, each of which are indexed within their own tables, there are several additional document types which only exist as embedded documents within a parent Document. These embedded documents cannot exist on their own (outside of the context of a parent).

Active Effect
  • BaseActiveEffect - The base ActiveEffect model definition which defines common behavior of an ActiveEffect document between both client and server.
  • ActiveEffect - The client-side ActiveEffect document which extends the common BaseActiveEffect model.
  • ActiveEffectConfig - The Application responsible for configuring a single ActiveEffect document within a parent Actor or Item.

Combatant
  • BaseCombatant - The base Combatant model definition which defines common behavior of an Combatant document between both client and server.
  • Combatant - The client-side Combatant document which extends the common BaseCombatant model.
  • CombatantConfig - The Application responsible for configuring a single Combatant document within a parent Combat.

Playlist Sound
  • BasePlaylistSound - The base PlaylistSound model definition which defines common behavior of an PlaylistSound document between both client and server.
  • PlaylistSound - The client-side PlaylistSound document which extends the common BasePlaylistSound model.
  • PlaylistSoundConfig - The Application responsible for configuring a single PlaylistSound document within a parent Playlist.

Table Result
  • BaseTableResult - The base TableResult model definition which defines common behavior of an TableResult document between both client and server.
  • TableResult - The client-side TableResult document which extends the common BaseTableResult model.

Ambient Light
  • BaseAmbientLight - The base AmbientLight model definition which defines common behavior of an AmbientLight document between both client and server.
  • AmbientLightDocument - The client-side AmbientLight document which extends the common BaseAmbientLight model.
  • LightConfig - The Application responsible for configuring a single AmbientLight document within a parent Scene.

Ambient Sound
  • BaseAmbientSound - The base AmbientSound model definition which defines common behavior of an AmbientSound document between both client and server.
  • AmbientSoundDocument - The client-side AmbientSound document which extends the common BaseAmbientSound model.
  • AmbientSoundConfig - The Application responsible for configuring a single AmbientSound document within a parent Scene.

Drawing
  • BaseDrawing - The base Drawing model definition which defines common behavior of an Drawing document between both client and server.
  • DrawingDocument - The client-side Drawing document which extends the common BaseDrawing model.
  • DrawingConfig - The Application responsible for configuring a single Drawing document within a parent Scene.

Measured Template
  • BaseMeasuredTemplate - The base MeasuredTemplate model definition which defines common behavior of an MeasuredTemplate document between both client and server.
  • MeasuredTemplateDocument - The client-side MeasuredTemplate document which extends the common BaseMeasuredTemplate model.
  • MeasuredTemplateConfig - The Application responsible for configuring a single MeasuredTemplate document within a parent Scene.

Note
  • BaseNote - The base Note model definition which defines common behavior of an Note document between both client and server.
  • NoteDocument - The client-side Note document which extends the common BaseNote model.
  • NoteConfig - The Application responsible for configuring a single Note document within a parent Scene.

Tile
  • BaseTile - The base Tile model definition which defines common behavior of an Tile document between both client and server.
  • TileDocument - The client-side Tile document which extends the common BaseTile model.
  • TileConfig - The Application responsible for configuring a single Tile document within a parent Scene.

Token
  • BaseToken - The base Token model definition which defines common behavior of an Token document between both client and server.
  • TokenDocument - The client-side Token document which extends the common BaseToken model.
  • TokenConfig - The Application responsible for configuring a single Token document within a parent Scene.

Wall
  • BaseWall - The base Wall model definition which defines common behavior of an Wall document between both client and server.
  • WallDocument - The client-side Wall document which extends the common BaseWall model.
  • WallConfig - The Application responsible for configuring a single Wall document within a parent Scene.

The Game Canvas

The visual game surface in Foundry Virtual Tabletop is managed by a WebGL-powered canvas which uses the PixiJS library.

Canvas Building Blocks

The game canvas is constructed using several core building blocks.

  • Canvas - The master controller of the canvas element upon which the tabletop is rendered.
  • CanvasLayer - An abstract pattern for primary layers of the game canvas to implement.
  • PlaceablesLayer - A subclass of Canvas Layer which is specifically designed to contain multiple PlaceableObject instances, each corresponding to an embedded Document.
  • CanvasDocumentMixin - A specialized sub-class of the ClientDocumentMixin which is used for document types that are intended to be represented upon the game Canvas.
  • PlaceableObject
  • CanvasAnimation

Canvas Groups

The first level of canvas hierarchy is the concept of groups which provide top-level containers for various concepts.

  • HiddenCanvasGroup - A container for objects which are transformed but not rendered.
  • RenderedCanvasGroup - A container for objects which are rendered on the canvas.
  • PrimaryCanvasGroup - Tangible objects which exist within the Scene and are affected by lighting and other effects.
  • EffectsCanvasGroup - Visual effects which modify the appearance of objects in the PrimaryCanvasGroup.
  • InterfaceCanvasGroup - User interface elements which provide interactivity and context but are not tangible objects within the Scene.

Canvas Layers

Within each of the above canvas groups there are a number of layers which provide specific functionality. Canvas layers utilize the following base classes.

  • CanvasLayer A base class for all canvas layers.
  • InteractionLayer An extension of CanvasLayer which provides user interactivity for its contained objects.
  • PlaceablesLayer An extension of InteractionLayer specifically designed for drawing Documents to the canvas.

The following are implementations of canvas layers:

Within the Effects Canvas Group

Within the Interface Canvas Group

Canvas Objects

Canvas layers contain PlaceableObject instances which are rendered within that layer. The following are the available object types which may be placed.

HUD Overlay

In addition to WebGL canvas layers, there is also support for HTML-based canvas overlay known as "HUD" objects.

User Interface

In addition to the underlying data and the visual representation of that data on the Canvas, Foundry VTT renders many HTML Applications which represent modular interface components for browsing, editing, or configuring elements of the virtual tabletop.

Application Building Blocks

The following classes provide high-level building blocks for defining HTML applications within Foundry Virtual Tabletop.

Dice Rolling

As a developer, you may often want to trigger dice rolls or customize the behavior of dice rolling. Foundry Virtual Tabletop provides a set of API concepts dedicated towards working with dice.

  • Roll - An interface and API for constructing and evaluating dice rolls.
  • RollTerm - An abstract class which represents a single token that can be used as part of a Roll formula.
  • MersenneTwister - A standalone, pure JavaScript implementation of the Mersenne Twister pseudo random number generator.

Roll Term Types
  • DiceTerm - An abstract base class for any type of RollTerm which involves randomized input from dice, coins, or other devices.
  • MathTerm - A type of RollTerm used to apply a function from the Math library.
  • NumericTerm - A type of RollTerm used to represent static numbers.
  • OperatorTerm - A type of RollTerm used to denote and perform an arithmetic operation.
  • ParentheticalTerm - A type of RollTerm used to enclose a parenthetical expression to be recursively evaluated.
  • PoolTerm - A type of RollTerm which encloses a pool of multiple inner Rolls which are evaluated jointly.
  • StringTerm - A type of RollTerm used to represent strings which have not yet been matched.

Dice Types
  • Die - A type of DiceTerm used to represent rolling a fair n-sided die.
  • Coin - A type of DiceTerm used to represent flipping a two-sided coin.
  • FateDie - A type of DiceTerm used to represent a three-sided Fate/Fudge die.

Other Major Components

In addition to the outlined structure above, there are many additional miscellaneous elements of the Foundry Virtual Tabletop API for you to explore. Please browse the sidebar for a complete listing of classes and functions. Some specific classes which are noteworthy or commonly used include:

Audio and Video
  • AudioHelper - Utilities for working with Audio files.
  • ImageHelper - Utilities for working with Image files.
  • Sound - The Sound class is used to control the playback of audio sources using the Web Audio API.
  • VideoHelper - Utilities for working with Video files.

Game Management
  • Game - The master controller for the active game instance
  • GameTime - A singleton class which keeps the official Server and World time stamps.

Video and Voice Chat
  • AVMaster - The master Audio/Video controller instance.
  • AVClient - An interface for an Audio/Video client which is extended to provide broadcasting functionality.
  • SimplePeerAVClient - An implementation of the AVClient which uses the simple-peer library and the Foundry socket server for signaling.

Interactivity
  • Hooks - An infrastructure for registering event handlers which fire under specific conditions.
  • KeyboardManager - A set of helpers and management functions for dealing with user input from keyboard events.
  • SocketInterface - Helper functions for dispatching and receiving socket events in a standardized way.