Commit 889245a5 authored by Andrew's avatar Andrew

Remove API documentation from RST pages

parent d4a61a32
......@@ -27,11 +27,11 @@ roleplaying games in a beautiful and intuitive web-based application.
pages/dice
pages/features/av
pages/features/aws
pages/api
pages/systems
pages/modules
pages/partnerships
notes/notes
Developer API <http://foundryvtt.com/api>
About Foundry Virtual Tabletop
......
......@@ -3,7 +3,7 @@
"recurseDepth": 10,
"sourceType": "module",
"tags": {
"allowUnknownTags": false,
"allowUnknownTags": true,
"dictionaries": ["jsdoc"]
},
"templates": {
......
.. _api:
Developer API Documentation
***************************
This section of the documentation is dedicated to the software APIs which enable system and module developers to create
amazing add-on software which augments and extends the base functionality of the FVTT platform.
.. toctree::
:caption: API Contents
:name: api-contents
:maxdepth: 2
api/entities
api/canvas
api/dice
api/hooks
api/ui
api/localization
.. _application:
The Application Class
*********************
The :class:`Application` class provides the foundation for UI elements in Foundry VTT. As a developer, you
should extend this class to define your own custom UI concepts which can be rendered in-game.
.. autoclass:: Application
:members:
Application Example
===================
This section provides a working example Application that could be defined in your game. When creating a module, or
a UI component of a game system, you would pair this JavaScript code which defines the Application with an HTML
template (``options.template``) as well as accompanying CSS rules to define how the HTML should be styled.
.. code-block:: javascript
/**
* A simple demo application which displays each active player's impersonated Actor
* Displays the portrait and health bar for that Actor
*/
class PartySummary extends Application {
/**
* Define default options for the PartySummary application
*/
static get defaultOptions() {
const options = super.defaultOptions;
options.template = "public/modules/party-summary/templates/summary.html";
options.width = 600;
options.height = "auto";
return options;
}
/* -------------------------------------------- */
/**
* Return the data used to render the summary template
* Get all the active users
* The impersonated character for each player is available as user.character
*/
getData() {
return game.users.entities.filter(u => u.active);
}
/* -------------------------------------------- */
/**
* Add some event listeners to the UI to provide interactivity
* Let's have the game highlight each player's token when their name is clicked on
*/
activateListeners(html) {
html.find(".actor-name").click(ev => {
ev.preventDefault();
// Get the actor which was clicked and the active token(s) for that actor
let actorId = ev.currentTarget.parentElement.getAttribute("data-actor-id"),
actor = game.actors.get(actorId),
tokens = actor.getActiveTokens(true);
// Highlight active token(s) by triggering the token's mouse-over handler
for ( let t of tokens ) {
t._onMouseOver();
}
})
}
}
To render your party summary UI to the player, all that needs to be done is to create an instance of the
application class and call it's render function.
.. code-block:: javascript
let ps = new PartySummary();
ps.render(true);
.. _dialog:
Dialog Window
*************
The :class:`Dialog` class provides an extension of :class:`Application` which makes it easy to create modal
dialog prompts.
.. autoclass:: Dialog
:members:
.. autofunction:: Application#render
.. _formApplication:
The Form Application
********************
A very common use case for building :class:`Application` UI elements is to edit an existing data object. The editing
workflow has many common features - you have a form of input fields which are modified and then saved, at which point
the underlying data object is saved and further downstream updates may also occur.
In order to simplify this workflow, the :class:`FormApplication` class provides a layer of abstraction which extends
the base :class:`Application` and adds some additional methods and workflows which are specifically ideal for working
with forms and saving new data.
----------
.. autoclass:: FormApplication
:members:
----------
.. autoclass:: BaseEntitySheet
:members:
.. _helpers:
Tabbed Navigation
*****************
To make effective use of screen space, it often makes sense to sibling concepts into a tabbed navigation area. The
:class:`Tabs` class helps to implement this easily. Simply create instances of the :class:`Tabs` class when you
register event listeners for your UI element and the instance will do the rest of the work for you.
.. autoclass:: Tabs
:members:
.. _notifications:
Sending Notifications
*********************
The :class:`Notifications` class provides an :class:`Application` implementation which makes it easy to display
contextual notifications to clients. There should only be a singleton instance of this class, so rather than creating
your own instance please use the existing instance which is available as `ui.notifications`.
.. autoclass:: Notifications
:members:
.. _templating:
HTML Templates and Handlebars
*****************************
HTML templating in Foundry Virtual Tabletop uses the very flexible and easy-to-use Handlebars.js as it's templating
engine. As a developer in the FVTT ecosystem, you will end up defining HTML templates which are included as part of your
System, Module, or World. For example, suppose you define the following HTML template and save this as the file named
``public/modules/mymodule/templates/hello.html``.
.. code-block:: html
<div>
<h3>My Name is {{name}}</h3>
<p>I am feeling {{mood}} to learn more about HTML templates in Foundry VTT.</p>
{{#unless knowEverything}}
<p>I have things to learn:</p>
<ol>
{{#each items}}
<li>{{this}}</li>
{{/each}}
</ol>
{{/unless}}
</div>
This HTML template can be loaded and evaluated against an object which provides the data used for rendering. You can
accomplish this yourself using the base ``Handlebars.compile`` function, but Foundry VTT provides an extra convenience
layer with the ``renderTemplate`` method which provides asynchronous template loading and client-side caching which
you are recommended to use.
.. autofunction:: renderTemplate
When using the rendering function, provide a data object which corresponds to the variables in your HTML template. For
example:
.. code-block:: javascript
// Specify the target template path
const templatePath = "public/modules/mymodule/templates/hello.html"
// Define the data provided to the Handlebars template
const templateData = {
name: "Edgar",
mood: "curious",
knowEverything: false,
items: ["How to define a template", "How to render that template using dynamic data"]
}
// Render the template to compile the HTML
renderTemplate(templatePath, templateData).then(html => {
// Do whatever you want with the returning HTML, for example - add it to the client DOM
document.body.appendChild(html);
})
There is a lot you can do inside Handlebars templates, and I encourage you to spend some time with the documentation
and examples for the Handlebars.js library (https://handlebarsjs.com/) in order to learn what is possible.
As you begin to frequently render structured HTML elements within the VTT, you will likely find yourself wanting more
structure to manage the application windows and data they contain. Once you understand the basics of manual template
rendering, a great next step is to learn about the convenience layer and abstraction provided by :ref:`application`
which allows you to define render-able HTML windows using a class pattern.
Core Template Helpers
=====================
Foundry Virtual Tabletop defines several built-in template helpers that provide commonly used utility functions. These
are listed below with example HTML template usage for each.
Selected Option in a Select Field
---------------------------------
When rendering a ``<select>`` element in an HTML template, you frequently want to specify which option is currently
selected. Use the ``{{#select variable}}`` block helper as a wrapper outside of the list of ``<option>`` elements to
designate the correct option as currently selected when rendering the template. This helper is commonly used with an
``{{#each}}`` block to render the dropdown list. Example usage:
.. code-block:: html
<select name="flavor">
{{#select flavor}}
{{#each flavors as |name label|}}
<option name="{{name}}">{{label}}</option>
{{/each}}
{{/select}}
</select>
Checkbox Field Checked State
----------------------------
Another common requirement when compiling a template for a ``<form>`` element is to designate whether any checkbox
elements of the type ``<input type="checkbox">`` are currently checked or not. Use the ``{{checked variable}}`` inline
helper to add the "checked" property or not depending on whether the value of ``variable`` is true. Example usage:
.. code-block:: html
<input type="checkbox" name="hasThing" {{checked hasThing}}/>
FilePicker UI
-------------
You can render a file-picker UI element by calling ``{{filePicker target=String type=String}`` with the required field
``target`` which provides the ``name`` of the ``<input>`` element which should be modified by the FilePicker UI and
``type`` which currently accepts either "image" or "audio" as a way to filter the set of files which are shown.
Example usage is:
.. code-block:: html
<input type="text" name="profilePath" title="Profile Image Path" value={{profile}} placeholder="File Path"/>
{{filePicker target="profilePath" type="image"}}
Rich Text Editor (TinyMCE)
--------------------------
Another commonly useful helper is to render a rich text editor field which allows you to use the TinyMCE editor for
more user-friendly text editing by calling the ``{editor target=key content=data button=true}}`` helper where the
``target`` argument accepts the key name of the data element which should be updated when text is modified, ``content``
specifies the current value of the text pre-loaded in the editor, and ``button`` controls whether the editor is activated
through a toggled button (if true) or is always active (if false). Example usage is:
.. code-block:: html
<div class="container">
{{editor content=data.biography.value target="data.biography.value" button=true}}
</div>
.. _canvas:
The Game Canvas
***************
The virtual tabletop environment in Foundry VTT is implemented using an HTML5 canvas.
The canvas itself is constructed using an ordered sequence of layers.
Understanding the canvas layers will be helpful when building within the application.
.. toctree::
:caption: Canvas Layers
:name: canvas-layers
:maxdepth: 1
canvas/background
canvas/grid
canvas/walls
canvas/tokens
.. _canvas-background:
The Background Layer
********************
The Background Layer is the bottom-most layer of the tabletop Canvas. The Background Layer is responsible for
rendering your underlying background image and defining the interactable area of the scene. By default,
the canvas uses an interactive area which is 1.5 times the dimensions of your background image (with a minimum
of 1000px.)
Mod developers may wish to interact with or manipulate this layer and can do so using the singleton instance of
the :class:`BackgroundLayer` class which is accessible from within the client as ``canvas.background``.
.. autoclass:: BackgroundLayer
:members:
.. _canvas-grid:
The Grid Layer
**************
The Grid Layer is positioned 2nd from bottom in the layers of the Canvas. The Grid Layer is responsible for
orienting and segmenting the game space into grid spaces. Currently only a square grid is supported but hex
grid support is flagged as a feature for work during Beta development.
The Grid provides convenience tools for measuring distance, restricting token movement, and providing guide
lines for anchoring wall segments or other canvas features.
Mod developers may wish to interact with or manipulate this layer and can do so using the singleton instance of
the :class:`GridLayer` class which is accessible from within the client as ``canvas.grid``.
.. autoclass:: GridLayer
:members:
.. _canvasTokens:
The Tokens Layer
****************
The Tokens Layer is the middle layer of the tabletop Canvas and it contains all the Sprites which represent
actors within the game space. Tokens are placed onto the Tokens Layer by dragging actors from the Actors
Directory (in the right sidebar) onto the canvas.
-----
The Token Layer
===============
All tokens which are rendered on the canvas are drawn as children of the :class:`TokenLayer`. The token layer may be
accessed globally as ``canvas.tokens`` and provides the following API.
.. autoclass:: TokenLayer
:members:
-----
The Token Object
================
As a mod developer, you may find yourselves wanting to interact with the tokens which are active within a
:class:`Scene` and are drawn within the :class:`TokenLayer`. The :class:`Token` class provides a rich API for
interacting with these tokens.
.. autoclass:: foundry.Token
:members:
.. _canvas-walls:
The Walls Layer
***************
The Grid Layer is positioned 2nd from bottom in the layers of the Canvas. The Grid Layer is responsible for
orienting and segmenting the game space into grid spaces. Currently only a square grid is supported but hex
grid support is flagged as a feature for work during Beta development.
The Grid provides convenience tools for measuring distance, restricting token movement, and providing guide
lines for anchoring wall segments or other canvas features.
Wall Configuration
==================
Walls are customized by the Game Master from within the application. To add or modify walls on the Walls
Layer activate the Wall Layer on the primary toolbar as a player with Game Master privileges. There are
four varietes of wall segments which can be placed into a scene:
Regular Walls
These walls block both movement and vision. They are rendered on the Walls Layer using an off-white color.
Invisible Walls
These walls block movement, but not vision. They are rendered on the Walls Layer using a light blue color.
Doors
These walls are able to be toggled between multiple states. Doors may be **closed**, **open**, or **locked**.
Closed (or locked) doors block both movement and vision, while open doors do not block either vision or
movement. Doors will be rendered as a small icon for player views which, if clicked, will open or close the
door provided it is not locked. Only Game-Master players have the ability to unlock doors. Open doors are
rendered in green while with closed doors in orange and locked doors in red.
Secrets
These walls work as doors, able to be toggled between **closed**, **open**, or **locked** states, however
unlike regular doors the icon for secret doors is not shown to players and these can only be toggled by the
Game Master. Secret doors are rendered in purple.
.. image:: /_static/images/walls-doors.jpg
In the above image (from the GM perspective), **Daulgrim** the Dwarf Ranger is exploring a small room. The white
lines around the exterior of the room are regular walls, the fountain is surrounded by invisible walls which
prevent the player from moving into the fountain area. There is a closed door to the right is not locked and
could be opened by the player.
Walls Layer API
===============
Mod developers may wish to interact with or manipulate this layer and can do so using the singleton instance of
the :class:`WallsLayer` class which is accessible from within the client as ``canvas.walls``.
.. autoclass:: WallsLayer
:members:
.. _diceAPI:
Dice Rolling API
****************
For mod developers, you may want to customize in-depth the behavior of dice rolling. You can interact directly with
the Roll API by creating instances of the :class:`Roll` class.
-----
The Roll Interface
==================
Most frequently when dispatching or executing dice rolls, you will want to use the :class:`Roll` API directly, which
handles the parsing of dice syntax, the evaluation of dynamic attributes and more.
.. autoclass:: Roll
:members:
-----
The Basic Die
=============
There may be cases where you want more fine-grained control over dice rolling. In such cases, you can also create
instances of the base :class:`Die` class directly.
.. autoclass:: Die
:members:
.. _entityAPI:
Game Entities API
*****************
Each Entity type in Foundry Virtual Tabletop extends the base :class:``Entity`` class. These implementations and related
functionality are detailed on the following pages.
.. toctree::
:caption: Entity API
:maxdepth: 2
entities/abstract
entities/user
entities/scene
entities/actor
entities/item
entities/playlist
entities/compendium
Database Operation Workflow
===========================
Entities are managed through a set of API methods which allow for create, update, and delete operations. These methods
follow a standardized workflow:
1. Client A dispatches a request by calling the entity manipulation method, for example ``Actor.create(actorData, options);``
2. A pre-creation hook ``preCreateActor`` is triggered which can allow modules or systems to modify the contents of ``actorData``
before it is dispatched to the server.
3. A server-side event handler processes the request and updates the database. Once the database write is successful, the
handler responds to the requesting client (A) with an "acknowledgement" indicating the request was completed. Furthermore,
the handler broadcasts the event to all other connected clients, informing other users that a change was made.
4. Updated data is received by all connected clients and for each client a post-update hook, in this case ``createActor`` is
triggered which allows modules or systems to take follow-up actions in response to the change.
The workflow diagram below illustrates this process for the example event of an Actor creation.
.. figure:: /_static/images/socket-workflow.svg
This diagram illustrates the socket event workflow for an Actor creation request
.. _entityClass:
Entity and Collection Abstractions
**********************************
All Entities in Foundry Virtual Tabletop are built to extend the Entity class pattern. Collections of same-typed
Entities each belong to a specific Collection instance. Neither of these abstract layers should be required for
direct usage by module developers, but are provided here for reference.
.. contents:: Page Contents
:depth: 1
:local:
:backlinks: top
------
The Entity Class
================
.. autoclass:: Entity
:members:
------
The Collection Class
====================
.. autoclass:: Collection
:members:
.. _actorAPI:
The Actor Entity
****************
For application developers there are three important layers which are useful when working with Actors. The
:class:`Actors` collection manages the set of actor entities which are present within the world. Each individual actor
within that collection is an instance of the :class:`Actor` class (by default). Game systems which want more control
over the behaviors and attributes of an actor may override this to a subclass included in their own definition.
When viewing or interacting with an actor inside the tabletop framework, the actor's data is rendered and edited using
the :class:`ActorSheet` class (by default). Game systems which want to fine-tune how the actor data is rendered may
override this to a subclass included in their own definition.
.. contents:: Actors API Components
:depth: 1
:local:
:backlinks: top
------
The Actor Class
===============
.. autoclass:: foundry.Actor
:members:
------
The Actors Collection
=====================
.. autoclass:: Actors
:members:
------
The Actor Sheet
===============
.. autoclass:: ActorSheet
:members:
.. _compendiumAPI:
Compendium Content Packs
************************
Module developers can interact with compendum packs in a programmatic way using the API offered by the
:class:`Compendium` class.
-----
The Compendium Pack Class
=========================
.. autoclass:: Compendium
:members:
.._itemAPI:
The Item Entity
***************
Item entities represent objects or features that are owned by an Actor. While the term item tends to imply physical
possessions, as a developer in Foundry Virtual Tabletop you should consider Items as the building block for anything
that can be owned by an Actor. For example, in the D&D5e system, Item types are used for Classes, Spells, and Feats
in addition to standard inventory and equipment.
The FVTT framework provides core APIs for manipulating and modifying Items including support to allow Items to belong
to an Actor to modify the Actor's owned version of that Item.
There are several important API layers which are useful when working with Items. The :class:`Items` collection has
all of the :class:`Item` instances which are defined at the World level (as oppoosed to owned items which belong to
a specific actor). This Items collection is available under ``game.items``.
The :class:`Item` class represents a single item which may be unowned (and defined at the World level) or owned (and
defined at the Actor level). Owned items which belong to an :class:`Actor` are defined in that actor's data model
under ``actor.data.items``. The :class:`Item` class may be overridden by a system or module by defining the
``Config.Item.entityClass`` global configuration value.
When viewing or interacting with an item's data, the item is rendered and edited using the :class:`ItemSheet` class
which can be extended or overridden by systems or modules. To override the default implementation, a mod should
define the ``CONFIG.Item.sheetClass`` global configuration value.
.. contents:: Items API Components
:depth: 1
:local:
:backlinks: top
----
The Item Class
==============
.. autoclass:: foundry.Item
:members:
----
The Items Collection
====================
.. autoclass:: Items
:members:
----
The Item Sheet
==============
.. autoclass:: ItemSheet
:members:
.. _playlistAPI:
The Audio Playlist Entity
*************************
Audio in Foundry VTT provides a key layer to improve immersion and enrich gameplay. The core software provides APIs
for audio effects which are triggered programmatically as well as audio Playlists which are user-defined Entities.
Overall audio management is controlled by the :class:`Playlists` collection while the :class:`Playlist` class implements
the individual playlist entity.
----
The Audio Collection
====================
.. autoclass:: Playlists