clientSettings

The client's settings: the person's own on this device for the account signed in, the same in every world, on every platform and in a headset. They are a different thing from a world's own settings: settings is the world's settings file (/zero/source/.world_settings), authored with the world.

• Declared once, by the engine. A group is one tab of the settings menu: clientSettings.registerGroup{ id, title, description, icon, order, visible }, where visible() says whether the tab shows on this client now. Entries name their group: clientSettings.register{ ... }. A setting carries

  • a field its every value is held to (Field.enum, Field.range, Field.bool), whose default is the setting's default; labels names an enum's members, step and format shape a range;
  • a scope: "device" for what depends on this machine, "userPlatform" for what follows the person on this kind of platform;
  • an effect of kind "engine": apply(value) takes the value into the engine (on register, on every change and when the account changes), and changed(value) runs only when the person changes or resets it.

  An action carries no field and no value: its effect is run(), shown as a button. available() on either says whether it can be used now and, when it cannot, why.

  Every word a person reads (title, description, label, button, an enum's labels) is text or { key = "namespace.key", values? }, the catalog message said in the player's language each time the menu is drawn.

• Reading. clientSettings.get(key) is the value the person chose, or the setting's default. clientSettings.list() states every group with each entry's value, default, source ("player" once the person chose one, "default" before), scope, choices or range, and availability; the menu draws exactly that list. A world reads the settings it needs, e.g. clientSettings.get("xr.perspective").

• Changing. clientSettings.set(key, value) holds the value to the field, keeps it and carries out the effect; clientSettings.reset(key | group) returns a setting or a whole group to its defaults; clientSettings.run(key) runs an action. Each is refused with world or agent code on the Luau stack, naming the setting: the person changes their settings in the menu, and a world reads them and never changes them.

• The System tab. The settings show as the System tab of the app menu (appMenu), the menu the pause action opens: every visible group a section, with Reset to defaults on a section where the person chose something. clientSettings.open(group?) opens the menu on that tab, from anywhere, a world's own code included; the editor's Settings… and the gear on its dock in a headset do the same. The tab shows while clientSettings.reachable() is true, that is while some group is visible.

• The groups. VR (xr_menu) shows while this client can draw to a headset; every other group shows in a headset as it does on a desktop.

• Where values are kept. As preferences of the signed-in account on this device (zero_account_prefs, under setting.<key>), whatever the scope; with nobody signed in, the signed-out record. Signing in or out switches to that account's settings and applies them.

clientSettings.onChanged(fn) hears each change, and fn(nil) when the account changes. clientSettings.buildSection(model) returns the System tab's widget tree for a state, laid out for a desktop, a phone or a headset's panel.