Settings menu

The module PulseSettings is a settings menu for the player settings of PulseFoundation. Every setting that a plugin or the game registers (a UPulsePlayerSettings class, a settings collection asset or code) shows up in it without UI code: tabs, sections, a row per setting, a detail panel, apply/revert, reset and key binding with conflict handling. It is built with CommonUI and opens through the UI host of PulseFoundation (UPulseUIPresenter): on the Pulse HUD of PulseGameplay, in the viewport without it, or in the UI of a game with its own presenter.

How settings are registered, their sources, apply modes and conditions are described in the PulseFoundation player settings page.

Opening the menu

  • Blueprint: Open Settings Screen (UPulseSettingsLibrary::OpenSettingsScreen) with the local player controller. It opens the screen class from the project settings on the configured layer of the UI host (Layer, default Pulse.UI.Layer.Menu, which the Pulse HUD puts onto its Main stack) and returns the screen; a screen that is open already is returned as it is.
  • Without the Pulse HUD (UPulseHUDSettings::bEnableHUD off) the default presenter of PulseFoundation adds the screen to the viewport; a game with its own UI host (Project Settings > Pulse > Foundation > UI > Presenter Class) shows it where it shows menus. Without a local player the function logs a warning and returns null.
  • Cheat: PulseSettingsOpen.

Leaving the menu (Back button or the CommonUI back action) with pending changes (settings with apply mode OnApply, such as resolution) asks: Apply, Discard or Stay (a modal of the UI host: Apply is the default answer, Discard a neutral one, Stay the cancel answer of the back key). Closing it in any other way (layer closed, map change) drops pending changes. Without a UI host for the player the screen does not ask: it closes and drops the changes, resets a tab and swaps keys right away. A UI host that cannot show a modal answers Cancel, and the screen honours it with a warning in the log: no reset, and Back keeps it open while changes are pending (a key in use is still swapped when such a host gives no answer at all).

Layout

Part Comes from
Tabs The categories directly below Pulse.SettingCategory (Gameplay, Video, Audio, Controls, Interface, Accessibility, own ones). Tabs without visible settings are hidden.
Sections Deeper categories (Pulse.SettingCategory.Interface.HUD is the section HUD of the tab Interface), shown as a header.
Rows One UPulseSettingEntry per setting, in the order of the registry (sort order, then name). Rows are pooled.
Detail panel Name and description of the hovered or focused row.

Default widgets

The defaults live in /PulseGameplay/Settings/. Derive from them (or from the C++ classes) to restyle the menu; all logic is in C++, the Blueprints only hold the layout.

Widget Class Job
W_PulseSettingsScreen UPulseSettingsScreen The screen.
W_PulseSettingEntry UPulseSettingEntry A row (every value type).
W_PulseKeyCapture UPulseKeyCaptureWidget “Press a key” prompt on the Modal layer of the UI host.
W_PulseSettingsButton UPulseHUDTextButton Button with text (footer, row controls), theme role Pulse.UI.Button.Secondary.
W_PulseSettingsTab UPulseHUDTextButton Tab button (TabButtonClass), theme role Pulse.UI.Button.Tab.

All defaults use Pulse Style roles of the UI theme (PulseFoundation), so the theme changes their look; buttons set their role with StyleRole (the Apply button Pulse.UI.Button.Primary, row arrows and Reset Pulse.UI.Button.Icon). Section headers use SectionTextStyle, or the theme role Pulse.UI.Text.Heading when it is empty, also after a theme change.

Screen (UPulseSettingsScreen)

Named widgets the screen binds (all optional except the first two):

Name Type Use
TabPanel panel (horizontal or vertical box) Receives the tab buttons (TabButtonClass, spacing TabPadding).
EntryPanel panel (vertical box) Receives section headers (SectionTextStyle, SectionPadding) and rows.
EntryScrollBox scroll box Scrolls the focused row into view.
ApplyButton, RevertButton common buttons Enabled while there are pending changes.
ResetButton common button Asks, then sets the settings of the shown tab back to their defaults.
BackButton common button Same as the back action.
DetailNameText, DetailDescriptionText text blocks Detail panel.
RestartHint any widget Shown while pending changes need a restart.
EmptyHint any widget Shown when no setting is registered.

Class settings: EntryClass (row for every type), EntryClassOverrides (row class per value type, e.g. a color picker for Color), KeyCaptureClass, KeyCaptureLayer (layer of the UI host of the key prompt, default Pulse.UI.Layer.Modal), bManageInput / InputPriority (adds a menu input context through the input manager while the screen is open). Blueprint: GetSettings (the UMVVMPulseSettings view model), SelectTab, ApplyChanges, RevertChanges, ResetSelectedTab, RequestClose, ShowDetails, CaptureKey, event On Tab Selected.

