Running VRCSDK on Linux with Unity 2019.4.31f1

Theres a few quirks with doing VRC dev on Linux, so I thought I'd share a quick rundown on how to get everything to work smoothly.

Install Unityhub
- on Arch we can use yay -S unityhub
- on other distros you can use the Flatpak (I personally avoid it) flatpak install flathub com.unity.UnityHub
- or the more recommended method of manually adding repos and installing
Install 2019.4.31f1 by clicking the 'UnityHub' link on this page

Be sure to add Windows build support (mono) when installing!

Sometimes the hub has issues connecting to your browser for signing in / editor install. If this happens it can usually be solved by typing unityhub <link> in your browser when it sits at the blank page. (See comment here)

Make sure you have these packages installed, they might be named differently for your distro, and some of them you may not need at all. Without the gconf package, your unity editor may seem to not open at all until you try to open in with a terminal and see the error output mentioning the missing package.

mono

dotnet-runtime-6.0

dotnet-sdk-6.0

these are needed for 2019 or higher

gconf

icu70

Next we need to make sure that everything is working correctly. Open Unity with a new 3D project and test a few things, especially in the 3d view. You also may want to be sure your text editor is correctly set up, or check if there is a package for it, such as adding the vscode package in the package manager for vscodium.
Now we need to download the Creator Companion. Pretty much everything we do related to VRC can be taken from macOS support pages. However please note that running the SDK on Linux / UNIX is unsupported at this time. To install on Linux besure you have the dotnet-sdk-6.0 package and run:

dotnet tool install --global vrchat.vpm.cli

You can update the tool using:

dotnet tool update --global vrchat.vpm.cli

If this doesn't work, or the options below, you may not have dotnet tools in your environment variables. You can optionally temporarily add it with env PATH="$PATH:~/.dotnet/tools", and check it with echo $PATH

First run vpm to initialize everything. This should dump the settings.json file we need to edit.
Next edit the settings.json file with

nano ~/.local/share/VRChatCreatorCompanion-Beta

!Please add location to docs!

Add the following paths:

"pathToUnityExe": "~/Unity/Hub/Editor/2019.4.31f1/Editor/Unity",

"pathToUnityHub": "/opt/unityhub/unityhub-bin",

Exit and save with ctrl+x and check the VPM can see your editor location

vpm check hub

[17:30:48 ERR] Can only get Hub version on Windows and Mac so far...
[17:30:48 INF] Found Unity Hub version  at /opt/unityhub/unityhub-bin

vpm check unity

[17:31:39 INF] VPM Doesn't know how to look at Linux executables for version yet, so just returning true for PathIsValidUnityVersion(~/Unity/Hub/Editor/2019.4.31f1/Editor/Unity)
[17:31:39 INF] Unity is installed.

You can ignore the extra messages, this is just due to our platform.

Now that our vpm is set to find our locations we can install templates with

vpm install templates

Which will install relevant templates such as 'Avatars' and 'Worlds' packages.

You can find more VPM usage here

Creating an SDK3.0 Project

This process is really simple, and similar to that of on Windows, the only difference is that we use the CLI to initialize a new project

To create a new project use

vpm new <project name> <template> [path]

Example for avatars:

vpm new Test Avatar /run/media/user/drive/Test/

You can list all available templates with

vpm list templates

We can then add this project to our UnityHub and open it from there. This should automagically initialize a Unity project with the correct files in Packages/vpm-manifest.json and Packages/packages-lock.json and import them on first open.

Congrats! You're ready to start working!

Adding packages

You can add VRCC packages to your project with

vpm add package <package> [-p project]

Such as:

vpm add package vrchat.blackstartx.gesture-manager -p /run/media/user/disk/project

To add gesture manager. Alternatively, replace with an absolute path to a local package.

Quirks, Issues, and Tips!

This is the fun part about Linux :3

There are a few quirks when working with VRCSDK projects on Linux, mostly graphics stuff as most packages should be cross-platform, and if they are not the original developer has not written their package correctly for dotnet, as it is meant to be cross-platform. All of my tools worked out of the box except for one. I will add stuff as I find out more!

