Updating your Mod and Starter Project

Make sure to check the docs sidebar to see if there’s an Updating guide written for the version you’re updating to! It will have special directions and information that will save you a lot of time.

They’re near the top of the Development section, usually directly above this page’s listing.

When Coffee Stain updates Satisfactory, changes can occur to game internals that require mod developers to update their mods.

This page will cover the general process of updating a mod development environment from one version to another, and things to look out for when seeing if your mod still works after transitioning.

Why Mods Need to Update

Whether or not a game update or SML update requires a mod update depends on a number of factors:

  • What game systems the mod interacts with

  • What game systems the game update modified

  • What files Coffee Stain changed in the background, even if they weren’t mentioned in the patch notes

  • Unreal Engine version transitions

  • Significant changes to SML APIs, usually denoted with a major version number bump

If the systems a mod is working with wasn’t touched by an update, it could end up working without any changes.

Avoid Breaking in the First Place

There are a few measures you can take in order to decrease the chances of your mod breaking on an update.

  • Avoid header edits if at all possible. Instead, use Access Transformers.

  • Use already-established systems to implement behavior. For example, use the SML Keybinds system instead of writing your own keybind handling logic. Then, if it breaks, there are more people on board to fix it, rather than just you.

  • Consider implementing some functionality in Blueprints, since they are generally less likely to break when header updates occur. This comes at a nonzero performance cost, but that discussion is out of the scope of this docs page. Consider the case of Pak Utility Mod, which has required extremely few updates in the scale of things, partly because it uses no C++ code.

How to Tell Something Broke

Sometimes, game systems will change in a way that breaks your mod, but not enough to cause it to crash on startup, or crash at all during normal gameplay. For example, if a base-game material or texture file you were depending on is moved or removed, it will silently be replaced with a default or None value!

In cases like this, it can be hard to track down these failures, especially as the scope of a mod grows to have more content and work with more game systems.

Here are some approaches you can follow to detect problems caused by updates.

  • Listen to Your Users

    Make sure that there’s an easy way for users to contact you with problems if/when they find them. This could involve listing your Discord tag on the mod page, setting up and linking your Github issues page, etc. Here is an example Github issue template you may find useful.

  • Keep an Old Game Version On Hand

    If your mod has complicated behaviors, it may be beneficial to make a local copy of the previous version of the game before updating. If you feel like something changed, you can follow the same procedures in each version side-by-side to find discrepancies. Also, if an asset you need was removed during the update, you may be able to go back and extract it from the old copy of the game.
    The process for doing this will be described in more detail in another section.

  • Run Standard-ish Tests

    Consider writing behavior-driven development inspired tests for yourself (or generous users) to manually perform after an update. By walking through the procedures that a new user would follow to start working with your mod, or through common interactions a user would have, you can find issues before your users report them to you.

    For example, with the PowerSuit Modules mod, a good test would be to craft a new suit, install the Jetpack Module, spawn in a specific amount of fuel items, and fly to the top of a fixed height structure, recording fuel levels before and after flight. This imitates a common user activity, and performing it would help detect any differences in the various mod systems between updates.

Before you Proceed

Below is a sequence of steps to follow while updating if you want to be as careful as possible.

Depending on the size of the update, you may be able to skip some of the steps, but it’s better to play it safe than regret not making a useful, time-saving backup!

Storage space is cheap, your time is not.

Back Up Your Game

As described in the 'Keep an Old Game Version On Hand' bullet, by keeping an old install of the game on hand, you can check behaviors or retrieve assets that may have been deleted during an update.

In order to do this, simply make a copy of your entire game install directory, and put it somewhere that Steam/Epic won’t try to meddle with it.

Note that you can only do this before updating your copy of the game - outside of switching between the two branches, Early Access and Experimental, you can’t go backwards in update history. This is a great reason to turn off auto-update, so that you can make a copy before Steam/Epic pulls out the rug under you.

There is an involved process for downloading older versions of the game from Steam, as described in the FAQ, but it is time consuming and you’ll save a lot of time by making backups instead.

After making a copy, you are safe to update your game install as you normally would.

You can use the launch scripts in the Testing/Multiplayer Testing page to launch this separate copy of the game while still having the new copy set up (even running at the same time) on Steam/Epic.

Back Up Your Old Engine

When Coffee Stain updates to a newer version of Unreal Engine, or in the occasion that the SML team patches the engine for various reasons, you will have to update your locally installed Editor to build mods for the new version.

We strongly suggest that you keep the old editor installed until you are done porting your mods so that you can reference settings, blueprint fields, and code you have written that may have been removed or made impossible to open due to the update.

