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.
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:
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 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.
Any modification, overriding, or usage of private API methods should be done at the developers own risk. Packages which touch these private API methods are likely to be inherently less stable and more prone to breakage than packages which only engage with our provided 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() {}
/**
* Able to be called externally, but treated as part of the private API
* @internal
*/
async _doThing() {}
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.
@publicMethods 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.
@protectedMethods 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.
@privateMethods 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". Now that JavaScript offers true private methods like #privateMethod we are moving our codebase away from use of the @private annotation entirely. Methods which were previously @private will be, at some point, migrated to become true private methods.
@internalMethods 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.
_ namingMethods and properties which begin with an underscore _ and are not otherwise documented with one of the above tags should be treated as @private.
# namingMethods and properties which begin with a # are truly private, and cannot be accessed outside their declaring class. This is enforced by Javascript itself - any attempt to read or write these will cause a syntax error.
MDN reference
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.
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.
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).
Foundry Virtual Tabletop includes the following primary Document types, each of which is saved to its own database table with within the active World.
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).
The visual game surface in Foundry Virtual Tabletop is managed by a WebGL-powered canvas which uses the PixiJS library.
The game canvas is constructed using several core building blocks.
The first level of canvas hierarchy is the concept of groups which provide top-level containers for various concepts. They are containers that mixin foundry.canvas.groups.CanvasGroupMixin.
Within each of the above canvas groups there are a number of layers which provide specific functionality. Canvas layers utilize the following base classes.
The following are implementations of canvas layers:
Canvas layers contain foundry.canvas.placeables.PlaceableObject instances which are rendered within that layer. The following are the available object types which may be placed.
In addition to WebGL canvas layers, there is also support for HTML-based canvas overlay known as "HUD" objects.
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.
The following classes provide high-level building blocks for defining HTML applications within Foundry Virtual Tabletop.
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.
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: