Space Station Multiverse

How to switch to MV Engine

In this page, I’ll document how you could switch your fork to using MV Engine. (General information about MV Engine).

Determining Engine Version

First, determine which engine version you will need. MV does not support every upstream engine branch, but instead does occasional releases.

  • Consult the table on the MV Engine page to see the currently supported mainline version and backport branches. If you’re using EE or one of the other supported versions, there should be a supported matching engine branch available already.
  • If not, if you’re planning to merge forward anyway, one of those versions might be good targets for merging up to.
  • It also may be possible to request a new backport branch or an update to mainline. In general, I’m looking at roughly quarterly releases.

Now that you’ve identified an MV engine version and it’s associated tag & git hash, you can swap WizDen Robust for MV Engine.

Quick Starts

You may be able to perform both the below steps (Change RT Submodule + Content-Side changes) by merging changes from one of the below repos. If your content forks at a point that takes place after, it may save you the below manual steps.

  • Vanilla on or later than Jun 16, 2024
  • EE on or later than Aug 17, 2024

You may still with to unmerge some of the specific changes in these branches (ex: vscode solution file fix).

The below instructions provide manual steps on how to cherry pick and update your modules, which takes longer but will give you a better understanding of the upgrade process.

Change RT Submodule

(In the following example, I will demonstrate with EE codebase, but this should work with any SS14 codebase.)

From your root content folder, make sure your git doesn’t have any pending changes and you’re on the branch you expect:

ss14@lab:~/Einstein-Engines$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Check your current engine version as follows:

ss14@lab:~/Einstein-Engines$ git submodule status
eb638099999dce3a43d90772ca976ae010d649c0 RobustToolbox (v0.96.6.0-1224-geb6380999)

Now, change the submodule to MV Engine by editing .gitmodules as follows:

[submodule "RobustToolbox"]
	path = RobustToolbox
	url = https://github.com/Space-Station-Multiverse/RobustToolbox.git
	branch = April2024

Note we have changed the URL to be for SSMV instead of WizDen. Don’t forget to change your branch as needed (to ‘master’ or a backport branch in the table above)

Now inform git of the new submodule provider by:

ss14@lab:~/Einstein-Engines$ git submodule sync    
Synchronizing submodule url for 'RobustToolbox'
ss14@lab:~/Einstein-Engines$ git submodule update --init --recursive --remote
remote: Enumerating objects: 296, done.
remote: Counting objects: 100% (256/256), done.
remote: Compressing objects: 100% (95/95), done.
remote: Total 296 (delta 175), reused 235 (delta 161), pack-reused 40 (from 1)
Receiving objects: 100% (296/296), 87.76 KiB | 14.63 MiB/s, done.
Resolving deltas: 100% (186/186), completed with 35 local objects.
From https://github.com/Space-Station-Multiverse/RobustToolbox
* [new branch]          April2024  -> origin/April2024
+ 53516d638...f39a775ed master     -> origin/master  (forced update)
* [new branch]          mvAuth     -> origin/mvAuth
* [new tag]             mv-1.0.1   -> mv-1.0.1
* [new tag]             mv-0.0.3   -> mv-0.0.3
* [new tag]             mv-0.0.4   -> mv-0.0.4
* [new tag]             mv-0.0.5   -> mv-0.0.5
* [new tag]             mv-0.0.6   -> mv-0.0.6
* [new tag]             mv-1.0.0   -> mv-1.0.0
* [new tag]             mv-April2024-1.0.1 -> mv-April2024-1.0.1
Submodule path 'RobustToolbox': checked out 'e52cc5065f2d7fd18635b2bd8f2f63fde4e56c1f'
Submodule path 'RobustToolbox/Lidgren.Network/Lidgren.Network': checked out '1d85b82e058101b7ebd60cc8883af5359e4c263a'
Submodule path 'RobustToolbox/NetSerializer': checked out '0b0b5c782a2dc017bb1e8b14ae9cec47bcb4d975'
Submodule path 'RobustToolbox/Robust.LoaderApi': checked out '86a02eef163156fe899eb498acd488e8d7063a0e'

You may notice the RT engine submodules are now in a modified state:

