Constructor
new Actor(dataopt, contextopt)
- See:
-
- data.ActorData The Actor data schema
- documents.Actors The world-level collection of Actor documents
- applications.ActorSheet The Actor configuration application
Examples
let actor = await Actor.create({
name: "New Test Actor",
type: "character",
img: "artwork/character-profile.jpg"
});
let actor = game.actors.get(actorId);
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
data.ActorData |
<optional> |
{}
|
Initial data provided to construct the Actor document |
context |
object |
<optional> |
{}
|
The document context, see foundry.abstract.Document |
Extends
- abstract.Document
- abstract.BaseActor
- ClientDocumentMixin
Members
_lastWildcard :string|null
Cache the last drawn wildcard token to avoid repeat draws
Type:
- string | null
apps :Object.<Application>
- Overrides:
- See:
-
- Document#render
A collection of Application instances which should be re-rendered whenever this document is updated. 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 Document#render.
Type:
- Object.<Application>
collection :Collection
- Overrides:
Return a reference to the parent Collection instance which contains this Document.
Type:
collectionName :string
- Overrides:
The named collection to which this Document belongs.
Type:
- string
compendium :CompendiumCollection
- Overrides:
A reference to the Compendium Collection which contains this Document, if any, otherwise undefined.
Type:
data :DocumentData
- Overrides:
The base data object for this Document which persists both the original source and any derived data.
Type:
- DocumentData
documentName :string
- Overrides:
The canonical name of this Document type, for example "Actor".
Type:
- string
folder :Folder|null
- Overrides:
Return a reference to the Folder to which this Document belongs, if any.
Type:
- Folder | null
Example
let folder = game.folders.contents[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 :boolean
- Overrides:
Test whether this Document is owned by any non-Gamemaster User.
Type:
- boolean
id :string|null
- Overrides:
The canonical identifier for this Document
Type:
- string | null
img :string
A convenient reference to the file path of the Actor's profile image
Type:
- string
isEmbedded :boolean
- Overrides:
Test whether this Document is embedded within a parent Document
Type:
- boolean
isOwner :boolean
- Overrides:
A boolean indicator for whether or not the current game User has ownership rights for this Document. Different Document types may have more specialized rules for what constitutes ownership.
Type:
- boolean
isToken :boolean
Test whether an Actor document is a synthetic representation of a Token (if true) or a full Document (if false)
Type:
- boolean
itemTypes :Object.<Array.<documents.Item>>
Provide an object which organizes all embedded Item instances by their type
Type:
- Object.<Array.<documents.Item>>
limited :boolean
- Overrides:
A boolean indicator for whether the current game User has exactly LIMITED visibility (and no greater).
Type:
- boolean
link
- Overrides:
Return a string which creates a dynamic link to this Document instance.
name :string|null
- Overrides:
The name of this Document, if it has one assigned
Type:
- string | null
overrides :object
An object that tracks which tracks the changes to the data model which were applied by active effects
Type:
- object
pack :string|null
- Overrides:
An immutable reference to a containing Compendium collection to which this Document belongs.
Type:
- string | null
parent :Document|null
- Overrides:
An immutable reverse-reference to the parent Document to which this embedded Document belongs.
Type:
- Document | null
permission :number
- Overrides:
Return the permission level that the current game User has over this Document. See the CONST.DOCUMENT_PERMISSION_LEVELS object for an enumeration of these levels.
Type:
- number
Example
game.user.id; // "dkasjkkj23kjf"
actor.data.permission; // {default: 1, "dkasjkkj23kjf": 2};
actor.permission; // 2
sheet :FormApplication|null
- Overrides:
Lazily obtain a FormApplication instance used to configure this Document, or null if no sheet is available.
Type:
- FormApplication | null
temporaryEffects
An array of ActiveEffect instances which are present on the Actor which have a limited duration.
thumbnail :string
Provide a thumbnail image path used to represent this document.
Type:
- string
token
Return a reference to the TokenDocument which owns this Actor as a synthetic override
uuid :string
- Overrides:
A Universally Unique Identifier (uuid) for this Document instance.
Type:
- string
visible :boolean
- Overrides:
A boolean indicator for whether or not the current game User has at least limited visibility for this Document. Different Document types may have more specialized rules for what determines visibility.
Type:
- boolean
Methods
(protected) _initialize()
- Overrides:
Perform one-time initialization tasks which only occur when the Document is first constructed.
(protected) _onCreate(data, options, userId)
- Overrides:
Perform follow-up operations after a Document of this type is created. Post-creation operations occur for all clients after the creation is broadcast.
Parameters:
Name | Type | Description |
---|---|---|
data |
object | The initial data object provided to the document creation request |
options |
object | Additional options which modify the creation request |
userId |
string | The id of the User requesting the document update |
_onCreateEmbeddedDocuments(embeddedName, documents, result, options, userId)
Follow-up actions taken after a set of embedded Documents in this parent Document are created.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
documents |
Array.<Document> | An Array of created Documents |
result |
Array.<object> | An Array of created data objects |
options |
object | Options which modified the creation operation |
userId |
string | The ID of the User who triggered the operation |
(protected) _onDelete(options, userId)
- Overrides:
Perform follow-up operations after a Document of this type is deleted. Post-deletion operations occur for all clients after the deletion is broadcast.
Parameters:
Name | Type | Description |
---|---|---|
options |
object | Additional options which modify the deletion request |
userId |
string | The id of the User requesting the document update |
_onDeleteEmbeddedDocuments(embeddedName, documents, result, options, userId)
Follow-up actions taken after a set of embedded Documents in this parent Document are deleted.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
documents |
Array.<Document> | An Array of deleted Documents |
result |
Array.<object> | An Array of document IDs being deleted |
options |
object | Options which modified the deletion operation |
userId |
string | The ID of the User who triggered the operation |
(protected) _onUpdate(changed, options, userId)
- Overrides:
- See:
Perform follow-up operations after a Document of this type is updated. Post-update operations occur for all clients after the update is broadcast.
Parameters:
Name | Type | Description |
---|---|---|
changed |
object | The differential data that was changed relative to the documents prior values |
options |
object | Additional options which modify the update request |
userId |
string | The id of the User requesting the document update |
_onUpdateEmbeddedDocuments(embeddedName, documents, result, options, userId)
Follow-up actions taken after a set of embedded Documents in this parent Document are updated.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
documents |
Array.<Document> | An Array of updated Documents |
result |
Array.<object> | An Array of incremental data objects |
options |
object | Options which modified the update operation |
userId |
string | The ID of the User who triggered the operation |
(async, protected) _preCreate(data, options, user)
- Overrides:
Perform preliminary operations before a Document of this type is created. Pre-creation operations only occur for the client which requested the operation.
Parameters:
Name | Type | Description |
---|---|---|
data |
object | The initial data object provided to the document creation request |
options |
object | Additional options which modify the creation request |
user |
documents.BaseUser | The User requesting the document creation |
_preCreateEmbeddedDocuments(embeddedName, result, options, userId)
Preliminary actions taken before a set of embedded Documents in this parent Document are created.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
result |
Array.<object> | An Array of created data objects |
options |
object | Options which modified the creation operation |
userId |
string | The ID of the User who triggered the operation |
(async, protected) _preDelete(options, user)
- Overrides:
Perform preliminary operations before a Document of this type is deleted. Pre-delete operations only occur for the client which requested the operation.
Parameters:
Name | Type | Description |
---|---|---|
options |
object | Additional options which modify the deletion request |
user |
documents.BaseUser | The User requesting the document deletion |
_preDeleteEmbeddedDocuments(embeddedName, result, options, userId)
Preliminary actions taken before a set of embedded Documents in this parent Document are deleted.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
result |
Array.<object> | An Array of document IDs being deleted |
options |
object | Options which modified the deletion operation |
userId |
string | The ID of the User who triggered the operation |
(async, protected) _preUpdate(changed, options, user)
- Overrides:
Perform preliminary operations before a Document of this type is updated. Pre-update operations only occur for the client which requested the operation.
Parameters:
Name | Type | Description |
---|---|---|
changed |
object | The differential data that is changed relative to the documents prior values |
options |
object | Additional options which modify the update request |
user |
documents.BaseUser | The User requesting the document update |
_preUpdateEmbeddedDocuments(embeddedName, result, options, userId)
Preliminary actions taken before a set of embedded Documents in this parent Document are updated.
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
result |
Array.<object> | An Array of incremental data objects |
options |
object | Options which modified the update operation |
userId |
string | The ID of the User who triggered the operation |
applyActiveEffects()
Apply any transformations to the Actor data which are caused by ActiveEffects.
canUserModify(user, action, dataopt) → {boolean}
- Overrides:
Test whether a given User has permission to perform some action on this Document
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
user |
documents.BaseUser | The User attempting modification |
|
action |
string | The attempted action |
|
data |
object |
<optional> |
Data involved in the attempted action |
Returns:
Does the User have permission?
- Type
- boolean
clone(dataopt, saveopt, contextopt) → {Document|Promise.<Document>}
- Overrides:
Clone a document, creating a new document by combining current data with provided overrides. The cloned document is ephemeral and not yet saved to the database.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
Object |
<optional> |
{}
|
Additional data which overrides current document data at the time of creation |
save |
boolean |
<optional> |
false
|
Save the clone to the World database? |
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context options passed to the create method |
Returns:
The cloned Document instance
- Type
- Document | Promise.<Document>
(async) createEmbeddedDocuments(embeddedName, data, contextopt) → {Promise.<Array.<Document>>}
- Overrides:
- See:
-
- Document.createDocuments
Create multiple embedded Document instances within this parent Document using provided input data.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
embeddedName |
string | The name of the embedded Document type |
||
data |
Array.<object> | An array of data objects used to create multiple documents |
||
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context which customizes the creation workflow |
Returns:
An array of created Document instances
- Type
- Promise.<Array.<Document>>
(async) delete(contextopt) → {Promise.<Document>}
- Overrides:
- See:
-
- Document.deleteDocuments
Delete this Document, removing it from the database.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context which customizes the deletion workflow |
Returns:
The deleted Document instance
- Type
- Promise.<Document>
(async) deleteEmbeddedDocuments(embeddedName, ids, contextopt) → {Promise.<Array.<Document>>}
- Overrides:
- See:
-
- Document.deleteDocuments
Delete multiple embedded Document instances within a parent Document using provided string ids.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
embeddedName |
string | The name of the embedded Document type |
||
ids |
Array.<string> | An array of string ids for each Document to be deleted |
||
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context which customizes the deletion workflow |
Returns:
An array of deleted Document instances
- Type
- Promise.<Array.<Document>>
exportToJSON(optionsopt)
- Overrides:
Export document data to a JSON file which can be saved by the client and later imported into a different session.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
options |
object |
<optional> |
Additional options passed to the ClientDocumentMixin#toCompendium method |
getActiveTokens(linkedopt, documentopt)
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. If the Actor is a synthetic token actor, only the exact Token which it represents will be returned.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
linked |
boolean |
<optional> |
false
|
Limit results to Tokens which are linked to the Actor. Otherwise return all Tokens even those which are not linked. * |
document |
boolean |
<optional> |
false
|
Return the Document instance rather than the PlaceableObject |
Returns:
Token[]} An array of Token instances in the current Scene which reference this Actor.
getEmbeddedCollection(embeddedName) → {Collection}
- Overrides:
Obtain a reference to the Array of source data within the data object for a certain embedded Document name
Parameters:
Name | Type | Description |
---|---|---|
embeddedName |
string | The name of the embedded Document type |
Returns:
The Collection instance of embedded Documents of the requested type
- Type
- Collection
getEmbeddedDocument(embeddedName, id, optionsopt) → {Document}
- Overrides:
Get an embedded document by it's id from a named collection in the parent document.
Parameters:
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
embeddedName |
string | The name of the embedded Document type |
|||||||||||
id |
string | The id of the child document to retrieve |
|||||||||||
options |
object |
<optional> |
Additional options which modify how embedded documents are retrieved Properties
|
Returns:
The retrieved embedded Document instance, or undefined
- Type
- Document
getFlag(scope, key) → {*}
- Overrides:
Get the value of a "flag" for this document 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
- *
getRollData() → {object}
Prepare a data object which defines the data schema used by dice roll commands against this Actor
Returns:
- Type
- object
(async) getTokenData(dataopt) → {Promise.<data.TokenData>}
Create a new TokenData object which can be used to create a Token representation of the Actor.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
object |
<optional> |
{}
|
Additional data, such as x, y, rotation, etc. for the created token data |
Returns:
The created TokenData instance
- Type
- Promise.<data.TokenData>
(async) getTokenImages() → {Promise.<Array.<string>>}
Get an Array of Token images which could represent this Actor
Returns:
- Type
- Promise.<Array.<string>>
getUserLevel(user) → {number|null}
- Overrides:
Get the permission level that a specific User has over this Document, a value in CONST.DOCUMENT_PERMISSION_LEVELS.
Parameters:
Name | Type | Description |
---|---|---|
user |
documents.BaseUser | The User being tested |
Returns:
A numeric permission level from CONST.DOCUMENT_PERMISSION_LEVELS or null
- Type
- number | null
(async) importFromJSON(json) → {Promise.<Document>}
- Overrides:
Update this Document using a provided JSON string.
Parameters:
Name | Type | Description |
---|---|---|
json |
string | JSON data string |
Returns:
The updated Document
- Type
- Promise.<Document>
(async) importFromJSONDialog() → {Promise.<void>}
- Overrides:
Render an import dialog for updating the data related to this Document through an exported JSON file
Returns:
- Type
- Promise.<void>
migrateSystemData() → {object}
- Overrides:
For Documents which include game system data, migrate the system data object to conform to its latest data model. The data model is defined by the template.json specification included by the game system.
Returns:
The migrated system data object
- Type
- object
(async) modifyTokenAttribute(attribute, value, isDelta, isBar) → {Promise.<documents.Actor>}
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 document
- Type
- Promise.<documents.Actor>
prepareBaseData()
- Overrides:
Prepare data related to this Document itself, before any embedded Documents or derived data is computed.
prepareData()
- Overrides:
Prepare data for the Document. Begin by resetting the prepared data back to its source state. Next prepare any embedded Documents and compute any derived data elements.
prepareDerivedData()
- Overrides:
Apply transformations or derivations to the values of the source data object. Compute data fields whose values are not stored to the database.
prepareEmbeddedDocuments()
- Overrides:
Prepare all embedded Document instances which exist within this primary Document.
render(forceopt, contextopt)
- Overrides:
- See:
Render all of the Application instances which are connected to this document by calling their respective
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
force |
boolean |
<optional> |
false
|
Force rendering |
context |
object |
<optional> |
{}
|
Optional context |
(async) rollInitiative(options) → {Promise.<(documents.Combat|null)>}
Roll initiative for all Combatants in the currently active Combat encounter which are associated with this Actor. If viewing a full Actor document, all Tokens which map to that actor will be targeted for initiative rolls. If viewing a synthetic Token actor, only that particular Token will be targeted for an initiative roll.
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object | Configuration for how initiative for this Actor is rolled. Properties
|
Returns:
A promise which resolves to the Combat document once rolls are complete.
- Type
- Promise.<(documents.Combat|null)>
(async) setFlag(scope, key, value) → {Promise.<Document>}
- Overrides:
Assign a "flag" to this document. 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 document
- Type
- Promise.<Document>
(async) sortRelative(optionsopt) → {Promise.<Document>}
- Overrides:
Determine the sort order for this Document by positioning it relative a target sibling. See SortingHelper.performIntegerSort for more details
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
options |
object |
<optional> |
Sorting options provided to SortingHelper.performIntegerSort |
Returns:
The Document after it has been re-sorted
- Type
- Promise.<Document>
testUserPermission(user, permission, options) → {boolean}
- Overrides:
Test whether a certain User has a requested permission level (or greater) over the Document
Parameters:
Name | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
user |
documents.BaseUser | The User being tested |
||||||||||
permission |
string | number | The permission level from DOCUMENT_PERMISSION_LEVELS to test |
||||||||||
options |
object | Additional options involved in the permission test Properties
|
Returns:
Does the user have this permission level over the Document?
- Type
- boolean
toCompendium(packopt, optionsopt) → {object}
- Overrides:
Transform the Document data to be stored in a Compendium pack. Remove any features of the data which are world-specific.
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pack |
CompendiumCollection |
<optional> |
A specific pack being exported to |
||||||||||||||||||||||||||||||
options |
object |
<optional> |
Additional options which modify how the document is converted Properties
|
Returns:
A data object of cleaned data suitable for compendium import
- Type
- object
toJSON() → {object}
- Overrides:
Convert the Document instance to a primitive object which can be serialized. See DocumentData#toJSON
Returns:
The document data expressed as a plain object
- Type
- object
toObject(sourceopt) → {object}
- Overrides:
Transform the Document instance into a plain object. The created object is an independent copy of the original data. See DocumentData#toObject
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
source |
boolean |
<optional> |
true
|
Draw values from the underlying data source rather than transformed values |
Returns:
The extracted primitive object
- Type
- object
(async) unsetFlag(scope, key) → {Promise.<Document>}
- Overrides:
Remove a flag assigned to the document
Parameters:
Name | Type | Description |
---|---|---|
scope |
string | The flag scope which namespaces the key |
key |
string | The flag key |
Returns:
The updated document instance
- Type
- Promise.<Document>
(async) update(dataopt, contextopt) → {Promise.<Document>}
- Overrides:
- See:
-
- Document.updateDocuments
Update this Document using incremental data, saving it to the database.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
object |
<optional> |
{}
|
Differential update data which modifies the existing values of this document data |
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context which customizes the update workflow |
Returns:
The updated Document instance
- Type
- Promise.<Document>
(async) updateEmbeddedDocuments(embeddedName, updates, contextopt) → {Promise.<Array.<Document>>}
- Overrides:
- See:
-
- Document.updateDocuments
Update multiple embedded Document instances within a parent Document using provided differential data.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
embeddedName |
string | The name of the embedded Document type |
||
updates |
Array.<object> | An array of differential data objects, each used to update a single Document |
||
context |
DocumentModificationContext |
<optional> |
{}
|
Additional context which customizes the update workflow |
Returns:
An array of updated Document instances
- Type
- Promise.<Array.<Document>>