In order to have both the old and new version of the editor installed on your computer, you should do the following:

  1. Navigate to your editor 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_Previous-SML-Version-Here\ 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_Previous-SML-Version-Here\Engine\Binaries\Win64\UE4Editor.exe

  6. Install the new editor build from the directions in the next section

  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.

You may have to edit a registry key entry to fix this - ask on the Discord for help with this.

Install the New Engine

The new editor version can probably be downloaded from the GitHub releases page, but you should keep your eyes on the Discord to see if a specific branch or download link is mentioned instead. The specific files to download are described in the Dependencies guide.

Remember, if you see a 404 page following that link, the page is not dead, you need to log into the right GitHub account. More info on this can be found here.

Fixing the Start Menu Shortcuts (Optional)

If you typically launch the editor via the Windows Start Menu you will likely have to repair the shortcuts there after moving engine folders around. You can open the folder containing the shortcuts by searching for "Unreal Engine - CSS" in the start menu, right clicking on the shortcut, then choosing "Open File Location". From there you can edit the shortcut’s properties to configure its target, name, and launch location.

You may also want to assign custom icons to each shortcut. This will change the appearance of the editor in the taskbar, making it easier to distinguish between multiple versions of the editor running at once. You can create your own icons or use these ones from on the Discord. You may have to restart your computer for the icon changes to take effect, as windows aggressively caches icon images.

Preparing to Update your Starter Project

Depending on how you downloaded your modding starter project, one of these approaches will be easier than the rest, or you may have to use one to get what you want.

You should read both options in full to make an informed decision.

Option 1: Fresh Starter Project

If you have a small, self contained mod, or the changes to SML or game systems are immense, it may be easier to simply set up a new starter project than bother trying to update your existing one.

Note that getting a new starter project doesn’t mean starting over on your mod - you still keep all of your mod-specific files.

If you have lots of project-level specific settings, such as special packaging rules or editor configurations, this may not be ideal.

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.

Your mod’s files are probably all within its plugin folder, so you can simply transfer over that entire folder to the Mods folder of the new project. Remember to regenerate Visual Studio project files and build after you do this.

Bring Over Editor Configs

Editor settings are stored at the project level, and if you have any special ones, you probably don’t want to lose them when you update. They are stored in the /Config/ folder. For example, Action Mappings are stored in DefaultInput.ini. You should git diff the files to make sure that you are adding any new fields that were introduced by the update, while still keeping the old values you want.

Option 2: Replace Changed Files

If you have a lot of mods set up in one project, the changes to SML or game systems are small, or you want to preserve your project’s git history, (not mod, that would still be preserved by Option 1) this may be the route to update your existing project.

After performing any of these approaches, you may or may not have to integrate Wwise again. You can find directions for that here.

How to proceed from here depends on how you originally downloaded the starter project.

No matter which of the below situations applies to you, you should absolutely make a backup copy of the old project before trying to move anything. Even if you are a git wizard, it’s a lot simpler to completely toss a broken copy instead of trying to patch it up again.

Option 2A: You Cloned or Forked the Starter Project

You will have to pull (if you cloned) or merge (if you forked) the changes made in the main SML repository. You may also have to switch branches and/or check out a newer commit. Check the Project Setup page to determine what branch/commit you should be on.

There are a few files that will likely have been automatically modified, and you will have to discard or stash your own changes in order to merge in the upstream changes without conflict.

They include, but are not necessarily limited to:

Once you have stashed or discarded your changes to these files, you should be able to pull/merge in the files.

You may wish to delete some project temporary folders, especially after an engine update, to save on disk space.

  • <project directory>/Intermediate/

  • <project directory>/Build/

  • <project directory>/Binaries/

  • <your mod’s directory>/Saved/

Dealing With the Content Folder

The content folder will be regenerated with most game updates so that stubs are in the correct places.

Most Unreal Engine asset files are raw binary files, which means git diffing them is difficult. Panakotta has directions on using UE as diff tool here, but in the case of almost all base game assets, you probably just want to throw out the old ones and bring in the new ones instead.

This will involve a lot of changed files, but since the starter project ships with only stubs, they are tiny in file size.

Option 2B: You Downloaded a Zip of the Starter Project

Git is a powerful tool, and although it might take a bit to learn, it definitely pays off in the long run. Consider cloning the project instead to make future updates easier.

You will have to delete all of the old files and folders and copy in the new ones. It’s important to delete the entire directory of old files first to ensure that you don’t accidentally leave something around that was deleted in the update.

