Construct an Actor document using provided data and context.
Initial data from which to construct the Actor
Construction context options
An object that tracks which tracks the changes to the data model which were applied by active effects
The statuses that are applied to this actor by active effects
Cache the last drawn wildcard token to avoid repeat draws
The source data object for this DataModel instance. Once constructed, the source object is sealed such that no keys may be added nor removed.
An immutable reverse-reference to a parent DataModel to which this model belongs.
Private _tokenA cached array of image paths which can be used for this Actor's token. Null if the list has not yet been populated.
Static metadataDefault metadata which applies to each instance of this Document type.
Static DEFAULT_The default icon used for newly created Actor documents.
Static LOCALIZATION_A set of localization prefix paths which are used by this DataModel.
Provide a thumbnail image path used to represent this document.
Test whether an Actor document is a synthetic representation of a Token (if true) or a full Document (if false)
Retrieve the list of ActiveEffects that are currently applied to this Actor.
An array of ActiveEffect instances which are present on the Actor which have a limited duration.
Return a reference to the TokenDocument which owns this Actor as a synthetic override
Whether the Actor has at least one Combatant in the active Combat that represents it.
The canonical identifier for this Document.
Test whether this Document is embedded within a parent Document
A Universally Unique Identifier (uuid) for this Document instance.
Define the data schema for this document instance.
Is the current state of this DataModel invalid? The model is invalid if there is any unresolved failure.
An array of validation failure instances which may have occurred when this instance was last validated.
Static schemaEnsure that all Document classes share the same schema of their base declaration.
Static databaseThe database backend used to execute operations and handle results.
Static implementationStatic baseStatic collectionThe named collection to which this Document belongs.
Static documentThe canonical name of this Document type, for example "Actor".
Static TYPESThe allowed types which may exist for this Document class.
Static hasDoes this Document support additional subtypes?
Static hierarchyThe Embedded Document hierarchy for this Document.
Initialize the source data for a new DataModel instance. One-time migrations and initial cleaning operations are applied to the source data.
The candidate source data from which the model will be constructed
Options provided to the model constructor
Migrated and cleaned source data which will be stored to the model instance
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.
Optional linked: boolean = falseLimit results to Tokens which are linked to the Actor. Otherwise, return all Tokens even those which are not linked.
Optional document: boolean = falseReturn the Document instance rather than the PlaceableObject
An array of Token instances in the current Scene which reference this Actor.
Get all ActiveEffects that may apply to this Actor. If CONFIG.ActiveEffect.legacyTransferral is true, this is equivalent to actor.effects.contents. If CONFIG.ActiveEffect.legacyTransferral is false, this will also return all the transferred ActiveEffects on any of the Actor's owned Items.
Return a data object which defines the data schema against which dice rolls can be evaluated. By default, this is directly the Actor's system data, but systems may extend this to include additional properties. If overriding or extending this method to add additional properties, care must be taken not to mutate the original object.
Create a new Token document, not yet saved to the database, which represents the Actor.
Optional data: object = {}Additional data, such as x, y, rotation, etc. for the created token data
Optional options: object = {}The options passed to the TokenDocument constructor
The created TokenDocument instance
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.
The attribute path
The target attribute value
Whether the number represents a relative change (true) or an absolute change (false)
Whether the new value is part of an attribute bar, or just a direct value
The updated Actor document
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.
Configuration for how initiative for this Actor is rolled.
Create new Combatant entries for Tokens associated with this actor.
Re-roll the initiative for this Actor if it has already been rolled.
Additional options passed to the Combat#rollInitiative method.
A promise which resolves to the Combat document once rolls are complete.
Toggle a configured status effect for the Actor.
A status effect ID defined in CONFIG.statusEffects
Optional options: { Additional options which modify how the effect is created
Force the effect to be active or inactive regardless of its current state
Display the toggled effect as an overlay
A promise which resolves to one of the following values: - ActiveEffect if a new effect need to be created - true if was already an existing effect - false if an existing effect needed to be removed - undefined if no changes need to be made
Get this actor's dependent tokens. If the actor is a synthetic token actor, only the exact Token which it represents will be returned.
Internal Register a token as a dependent of this actor.
The token.
Internal Remove a token from this actor's dependents.
The token.
Internal Prune a whole scene from this actor's dependent tokens.
The scene.
Internal Post-process an update operation for a single Document instance. Post-operation events occur for all connected clients.
The differential data that was changed relative to the documents prior values
Additional options which modify the update request
The id of the User requesting the document update
Internal Pre-process a creation operation for a single Document instance. Pre-operation events only occur for the client which requested the operation.
Modifications to the pending Document instance must be performed using Document#updateSource.
The initial data object provided to the document creation request
Additional options which modify the creation request
The User requesting the document creation
Return false to exclude this Document from the creation operation
Internal Pre-process an update operation for a single Document instance. Pre-operation events only occur for the client which requested the operation.
The candidate changes to the Document
Additional options which modify the update request
The User requesting the document update
A return value of false indicates the update operation should be cancelled.
Get the explicit permission level that a User has over this Document, a value in CONST.DOCUMENT_OWNERSHIP_LEVELS. This method returns the value recorded in Document ownership, regardless of the User's role. To test whether a user has a certain capability over the document, testUserPermission should be used.
Optional user: BaseUserThe User being tested
A numeric permission level from CONST.DOCUMENT_OWNERSHIP_LEVELS or null
Test whether a certain User has a requested permission level (or greater) over the Document
The User being tested
The permission level from DOCUMENT_OWNERSHIP_LEVELS to test
Additional options involved in the permission test
Require the exact permission level requested?
Does the user have this permission level over the Document?
Test whether a given User has permission to perform some action on this Document
The User attempting modification
The attempted action
Optional data: object = {}Data involved in the attempted action
Does the User have permission?
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.
Optional data: Object = {}Additional data which overrides current document data at the time of creation
Optional context: DocumentConstructionContext = {}Additional context options passed to the create method
The cloned Document instance
Copy and transform the DataModel into a plain object. Draw the values of the extracted object from the data source (by default) otherwise from its transformed values.
Draw values from the underlying data source rather than transformed values
The extracted primitive object
Update this Document using incremental data, saving it to the database.
Optional data: object = {}Differential update data which modifies the existing values of this document
Optional operation: Partial<Omit<DatabaseUpdateOperation, "updates">> = {}Parameters of the update operation
The updated Document instance
Document.updateDocuments
Obtain a reference to the Array of source data within the data object for a certain embedded Document name
The name of the embedded Document type
The Collection instance of embedded Documents of the requested type
Get an embedded document by its id from a named collection in the parent document.
The name of the embedded Document type
The id of the child document to retrieve
Optional options: { Additional options which modify how embedded documents are retrieved
Throw an Error if the requested id does not exist. See Collection#get
Allow retrieving an invalid Embedded Document.
The retrieved embedded Document instance, or undefined
If the embedded collection does not exist, or if strict is true and the Embedded Document could not be found.
Create multiple embedded Document instances within this parent Document using provided input data.
The name of the embedded Document type
An array of data objects used to create multiple documents
Optional operation: DatabaseCreateOperation = {}Parameters of the database creation workflow
An array of created Document instances
Document.createDocuments
Update multiple embedded Document instances within a parent Document using provided differential data.
The name of the embedded Document type
An array of differential data objects, each used to update a single Document
Optional operation: DatabaseUpdateOperation = {}Parameters of the database update workflow
An array of updated Document instances
Document.updateDocuments
Delete multiple embedded Document instances within a parent Document using provided string ids.
The name of the embedded Document type
An array of string ids for each Document to be deleted
Optional operation: DatabaseDeleteOperation = {}Parameters of the database deletion workflow
An array of deleted Document instances
Document.deleteDocuments
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.
The flag scope which namespaces the key
The flag key
The flag value
A Promise resolving to the updated document
Internal Post-process a creation operation for a single Document instance. Post-operation events occur for all connected clients.
The initial data object provided to the document creation request
Additional options which modify the creation request
The id of the User requesting the document update
Internal Pre-process a deletion operation for a single Document instance. Pre-operation events only occur for the client which requested the operation.
Additional options which modify the deletion request
The User requesting the document deletion
A return value of false indicates the deletion operation should be cancelled.
Internal Post-process a deletion operation for a single Document instance. Post-operation events occur for all connected clients.
Additional options which modify the deletion request
The id of the User requesting the document update
Validate the data contained in the document to check for type and content This function throws an error if data within the document is not valid
Optional parameters which customize how validation occurs.
A specific set of proposed changes to validate, rather than the full source data of the model.
If changes are provided, attempt to clean the changes before validating them?
Allow replacement of invalid values with valid defaults?
If true, invalid embedded documents will emit a warning and be placed in the invalidDocuments collection rather than causing the parent to be considered invalid.
Throw if an invalid value is encountered, otherwise log a warning?
Perform validation on individual fields?
Perform joint validation on the full data model? Joint validation will be performed by default if no changes are passed. Joint validation will be disabled by default if changes are passed. Joint validation can be performed on a complete set of changes (for example testing a complete data model) by explicitly passing true.
An indicator for whether the document contains valid data
Update the DataModel locally by applying an object of changes to its source data. The provided changes are cleaned, validated, and stored to the source data object for this model. The source data is then re-initialized to apply those changes to the prepared data. The method returns an object of differential changes which modified the original data.
New values which should be applied to the data model
Optional options: object = {}Options which determine how the new data is merged
An object containing the changed keys and values
Protected _onProtected _updateStatic defineDefine the data schema for documents of this type. The schema is populated the first time it is accessed and cached for future reuse.
Static getDetermine default artwork based on the provided actor data.
The source actor data.
Candidate actor image and prototype token artwork.
Static canStatic migrateStatic _initializationStatic createCreate multiple Documents using provided input data. Data is provided as an array of objects where each individual object becomes one new Document.
An array of data objects or existing Documents to persist.
Optional operation: Partial<Omit<DatabaseCreateOperation, "data">> = {}Parameters of the requested creation operation
An array of created Document instances
const data = [{name: "New Actor", type: "character", img: "path/to/profile.jpg"}];
const created = await Actor.createDocuments(data);
const data = [{name: "Tim", type: "npc"], [{name: "Tom", type: "npc"}];
const created = await Actor.createDocuments(data);
const actor = game.actors.getName("Tim");
const data = [{name: "Sword", type: "weapon"}, {name: "Breastplate", type: "equipment"}];
const created = await Item.createDocuments(data, {parent: actor});
const data = [{name: "Compendium Actor", type: "character", img: "path/to/profile.jpg"}];
const created = await Actor.createDocuments(data, {pack: "mymodule.mypack"});
Static updateUpdate multiple Document instances using provided differential data. Data is provided as an array of objects where each individual object updates one existing Document.
An array of differential data objects, each used to update a single Document
Optional operation: Partial<Omit<DatabaseUpdateOperation, "updates">> = {}Parameters of the database update operation
An array of updated Document instances
const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}];
const updated = await Actor.updateDocuments(updates);
const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}, {_id: "kj549dk48k34jk34", name: "Thomas"}]};
const updated = await Actor.updateDocuments(updates);
const actor = game.actors.getName("Timothy");
const updates = [{_id: sword.id, name: "Magic Sword"}, {_id: shield.id, name: "Magic Shield"}];
const updated = await Item.updateDocuments(updates, {parent: actor});
const actor = await pack.getDocument(documentId);
const updated = await Actor.updateDocuments([{_id: actor.id, name: "New Name"}], {pack: "mymodule.mypack"});
Static deleteDelete one or multiple existing Documents using an array of provided ids. Data is provided as an array of string ids for the documents to delete.
An array of string ids for the documents to be deleted
Optional operation: Partial<Omit<DatabaseDeleteOperation, "ids">> = {}Parameters of the database deletion operation
An array of deleted Document instances
const tim = game.actors.getName("Tim");
const deleted = await Actor.deleteDocuments([tim.id]);
const tim = game.actors.getName("Tim");
const tom = game.actors.getName("Tom");
const deleted = await Actor.deleteDocuments([tim.id, tom.id]);
const tim = game.actors.getName("Tim");
const sword = tim.items.getName("Sword");
const shield = tim.items.getName("Shield");
const deleted = await Item.deleteDocuments([sword.id, shield.id], parent: actor});
const actor = await pack.getDocument(documentId);
const deleted = await Actor.deleteDocuments([actor.id], {pack: "mymodule.mypack"});
Static createCreate a new Document using provided input data, saving it to the database.
The created Document instance
Document.createDocuments
const data = [{name: "Special Sword", type: "weapon"}];
const created = await Item.create(data);
const data = [{name: "Special Sword", type: "weapon"}];
const actor = game.actors.getName("My Hero");
const created = await Item.create(data, {parent: actor});
const data = [{name: "Special Sword", type: "weapon"}];
const created = await Item.create(data, {pack: "mymodule.mypack"});
Static getStatic getA compatibility method that returns the appropriate name of an embedded collection within this Document.
An existing collection name or a document name.
The provided collection name if it exists, the first available collection for the document name provided, or null if no appropriate embedded collection could be found.
Actor.getCollectionName("items");
// returns "items"
Actor.getCollectionName("Item");
// returns "items"
Static _preInternal Pre-process a creation operation, potentially altering its instructions or input data. Pre-operation events only occur for the client which requested the operation.
This batch-wise workflow occurs after individual Document#_preCreate workflows and provides a final pre-flight check before a database operation occurs.
Modifications to pending documents must mutate the documents array or alter individual document instances using Document#updateSource.
Pending document instances to be created
Parameters of the database creation operation
The User requesting the creation operation
Return false to cancel the creation operation entirely
Static _onInternal Post-process a creation operation, reacting to database changes which have occurred. Post-operation events occur for all connected clients.
This batch-wise workflow occurs after individual Document#_onCreate workflows.
The Document instances which were created
Parameters of the database creation operation
The User who performed the creation operation
Static _preInternal Pre-process an update operation, potentially altering its instructions or input data. Pre-operation events only occur for the client which requested the operation.
This batch-wise workflow occurs after individual Document#_preUpdate workflows and provides a final pre-flight check before a database operation occurs.
Modifications to the requested updates are performed by mutating the data array of the operation. Document#updateSource.
Document instances to be updated
Parameters of the database update operation
The User requesting the update operation
Return false to cancel the update operation entirely
Static _onInternal Post-process an update operation, reacting to database changes which have occurred. Post-operation events occur for all connected clients.
This batch-wise workflow occurs after individual Document#_onUpdate workflows.
The Document instances which were updated
Parameters of the database update operation
The User who performed the update operation
Static _preInternal Pre-process a deletion operation, potentially altering its instructions or input data. Pre-operation events only occur for the client which requested the operation.
This batch-wise workflow occurs after individual Document#_preDelete workflows and provides a final pre-flight check before a database operation occurs.
Modifications to the requested deletions are performed by mutating the operation object. Document#updateSource.
Document instances to be deleted
Parameters of the database update operation
The User requesting the deletion operation
Return false to cancel the deletion operation entirely
Static _onInternal Post-process a deletion operation, reacting to database changes which have occurred. Post-operation events occur for all connected clients.
This batch-wise workflow occurs after individual Document#_onDelete workflows.
The Document instances which were deleted
Parameters of the database deletion operation
The User who performed the deletion operation
Static _addInternal Define a simple migration from one field name to another. The value of the data can be transformed during the migration by an optional application function.
The data object being migrated
The old field name
The new field name
An application function, otherwise the old value is applied
Whether a migration was applied.
Static cleanStatic validateEvaluate joint validation rules which apply validation conditions across multiple fields of the model. Field-specific validation rules should be defined as part of the DataSchema for the model. This method allows for testing aggregate rules which impose requirements on the overall model.
Candidate data for the model
An error if a validation failure is detected
Static fromCreate a new instance of this DataModel from a source record. The source is presumed to be trustworthy and is not strictly validated.
Initial document data which comes from a trusted source.
Optional context: any = {}Model construction context
Static fromJSONStatic migrateStatic shimTake data which conforms to the current data schema and add backwards-compatible accessors to it in order to support older code which uses this data.
Data which matches the current schema
Optional options: { Additional shimming options
Apply shims to embedded models?
Data with added backwards-compatible properties
Static Protected _logStatic Private _requestPrivate Request wildcard token images from the server and return them.
The actor whose prototype token contains the wildcard image path.
Optional options: { The name of the compendium the actor is in.
The list of filenames to token images that match the wildcard search.
The client-side Actor document which extends the common BaseActor model.
Hook Events
hookEvents.applyCompendiumArt
Mixes
ClientDocumentMixin
See
Example: Create a new Actor
Example: Retrieve an existing Actor