Session Settings

Introduced in SML3.5, Session Settings (referred to in-game as Mod Savegame Settings) are a feature similar to Advanced Game Settings that allows mods to store configuration information on a per-game-save basis. Session Setting values are automatically replicated in multiplayer and can be edited by any connected player. Note that Session Settings do not require Advanced Game Settings to be enabled to be used.

Session Settings are currently stored in the Map Travel URL, making them available exceedingly early in the loading process. This may change in the future depending on what mod developers decide is more useful.

It’s possible to make a session setting specific to only a certain level, making them particularly useful for providing config options for custom levels since they can be edited before the save is created.

Session Settings vs. Mod Config

Session settings are always per-game-save, while mod config is stored per-game-installation. For example, in a dedicated server, the server has its own mod config and each client has their own mod config. Making the server aware of client’s chosen configs (or vice versa) is only required if some behavior on both sides requires it, for example movement speeds or content registration. Replicating config values must be implemented by the mod developer. Session Setting values are automatically replicated in multiplayer.

Mod Configurations are better for user interface or visual stuff since it gets saved with the user’s installation, carries over between saves, and different users may want different settings on the same server.

Session Settings are good for things that do not pertain to a particular player, or you want to be a choice per save file, such as what recipes from a mod are enabled, how fast a machine operates, or options for a custom level.

Defining New Session Settings

Session Settings are defined by Data Assets. To create a Session Setting in Blueprint, in a content browser right click and select Create Advanced Asset > Miscellaneous > Data Asset and search for SMLSessionSetting.

Selecting a Str Id

Session Settings inherit from UFGUserSetting, the class the game uses to define the configuration options in the settings menu.

The "Str Id" field is a unique identifier for the session setting and is used for retriving the value of the session setting later. See the table below for some examples of Str Ids and things to keep in mind when selecting one.

Table 1. Example Session Setting Str Ids
✔️ Good Example ❌ Bad Practice

✔️ YourModReference.EnableFizzBuzz

Prefix the id with your Mod Reference to ensure it is unique across mods.

❌ EnableFizzBuzz

Another mod could implement a session setting by this name, leading to a conflict.

✔️ YourModReference.WhizzbangStrengthMult

Since session settings are referenced by their string id, giving them a verbose, unique name makes it easy to find all usages of the setting in code via a find operation.

❌ YourModReference.Multiplier

Multiplier for what? It’s easy to forget what this setting controls, and if you ever decide to add other "multipliers" in the future, they could easily be mentally confused with this one.

✔️ YourModReference.PowerCostMultFloat

Since you must use a type-specific method to read/write a Session Setting, consider including the setting’s type as part of its id as a reminder of what type it is. Unfortunately using the wrong getter method is currently a silent error due to how the FG Options system is implemented, making this problem particularly annoying to track down.

✔️ YourModRef.MinerMk1.PowerCostMultFloat

Consider indicating which building/feature a setting applies to if you offer multiple settings with similar names or functionality.

Display

The following fields control how session settings appear to end users:

  • Display Name: User-facing name of the option. Users can search for this text within the setting’s category.

  • Tool Tip: User-facing description of what the option does. Appears at the bottom of the setting scroll list when the user hovers over the option. Text will wrap as needed to fit the user’s screen, but manual new lines are not supported.

  • Widgets to Create: Defines where the setting appears. Elaborated on below.

Category Assets

Session settings appear in categories defined by FGUserSettingCategory assets. You must create a minimum of 2 Category assets for your mod’s session settings, one for the overarching Category used by your mod, and a second for a Sub Category within your category. Category assets can be reused for multiple options within the same mod.

The following defaults are suggested:

Session Setting categories do not use the icon functionality offered by FGUserSettingCategory.
(Main) Category

Suggested asset name: SSC_YourModReference

  • mDisplayName: The Friendly Name of your mod, for example, Example Mod. The user can search all Categories for what you write here.

  • mMenuPriority: Leave this at 0, you can’t infer what other mods the end user will have installed to pick a "good" value. If you create multiple main categories, you can use this field to ensure they display next to each other. In this case, pick a random large number to use as a base and then a small offset to group them together, for example, 864392 and 864392.1.

