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
- on Arch we can use
-
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
gconfpackage, 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
vscodepackage in the package manager forvscodium. -
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.0package 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 withecho $PATH
- First run
vpmto initialize everything. This should dump thesettings.jsonfile we need to edit. - Next edit the
settings.jsonfile 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+xand 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
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.
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.
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 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.xreintroduced 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 toUndeclared Identifier: Oriface. Avoid this version, or optionally comment out / remove DPS from thePoiyomi 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.
- 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.
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 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.
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.
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.