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:
_data :Object
- Source:
- Overrides:
The original source data for the Entity provided upon initialization. This reflects the database state of the Entity before any transformations are applied.
Type:
- Object
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:
- Object.<Application>
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:
- Compendium | null
data :Object
- Source:
- Overrides:
The effective data for the Entity. This data object may have transformations applied to it.
Type:
- Object
folder :Folder|null
- Source:
- Overrides:
Return a reference to the Folder which this Entity belongs to, if any.
Type:
- Folder | null
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;
hasPlayerOwner
- Source:
- Overrides:
Test for whether this Entity can be owned by any non-gamemaster player.
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
- Source:
- Deprecated:
- since 0.7.2
- See:
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 :Collection.<string, OwnedItem>
- Source:
Construct the Array of Item instances for the Actor Items are prepared by the Actor.prepareEmbeddedEntities() method
Type:
- Collection.<string, OwnedItem>
itemTypes :Object.<string, Array>
- Source:
Classify Owned Items by their type
Type:
- Object.<string, Array>
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
link
- Source:
- Overrides:
Return a string which represents a dynamic link to this Entity.
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
overrides :Data
- Source:
A set that tracks which keys in the data model were modified by active effects
Type:
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:
- number
Example
game.user.id; // "dkasjkkj23kjf"
entity.data.permission; // {default: 1, "dkasjkkj23kjf": 2};
entity.permission; // 2
sheet :BaseEntitySheet|null
- 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:
- BaseEntitySheet | null
Example
A subclass of the Actor entity
let actor = game.entities.actors[0];
actor.sheet; // ActorSheet
temporaryEffects
- Source:
An array of ActiveEffect instances which are present on the Actor which have a limited duration.
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
_initialize()
- Source:
- Overrides:
Safely Initialize data structure for the Entity. Errors that occur here should be captured and logged, but should not break construction of the Entity instance.
applyActiveEffects()
- Source:
Apply any transformations to the Actor data which are caused by ActiveEffects.
(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, data, options) → {Promise.<(Data|Array.<Data>)>}
- Source:
- Overrides:
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
|
Returns:
A Promise which resolves to the created embedded Data once the creation request is successful
(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
|
Returns:
A Promise resolving to the created Owned Item data
- Type
- Promise.<Object>
(async) delete(options) → {Promise.<Entity>}
- Source:
- Overrides:
- 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:
- Overrides:
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 deleted = 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 Properties
|
Returns:
The deleted Embedded Entities
(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.<Token>}
- 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.
getEmbeddedCollection(embeddedName) → {Array.<object>}
- 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.<object>
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 owned Item 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.<Array.<string>>}
- Source:
Get an Array of Token images which could represent this Actor
Returns:
- Type
- Promise.<Array.<string>>
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()
- Source:
- Deprecated:
- since 0.7.0
(async) modifyTokenAttribute(attribute, value, isDelta, isBar) → {Promise.<Actor>}
- 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:
The updated Actor entity
- Type
- Promise.<Actor>
prepareBaseData()
- Source:
First prepare any derived data which is actor-specific and does not depend on Items or Active Effects
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.
prepareDerivedData()
- Source:
Apply final transformations to the Actor data after all effects have been applied
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.
render(force, context)
- Source:
- Overrides:
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:
- 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
(async) toCompendium() → {Object}
- Source:
- Overrides:
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:
- Overrides:
Serializing an Entity should simply serialize it's inner data, not the entire instance
Returns:
- Type
- Object
(async) unsetFlag(scope, key) → {Promise.<Entity>}
- 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:
The updated Entity instance
- Type
- Promise.<Entity>
(async) update(data, options) → {Promise.<Entity>}
- Source:
- Overrides:
- 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:
- Overrides:
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
|
Returns:
The updated Entity or array of Entities
(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>