ClientSettings - Foundry Virtual Tabletop Developer API

ClientSettings

A class responsible for managing defined game settings or settings menus. Each setting is a string key/value pair belonging to a certain package and a certain store scope.

When Foundry Virtual Tabletop is initialized, a singleton instance of this class is constructed within the global Game object as as game.settings.

Constructor

new ClientSettings()

See:

Members

menus :Map

Registered settings menus which trigger secondary applications

Type:

settings :Map

A object of registered game settings for this scope

Type:

sheet

Return a singleton instance of the Game Settings Configuration app

storage

The storage interfaces used for persisting settings Each storage interface shares the same API as window.localStorage

Methods

get(module, key)

Get the value of a game setting for a certain module and setting key

Example

// Retrieve the current setting value
game.settings.get("myModule", "myClientSetting");

Parameters:

Name	Type	Description
`module`	string	The module namespace under which the setting is registered
`key`	string	The setting key to retrieve

register(module, key, data)

Examples

// Register a client setting
game.settings.register("myModule", "myClientSetting", {
  name: "Register a Module Setting with Choices",
  hint: "A description of the registered setting and its behavior.",
  scope: "client",     // This specifies a client-stored setting
  config: true,        // This specifies that the setting appears in the configuration view
  type: String,
  choices: {           // If choices are defined, the resulting setting will be a select menu
    "a": "Option A",
    "b": "Option B"
  },
  default: "a",        // The default value for the setting
  onChange: value => { // A callback function which triggers when the setting is changed
    console.log(value)
  }
});

// Register a world setting
game.settings.register("myModule", "myWorldSetting", {
  name: "Register a Module Setting with a Range slider",
  hint: "A description of the registered setting and its behavior.",
  scope: "world",      // This specifies a world-level setting
  config: true,        // This specifies that the setting appears in the configuration view
  type: Number,
  range: {             // If range is specified, the resulting setting will be a range slider
    min: 0,
    max: 100,
    step: 10
  }
  default: 50,         // The default value for the setting
  onChange: value => { // A callback function which triggers when the setting is changed
    console.log(value)
  }
});

Parameters:

Name	Type	Description
`module`	string	The namespace under which the setting is registered
`key`	string	The key name for the setting under the namespace module
`data`	Object	Configuration for setting data

registerMenu(module, key, data)

Example

// Define a settings submenu which handles advanced configuration needs
game.settings.registerMenu("myModule", "mySettingsMenu", {
  name: "My Settings Submenu",
  label: "Settings Menu Label",      // The text label used in the button
  hint: "A description of what will occur in the submenu dialog.",
  icon: "fas fa-bars",               // A Font Awesome icon used in the submenu button
  type: MySubmenuApplicationClass,   // A FormApplication subclass which should be created
  restricted: true                   // Restrict this submenu to gamemaster only?
});

Parameters:

Name	Type	Description
`module`	string	The namespace under which the menu is registered
`key`	string	The key name for the setting under the namespace module
`data`	Object	Configuration for setting data

(async) set(module, key, value)

Set the value of a game setting for a certain module and setting key

Example

// Update the current value of a setting
game.settings.set("myModule", "myClientSetting", "b");

Parameters:

Name	Type	Description
`module`	string	The module namespace under which the setting is registered
`key`	string	The setting key to retrieve
`value`	any	The data to assign to the setting key