Skip to content

Developing a System Module

Jump to bottom
Larkinabout edited this page Apr 9, 2023 · 42 revisions

Introduction

Token Action HUD is a Foundry VTT application generated by two modules: the Token Action HUD Core module and a dedicated Token Action HUD system module (e.g., Token Action HUD D&D5e for the D&D 5e system).

Token Action HUD Core module (TAH Core)

TAH Core drives the Token Action HUD application. It provides base classes for Token Action HUD system modules to extend. The HTML templates and CSS styles are part of TAH Core. TAH Core is also responsible for building out all of the subcategories and actions that are common to all Foundry VTT systems: compendiums, macros and actions such as making a token visible/invisible and adding tokens to the combat tracker.

Token Action HUD system modules (TAH system module)

TAH system modules are responsible for building out the subcategories and actions related to the system. They also define the base layout of the HUD as well as the system-defined subcategories available to the user.

A TAH system module will have the following at a minimum:

  • An ActionHandler class, which extends TAH Core's ActionHandler class.
  • A RollHandler class, which extends TAH Core's RollHandler class.
  • A SystemManager class, which extends TAH Core's SystemManager class.
  • A callback handler for TAH Core's tokenActionHudCoreApiReady hook.
  • A tokenActionHudSystemReady hook to pass its SystemManager class and its required core module version to TAH Core.
  • A required core module version.

System Module Classes

ActionHandler

Extends TAH Core's ActionHandler class and builds system-defined actions for the HUD.

Required Methods

  • buildSystemActions(character, subcategoryIds): Called by TAH Core to initiate the build of system-defined actions by the TAH system module.

RollHandler

Extends TAH Core's RollHandler class and handles action events triggered when an action is clicked.

Required Methods

  • doHandleActionEvent(event, encodedValue): Called by TAH Core to initiate the handling of action events by the TAH system module.
    • event: The event.
    • encodedValue: The encoded value stored against the button.

Example:

  1. The 'Club' action is clicked on the HUD.
  2. TAH Core calls the TAH system module's doHandleActionEvent method and passes event and encodedValue (e.g., 'item|lbeVmFOH3ZzSRn7V').
  3. The TAH system module decodes encodedValue into its component parts using encodedValue.split(this.delimiter) and passes the result into the variables: actionType and actionId.
  4. The component parts are resolved using if and switch functions to identify the action as an item use.
  5. The item object is retrieved from the actor object using coreModule.api.Utils.getItem(this.actor, actionId).
  6. The item object's use method is called.

SystemManager

Extends TAH Core's SystemManager class and used by TAH Core to register the TAH system module's extended classes. This class must be passed from the TAH system module to TAH Core via the 'tokenActionHudSystemReady' hook. TAH Core will then call the following TAH system module methods:

Required Methods

  • doGetActionHandler: Initialise and return the system module's ActionHandler.
  • doGetCategoryManager: Intialise and return the system module's CategoryManager, or the CoreCategoryManager.
  • doGetRollHandler: Initialise and return the system module's RollHandler.
  • doRegisterDefaultFlags: Register the system module's default HUD layout and available subcategories.
  • doRegisterSettings: Register the system module's settings.
  • getAvailableRollHandlers: Return a list of available roll handlers.

tokenActionHudCoreApiReady hook

To extend TAH Core's classes, the TAH system module classes must be wrapped in a callback handler for TAH Core's tokenActionHudCoreApiReady hook. The hook passes TAH Core's module api enabling the TAH system module to access TAH Core's classes and utils. This example code shows the expected format:

export let SystemManager = null

Hooks.once('tokenActionHudCoreApiReady', async (coreModule) => {
    SystemManager = class SystemManager extends coreModule.api.SystemManager {
        // CODE
    }
})

tokenActionHudSystemReady Hook

A call of the tokenActionHudSystemReady hook to pass its SystemManager class and its required core module version to TAH Core. This example code shows the expected format:

import { SystemManager } from './system-manager.js'
import { MODULE, REQUIRED_CORE_MODULE_VERSION } from './constants.js'

Hooks.once('ready', async () => {
    const module = game.modules.get(MODULE.ID)
    module.api = {
        requiredCoreModuleVersion: REQUIRED_CORE_MODULE_VERSION,
        SystemManager
    }
    Hooks.call('tokenActionHudSystemReady', module)
})

