.._itemAPI:

The Item Entity

Item entities represent objects or features that are owned by an Actor. While the term item tends to imply physical possessions, as a developer in Foundry Virtual Tabletop you should consider Items as the building block for anything that can be owned by an Actor. For example, in the D&D5e system, Item types are used for Classes, Spells, and Feats in addition to standard inventory and equipment.

The FVTT framework provides core APIs for manipulating and modifying Items including support to allow Items to belong to an Actor to modify the Actor’s owned version of that Item.

There are several important API layers which are useful when working with Items. The Items() collection has all of the Item() instances which are defined at the World level (as oppoosed to owned items which belong to a specific actor). This Items collection is available under game.items.

The Item() class represents a single item which may be unowned (and defined at the World level) or owned (and defined at the Actor level). Owned items which belong to an Actor() are defined in that actor’s data model under actor.data.items. The Item() class may be overridden by a system or module by defining the Config.Item.entityClass global configuration value.

When viewing or interacting with an item’s data, the item is rendered and edited using the ItemSheet() class which can be extended or overridden by systems or modules. To override the default implementation, a mod should define the CONFIG.Item.sheetClass global configuration value.


The Item Class

class foundry.Item()

The Item entity. This base Item refers primarily to items which are not currently owned.

foundry.Item.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.Item.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.Item.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.Item.createOwned(itemData, actor)

A convenience constructor method to create an Item instance which is owned by an Actor

Arguments:
  • itemData (Object) –
  • actor (Actor) –
foundry.Item.hasPerm(args)

Override the standard permission test for Item entities as we need to apply a special check for owned items OwnedItems have permission that the player has for the parent Actor.

Returns:Boolean – Whether or not the user has the permission for this item
foundry.Item.isOwned

A flag for whether the item is owned by an Actor entity

foundry.Item.limited

A boolean indicator for whether the current game user has ONLY limited visibility for this Entity.

foundry.Item.update(data, options)

Extend the base Entity update logic to update owned items as well. See Entity.update for more complete API documentation

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

Promise – A Promise which resolves to the updated Entity


The Items Collection

class Items()

The Collection of Item entities The items collection is accessible within the game as game.items

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

Remove an Entity from the Collection by its ID.

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

Items.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;

Items.Collection.render(args)

Re-render any currently visible applications associated with this Collection

Items.object

Elements of the Items collection are instances of the Item class, or a subclass thereof

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

Items.registeredSheets

type: Array

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

Items.unregisterSheet(args)

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


The Item Sheet

class ItemSheet(item, options)

The default Item Sheet

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

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

Arguments:
  • item (Item) – The Item instance being displayed within the sheet.
  • options (Object) – Additional options which modify the rendering of the item.
  • options.editable (Boolean) – Is the item editable? Default is true.
ItemSheet.activateListeners(html)

Activate listeners which provide interactivity for item sheet events

Arguments:
  • html (jQuery) – The HTML object returned by template rendering
ItemSheet.actor

type: Actor

The Actor instance which owns this item. This may be null if the item is unowned.

ItemSheet.defaultOptions

type: Object

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

ItemSheet.getData()

Customize the data provided to the item sheet for rendering. By default we just duplicate the item data.

ItemSheet.id

type: String

Provide a unique CSS ID for owned Item sheets

ItemSheet.item

type: Item

A convenience reference to the Item entity