You can use GitHub’s branch/tag compare functionality to see what changed. Just keep in mind that it can’t preview uasset files for you.

As a general overview, changes could include any or all of the following:

  • /Content/ stub files

  • /Source/

  • /Config/

  • /Plugins/

  • /Mods/AccessTransformers/

  • /Mods/Alpakit/

  • /Mods/ExampleMod/

  • /Mods/SML/

  • /Mods/SMLEditor/

  • FactoryGame.uproject

  • .gitignore

Option 2C: You Have a Project Level Repo

Possible reasons to have a project-level repo include working with lots of copyrighted files, having a complete starter project, working with a team of people on multiple interdependent mods at once, or having custom project settings you want to preserve.

If you have a project level git repo, your project git history is probably vastly different from the base SML repo, so trying to merge in the changes is likely infeasible.

You’ll have to go through most of the same process as the zip project download.

Updating a Complete Starter Project

If you have generated a complete starter project using the Asset Toolkit, you will need to do so again to get the updated base-game files, since numerous assets will have changed, even if not mentioned in the patch notes.

You should delete your entire previous base-game Content folder, as well as the stubs from the starter project you may have copied in during earlier update steps. It’s important to fully replace the folder to be sure you don’t have any no-longer-existing assets in there, which could lead to confusion or name conflicts when trying to use them in your mods.

Remember to copy back in AngryBeaver’s recreated assets. The process for doing this is covered on the Asset Toolkit page.

Also, make sure to download an updated version of the Asset Toolkit mods, because they may have been patched since you last generated your project.

Watch Out: Complete Starter Projects and Version Control

If you are using a project-level git repo and you have generated a complete starter project, updates present an additional risk.

You must be careful with how you bring the regenerated assets into version control. GitHub (and most other VC platforms) has a size limit on how big they will alow an individual commit to be, and hitting this limit is quite feasible when bringing in this many assets.

Before committing the regenerated assets, consider running a TreeSize or WinDirStat analysis to find out which directories are the largest so that you can split up the changes into separately committed and pushed units.

If you accidentally make a commit too large, you will have to use git rebase to break it apart into multiple smaller commits and make it possible to push your repo again.

Making Sure the Starter Project Update Worked

Now that you’ve brought in the updated files, you should try to build and open the editor to make sure it worked correctly.

This step allows you to catch any problems that could have occurred now, as opposed to later when you’re trying to fix your mods, and it’s unclear what the cause is.

Temporarily move out all items from your Mods/ folder except those that came with the Starter Project (Alpakit, ExampleMod, SML, SMLEditor), regenerate Visual Studio project files, and rebuild the project. This ensures that any potential problems with your mods don’t affect the build process.

If it worked, you should be able to build and open the editor.

If Unreal complains about your project being compiled for a different version of the editor, close down the Editor entirely - do not use any of Unreal’s prompts to port the project. Instead, open your FactoryGame.uproject and modify the EngineAssociation field to match the updated version number.

After you’re sure the editor is working with just SML loaded, move on to the next sections.

Dealing with Multiple Mods in One Project

If you develop multiple mods in the same project, odds are that one of them will not work after an update.

Even if the mods are totally separate from each other, Unreal could prevent you from packaging any mods at all while a non-working mod is also present.

You may need to temporarily move out some of the troublesome mods to allow building others.

One way to do this is to rename the uplugin file to <ModReference>.uplugin.disabled to stop Unreal from loading it. You will probably have to regenerate the Visual Studio project files if you do this. Directions for that can be found here.

Since the uplugin file is the only file you’re changing, this approach lets you turn off mods without causing a torrent of Git file changes.

Preparing to Update a Mod

If your mod has dependencies, you should update them first, ideally without your dependent mod present in the project. Consider disabling the dependent mod via the approach described above until the dependency is ready.

If you keep your mods in separate plugin repos, consider creating a branch or tag on each named after the game version the code supported (ex. Update5) so that you (and others) can refer back to it later if needed.

The Cycle of Updating

