A server to create "dashboards" to let other people control selected avatar parameters via a webinterface. Each avatar is set up individually and the parameters can be controlled with a button, a toggle switch and a rotrary input (emulating some of the built-in Action Menu controls).
There are three main way to install and run this server:
- Build and run it directly on your machine
- Run it in a container with docker
- Run it in a container with docker-compose
This readme documents how to do each of these options.
- Node.js v16+
- Clone the repository
cdinto it- Run
npm install --legacy-peer-depsto install the required modules for the server cd client- Run
npm installto install the required modules for the frontend npm run buildto build the frontend
cd into the cloned repository and run node ./ /path/to/config.yml [/path/to/icons].
You need to pick a location for the config file (i.e. replace /path/to/config.yml with an actual path).
If you want to just store it in the same folder as the cloned repository, you can set the path to ./config.yml, but you can also put it anywhere else on your PC.
The second parameter is optional, since the path where the uploaded icons are stored can also be set in the config file (Default: ./icons).
The first time you launch the server you are asked if you are currently running in a docker container.
Answer this question with n.
Afterwards you have to create an admin password.
If you want to change it later you can either remove the admin.password key from the config file to summon the prompt again or go to a website like bcrypt-generator.com and "encrypt" your new password there before putting it into the config file.
- Docker (on Windows you probably want to use Docker Desktop for convenience)
- Clone the repository
cdinto it- Run
docker build ./ -t vrc-param-server
To run the first time setup run
docker run -it --rm -v /path/to/your/config/directory:/data/config vrc-param-serverNote that the path to the config directory has to be absolute.
If you want to use a relative path you can write something like $(pwd)/config to place the config file in ./config.
Important note for Git Bash users on windows: Git bash fucks up your paths so you need to prepend MSYS_NO_PATHCONV=1 to the command, otherwise docker will complain about broken paths.
The setup will ask you if you run in docker; answer this with y.
Afterwards you have to create an admin password.
Once the first time setup is complete you can run the server like this:
docker run \
-d \ # run as a deamon
--restart unless-stopped \ # automatically (re)start the server when your PC restarts
-v /path/to/your/config/directory:/data/config \
-v /path/to/icons:/data/config \ # optionally set the path to where icons should be stored
-p 8080:8080 \ # set the address and port for the webinterface
-p 9001:9001/udp # set the OSC input portRunning the server with docker-compose has two main advantages compared to running it in Docker directly:
- You can easily change all the config in
docker-compose.ymldirectly and recreate everything with a single command - You can run
cloudflaredalongside it with a single command which not only removes the need for port forwarding, but also takes care of creating an encrypted tunnel directly to the server.
- Docker (on Windows you probably want to use Docker Desktop for convenience)
- Clone the repository
cdinto it- Run
docker compose build
Open docker-compose.yml and set the path of the config directory to a path of your choosing (or leave it as ./config to store it in the same folder as the cloned repository).
You can also add another entry to the volumes to set the path of where icons should be stored (e.g. - "./icons:/data/icons").
If this is not set the icons will be stored in an unnamed docker volume.
If you have a domain and a tunnel set up on cloudflare, you can log into the dashboard, go to Access -> Tunnels, click on Configure next to the tunnel you want to use, click on the Docker environment button and copy the part of the command after docker run cloudflare/cloudflared:<version>, which should look something like tunnel --no-autoupdate run --token <long string of characters>.
Paste this part into the docker-compose.yml so it replaces the word tunnel in services.cloudflared.command (keep the --url part after tunnel).
If you don't have a tunnel set up you can either consult cloudflares documentation or continue with ephemeral tunnels.
To run the first time setup run
docker compose run --rm vrc-param-serverThe setup will ask you if you run in docker; answer this with y.
Afterwards you have to create an admin password.
Once the first time setup is complete you can run the server like this:
docker compose up -dYou can now access the dashboard on localhost:45000 or via the tunnel address.
If you use an ephemeral tunnel, you can run docker logs vrc-osc-remote-server-cloudflared-1 and find the part at the top that says something like
2022-08-07T14:33:13Z INF Requesting new quick Tunnel on trycloudflare.com...
2022-08-07T14:33:16Z INF +--------------------------------------------------------------------------------------------+
2022-08-07T14:33:16Z INF | Your quick Tunnel has been created! Visit it at (it may take some time to be reachable): |
2022-08-07T14:33:16Z INF | https://<some prefix>.trycloudflare.com |
2022-08-07T14:33:16Z INF +--------------------------------------------------------------------------------------------+
Opening the URL there should bring up the server UI while also being reachable from the internet without additional setup.
You can stop the server by running
docker compose downThe actual web interface should be self-explanatory.
To get started navigate to /admin relative to the address of the server and log in with your admin password.
You can then follow the interface to create a new board, add avatars and controls to it and more.
Documentation coming soon
Some options are not currently configurable via the web interface. You can instead change them in your config.yml
| value | function |
|---|---|
| socketCounter | Prints the number of active sockets to the web interface (number of connections) |
| hideAvatarIDs | Hides most of the avatar ID that get printed to the console |
| (name)Validation | Defines if the section's validation logs should be printed |
| value | function |
|---|---|
| enabled | Is it? |
| volume | volume of sounds (0.0-1.0) |
| (name)Path | Paths to the sound files |
The boards always says 'The currently selected avatar has no controls on this board'
There is no way for the server to "ask" VRChat what the current avatar is; VRChat only sends that information upon avatar changes. If you restart the server you need to switch into an avatar you have set up before the server displays the respective board. Resetting your avatar in game will also work.
Also make sure that the server is actually receiving OSC messages from VRChat.
Is VRChat configured to send OSC packets to the right address that the server is listening on?
By default VRChat sends OSC packets to localhost:9001 and the server listens to the same address, but if you run the server on another PC or have multiple clients listening (with my UDP Multiplexer for example), these addresses can deviate from the defaults.
You can debug all incoming data by setting osc.log_all_inputs in the config file to true and then observing the logs for logged packets.
Buttons/Toggles/Rotraries don't work
Make sure that the server is sending data to the right address that VRChat is listening on.
By default VRChat listens on port 9000 on all addresses and the server sends data to localhost:9000 (i.e. host.docker.internal when running in docker), but if you run the server on a different machine or in a VM you need to set the output port and address within the config file to the correct values.