Unity Configuration Generator

Configurations provide the method for telling A part of the vrch project providing a Unity tool to generate index/address mapping coordinates.

What is a Configuration Map?

Configuration Maps are the magic sauce behind vrch.

A configuration map is a json formatted object that provides critical information needed to calculate haptic feedback levels:

1. Positional Haptic Node Information. (nodes)
2. Information to identify configuration used. (meta)

Typically nodes in a Configuration Map represent the Physical location of feedback points on someone's body. The Server then will use these physical locations to accurately output corrected haptic signals. Even if the two (or more) systems are structured completely different, it is still possible to mesh them with this method.

The structure of the Configuration Map allows for custom OSC Address definitions. This opens alot of doors for user-configurable solutions like VRC, since arbitrary addresses can be used as inputs for a location. Not just limited to Avatar Contacts.

Pretty much if you can answer the question: "where on the body should this address affect?" it is possible to drive haptics behaviour. An example of this is the Tail Pull example below.

Building Maps:

Setup The Project (can handle multiple maps)

• Create a new unity project either using the Unity Hub or VRCC, it doesn't matter which.
  • This project is based in unity 2022.3.22f1, but no special features were used so it should be compatible with most modern versions.
• Download the unity package from the Releases page.
• Import the package and load in the Haptics-Standard-DO NOT EDIT ME scene.
• CREATE A NEW SCENE. Do not change anything in the standard scene. Changes could render maps inaccurate to useless at best.
  • DO NOT MESS WITH THE DUMMY MODEL. Moving or scaling the dummy is garunteed to render innacurate maps in the best case scenerio.
  • If changes are accidentally made, using undo (ctrl+z) will solve most accidental moving of the dummy.
  • In the event that Undo is not helpful, simply delete the scene from the Assets/Scenes directory and reimport the package.

Configuration Map for a custom haptic device:

Make sure you have Gizmo's on, haptic nodes display the radius through them.

Meta Data:

• In your scene create an Empty Object, make sure that it is at origin (x:0, y:0, x:0).
• This will be your map root, name it something relevant.
• Add a MetaInfo component to your map root from the Scripts directory: Scripts/MetaInfo.
• Fill out the fields carefully: (These will later be used to identify your node map in-game)
  • Map_name: This is the name of your device. Note: Different authors can have the same Map_name.
  • Map_author: Your screen name, which will be used to identify maps you have made.
  • Map_version: An integer number greater than 0. Increment this each time you make a change to the map.

Build Nodes:

Add a child Game Object to the map root and add a NodeInfo from the Scripts directory.

Place node:

• Move the node into place on the surface of the standard model.

• A haptic node should be placed with the center point touching the avatars skin. Typically the half-sphere resulting from this is sufficient.

Configure the fields on your node:

• Address: Use the Generate Address button. Feel free to change the random characters to a legible name, but it shouldn't matter.
• External Address: (usually unchecked) If checked, a haptic node will not be created and it is up to the installer to ensure an address of that value exists on the avatar.
• Groups: These are what prevent nodes on the front of the torso from affecting the back nodes, and one leg from affecting another. Generally only 2 groups are needed on each node.
• Radius: Bigger means the node will be able to "service" a larger area of the skin, at the cost of triggering at a further distance from the skin.
• Target Bone: This is the avatar bone that this node should be parented to on avtar uplaod. This keeps the nodes "stuck" to the skin rather than rotating at weird angles as the avatar moves.

Duplicate the Node (ctrl + D), edit the needed parameters, and continue until satisfied.

Export Map:

Last step!

Click on Haptics -> Start Map Generator.

Drag the Map Root into the slot on the window.

• Errors will be noted on the window here.

When ready use the Generate Map button to export the map to: Assets/Exported Configs

Custom Tail Pull Feedback:

There are three main steps to pulling this off; Configuring the physbone, Creating the Map, and installing the map. The first two steps are shown here, follow the Unity Haptics Installer tutorial as usual.

VRC Physbone Configuration

VRC's Avatar contacts drive a parameter depending on how much a physbone is stretched. Since we know this can be represented by feedback at the base of the spine, we can create a map that pipes feedback into that region automatically.

From the documentation we can configure our tail physbone like this: The only things we care about are the Max Stretch and the Parameter, everything else can be left as is.

I went with a 10% growth to allow for some stretch, but not affect the existing setup too much. And with avatar/parameters/tail_Stretch for the parameter.

• Note the avatar/parameters/<parameter>_Stretch parameter structure.

Map Generation

After choosing a suitable name for this map (e.g. Tail_Pull) create a single node:

The node is configured like so:

The node produced this json map, which injects the /avatar/parameters/tail_Stretch parameter at the specified location. See the installer for indepth instructions.

{
  "nodes": [
    {
      "node_data": {
        "x": 0.0,
        "y": 0.9628999829292297,
        "z": -0.08659999817609787,
        "groups": [
          "TorsoBack"
        ]
      },
      "address": "/avatar/parameters/tail_Stretch",
      "is_external_address": true,
      "radius": 0.03750000149011612,
      "target_bone": "Hips"
    }
  ],
  "meta": {
    "map_name": "Tail-Pull",
    "map_author": "Average",
    "map_version": 1
}
}