# Rolly Settings: architecture

> How the code is put together, for programmers who read or extend it. The README explains how to use the plugin.

Product: Rolly Settings 0.1.0 | Sheet: architecture | Updated: 2026-09-30 | HTML: https://rolly-docs.pages.dev/settings/architecture/

How the code is put together, for programmers who read or extend it. The README explains how to use the plugin.

## Modules

| Module | Loads in | Depends on | Holds |
|---|---|---|---|
| `RollySettings` | Runtime | Engine modules, Enhanced Input, `RollySettingsCore` | The settings model and flows, the subsystems and their Blueprint API, bindings, saving, the built-in library, the controls |
| `RollySettingsUI` | Games and the editor, never a dedicated server | `RollySettings`, `RollySettingsCore`, `RollySettingsCoreUI` | The settings screen, its rows, key capture, the keep-or-revert dialog and the Open and Close Settings API |
| `RollySettingsEditor` | Editor | The modules above and `RollySettingsCoreEditor` | Asset tools, the cook hook, the Play In Editor restore, the theme previews' presenter and every automated test |
| `RollySettingsCore` | Runtime | Engine modules only | Setup reports, validation, the player's input device, the accessibility preferences |
| `RollySettingsCoreUI` | Games and the editor, never a dedicated server | `RollySettingsCore` | The Rolly UI design system: theme and presets, widgets, components, navigations, the five layout templates, the category screen, toasts, dialogs and the per-player screen stack |
| `RollySettingsCoreEditor` | Editor | `RollySettingsCore`, `RollySettingsCoreUI` | The Message Log listing, the design system's cook hook, the theme editor (preset picker, thumbnails, details preview with its checks strip, preview window, context menu) and the UI test support |

The three core modules are the shared Rolly foundation, carried inside the plugin under this product's name. Dependencies point one way: the UI module uses the runtime module, never the reverse, and the product never depends on another Rolly product.

## Folders

Every module keeps its front door in its root folder: the module header, its Project Settings class, its Blueprint libraries and the types several folders share. Everything else sits in a feature folder with the same name under `Public/` and `Private/`, and code includes headers by that path (`Screens/RollySettingsScreen.h`).

**`RollySettings`**

