Game Entities API

Each Entity type in Foundry Virtual Tabletop extends the base Entity() class. These implementations and related functionality are detailed on the following pages.


The Entity Abstract Class

class Entity(data, collection, apps)

A class pattern for all primary data entities within the Foundry VTT Framework

Arguments:
  • data (Object) –
    The data Object with which to create the Entity
  • collection (Collection) –
    An Array or Collection instance to which the Entity belongs
  • apps (Array) –
    An Array of Application instances which the Entity modifies
Entity.collection

Return a reference to the Collection class which stores Entity instances of this type.

Entity.create(data, options)

Create a new entity using provided input data The data for entity creation is typically provided from the server through the ‘create<Entity>’ socket Alternatively, the creation event may originate locally and the new entity can be pushed back to the server

Arguments:
  • data (Object) – The data with which to create the entity
  • options (Object) – Additional options which customize the creation workflow
  • options.temporary (Boolean) – Create a temporary entity which is not saved to the world database. Default is false.
  • options.displaySheet (Boolean) – Show the configuration sheet for the created entity once it is created. Default is true.
Returns:

Promise – A Promise which resolves to contain the created Entity

Entity.delete()

Delete the entity, removing it from its collection and deleting its data record

Returns:Promise – A Promise which resolves to the ID of the deleted Entity once handled by the server
Entity.entity

Get the parent class in the inheritance chain that extends Entity directly. This is the base entity type.

Entity.hasPerm(user, permission)

Test whether a provided User has ownership permission over the Entity instance

Arguments:
  • user (User) – The user to test for permission
  • permission (Number) – The permission level to test
Returns:

Boolean – Whether or not the user has the permission for this Entity

Entity.permission

Get the current user’s permission level

Entity.render()

Render all of the applications which are connected to this Entity

Entity.sheet

type: BaseEntitySheet

A property which gets or creates a singleton instance of the sheet class used to render and edit data for this particular entity type.

Entity.update(data)

Update the current entity using new data This new data is typically provided from the server through the ‘update<Entity>’ socket Alternatively, the update may originate locally, in which case it can be pushed back to the server

Arguments:
  • data (Object) – The data with which to update the entity
Returns:

Promise – A Promise which resolves to the updated Entity


The Collection Abstract Class

class Collection(data, apps)

A class pattern for collections of Entity objects within the Foundry VTT Framework

Arguments:
  • data (Object) – An Array of Entity data from which to create instances
  • apps (Array) – An Array of Application instances which the Collection modifies
Collection.apps

type: Array

An Array of application references which will be automatically updated when the collection content changes

Collection.create(data, options)

Create a new entity using provided input data The data for entity creation is provided from the server through the create<Entity> socket

Arguments:
  • data (Object) – The data with which to create the entity
  • options (Object) – Additional options which customize the creation workflow
  • options.temporary (Boolean) – Create a temporary entity which is not saved to the world database. Default is false.
  • options.displaySheet (Boolean) – Show the configuration sheet for the created entity once it is created. Default is true.
Returns:

Entity – The created Entity instance

Collection.delete(entityId)

Delete an existing Entity from this Collection using its ID

Arguments:
  • entityId (String) – The entity ID which should be locally deleted
Returns:

String – The ID of the entity which was successfully deleted

Collection.entities

type: Array

An Array of all the Entity instances of this type which are contained within the collection

Collection.entity

type: String

Return the base Entity name which this collection manages.

This should always be the primitive name of the entity type, not the name of a specific subclass implementation For example “Actor”, not “Actor5e”

Collection.get(id)

Get an element from the collection by ID

Arguments:
  • id (String) – The entity ID to retrieve from the collection
Returns:

Entity – The retrieved Entity, if the ID was found, otherwise null;

Collection.index(id)

Retrieve the index of an entity within the collection by its ID

Arguments:
  • id (String) – The entity ID to retrieve from the collection
Returns:

Number – The index of the Entity within the collection, if found, otherwise -1;

Collection.insert(entity)

Add a new Entity to the Collection, asserting that they are of the correct type

Arguments:
  • entity (Entity) – The entity instance to add to the collection
Collection.instance

type: Collection

Return a reference to the singleton instance of this Collection By default, a Collection is located in game[Collection.name], for example game.actors

Collection.name

type: String

The Collection name

Collection.object

type: Entity

Return a reference to the Entity subclass which should be used when creating elements of this Collection

This should always be an explicit reference to the class which is used in this game to represent the entity, and not the base implementation of that entity type. For example Actor5e() not Actor()

Collection.remove(id)

Remove an Entity from the Collection by its ID.

Arguments:
  • id (String) – The entity ID which should be removed
Collection.render()

Re-render any currently visible applications associated with this Collection

Collection.socketListeners(socket)

Activate socket listeners related to this particular Entity type

Arguments:
  • socket (Socket) – The open game socket
Collection.source

type: Object

A reference to the original source data provided by the server

Collection.update(data)

Update an existing Entity within the Collection using provided update data The data used to update an entity is provided through the update<Entity> socket

Arguments:
  • data (Object) – The data with which to update the entity
Returns:

Entity – The updated Entity instance