Document how to build for Dedicated Server as the target platform

[webbertakken]

Context

As mentioned here it might be simple to do.

https://github.com/game-ci/unity-actions/pull/136#issuecomment-1023277902

Suggested solution

Let's check if this works as expected and add it to the documentation

[AndrewKahr]

I don't think it will remain so simple to do. As stated in the initial post:

How can I access this new feature? Dedicated Server platform support is now available inside the Unity Editor as of Unity 2021.2.0b1. Before 2021.3 LTS, Unity will move the feature from the default Unity Editor installation and into a separate support installer via Unity Hub in a future release.

Those support packages started appearing in 2021.2.4 and up so it seems like we need to install the support package for each platform you want to target for it to be an option. The support packages also seem to only be available to windows and mac hosts but both have support packages for windows, mac, and linux.

I also saw:

var buildPlayerOptions = new BuildPlayerOptions() { subtarget = (int) StandaloneBuildSubtarget.Server, target = BuildTarget.StandaloneWindows64, options = BuildOptions.Development };

Not sure if this means the default build script needs updating.

[davidmfinol]

Before 2021.3 LTS, Unity will move the feature from the default Unity Editor installation and into a separate support installer via Unity Hub in a future release.

This reads to me as implying that 2021.3 LTS and newer will not require the support package. It sounds like we may need to do some extra work to support downloading the packages for Unity versions between 2021.2.0b1 and 2021.3 LTS, but I expect that the vast majority of users that are interested in server builds will stick to LTS versions.

var buildPlayerOptions = new BuildPlayerOptions()
{
subtarget = (int) StandaloneBuildSubtarget.Server,
target = BuildTarget.StandaloneWindows64,
options = BuildOptions.Development
};

This code is simply passing in the subtarget through code. Currently, server builds can be done by passing EnableHeadlessMode through code or by passing EnableHeadlessMode through the Unity CLI. We could update the default build script, but I think it would be better to encourage passing the subtarget through the Unity CLI if possible.

[AndrewKahr]

That's my bad, I got it backwards. We should be good then once documented.

[davidmfinol]

That's my bad, I got it backwards. We should be good then once documented.

It may be me who's reading it backwards. Either way, we'll find out once 2021.3 LTS is released.

[afroraydude]

This code is simply passing in the subtarget through code. Currently, server builds can be done by passing EnableHeadlessMode through code or by passing EnableHeadlessMode through the Unity CLI. We could update the default build script, but I think it would be better to encourage passing the subtarget through the Unity CLI if possible.

