The Actor Entity

For application developers there are three important layers which are useful when working with Actors. The Actors() collection manages the set of actor entities which are present within the world. Each individual actor within that collection is an instance of the Actor() class (by default). Game systems which want more control over the behaviors and attributes of an actor may override this to a subclass included in their own definition.

When viewing or interacting with an actor inside the tabletop framework, the actor’s data is rendered and edited using the ActorSheet() class (by default). Game systems which want to fine-tune how the actor data is rendered may override this to a subclass included in their own definition.


The Actor Class

class foundry.Actor()

The Actor class is a type of Entity() which represents the protagonists, characters, enemies, and more that inhabit the World.

foundry.Actor.Entity.create(data, options)

Create a new entity using provided input data The data for entity creation is typically provided from the server through the ‘create<Entity>’ socket Alternatively, the creation event may originate locally and the new entity can be pushed back to the server

Arguments:
  • data (Object) – The data with which to create the entity
  • options (Object) – Additional options which customize the creation workflow
  • options.temporary (Boolean) – Create a temporary entity which is not saved to the world database. Default is false.
  • options.displaySheet (Boolean) – Show the configuration sheet for the created entity once it is created. Default is true.
Returns:

Promise – A Promise which resolves to contain the created Entity

foundry.Actor.Entity.update(data, options)

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

Arguments:
  • data (Object) – The data with which to update the entity
  • options (Object) – Additional options which customize the update workflow
  • options.diff (Boolean) – Diff the provided data against existing entity data, only submitting the difference to the server. Default is true.
Returns:

Promise – A Promise which resolves to the updated Entity

foundry.Actor.Entity.delete(options)

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

Arguments:
  • options (Object) – Additional options which customize the deletion workflow
Returns:

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

foundry.Actor._tokenImages

type: Array

Cache an Array of allowed Token images if using a wildcard path

foundry.Actor.createOwnedItem(itemData, options)

Create a new item owned by this Actor.

Arguments:
  • itemData (Object) – Data for the newly owned item
  • options (Object) – Item creation options
  • options.displaySheet (Boolean) – Render the Item sheet for the newly created item data
Returns:

Promise.<Item> – A Promise containing the newly created owned Item instance

foundry.Actor.deleteOwnedItem(itemId, options)

Delete an owned item by its ID

Arguments:
  • itemId (Number) – The ID of the item to delete
  • options (Object) – Item deletion options
Returns:

Promise.<Number> – A Promise resolving to the deleted item ID

foundry.Actor.fromToken(token)

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

Arguments:
  • token (Token) –
Returns:

Actor

foundry.Actor.getActiveTokens(linked=false)

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.

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

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

foundry.Actor.getOwnedItem(itemId)

Get an owned item by it’s ID, initialized as an Item entity class

Arguments:
  • itemId (Number) – The ID of the owned item
Returns:

Item|null – An Item class instance for that owned item or null if the itemId does not exist

foundry.Actor.getTokenImages()

Get an Array of Token images which could represent this Actor

Returns:Promise
foundry.Actor.img

type: String

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

foundry.Actor.importItemFromCollection(collection, entryId)

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

Arguments:
  • collection (String) – The name of the pack from which to import
  • entryId (String) – The ID of the compendium entry to import
foundry.Actor.isPC

type: Boolean

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

foundry.Actor.isToken

type: Boolean

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

foundry.Actor.items

type: Array.<Item>

Construct the Array of Item instances for the Actor

foundry.Actor.prepareData()

Prepare data for the Actor instance whenever it is first created or later updated.

foundry.Actor.token

type: Token

A reference to a placed Token which creates a synthetic Actor

foundry.Actor.update(data, options)

Extend the default update method to enhance data before submission. See the parent Entity.update method for full details.

Arguments:
  • data (Object) – The data with which to update the Actor
  • options (Object) – Additional options which customize the update workflow
Returns:

Promise – A Promise which resolves to the updated Entity

foundry.Actor.updateManyOwnedItem(data, options)

Update multiple owned items within the parent Actor

Arguments:
  • data (Object) – The multi-object update to perform
  • options (Object) – Owned Item update options
Returns:

Promise – A Promise resolving to the updated Actor

foundry.Actor.updateOwnedItem(itemData, options)

Update an owned item using provided new data

Arguments:
  • itemData (Object) – Data for the item to update
  • options (Object) – Item update options
Returns:

Promise.<Item> – A Promise resolving to the updated Item object


The Actors Collection

class Actors()

The Collection() of Actor() entities The actors collection is accessible within the game as game.actors

Actors.Collection.insert(entity)

Add a new Entity to the Collection, asserting that they are of the correct type

Arguments:
  • entity (Entity) – The entity instance to add to the collection
Actors.Collection.remove(id)

Remove an Entity from the Collection by its ID.

Arguments:
  • id (String) – The entity ID which should be removed
Actors.Collection.get(id)

Get an element from the collection by ID

Arguments:
  • id (String) – The entity ID to retrieve from the collection
Returns:

Entity – The retrieved Entity, if the ID was found, otherwise null;

Actors.Collection.index(id)

Retrieve the index of an entity within the collection by its ID

Arguments:
  • id (String) – The entity ID to retrieve from the collection
Returns:

Number – The index of the Entity within the collection, if found, otherwise -1;

Actors.Collection.render(args)

Re-render any currently visible applications associated with this Collection

Actors.object

type: Actor

Elements of the Actors collection are instances of the Actor class, or a subclass thereof

Actors.registerSheet(args)

Register an Actor sheet class as a candidate which can be used to display Actors of a given type See EntitySheetConfig.registerSheet for details

Actors.registeredSheets

type: Array

Return an Array of currently registered sheet classes for this Entity type

Actors.unregisterSheet(args)

Unregister an Actor sheet class, removing it from the list of avaliable sheet Applications to use See EntitySheetConfig.unregisterSheet for details


The Actor Sheet

class ActorSheet(actor, options)

The default Actor Sheet

This Application is responsible for rendering an actor’s attributes and allowing the actor to be edited.

System modifications may elect to override this class to better suit their own game system by re-defining the value CONFIG.Actor.sheetClass.

Arguments:
  • actor (Actor) – The Actor instance being displayed within the sheet.
  • options (Object) – Additional options which modify the rendering of the Actor’s sheet.
  • options.editable (Boolean) – Is the Actor editable? Default is true.
ActorSheet.activateListeners(html)

Activate the default set of listeners for the Actor Sheet These listeners handle basic stuff like form submission or updating images

Arguments:
  • html (JQuery) – The rendered template ready to have listeners attached
ActorSheet.actor

type: Actor

A convenience reference to the Actor entity

ActorSheet.close()

Remove references to an active Token when the sheet is closed See Application.close for more detail

Returns:Promise
ActorSheet.defaultOptions

type: Object

Default rendering and configuration options used for the ActorSheet and its subclasses. See Application.defaultOptions and FormApplication.defaultOptions for more details.

ActorSheet.getData()

Prepare data for rendering the Actor sheet The prepared data object contains both the actor data as well as additional sheet options

ActorSheet.id

Define a unique and dynamic element ID for the rendered ActorSheet application

ActorSheet.title

type: String

The displayed window title for the sheet - the entity name by default

ActorSheet.token

type: Token

If this Actor Sheet represents a synthetic Token actor, reference the active Token