The User Entity

Each connected client corresponds to an instance of the User() Entity. The collection of all such Entities is stored in the Users() Collection. Refer to the users page for documentation regarding the User concept and its usage within Foundry VTT.


The User Instance

class User(data, options)

The User entity Each player who connects to a Foundry Virtual Tabletop session is a User. Users represent human beigns (or possibly programmatic players) and are the cornerstone of identity in Foundry VTT.

Arguments:
  • data (Object) – The source data for the User entity, usually retrieved from the database.
  • data._id (string) – The Entity ID, automatically generated by the Database when a new User is created.
  • data.password (string) – An access key for the Entity.
  • data.role (number) – The role level for the User, from CONST.USER_ROLES
  • data.permissions (Object) – An object of key-value permissions for the User which extend the default functionality of the User’s role.
  • data.avatar (string) – A web-accessible file path to an avatar image used to represent the User.
  • data.scenes (string) – The _id of the Scene entity that the User is currently viewing.
  • data.character (string) – The _id of the Actor entity that the User has chosen as their primary character.
  • data.color (string) – A color string which represents the visual color associated with this particular User.
  • data.flags (Object) – A free-form object of key-value pairs which allows modules and systems the ability to store arbitrary data as part of the User object.
  • options (Object) – Initialization options which modify the construction of a User entity. See the Entity class for more detail.
User.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

User.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

User.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

User.active

type: Boolean

Return a flag for whether this User is currently active

User.avatar

type: String

Return the User avatar icon or the controlled actor’s image

User.character

type: Actor

Return the Actor instance of the user’s impersonated character (or undefined)

User.collection

type: Users

User instances belong to the Users collection

User.hasPermission(permissionName)

Test whether the User has at least a specific permission

Arguments:
  • permissionName (string) – The permission name from USER_PERMISSIONS to test
Returns:

boolean – Does the user have at least this permission

User.hasRole(role)

Test whether the User has at least the permission level of a certain role

Arguments:
  • role (string|number) – The role name from USER_ROLES to test
Returns:

boolean – Does the user have at least this role level?

User.isGM

A flag for whether the current User has Assistant GameMaster or full GameMaster role

User.isRole(role)

Test whether the User has exactly the permission level of a certain role

Arguments:
  • role (string|number) – The role name from USER_ROLES to test
Returns:

boolean – Does the user have exactly this role level?

User.isSelf

A flag for whether this User is the connected client

User.isTrusted

A flag for whether the current User is a Trusted Player

User.permission

Note

Deprecated: 0.4.x

type: Number

A convenience shortcut for the permission level of the current User

User.permissions

type: Object

A convenience shortcut for the permissions object of the current User

User.setPermission(permission, allowed)

Sets a user’s permission Modifies the user permissions to grant or restrict access to a feature.

Arguments:
  • permission (String) – The permission name from USER_PERMISSIONS
  • allowed (Boolean) – Whether to allow or restrict the permission
User.targets

type: Set.<Token>

Track references to the current set of Tokens which are targeted by the User


The Users Collection

class Users()

The collection of User entities which is accessible through game.users. The array of User entities within this collection is accessible through game.users.entities.

Users.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
Users.Collection.remove(id)

Remove an Entity from the Collection by its ID.

Arguments:
  • id (String) – The entity ID which should be removed
Users.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;

Users.object

Elements of the Users collection are instances of the User class

Users.players

Get the users with player roles


The Player Config Application

class PlayerConfig(user, options)

The Player Configuration application provides a form used to allow the current client to edit preferences and configurations about their own User entity.

Arguments:
  • user (User) – The User entity being configured.
  • options (Object) – Additional rendering options which modify the behavior of the form.
PlayerConfig.activateListeners(html)

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

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

type: Object

Assign the default options which are supported by the entity edit sheet

PlayerConfig.getData()

Provide data to the form

Returns:Object – The data provided to the template when rendering the form