requiredCoreModuleVersion

This is the required core module version in the format: Major.Minor or Major.Minor.Patch, e.g., 1.1. TAH Core's module version is in the format: Major.Minor.Patch, however patch releases should never include breaking changes, therefore Major.Minor should suffice and allow for easy updating of TAH Core patch releases without requiring a corresponding TAH system module release.

Token Action HUD Core Classes

ActionHandler

Builds the action list and saves the HUD's actions to the actor.

Available Variables

  • actor: Object. The actor object.
  • characterName: String. The actor's character name.
  • delimiter: String. The delimiter character for using in the action's encodedValue. The default is |.
  • token: Object. The token object.

Available Methods

  • addSubcategoryToActionList(parentSubcategoryData, subcategoryData, update = false): Add a subcategory to the action list under the given parent subcategory.
    • parentSubcategoryData: { id, type }
      • id: The parent subcategory id, e.g., 'inventory'.
      • type: The parent subcategory type: 'system' or 'system-derived'.
    • subcategoryData: { id, type, advancedCategoryOptions, hasDerivedSubcategories, isSelected, info1, info2, info3, subtitleClass }
      • id: The subcategory id, e.g., 'weapons'.
      • name: The subcategory name as displayed on the HUD.
      • type: The subcategory type: 'system' or 'system-derived'.
      • advancedCategoryOptions: Optional. { characterCount, showTitle }
        • characterCount: Optional. The number of characters to show for each action's name within the subcategory.
        • showTitle: Optional. Whether to show the subcategory title on the HUD: true or false.
      • hasDerivedSubcategories: Optional. Whether the subcategory has derived subcategories of its own: true or false.
      • isSelected: Optional. Whether the subcategory is selected on the HUD: true or false.
      • info1, info2, info3: Optional. { class, text, title }
        • class: Optional. The CSS class applied to the DIV.
        • text: The text.
        • title: Optional. The title applied to the DIV.
      • subtitleClass: The CSS class applied to the DIV.
    • update: Whether to update existing subcategories. Default is false.
  • addActionsToActionList(actions, subcategoryData): Add a list of actions to the action list under the given subcategory.
    • actions = [{ id, name, encodedValue, cssClass, info1, info2, info3, selected }]: The list of actions.
      • id: The action id. Most commonly the item id.
      • name: The action name displayed on the button.
      • encodedValue: The value passed to the RollHandler when an action is clicked.
      • cssClass: Optional. The CSS class applied to the button.
      • icon: Optional. The icon displayed on the button in HTML format, e.g., <i class="fas fa-plus" title="Bonus"></i>.
      • img: Optional. The image displayed on the button. See Utils#getImage for respecting TAH Core's 'Display Icons' module setting.
      • info1, info2, info3: { class, text, title }
        • class: Optional. The CSS class applied to the DIV.
        • text: The text.
        • title: Optional. The title applied to the DIV.
      • selected: Optional. Whether the action is selected in the HUD: true or false.
    • subcategoryData = { id, type }: The subcategory data.
      • id: The subcategory id.
      • type: The subcatgegory type.
  • addSubcategoryInfo(subcategoryData): Add subcategory info to an existing subcategory.
    • subcategoryData = { id, type, info }: The subcategory data.
      • id: The subcategory id.
      • type: The subcategory type.
      • info = { info1, info2, info3 }: The subcategory info object.
        • info1|info2|info3 = { class, text, title }: The subcategory info.
          • class: The CSS class.
          • text: The text.
          • title: The tooltip.

ActionListExtender

Extends the ActionHandler with the extendActionList method.

CategoryManager

Manages categories and subcategories and saves the HUD's categories and subcategories to the user.

PreRollHandler

Handles action events before passing to the TAH system module.

RollHandler

Registers key presses, handles core-defined actions and calls the TAH system module's RollHandler#doHandleActionEvent.

Available Methods/Variables

  • actor: Object. The actor object.
  • alt: Boolean. Whether the ALT key was pressed when the button was clicked.
  • ctrl: Boolean. Whether the CTRL key was pressed when the button was clicked.
  • delimiter: String. The delimiter character for using in the action's encodedValue. The default is |.
  • doRenderItem(actor, itemId): Renders the item's sheet.
    • actor: The actor object.
    • itemId: The item's id.
  • isRenderItem(): Returns a boolean for whether the item sheet can be rendered.
  • rightClick: Boolean. Whether the button was right-clicked.
  • shift: Boolean. Whether the SHIFT key was pressed when the button was clicked.
  • token: Object. The token object.

