satisfactorymodding / documentation

Documentation for SML and Unreal modding.

Satisfactory Modding Documentation

Documentation for Satisfactory Mod Loader (SML) and Satisfactory modding. Master branch is live on https://docs.ficsit.app/. Please contact us on the Satisfactory Modding Discord Server with questions and suggestions, or contribute via PRs (see below).

We attempt to use Semantic Line Break format in the source files, but this is only loosely followed.

An overview of Asciidoc syntax can be found here.

Pull requests should target the Dev branch.

Before you submit changes, you should probably follow the Development Setup directions below to verify that the pages are displaying as expected.

Documentation for other mods is also served through the same site. If you have written documentation for your mod and would like it to be added, contact us.

Contributing

We greatly appreciate any contributions you may have to the docs. Even if you only have the rough outline of a page done, feel free to contact us on the Discord and we'll help you turn it into a full page.

The easiest way to contribute is to make a fork of the repo, then use a Pull Request targeting the Dev branch for us to review the changes.

Send us a message on the Discord if we don't review it within a day or two.

Development Setup

Devcontainer

If you already have Visual Studio Code and Docker installed, we offer a devcontainer for the repository that will be auto-detected when you open the folder in VSCode.

This also means that Github Codespaces is a pretty convenient way to test out other people's PRs.

Make sure you have the Remote Containers extension and Docker Desktop installed.

Remember to turn off Docker starting with system startup and to close Docker after you're done using it. It reserves a lot of system memory even when not actively in use.

If it doesn't automatically prompt you, press Ctrl+Shift+P to open the Command Palette, then type "Reopen in Container" and select the option that appears.

The container will automatically serve the built content upon opening for preview in your browser or within VSCode, as well as a file watcher to automatically rebuild the preview upon detecting changes. You will still have to manually refresh your browser, though...

If you are switching between container and local dev you may have to delete the node_modules and/or .pnpm_store folder.

Manual

If you don't want to use the preconfigured devcontainer, or Codespaces, follow the directions below.

Although you can edit the .adoc files with just about any editor out there, we suggest either Visual Studio Code (with the Asciidoc and Code Spell Checker plugins) or IntelliJ.

In order to see what the pages will look like on the live site before being deployed, follow the below directions.

Installing

1. Install Node.js (the CI uses 16 but newer should be fine) and pnpm Package Manager through your preferred method.

2. Clone the repository

3. Use pnpm to install dependencies

pnpm install

Building

To set up a development watch server that will automatically rebuild the docs when you make changes:

pnpm run watch:dev

To build the docs for SML and all other hosted mods (slow):

pnpm run build

To build the docs for just SML (much faster):

pnpm run build:dev

The output HTML files for both commands can be found in \build\site.

Previewing

To preview the content, you can open the output HTML files in your browser, ex. build/site/satisfactory-modding/latest/index.html

You can also run pnpm run serve which will start a local webserver.

Link Checker

The CI will also run the lychee link checker to check for broken links. Its reports can be found in the the Actions tab of the repo. You can optionally install the tool yourself if you want to run it locally by following the lychee documentation.

Adding Docs for Another Mod

If you'd like, you can write docs for other mods and have them be included on the live site.

Mods that have done this include FicsIt-Networks, Refined Power, Ficsit Remote Monitoring, TweakIt, and more.

Contact us for more details if you'd like to set this up. The general steps are below:

• Create a repository with your documentation files
• Enable github actions on your repository
• Edit the antora-playbook-ci.yml and antora-playbook.yml files to add your repo as a Source. Follow the format of the other mods already listed there
• Make sure you can build this docs repo locally with your site added as a source. Run the build task defined in package.json to do this. Consider temporarily commenting out other mods' repos to speed this up.
• If you want the deployed copy to automatically update when you push changes to your repo, you should set up an Actions file similar to this one and contact us on the Discord to get a token to add to your secrets so the Actions file can function.
• PR the Dev branch with your changes to the playbook files.

Sub-mod documentation sites are currently still subject to the Lychee link checker run by our CI, so if you have broken links in your docs, the build will fail and your site will not be updated. You can check the Actions for this repo to see if/why they failed. Mod docs updates are started by the SatisfactoryModdingBot github user under the action name mod-docs-update.

Adding new version branches

We typically create new version branches once a new major or minor version of SML has released. The goal is to provide a point of reference in the docs for working with older versions.

In order to add a new frozen version branch of the docs:

1. Create a branch on a commit following the name format vX.X.X, for example, v3.1.1
2. Add the branch name to the branches list in antora-playbook.yml and antora-playbook-ci.yml
3. Edit antora.yml on the branch to have a version that matches the branch name (instead of latest). Here's an explanation of why that needs to happen.
4. You're good to go - CI will take care of deploying it for you.

