Updating your Starter Project and Mod

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 - there is no way to obtain older versions of the game from Steam or Epic, outside of switching between the two branches - Early Access and Experimental. 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.

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.

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.

Depending on how you downloaded your modding starter project, one of these approches 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 plugins, 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 Plugins folder except those that came with the Starter Project (Alpakit, ExampleMod, SML, SMLEditor, Wwise), 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 stuido 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 the 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 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:

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!