Actor

Actor

The Actor Entity which represents the protagonists, characters, enemies, and more that inhabit and take actions within the World.

Constructor

new Actor()

Source:
See:
  • Actors Each Actor belongs to the Actors collection.
  • ActorSheet Each Actor is edited using the ActorSheet application or a subclass thereof.
  • ActorDirectory All Actors which exist in the world are rendered within the ActorDirectory sidebar tab.
Examples

Create a new Actor

let actor = await Actor.create({
  name: "New Test Actor",
  type: "character",
  img: "artwork/character-profile.jpg",
  folder: folder.data._id,
  sort: 12000,
  data: {},
  token: {},
  items: [],
  flags: {}
});

Retrieve an existing Actor

let actor = game.actors.get(actorId);

Extends

Members

(static) config

Source:

apps :Object.<Application>

Source:
Overrides:
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:
Overrides:

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:
Overrides:

The original source data for the object provided at initialization.

Type:
  • Object

folder :Folder|null

Source:
Overrides:

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:
Overrides:

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

Type:
  • string

img :string

Source:

A convenient reference to the file path of the Actor's profile image

Type:
  • string

isPC :boolean

Source:

A boolean flag for whether this Actor is a player-owned character. True if any User who is not a GM has ownership rights over the Actor entity.

Type:
  • boolean

isToken :boolean

Source:

Test whether an Actor entity is a synthetic representation of a Token (if true) or a full Entity (if false)

Type:
  • boolean

items :Array.<Item>

Source:

Construct the Array of Item instances for the Actor Items are prepared by the Actor.prepareEmbeddedEntities() method

Type:

limited :boolean

Source:
Overrides:

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:
Overrides:

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

Type:
  • string

options :Object

Source:
Overrides:

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

Type:
  • Object

owner :boolean

Source:
Overrides:

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:
Overrides:

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:
Overrides:

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

token :Token

Source:

A reference to a placed Token which creates a synthetic Actor

Type:

uuid :string

Source:
Overrides:

A Universally Unique Identifier (uuid) for this Entity instance

Type:
  • string

visible :boolean

Source:
Overrides:

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

Type:
  • boolean

Methods

(static) createTokenActor(baseActor, token) → {Actor}

Source:

Create a synthetic Token Actor instance which is used in place of an actual Actor. Cache the result in Actors.tokens.

Parameters:
Name Type Description
baseActor Actor
token Token
Returns:
Type
Actor

(static) fromToken(token) → {Actor}

Source:

Create a synthetic Actor using a provided Token instance If the Token data is linked, return the true Actor entity If the Token data is not linked, create a synthetic Actor using the Token's actorData override

Parameters:
Name Type Description
token Token
Returns:
Type
Actor

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

Source:
Overrides:

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, createData, options) → {Promise}

Source:
Overrides:

Create one EmbeddedEntity within this parent Entity. Dispatch the creation request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to create
createData Object

An object of initial data from which to create the Embedded Entity
options Object

Additional creation options which modify the request
Returns:

A Promise which resolves to this Entity once the creation request is successful

Type
Promise

(async) createManyEmbeddedEntities(embeddedName, createData, options) → {Promise}

Source:
Overrides:

Create multiple Embedded Entities within this parent Entity using an Array of creation data. Dispatch the update request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to update
createData Array

An Array of initial data objects from which to create the Embedded Entities.
options Object

Additional update options which modify the request
Returns:

A Promise which resolves to this Entity once the creation request is successful

Type
Promise

(async) createOwnedItem(itemData, options) → {Promise.<Object>}

Source:
See:

Create a new item owned by this Actor. This redirects its arguments to the createEmbeddedEntity method.

Parameters:
Name Type Description
itemData Object

Data for the newly owned item
options Object

Item creation options

Properties
Name Type Description
renderSheet boolean

Render the Item sheet for the newly created item data
Returns:

A Promise resolving to the created Owned Item data

Type
Promise.<Object>

(async) delete(options) → {Promise}

Source:
Overrides:

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

Example
const deleted = await entity.delete();
Parameters:
Name Type Description
options Object

Additional options which customize the deletion workflow
Returns:

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

Type
Promise

(async) deleteEmbeddedEntity(embeddedName, childId, options) → {Promise}

Source:
Overrides:

Delete one EmbeddedEntity within this parent Entity. Dispatch the deletion request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to delete
childId string

The id of the existing Embedded Entity child to delete
options Object

Additional deletion options which modify the request
Returns:

A Promise which resolves to this Entity once the deletion request is successful

Type
Promise

(async) deleteManyEmbeddedEntities(embeddedName, deleteIds, options) → {Promise}

Source:
Overrides:

Delete multiple Embedded Entities within this parent Entity by an Array of child ids. Dispatch the update request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to update
deleteIds Array

An Array of Embedded Entity ids to delete from the parent Entity
options Object

Additional update options which modify the request
Returns:

A Promise which resolves to this Entity once the update request is successful

Type
Promise

(async) deleteOwnedItem(itemId, options) → {Promise.<Object>}

