VR169 Companion

This chapter covers installing, configuring and using "VR169 Companion", the companion application for the asset.

Overview

"VR169 Companion" is a Windows-only companion application that lets the asset work together with VRChat system features an avatar gimmick cannot control on its own. It is designed so that it needs no installer writing to your system, no registry changes and no administrator rights. It communicates locally with VRChat over the OSC protocol and synchronises the official camera parameters and the control signals specific to the asset.

Main features

Linked start and stop of VR169 and the standard VRChat camera. It detects the standard VRChat camera opening and deploys the asset on the avatar automatically, and detects it closing and shuts the asset down automatically. Note: you cannot open or close the standard VRChat camera directly from the asset side. Camera shutter control from VR169. It detects a hand gesture on the avatar, or an Expression menu operation, and makes the standard VRChat camera take a photograph. Coexistence with other OSC applications. Because the send address and other values can be customised, it can run alongside other external OSC applications without interfering with them.

Behaviour and limitations

This application communicates with VRChat over your local network. Depending on your PC environment, the linking features may not work correctly.

The camera closes automatically during initialisation. When this application recognises VR169 on the avatar, it closes the standard VRChat camera if it is open.
Guard time just after startup. For about two seconds after the asset starts, shutter input is not accepted, to prevent misfires and duplicate sends.
Limit on consecutive shots. Because of how VRChat works, consecutive shooting instructions need an interval of about one second.
Effects of the network environment. If the network load on your PC is high or packets are lost, the linked data can very occasionally be delayed or briefly interrupted.
Log history limit. The log area in the application keeps at most 1000 entries.
Timer shooting. Very occasionally the timer is cancelled. This is current behaviour.

Installing

Where to put it

Place the VR169_Companion_x.x.x folder bundled with the asset package, as a whole folder, in any local folder you like. VR169 Companion.exe inside that folder is the application itself. Note: if you place it in a folder protected by administrator rights (for example C:\Program Files), writing the settings file may fail. We recommend a directory with open permissions, such as somewhere under your user folder.

Clearing security protection

Executable programs downloaded from the internet may be blocked from starting, quarantined or deleted by Windows protection features or by security software. Carry out the steps below as needed.

Unblocking in Properties

Right-click the application file (VR169 Companion.exe) and choose "Properties".
Look at the Security item at the bottom of the "General" tab.
Tick "Allow" (or "Unblock").
Click "Apply", then "OK" to close the window.

If a Windows SmartScreen warning appears. If the blue "Windows protected your PC" warning screen appears, do the following.

Click the "More info" text link in the warning.
Click the "Run anyway" button that then appears. This clears the start-up protection. You only need to do this the first time.

If security software deletes it automatically. If the program is quarantined or deleted automatically by mistake, restore the file as follows.

With Windows Defender (the standard security feature): 1. Open "Windows Security" from the security icon in the taskbar. 2. Choose "Virus and threat protection" then "Protection history". 3. Select this application among the quarantined items and restore it. 4. To prevent further false detections, add the folder you placed the files in to the scan exclusions.
With third-party security software: remove the file from quarantine in the detection history of that software and register it as a trusted application.

Settings and operation

The settings for this application are created and saved automatically as a settings file named config.json, inside the "AppData folder" that Windows provides for each user. This keeps your settings without making unnecessary changes to important system information on your PC and without causing security problems.

Settings

If you use several OSC applications, we recommend an OSC router. These values can only be changed while the application is stopped.

Receive settings

Receive port: the port number on which data sent from VRChat and from the asset is received (default: 9001).

Send settings

Destination IP / destination port: where packets are sent to VRChat (default: 127.0.0.1 / 9000). You do not normally need to change these.

Forwarding settings

This feature relays data in the background through this application, so that it can run alongside another OSC application that uses port "9001" on the same PC. Note: to keep the relayed data consistent, use a forwarding IP that is either the loopback address on the same PC (127.0.0.1) or on a closed, sufficiently trusted connection such as a home network.

How to set up forwarding

Change the receive port of the external software you want to run at the same time from the standard 9001 to another relay number (for example 9002).
Tick "Forward to another application" in this application.
Enter the relay port number you set in the other software (for example 9002) in the "Forwarding port" of this application.
Click "Save settings" to record the settings, and make sure the application is in the started state.
Once you have confirmed that this application is running, start the other external software.

Running it

In principle, starting it is all the preparation you need; no special operation is required.

Starting

Run VR169 Companion.exe.
Start VRChat and load the avatar that VR169 is set up on.
The connection is checked in the background. Once the log records that the connection is complete, the system connection is done. Checking the connection takes about two seconds.

Stopping

To end monitoring completely and close the application, click the "×" button at the top right of the window. It cleans up its internal communication and threads and then exits.
To leave the application running but pause monitoring temporarily, click the "Stop" button on screen.

Saving and resetting settings

Manual save: clicking "Save settings" records the current values on screen into the settings file. If saving fails, because of restricted write permissions for example, the reason and the error are printed in red in the log area.
Reset: running "Reset settings" rewrites every value back to its default, after you confirm the dialog.

Preventing duplicate instances

If you start the application file again by mistake while it is already running, the duplicate-instance guard detects it. It shows a warning screen and then closes the duplicate process automatically.

[If the duplicate-instance warning appears even though no application window is on screen] The previous shutdown may not have closed completely and may still be present in the OS task list. Wait a few seconds and start it again, or clear the process as follows.

Press Ctrl + Shift + Esc to open the Windows "Task Manager".
Find and select VR169 Companion.exe in the process list.
Run "End task" to force the process closed, then start the application again.

Operating the shutter

Follow "The camera hand: operation and functions" and perform the shutter operation on the avatar.
The log shows that the shutter input was detected, and the VRChat camera takes a photograph.

[Note] Very occasionally the shutter does not fire. We plan to keep updating it towards greater stability. Shutter input is discarded for about two seconds from the moment VR169 and the application connect, and for consecutive input within about one second. This is a measure for stable operation and for how VRChat works. Thank you for your understanding.