From 96ddfe42e6f4b9e0694c8fab159fe53ff2e4a143 Mon Sep 17 00:00:00 2001 From: Jesse Hodgson Date: Thu, 13 Nov 2025 11:40:43 -0500 Subject: [PATCH 1/2] Add page for setting up the modding environment on Linux --- modules/ROOT/nav.adoc | 1 + .../BeginnersGuide/LinuxSetup.adoc | 159 ++++++++++++++++++ .../BeginnersGuide/dependencies.adoc | 38 ++--- 3 files changed, 179 insertions(+), 19 deletions(-) create mode 100644 modules/ROOT/pages/Development/BeginnersGuide/LinuxSetup.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 76209940..82851464 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -24,6 +24,7 @@ ***** xref:Development/BeginnersGuide/StarterProject/StarterProjectViaClone.adoc[Option A: Git Clone] ***** xref:Development/BeginnersGuide/StarterProject/StarterProjectViaZip.adoc[Option B: Download Zip] *** xref:Development/BeginnersGuide/project_setup.adoc[Project Setup] + *** xref:Development/BeginnersGuide/LinuxSetup.adoc[Linux Setup] *** xref:Development/BeginnersGuide/StarterProjectStructure.adoc[Starter Project Structure] *** xref:Development/BeginnersGuide/SimpleMod/index.adoc[Create a Simple Mod] **** xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Plugin Setup and Game World Module] diff --git a/modules/ROOT/pages/Development/BeginnersGuide/LinuxSetup.adoc b/modules/ROOT/pages/Development/BeginnersGuide/LinuxSetup.adoc new file mode 100644 index 00000000..2685bfdc --- /dev/null +++ b/modules/ROOT/pages/Development/BeginnersGuide/LinuxSetup.adoc @@ -0,0 +1,159 @@ += Setting Up The Modding Environment on Linux + +The Satisfactory Modding Environment is also available for you to develop if you are on a Linux-based platform. + +NOTE: This is for setting up the Modding Environment on Linux. If you are on Windows, please follow the guide xref:Development/BeginnersGuide/dependencies.adoc[here]. + +== Prerequisites + +Before we can begin, we must install the following packages with our distro's package manager. +On Debian-based systems such as Ubuntu, this would be `apt install`, or `dnf install` on Fedora. + +* `git` (For version control) +* `msitools` (For `msiextract`, used by `vsdownload.py` of msvc-wine) +* `tar` and `zstd` (For decompressing the engine archive) +* `dos2unix` (For the Wwise patches, used by the SML project) + +For example, on Fedora this would be + +[source,bash] +---- +dnf install git msitools tar zstd dos2unix`. +---- + +== Engine Setup + +Now we can begin setting up our custom version of Unreal Engine. + +=== Download MSVC + +First, we must install MSVC using msvc-wine: + +Copy and paste this into your terminal, but be sure to first swap `` to the directory where you want to install MSVC, then run it. +This will automatically clone the msvc-wine repository and use it to download the correct version if MSVC for the editor to use. + +[source,bash] +---- +git clone --branch ue-patches https://github.com/mircearoata/msvc-wine.git + +cd msvc-wine + +./vsdownload.py --accept-license --dest "" --msvc-version "17.4" --sdk-version "10.0.18362" --channel "release.ltsc.17.4" + +./install.sh "" +---- + +Next, you'll need to edit either `/etc/environment` or `~/.profile` with a tool such as Neovim, to set the `UE_WINE_MSVC` environment variable. + +For example: `UE_WINE_MSVC=""` (make sure to surround the directory in quotes) + +Then you may need to log out and back in, or restart your PC for the change to take effect. + +=== Download the engine + +You can do this one of two ways: Either build the engine from source, or download an already built archive from the GitHub CI. + +==== From Source + +Clone the `5.3.2-CSS-linux` branch of https://github.com/satisfactorymodding/UnrealEngine (A source build can take at least 2-3 hours depending on your hardware) + +==== Download an archive + +Currently, Mircea is hosting build archives for us at https://files.mircearoata.me/UE_Linux/, but this will be changed over to the GitHub CI eventually. +Click on the latest commit link, and download each of the `UnrealEngine-CSS-Editor-Linux.tar.zst.*` files one at a time. + +Once those are done downloading, create a folder called `UnrealEngineCSS` or similar, and move the archives into it. +Then run the command below to extract them: + +[source,bash] +---- +cat UnrealEngine-CSS-Editor-Linux.tar.zst.* | zstd -d | tar -xf - +---- + +=== Register the engine + +Register the engine to your system by running this command, replacing `` with the path to your engine installation: + +[source,bash] +---- +/Engine/Binaries/Linux/UnrealVersionSelector -register -unattended +---- + +Then, edit the file `/Engine/Build/InstalledBuild.txt` to remove the `-linux` suffix from the version name if it is present. + +== Project Setup + +Clone or download the starter project from https://github.com/satisfactorymodding/SatisfactoryModLoader as normal. + +=== Wwise setup + +Download the latest build of wwise-cli from https://github.com/mircearoata/wwise-cli/releases/latest. + +Run this command in your terminal to download the required version of Wwise: + +[source,bash] +---- +./wwise-cli download --sdk-version "2023.1.3.8471" --filter Packages=SDK --filter DeploymentPlatforms=Windows_vc160 --filter DeploymentPlatforms=Windows_vc170 --filter DeploymentPlatforms=Linux --filter DeploymentPlatforms= +---- + +When that's done, run this command to integrate it into the starter project, replacing `` with the path to your project: + +[source,bash] +---- +./wwise-cli integrate-ue --integration-version "2023.1.3.2970" --project "/FactoryGame.uproject" +---- + +=== IDE setup + +Now we must set up our IDE for building the starter project, and for developing with C++. +Since Visual Studio isn't available for Linux, you can instead use Rider or VS Code. + +==== Rider + +Currently, Rider doesn't show the `Mods` directory when opening the .uproject, so you must generate a Visual Studio Solution to open it. +However, you will also need a Makefile to build the project. +Run the following commands, replacing `` and `` with the respective paths. + +To generate the VS Solution: + +[source,bash] +---- +/Engine/Build/BatchFiles/Linux/Build.sh -projectfiles -project="/FactoryGame.uproject" -game -2022 +---- + +To create a Makefile: + +[source,bash] +---- +/Engine/Build/BatchFiles/Linux/Build.sh -projectfiles -project="/FactoryGame.uproject" -game -Makefile +---- + +Open the `FactoryGame.sln` file in Rider. +In the Rider settings, under `Toolset and Build`, make sure `.NET CLI executable path` is set to `/Engine/Binaries/ThirdParty/DotNet/6.0.302/linux/dotnet` + +==== VS Code + +To generate a code-workspace file, run the following command, replacing `` and `` with the respective paths. + +[source,bash] +---- +/Engine/Build/BatchFiles/Linux/Build.sh -projectfiles -project="/FactoryGame.uproject" -game -VSCode +---- + +Open the `.code-workspace` file, **not** the folder. +In the workspace settings, add `/Engine/Binaries/ThirdParty/DotNet/6.0.302/linux` to `omnisharp.dotNetCliPaths` + +=== Other + +For other IDEs (not tested by us), you can view this page for command line options to generate project files for various other IDEs: https://github.com/satisfactorymodding/UnrealEngine/blob/5.3.2-CSS/Engine/Source/Programs/UnrealBuildTool/Modes/GenerateProjectFilesMode.cs#L26-L38 + +== Compile the project + +* For Rider, open the Terminal and run `make FactoryEditor` +* For VS Code, press `Ctrl + Shift + P`, then select `Run Task`, then `FactoryEditor Linux Development Build` + +Then wait for the build to complete. + +== Open the editor + +If everything above was done correctly, you may now open the `FactoryGame.uproject` file in your Starter Project to launch the Unreal Editor. \ No newline at end of file diff --git a/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc b/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc index fc344572..56c7aeef 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc @@ -14,6 +14,8 @@ once everything is installed and built - 30+ GB is possible. Keep this in mind when deciding where put all your files - don't keep them on a drive with very little space left. +NOTE: This is for setting up the Modding Environment on Windows. If you are on Linux, please follow the guide xref:Development/BeginnersGuide/LinuxSetup.adoc[here]. + == Before you Begin Make sure you've read the starting information on the @@ -103,7 +105,7 @@ Satisfactory's dedicated servers typically run on Linux. Cross-compiling from Windows to Linux requires the compatible version of Unreal Engine specific CLang Toolchain to be installed prior to building for Linux Dedicated Servers. -The download link for these files can be found on the Unreal documentation page for +The download link for these files can be found on the Unreal documentation page for https://dev.epicgames.com/documentation/en-us/unreal-engine/linux-development-requirements-for-unreal-engine?application_version=5.3#nativetoolchain[Cross-Compiling for Linux]. Currently, Satisfactory uses Unreal Engine 5.3.2 with custom changes provided by Coffee Stain Studios. @@ -179,10 +181,21 @@ It's imperative that you download the correct engine for the version of the game or you will have to repeat a large amount of the setup process again. ==== -include::/_includes/current-branch-header.adoc[] +If you are looking to develop mods for Update 1.0, +follow the link:https://docs.ficsit.app/satisfactory-modding/v3.10.0/index.html[SML v3.10.0] documentation instead. +However, we strongly suggest developing mods for Update 1.1 instead as it will be released to the stable branch on June 10th. +==== + +// When updating the below, remember to update StaterProjectViaClone.adoc, StarterProjectViaZip.adoc, and dependencies.adoc (engine) +==== +This is the *latest stable* version of the docs. +// This is the *development* version of the docs. + +// Stable (Release) and Experimental are currently both the same version - 1.0 Release. -Download this engine version: + -https://github.com/satisfactorymodding/UnrealEngine/releases/{engine-version} +You should download from the *latest engine release*, +which an be found at the top of this page: +https://github.com/satisfactorymodding/UnrealEngine/releases ==== Download the following files from the release linked above: @@ -256,9 +269,6 @@ and in order to develop mods, you'll need to install and integrate Wwise with your mod project, even if you do not plan to modify sounds. -[id="WwiseLauncher"] -=== Download the Audiokinetic Launcher - Visit https://www.audiokinetic.com/en/download/[Wwise] and click on the `+Download Audiokinetic Launcher+` button. Clicking the button will probably redirect you to a sign in page. @@ -266,9 +276,6 @@ Create an account if you don't have one yet, or sign in, to download and run the After the installer is complete it should open the launcher for you. -[id="WwiseVersion"] -=== Install the Wwise Version - In the launcher's left sidebar, select the topmost `Wwise` section (note: not the "Wwise Audio Lab" section). Under the "INSTALL A NEW VERSION" heading, @@ -277,8 +284,6 @@ Select `2023.1` from the "Major" dropdown. Select version `2023.1.3.8471` from the "Version" dropdown. Click `Install`. -image::BeginnersGuide/Wwise/wwise_version.png[Select Wwise version screenshot, title=Installing a new Wwise version. Wwise UI may differ slightly from this screenshot.] - [WARNING] ==== Watch out - most older versions of Wwise don't have support for Unreal Engine 5, which this project needs. @@ -308,19 +313,14 @@ Once presented with options on what to install, select: *** _Windows_ **** pass:[✔] Visual Studio 2019 **** pass:[✔] Visual Studio 2022 -**** pass:[✔] Game Core -If anything else is selected by default, do not uncheck them. They are required for Visual Studio to work. - -image::BeginnersGuide/Wwise/wwise_packages.png[Select Wwise packages screenshot, title=Selecting packages and deployment platforms. Wwise UI may differ slightly from this screenshot.] +If anything is selected by default, do not uncheck them. They are required for Visual Studio to work. Click `Next` (you may need to scroll down to see the button). You don't need to add any plugins, -so press `Select None` in the top right then `Install` (or `Modify` if you already have it installed) in the bottom left to begin the installation process. +so press `Select None` in the top right then `Install` in the bottom left to begin the installation process. Accept any User Account Control or Terms and Conditions prompts that appear along the way. -image::BeginnersGuide/Wwise/wwise_no_plugins.png[Do not select any Wwise plugins screenshot, title=Deselect all plugins. Wwise UI may differ slightly from this screenshot.] - == Satisfactory Mod Manager xref:index.adoc#_satisfactory_mod_manager_aka_smm[Satisfactory Mod Manager] From 018cd9059c1f56c0b0bb00ec49c30871c3ec14f7 Mon Sep 17 00:00:00 2001 From: Jesse Hodgson Date: Fri, 14 Nov 2025 09:59:25 -0500 Subject: [PATCH 2/2] Revert unintentional changes to dependencies.adoc --- .../BeginnersGuide/dependencies.adoc | 41 ++++++++++--------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc b/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc index 56c7aeef..3326439d 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc @@ -14,7 +14,8 @@ once everything is installed and built - 30+ GB is possible. Keep this in mind when deciding where put all your files - don't keep them on a drive with very little space left. -NOTE: This is for setting up the Modding Environment on Windows. If you are on Linux, please follow the guide xref:Development/BeginnersGuide/LinuxSetup.adoc[here]. +NOTE: This is for setting up the Modding Environment on Windows. +If you are on Linux, please follow the guide xref:Development/BeginnersGuide/LinuxSetup.adoc[here]. == Before you Begin @@ -105,7 +106,7 @@ Satisfactory's dedicated servers typically run on Linux. Cross-compiling from Windows to Linux requires the compatible version of Unreal Engine specific CLang Toolchain to be installed prior to building for Linux Dedicated Servers. -The download link for these files can be found on the Unreal documentation page for +The download link for these files can be found on the Unreal documentation page for https://dev.epicgames.com/documentation/en-us/unreal-engine/linux-development-requirements-for-unreal-engine?application_version=5.3#nativetoolchain[Cross-Compiling for Linux]. Currently, Satisfactory uses Unreal Engine 5.3.2 with custom changes provided by Coffee Stain Studios. @@ -181,21 +182,10 @@ It's imperative that you download the correct engine for the version of the game or you will have to repeat a large amount of the setup process again. ==== -If you are looking to develop mods for Update 1.0, -follow the link:https://docs.ficsit.app/satisfactory-modding/v3.10.0/index.html[SML v3.10.0] documentation instead. -However, we strongly suggest developing mods for Update 1.1 instead as it will be released to the stable branch on June 10th. -==== +include::/_includes/current-branch-header.adoc[] -// When updating the below, remember to update StaterProjectViaClone.adoc, StarterProjectViaZip.adoc, and dependencies.adoc (engine) -==== -This is the *latest stable* version of the docs. -// This is the *development* version of the docs. - -// Stable (Release) and Experimental are currently both the same version - 1.0 Release. - -You should download from the *latest engine release*, -which an be found at the top of this page: -https://github.com/satisfactorymodding/UnrealEngine/releases +Download this engine version: + +https://github.com/satisfactorymodding/UnrealEngine/releases/{engine-version} ==== Download the following files from the release linked above: @@ -269,6 +259,9 @@ and in order to develop mods, you'll need to install and integrate Wwise with your mod project, even if you do not plan to modify sounds. +[id="WwiseLauncher"] +=== Download the Audiokinetic Launcher + Visit https://www.audiokinetic.com/en/download/[Wwise] and click on the `+Download Audiokinetic Launcher+` button. Clicking the button will probably redirect you to a sign in page. @@ -276,6 +269,9 @@ Create an account if you don't have one yet, or sign in, to download and run the After the installer is complete it should open the launcher for you. +[id="WwiseVersion"] +=== Install the Wwise Version + In the launcher's left sidebar, select the topmost `Wwise` section (note: not the "Wwise Audio Lab" section). Under the "INSTALL A NEW VERSION" heading, @@ -284,6 +280,8 @@ Select `2023.1` from the "Major" dropdown. Select version `2023.1.3.8471` from the "Version" dropdown. Click `Install`. +image::BeginnersGuide/Wwise/wwise_version.png[Select Wwise version screenshot, title=Installing a new Wwise version. Wwise UI may differ slightly from this screenshot.] + [WARNING] ==== Watch out - most older versions of Wwise don't have support for Unreal Engine 5, which this project needs. @@ -313,14 +311,19 @@ Once presented with options on what to install, select: *** _Windows_ **** pass:[✔] Visual Studio 2019 **** pass:[✔] Visual Studio 2022 +**** pass:[✔] Game Core -If anything is selected by default, do not uncheck them. They are required for Visual Studio to work. +If anything else is selected by default, do not uncheck them. They are required for Visual Studio to work. + +image::BeginnersGuide/Wwise/wwise_packages.png[Select Wwise packages screenshot, title=Selecting packages and deployment platforms. Wwise UI may differ slightly from this screenshot.] Click `Next` (you may need to scroll down to see the button). You don't need to add any plugins, -so press `Select None` in the top right then `Install` in the bottom left to begin the installation process. +so press `Select None` in the top right then `Install` (or `Modify` if you already have it installed) in the bottom left to begin the installation process. Accept any User Account Control or Terms and Conditions prompts that appear along the way. +image::BeginnersGuide/Wwise/wwise_no_plugins.png[Do not select any Wwise plugins screenshot, title=Deselect all plugins. Wwise UI may differ slightly from this screenshot.] + == Satisfactory Mod Manager xref:index.adoc#_satisfactory_mod_manager_aka_smm[Satisfactory Mod Manager] @@ -341,4 +344,4 @@ To install Satisfactory Mod Manager, follow the directions xref:ForUsers/Satisfa The last dependency to obtain is a copy of the modding Starter Project. Check out the xref:Development/BeginnersGuide/StarterProject/ObtainStarterProject.adoc[next section] -for directions on how to obtain it. +for directions on how to obtain it. \ No newline at end of file