Settings
Categories:
Settings are the options a player changes — volume, graphics quality, resolution, accessibility choices. GS_Play lets you declare them as data and handles the rest: applying each one to the engine, saving them, and restoring them next launch.
You do not write loading code, saving code, or apply code. You author what the options are and what each one drives.
For architecture details and the full API, see the Framework API reference.
Contents
Declaring Settings
Settings are authored as data, not code. Create an Options Profile asset and add an option for each thing your game exposes.
Every option carries:
| Field | What it is |
|---|---|
| Key | The name your code and presets use, e.g. audio.master. |
| Display Name | What the player sees. |
| Category | Which page it belongs on — Graphics, Audio, Display, Gameplay, Accessibility, Controls. |
| Description | Tooltip text. |
| Apply target | What it actually does when changed. |
Pick the option kind for the widget you want — a toggle, a slider with min/max/step, a dropdown with labelled entries, or a colour picker.
The apply target is the part worth pausing on. It is what connects the option to the engine: a console variable, the window mode, the resolution, an audio channel’s volume — or nothing at all, if the value is just something your own game code reads.
You can assign more than one profile. They merge by key, so a project can layer its own options over a supplied set.
In a dropdown, the label is not the value
Each dropdown entry has a Label the player sees and a Value that gets stored and applied. When you write a preset, use the value.Reading and Writing Settings
Setting a value applies it, saves it and notifies listeners in one call. You never have to apply or save separately.
| Need | Method |
|---|---|
| Read a value | GetOptionBool / GetOptionFloat / GetOptionInt / GetOptionString |
| Change a value | SetOptionBool / SetOptionFloat / SetOptionInt / SetOptionString |
| Restore one option | ResetToDefault |
| Restore everything | ResetAllToDefault |
| Get every option in a category | GetOptionsByCategory |
| React to any change | OnOptionChanged on the notification bus |
GetOptionsByCategory is how you build a settings screen without hard-coding it — ask for the Graphics options and build a row per key.
A tip worth taking: the ImGui debug menu renders your entire option catalog live, with the right widget for each option. Author an option, press play, and drive it before you build any UI for it.
Presets
A preset is a named set of values — Low, Medium, High. Create a preset asset, list the keys it sets and the values it sets them to, and assign it to the Options Manager.
Applying a preset overwrites those options, applies and saves in one action.
Presets have no state of their own. A preset counts as active only while every value it names still matches, so the moment a player nudges one slider, the active preset becomes Custom. That is the familiar behaviour, and it happens for free.
Quick Reference
| Need | Bus | Method / Event |
|---|---|---|
| Read a setting | OptionsManagerRequestBus | GetOptionFloat / Bool / Int / String |
| Change a setting | OptionsManagerRequestBus | SetOptionFloat / Bool / Int / String |
| Restore one setting | OptionsManagerRequestBus | ResetToDefault |
| Restore everything | OptionsManagerRequestBus | ResetAllToDefault |
| List a category’s options | OptionsManagerRequestBus | GetOptionsByCategory |
| Apply a preset | OptionsManagerRequestBus | ApplyPreset |
| Know which preset is active | OptionsManagerRequestBus | GetActivePresetName |
| React to a setting change | OptionsManagerNotificationBus | OnOptionChanged |
Glossary
| Term | Meaning |
|---|---|
| Options Profile | An asset declaring the settings a game exposes |
| Apply Target | What an option does to the engine when its value changes |
| Key | The stable name a setting is stored and referred to by |
| Preset | A named set of values, e.g. Low / Medium / High |
| Custom | The active preset name when values no longer match any preset |
See Also
For the full API:
For related systems:
- The Basics: Options & Input — the input half of GS_Options
- The Basics: Debugging — the live options editor
Get GS_Core
GS_Core - Explore this gem on the product page and add it to your project.