Unity on Linux / macOS uses OpenGL as DirectX isn't available (although some implementation of DXVK would be nice, if it's possible). However this should be okay as most shaders work with both (I actually do not know the specifics on this yet, I am still learning it myself ^^;). This can sometimes cause some hiccups with certain, more overcomplicated shaders.

Poiyomi:

Poiyomi hates running under openGL, I would avoid using it if you can, however if you're a creator like me and have to use some of it's features, there's a few workarounds you can use. Please note that none of this is supported by Poiyomi and it's creators we are running on Linux under OpenGL, which is not the intended case at all

Occasionally, when you have a complex material set, or multiple materials on an avatar you may get a failed compilation with an error like:

Shader '.poiyomi/Poiyomi 7.3/★ Poiyomi Pro ★' uses 37 texture parameters, more than the 32 supported by the current graphics device

This is due to a limitation within OpenGL, to get around this, Lock-in materials you are currently not using, and reduce your overall number of Poiyomi shaders in your scene. Interestingly, Locking-in the material will have it compile correctly so you can view the shader. I usually edit the shader on it's own, then lock-in before editing other things. This speeds up upload time anyways. Alternatively, if you are tweaking something, you can animate the parameters, lock-in the shader, edit the material, and then unlock and relock removing the animated parameter.
Poiyomi Pro 8.2.x reintroduced Raliv's DPS system. There is a bug in the code that doesn't seem to present itself in windows, that will prevent the shader from compiling. I have not reported this bug as I only see the issue on Linux, however it is due to Undeclared Identifier: Oriface. Avoid this version, or optionally comment out / remove DPS from the Poiyomi Pro.shader. This issue is not present in 7.3.x, only 8.2.x. Alternatively, you can add the Identifier yourself, but I am not a shader dev.

RATs (Raz's Animator Tweaks n Stuff):

~~- There is an issue with a hardcoded path replacement causing UNIX systems to not find the correct path. You can fix this by using the version I forked here to make it cross-compatible.~~

This PR has been merged! You can now clone the original repo! Thanks Raz!

You still should use the original harmony unitypackage for .net4.8, I have not tested RAZ's repo yet.

Cross-Platform Dev Stuff

I run into constant issues trying to run projects on both Windows and Linux using the same file. I recommend against this, Windows will corrupt folders it does not have explicit permissions for, and will corrupt them when you try to fix this. I recommend using a local version control server like GitLab and having seperate locations with seperate Library folders. If you do decide to swap back and forth, make sure you trash your library folder as Windows will corrupt it when it tries to read it. On Linux it just seems to run a re-import (wasting time). Gotta love NTFS eh?

VRChat Under Wine

VRChat runs perfectly on desktop under Wine / Proton for checking development. Thanks Steamdeck! Check out the ProtonDB page for tweaks related to your distro. I wouldn't bother with SteamVR on Linux unless you like tinkering and breakages. This is not a VRC issue, but a SteamVR one.

VRChat in a VM

VRC also works okay in a Windows VM under QEMU, however this is much more advanced and requires some pretty decent knowlege on QEMU VMs. I used VRC in a VM for months very smoothly until the infamous EAC update, which caused some slowdowns for my personal setup. However a decent amount of these issues can be worked around by following the docs here. Which should get it running pretty decent for most users, especially those with AMD card passthrough. However I'd recommend just biting the bullet and restarting into Windows instead of wasting your time with this, unless you have the headroom, sadly.

Other stuff!

Both Blender and Substance Painter work natively on Linux! (Substance suite only on Steam at the moment after Adobe buyout) This makes my workflow work perfectly.

Marvelous Designer runs darn-near-perfect under Wine. I personally use wine-staging and create a Windows 10 prefix with vcrun2019, DXVK, and dotnet48 installed. You can also add corefonts to render Windows fonts, or swap it to Noto in preferences for a cleaner UI. I have absolutely no issues running this under Wine, and in-fact think it runs better than Windows with some tweaking.

There are also repos on GitHub with instructions on how to use Adobe Photoshop and other Adobe products if you're like me and stuck using them for your whole life. Alternatively just do what I haven't and bite the bullet to use GIMP.

SpookySkeletons/VRCDevLinux.md