UGantrySetting
One thing a player can set, such as mouse sensitivity, window mode or a key binding.
Gantry provides the shapes: Number Setting (a slider), Choice Setting (a list), Toggle Setting (a check box), Action Setting (a button) and Key Binding Setting. Gantry also does the bookkeeping around them: change events, conditions, apply, revert and saving. What each setting means, and where its value lives, is up to your game.
You add a setting to a settings page, and you choose where its value lives in one of three ways. You can mix them freely on one page:
- Leave it alone. The value is kept in the player's save under the setting's Id. This is all a game-only setting (a sensitivity, a crosshair colour) needs.
- Subclass a shape in Blueprint or C++. Override Read Value and Write Value to say where the value lives, Get Options for a choice's options, and Gather Edit State for when it is disabled.
- Bind functions in C++ (BindValue, BindOptions, BindEditState, BindApply) on settings that a settings provider (
UGantrySettingsProvider) builds for each player.
Each local player has their own copy of every setting, owned by their settings registry. A new value takes effect as soon as it is set, so the game shows it at once. The registry remembers each value as it was when changes were last applied: Apply Changes keeps the new values, and Revert Changes puts the old ones back.
- Inherits
UObject
Properties
| Property | Type | Default | Description |
|---|---|---|---|
Id read-only | FName | None | Name unique among all of a player's settings, for code and saved values, e.g. "Video.WindowMode". |
DisplayName read-only | FText | What the player reads. | |
Description read/write | FText | One or two sentences on what it does, for a details panel or a tooltip. Writable from Blueprint, so a provider can describe the settings it makes. | |
Presentation read-only | FGameplayTag | () | A tag telling your settings screen how to draw this setting when its shape is not enough, such as a colour picker or a calibration screen. The tag is your game's own; Gantry never reads it. Leave it empty to draw the setting by its shape (number, choice, toggle, action). |
Tags read-only | FGameplayTagContainer | () | Free-form tags a game's settings screen can use: grouping, a "requires restart" marker, filters. |
DependsOn read-only | TArray<FName> | Ids of settings whose changes can change this one's state or options. This setting is told when they change. | |
Conditions read-only | TArray<TObjectPtr<UGantrySettingCondition> > | Conditions that hide or disable the setting. All of them apply. | |
bAppliesUserSettings read-only | bool | False | Whether the engine's user settings (UGameUserSettings) must be applied and saved for a change to take effect. The registry applies them once for every such setting that changed. |
bNeedsVideoConfirm read-only | bool | False | Whether a change to this setting changes the display, such as window mode or resolution. The player must then confirm the change before Video Confirm Seconds run out, or it reverts. Needs Applies User Settings. |
OnChanged | FGantryOnSettingChanged | () | Fired when the value changes. |
Registry | TObjectPtr<UGantrySettingsRegistry> | None |
Functions
GatherEditState
The setting's own contribution to its edit state: hide it, disable it with a reason, or disable some options.
The default allows everything.
| Pin | Type | Direction | Description |
|---|---|---|---|
State | FGantrySettingEditState | out | The state so far; change it in place. |
GetEditState
Whether the setting can be seen and changed now, and if not, why not.
| Pin | Type | Direction | Description |
|---|---|---|---|
| Return Value | FGantrySettingEditState | out | The combined answer of Gather Edit State, then the bound edit state, then every condition. |
GetLocalPlayer
| Pin | Type | Direction | Description |
|---|---|---|---|
| Return Value | ULocalPlayer* | out | The local player whose setting this is; null when the registry has none (tests, the editor). |
GetRegistry
| Pin | Type | Direction | Description |
|---|---|---|---|
| Return Value | UGantrySettingsRegistry* | out | The registry this setting belongs to; null on the copy in a page asset. |
K2_OnApplied
Blueprint: the setting's value has just been applied.
NotifyChanged
Announces a change.
Fires this setting's On Changed, then the registry's On Setting Changed, and tells the settings that depend on this one. The shapes call it when their value is set. Call it yourself when the value changed somewhere else, such as a window resized by hand.
| Pin | Type | Direction | Description |
|---|---|---|---|
Reason | EGantrySettingChangeReason | in | Why it changed. |
C++
Public C++ members that Blueprint does not see.
FEditStateFunction
using UGantrySetting::FEditStateFunction = TFunction<void>
Native edit state: narrows the setting's state in place.
Initialize
virtual void Takes the setting into a registry: remembers the registry and the current value.
Called by the registry on its own copy; never on the copy in a page asset.
StoreInitial
virtual void Remembers the current value as the one Revert returns to.
RestoreToInitial
virtual void Puts back the value remembered by StoreInitial.
ResetToDefault
virtual void Sets the default value, when the setting has one.
IsDirty
virtual bool Whether the value differs from the one StoreInitial remembered.
HasDefault
virtual bool Whether the setting has a default to reset to.
Apply
virtual void Makes a changed value stick.
The registry calls it for each changed setting during Apply Changes, before anything is saved. Runs the bound apply function, then On Applied.
GetDependencies
virtual void The ids of other settings whose changes can change this one's state or options: Depends On, and the conditions'.
BindEditState
void C++: narrows the edit state with a function, after Gather Edit State and before the conditions.
BindApply
void C++: runs a function when a change to this setting is applied, before On Applied.