| Folder | What it holds |
|---|---|
| (root) | `RollySettings.h` (module, log category), `URollySettingsProjectSettings` (Plugins > Rolly Settings), `RollySettingsTypes.h` (scopes, apply modes, results, categories), `RollySettingsTags` (the built-in tags) |
| `Kinds/` | `URollySetting` and a class per kind: Toggle, Choice, Slider, Key Binding, Key Mappings, Action. Definitions only: defaults, options, the text form of a value |
| `Model/` | `URollySettingsCollection` (the data asset), `FRollySettingsCollectionSource` (which collection runs), `FRollySettingsModel` (values and flows of one scope), `FRollySettingsPlayerView` (one player's view of both scopes), conditions, the validator, the value codec, the confirmation ticker |
| `Bindings/` | `URollySettingBinding` and the built-in bindings (stored only, Blueprint custom, display, graphics, audio, accessibility, input), with the engine adapters they share (`FRollySettingsGameUserSettings`, displays, quality levels, colour vision, console variables, `URollySettingsAudioSubsystem`) |
| `Library/` | `FRollySettingsDefaultLibrary`: the built-in library, built in code |
| `Controls/` | `FRollySettingsControls` (a player's Enhanced Input keys), `FRollySettingsKeyCapture`, the Sensitivity and Invert input modifiers, `URollySettingsPlayerInput` |
| `Storage/` | `URollySettingsStorage` and its ini and memory storages |
| `Subsystems/` | `URollySettingsSharedSubsystem` (game instance: Shared values), `URollySettingsSubsystem` (local player: Per Player values and the Blueprint API), the console commands |

**`RollySettingsUI`**

| Folder | What it holds |
|---|---|
| (root) | The module, `URollySettingsUIProjectSettings` (Plugins > Rolly Settings Screen), `URollySettingsUILibrary` (Open, Close and Is Rolly Settings Open) |
| `Screens/` | `URollySettingsScreen`, a category screen of the core that supplies the data: the categories with their icons and live summaries, the rows of a category (made by the private `FRollySettingsListBuilder` from the row class `FRollySettingsRowClassMap` finds for each setting's kind: the screen's Row Classes, then Project Settings', then the built-in rows, the nearest parent class winning), the focused setting's detail and facts, and Apply, Revert, Reset and Discard; `URollySettingsKeyCaptureScreen` with its private input processor; `URollySettingsUISubsystem` (opens the screens, at a category too, and shows the keep-or-revert dialog) |
| `Rows/` | `URollySettingsRow` (on the core row), `URollySettingsSettingRow` (a row of one setting) and a row per kind |

**`RollySettingsEditor`**

| Folder | What it holds |
|---|---|
| (root) | The module: registrations |
| `Assets/` | The collection's asset definition and factory, and Tools > Rolly > Create Settings Collection from Defaults |
| `Cook/` | `FRollySettingsCookRules`: cooks what Project Settings name |
| `PlayInEditor/` | `FRollySettingsEngineState`: records the engine values bindings change and puts them back after Play In Editor and after tests |
| `Preview/` | `FRollySettingsPreviewContent`: the read-only presenter of the theme previews: the built-in library's categories and settings at their written defaults as preview rows (sample key rows for Key Mappings), never calling a binding |
| `Tests/` | Shared test games and collections at its root; a folder per runtime folder (`Kinds`, `Model`, `Library`, `Storage`, `Bindings`, `Controls`, `Subsystems`), plus `Editor` and `UI` |

**The core modules**

| Module and folder | What it holds |
|---|---|
| `RollySettingsCore/Diagnostics` | `FRollySettingsCoreSetupReporter` (setup mistakes at run time: Output Log, Message Log, screen), `FRollySettingsCoreValidationResult` (the checks behind Data Validation) |
| `RollySettingsCore/Input` | `URollySettingsCoreInputDeviceSubsystem`: the input method and gamepad family each player uses |
| `RollySettingsCore/Accessibility`, `Shared` | `FRollySettingsCoreAccessibility`: high contrast and reduced motion, which the High Contrast Interface and Reduce Motion settings write; they live in the shared console variables of `FRollySettingsCoreSharedChannel` (`rolly.ui.contrast`, `rolly.ui.motion`, and `rolly.ui.theme` with the pointer `[RollyUI] Theme`), so every installed Rolly product follows them |
| `RollySettingsCoreUI` (root) | `URollySettingsCoreUISettings` (Plugins > Rolly Settings Core UI), `URollySettingsCoreUILibrary` (Push Rolly Screen, Show Rolly Dialog and the other nodes), shared types |
| `RollySettingsCoreUI/Theme` | `URollySettingsCoreUITheme` (the asset), the six presets, `URollySettingsCoreUIThemeSubsystem` (the theme, preset, layout and density in use, high contrast, reduced motion, preview looks), `FRollySettingsCoreUIThemeResolver` (Theme Source, the shared variable and pointer) and the bridge for other products' themes, `FRollySettingsCoreUIStyle` (roles resolved for drawing), the theme listener for Widget Blueprints |
| `RollySettingsCoreUI/Widgets`, `Icons`, `Glyphs` | Plain widgets that follow the theme (text, inline text, surface, backdrop, list, switch, slider, focus frame, spinner, shadow, player badge), the region, shelf and portal the templates use, code-drawn icons and key glyphs |
| `RollySettingsCoreUI/Components`, `Navigation` | `URollySettingsCoreUIUserWidget` (base of every Rolly widget with parts) and the components: button, row, prompt, Rolly Prompt Bar; the navigations: Rolly Tab Strip, the side rail, the switcher and the hub's tiles |
| `RollySettingsCoreUI/Templates` | The layout templates (Tabs, Rail, Panel, Hub, Drawer) and their registry |
| `RollySettingsCoreUI/Screens`, `Stack`, `Toasts` | `URollySettingsCoreUIScreen`, `URollySettingsCoreUICategoryScreen` (the base of the settings screen: parts in the template's slots, levels, category keys, detail, footer, touch), `URollySettingsCoreUIDialog`, the host; `URollySettingsCoreUIStackSubsystem` (one player's screens, focus, input, pause, toasts) and the replaceable presenter and input handler |
| `RollySettingsCoreUI/Layout`, `Motion` | Helpers for code-built layouts, fixed metrics, the tween runner |
| `RollySettingsCoreEditor/Cook`, `Assets`, `Details`, `Preview`, `Testing` | The cook hook of what Project Settings name and the shared theme; the theme editor; the preview scene and content source the settings presenter feeds; and `RollySettingsCoreUITests` (the test support) |

## How a value travels

1. **Definition.** `FRollySettingsCollectionSource` picks the collection of Project Settings, or the built-in library. The shared subsystem keeps it and runs the Shared `FRollySettingsModel`; each local player's subsystem runs a Per Player model and an `FRollySettingsPlayerView` over both.
2. **Start.** Each model reads the saved values (the storage, and the bindings for values the engine saves itself) and applies them as one group through the bindings.
3. **A change.** A Set node, a row of the screen or a console command reaches the player's view, which hands it to the model of the setting's scope. Immediate values apply through the binding and save at once; On Apply values wait. Apply applies the waiting values as one group: each binding's `ApplyValue`, then `FinishApplyingValues` once per binding (one window change, one GameUserSettings.ini save), then one storage write. A setting that needs confirmation starts the ticker's countdown; Confirm keeps the values, Revert or the timeout puts the old ones back.
4. **The engine.** Bindings change engine state: the engine's user settings, console variables at the Game Override priority (High Contrast Interface and Reduce Motion write the shared `rolly.ui.contrast` and `rolly.ui.motion`, which every installed Rolly product follows), the sound mix. Values the engine changes itself are read again after every group and when the engine reports a change.
5. **The screen.** `URollySettingsUISubsystem::OpenSettings` (or `OpenSettingsAt` with a category tag) pushes `URollySettingsScreen` on the player's screen stack (`RollySettingsCoreUI`). The screen reads the player's view: a category per collection category with something to show (with its icon and a summary of its first values for the hub's tiles), and a row per setting that `FRollySettingsListBuilder` makes from the row class of its kind. The core's category screen puts them into the layout template in use (tabs, side rail, centered panel, couch hub or side drawer) and handles the navigation, levels, detail and footer. Rows change values through the player's subsystem; the view's change event refreshes the rows, the detail and facts, the tiles' summaries, the footer's Rolly Prompt Bar and the restart notice, and an Apply shows a toast. A key cell opens `URollySettingsKeyCaptureScreen`, which feeds `FRollySettingsKeyCapture`, then `FRollySettingsControls`, then Enhanced Input.

## Extension points

| To change | Do this | No plugin code changes |
|---|---|---|
| Where a value goes | A subclass of `URollySettingBinding`, or a Blueprint child of Rolly Setting Custom Binding | Yes |
| Where values are saved | A subclass of `URollySettingsStorage`, picked in Project Settings | Yes |
| The subsystems | A project subclass of `URollySettingsSubsystem`, `URollySettingsSharedSubsystem` or `URollySettingsUISubsystem` replaces the plugin's own | Yes |
| The look | A Rolly Settings Core UI Theme asset (shared by every Rolly product, or this product's own through Theme Source), or a preset; an Interface Theme setting is a Choice on `rolly.ui.theme` (README, the recipe) | Yes |
| The layout | A layout id (Tabs, Rail, Panel, Hub, Drawer) in Project Settings or the theme; a template of your own per id in Project Settings > Rolly Settings Core UI > Template Classes | Yes |
| The layout of the screen, key capture, rows, tabs, prompts or dialogs | Blueprint subclasses whose widgets are named like the parts (README, Layouts of your own), picked in Project Settings or the screen's class defaults | Yes |
| Where the screens are hosted, or how they take input | Set Host Panel (a panel of your own), `IRollySettingsCoreUIPresenter` and `IRollySettingsCoreUIInputHandler` | Yes |
| A new setting kind | A C++ subclass of `URollySetting` (its text form, options and checks are virtual). The model, saving and the Blueprint API take it; the settings screen has rows for the built-in kinds only, reports such a setting and leaves it out, so show it in a widget of your own | Yes, except on the settings screen |

## Tests

All automated tests live in `RollySettingsEditor/Private/Tests`, grouped like the code they test, and are named `Rolly.Settings.<Area>.<Case>`. The screen tests (`Tests/UI`) drive the screen through the core's test support (`RollySettingsCoreEditor`, `Testing/RollySettingsCoreUITestSupport.h`): a game instance without Play In Editor, an off-screen window, a virtual Slate user, mouse and finger, and a camera for screenshots in rendering runs (`Rolly.Settings.UI.Screenshots.Screens`, `.Templates`, `.Presets` with Glass over the game, and `.Matrix`, whose R5 is a player of a two-player split). `Rolly.Settings.Editor.PreviewContent` and `.PreviewSafety` check the theme previews' presenter (no binding is ever called, GameUserSettings is never touched: AC-39) and `Rolly.Settings.Recipes.InterfaceTheme` the Interface Theme recipe. The design system's own tests are the core's (`RollySettingsCore.UI.*`, `RollySettingsCore.Editor.*`).