documentation's Issues

First Simple Machine Information Correction

On the page "First Simple Machine", when creating the connectors, the page says, "Set the output component’s direction property to output and the type to Item." I believe "type to Item" should be changed to "Connector to Conveyor".

The discord link is no longer valid

I have tried to join the discord server, on the web and on github and all the links indicate that they are expired

Remove the outdated page linking to the custom splitter videos

Splitter logic optimization means they are no longer relevant

Updating guide: tell people to switch branches and not just to pull because we don't know what branch they pulled in the past

https://discord.com/channels/555424930502541343/601030071221878784/1130583507744342156

Localization docs (Arch posted screenshots that can be used as images)

Updating guide: what to do about the wwise popup

https://discord.com/channels/555424930502541343/1036634533077979146/1131263355483594842

Implementing ADA messages

Sound generation:

• How to view all existing base-game ADA messages (check crowdin or
• Google TTS settings
• Post processing settings
• Advice for how to make ADA say common SF words the "right" way
• Suggested volume level (dB) to be consistent with base game voicelines
• Suggestions for how to capture audio without having to set up the google cloud account

In-game message playing:

• Setting up message assets
• Triggering messages in response to schematics via the story queue
• How to trigger messages "manually"
• Playing sounds in the ADA voice category
• Maximum character length before the popup messages get cut off

Kyrium shared some example code for this
https://discord.com/channels/555424930502541343/601030071221878784/957712385102184448

New FModel and wwiser sound extraction directions

Minor issue: Link to VS build tools no longer links the 2017 version we need

The new link should be https://visualstudio.microsoft.com/vs/older-downloads/

CDO documentation: how to trace back (from a blueprint) what class owns a field

Example case of mCompatibleItemDescriptors
https://discord.com/channels/555424930502541343/862002311579435028/1119137179919204352

Remove Algoia search (replace with Github repo search) or make it only search Latest

Replication docs page

Add docs note about multiplayer replication SML RCOs multicast not working because they're on controller -> not on every side, instead need to use a replicated subsystem or similar for this

Invalid Hyperlink

https://docs.ficsit.app/satisfactory-modding/latest/UploadToSMR.html#_smr_uplugin_validator

Contributing guidelines

Hey guys, Thanks for the great work.

I'm currently tickering with SML for the first time, working on implementing a new Equipement in game.

The docs are currently very lackluster around that topic, are PR welcome ? If so, should we target develop or master ?

Server Only Mods - Requesting improvement in documenting this data.json feature.

Currently the description of the 'remote_version' field is as follows.

Version number defined by your mod which is used for allowing different version of the mod to be playable with each other in multiplayer. You can think about it like a protocol version.

However, it is not noted that you can set this to * to accept any version. Which Archengius has clarified that for SML, a 'Server Side Mod' is a mod that accepts any version (where I'm assuming based on the wording that any also includes none).

Having this mentioned in the documentaion would be quite useful.

I was also going to originally suggesting adding a footnote about this somewhere other than the Uploading to SMR page as I doubt that is where anyone would look for info on it, However, I can't find a good page to suggest.

"Welcome to the Community" guide

Currently this info is spread across a bunch of discord bot commands and outdated ficsit.app guides that can't be edited by the community.

It should cover:

• Navigating SMR
• How to download SMM
• Walk through using SMM to install a mod
• SMM and mods are safe as long as you download them from ficsit.app, even though the computer may warn about running it, we just don't pay for a certificate (see the >virus Fred command)

it should replace these bot commands:
>welcome
>newbie
>virus

Update to mention support for nested plugin folders

Allows git repos with multiple plugins in them to be within the plugins folder of an modding starter project repo.

The Asset Toolkit docs can probably be updated to mention this as well.

https://discord.com/channels/555424930502541343/1036634533077979146/1084261362294857809

New launch arguments

Unsure if this is in SML3.5 or not. From Arch:

-noexceptionhandler (UE added) - Disables main SEH exception handler. That prevents crash reporter from catching SEH exceptions (namely, access violation), and allows the debugger to handle them instead.
-WaitForDebugger (UE added, SML handled in Shipping builds) - Waits for the debugger to attach at the start of the game. In shipping that would be during SML initialization, otherwise it would be inside of the engine loop.
-BreakIntoDebuggerOnErrorAndEnsure (SML added) - Makes failed ensures and checks break into the debugger if it is attached.

https://discord.com/channels/555424930502541343/562722670974599227/1044561843559075900

Practical example multiplayer guide

A Getting Started style of example that covers using RCOs to support multiplayer functionality.

Perhaps a machine with a widget that clients can open and cause values to change on the server with

Playing Sound that respects the volume sliders example

PowerSuit Modules has examples for now

Look at game user settings file to find volume category names

Quality of Life Mods (Typo)

The note section at the header of this page reads:

'This page serves as a temporary solution until the Mog Tags system is implemented on the Mod Repository.'

and should read Mod Tags

SCS and blueprint hooks helper docs (Arch made an example in ExampleMod)

Custom power generator (solar panel?) building guide

Update UE repo links to point to the new in-org repo

From https://github.com/SatisfactoryModdingUE/UnrealEngine to https://github.com/satisfactorymodding/UnrealEngine

License

Would it be possible to add a license to this project rather than for only the documentation itself?

Cannot find "M Interact Object"

On page "SimpleInteraction" there is stated
"The FGInteractWidget has the M Interact Object variable which represents the ...".

I created a blueprint class from FGInteractWidget besides buildable stuff.
But it does not show the "M Interact Object"-variable when I open it in the designer.

Cpp input action binding info

https://discord.com/channels/555424930502541343/862002356626128907/1130872287197937825

Name change "Mod Savegame Settings"

More information about Bootstrapper's pre-launch-debug log and the missing symbol warnings.

Request: More information in the docs about the pre-launch-debug log provided by the Bootstrapper and the information it provides. Specifically in relation to Missing Symbols information it provides and how to go about determinating which symbol is missing.

Reason: While trying to develop a multithreaded TCP server in my mod, missing symbols were causing UE to close without presenting an exception or logging an error. Unfortunately, due to Visual Studio freezing when loading the FactoryGame symbols, Debugging via VS was not possible. After discovering that there was a log file for the boostrapper which lists these missing symbols and specifically states they are missing, I was able to determine that missing symbols were the issue.

The warning on the C++ Modding page, while being sufficent to explain what to do when you know you have a missing symbol, Unfortunately there is nothing to tell you where to look to determine if a missing symbol is the reason for the issue. And currently, there is no mention of the pre-launch-debug log file anywhere in the docs.

Can't build the docs

I get the following error while building the docs:

artemachka@artemachka-VirtualBox:~/Satisfactory/Documentation$ yarn run build
yarn run v1.22.17
$ antora antora-playbook.yml --clean --fetch
[clone] https://github.com/satisfactorymodding/Documentation.git [####################################################################################################]
[clone] https://github.com/CoderDE/FicsIt-Networks.git [####################################################################################################]
[clone] https://git.hostxtra.co.uk/publicrefinedrd/refinedrddocs.git [####################################################################################################]
[clone] https://github.com/Feyko/Tweaker.git [####################################################################################################]
[clone] https://github.com/porisius/FicsitRemoteMonitoring.git [####################################################################################################]
[clone] https://github.com/Kyri123/KMods-Docs.git [####################################################################################################]
[clone] https://github.com/budak7273/ContentLib_Documentation.git [####################################################################################################]
error: Duplicate nav in Development@ficsitremotemonitoring: modules/ROOT/nav.adoc
1: docs/modules/ROOT/nav.adoc in https://github.com/porisius/FicsitRemoteMonitoring.git (ref: dev)
2: docs/modules/ROOT/nav.adoc in https://github.com/porisius/FicsitRemoteMonitoring.git (ref: main)
Add the --stacktrace option to see the cause.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

I guess it is connected to this commit. After reverting the commit I was able to successfully build the docs.

Multiplayer page updates

Move the discord's FAQ onto the docs as a page

Currently only Baine has the ability to edit the FAQ messages, so moving it to a docs page would give the community easier access to editing it. Let Robb/Baine know when done so the FAQ channel can be replaced with a link to the page.
https://discord.com/channels/555424930502541343/555515430681313300/1084897096181760001

Also, add:

• directions from the >offscreen command to the FAQ page, and redirect the command to this page
• "Can I add mods to a save I have already started played on for a while?
  It varies depending on the mod, but in general, yes. The mod should say on its mod page on ficsit.app if it can't be added to an in-progress game"

Example Buildable and docs hologram suggestion inconsistency

https://discord.com/channels/555424930502541343/862002311579435028/1122442558191186030

Creating buildables leveraging the abstract instance system

https://discord.com/channels/555424930502541343/862002311579435028/1083319192624840764

SML3.5 Simple Construction Script documentation

https://discord.com/channels/555424930502541343/562722670974599227/1044583953471909928

Buildable

Hi all,
just finished the "Buildable" Tutorial and found out:
When adding the Descriptor, you have to add a fitting Subcategory to the Build Category, or the recipe will not appear in the Build Menu for the build gun (you can only find it with the Search function).

Add information on how to make SML working on Linux

After a bit of searching and asking in the Discord channel I figured out that what works (even if it's not all the functionality) is to:

• do the manual installation
• set the steam launch option for satisfactory to WINEDLLOVERRIDES="msdia140.dll,xinput1_3.dll=n,b" %command% (or the equivalent with lutrix/epic/whatever)

this is not terribly complicated for someone that is already doing the manual installation, so it'd be useful to have it mentioned there. Some things that could be mentioned:

• mentioning that you're supposed to set an environment variable (so people who don't understand know what to google, and people who do get the idea)
• the wine wiki entry on the WINEDLLOVERRIDES environment variable, to give context.

If you point which branch it should go to I can make a pull request with these changes.

VS2019

Following the instructions with VS2022 doesn't work as the directory
C:\Program Files\Unreal Engine - CSS\Engine\Extras\UnrealVS\

only has:
VS2015
VS2017
VS2019

These are not compatible it seems with VS 2022.

Either a new plugin needs to be found or the user needs to be directed to install to VS2019 instead of VS2022 earlier in the tutorial.
VS2019 downloads exists here.
https://my.visualstudio.com/Downloads?q=Visual%20Studio%202019

I'm not sure if another plugin can be located so I reported an issue before editing the page as I didn't find anything when searching through the internet.

Instructions Needed (Provided) for Getting Started's Create An Item Tutorial

I would like to recommend changes to the BeginnersGuide/SimpleMod/item.html page. It is currently redirecting users to Conveyor Rendering, but that page is noted as out of date. A far better and current link would be Development/Modeling/MainMaterials.html#_factory_baked_mm_factorybaked. If you want to include the some hand-holding steps, that would probably be useful too.

1. Navigate to Content\FactoryGame\MasterMaterials
2. Right-click on MM_FactoryBaked and select Create Material Instance
3. Drag-drop the new MM_FactoryBaked_Inst into the folder with your mesh, and select Move Here
4. Double-click the new MM_FactoryBaked_Inst
5. Under Global Texture Parameter Values, enable Normal and set it to Tex_Doc-Item_N
6. Enable Albedo and set it to Tex_Doc-Item_AB
7. Enable ReflectionMap and set it to Tex_Doc-Item_MREO
8. Double-click on your item mesh (from Mesh_Doc-Item in the example), and set the Material Slot Element 0 to MM_FactoryBaked_Inst.

Great tutorial! Thank you!

SMl3.5 changes

Switch from yarn to pnpm

https://discord.com/channels/555424930502541343/830842478956642354/1121212387706544159

Google is caching outdated version 1.0.2 in search results

See this discussion in #smr-dev on the Discord: https://discord.com/channels/555424930502541343/830842478956642354/1072025195621130341

Seems like this may need to be fixed by the DNS owner?

Possible helpful links from that discussion:

• https://developers.google.com/search/docs/crawling-indexing/ask-google-to-recrawl
• https://developers.google.com/search/docs/crawling-indexing/canonicalization-troubleshooting

When I personally try rebuilding the docs from that far back on my machine, 1.0.2 suffers from this issue, but it doesn't seem to happen on any other branch, nor do I see where Antora is actually deciding what to fill the canonical link field with.

Dediserver guide for mod creators

• what VS targets to build for to have dedi support
• how to list your mod as having dedisupport on SMR (but I think this should happen automatically based on what build targets you uploaded?)
• how to build just shipping/dev editor for your own testing so you don't recompile dediserver every single time you build a test version and don't need it
• an explanation of how dediservers differs from regular multiplayer (stuff like "everyone playing is a client" and "really important to make sure you get your multiplayer code working right, because if it 'just works for the host' that means it won't work for anyone in mp")

Replace Simple Machine with guide for creating a custom manufacturer

Simple Machine is currently an item counter implementing custom grab logic with blueprint code.

• Not really a common use case
• Bad for performance (should do in C++ instead)
• Current example has crashing problems that are probably threading related
• Hologram is broken for it

A custom manufacturer tutorial might be longer but would cover more meaningful topics

Switch to FModel instead of UModel

Access transformers format fix

https://discord.com/channels/555424930502541343/562722670974599227/1129793073979863080

Page for "sml blueprint utility functions" ex. Arch's new sort with comparator function

Localization tutorial

ExampleMod and SML are also localized now in the starter project
https://discord.com/channels/555424930502541343/562722670974599227/1044365548722602005

"How to clone an open source mod into your project" tutorial

Also a page with links to open source mods that are good examples of various topics

First Simple Machine: there's no "type" on output/input components

Hi, the docs' First Simple Machine there's a paragraph that states:

Set the output component’s direction property to output and the type to Item. Do the same for the input component, but change its direction property to input.

I searched carefully, but I couldn't find any type on output/input components 😕

https://docs.ficsit.app/satisfactory-modding/latest/Development/BeginnersGuide/SimpleMod/machines/SimpleMachine.html#_create_the_machine