Skip to content

Game.UI.Menu.OptionsUISystem

Assembly: Game
Namespace: Game.UI.Menu

Type: class

Base: UISystemBase

Summary:
OptionsUISystem is the UI system that manages the in-game Options/Settings UI. It maintains registered settings pages and sections (including built-in and mod-provided pages), handles searching/filtering of widgets, manages input/layout bindings, a directory browser panel used by some settings, display-confirmation workflow for screen mode/resolution changes, and integration with the modding toolchain notification state. The class contains several nested types that represent the runtime model of the options UI: - Page — a settings page compilation with multiple sections. - Section — a single section (tab) containing options grouped for display. - Option — wrapper for an IWidget plus metadata like visibility/advanced group. - WidgetInfo — compact item used for search results and JSON output. - UnitSettings — a small value type for interface unit preferences (time, temperature, unit system).

Fields

  • private const string kGroup = "options"
    Identifier used for widget bindings group name.

  • private GameScreenUISystem m_GameScreenUISystem
    Cached reference to the Game UI screen system (used when opening options from in-game).

  • private EditorScreenUISystem m_EditorScreenUISystem
    Cached reference to the Editor UI screen system (used when opening options from editor).

  • private MenuUISystem m_MenuUISystem
    Cached reference to the Main Menu UI system (used when opening options from main menu).

  • private bool m_IsAdvanced
    Tracks whether the UI is currently showing advanced options.

  • private string m_SearchQuery
    Current search/filter query string (null/empty when not searching).

  • private List<int> m_SearchIds = new List<int>()
    List of widget ids (WidgetInfo.GetId) matching the current search.

  • private string m_LastLayout
    Cached last keyboard layout name to detect layout changes and update control-path map.

  • private ValueBinding<string> m_ActivePageBinding
    Binding for currently active page id (exposed to UI).

  • private ValueBinding<string> m_ActiveSectionBinding
    Binding for currently active section id (exposed to UI).

  • private GetterValueBinding<List<Page>> m_PagesBinding
    Binding that supplies the sorted list of pages to the UI.

  • private WidgetBindings m_WidgetBindings
    Bindings that hold the current children widgets being displayed in the options panel.

  • private ValueBinding<Dictionary<string, ControlPath>> m_LayoutMapBinding
    Binding that exposes localized keyboard-control name map for UI hints.

  • private ValueBinding<bool> m_DirectoryBrowserActive
    Binding that indicates whether the directory browser panel is active.

  • private WidgetBindings m_DirectoryBrowserBinding
    Bindings used when the directory browser is active (children = directory items).

  • private DirectoryBrowserPanel m_DirectoryBrowser
    Active directory browser instance (can be null).

  • private DirectoryBrowserPanel m_LastDirectoryBrowser
    Last directory browser instance used; used to detect activation changes and switch bindings.

  • private float m_DisplayConfirmationTime
    Timer used for display confirmation (when user changes resolution/display mode).

  • private DisplayMode m_LastDisplayMode
    Saved display mode used to revert if user doesn't confirm changes.

  • private ScreenResolution m_LastResolution
    Saved resolution used to revert if user doesn't confirm changes.

  • private int m_LastDisplayIndex
    Saved display index used to revert if user doesn't confirm changes.

  • private Dictionary<string, Page> pages { get; } = new Dictionary<string, Page>()
    Dictionary mapping page id -> Page model for all registered pages (built-in and from mods).

  • private List<Page> sortedPages => (from p in pages.Values orderby p.builtIn descending, p.index select p).ToList()
    Read-only computed list of pages sorted with built-in pages first and by index.

Properties

  • private Dictionary<string, Page> pages { get; }
    Holds all registered pages keyed by id. Pages are added via RegisterSetting and removed via UnregisterSettings.

  • private List<Page> sortedPages
    Computed sorted list of pages used to present pages in the UI. Built-in pages (page.builtIn == true) appear first then by page.index.

Nested Types (brief)

  • Page
    Model for a settings page. Contains id, index, builtIn flag, beta flag, a warning flag and getter, and a list of Section objects. Methods include UpdateVisibility, UpdateNameAndDescription, UpdateWarning, and Write(IJsonWriter).

  • Section
    Model for a section/tab inside a Page. Holds a list of Option entries, group names, visibility state and per-group visibility. Methods include GetItems(isAdvanced), UpdateVisibility(isAdvanced), UpdateNameAndDescription(isAdvanced), UpdateWarning(isAdvanced), and Write(IJsonWriter). Sections are constructed from AutomaticSettings.SettingPageData.

  • Option
    Simple wrapper holding IWidget widget and metadata: isVisible, isAdvanced, simpleGroupIndex, advancedGroupIndex, searchHidden plus GetGroupIndex(isAdvancedIndex).

  • WidgetInfo (struct)
    Serializable item with id, displayName, visibility flags and helper GetId/GetIndices for packing/unpacking page/section/widget indices into a single int id.

  • UnitSettings (struct)
    Value type capturing interface unit-related preferences (timeFormat, temperatureUnit, unitSystem) and supports IEquatable and IJsonWritable.

Constructors

  • public OptionsUISystem()
    Default constructor for the system. The system initialization happens in OnCreate where bindings, default pages, and toolchain queries are set up.

