Entity

Entity

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. Each Entity type in Foundry Virtual Tabletop extends this base Entity class which ensures similar behavior and workflow across 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.

Constructor

(abstract) new Entity(data, options)

Source:
See:
Example
let actorData = {name: "John Doe", type: "character", img: "icons/mystery-man.png"};
let actor = new Actor(actorData);
Parameters:
Name Type Description
data Object

The data Object with which to create the Entity
options Object

Additional options which modify the created Entity behavior

Properties
Name Type Attributes Description
compendium Compendium <optional>

A reference to the Compendium pack from which this Entity was drawn.

Members

(static) collection :EntityCollection

Source:

Return a reference to the EntityCollection instance which stores Entity instances of this type. This property is available as both a static and instance method and should be overridden by subclass Entity implementations.

Type:

(static) config :Object

Source:
Properties:
Name Type Description
baseEntity Entity

The parent class which directly inherits from the Entity interface.
collection EntityCollection

The EntityCollection instance to which Entities of this type belong.
embeddedEntities Array

The names of any Embedded Entities within the Entity data structure.

Configure the attributes of this Entity class

Type:
  • Object

(static) entity :string

Source:

The class name of the base Entity type, for example "Actor". This is useful in cases where there is an inheritance chain. Many places throughout the framework rely upon the canonical entity name which may not always be equal to the class name. This property is available as both a static and instance method.

Type:
  • string
Example
class Actor2ndGen extends Actor {...}
Actor2ndGen.entity // "Actor"

apps :Object.<Application>

Source:
See:

A collection of Application instances which should be re-rendered whenever this Entity experiences an update to its data. The keys of this object are the application ids and the values are Application instances. Each Application in this object will have its render method called by Entity#render.

Type:

compendium :Compendium|null

Source:

The Entity may optionally belong to a parent Compendium pack. If so this attribute will contain a reference to that Compendium object. Otherwise null.

Type:

data :Object

Source:

The original source data for the object provided at initialization.

Type:
  • Object

folder :Folder|null

Source:

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

Type:
Example

Entities may belong to Folders

let folder = game.folders.entities[0];
let actor = await Actor.create({name: "New Actor", folder: folder.id});
console.log(actor.data.folder); // folder.id;
console.log(actor.folder); // folder;

id :string

Source:

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

Type:
  • string

limited :boolean

Source:

A boolean indicator for whether the current game user has ONLY limited visibility for this Entity. Note that a GM user's perspective of an Entity is never limited.

Type:
  • boolean

name :string

Source:

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

Type:
  • string

options :Object

Source:

The options object that was used to configure the Entity upon initialization.

Type:
  • Object

owner :boolean

Source:

A boolean indicator for whether or not the current game User has ownership rights for this Entity. This property has a setter which allows for ownership rights to be temporarily overridden on a per-instance basis.

Type:
  • boolean

permission :Number

Source:

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.

Type:
Example
game.user.id; // "dkasjkkj23kjf"
entity.data.permission; // {default: 1, "dkasjkkj23kjf": 2};
entity.permission; // 2

sheet :BaseEntitySheet

Source:

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

Type:
Example

A subclass of the Actor entity

let actor = game.entities.actors[0];
actor.sheet; // ActorSheet

uuid :string

Source:

A Universally Unique Identifier (uuid) for this Entity instance

Type:
  • string

visible :boolean

Source:

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

Type:
  • boolean

Methods

(static) activateSocketListeners(socket)

Source:

Activate the Socket event listeners used to receive responses from events which modify database documents

Parameters:
Name Type Description
socket Socket

The active game socket

(static) can(user, action, target) → {boolean}

Source:

Test whether a given User has permission to perform some action on this Entity

Parameters:
Name Type Description
user User

The User requesting creation
action string

The attempted action
target Entity

The targeted Entity
Returns:

Does the User have permission?

Type
boolean

(static) can()

Source:

Test whether a given User has permission to perform some action on this Entity

(async, static) create(data, options) → {Promise.<(Entity|Array.<Entity>)>}

Source:

Create one or multiple new entities using provided input data. Data may be provided as a single object to create one Entity, or as an Array of Objects. Entities may be temporary (unsaved to the database) by passing the temporary option as true.