I had reported on your Discord (message link) that the flag does not work as of Unity 2021.2.27f1. I have preprocessor flags that run certain bits of code depending on if the application is running in server/headless mode (#UNITY_SERVER) that did work with the flag for 2021.2.26f1 but not 2021.27f1 or later. Thought I should put that out there. It has also been removed from the Unity documentation for 2021.2.

[davidmfinol]

@afroraydude Thanks for the confirmation on the CLI. Does it work if you set the subtarget in your buildMethod?

[afroraydude]

I'll test it out

[tliff]

I've tested it on 2021.2.12f1 by setting the subtarget in buildMethod.

Gives me

##### ExitCode
-1
##### Output
The properties of source file /opt/unity/Editor/Data/PlaybackEngines/LinuxStandaloneSupport/Variations/linux64_server_nondevelopment_mono/Data/Resources/unity default resources could not be retrieved: No such file or directory
[  2/131    0s] CopyFiles Builds/StandaloneLinux64Server/spacepirates
##### ExitCode
-1
##### Output
The properties of source file /opt/unity/Editor/Data/PlaybackEngines/LinuxStandaloneSupport/Variations/linux64_server_nondevelopment_mono/LinuxPlayer could not be retrieved: No such file or directory
[  3/131    0s] CopyFiles Builds/StandaloneLinux64Server/UnityPlayer.so
##### ExitCode
-1
##### Output
The properties of source file /opt/unity/Editor/Data/PlaybackEngines/LinuxStandaloneSupport/Variations/linux64_server_nondevelopment_mono/UnityPlayer.so could not be retrieved: No such file or directory
*** Tundra build failed (0.15 seconds), 129 items updated, 131 evaluated

which seems to imply that the support modules (windows-server/linux-server/mac-server) are required.

[paulpach]

I was got the same error as @tliff by setting the subtarget

Please see my pull request, it should add the missing modules so that the images can now build dedicated servers

[davidmfinol]

The images should be created when the next docker version is released. We also need to update unity-builder to set the subtarget, and test using the new images.

[jbarnoin]

Hey,

As per the above, it looks like dedicated server build support is supposed to be available in the latest linux docker images, however our build is failing with "Error building Player: Currently selected scripting backend (Mono) is not installed." when trying to build using unityci/editor:2021.3.4f1-base-1.0.1, only if our build script contains EditorUserBuildSettings.standaloneBuildSubtarget = StandaloneBuildSubtarget.Server;

Without this subtarget the build works fine. I've confirmed that this is the same error I get if I try building locally with this subtarget without the dedicated server module installed, and that it goes away after adding the submodule.

Is there any chance the images somehow don't yet have the dedicated server module installed? Otherwise any clue about what might be causing the error will be appreciated.

[Thendon]

@jbarnoin encountered this issue as well. After reading through the Dockerfile I realized that only docker images which include the string "linux" contain the linux-server module what kind of makes sense. The only image which contains linux is linux-il2cpp though. So I changed the gitlab-ci.yml to image: $IMAGE:$UNITY_VERSION-linux-il2cpp-$IMAGE_VERSION

Does that mean there is no image for building linux server with mono or did I overlook something?

[davidmfinol]

@Thendon Is image: $IMAGE:$UNITY_VERSION-linux-il2cpp-$IMAGE_VERSION not capable of building for Mono? My understanding was that IL2CPP images should be able to support both Mono and IL2CPP.

[Thendon]

@davidmfinol my fault you are right! It is possible to build mono with that image.

[davidmfinol]

@Thendon Out of curiosity, are you able to successfully make dedicated server builds? We'd appreciate any help with documenting the process if you are able to get it working.

[Thendon]

@davidmfinol server builds are working perfectly fine! My process summarized:

• expand the BuildCommand.cs file a bit for supporting subtargets as described above
• switch the image tag from using base to one which contains the servers platform name (in my case linux-il2cpp)

After taking another look I guess I was confused about linux-il2pp and building mono with the image since there is a windows-mono tag but no linux-mono tag in docker hub. But as statet building mono with the il2cpp image wasn't a problem.

[danielchipman]

We could update the default build script, but I think it would be better to encourage passing the subtarget through the Unity CLI if possible.

Had a discussion with a dev on the dedicated server team about this and they confirmed that the CLI option is only reliable on 2023 versions of Unity going forward:

Cristian [Unity] — Today at 1:17 PM what the -standaloneBuildSubtarget Server argument does is to set the active target to Dedicated Server. In the most recent version of Unity, if you leave the BuildPlayerOptions.subtarget value unassigned, it should preserve the active one, I'm not entirely sure it is the same case for 2021.3. But in any case, to make sure, you should be able to assign it to the active one

Cristian [Unity] — Today at 1:24 PM just had a quick look and I can confirm that in 21.x and 22.x you have to explicitly assign the BuildPlayerOptions.subtarget value if you want to build the Dedicated Server

@davidmfinol given this I think it would be valuable to update the default build method in the unity-builder action to support configuring the subtarget. I was able to get server builds working by providing my own custom build method, but this is clunkier for users to setup and more fragile since I will have to manually keep my custom build method updated in parity with any other changes that may happen to the unity-builder's build method.

Everything else worked great though and was simple to setup.

[davidmfinol]

would be valuable to update the default build method in the unity-builder action to support configuring the subtarget

Agreed with this, as it's something I've been wanting to do for a while. Since I haven't been able to make time to do it myself, it would be great if someone in the community could raise a PR to unity-builder with this change.

[danielchipman]

@davidmfinol I can possibly take a swing at this depending on desired approach.

From what I can tell, the smallest and lowest risk modification to accomplish this would simply be to manually provide support for the -standaloneBuildSubtarget flag as a custom build parameter, then pass this into the build options in Builder.cs:

      // Determine subtarget
      StandaloneBuildSubtarget buildSubtarget;
      if (!options.TryGetValue("standaloneBuildSubtarget", out var subtargetValue) || !Enum.TryParse(subtargetValue, out buildSubtarget)) {
        buildSubtarget = StandaloneBuildSubtarget.NoSubtarget;
      }

      // Define BuildPlayer Options
      var buildPlayerOptions = new BuildPlayerOptions {
        scenes = scenes,
        locationPathName = options["customBuildPath"],
        target = (BuildTarget) Enum.Parse(typeof(BuildTarget), options["buildTarget"]),
        options = buildOptions,
        subtarget = (int) buildSubtarget
      };

A few notes:

• I noticed the default-build-script project is checked in at 2019.2.11f1- I assume there is a desire to keep this code compatible with editor versions older than 2021.2.x, in which case the additions above would need to be wrapped in #if UNITY_2021_2_OR_NEWER.
• A drawback of this approach would be that this effectively overloads Unity's parameter to behave differently in 2021.x and 2022.x projects without this method, which could possibly lead to some confusion. I don't personally think this is a deal breaker (arguably Unity already introduced this confusion by breaking their own feature as documented), but I'd understand if you feel differently.
• A more comprehensive solution would be to add an optional parameter to the unity-builder action for the subtarget for a more formal integration, but that can be done as a separate change.

If you're happy with the above approach and are fine with introducing version based conditional compilation, please let me know and I can start setting up a PR.

[davidmfinol]

Yes, we do want to support both older and newer versions of Unity, so we already do version-based conditional compilation. What you suggested sounds great to me.

One thing I will note is that we are currently working on a large refactoring of unity-builder for an upcoming v3. I believe it should be simple to also update our game-ci/cli repo with your change, and I can make sure that that gets done as part of merging your PR.

[danielchipman]

PR for standaloneBuildSubtarget flag: https://github.com/game-ci/unity-builder/pull/532 Associated docs update: https://github.com/game-ci/documentation/pull/389

Tested the build method against 2019.2 and 2021.3 for client and server builds. Please let me know if there are any issues or steps/tests I missed.

This is definitely a bare minimum fix, hopefully someone has time to make server builds more of a first class citizen.

[davidmfinol]

Thanks for your contribution @danielchipman !

I'm closing this issue, and additional improvements or iterations can be followed up in a new issue.