Updating from SML 2.2.1

Save Issue Resolved

There was previously an issue that prevented any modded saves from being loaded. This has since been resolved. Happy modding!

A lot of things have changed both behind the scenes and on the surface to allow for SML to work with the new engine update and modular build of Satisfactory, and all mods must be updated for these changes.

These changes are quite beneficial for modding, and grant mods a lot more control over the game.

In addition to changes to Unreal Engine itself between versions 4.22 and 4.25, there have been numerous changes made to SML itself. We will only go into the SML and Satisfactory-specific differences here, as Unreal Engine documentation covers the engine differences.

To update your SML 2.0 mod to SML 3.0, there are a number things you’ll have to change in your existing mod files.

We’re still working on updating the docs, so make sure to check here regularly to avoid missing something! Keep your eyes on #modding-info-feed on the Discord for pushes to the docs, and let us know if you have trouble with something.

Steps to Update

SML3.0 has changed mods over to be Unreal Plugins, which is how mods work in most other Unreal games, and how the eventual officially supported mods will work.

This means that instead of mod content being mounted in Content/<mod reference> it will now be in Plugins/<mod reference>/Content.

SML3.0 has a system to automatically redirect old modded content to their new locations. This means that, assuming you put assets in the same places within your plugin as they were in your SML2.0 content folder, modded content in SML2.0 saves will work in SML3.0.

To update your mod, you will have to do, at minimum, the following steps:

  • Rename the install folder of your current version of the engine/editor (described in the section below) so you can reference it while updating

  • Install the new engine/editor as described in the section below

  • Perform the project setup steps described in the Getting Started guide, which includes getting the new SML version and new Starter Project, as well as integrating a new Wwise version.

  • Create a new 'Content Only' Unreal Plugin through the default Editor UI, which has some extra steps if you have a C++ mod.

  • Change over your old InitMod to the new Mod Modules system (read more below)

  • Fill out the fields in your mod’s Plugin Manifest (which has replaced the data.json system).

If you have a C++ mod, be sure to specify your Modules correctly in the Modules section of the plugin manifest. See the Releasing Your Mod page for examples

New Editor Build

You will need to download and install a new copy of the editor build for the new engine from here.

We strongly suggest that you keep the old SML 2.2.1 editor installed until you are done porting your mods so that you can reference settings and BP code that have been removed in SML 3.0, ex. InitMod.

If you would like to keep the old SML 2.2.1 version of the editor and have both copies installed on your computer (helpful when updating your mod) you should do the following:

  1. Navigate to your install folder (probably C:\Program Files\Unreal Engine - CSS)

  2. Run SetupScripts\Unregister.bat (might need to do this as admin)

  3. Rename the install folder to C:\Program Files\Unreal Engine - CSS_2-2-1\ or similar.

  4. Run SetupScripts\Register.bat from the new location (might need to do this as admin)

  5. Now, to launch the old editor, you can run C:\Program Files\Unreal Engine - CSS_2-2-1\Engine\Binaries\Win64\UE4Editor.exe.

  6. Install the new editor build from the link above.

  7. Optionally, edit your Start Menu shortcuts (probably in C:\ProgramData\Microsoft\Windows\Start Menu\Programs) so that you have one for the old editor and one for the new editor

If you have previously moved the editor folder without doing the Unregister.bat step, you may experience issues with the editor thinking Unreal projects are an incorrect version. To resolve this, perform the Unregister step for the old editor version. This should not be required for the new editor version.

Project Setup

Set Up New Project

Now that you have the new editor version, you can head over to the Getting Started guide to set up the project for the new engine version.

Be aware that we will be releasing updated versions of the Starter Project, so you may need to perform the setup process again in the future, or will need to bring in updated files to your Starter Project. If you are reading this far, you are likely an experienced modder, and as such we suggest you use Git to clone the Starter Project repo as opposed to downloading a zip of it. This vastly simplifies the process of updating the project, but could cause you to encounter merge conflicts down the line.

You can stop following the Getting Started Guide once you reach 'Recipe vs Schematic.'

Then, return here for an explanation of how to safely move your content over from SML2 without losing it.

Porting Your Old Assets

