--- title: AFM_Settings product: Advanced Framework Pro version: 1.0 engine: Unreal Engine 5.8 updated: 2026-10-05 canonical: https://docs.human-codeable.com/plugins/afm-settings.html --- Module # AFM_Settings Graphics, audio and gameplay settings built on the state contract, backed by console variables and a save game, with presets for the common console variables. #### What it gives you - A working settings menu with no code - Console-variable and audio-volume setting types - Persistence through a save game - Presets for the standard graphics settings #### Requires None #### Required by None 27 assets59 API members ## Description Settings reuse `AFM_State`'s value contract rather than inventing their own. A setting is a `BP_Value_Settings_*` object exposing `BPI_Value`, so the same `WBP_SettingItem_*` widgets that bind to world state bind to settings too. The practical consequence is that adding a setting is an asset, not code. The plugin ships presets for the common console variables — anti-aliasing, shadows, textures, view distance, foliage, post-process, dynamic resolution, pixel density, fixed foveated rendering — plus volume settings per sound class. ## Setup 1. Enable `AFM_Settings`. 2. Add `BPC_GameState_Settings` to your game state. 3. Register the setting presets you want in its settings list. 4. Add the settings page to your menu — `DA_WidgetPage_Settings_Desktop` is ready to use. [![The settings component on the game state](../images/AFM_Settings_setup-1600.webp?v=fc871a46)](../images/AFM_Settings_setup-1600.webp?v=fc871a46) The settings component on the game state ## Usage ### Adding a setting See [Add a setting](../workflows/add-setting.html). ### Persisting `BP_SaveGame_Settings` handles storage. Values are written on change and restored on startup by the settings component. ### Reading a setting from gameplay Ask the settings component for the value object and read it through `BPI_Value`, rather than reading the console variable directly — this keeps the save game and the live value in step. ## Key properties | Property | When to change | |---|---| | `Name` / `Caption` | Always — the label and helper text in the menu | | Console variable name | On the `_Console` variants, to target a different CVar | | Value mapping | To change how integer steps map to CVar values | ## Extending Derive from the `BP_Value_Settings_*` base matching your type. The correct widget is chosen from the value type automatically. ## Example map The settings page in `Map_Examples_Lobby` is the shipped settings menu. ## Troubleshooting **A setting does not persist.** It is not registered with `BPC_GameState_Settings`; unregistered values work in-session but are never written to the save game. ## API reference Every blueprint asset in this plugin. Expand an asset to see its members. ### Blueprints **BP_Value_Settings**6 members extends `BP_Value` · implements `BPI_Value` Base class for one editable setting: the name and caption a settings row displays, and a reference back to the settings component that made it. Settings are identified by their class, not by an instance you place, so the component creates one object per class and calls Init on it. Subclass one of the typed variants below rather than this directly. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Name`Description | `text` | Heading a setting shows in the interface, handed over whenever a widget asks the setting for its title. Leave empty for a row with no label of its own. | | var | `Caption`Description | `text` | Explanatory line offered under the heading, handed over whenever a widget asks the setting for its caption. Leave empty for a row with a heading alone. | | var | `Settings Component` | `BPC_GameState_Settings` | Owning settings component, filled in as the object is built by Get Object For Settings. Volume settings route their sound changes back through it, so a setting created by hand without one cannot reach the sound mix. | | event | `Init` | `()` | Empty hook run once by Get Object For Settings just after the setting object is built. Override it to read the current value out of wherever the setting really lives, or to bind to whatever the setting mirrors. | | event | `OnObjectRegistered_Event` | `(Object: Object)` | Bound to the settings component and called for each object registered with it. Objects of this setting's Reference Class are added to Reference Objects and Reference Objects Updated is raised; everything else is dropped. This is how a setting finds the components it has to drive without anyone wiring the two together. | | event | `ReferenceObjectsUpdated` | `()` | Raised whenever an object of this setting's Reference Class has registered. Empty here: subclasses override it to push the saved value into whatever has just arrived, which is what lets a setting apply itself to objects that appear long after the game started. | **BP_Value_Settings_Bool**4 members extends `BP_Value_Settings` · implements `BPI_Value_Boolean` Base for an on/off setting, carrying the texts shown for the false and true states and the default that Reset restores. Where the value actually lives is left open: subclass it and override Get Boolean and Set Boolean, or use the console variant, which already stores it in a console variable. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Text False`Description | `text` | Caption offered to widgets for the off position, returned as the first of the pair of texts. Toggles bound to the setting show it while the value reads false. | | var | `Text True`Description | `text` | Caption offered to widgets for the on position, returned as the second of the pair of texts. Toggles bound to the setting show it while the value reads true. | | event | `Value_Reset`Value | `(Source Info: ST_SourceInfo)` | Implemented by a value to put itself back to its configured default. Called on every value of an actor by configurator and settings screens; the colour and drag states deliberately do nothing. | | event | `ReferenceObjectsUpdated` | `()` | Looks this setting's class up in the save game's boolean map and, when an entry is there, applies it through Set Boolean. An object that registers late is brought in line with the saved value instead of keeping its default. A setting that has never been saved does nothing here. | **BP_Value_Settings_Float**11 members extends `BP_Value_Settings` · implements `BPI_Value_Float` Base for a continuous setting: the range the value is stored in, the range, units, segment marks and fractional digits a slider draws itself from, and the default that Reset restores. Reading and writing the value is left to subclasses, so use the console or volume variant, or override Get Float and Set Float yourself. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Value Range`Value | `InputRange` | Real range the console variable or sound mix behind the setting works in. The stored 0 to 1 fraction is mapped onto it when written and normalised back out of it when read; it is not what widgets show, which is Display Range. | | var | `Units`Description | `text` | Suffix widgets append to the displayed number, such as a per cent marker. Leave empty for a bare number. | | var | `Segments`Description | `float[]` | Marks along the slider, given in the numbers of Display Range, that widgets draw as notches. Leave empty for a plain unmarked slider. | | var | `Maximum Fractional Digits`Description | `int` | Largest number of decimal places widgets show for the value, one by default. Presentation only; the stored fraction keeps its full precision. | | var | `Current Value`Value | `float` | Where the setting's value is actually held, as a position from 0 to 1 rather than as the number a reader sees. Normalize Range converts into it and Mapped Value converts back out of it through Value Range, which is what lets a slider be drawn without knowing anything about the real units. | | var | `Default Value`Value | `float` | Value a reset writes back, as the 0 to 1 fraction across Value Range rather than a real reading. It is not applied at start-up, so the setting opens on whatever the console variable or mix already holds. | | var | `Display Range`Description | `InputRange` | Range reported to widgets in place of Value Range, letting a slider read 0 to 100 while the variable behind it works in its own units. The interpolated reading is the stored fraction mapped into it. | | fn | `NormalizeRange` | `(Value: float, out NormalizedValue: float)` | Turns a value expressed in Value Range into the 0 to 1 form Current Value is stored in. Hand it the real number and store what comes back. | | fn | `MappedValue` | `(out MappedValue: float)` | Returns Current Value mapped back into Value Range, which is the number to hand to whatever the setting drives. It reads Value Range and not Display Range: Display Range is what a slider labels itself with. | | event | `ReferenceObjectsUpdated` | `()` | Looks this setting's class up in the save game's float map and, when an entry is there, applies it through Set Float, so an object that registers late arrives at the saved value rather than its default. | | event | `Value_Reset`Value | `(Source Info: ST_SourceInfo)` | Implemented by a value to put itself back to its configured default. Called on every value of an actor by configurator and settings screens; the colour and drag states deliberately do nothing. | **BP_Value_Settings_Integer**4 members extends `BP_Value_Settings` · implements `BPI_Value_Integer` Base for a setting chosen from a numbered list, holding the texts that label each value and the default that Reset restores. The value is not stored here: subclass it and override Get Integer and Set Integer, or use the console variant, which maps the setting onto a scalability cvar. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Texts`Description | `text[]` | Option labels offered to widgets, one per choice, with the value acting as the position in the list. Leave empty for a setting that shows a bare number rather than a named option. | | var | `Default Value`Setting | `int` | Option a reset writes back, as a position in Texts. It is not applied at start-up, so the setting opens on whatever the underlying variable already holds. | | event | `ReferenceObjectsUpdated` | `()` | Looks this setting's class up in the save game's integer map and, when an entry is there, applies it through Set Integer, so an object that registers late arrives at the saved value rather than its default. | | event | `Value_Reset`Value | `(Source Info: ST_SourceInfo)` | Implemented by a value to put itself back to its configured default. Called on every value of an actor by configurator and settings screens; the colour and drag states deliberately do nothing. | **BP_Value_Settings_Name**3 members extends `BP_Value_Settings` · implements `BPI_Value_Name` Base for a setting whose value is one of several named options, holding the IDs, the texts shown for them and the default ID. Current Index reports where the present value sits in the list, and Next Value and Previous Value step through it. Storing the value is left open: subclass it and override Get Value and Set, as the theme setting does. | Kind | Name | Signature | Description | |---|---|---|---| | fn | `CurrentIndex`Default | `(out Index: int)` | Returns the position of the current name in the setting's list of identifiers, which is how selectors know which option to show. The answer is -1 when the current name is missing from that list, including the None a setting reports until a subclass supplies a real one. | | event | `Value_Reset`Value | `(Source Info: ST_SourceInfo)` | Implemented by a value to put itself back to its configured default. Called on every value of an actor by configurator and settings screens; the colour and drag states deliberately do nothing. | | event | `ReferenceObjectsUpdated` | `()` | Looks this setting's class up in the save game's name map and, when an entry is there, applies it through Set Name, so an object that registers late arrives at the saved option rather than its default. | ### Blueprints/Console **BP_Value_Settings_Bool_Console**4 members extends `BP_Value_Settings_Bool` On/off setting stored in a console variable. Reads the variable named in Console Command for its current state and writes the false or true string back as a console command when the player changes it. Subclass it and fill in the command and the two strings to expose any boolean cvar as a setting, as the dynamic resolution preset does. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Console Command`Setting | `string` | Name of the console variable the setting reads and writes, such as a dynamic resolution switch. The variable itself holds the value, so nothing is cached here and a name that matches none reads back as off. | | var | `New String False`Setting | `string` | Argument appended to the console command when the setting is switched off, zero by default. Change it for a variable whose off position is some other word or number. | | var | `New String True`Setting | `string` | Argument appended to the console command when the setting is switched on, one by default. Change it for a variable whose on position is some other word or number. | | event | `Value_setBoolean`Value_Boolean | `(SourceInfo: ST_SourceInfo, Value: bool)` | Implemented by a boolean value to take a new setting from the pawn described by the source info. Buttons call it when their selection changes. | **BP_Value_Settings_Float_Console**2 members extends `BP_Value_Settings_Float` Continuous setting stored in a console variable. Reads the variable named in Console Command and normalises it to 0-1 against Value Range for the slider, then writes the interpolated figure back as a console command when the slider moves. Subclass it with the command and range filled in, as the VR resolution preset does. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Console Command`Setting | `string` | Name of the console variable the setting reads and writes, such as a screen percentage. Its reading is normalised across Value Range on the way in and mapped back onto that range on the way out, so widgets only ever deal in 0 to 1. | | event | `Value_setFloat`Value_Float | `(SourceInfo: ST_SourceInfo, Value: float)` | Implemented by a float value to take a new value from the pawn described by the source info. Sliders call it as their handle moves; the drag state reads the value as 0 to 1 across its own range. | **BP_Value_Settings_Integer_Console**1 members extends `BP_Value_Settings_Integer` Whole-number setting stored in a console variable, and the pattern behind every quality level the framework ships. Reads the variable named in Console Command and writes the new number back as a console command. Subclass it and set the command, the default and the texts naming each level; the graphics presets are all one-liners over this. | Kind | Name | Signature | Description | |---|---|---|---| | event | `Value_setInteger`Value_Integer | `(SourceInfo: ST_SourceInfo, Value: int)` | Implemented by an integer value to take a new value from the pawn described by the source info. Drop-downs call it when one of their options is chosen. | ### Blueprints/SaveGame **BP_SaveGame_Settings**0 members extends `SaveGame` Save game the settings component reads and writes: four maps, one per value type, each keyed by the settings value class so a stored value can be matched back to the setting it belongs to. Created or loaded automatically from the save slot. Subclass it only if a project needs extra fields saved alongside, then name that subclass as Save Game Class. No editor-visible members; this asset configures defaults only. ### Blueprints/Volume **BP_Value_Settings_Float_Volume**1 members extends `BP_Value_Settings_Float` Continuous setting that mixes one sound class. Keeps its level as a plain value and pushes it to the settings component's sound mix as a class override whenever it changes, displayed as a whole number from 0 to 100. Subclass it and choose a Sound Class to add a mix your project needs; the four volume presets are exactly that. | Kind | Name | Signature | Description | |---|---|---|---| | event | `Value_setFloat`Value_Float | `(SourceInfo: ST_SourceInfo, Value: float)` | Implemented by a float value to take a new value from the pawn described by the source info. Sliders call it as their handle moves; the drag state reads the value as 0 to 1 across its own range. | ### Components **BPC_GameState_Settings**21 members extends `ActorComponent` Settings component the whole settings module hangs off. Add it to your game state and the framework has a settings system: it creates one object per settings value class the first time anything asks for it, keeps them in a map, and loads, applies and saves them through a save game in the named slot. Also holds the sound mix that volume settings override and the editor-set default overrides. | Kind | Name | Signature | Description | |---|---|---|---| | var | `Sound Mix Class`Sound | `SoundMix` | Mix whose class overrides carry the volume settings, applied whenever Set Global Sound Volume runs. Leave it unset and the volume settings change nothing, because there is no mix to override. | | var | `Apply Defaults on Startup`Overrides | `class[]` | Setting classes meant to be created and put back to their defaults as play begins. Begin Play is empty here and nothing else in the graph reads the list, so filling it in has no effect on its own; call Load Settings or the apply functions yourself. | | var | `Setting Default Override Boolean`Overrides | `Map, bool>` | Replacement defaults for boolean settings, keyed by setting class, in the shape Apply Settings Boolean takes. Nothing in the graph reads the map, so hand it to that function yourself if you want these values pushed out. | | var | `Save Slot Name`Save | `string` | Slot that saved settings are written to and read back from, always at user index 0. Point it somewhere new after a save and the old values are no longer found; an empty slot causes a fresh save object to be created instead. | | var | `Save Game Class`Save | `class` | Class of save object created when the slot is still empty, holding the four maps of stored values. Leave it unset and no save object can be built, so saving and loading quietly do nothing. | | var | `Setting Default Override Float`Overrides | `Map, float>` | Replacement defaults for float settings, keyed by setting class, given as the 0 to 1 fraction the float settings work in rather than real units. Nothing in the graph reads the map; pass it to Apply Settings Float to push the values out. | | var | `Setting Default Override Name`Overrides | `Map, name>` | Replacement defaults for name settings, keyed by setting class, each value being one of the identifiers that setting offers. Nothing in the graph reads the map; pass it to Apply Settings Name to push the values out. | | var | `Setting Default Override Integer`Overrides | `Map, int>` | Replacement defaults for integer settings, keyed by setting class, each value being an index into that setting's list of options. Nothing in the graph reads the map; pass it to Apply Settings Integer to push the values out. | | fn | `getAllRegisteredObjectsOfClass` | `(Class: class, out FoundObjects: Object[])` | Returns every registered object that is of the given class or a subclass of it. The settings values use it to collect the objects they act on. It walks the whole registered list each time it is called, so hold on to the result rather than asking per frame. | | fn | `SaveAllSettings`Save | `()` | Saves every setting built so far by handing the cached setting classes to Save Settings. Settings that have never been asked for are absent from the cache and so are left out of the save. | | fn | `ApplySettings_Integer`Apply | `(MapPin: Map, int>)` | Writes each stored number into its setting, fetching or creating the setting object for every key in the map. Used by Load Settings to restore the integer settings, with the local player pawn recorded as the source of each change. | | fn | `ApplySettings_Name`Apply | `(MapPin: Map, name>)` | Writes each stored name into its setting, fetching or creating the setting object for every key in the map. Names are not checked against the identifiers a setting offers, so a stale entry in a save is passed on unchanged. | | fn | `ApplySettings_Float`Apply | `(MapPin: Map, float>)` | Pushes each stored float into its setting, fetching or creating the setting object for every key in the map. Values are the 0 to 1 fractions float settings work in, not readings in the real units of Value Range. | | fn | `ApplySettings_Boolean`Apply | `(Settings: Map, bool>)` | Pushes each stored boolean into its setting, fetching or creating the setting object for every key in the map. Changes are reported as coming from the local player pawn under the source name Settings Component, so listeners treat them as an ordinary set. | | fn | `SaveSettings`Save | `(out Settings: class[])` | Reads the current value of every listed setting class through its value interface, records it in the matching map of the save object and writes the whole save object to the slot. Classes that are not boolean, float, name or integer settings are passed over. | | fn | `LoadSettings`Load | `()` | Applies the four maps of saved values out of the save object, building each setting object as it goes. Call it once as play begins; the values are pushed out on the machine that calls it and are recorded as coming from the local player pawn. | | fn | `getSettingsSaveGame` | `(out Save Game Settings: BP_SaveGame_Settings)` | Returns the settings save object, loading it from the slot on first use or creating a fresh one of Save Game Class when the slot is empty, then keeping it for later calls. Nothing comes back when the slot holds a save of some other class, which leaves saving and loading with nothing to work on. | | fn | `getObjectForSettings` | `(Key: class, out SettingObject: BP_Value_Settings)` | Returns the live setting object for a setting class, creating it on first request, running its Init and caching it so later requests share the one instance. The new object is given the settings component as its Settings Component; despite being marked pure it does build objects, so every setting a screen touches ends up in the cache. | | event | `SetGlobalSoundVolume` | `(SoundClass: SoundClass, Volume: float)` | Applies a volume to one sound class by overriding it inside Sound Mix Class. Called by the volume settings each time their value changes; with no mix set the call does nothing. | | event | `ResetAllSettings` | `()` | Runs Value Reset on every setting object built so far, so each writes its own default back through its setter. Settings never requested are untouched and nothing is written to the slot, so follow it with Save All Settings to keep the reset. Called by the Reset button on the settings screen. | | event | `RegisterObjectToSettings` | `(Object: Object)` | Adds an object to the list of things settings may act on and raises On Object Registered so every settings value interested in that class can pick it up. The add is unique, so an object cannot end up in the list twice, though registering it again does raise the event again. | ### Libraries **BFL_Settings**1 members extends `BlueprintFunctionLibrary` Function library for the settings module. Register Object To Settings hands an object to the game state's settings component so it is applied and saved alongside everything else. Call it statically from anything that should take part in settings without owning a value asset of its own. | Kind | Name | Signature | Description | |---|---|---|---| | fn | `Settings_RegisterObjectToSettings` | `(Object: Object, __WorldContext: Object)` | Static shortcut for registering an object with the settings system: it takes any world context object, finds the settings component on the game state and calls Register Object to Settings on it. Use it from an actor that holds no reference to the game state. Both lookups are guarded, so a call made before the game state exists quietly does nothing rather than failing. | ### Presets **BP_Value_Settings_Bool_Console_DynamicResolution**0 members extends `BP_Value_Settings_Bool_Console` Ready-made toggle for dynamic resolution, driving the r.DynamicRes.OperationMode console variable. No shipped settings screen uses it, so point a toggle row at it to offer it to players, or copy it as the pattern for another boolean cvar. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Float_Console_PixelDensity**1 members extends `BP_Value_Settings_Float_Console` Ready-made slider for VR render resolution, driving xr.SecondaryScreenPercentage.HMDRenderTarget between 50 and 150 per cent and shown to the player as 0.5 to 1.5, defaulting to the middle. Used by the desktop graphics tab; copy it and change the ranges if your headset target differs. | Kind | Name | Signature | Description | |---|---|---|---| | event | `Value_setFloat`Value_Float | `(SourceInfo: ST_SourceInfo, Value: float)` | Implemented by a float value to take a new value from the pawn described by the source info. Sliders call it as their handle moves; the drag state reads the value as 0 to 1 across its own range. | **BP_Value_Settings_Float_Volume_Master**0 members extends `BP_Value_Settings_Float_Volume` Ready-made volume setting for the master sound class, so it scales everything else in the mix. Used by the sound tab of the desktop settings screen; point a slider row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Float_Volume_Music**0 members extends `BP_Value_Settings_Float_Volume` Ready-made volume setting for the music sound class. Used by the sound tab of the desktop settings screen; point a slider row at it to put music volume on a screen of your own. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Float_Volume_SFX**0 members extends `BP_Value_Settings_Float_Volume` Ready-made volume setting for the sound effects class. Used by the sound tab of the desktop settings screen; point a slider row at it to put effects volume on a screen of your own. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Float_Volume_UI**0 members extends `BP_Value_Settings_Float_Volume` Volume setting intended for interface sounds, but as shipped it carries the SFX label and the effects sound class, so it duplicates the SFX preset. Nothing references it. Give it a sound class and a name of its own before putting it on a settings screen. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Float_Volume_Voice**0 members extends `BP_Value_Settings_Float_Volume` Ready-made volume setting for the voice sound class. Used by the sound tab of the desktop settings screen; point a slider row at it to put dialogue volume on a screen of your own. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_AntiAA**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for anti-aliasing, driving the sg.AntiAliasingQuality scalability variable and defaulting to level 3. Unlike the other quality presets it is not on the shipped graphics tab, so add a selector row for it if you want it offered. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_Effects**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for effects, driving the sg.EffectsQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_FFR**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for fixed foveated rendering, driving the vr.FixedFoveationLevel variable and defaulting to level 4. Used by the graphics tab of the desktop settings screen. Only meaningful on headsets that support foveation. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_Foliage**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for foliage, driving the sg.FoliageQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_PostProcess**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for post processing, driving the sg.PostProcessQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_ShadowQuality**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for shadows, driving the sg.ShadowQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_Texture**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for textures, driving the sg.TextureQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only. **BP_Value_Settings_Integer_Console_ViewDistance**0 members extends `BP_Value_Settings_Integer_Console` Ready-made quality setting for view distance, driving the sg.ViewDistanceQuality scalability variable and defaulting to level 3. Used by the graphics tab of the desktop settings screen; point a selector row at it to offer it elsewhere. No editor-visible members; this asset configures defaults only.