The Actor Entity

One of the most fundamental entities within Foundry Virtual Tabletop is the Actor. Actors are the protagonists, enemies, allies, and personalities within the World that you create. The game System defines the exact types of actors which are relevant, but for most role-playing games actors will, at the very least, represent the characters which the players impersonate.

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

Render all applications associated with this Collection

Actors.importFromCollection(collection, entryId)

Import an Actor from a compendium collection, adding it to the current World

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

Promise – A Promise containing the imported Actor

Actors.object

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


The Actor Class

class Actor(data, apps)

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

Actor.createOwnedItem(itemData, push=false)

Create a new item owned by this Actor. The creation request is submitted to the server where the item is assigned an ID The return item (with itemID) is then added to the actor.

Arguments:
  • itemData (Object) – Data for the newly owned item
  • push (Boolean) – Push the item creation request to other clients?
Actor.deleteOwnedItem(itemId, push=false)

Delete an owned item by its ID

Arguments:
  • itemId (Number) – The ID of the item to delete
  • push (Boolean) – Push the item deletion to other clients?
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.

Actor.img

type: String

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

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
Actor.isPC

A boolean flag for whether this Actor is a player-owned character.

Actor.items

type: Array

A convenient reference to the Array of Items which are owned by the Actor

Actor.sheet

type: ActorSheet

A property which gets or creates a singleton instance of the ActorSheet() which is used to render and edit this Actor’s data.

Actor.token

type: Object

A convenient reference to the default Token data for the Actor

Actor.update(data, push=false)

Update the Actor using new provided data. When an actor is updated, we trigger some additional related updates:

Re-render the parent collection if names, images, or permissions have changed Re-render active tokens if their linked attribute has changed

Arguments:
  • data (Object) – The new data object with which to update the Actor entity
  • push (Boolean) – Push the updated Actor data back to the server and to other clients? Default is false
Returns:

Array – An Array of Actor properties which were modified during the update process

Actor.updateOwnedItem(itemData, push=false)

Update an owned item using provided new data

Arguments:
  • itemData (Object) – Data for the item to update
  • push (Boolean) – Push the item update to other clients?

The Actor Sheet

class ActorSheet(actor, options)

The default Actor Sheet

This is a WindowApplication() that 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.

For basic or aesthetic modifications, overriding this class entirely may not be necessary and you may simply wish to replace the default HTML template. This can be accomplished by re-defning CONFIG.ActorSheet.template.

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.getData()

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

ActorSheet.title

type: String

The displayed window title for the Actor sheet - just the name by default