Combat

Combat

The Combat model definition which defines common behavior of an Combat document between both client and server. Each Combat document contains CombatData which defines its data schema.

Constructor

new Combat(dataopt)

See:
  • data.CombatData The Combat data schema
  • documents.Combats The world-level collection of Combat documents
  • embedded.Combatant The Combatant embedded document which exists within a Combat document
  • applications.CombatConfig The Combat configuration application
Parameters:
Name Type Attributes Default Description
data data.CombatData <optional>
 {}

Initial data provided to construct the Combat document

Extends

Members

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:

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

combatant :Combatant

Get the Combatant who has the current turn.

Type:

compendium :CompendiumCollection

Overrides:

A reference to the Compendium Collection which contains this Document, if any, otherwise undefined.

Type:

CONFIG_SETTING :string

The configuration setting used to record Combat preferences

Type:
  • string

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

A Document may belong to a Folder

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

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

limited :boolean

Overrides:

A boolean indicator for whether the current game User has exactly LIMITED visibility (and no greater).

Type:
  • boolean
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

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.ENTITY_PERMISSIONS object for an enumeration of these levels.

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

round :number

The numeric round of the Combat encounter

Type:
  • number

scene :Scene

A reference to the Scene document within which this Combat encounter occurs. If a specific Scene is not set in the Combat Data, the currently viewed scene is assumed instead.

Type:

settings

Return the object of settings which modify the Combat Tracker behavior

sheet :FormApplication|null

Overrides:

Lazily obtain a FormApplication instance used to configure this Document, or null if no sheet is available.

Type:

started :boolean

Has this combat encounter been started?

Type:
  • boolean

turn :number

The numeric turn of the combat round in the Combat encounter

Type:
  • number

turns :Array.<Combatant>

Track the sorted turn order of this combat encounter

Type:

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

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)

Overrides:

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

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)

Overrides:

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)

Overrides:

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)

Overrides:

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)

Overrides:

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)

Overrides:

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

(async) activate(optionsopt) → {Promise.<Combat>}

Set the current Combat encounter as active within the Scene. Deactivate all other Combat encounters within the viewed Scene and set this one as active

Parameters:
Name Type Attributes Description
options object <optional>

Additional context to customize the update workflow
Returns:
Type
Promise.<Combat>

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, optionsopt) → {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
options object <optional>
 {}

Additional options which customize the creation workflow

Properties
Name Type Attributes Default Description
save boolean <optional>
 false

Save the clone to the World database?
keepId boolean <optional>
 false

Keep the original Document ID? Otherwise the ID will become undefined
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>>

(async) endCombat() → {Promise.<Combat>}

Display a dialog querying the GM whether they wish to end the combat encounter and empty the tracker

Returns:
Type
Promise.<Combat>

exportToJSON()

Overrides:

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

getCombatantByToken(tokenId)

Get a Combatant using its Token id

Parameters:
Name Type Description
tokenId string

The id of the Token for which to acquire the combatant

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
Name Type Attributes Default Description
strict boolean <optional>
 false

Throw an Error if the requested id does not exist. See Collection#get
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
*

getUserLevel(user) → {number|null}

Overrides:

Get the permission level that a specific User has over this Document, a value in CONST.ENTITY_PERMISSIONS.

Parameters:
Name Type Description
user documents.BaseUser

The User being tested
Returns:

A numeric permission level from CONST.ENTITY_PERMISSIONS 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>

(async) nextRound() → {Promise.<Combat>}

Advance the combat to the next round

Returns:
Type
Promise.<Combat>

(async) nextTurn() → {Promise.<Combat>}

Advance the combat to the next turn

Returns:
Type
Promise.<Combat>

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.

prepareEmbeddedEntities()

Overrides:

Prepare all embedded Document instances which exist within this primary Document.

(async) previousRound() → {Promise.<Combat>}

Rewind the combat to the previous round

Returns:
Type
Promise.<Combat>

(async) previousTurn() → {Promise.<Combat>}

Rewind the combat to the previous turn

Returns:
Type
Promise.<Combat>

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) resetAll() → {Promise.<Combat>}

Reset all combatant initiative scores, setting the turn back to zero

Returns:
Type
Promise.<Combat>

(async) rollAll(optionsopt)

Roll initiative for all combatants which have not already rolled

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Additional options forwarded to the Combat.rollInitiative method

(async) rollInitiative(ids, optionsopt) → {Promise.<Combat>}

Roll initiative for one or multiple Combatants within the Combat entity

Parameters:
Name Type Attributes Default Description
ids string | Array.<string>

A Combatant id or Array of ids for which to roll
options object <optional>
 {}

Additional options which modify how initiative rolls are created or presented.

Properties
Name Type Attributes Default Description
formula string | null <optional>

A non-default initiative formula to roll. Otherwise the system default is used.
updateTurn boolean <optional>
 true

Update the Combat turn after adding new initiative scores to keep the turn on the same Combatant.
messageOptions object <optional>
 {}

Additional options with which to customize created Chat Messages
Returns:

A promise which resolves to the updated Combat entity once updates are complete.

Type
Promise.<Combat>

(async) rollNPC(optionsopt)

Roll initiative for all non-player actors who have not already rolled

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Additional options forwarded to the Combat.rollInitiative method

(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) setInitiative(id, value)

Assign initiative for a single Combatant within the Combat encounter. Update the Combat turn order to maintain the same combatant as the current turn.

Parameters:
Name Type Description
id string

The combatant ID for which to set initiative
value number

A specific initiative value to set

setupTurns() → {Array.<Combatant>}

Return the Array of combatants sorted into initiative order, breaking ties alphabetically by name.

Returns:
Type
Array.<Combatant>

(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>

(async) startCombat() → {Promise.<Combat>}

Begin the combat encounter, advancing to round 1 and turn 1

Returns:
Type
Promise.<Combat>

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 ENTITY_PERMISSIONS to test
options object

Additional options involved in the permission test

Properties
Name Type Attributes Default Description
exact boolean <optional>
 false

Require the exact permission level requested?
Returns:

Does the user have this permission level over the Document?

Type
boolean

toCompendium(packopt) → {object}

Overrides:

Transform the Document 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.

Parameters:
Name Type Attributes Description
pack CompendiumCollection <optional>

A specific pack being exported to
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>>