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.


The Entity Class

class Entity(data)

An abstract class pattern for all primary data entities within the Foundry VTT Framework An entity represents a primary data concept, for example: Actor, Item, Scene, or ChatMessage. Employing this abstraction layer ensures similar behavior and workflow for all entity types.

Documentation for this class is provided for reference, but developers should not extend this class directly, instead work with or extend the Entity implementations that are referenced in this section of the API documentation.

Entities are instantiated by providing their base data, and an optional Array of Application instances which should be automatically refreshed when the Entity experiences an update.

Arguments:
  • data (Object) – The data Object with which to create the Entity

Examples:

let actorData = {name: "John Doe", type: "character", img: "icons/mystery-man.png"};
let actor = new Actor(actorData);
Entity.collection

type: Collection

Return a reference to the Collection class which stores Entity instances of this type. This property should be overridden by child class implementations.

Entity.collection

type: Collection

Return a reference to the Collection class which stores Entity instances of this type. This property simply references the static class property for convenience.

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(options)

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

Arguments:
  • options (Object) – Additional options which customize the deletion workflow
Returns:

Promise – A Promise which resolves to the ID of the deleted Entity once handled by the server

Entity.entity

type: Entity

The parent class name of the base entity type. For subclass Entities, this will examine the inheritance chain and return the base type.

Examples:

class Actor2ndGen extends Actor {
  // ...
}
Actor2ndGen.entity    // Actor
Entity.entity

type: Entity

A instance-level convenience accessor for the class-level entity property

Entity.exportToJSON()

Export entity data to a JSON file which can be saved by the client and later imported into a different session

Entity.folder

type: Folder|null

Return a reference to the Folder which this Entity belongs to, if any

Entity.getEmbeddedEntity(collection, id)

Get an Embedded Entity by it’s ID from a named collection in the parent

Arguments:
  • collection (string) – The named collection of embedded entities
  • id (number) – The numeric ID of the child to retrieve
Returns:

*|null – Retrieved data for the requested child, or null

Entity.getFlag(scope, key)

Get the value of a “flag” for this Entity See the setFlag method for more details on flags

Arguments:
  • scope (String) – The flag scope which namespaces the key
  • key (String) – The flag key
Returns:

* – The flag value

Entity.hasPerm(user, permission, exact=false)

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
  • exact (Boolean) – Tests for an exact permission level match, by default this method tests for an equal or greater permission level.
Returns:

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

Entity.id

type: String

A convenience accessor for the _id attribute of the Entity data object

Entity.importFromJSON(json)

Import data and update this entity

Arguments:
  • json (String) – JSON data string
Returns:

Promise.<Entity> – The updated Entity

Entity.importFromJSONDialog()

Render an import dialog for updating the data related to this Entity through an exported JSON file

Returns:Promise.<void>
Entity.limited

A boolean indicator for whether the current game user has ONLY limited visibility for this Entity.

Entity.name

type: String

A convenience accessor for the name attribute of the Entity data object

Entity.permission

type: Number

Return the permission level that the current game User has over this Entity. See the CONST.ENTITY_PERMISSIONS object for an enumeration of these levels.

Entity.prepareData()

Prepare data for the Entity whenever the instance is first created or later updated. This method can be used to derive any internal attributes which are computed in a formulaic manner. For example, in a d20 system - computing an ability modifier based on the value of that ability score.

Entity.render(...args)

Render all of the applications which are connected to this Entity

Arguments:
  • args (*) – Variable arguments which are forwarded to each Application.render() call
Entity.setFlag(scope, key, value)

Assign a “flag” to this Entity. Flags represent key-value type data which can be used to store flexible or arbitrary data required by either the core software, game systems, or user-created modules.

Each flag should be set using a scope which provides a namespace for the flag to help prevent collisions.

Flags set by the core software use the “core” scope. Flags set by game systems or modules should use the canonical name attribute for the module Flags set by an individual world should “world” as the scope.

Flag values can assume almost any data type. Setting a flag value to null will delete that flag.

Arguments:
  • scope (String) – The flag scope which namespaces the key
  • key (String) – The flag key
  • value (*) – The flag value
Returns:

Promise.<Entity> – A Promise resolving to the updated 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.

Examples:

let actor = game.entities.actors[0];
actor.sheet      // ActorSheet
Entity.sortRelative()

Sort this Entity relative a target by providing the target, an Array of siblings and other options. See SortingHelper.performIntegerSort for more details

Entity.unsetFlag(scope, key)

Remove a flag assigned to the Entity

Arguments:
  • scope (string) – The flag scope which namespaces the key
  • key (string) – The flag key
Returns:

Promise – A Promise resolving to the updated Entity

Entity.update(data, options)

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
  • options (Object) – Additional options which customize the update workflow
  • options.diff (Boolean) – Diff the provided data against existing entity data, only submitting the difference to the server. Default is true.
Returns:

Promise – A Promise which resolves to the updated Entity

Entity.visible

A boolean indicator for whether or not the current game User has at least limited visibility for this Entity.


The Collection 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.directory

Return a reference to the SidebarDirectory application for this Collection

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.importFromCollection(collection, entryId, updateData)

Import an Entity from a compendium collection, adding it to the current World

Arguments:
  • collection (String) – The name of the pack from which to import
  • entryId (String) – The ID of the compendium entry to import
  • updateData (Object) – Data used to update the imported Entity before it is created in the World
Returns:

Promise – A Promise containing the imported Entity

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(args)

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