Examples
const data = {name: "New Entity", type: "character", img: "path/to/profile.jpg"};
const created = await Entity.create(data); // Returns one Entity, saved to the database
const temp = await Entity.create(data, {temporary: true}); // Not saved to the database
const data = [{name: "Tim", type: "npc"], [{name: "Tom", type: "npc"}];
const created = await Entity.create(data); // Returns an Array of Entities, saved to the database
const created = await Entity.create(data, {temporary: true}); // Not saved to the database
Parameters:
Name Type Description
data Data | Array.<Data>

A Data object or array of Data
options Options

Additional options which customize the creation workflow

Properties
Name Type Attributes Description
temporary boolean <optional>

Create a temporary entity which is not saved to the world database. Default is false.
renderSheet boolean <optional>

Display the sheet for the created entity once it is created. Default is false.
Returns:

The created Entity or array of Entities

Type
Promise.<(Entity|Array.<Entity>)>

(async, static) delete(data, options) → {Promise.<(Entity|Array.<Entity>)>}

Source:

Delete one or multiple existing entities using provided ids. The target ids may be a single string or an Array of strings.

Examples
const id = "12ekjf43kj2312ds";
const deleted = await Entity.delete(id); // A single deleted entity from the database
const ids = ["12ekjf43kj2312ds", "kj549dk48k34jk34"];
const deleted = await Entity.delete(ids); // Returns an Array of deleted Entities
Parameters:
Name Type Description
data string | Array.<string>

A single id or Array of ids
options Options

Additional options which customize the deletion workflow
Returns:

The deleted Entity or array of Entities

Type
Promise.<(Entity|Array.<Entity>)>

(async, static) update(data, options) → {Promise.<(Entity|Array.<Entity>)>}

Source:

Update one or multiple existing entities using provided input data. Data may be provided as a single object to update one Entity, or as an Array of Objects.

Examples
const data = {_id: "12ekjf43kj2312ds", name: "New Name"}};
const updated = await Entity.update(data); // Updated entity saved to the database
const data = [{_id: "12ekjf43kj2312ds", name: "New Name 1"}, {_id: "kj549dk48k34jk34", name: "New Name 2"}]};
const updated = await Entity.update(data); // Returns an Array of Entities, updated in the database
Parameters:
Name Type Description
data Data | Array.<Data>

A Data object or array of Data. Each element must contain the _id of an existing Entity.
options Options

Additional options which customize the update workflow

Properties
Name Type Attributes Description
diff boolean <optional>

Difference the provided data against the current to eliminate unnecessary changes.
Returns:

The updated Entity or array of Entities

Type
Promise.<(Entity|Array.<Entity>)>

(async) clone(createData, options) → {Promise.<Entity>}

Source:

Clone an Entity, creating a new Entity using the current data as well as provided creation overrides.

Parameters:
Name Type Description
createData Object

Additional data which overrides current Entity data at the time of creation
options Object

Additional creation options passed to the Entity.create method
Returns:

A Promise which resolves to the created clone Entity

Type
Promise.<Entity>

(async) createEmbeddedEntity(embeddedName, data, options) → {Promise.<(Data|Array.<Data>)>}

Source:

Create one or multiple EmbeddedEntities within this parent Entity. Data may be provided as a single Object to create one EmbeddedEntity or as an Array of Objects to create many. Entities may be temporary (unsaved to the database) by passing the temporary option as true.

Examples
const actor = game.actors.get("dfv934kj23lk6h9k");
const data = {name: "Magic Sword", type: "weapon", img: "path/to/icon.png"};
const created = await actor.createEmbeddedEntity("OwnedItem", data); // Returns one EmbeddedEntity, saved to the Actor
const temp = await actor.createEmbeddedEntity("OwnedItem", data, {temporary: true}); // Not saved to the Actor
const actor = game.actors.get("dfv934kj23lk6h9k");
const data = [{name: "Mace of Crushing", type: "weapon"}, {name: "Shield of Defense", type: "armor"}];
const created = await actor.createEmbeddedEntity("OwnedItem", data); // Returns an Array of EmbeddedEntities, saved to the Actor
const temp = await actor.createEmbeddedEntity("OwnedItem", data, {temporary: true}); // Not saved to the Actor
Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to create
data Data | Array.<Data>

A Data object or an Array of Data objects to create
options Options

Additional creation options which modify the request

Properties
Name Type Attributes Description
temporary boolean <optional>

Create a temporary entity which is not saved to the world database. Default is false.
renderSheet boolean <optional>

Display the sheet for each created Embedded Entities once created.
Returns:

A Promise which resolves to the created embedded Data once the creation request is successful

Type
Promise.<(Data|Array.<Data>)>

(async) delete(options) → {Promise.<Entity>}

Source:
See:

Delete the current Entity.

Parameters:
Name Type Description
options Options

Options which customize the deletion workflow
Returns:

The deleted Entity

Type
Promise.<Entity>

(async) deleteEmbeddedEntity(embeddedName, data, options) → {Promise.<(Data|Array.<Data>)>}

Source:

Delete one or multiple existing EmbeddedEntity objects using provided input data. Data may be provided as a single id to delete one object or as an Array of string ids.

Examples
const actor = game.actors.get("dfv934kj23lk6h9k");
const item = actor.data.items.find(i => i.name === "Magic Sword");
const deleted = await actor.deleteEmbeddedEntity("OwnedItem", item._id); // Deletes one EmbeddedEntity
const actor = game.actors.get("dfv934kj23lk6h9k");
const weapons = actor.data.items.filter(i => i.type === "weapon");
const deletions = weapons.map(i => i._id);
const updated = await actor.deleteEmbeddedEntity("OwnedItem", deletions); // Deletes multiple EmbeddedEntity objects
Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to create
data string | Array.<string>

A Data object or array of Data. Each element must contain the _id of an existing Entity.
options Options

Additional options which customize the update workflow
Returns:

The deleted Embedded Entities

Type
Promise.<(Data|Array.<Data>)>

exportToJSON()

Source:

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

