Updating your Mod and Starter Project

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

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

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

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

Your updating process will cycle through the following steps:

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

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:

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!