Upgrading from SML 3.11.x to 3.12.x
|
SML 3.12 and 1.2 support have not been released yet!
The contents of this page will change frequently!
Keep your eyes on the |
SML3.12 brings support for Satisfactory 1.2. As a major update bundled with an Unreal Engine upgrade, most mods are expected to need recompilation with the new engine and game headers.
Please read this entire page before you begin updating your mod. It will save you time later to have an idea going in of what to expect while updating. After you have finished reading this page, follow the directions on the Updating your Mod guide to install the updated engine, starter project, and update your mod.
Versioned Cooked Content
TODO move this heading?
Since Alpakit uses Versioned Cooked Content as of SML 3.10, there is a chance that some blueprint-only mods packaged for SML3.10 will require no changes to function properly in Satisfactory 1.2.
Since it’s not possible for an end user to predict which mods will or won’t work, we are not planning to announce this, except to careful readers of this page - hey, that’s you! It’s up to mod developers and attentive community members to test mods and update their ficsit.app Compatibility Info accordingly.
As a general rule of thumb, your mod will probably NOT have survived if:
-
It includes includes any C++ modules
-
It interfaces with systems changed in Satisfactory 1.2, like vehicles
-
It worked with user input, especially for controllers
-
You stepped outside on a rainy day while wearing 1 sock on the wrong foot during the 1.2 experimental (that is to say, there are factors we aren’t aware of yet)
To test whether your mod still works without recompiling:
-
Install your published SML3.10-dependent mod via Satisfactory Mod Manager or by manually installing it.
-
As SML 3.12 is not currently released, it is not available on SMM. Use Alpakit to package a version of SML yourself. Note that SMM will replace your self-packaged copy of SML if it detects that changes are required.
-
Launch your game and test your mod accordingly
-
If your mod functions without a recompile, update its Compatibility Info on the mod page accordingly. No need to build and upload a new version.
New Features
This section talks about the new features that Satisfactory 1.2 and SML 3.12 bring to the table.
User Config Resetting
TODO Additional details, see https://github.com/satisfactorymodding/SatisfactoryModLoader/pull/364/
Users can now reset Mod Configuration options to their default values directly from the config screen. Package ExampleMod and try it out in game!
As a mod developer, you can exclude certain options from being reset ('Allow User Reset'), check if a setting is at its default value, or trigger a reset yourself via code. If a config section disallows reset, all options within that section are also unable to be reset.
All existing default values and user config choices have been preserved. Although you do not technically need to change anything for your mods to get this feature, it is worth reviewing your configuration to see if there are any values that the user should not be allowed to reset.
ficsit.app Controller Compatibility Tracking
TODO currently only live on ficsit.dev
ficsit.app now allows you to communicate if your mod works with controllers, such as Xbox, Playstation, or Steam controllers. This information is presented and stored in a system similar to the existing Stable and Experimental branch compatibility.
The possible options are:
-
Untested - (Leave your mod at this unless you have a good reason to otherwise.) No controller support information has been reported for this mod yet. Try it out and contact us on the Discord so it can be updated!
-
Unsupported - You will need to use a mouse and keyboard to interact with elements introduced by or altered by this mod.
-
Partial - This mod partially supports playing with a controller, but there are still some things missing. You may need to use a mouse and keyboard to interact with some elements introduced by or altered by this mod. Be sure to read the note and see an explanation!
-
Supported (Implicit) - This mod supports playing with a controller. This is because the mod does not introduce or modify any systems that require an explicit effort to support controllers - existing controller support already covers it.
-
Supported - This mod supports playing with a controller. The developer has made a specific effort to ensure that playing with a controller is possible and tested it themselves.
This information is currently only visible on ficsit.app, not inside of SMM.
ficsit.app Disclosures
TODO currently only live on ficsit.dev, and there are pending content policy edits not on dev yet
ficsit.app now offers a consistent location for mods to place their Network Activity Transparency information. Previously, this information was expected to be somewhere inside the mod description text. This new change helps users find the information quickly and ensures developers know they need to provide it. Together with this field is a new one for disclosing generative AI usage.
You can read more about what information must be disclosed in the ficsit.app Content Policy.
Note that uploading additional versions of your mod is blocked until disclosure questions are answered.
This information is currently only visible on ficsit.app, not inside of SMM.
Modding and Linux
Thanks to some hard work on the build system, the binaries we distribute for SML 3.12 and the custom Unreal Engine version are now compiled on Linux machines.
This shouldn’t change anything visible to end users or mod developers, but it makes our automated build systems a lot easier to maintain, and means it’s now easier for individual mod developers to set up their own, if desired.
Coinciding with this, we’ve done a bunch of testing with developing mods from Linux machines, and it’s now stable enough for us to include directions on the docs. As Linux systems are often unique, expect to have to face some undocumented complications and join the Discord to seek setup assistance.
You can find the Linux-specific setup directions on the Linux Setup page.
Advanced Game Settings split to Creative Mode and Game Modes
TODO
Satisfactory 1.2 has renamed the concept of Advanced Game Settings to "Creative Mode". These options still disable achievements. There is a new category of settings called "Game Modes" that include the new ore node randomization and cost multiplier settings. "Game Modes" do not disable achievements.
It should be possible to define new Game Mode settings using FGUserSetting, but no one has tried it yet.
Not Done Yet
The following features are not quite ready to use yet.
Editor Can’t Open Standalone
If you open the editor from the Windows Start menu, it may fail to open.
Logs can be found in %LOCALAPPDATA%\UnrealEngine\5.6\Saved\Logs\Unreal.log
We are still investigating why this happens.
In the mean time, the editor will open properly when you double-click-open FactoryGame.uproject in the Starter Project.
TODO Arch+Rob identified potential fix and new engine is building https://discord.com/channels/555424930502541343/562722670974599227/1510481056850251977
Unreal Game Features
WIP
Changes in 1.2 allow Satisfactory mods to take advantage of the Unreal Game Features and Modular Gameplay system. Game Features are similar to SML’s Game Instance Modules.
|
SMM/ficsit-cli and ficsit.app do not yet support distribution of mods using the Game Feature asset structure. This support is being written and 3.12 won’t be publicly released until it’s done. |
TODO Basically all mods should switch to the GameFeature system, because all mods that add content should for the asset management. Pure libraries would be the ones that don’t need to. https://discord.com/channels/555424930502541343/562722670974599227/1509918776605278348
Satisfactory now uses the Asset Manager All previous asset types that were previously auto-detected (such as icon libraries, input contexts, FGMessages (ADA), and FGUserSettings) now require using Game Features.
ExampleMod has been updated to package its files using Game Features.
To migrate your mod to use Game Features:
-
Delete any existing built copies of the mod from your game install directories. The game will get confused and not load things properly if you have both a "standard" and "game features" copy of your mod installed at once. ("A version of the 'ModReferenceHere' plugin has already been enabled" log message produced)
-
Close the Unreal editor
-
Transfer the mod’s plugin folder from the
<Project>/Mods/directory to the<Project>/Mods/GameFeatures/directory. -
Regenerate Visual Studio Project Files
-
Compile for Development Editor
-
Create a new Data Asset of type FGGameFeatureData in the mod’s content root folder with the name of your mod reference. Using the name
GameFeatureDatais also supported but discouraged as it makes editing multiple mods at once confusing. -
(Optional) Create a new mod with the Alpakit template to copy its Primary Asset Types to Scan rules to your own
-
TODO what actions need to be set up?
It lists the actions to be taken when loading/unloading the GameFeature, and the asset search paths for primary assets-Mircea
In the future the World Partition Data Layers system, with data layers loaded by Game Features, will be the intended approach for creating additions to the game map, like new ore nodes or terrain elements, replacing the current sublevel spawning approach. Based on SirDigby’s testing, this is not working yet.
TODO Arch mentioned it’s possible to register schematics and stuff without SML now via this; best place to document?
Required Changes
In addition to any specific-to-your-mod issues you may encounter, the changes described below must be made in order for your mod to be updated.
Dependency Updates
The following project dependencies have updated. Install the updated versions as you follow the Updating your Mod guide.
Engine Update
Satisfactory 1.2 brings the game to Unreal Engine 5.6.1. Download and set up our custom release while following the Updating your Mod guide.
Clang Toolchain Update
This updated engine version also requires an updated clang toolchain. Download and set up the new toolchain while following the Updating your Mod guide.
Wwise Update
CSS has also updated to a newer version of Wwise. The Dependencies page Wwise instructions lists the new Wwise version and guides you through integrating it into your project as you follow the Updating your Mod guide.
Generate Wwise Sound Banks
If you see the "GeneratedSoundBanks folder does not seem to be set. Would you like to open the settings window to set it?" message, use the Wwise editor to manually generate sound banks once, You should not need to do this again unless you create a new Wwise project or use Wwise systems in your mod.
Unreal Pointer Migration
TODO
Satisfactory has switched to use Unreal TObjectPtr<>`s instead of raw pointers (for example, `UObject*) in their codebase
for the memory and dependency management benefits it offers.
Any C++ mods using raw pointers to UObjects/UStructs/UProperties
must switch to this format to avoid crashes (It will build somewhat fine like this but not using TObjectPtr might result in GC crashes if/when we enable Incremental GC - Arch).
In the next SML update, mods still using raw pointers will be unable to compile.
You can force this compile-time check now by adjusting the Unreal Header Tool configuration:
[UnrealHeaderTool]
; ...
; <CSS> FactoryGame has been migrated to use TObjectPtr, disallow native pointers in game code
NonEngineNativePointerMemberBehavior=DisallowIn most cases the swap can be a drop-in replacement, as TObjectPtr can automatically cast to a raw pointer as needed, but it can’t automatically cast to a pointer-by-reference, which may require additional code changes.
Unreal has provided a conversion tool that can update portions of your code automatically: Unreal Engine 5 Migration Guide: Optional Conversion Tool
You don’t need to build the tool yourself, our engine ships it in C:\Program Files\Unreal Engine - CSS\Engine\Binaries\Win64\UnrealObjectPtrTool.exe
Steps to run tool?
Running the tool applies for every loaded mod in the project.
Additional Changes
You might not be affected by these changes, but we’d like to draw extra attention to them.
Enhanced Input
A number of fields have been moved between InputMappingContext and InputAction classes this update.
You can find their old values by opening up your backup copy of the project and checking it there. If you don’t have a backup copy, make one next time! You may also be able to recover this info by using FModel or Content Inspector on an existing release of your mod.
Mapping Context Parent Class Change
Input contexts using the Parent Context registration approach need to be migrated to a new purpose-built data asset class.
The mParentContext field has been moved from UFGInputMappingContext to UFGChildInputMappingContext,
so the value set on existing assets will be lost.
To migrate an existing input mapping context asset,
right click on it and select either of the 2 Convert to a Different DataAsset Type menu options,
then select FGChildInputMappingContext
Also need to be using GameFeatures for it to be auto detected otherwise need to manually register (no longer using parent approach https://discord.com/channels/555424930502541343/562722670974599227/1509904209649340558)
Do they need special register steps in gamefeaturedata? https://discord.com/channels/555424930502541343/562722670974599227/1509918327420616805 Almost certainly FGChildInputMappingContext Seems like non-child don’t as long as something else references them, ex. MC_InputExampleWidget referenced by Widget_InputExample
Player Mappable Settings Migration
A number of fields previously present on InputContexts' "Mappings" records have moved to Input Actions:
-
Is Player Mappable
-
Name (for options value saving)
-
Display Name
-
Display Category
These fields were previously configured on the InputContext, unless you were using the Experimental Player Mappable Key Settings option. This update makes that option no longer experimental, but the requirement.
It’s still possible to set these on the input context if you use the Override Settings Setting Behavior,
but it’s recommended to configure them on the action instead.
TODO should axis still have it on the action? ex. ExampleMod /Script/EnhancedInput.InputAction'/ExampleMod/Inputs/Interface/IA_ExampleWidgetMovementAxis.IA_ExampleWidgetMovementAxis' needs 4 separate
C++ Full Include Paths (BuildSettingsVersion V5)
A change in CSS build settings means that all modules must follow BuildSettingsVersion.V5.
Previously, targets for mods could have slightly different settings and still work properly.
Although the Alpakit mod templates have been updated to account for this for a few game updates, existing mods using legacy build settings may need to update their mod source to compile under the updated settings.
The most common example of this is needing to use full paths in includes now.
For example, code previously using #include "FGHologram.h"
must now use #include "/Hologram/FGHologram.h".
More context on this Discord message chain.
Asset Dumping with -nullrhi no longer works
Dumping assets with -nullrhi is no longer possible, because Unreal Engine doesn’t load mesh data when using that anymore,
as a dedicated servers memory optimization.
-RenderOffscreen can be used instead, which will still use the GPU to render, but without the game window.
ExampleLevel Lighting Update
Archengius has updated Example Level’s lighting to use exactly the same settings as the base game. If you’ve developed a custom map, check out the settings and lighting actors inside ExampleLevel so you can match the base game’s settings.
TODO list of places to look at specifically?
Console Shared Codebase
Note that Satisfactory 1.2 brings the PC and console versions of the game to the same codebase. Although it is still not possible to develop mods for consoles, you may notice additional code and assets for console support code.
Custom Icon Libraries on Servers
1.2 fixes a base-game bug content registration bug, allowing modded Icon Libraries to work properly on dedicated servers. No changes to existing icon libraries are known to be required for the fix to work.
Complete Changelog
|
This link temporarily compares to the |
The full list containing every changed file and asset can be viewed using GitHub’s Compare Changes feature: https://github.com/satisfactorymodding/SatisfactoryModLoader/compare/v3.11.3…dev