Your updating process will cycle through the following steps:

  1. Attempt to compile the Visual Studio project

  2. Deal with Visual Studio build errors by:

  3. Repeat steps 1-2 until the project builds successfully for both Development Editor and Shipping

  4. Open the Unreal Engine Editor for your project

  5. Run Alpakit on SML to install the latest version of SML in your copy of the game, or install it via SMM. Problems in your own project files could prevent packaging from succeeding - if you encounter any, see Step 7.

  6. Run Alpakit on your mod to see what fails (or maybe it works the first time!)

  7. Deal with errors that Alpakit finds. Possible problems include:

    • Blueprints that 'just' need to be opened and recompiled (see Beware of Changed Files section)

    • Missing assets. Look back in your backups to find out what they were, try to find their new locations, and replace them or extract the files from your old game copy if needed.

    • No-longer-available function calls. To-Do comment them out or try to replace them.

    • Something else entirely. Consider asking for help on the Discord.

  8. Repeat steps 6-7 until Alpakit builds your mod successfully

  9. Launch the game with your mod installed

  10. Resolve crashes that occur when you try to launch the game

  11. Restore the functionality you had to comment out or unhook in steps 2 and 7

  12. Test functionality in your mod to ensure nothing has broken

  13. Resolve any problems you find by testing your mod further

Below are some notes on a few things to watch out for.

Seemingly Ignored Access Transformers

Sometimes, compilation in Visual Studio will fail due to your mod trying to access private fields of various classes, even though you have already have added said classes to your mod’s Access Transformers.

You can resolve this by changing any line in that mod’s access transformers file, for example, a comment (which are denoted with ; semicolons.) The line can be changed back later; modifying the file will make the compiler rebuild the access transformers correctly. More info on why this works can be found on the Access Transformers page.

Alternatively, a full rebuild should also fix this.

Beware of Changed Files

If you open a file and see that Unreal wants to save it after you haven’t changed anything, you should be cautious and try to find out what field may have changed on you. Sometimes Unreal will complain nosily about problems like this (ex. missing blueprint library, parent class not found), but sometimes it will silently replace it with a None reference (ex. textures or materials)!

If you open one of your mod assets, and it’s broken for some reason (or has a missing reference), DO NOT SAVE IT! You will be saving the broken reference over the correct value.

If you do save the file, or Unreal saves it on you, go into version control and discard the changes. As long as you can avoid keeping the saved copy, if you restore the missing referenced asset, it will be back without data loss next time you open the editor and/or file.

This is one of the many reasons to keep a copy of your old project. You can find out what used to be in that field, then go fix it on all of your assets in one fell swoop without having to hunt down each usage.

In the case of a missing or damaged parent class, looking at backup is one of the only ways to get info out of the inoperable asset.

Missing Parent Class

It’s possible that, after an update, the parent class of one of your assets has changed due to Coffee Stain or another mod developer moving the location of the class on their end.

A broken parent class almost always makes an asset unable to be opened in the Unreal Engine Editor. Hopefully you followed the directions in the Back Up Your Old Engine section, because if you did, you can open up the working version of the asset in the old editor and find out field values and other settings you configured.

You can also try to set up a Core Redirect in order to tell Unreal about the location of the new parent class, which may make make it possible to open the asset in the editor again. See the linked page for more details.

Releasing An Update

Once your mod is updated and you’ve done sufficient testing, it’s time to release an update to the Mod Repository.

You’ll want to do the following things:

  1. Write up patch notes for the update. This should mention any new features, bugfixes, or changes to existing features introduced by this version.

  2. Update the sem version number in your mod’s uplugin file. You can do this from the Alpakit Edit Mod wizard. Remember, this number is in the Major.Minor.Patch format. In general, follow these rules to decide what your new version number should be:

    • You should not go "backwards" in total version number. For example, don’t release 1.1.0 after releasing 1.2.0

    • If this update is only fixing bugs, you should increment only the Patch number. (Example: 1.2.9 to 1.2.10)

    • If this update adds new features and is not likely to break compatibility with other mods, you should increment the Minor number and reset the Patch number back to 0. (Example: 1.9.3 to 1.10.0)

    • If the update is a significant rewrite or certainly breaks compatibility with other mods, you should increment the Major number and reset the Minor and Patch numbers back to 0. (Example: 1.9.3 to 2.0.0)

    • More info can be found on the Releasing Your Mod page.

  3. Update the version range of your mod’s dependencies. For example, every mod depends on SML, and the version of SML it depends on determines what game versions it is considered compatible with. Find the latest SML version number by checking its Alpakit Edit Mod wizard in your editor or by checking the SML releases page. You probably want to be using the caret range specifier here (ex. ^3.6.1) whose functionality is described in the Plugins > SemVersion section of the Releasing Your Mod page.

  4. Follow the directions on the Uploading your Mod to SMR page to release the update

You’re (Hopefully) Done

If you’ve gotten this far, you should have completed the process of updating your mod and starter project.

Or, if you were reading through, you’re better prepared to update in the future.

If you think this guide skipped over something, you found a mistake, or you’d like to contribute more to this guide, please speak up on the Discord or open a PR.

Thanks for reading!