Here is a summary of the steps you can use to port your old SML2 content to the new project without having to recreate every asset. Order is very important here.

  1. Optionally, clone the SML3 Starter Project instead of downloading zip. The reasons for doing this are described above.

  2. Create a new content folder in the SML3 Starter Project that is in the same place as stuff was in your SML2 Starter Project. ex /Content/ArmorModules

  3. If you have C++ content, move it over as well and make sure it compiles first before continuing.

  4. In your system file explorer, copy the content from your SML2 project to that folder in your SML3 project (Copy, not move, so you can do it again if you make a mistake)

  5. Take note of any errors that occur with your content and consider fixing them now (if they don’t require SML3 concepts to resolve the errors)

  6. Within the SML3 UE editor, create your Unreal plugin if you haven’t yet, which will make a plugin content folder for it.

  7. Within the SML3 UE editor, use its Move functionality to move things from the old content folder ex./Content/ArmorModules to the new plugin content folder ex. /Plugins/ArmorModules/Content. This means that UE should hopefully fix the bindings and references stuff for you. You can either do this via the usual 'move' or you can try right clicking on the folder and picking 'migrate…​' (I (Robb) haven’t tried this yet)

  8. Right click on the old content folder and choose 'fix up redirectors in folder'

  9. Fix any errors your content may be experiencing.

  10. Open your old SML2 editor to view your old InitMod and re-create its logic in your new GameWorldModule (within the SML3 editor, of course).

If you would like support with this, or encounter issues following this process, please ask on the #developers channel on the discord.

Note on Placeholders

Note that placeholder assets in the Starter Project have not yet been updated to include Update 4 content. If you’re looking to use new items from the Update 4, you will need to create stub blueprints for them yourself. You can read more about this on the Reusing Base Game Files page. Instead of trying to placeholder a mesh or texture, you will be creating a placeholder for the an FGItemDescriptor or similar.

But don’t worry, we are working hard on updating the project, and upcoming versions will include even more content than the old ones did.

Changed Concepts

A number of other concepts that your mod may or may not make use of have changed. Read below to see if you need to make changes to your mod.

Although we have done our best to make this list up to complete, we may have missed some things that this update changes. If you encounter SML changes not listed here, please contact us on the Discord so that we can add them to this list, or add it yourself via 'Edit this Page.'

  • The Bootstrapper is no longer needed, and has been removed. Unreal Engine and SML now take care of what it used to do.

  • InitMod is no more, and has been supplanted by the Mod Modules system. Most things that involved InitMod now involve the RootGameWorld Module.

  • InitMenu has also been replaced by the Mod Modules system. Check out the InitMenuWorld Module page.

  • The mod configuration system works slightly differently. All mod config structs should now extend UModConfiguration.

  • There is now a system built into SML for making custom key bindings that work with the base game key binding menu. Read more about it on the Registry page.

  • Alpakit Overrides/Overwrites have been replaced with the new Reflection Blueprint Library functionality, and by BP hooking and C++ for additional functionality not covered by BP reflection. They did not work consistently anyways. Read the Overwriting page and ask about this on the discord if you have to do this.

  • This list is not complete. Please read the "Update Notes from the Discord" section below.

New/Updated Docs Pages of Note

Here are a few notable docs pages outside of the tutorial that have been created or updated for SML3.0:

Development

Community Resources

Update Notes from the Discord

This section is a copy of the announcement recently posted on the Discord. It contains some information that has not yet been incorporated into the docs. It has been posted again here for your convenience.

Hey @\moddevs! We're happy to announce that SML and toolkit transition to Update 4 and the new 4.25 engine has finished!
You can now start porting your mods to make them available to the end users sooner, while we are polishing the rest of the modding ecosystem.

DISCLAIMERS:
======================================================
⚠⚠ECOSYSTEM IS NOT YET READY FOR MOD DISTRIBUTION TO END USERS⚠⚠

SMM and SMR are still being worked on to support new mod distribution format.
Ficsit.app will not recognize your mod if you try to upload it now!
You should restrain from distributing your mods publicly now, until the rest of the system is ready.

We will make a public announcement when that happens.
======================================================
⚠⚠MODDED CONTENT CAN'T BE LOADED FROM SAVE FILES⚠⚠

The main reason we have not announced to the general public that mods are ready yet is because content from mods can't be loaded from save files at all!

If you load a save in this update, even one made in Update 4, modded content will NOT load in at ALL.

You will need to write your own SML Chat Commands to give yourself modded items for testing,
or craft them in-game through normal methods.
We suggest making 'testing recipes' that you will not ship with the mod to ease this process.

We are already in contact with CSS about this, and they will be pushing an update in the next few days to fix this.

Keep this in mind while updating your mods to SML3. Issues with saves are likely not your fault.
======================================================

The rough process of updating your mod to SML3.0 is described in the docs here: https://docs.ficsit.app/satisfactory-modding/latest/Development/UpdatingFromSml2.html