ss14@lab:~/Einstein-Engines$ cd RobustToolbox/
ss14@lab:~/Einstein-Engines/RobustToolbox$ git status
HEAD detached at e52cc5065
Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git restore <file>..." to discard changes in working directory)
       modified:   Lidgren.Network/Lidgren.Network (new commits)
       modified:   NetSerializer (new commits)
       modified:   Robust.LoaderApi (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

This will get fixed up later in the process, but is expected for now.

From inside RobustToolbox folder we check out our desired engine tag. Change the version of RT to an MV provided one: (Note – 1.0.1 is already out of date, see the main MV engine page to pull a supported version number instead)

ss14@lab:~/Einstein-Engines/RobustToolbox$ git checkout mv-April2024-1.0.1  
M       Lidgren.Network/Lidgren.Network
M       NetSerializer
M       Robust.LoaderApi
Previous HEAD position was e52cc5065 Update version script to support backport branches
HEAD is now at 4f1c06b9c Version: 1.0.1

(Submodules are still in a modified state — not to worry this will be resolved soon)

ss14@lab:~/Einstein-Engines/RobustToolbox$ git status
HEAD detached at mv-April2024-1.0.1
Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git restore <file>..." to discard changes in working directory)
       modified:   Lidgren.Network/Lidgren.Network (new commits)
       modified:   NetSerializer (new commits)
       modified:   Robust.LoaderApi (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

The status for the root folder now looks as expected:

s14@lab:~/Einstein-Engines$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git restore <file>..." to discard changes in working directory)
 (commit or discard the untracked or modified content in submodules)
       modified:   .gitmodules
       modified:   RobustToolbox (new commits, modified content)

no changes added to commit (use "git add" and/or "git commit -a")

We can verify RT is the expected version via:

ss14@lab:~/Einstein-Engines$ git diff RobustToolbox
diff --git a/RobustToolbox b/RobustToolbox
--- a/RobustToolbox
+++ b/RobustToolbox
@@ -1 +1 @@
-Subproject commit 4f1c06b9c809bfffddbfd859ce38f65ad1a2f5db
+Subproject commit 4f1c06b9c809bfffddbfd859ce38f65ad1a2f5db-dirty

And indeed, checking the github page shows that hash is the expected version tag. I’ll go ahead and stage both files needed to git now and commit:

ss14@lab:~/Einstein-Engines$ git add RobustToolbox  
ss14@lab:~/Einstein-Engines$ git add .gitmodules
ss14@lab:~/Einstein-Engines$ git commit
[master c8c9581ecf] Use MV Engine
2 files changed, 3 insertions(+), 3 deletions(-)

Now, let’s update RT’s submodules to clear out the modified subsubmodules:

ss14@lab:~/Einstein-Engines$ git submodule update --init --recursive
Submodule path 'RobustToolbox/Lidgren.Network/Lidgren.Network': checked out '61a56c60bd99d000c25bd3f105b6de090076c98f'
Submodule path 'RobustToolbox/NetSerializer': checked out '7f51deaecab8498a8953f7fb3e551b9892c5dff4'
Submodule path 'RobustToolbox/Robust.LoaderApi': checked out '99a2f4b88077629f69fb66f74f50e88dbe43e0e8'

And we can see the status is as expected:

ss14@lab:~/Einstein-Engines$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
 (use "git push" to publish your local commits)

nothing to commit, working tree clean
ss14@lab:~/Einstein-Engines$ cd RobustToolbox/
ss14@lab:~/Einstein-Engines/RobustToolbox$ git status
HEAD detached at mv-April2024-1.0.1
nothing to commit, working tree clean

Content-Side Changes

The next big step is pulling in the content-side MV changes to make MV Auth work.

In future, this might be done in an easier method, but for now I’m going to do this by pulling the relevant changes from the SSMV Content repo’s MV Auth branch and putting them onto my fork.

I start by running dotnet restore to pull latest versions of everything.

ss14@lab:~/Einstein-Engines$ dotnet restore
/home/ss14/Einstein-Engines/BuildChecker/BuildChecker.csproj : warning NU1503: Skipping restore for project '/home/ss1
4/Einstein-Engines/BuildChecker/BuildChecker.csproj'. The project file may be invalid or missing targets required for
restore. [/home/ss14/Einstein-Engines/SpaceStation14.sln]
 Determining projects to restore...
 Restored /home/ss14/Einstein-Engines/RobustToolbox/Avalonia.Base/Avalonia.Base.csproj (in 176 ms).
 Restored /home/ss14/Einstein-Engines/Content.Shared.Database/Content.Shared.Database.csproj (in 176 ms).
 Restored /home/ss14/Einstein-Engines/RobustToolbox/OpenToolkit.GraphicsLibraryFramework/OpenToolkit.GraphicsLibraryF
ramework.csproj (in 176 ms).
 Restored /home/ss14/Einstein-Engines/RobustToolbox/Lidgren.Network/Lidgren.Network.csproj (in 0.7 ms).
..... (many more restore lines)
 5 of 37 projects are up-to-date for restore.

The 5/37 restore line perturbs me, so I run it again:

ss14@lab:~/Einstein-Engines$ dotnet restore
/home/ss14/Einstein-Engines/BuildChecker/BuildChecker.csproj : warning NU1503: Skipping restore for project '/home/ss1
4/Einstein-Engines/BuildChecker/BuildChecker.csproj'. The project file may be invalid or missing targets required for
restore. [/home/ss14/Einstein-Engines/SpaceStation14.sln]
 Determining projects to restore...
 All projects are up-to-date for restore.

Now to pull content, I will temporarily add SSMV Content repo as a remote and fetch its contents:

ss14@lab:~/Einstein-Engines$ git remote add ssmvContent https://github.com/Space-Station-Multiverse/space-station-14
ss14@lab:~/Einstein-Engines$ git fetch ssmvContent
remote: Enumerating objects: 60834, done.
remote: Counting objects: 100% (14933/14933), done.
remote: Total 60834 (delta 14933), reused 14933 (delta 14933), pack-reused 45901 (from 1)
Receiving objects: 100% (60834/60834), 112.23 MiB | 62.05 MiB/s, done.
Resolving deltas: 100% (43951/43951), completed with 4682 local objects.
From https://github.com/Space-Station-Multiverse/space-station-14
* [new branch]            master     -> ssmvContent/master
* [new branch]            mvAuth     -> ssmvContent/mvAuth
Fetching submodule RobustToolbox
fatal: remote error: upload-pack: not our ref 6bdd9cab4b1eb6ddff5a4f7cc4373aefe3e932dc
Errors during submodule fetch:
       RobustToolbox

StackOverflow says the error is because I didn’t push my changes to the remote repo. But running fetch a few more times doesn’t throw errors, so I’m going to continue onward for now.

ss14@lab:~/Einstein-Engines$ git fetch ssmvContent
ss14@lab:~/Einstein-Engines$ git fetch ssmvContent
ss14@lab:~/Einstein-Engines$

Now I’m going to merge in changes from SSMV Content’s MV Auth branch. In EE’s case, this branch exists in the future, and so directly merging it would pull in a bunch of not-related upstream content. So I will selectively merge just the changes required by looking at the MV Auth branch history, resolving conflicts as I go.

ss14@lab:~/Einstein-Engines$ git cherry-pick 99fda716e70d3ff318ea0815e02f99fb1b5ebf96
[master 81cc978e07] Early WIP on auth (content-side)
Date: Sat Aug 10 23:14:25 2024 -0700
1 file changed, 24 insertions(+), 20 deletions(-)
ss14@lab:~/Einstein-Engines$ git cherry-pick afd96d22ff265655366ab960d85cd1bc5400d340
Auto-merging Content.Server.Database/Migrations/Postgres/PostgresServerDbContextModelSnapshot.cs
Auto-merging Content.Server.Database/Migrations/Sqlite/SqliteServerDbContextModelSnapshot.cs
Auto-merging Content.Server.Database/Model.cs
Auto-merging Content.Server/Connection/ConnectionManager.cs
Auto-merging Content.Server/Database/ServerDbBase.cs
Auto-merging Content.Server/Database/ServerDbManager.cs
Auto-merging Content.Server/Database/ServerDbPostgres.cs
Auto-merging Content.Server/Database/ServerDbSqlite.cs
Auto-merging Content.Server/IoC/ServerContentIoC.cs
CONFLICT (content): Merge conflict in Content.Server/IoC/ServerContentIoC.cs
error: could not apply afd96d22ff… First working implementation; store/retrieve/check public keys in database
hint: After resolving the conflicts, mark them with
hint: “git add/rm <pathspec>”, then run
hint: “git cherry-pick –continue”.
hint: You can instead skip this commit with “git cherry-pick –skip”.
hint: To abort and get back to the state before “git cherry-pick”,
hint: run “git cherry-pick –abort”.
(resolved in vs code)
…

(I apologize for not squashing these into a single change)

After merging all the changes, I can check my git log and double check none were missed.

Now we build and cross our fingers.

The only issue in this particular example was EE not having AdminFlags.Moderator, so I changed it to AdminFlags.Server for now.

Testing

Running this, we wouldn’t notice any change yet as we’re connected via localhost.

So we set via the console a few settings to help force key auth to be testable locally:

sudo cvar auth.allowlocal false
sudo cvar auth.mode 1
disconnect

Reconnecting gives us an auth required error, so now we run ssmv launcher:

We can add an entry for localhost, and see the following:

The caution is because it’s not reporting an engine version, which is expected for a local dev build. We can work around this by setting via terminal:

cvar build.engine_version "mv-April2024-1.0.1"

Upon refreshing, the caution symbol is gone and connect works.

Via in-game console, we can check our account has a key set:

Everything seems to be working 🎉

Using Engine with CDN

I have not yet migrated to the newer CDN distribution method so I can’t speak to that yet, however, this applies to the older CDN method (still in use by EE?)

Your server will need to convey to the launcher to use the desired version of multiverse engine. In the above example we set the cvar to test temporarily, but in production use you would likely be using the gen_build_info.py script.

That script already mostly correctly pulls the mv-x.x.x version tag (or backport tag, etc) and places it in the build.info, but it does need to be updated to not cut off the mv- part at the beginning. You probably already pulled that as one of the merges during the merge step above — so you probably shouldn’t need to do any extra work here.

Next Steps

Head back to MV Engine main page for configuration and command guidance.