unity-sim

A Unity based simulator for Banksia.

Current unity version: Unity 6.1 (6000.1.14f1)

Development

You'll need to get Unity through Unity Hub.

1. Installing unityhub on NixOS

Add pkgs.unityhub and an appropriate IDE to your configuration.nix:

  # /etc/nixos/configuration.nix
  # ...
  home-manager.users.nova = {
    home.packages = with pkgs; [
      # ...

      # Add here:
      unityhub
      jetbrains.rider  # or another appropriate IDE
    ];
    
    #...
  };
  # ...
};
# Or you could also add it to environment.systemPackages, but it is better to do it with home-manager

I recommend using Jetbrains Rider for Unity development.

Important

Make sure you update your nix channels (there was an important fix 5 hours before I wrote this).

sudo nix-channel --update

Rebuild your system (this might take a while, I'm sorry).

sudo nixos-rebuild switch

Make sure to reboot your system afterwards (or Unity Hub won't open correctly when signing in).

Note

Unity Hub won't work through a nix-shell, as it needs to use xdg-open from your web browser to be able to sign in.

2. Downloading Unity

Run unityhub, and press the appropriate button to sign in or create an account using a web browser.

Once in, you may be prompted to download the latest version of unity. Dismiss this, and manually select a version of Unity to download that matches the current project (See the top of the README for the current version).

On the left side-bar, select Installs. Then, in the top left, select Install Editor. Find the closest version >= to the version listed in the README, and press Install. Tick the options for Documentation and Linux Build SUpport (IL2CPP) (this will take a while).

Once complete, add this directory as a project. It won't be able to open. This is normal.

3. Open the project

To open the project, in a terminal, navigate to this directory, then run:

nix-shell # This will take a while
unity

And the editor should pop up.

If the version of unity changes at all, the unity alias will break, and we will need to update shell.nix to use the correct unity version in the alias.

4. Setting up your IDE

Create a rider-helper.sh file:

#!/bin/sh
exec rider "$@"

Then make it executable:

chmod 777 ./rider-helper.sh

In Unity, under Edit > Preferences > External Tools, choose the External Script Editor, browse to your rider-helper.sh, and select it. Now you should be able to run rider through Unity.

Warning

Open Rider through Unity exactly ONCE to get the project loaded, and then never again. Always load it from the command line in the future.

Once you have opened Rider once through Unity (e.g. double-clicking a C# file), close it.

Then, open Rider through the CLI (from the same terminal that you opened unity from):

rider
# OR ridermux

Go to the top right corner of the screen and select the cog to open settings.

Navigate to Build, Execution, Deployment > Toolset and Build > Toolset, then set the paths to the following:

Mono executable path: /usr/bin/mono
.NET CLI executable path: /usr/bin/dotnet
MSBuild version: /usr/lib/mono/msbuild/Current/bin/MSBuild.dll

This relies on running Rider through the FHS environment given to you by nix-shell, so you need to run it through the terminal that runs nix-shell, and not through Unity for this to work.

How I created the project:

I make a shell.nix with a fhs to allow us to run dynamically linked executables of the unity editor.

# at the root of the repository
nix-shell

tmux new -s hub

# in [hub]
unityhub
# ctrl + b, d

In a new terminal window:

tail -f ~/.config/unityhub/logs/info-log.json

Then create the project in unity hub. You should see a message in the logs like:

{"timestamp":"2025-08-05T08:44:47.682Z","level":"info","moduleName":"LaunchProcess","pid":16374,"message":"Spawning editor instance with command:  /home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Unity , and arguments:  [ '-createproject', '/home/nova/code/unity-sim/Simulator/JoeM', '-cloneFromTemplate', '/home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Data/Resources/PackageManager/ProjectTemplates/com.unity.template.3d-cross-platform-17.0.14.tgz', '-cloudOrganization', '1324567', '-cloudProject', 'AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA', '-cloudEnvironment', 'production', '-useHub', '-hubIPC', '-hubSessionId', 'AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA', '-accessToken', 'AAAAAAAAAAAAAAAAAAAA_AAAAAAAAAAAAAA_AAAAAAAAAAAA' ]"}

Copy the command it tried to run:

/home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Unity , and arguments:  [ '-createproject', '/home/nova/code/unity-sim/Simulator/JoeM', '-cloneFromTemplate', '/home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Data/Resources/PackageManager/ProjectTemplates/com.unity.template.3d-cross-platform-17.0.14.tgz', '-cloudOrganization', '1324567', '-cloudProject', 'AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA', '-cloudEnvironment', 'production', '-useHub', '-hubIPC', '-hubSessionId', 'AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA', '-accessToken', 'AAAAAAAAAAAAAAAAAAAA_AAAAAAAAAAAAAA_AAAAAAAAAAAA'

Then in the original shell, make a new tmux session, and run the command unityhub tried, formatting the arguments properly:

# in original shell
tmux new -s editor

# in [editor]
/home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Unity -createproject /home/nova/code/unity-sim/Simulator/JoeM -cloneFromTemplate /home/nova/Unity/Hub/Editor/6000.1.14f1/Editor/Data/Resources/PackageManager/ProjectTemplates/com.unity.template.3d-cross-platform-17.0.14.tgz -cloudOrganization 1324567 -cloudProject AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA -cloudEnvironment production -useHub -hubIPC -hubSessionId AAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA -accessToken AAAAAAAAAAAAAAAAAAAA_AAAAAAAAAAAAAA_AAAAAAAAAAAA

Then, the editor loaded: