Foundry Virtual Tabletop - API Documentation - Version 12
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:
We will provide guidance, documentation, and help with using the Public API
We will provide deprecation periods when breaking changes are made when possible
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 */ asyncdoThing() {}
/** * 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.
We may not provide guidance nor help, and documentation will only be our internal docs
We will not provide deprecation periods or compatibility layers when these functions change
We may make breaking changes at any point of development, including during the Stable phase
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.
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.
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.
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". 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.
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.
Methods 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).
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.
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).
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.
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.
Within each of the above canvas groups there are a number of layers which provide specific functionality. Canvas layers utilize the following base classes.
Canvas layers contain PlaceableObject instances which are rendered within that layer. The following are the available object types which may be placed.
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.
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.
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: