Namespace documents

Document definitions used throughout the Foundry Virtual Tabletop framework. The Document class represents a discrete entry in the server-side database.

Document Subclasses

Foundry has over 30 distinct Document types, each of which is available in the global namespace. However, the typical system only needs to customize a handful of them (Actor and Item being the most typical), while the rest can be left alone.

Subclassing a document is as simple as extending the class and replacing the reference in CONFIG.

class MyActor extends Actor {}

Hooks.once("init", () => {
  CONFIG.Actor.documentClass = MyActor;
});
Copy

The advantage of subclassing a document is you can adjust the behavior of core functions, such as actor.getRollData(), the function generally used to populate roll paths (e.g. 1d20 + @abilities.str.mod in dnd5e). By default, this function only returns a reference to the system property of the actor, but by subclassing it we can add in more information.

class MyActor extends Actor {
  getRollData() {
    const rollData = { ...this.system, flags: this.flags };

    return rollData;
  }
}
Copy

Now, in addition to the system information, users can access anything stored in flags with @flags.key.value! There are many other functions in the core software which are written with subclassing in mind, which you can find through the official API documentation.

Some important limitations of document subclassing:

• You can only register one document class per document type; the following section, document subtypes, covers how you can have varied behavior
• You cannot modify the database-backed schemas of documents; custom properties must go inside of flags or system (if available).
• You cannot define new document types beyond those defined by the core software.

Document Subtypes

While there can only be one registered document class per document type, there can be any number of registered document subtypes. A document subtype is a way to establish categories of documents, such as "character" or "npc". Eleven document types currently support subtypes; that is to say, they have a paired "type" and "system" field (a few others, like RollTable, have a type field but these cannot be customized or extended by community packages and do not have a corresponding system field).

• ActiveEffect
• Actor
• Card
• Cards
• ChatMessage
• Combat
• Combatant
• CombatantGroup
• Item
• JournalEntryPage
• RegionBehavior

You don’t need to implement your own subtypes for each of these; most systems only need to specify subtypes for Actor and Item. The rest, without registered subtypes, will default to type: "base".

Registering a subtype is done in the "documentTypes" property of system.json

  "documentTypes": {
    "Actor": {
      "character": {},
      "npc": {}
    },
    "Item": {
      "equipment": {},
      "feature": {}
    }
  },
Copy

This informs the server to expect that Actor will have two subtypes: "character" and "npc", while Items will have "equipment" and "feature". Foundry strictly prohibits creating un-registered document subtypes, however systems are not the only ones that can define a subtype — modules are also able to register subtypes. A module-registered subtype is always of the format module-id.subtype.

The second part of defining a document subtype is registering a data model for each subtype. The Data Models page gets into the details of how to fill in these data models, but the following is a good pattern for defining data models. Systems should always subclass TypeDataModel for these purposes (The exception is ActiveEffect subtypes, which should subclass ActiveEffectTypeDataModel).

class CharacterModel extends foundry.abstract.TypeDataModel {
  static defineSchema() {
    return {}
  }
}

const actorConfig = {
  character: CharacterModel
}

Hooks.once("init", () => {
  Object.assign(CONFIG.Actor.dataModels, actorConfig);
});
Copy

The actorConfig object, above, is necessary to associate the names of the subtypes defined in system.json with their data models. That is to say, each Actor with a type of "character" will have a CharacterModel instance for its system property.