Mods typically define a single main category for their session settings. If you end up creating multiple, make sure it’s still clear which mod is offering the category.

Sub Category:

Suggested asset name: SSSubC_YourModReference_SubCategoryName

  • mDisplayName: Header text for this sub category. This field’s text isn’t currently searchable.

  • mMenuPriority: Because you control all sub categories within your mod’s category, this field is useful for ordering them.

"Widgets to Create" entry

Session Settings inherit functionality from FGUserSettings that enable the same option to be displayed in multiple places, so making one appear involves creating at least one entry in the Widgets to Create field. Make sure to define these fields:

  • Category Class: Self explanatory.

  • Sub Category Class: Self explanatory.

  • Menu Priority: Controls options' ordering within the sub category.

Level Whitelist

When values are present in this array, the session setting is restricted to only appear when playing in one of the specified game levels. Combined with the fact that users can configure session settings when setting up a new game save, they are especially useful as options for custom maps.

Behavior

Not all properties inherited from UFGUserSetting are relevant to Session Settings. You will have to experiment to see which ones have an effect. Please update this documentation page via "Edit This Page" in the top right with your findings.

Checking the "Use CVar" field is only required if you wish to allow modifying the value of the session setting via the game console.

SML automatically forces the following property values on Session Settings. If you change any of these properties they will be automatically reset to these values next time the asset is loaded.

  • ShowInBuilds: Public Builds to ensure that session settings are visible to the user

  • ManagerAvailability: USM MAX, which is an invalid value, ensuring that the setting never displays in base-game options menus.

  • IsSettingSessionWide: true to ensure that multiplayer clients are able to modify session settings and have their changes stored with the save file.

In order to have a session setting only editable at save creation, use the "Don’t show in game" Visibility Disqualifier.

Registration

A Session Setting must be registered to be usable by the player.

To register a Session Setting, list it in the relevant array of your mod’s Game Instance Module.

Registering a Session Setting makes it available to be configured in the SML Session Settings menu which is available at both world creation and in the pause menu.

Reading and Writing Session Settings

Check ExampleMod for some example session settings and how to read their values. There is an example in the ExampleMod Level Blueprint and in the Game World Module.

From Blueprints

To get a reference to the Session Settings Manager, use the "Get Session Settings Manager" node.

You can read the value of a session setting via the "Get <typename> Option Value" method of the Session Settings Manager. You can also subscribe to changes via "Subscribe to Dynamic Option Update".

If you want to programatically modify the value of a session setting, use the "Set <typename> Option Value".

From C‍+‍+

The SessionSettingsManager is a UWorldSubsystem and as such can be accessed from the world context via Unreal’s getter.

An example of reading a integer Session Setting value from C‍+‍+:

// self->GetWorld() can be substituted with any other method of obtaining world context
USessionSettingsManager* SessionSettings = self->GetWorld()->GetSubsystem<USessionSettingsManager>();
auto optionValue = SessionSettings->GetIntOptionValue("YourModReference.IntSessionSetting");

Testing

Make sure to check in-game to ensure that your Session Settings appear and display as you expect. They are referred to in-game as Mod Savegame Settings - learn more on the Configuring Mods page.

Check out ExampleMod for some example types and setups using session settings.

Unreal Console Commands

If your session setting is configured to use a CVar its value can be set using Unreal console commands. For example SML.ForceAllowCheats 1 will set the SML session setting ForceAllowCheats to 1.

Advanced Game Settings

In order to create an Advanced Game Setting instead of a Session Setting, create a data asset of type FGUserSetting instead of SMLSessionSetting.

Once the type is set to Advanced Game Setting in the asset properties, the game will automatically discover it and add it to the Advanced Game Settings menu for you. You can use the same category system as Session Settings to control what categories it appears in. This is also true for Photo Mode and Options Menu settings, if for some reason you want to add values to those.