SystemManager

Intialises core and system classes.

Utils

Provides common functions.

Available Methods

  • checkAllow(userRole): Returns a boolean for whether the user is allowed to use the HUD.
    • userRole: The user role as obtained with game.user.role.
  • deepClone(original, options): A copy of Foundry VTT's deepClone function.
  • getActor(actorId, tokenId): Returns the actor object either from the actor id or token id.
    • actorId: The actor id.
    • tokenId: The token id.
  • getImage(entity, defaultImages = []): If the 'Display Icons' module setting is enabled, return the image url from an entity (actor, token, item, etc.).
    • entity: Object or String. The entity object (actor, token, item, etc.) or the URL for the image.
    • defaultImages: Array. A list of default images to not return if the entity uses one.
  • getItem(actor, itemId): Return the item object from the actor.
    • actor: The actor object.
    • itemId: The item id.
  • getToken(tokenId): Return the token object.
    • tokenId: The token id.
  • getControlledTokens(): Returns a list of controlled token objects.
  • getFirstControlledToken(): Returns the first controlled token object.
  • i18n(toTranslate): A shorthand for Foundry VTT's game.i18n.localize() function.
    • toTranslate: The value to translate.
  • isModuleActive(moduleId): Returns a boolean for whther the module is active. moduleId: The module id.
  • getModuleTitle(moduleId): Returns the module's title.
    • moduleId: The module id.
  • getSetting(key, defaultValue = null): Returns the setting's value for the Token Action HUD Core module.
    • key: The setting.
    • defaultValue: The default value to return if the setting does not exist.
  • setSetting(key, value): Sets the setting's value for the Token Action HUD core module.
    • key: The setting.
    • value: The value to set.
  • getUserFlag(key): Returns the user flag's value for the Token Action HUD Core module.
    • key: The flag.
  • setUserFlag(key, value): Sets the user flag's value for the Token Action HUD Core module.
    • key: The flag'
    • value: The value to set.
  • unsetUserFlag(key): Unsets the user flag for the Token Action HUD Core module.
    • key: The flag.

Logger

Logs messages to the console

Available Methods

  • info(message, notify = false): Log an info message to the console.
    • message: The message.
    • notify: Optional. Whether to notify the user.
  • error(message, notify = false): Log an error message to the console.
    • message: The message.
    • notify: Optional. Whether to notify the user.
  • debug(message, data): Log a debug message to the console where the 'Enable Debugging' module setting is enabled.
    • message: The message.
    • data: Optional. The data to include.

CSS Classes

Token Action HUD Core's CSS stylesheets include classes for use within the action's cssClass or action info's class property.

  • active: Used alongside the toggle class to indicate that an action is active.
  • disabled: Indicate that an action is disabled.
  • tah-spotlight: Color an action's info text. Good for spotlighting specific text when there are several on the action.
  • toggle: Indicate that an action is toggleable.

Hooks

forceUpdateTokenActionHud

Hooks.callAll('forceUpdateTokenActionHud')

Call this hook to trigger a Token Action HUD update. Most commonly used in TAH system modules in the RollHandler class to update the HUD after handling an actino event.

Variables

encodedValue

A pipe-separated list of identifiers built by the ActionHandler and resolved by the RollHandler. Most commonly, encodedValue will include an action type to identify how to handle the action and id to identify the source object. For example, an encodedValue of 'item|lbeVmFOH3ZzSRn7V' identifies the action as an item use (item) and the item object lbeVmFOH3ZzSRn7V. The encodedValue is stored as a string within the HTML button value. All handling is done on the system module side.

Terms

This is a list of terms used when developing Token Action HUD.

  • Action List: The data object used to build the HUD.
  • Category/categories: The first row of buttons always visible on the HUD.
  • Derived Subcategories: Subcategories that are nested within another Subcategory and are derived within the ActionHandler.
  • Subcategory/subcategories: The action groups visible when a Category is hovered/clicked.
Clone this wiki locally