Values that are not applied. Apply checks every pending value with its source first. A value the source does not take (an invalid key, a resolution it cannot parse) stays pending; a value whose source has nothing to write to, or that fails while it is written, is dropped. Both are reported: the screen shows a notification “Not applied” with the text of the result (GetLastApplyResult of the view model, details FPulseSettingsApplyReport), also after a reset of a tab (notifications of the UI host, ShowNotification). Leaving with Apply keeps the screen open while values are still pending, so the player can change them or choose Discard. The restart hint after Apply only appears when a written setting needs a restart. Key settings take an empty value or None as “unbound”. Assigning a key that another setting uses swaps both in one change (Pulse::Settings::Menu::AssignKey): when either value is refused, neither is written.

Row (UPulseSettingEntry)

One row class handles every value type: it shows the parts that fit the setting and collapses the others, so one Blueprint styles all rows.

Name Type Shown for
NameText, ValueText text blocks All (the value text is hidden when a button shows the value).
PendingIndicator any widget Value changed but not applied yet.
ResetButton common button Value differs from the default.
ToggleButton UPulseHUDTextButton Bool: a click toggles, the text shows On/Off.
Slider slider Int and Float with a range.
PreviousButton, NextButton common buttons Options (previous/next option) and numbers without slider (one step).
KeyButton UPulseHUDTextButton Key: a click asks for a new key, the text shows the key.

Disabled settings (a condition with effect Disable) are shown disabled, hidden ones are collapsed. The event On Setting Refreshed runs after every change, for own parts. GetSetting returns the UMVVMPulseSetting of the row.

Key bindings

A click on KeyButton opens W_PulseKeyCapture on the layer KeyCaptureLayer of the UI host (Modal by default); the capture starts before the prompt is activated (the setup of OpenWidgetOnLayer). The next key, mouse button or gamepad button is taken (bAllowMouseButtons, bAllowGamepadKeys); CancelKeys (Escape and the gamepad menu button by default) and the back action cancel. If another key setting already uses the key, the menu asks whether to swap the keys, so both stay bound. In code: Pulse::Settings::Menu::FindKeyConflict and AssignKey.

The three questions of the screen are requests of the UI host built in Pulse::Settings::Menu: MakePendingChangesRequest (answers Confirm, ActionDiscard = Discard, Cancel; ToPendingChangesAnswer turns them into Apply, Discard or Stay), MakeResetRequest and MakeKeyConflictRequest (only Confirm resets or swaps).

Project settings

Project Settings > Pulse > Gameplay > Settings Menu (UPulseSettingsMenuSettings):

Setting Default Meaning
ScreenClass W_PulseSettingsScreen Screen that Open Settings Screen opens.
Layer Pulse.UI.Layer.Menu Layer of the UI host the screen opens on; empty is Menu.
SettingsViewModelClass UMVVMPulseSettings View model the screen creates (category View Models). A child sets SettingViewModelClass and CategoryViewModelClass in its class defaults to give the rows, tabs and sections classes of its own (see the player settings of PulseFoundation). Empty or a class that does not fit uses UMVVMPulseSettings.

Input

  • Back (Escape, gamepad) goes through the CommonUI back action. The project needs CommonUI input data with a back action (Project Settings > Common Input), otherwise CommonUI logs “Cannot create action binding … no action provided” and only the Back button closes the menu. The same applies to PulseGameplay modals.
  • With the input manager enabled (UPulseUISettings::bEnablePlayerInputManager of Pulse Foundation), the screen adds a menu context (cursor shown, UI input) while it is open (bManageInput), and the UI host adds the context of its layer.
  • Gamepad: rows focus their control (toggle, slider, next button, key button); the scroll box follows the focus.

Cheats

Cheat Does
PulseSettingsOpen Opens the settings screen.
PulseSettingsList Prints every player setting with value, type and who registered it.
PulseSettingsSet <setting> <value> Changes a setting like the menu would (pending for OnApply settings), e.g. PulseSettingsSet Pulse.Setting.HUD.ShowCompass false.

In the editor, Pulse.PIE.Exec <instance> <command> (PulseFoundation) runs them as the player of a PIE instance.

Tests

PulseSettings.Keys: finding a key that is already used, assigning, swapping. PulseSettings.ViewModels: the screen’s view model class from the settings, its row class, the fallback to the base classes. PulseSettings.Menu: the questions of the screen and their answers (Apply, Discard, Stay; reset and swap only on Confirm), the default layers, the screen in the viewport with the default presenter of PulseFoundation.


PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.