Below, you can find the major changes in SML v3.0.0 as described by Archengius:

NEW MODULE SYSTEM
 - InitMods have been replaced by the new system of modules. There are 3 types of modules, loading at the different moments of the game: game instance (initialized once per game launch, accessible globally), game world (initialized every time game world is loaded) and menu world.
 - Modules can be located under any paths with any names, you no longer have to name your modules like InitMod for them to get hooked by SML, only thing you need is to set "Is Root Module" check on them.
 - Modules can have submodules loaded by calling "Load Module". Submodules can register do everything root modules do, including registering content, checking configuration and so on.
 - Modules of other mods are easily retrievable from anywhere, allowing easy cross-mod integration and communication routines to be implemented. See documentation for examples and possible use cases.

NEW MOD LOADING
 - SML no longer handles any of the mod loading, now it is handled by the Unreal Engine itself and its plugin system. Mods are now located under FactoryGame/Mods and represent folder hierarchies.
 - It allows loading any external plugins into the game as mods, including plugins from UE marketplace or other games. Try new things and go wild!
 - Mod content is now strictly isolated from the basegame and other plugins, each mod's content is mounted separately as /ModReference/ now. You can still access contents of the base game and other games as usual, though.
 - Alpakit has been reworked to support packaging of the mods using new system. In comparison to the old system, there are some new features: mods now have their assets indexed in Asset Registry, can include any external files for their own needs, can include UE configurations and additional binaries.
 - Overwrites have been removed. Use new Reflection Blueprint Library functionality to replace them, and BP hooking and C++ for additional functionality not covered by BP reflection.

NEW SML API: CONTENT REGISTRY, AND MORE!
 - Most of the SML APIs have been majorly redesigned to allow better editor and cross-mod compatibility, which resulted in them being migrated to UE subsystems. You can read more about UE subsystems in it's documentation.
 - NEW: Configuration API. New configuration API allows defining configuration scheme in a new format, specifying additional metadata required for automatically generating User Interface for changing configuration right in the game! NOTE: UI feature is not enabled for now and is still being actively worked on.
 - NEW: Content Registry API. You can now register your content conditionally, e.g change which schematics, research trees or recipes your mod registers based on external conditions like current mod configuration and so on.  It provides huge boost to modularity and configurability of the mods, and also allows implementing cross-mod integration when other mods are present.  As a bonus, it also allows registering alternate recipes and resource sink shop schematics!
 - NEW: Blueprint Reflection API. Several functions of the Unreal Reflection System have been exposed to blueprints to allow building better functionality without using C++ code. See Blueprint Reflection Library documentation for a list of accessible methods and properties.


NEW DOCUMENTATION AND SML PROJECT
 - New documentation can be viewed on https://docs.ficsit.app/. We're still working on updating it and covering new topic, so make sure to check it regularly to avoid missing something! Keep your eyes on #modding-info-feed for pushes to the docs.
* You need to have the latest release of Modded Unreal Engine 4.25, download it from the github. IMPORTANT: Make sure to keep old engine by renaming folder with it, it will make your life much easier when migrating mod content, since you cannot open some of the blueprints based on classes nonexistent in the new SML version (most obvious example would be InitMod and InitMenu)
 - You can get new SML project on SML github (https://github.com/satisfactorymodding/SatisfactoryModLoader). MAKE SURE TO CHANGE BRANCH TO "sml-dev" BEFORE DOWNLOADING!
 - Creation of the mods in new SML version is done by opening the editor, clicking on "Plugins" button in one of the drop-down menus and then using "New Plugin" button to create your new mod. Make sure to use "Content Only" or "Blank"
presets for your newly created plugin.
 - You might need to click on Content Browser's View Options -> Show Plugin Content to view contents of your mod. You can browse to them by clicking on the Content Browser root folder and selecting <Your Mod Name> Content there
 - Satisfactory assets HAVE NOT BEEN UPDATED TO U4 YET. If you're looking to use new items from the Update 4, you will need to create stub blueprints for them yourself. But don't worry, we are working hard on updating project, and new version will include even more content than the old one did.
 - Keep questions related to SML v3.0.0 and U4 transition in #development.

HAPPY MODDING!!!

Fun Facts

Some assorted notes from Archengius:

  • One thing worth mentioning is that SML now runs in "full mode" even inside of the editor. Except that patches are not really registered because we don’t have real FG code there. That would allow us to have a very smooth transition to working PIE once CSS gives us an editor build of the FactoryGame module.