Methods

  • public static void UpdateNotificationState(ModdingToolStatus toolStatus, DeploymentState deploymentState)
    Static helper that pushes/pops a toolchain-related notification depending on modding toolchain status (idle/outdated/invalid). If a non-idle status is present, it clears the notification; otherwise it pushes a warning with action to run toolchain install.

  • private async void QueryToolchainState()
    Asynchronously queries the modding ToolchainDeployment dependency manager for current state and calls UpdateNotificationState. Errors are caught and logged.

  • private void OnModdingToolchainStateChanged(ToolchainDependencyManager.State newState)
    Invoked on toolchain state change — marshals to main thread and updates notification state.

  • public void OpenDirectoryBrowser(string root, Action<string> onSelect)
    Creates and opens a DirectoryBrowserPanel rooted at the given path. When the user selects a directory, onSelect is invoked and the directory browser is closed.

  • private void OnCancelDirectory()
    Closes and clears the active directory browser.

  • private void SwitchBindings(bool browserActive)
    Enables/disables raw trigger bindings in the main options bindings vs. the directory browser bindings so only one set is active at a time.

  • protected override void OnCreate()
    Initializes bindings, value bindings and update bindings (m_WidgetBindings, m_ActivePageBinding, m_PagesBinding, layout map, unit settings and many UI control bindings). Adds directory browser bindings, starts toolchain query, subscribes to toolchain state changes, and selects the default visible page.

  • protected override void OnDestroy()
    Cleans up subscriptions (unsubscribes from toolchain state changes) and calls base.

  • public void RegisterSetting(Setting setting, string id, bool addPrefix = false)
    Registers settings provided by a Setting instance. Builds a Page from the setting page data, assigns index, sets section indices, updates visibility/name/warning as appropriate and stores into pages dictionary. If this is the first page with visible sections, selects a visible section. Finally updates pages binding and refreshes the currently displayed page.

  • public void UnregisterSettings(string id)
    Removes pages with the given id. If the currently active page was removed, switches to a visible page if available. Refreshes pages binding and displayed page.

  • private void SelectSection(string pageID, string sectionID, bool isAdvanced)
    Overload that sets advanced flag and delegates to SelectSection(pageID, sectionID).

  • private void SelectSection(string pageID, string sectionID)
    Attempts to select the provided section on the provided page. If a search query is active, calls FilterWidgets() instead. If page/section are invalid falls back to default selection.

  • private void FilterWidgets(List<int> ids, string query)
    Updates the search query and the internal list of matching widget ids (deduplicates and compares for change). If the search results or query changed, reselects active page/section to display search results.

  • private void FilterWidgets()
    Builds the list of IWidget children to display when a search is active, constructing Breadcrumbs and grouping labels as needed, and sets m_WidgetBindings.children to the search result list.

  • private void SelectVisibleSection(Page page)
    Selects the first visible section on the provided page.

  • private void SelectSection(Page page, Section section, bool isAdvanced)
    Overload that sets advanced flag and delegates to SelectSection(Page, Section).

  • private void SelectSection(Page page, Section section)
    Sets the active page/section bindings and updates m_WidgetBindings.children to the section's items for the current advanced flag.

  • private void RefreshPage()
    Refreshes the display of the currently active page/section (re-applies selection based on bindings).

  • private void SelectDefaultPage()
    Selects the first visible section among all registered pages (used when no page is active).

  • public void OpenPage(string pageID, string sectionID, bool isAdvanced)
    Public helper to open the options UI and select the provided page/section depending on the current game mode (MainMenu, Game, Editor). It finds the corresponding screen system, sets its activeScreen to Options and selects the requested section.

  • protected override void OnUpdate()
    Periodic update handling:

  • Ensures options UI is currently visible in the active screen; otherwise returns early.
  • Iterates all pages to update names, descriptions, visibility and warnings (only for the active page or when searching) and updates bindings if changes occur.
  • Handles the display confirmation timeout (revert if expired).
  • Manages the DirectoryBrowser binding state.

  • Detects keyboard layout changes and builds a layout map for localized key display names, updating the m_LayoutMapBinding.

  • public void ShowDisplayConfirmation()
    Starts the display-confirmation timer (default 15 sec) and saves the current graphics resolution/display mode/index so it can be reverted if not confirmed.

  • private void ConfirmDisplay()
    Confirms the display change (disables the confirmation timer) so no revert will happen.

  • private void RevertDisplay()
    Reverts graphics settings (resolution, display mode, display index) to the previously saved values and applies & saves the settings.

  • private void OnPageClosed(string pageId)
    Called when an options page closes; currently used to trigger telemetry for Graphics settings.

  • private static Label BuildGroupLabel(string pageId, string groupId)
    Helper that constructs a Label widget for a group name used in Breadcrumbs, with localized display string and beta flag lookup.

Usage Example

// Obtain the options system and open the "Audio" page (example ids depend on registered pages)
var options = World.GetExistingSystemManaged<Game.UI.Menu.OptionsUISystem>();
if (options != null)
{
    // Open page "Audio", section "General", do not show advanced
    options.OpenPage("Audio", "General", isAdvanced: false);
}

// Registering a setting (from a mod) so it appears in the Options UI:
// 'mySetting' is a Setting instance created by the mod.
// 'id' is the page id that setting belongs to; addPrefix true will prefix widget ids.
options.RegisterSetting(mySetting, "MyModOptions", addPrefix: true);

// Opening a directory browser from a settings widget:
options.OpenDirectoryBrowser("C:/MyMod/Exports", directory =>
{
    // handle selected directory
    Debug.Log("User selected: " + directory);
});

If you need more detailed documentation for nested types (Page, Section, Option, WidgetInfo, UnitSettings) or example flow showing how to create Setting data that RegisterSetting consumes, tell me which part to expand and I will produce detailed docs and examples.