getEmbeddedCollection(embeddedName) → {Array}

Source:

Obtain a reference to the Array of source data within the data object for a certain Embedded Entity name

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity type
Returns:

The Array of source data where Embedded Entities of this type are stored

Type
Array

getEmbeddedEntity(embeddedName, id, strict) → {Object|null}

Source:

Get an Embedded Entity by it's id from a named collection in the parent Entity.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity type to retrieve
id string

The numeric ID of the child to retrieve
strict boolean

Throw an Error if the requested id does not exist, otherwise return null. Default false.
Returns:

Retrieved data for the requested child, or null

Type
Object | null

getFlag(scope, key) → {*}

Source:

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

Parameters:
Name Type Description
scope String

The flag scope which namespaces the key
key String

The flag key
Returns:

The flag value

Type
*

hasPerm(user, permission, exact) → {boolean}

Source:

Test whether a provided User a specific permission level (or greater) over the Entity instance

Example

Test whether a specific user has a certain permission

// These two are equivalent
entity.hasPerm(game.user, "OWNER");
entity.owner;
// These two are also equivalent
entity.hasPerm(game.user, "LIMITED", true);
entity.limited;
Parameters:
Name Type Default Description
user User

The user to test for permission
permission string | number

The permission level or level name to test
exact boolean false

Tests for an exact permission level match, by default this method tests for an equal or greater permission level.
Returns:

Whether or not the user has the permission for this Entity.

Type
boolean

(async) importFromJSON(json) → {Promise.<Entity>}

Source:

Import data and update this entity

Parameters:
Name Type Description
json String

JSON data string
Returns:

The updated Entity

Type
Promise.<Entity>

(async) importFromJSONDialog() → {Promise.<void>}

Source:

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

Returns:
Type
Promise.<void>

initialize()

Source:

Initialize data structure for the Entity. First initialize any Embedded Entities and prepare their data. Next prepare data for the Entity itself, which may depend on Embedded Entities.

prepareData()

Source:

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.

prepareEmbeddedEntities()

Source:

Prepare Embedded Entities which exist within this parent Entity. For example, in the case of an Actor, this method is responsible for preparing the Owned Items the Actor contains.

render(force, context)

Source:

Render all of the Application instances which are connected to this Entity by calling their respective Application#render methods.

Parameters:
Name Type Description
force boolean

Force rendering
context Options

Optional context

(async) setFlag(scope, key, value) → {Promise.<Entity>}

Source:

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.

Parameters:
Name Type Description
scope String

The flag scope which namespaces the key
key String

The flag key
value *

The flag value
Returns:

A Promise resolving to the updated Entity

Type
Promise.<Entity>

(async) sortRelative()

Source:

Sort this Entity relative a target by providing the target, an Array of siblings and other options. If the Entity has an rendered sheet, record the sort change as part of a form submission See SortingHelper.performIntegerSort for more details

(async) toCompendium() → {Object}

Source:

Transform the Entity data to be stored in a Compendium pack. Remove any features of the data which are world-specific. This function is asynchronous in case any complex operations are required prior to exporting.

Returns:

A data object of cleaned data ready for compendium import

Type
Object

toJSON() → {Object}

Source:

Serializing an Entity should simply serialize it's inner data, not the entire instance

Returns:
Type
Object

(async) unsetFlag(scope, key) → {Promise}

Source:

Remove a flag assigned to the Entity

Parameters:
Name Type Description
scope string

The flag scope which namespaces the key
key string

The flag key
Returns:

A Promise resolving to the updated Entity

Type
Promise

(async) update(data, options) → {Promise.<Entity>}

Source:
See:

Update the current Entity using provided input data. Data must be provided as a single object which updates the Entity data.

Parameters:
Name Type Description
data Data

A Data object which updates the Entity
options Options

Additional options which customize the update workflow
Returns:

The updated Entity

Type
Promise.<Entity>

(async) updateEmbeddedEntity(embeddedName, data, options) → {Promise.<(Entity|Array.<Entity>)>}

Source:

Update one or multiple existing entities using provided input data. Data may be provided as a single object to update one Entity, or as an Array of Objects.

Examples
const actor = game.actors.get("dfv934kj23lk6h9k");
const item = actor.data.items.find(i => i.name === "Magic Sword");
const update = {_id: item._id, name: "Magic Sword +1"};
const updated = await actor.updateEmbeddedEntity("OwnedItem", update); // Updates one EmbeddedEntity
const actor = game.actors.get("dfv934kj23lk6h9k");
const weapons = actor.data.items.filter(i => i.type === "weapon");
const updates = weapons.map(i => {
  return {_id: i._id, name: i.name + "+1"};
}
const updated = await actor.createEmbeddedEntity("OwnedItem", updates); // Updates multiple EmbeddedEntity objects
Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to create
data Data | Array.<Data>

A Data object or array of Data. Each element must contain the _id of an existing Entity.
options Options

Additional options which customize the update workflow

Properties
Name Type Attributes Description
diff boolean <optional>

Difference the provided data against the current to eliminate unnecessary changes.
Returns:

The updated Entity or array of Entities

Type
Promise.<(Entity|Array.<Entity>)>