C++ Modding

Utilizing C++ code in your mod allows access to a much wider variety of game systems and features. Furthermore, C++ code is often compiled into far more performance friendly code than its Blueprint equivalent.

However, C++ systems have their own shortcomings as well. Writing a mod with C++ does not mean replacing all of your Blueprint assets with C++ code. The best mods are implemented with a careful combination of both C++ and Blueprint code.

Understanding Blueprint vs C++

Alex Forsythe has an excellent writeup (and corresponding video) that explains the different roles of C++ and blueprint in an Unreal project. Alex’s summary of the article:

It’s not an either/or decision. Learn what makes C++ and Blueprints different, what they have in common, and how to use them together effectively.

You can find the article (and a link to the video) here. You should at the very least watch the video before proceeding. Reading the article is also highly recommended.

Requirements

Well, since this is a very advanced topic, we recommend you to learn C++ and C++ for Unreal Engine first.

We have compiled a list of some helpful learning resources here, but you will probably want to search out some more on your own.

Here is a list of some concepts you should learn before going further:

C++ specific:

  • If/Else

  • Loop Structures

    • While

    • For

    • For Each

  • Lambda Functions

  • Pointers

  • References

C++ concepts which are used but are implemented differently in Unreal Engine:

  • std::string

  • std::vector

  • std::set (And the differences between it and std::vector)

  • Smart Pointers

The Unreal Engine synonyms for the aforementioned concepts (the UE implementation of them):

  • std::string → FString

  • std::vector → TArray

  • std::set → TSet

  • std::(unordered_)set<T> → TSet<T>

  • std::(unordered_)map<K, V> → TMap<K, V>

  • Unreal Smart Pointers

Other stuff added only by UE or general programming concepts:

  • What a UObject/UProperty/UFunction (reflection system) is

  • What an AActor is

  • What garbage collection means, how it works, and how to make use of it

If you have a good understanding of most these concepts, then you have a very solid foundation from which to start modding. If so, this is likely not your first time working on a project or mod like this, and you’ll be able to judge what content you can skip over and learn when needed.

We can not understate the value of learning through doing. Especially if just starting out with these concepts, we suggest that instead of immediately beginning working on a mod, taking the time to make a separate Unreal C++ project for testing and practice. Try out working with the concepts mentioned above before trying to make use of them in a mod.

The following resources may be helpful for you in the creation of your C++ mods:

  • CSS has been kind enough to provide us with the Satisfactory C++ headers. You can find them in the CommunityResources folder of your install.

  • You can find the .pdb files for the game in your install’s Binaries folder.

Dll, pdb & more

When you compile your C++ code into the final binaries (stuff that actually is used by the game) you will get a Dynamic Link Library (.dll) file. When you distribute your mod, you will have to make sure it includes this file. You will need to add it also to your data.json as an sml_mod object. More info on the upload process can be found on the Uploading to SMR page.

This file comes with a companion, the Program Database (.pdb) file. This file holds additional information about the original source code and allows you to debug your code more easily in runtime. You can ship this file with your mod, but don’t need to. If you do decide to ship it, it doesn’t needed to be added to the data.json file.

We won’t go into detail about the general technical stuff aspects of C++ in this documentation. If you want to learn more about that, there are plenty of good resources available elsewhere on the Internet. In order to write C++ mods, you will require both general C++ knowledge, and knowledge about how C++ applies to Unreal Engine systems. You can find a quick guide to the Unreal portion in the Unreal Documentation.

Warning

Due to technical limitations, there are some functions/features of Satisfactory and Unreal Engine that we are not able to access or need to use a work around to call correctly. This is the world we live in right now, and we can’t do much about it.

If you experience a crash or some undefined behavior while using a function from Unreal Engine or Satisfactory, you should read the javadoc comment that has been added to the function. Sometimes the comment will tell you that it doesn’t work and suggest you use the workaround written in the comment.

If it still doesn’t work, and you are absolutely sure that you are using it correctly, contact the SML developers on the Discord for further advice.

If your mod requires calling a Satisfactory function that is not compiled into their binaries, f.e. when the function is marked as inline, then it will create a log entry starting with [FATAL] Executable missing symbol with mangled name. This will you also tell you the mangled symbol name it was not able to find. You can still run the game, but when your mod tries to call this function, the game will crash. The crash may not cause the crash reporter to open, which is a signal that you should then checkout FactoryGame.log since it will tell you which symbol got called. This information will be very useful in fixing the bug, so keep it on hand if you plan to ask for help with your mod on the Discord.