Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pompom454/tea/llms.txt

Use this file to discover all available pages before exploring further.

The Setting API lets you define player-facing controls that appear in the built-in Settings dialog and persist across sessions via browser storage. Each setting you register adds a corresponding property to the global settings object, which you can read anywhere in your story to branch logic or adjust behavior.
All Setting API calls must be placed in your project’s JavaScript section (Story JavaScript in Twine 2, or a script-tagged passage in Twine 1/Twee). Settings defined outside of that section will not function correctly.

​
The settings object

Every setting registered with the Setting API automatically adds a property to the global settings object. You can read current values from it anywhere in your story: 
// Defined in JavaScript
Setting.addToggle("night", { label: "Night mode?", default: false });

// Used in a passage or script
if (settings.night) {
  $("html").addClass("night-mode");
}
You can write directly to settings properties (e.g. settings.theme = "dark"), but doing so bypasses Setting.save(). Always call Setting.save() manually afterwards, or use Setting.setValue() which calls it for you.

​
Registering settings

​
Setting.addHeader(name [, desc])

Adds a visual section header to the Settings dialog. Headers do not create a settings property.
​
name
string
required
The header’s display text.
​
desc
string
Optional description rendered below the header. May contain markup.
Setting.addHeader("Accessibility");
Setting.addHeader("Audio", "Controls for music and sound effects.");

​
Setting.addToggle(name, definition)

Adds a boolean on/off toggle to the Settings dialog and registers settings[name] as a boolean.
​
name
string
required
The settings property name.
​
definition
object
required
Definition object — see below.
Definition object properties:
​
label
string
required
Label displayed next to the toggle control.
​
desc
string
Additional description shown below the label. May contain markup.
​
default
boolean
Default value. Defaults to false when omitted.
​
onInit
Function
Called once during initialization with a result object as the sole argument and as this.
​
onChange
Function
Called whenever the control value changes with a result object as the sole argument and as this.
Setting.addToggle("mature", {
  label : "Show content for mature audiences?"
}); // default: false

​
Setting.addList(name, definition)

Adds a drop-down list to the Settings dialog and registers settings[name] as the selected member value.
​
name
string
required
The settings property name.
​
definition
object
required
Definition object — see below.
Definition object properties:
​
label
string
required
Label displayed above or beside the list control.
​
list
Array<string>
required
The array of option values. Each member is both a display label and the stored value.
​
desc
string
Additional description. May contain markup.
​
default
string
Default value. Must equal one of the list members. Defaults to the first member when omitted.
​
onInit
Function
Called once during initialization with a result object.
​
onChange
Function
Called whenever the selected option changes.
Setting.addList("difficulty", {
  label   : "Choose a difficulty level.",
  list    : ["Easy", "Normal", "Hard", "INSANE"],
  default : "Normal"
});

​
Setting.addRange(name, definition)

Adds a numeric range slider to the Settings dialog and registers settings[name] as a number.
​
name
string
required
The settings property name.
​
definition
object
required
Definition object — see below.
Definition object properties:
​
label
string
required
Label displayed next to the slider.
​
min
number
required
Minimum value.
​
max
number
required
Maximum value.
​
step
number
required
Increment size. Must divide evenly into max - min.
​
desc
string
Additional description. May contain markup.
​
default
number
Default value. Defaults to max when omitted.
​
onInit
Function
Called once during initialization.
​
onChange
Function
Called whenever the slider value changes.
var volumeHandler = function () {
  SimpleAudio.volume(settings.masterVolume / 10);
};

Setting.addRange("masterVolume", {
  label    : "Master volume.",
  min      : 0,
  max      : 10,
  step     : 1,
  onInit   : volumeHandler,
  onChange : volumeHandler
}); // default: 10 (max)

​
Setting.addValue(name [, definition])

Registers a settings property without adding a visible control to the Settings dialog. Useful for behind-the-scenes values that should persist across sessions.
​
name
string
required
The settings property name.
​
definition
object
Optional definition object — see below.
Definition object properties:
​
default
any
Default value. No type restriction.
​
onInit
Function
Called once during initialization with a result object.
​
onChange
Function
Called whenever the value changes via Setting.setValue().
Setting.addValue("lastPlayed");

Setting.addValue("schemaVersion", {
  default  : 1,
  onInit   : function () {
    // run any schema migration needed
  }
});

​
Result objects

The onInit and onChange callbacks receive a result object as both their sole argument and as this. Its shape mirrors the definition but reflects the current live values:
PropertyTypePresent for
namestringAll types
valueanyAll types
defaultanyAll types
listArray<string>List only
minnumberRange only
maxnumberRange only
stepnumberRange only

​
Reading and writing values

​
Setting.getValue(name) → any

Returns the current value of the named setting. Equivalent to settings[name].
​
name
string
required
The settings property name.
if (Setting.getValue("disableAudio")) {
  SimpleAudio.mute(true);
}

​
Setting.setValue(name, value)

Sets the named setting to a new value and automatically calls Setting.save().
When changing a setting that has an associated control, ensure the value is valid for that control type — e.g. do not set a range-type setting to a string or an out-of-range number.
​
name
string
required
The settings property name.
​
value
any
required
The new value for the setting.
Setting.setValue("theme", "Midnight");
Setting.setValue("masterVolume", 7);

​
Persistence

​
Setting.load()

Loads the settings from storage and applies defaults for any missing properties. Called automatically at startup — you should rarely need to call this manually. 
Setting.load();

​
Setting.save()

Saves the current state of the settings object to storage.
The Settings dialog controls and Setting.setValue() call this automatically. Only call it manually when you write directly to settings properties.
settings.theme = "Charcoal";
Setting.save(); // required when writing directly

​
Setting.reset([name])

Resets a single setting — or all settings — to their default values.
​
name
string
Name of the setting to reset. When omitted, all settings are reset.
Setting.reset("difficulty"); // reset one setting
Setting.reset();             // reset all settings

​
Practical example: full settings panel

// === Story JavaScript ===

// Section header
Setting.addHeader("Display");

// Night mode toggle
var nightModeHandler = function () {
  $("html").toggleClass("night-mode", settings.nightMode);
};
Setting.addToggle("nightMode", {
  label    : "Enable night mode?",
  default  : false,
  onInit   : nightModeHandler,
  onChange : nightModeHandler
});

// Font size range
var fontSizeHandler = function () {
  $("html").css("font-size", settings.fontSize + "px");
};
Setting.addRange("fontSize", {
  label    : "Base font size (pixels).",
  min      : 12,
  max      : 24,
  step     : 2,
  default  : 16,
  onInit   : fontSizeHandler,
  onChange : fontSizeHandler
});

// Section header
Setting.addHeader("Content");

// Difficulty list
Setting.addList("difficulty", {
  label   : "Difficulty level.",
  list    : ["Easy", "Normal", "Hard"],
  default : "Normal"
});

Build docs developers (and LLMs) love

Get started for freeTalk to us