Source:
See:

Delete an owned item by its id. This redirects its arguments to the deleteEmbeddedEntity method.

Parameters:
Name Type Description
itemId string

The ID of the item to delete
options Object

Item deletion options
Returns:

A Promise resolving to the deleted Owned Item data

Type
Promise.<Object>

exportToJSON()

Source:
Overrides:

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

getActiveTokens(linkedopt) → {Array}

Source:

Retrieve an Array of active tokens which represent this Actor in the current canvas Scene. If the canvas is not currently active, or there are no linked actors, the returned Array will be empty.

Parameters:
Name Type Attributes Default Description
linked Boolean <optional>
 false

Only return tokens which are linked to the Actor. Default (false) is to return all tokens even those which are not linked.
Returns:

An array of tokens in the current Scene which reference this Actor.

Type
Array

getEmbeddedCollection(embeddedName) → {Array}

Source:
Overrides:

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:
Overrides:

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:
Overrides:

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
*

getOwnedItem(itemId) → {Item}

Source:

Get an Item instance corresponding to the Owned Item with a given id

Parameters:
Name Type Description
itemId string

The OwnedItem id to retrieve
Returns:

An Item instance representing the Owned Item within the Actor entity

Type
Item

getRollData() → {Object}

Source:

Prepare a data object which defines the data schema used by dice roll commands against this Actor

Returns:
Type
Object

(async) getTokenImages() → {Promise}

Source:

Get an Array of Token images which could represent this Actor

Returns:
Type
Promise

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

Source:
Overrides:

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:
Overrides:

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:
Overrides:

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

Returns:
Type
Promise.<void>

importItemFromCollection(collection, entryId)

Source:

Import a new owned Item from a compendium collection The imported Item is then added to the Actor as an owned item.

Parameters:
Name Type Description
collection String

The name of the pack from which to import
entryId String

The ID of the compendium entry to import

initialize()

Source:
Overrides:

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.

(async) modifyTokenAttribute(attribute, value, isDelta, isBar) → {Promise}

Source:

Handle how changes to a Token attribute bar are applied to the Actor. This allows for game systems to override this behavior and deploy special logic.

Parameters:
Name Type Default Description
attribute string

The attribute path
value number

The target attribute value
isDelta boolean false

Whether the number represents a relative change (true) or an absolute change (false)
isBar boolean true

Whether the new value is part of an attribute bar, or just a direct value
Returns:
Type
Promise

prepareData()

Source:
Overrides:

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:
Overrides:

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.

removeEmbeddedEntity(embeddedName, id) → {Object|null}

Source:
Overrides:

Remove an Embedded Entity from the parent Entity data by it's id.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity type to retrieve
id number

The numeric ID of the child to retrieve
Returns:

The embedded entity data that was removed

Type
Object | null

render(…args)

Source:
Overrides:

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

Parameters:
Name Type Attributes Description
args * <repeatable>

Variable arguments which are forwarded to each Application's render call

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

Source:
Overrides:

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:
Overrides:

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

toJSON() → {Object}

Source:
Overrides:

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

Returns:
Type
Object

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

Source:
Overrides:

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}

Source:
Overrides:

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

Example
const updateData = {name: "New Name"};
const updated = await entity.update(updateData);
Parameters:
Name Type Description
data Object

The data with which to update the entity
options Object

Additional options which customize the update workflow

Properties
Name Type Description
diff Boolean

Diff the provided data against existing entity data, only submitting the difference to the server. Default is true.
Returns:

A Promise which resolves to the updated Entity

Type
Promise

(async) updateEmbeddedEntity(embeddedName, updateData, options) → {Promise}

Source:
Overrides:

Update one EmbeddedEntity within this parent Entity using incremental data. Dispatch the update request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to update
updateData Object

An object of incremental data from which to update the Embedded Entity
options Object

Additional update options which modify the request
Returns:

A Promise which resolves to this Entity once the update request is successful

Type
Promise

(async) updateManyEmbeddedEntities(embeddedName, updateData, options) → {Promise}

Source:
Overrides:

Update multiple Embedded Entities within this parent Entity using incremental data. Dispatch the update request to the server for handling. The result will be acknowledged to this client, and broadcast to other connected clients.

Parameters:
Name Type Description
embeddedName string

The name of the Embedded Entity class to update
updateData Array

An Array of incremental data, one per Embedded Entity, with which to update the Entity
options Object

Additional update options which modify the request
Returns:

A Promise which resolves to this Entity once the update request is successful

Type
Promise

(async) updateManyOwnedItems()

Source:
Deprecated:
  • since 0.4.4 in favor of Entity.updateManyEmbeddedEntities()

(async) updateOwnedItem(itemData, options) → {Promise.<Object>}

Source:
See:

Update an owned item using provided new data. This redirects its arguments to the updateEmbeddedEntity method.

Parameters:
Name Type Description
itemData Object

Data for the item to update
options Object

Item update options
Returns:

A Promise resolving to the updated Owned Item data

Type
Promise.<Object>