The _vrconfig.txt file is a text-based configuration file that customizes VR interactions for your aircraft.

VR Configurations are aircraft-specific which means each ACF requires its own configuration file. While VR Configurations are not required, they are strongly encouraged. Aircraft that do not have a VR Configuration will still load and still work, even with VR enabled, however, there will be no hotspots to make it easy for the user to get back into the pilot seat, and there will be no customization allowing the VR controllers to be used to their fullest potential.

The VR Configuration name needs to match the prefix of the ACF file, with _vrconfig.txt appended to the end. For example, to make a VR config for Cessna_172SP.acf, the file needs to be called Cessna_172SP_vrconfig.txt. This file must exist in the same directory as the ACF file.

The _vrconfig.txt file is a text file – Unix or Windows line endings are legal, blank lines are allowed after the header, and the character set should be UTF-8.

The header of the file should be

A
1100
VRCONFIG

followed by the directives listed below.

Hotspot Definitions

Hotspots are predefined locations that are used to precisely orient the VR user when selected. They are commonly used on the pilot and co-pilot seats so that users can quickly position themselves accurately in the seats.

Each hotspot block defines a single hotspot on or around the aircraft. You must use a matched pair of BEGIN_TELEPORT_HOTSPOT and END_TELEPORT_HOTSPOT. In this block you must have:

  • Exactly one Axis-Aligned-Bounding-Box (AABB)
  • Exactly one XYZ location
  • Exactly one Psi, Theta, and Phi orientation respectively.

Note: All units are in Aircraft Coordinates – meters with the origin at the aircraft CG and the positive Z axis pointing aft.  This is not the same as the English units used in Plane-Maker.

BEGIN_TELEPORT_HOTSPOT <Hotspot Type> <Name>

This begins the definition of a new teleport hotspot. All hotspot properties must be specified after this directive and before the matched END_TELEPORT_HOTSPOT directive. The legal types of hotspots are ‘SITTING’ and ‘STANDING’. A sitting hotspot places the user’s head at the XYZ location. A standing hotspot places the user’s feet at the XYZ location. The name property is useful for debugging purposes.

END_TELEPORT_HOTSPOT

This defines the end of a given teleport hotspot. Each hotspot must be “ended” before anything else in the file occurs, and before the file ends.

AABB <minx> <miny> <minz> <maxx> <maxy> <maxz>

This adds an axis-aligned bounding box (in aircraft coordinates, that is +X = right, +Y = up, +Z = aft) in meters around the CG of the aircraft. When the teleport beam lands inside this box, if the user ends the teleport, this hotspot will be used to position the user.

PRESET_XYZ <x> <y> <z>

This sets the location of the user to the location X, Y, Z in meters, relative to the default CG of the aircraft; X is right, Y is up, Z is aft. A sitting hotspot places the user’s head at the XYZ location. A standing hotspot places the user’s feet at the XYZ location.

PRESET_PSI <deg 0 – 360>

This sets the rotation orientation (rotating about the Y-axis) of the user’s view in degrees. 0 degrees is facing forward in the aircraft, 90 would look toward the right wing, 180 degrees would be looking back at the tail etc.

PRESET_THE <deg -90 – 90>

This sets the pitch orientation (rotating about the X-axis) of the user’s view in degrees. 0 degrees is level. 90 would look straight up at the sky. -90 would look down at the ground.

PRESET_PHI <deg -180 – 180>

This sets the tilt orientation (rotating about the Z-axis) of the user’s view in degrees. 0 degrees is upright. -90 would be like tilting their left ear to their shoulder. 90 would be like tilting their right ear to their shoulder.

Manipulator Customization

Some aircraft manipulators need more information than is currently available in the OBJ itself in order to function optimally with VR Controllers. The most common examples of these are knobs and switches. With a mouse, knobs usually move one detent for each click. With a VR controller, however, X-Plane needs to know how much rotation is necessary in order to move the knob to the next detent. For linear knobs like lighting rheostats, this can be a fraction of a degree. For more coarse knobs like a fuel selector, you may want to require 60 degrees of rotation. There are other reasons to specialize manipulators such as changing their behavior entirely. For example, if the default aircraft manipulator uses commands to increment something by single degrees, but you want a smoother feel to the knob, you may want to redefine the manipulator to use a dataref to increment by fractions of a degree.

It’s important to note that customizations done with this file ONLY affect VR controllers. They will not change mouse or joystick hardware functionality.

BEGIN_MANIP  <manip type> <cmnd1/dref1> <cmnd2/dref2> <tooltip>

This begins the manipulator block that defines the EXISTING aircraft OBJ manipulator to be customized. All manipulator properties must be specified AFTER this directive and before the matched END_MANIP directive. This line essentially contains the unique pieces of the OBJ manipulator for it to be looked up.

The manipulator type needs to match the type specified in the OBJ but without the ‘ATTR_manip_’. For example, if the OBJ has an ATTR_manip_command_axis, the type (for the purposes of this file) should be ‘command_axis’. The cmnd1/dref1 and cmnd2/dref2 should match those that exist in the OBJ manipulator definition. If the manipulator needs only one command/dataref, then cmnd2/dref2 can be omitted completely.

Lastly, to disambiguate two manipulators that have the exact same type and act on the same commands/datarefs, an optional tooltip can be used. This is common with Yoke manipulators since there are usually two yokes for the pilot and copilot and they typically act on the same datarefs. Again, if the tooltip is unnecessary to find a manipulator that is unambiguous and unique, it can be omitted completely.

The manipulator block will match only one manipulator – if more than one manipulator in the OBJ matches the specification, only one will be remapped; use more information (E.g. tooltips) when you need to remap manipulators that are otherwise ambiguous.

END_MANIP

This marks the end of a given manipulator block. Each manipulator block must be “ended” before anything else in the file occurs, and before the file ends.

ACTION axis_knob <v1 min> <v1 max> <dx> <dref1>

This tells the VR system that this manipulator should be changed to an axis_knob manipulator and used instead of the original manipulator. This is useful if you want to act on the dataref instead of a command in VR mode to have finer control over the knob’s increment/decrement amounts. DX specifies the amount of change applied to the dataref for each action. Use DEG_PER_ACTION to set the amount of wrist rotation needed for an action to fire.

ACTION drag_xy four_arrows <dx> <dy> <v1min> <v1max> <v2min> <v2max> <dref1> <dref2> <tooltip>

This tells the VR system that this manipulators should be changed to a drag_xy manipulator and used instead of the original manipulator. This is usually used to override the show/hide Yoke manipulator to instead make it behave as if the user has grabbed the yoke to begin using it.

DEG_PER_ACTION <deg>

This tells the system how many degrees of wrist rotation is necessary before a knob manipulator will be acted upon. Another way of thinking about it is how far does the VR controller need to be rotated before the manipulator will fire as if the mouse was clicked once.

SWITCH_THRESHOLD <angle threshold deg> <offset thresh meter>

Similar to DEG_PER_ACTION for knobs, SWITCH_THRESHOLD tells the system how much wrist tilt or motion is necessary to trigger a command. This is useful for things dials like the vertical speed dial on an airliner. The angle in degrees tells the system how many degrees of tilt are necessary before triggering the command. The offset threshold in meters tells the system how much motion should exist before triggering the command. This allows the user to lift/lower their arm to operate the dial instead of tilting their wrist.

WRAP_MANIP

This tells the system that the knob manipulator should wrap. Examples of knobs that should wrap would include the course knob or heading bug. Examples of knobs that should not wrap are lighting knobs and volume controls.

HOLD_MANIP

This tells the system that the knob/switch manipulator should hold down commands continuously while it is not in motion. Without this, commands are issued once for each ‘click’ of the switch or knob; with this, a command is held until the knob/switch is released or moved again. Do not use this for manipulators that use datarefs. It is only intended for command manipulators.

Starter keys and spring-loaded knobs and switches often require the HOLD_MANIP directive as they will return to the off position when not held.

JOYSTICK_MANIP <pitch min deg> <pitch max deg> <roll min deg> <roll max deg>

This tells the system that the manipulator is one that should be treated like a real-world joystick control (like those found on Airbuses and the CirrusJet). The data here will only become active if the user has enabled “Realistic” mode for their VR Yokes. The pitch and roll mins and maxes define the range of tilting motion in degrees of the VR controller that should be mapped to the full range of motion of the flight controls.

YOKE_MANIP_TRANSLATE <pitch trans axis min x> <pitch trans axis min y> <pitch trans axis min z> <pitch trans axis max x> <pitch trans axis max y> <pitch trans axis max z> <roll cent x> <roll cent y> <roll cent z> <roll min ang> <roll max ang>

This tells the system that the manipulator is one that should be treated like a real-world yoke control (like those found on a Cessna 172) where the pitch axis is a translation axis that slides back and forth and the roll axis is a rotation one like a steering wheel that rotates about a centroid. The data here will only become active if the user has enabled “Realistic” mode for their VR Yokes.

Pitch min and max x,y,z are in OBJ units and define the axis of translation for pitch; they can be taken directly from the translation axis used to animate your yoke. The length of the vector between these points defines how far the yoke moves from full nose up to full nose down, and is typically aligned along the Z axis.

Roll centroid x,y,z are also in OBJ units and define the point at which the yoke rotates around. This point should be somewhere on the center of the yoke, and can be taken from the static translation that precedes your yoke’s roll animation.

The roll axis defines the axis about which the yoke rolls, and can be taken from the axis of your roll animation directly. This should be a unit vector, and will typically be about the Z axis.

The roll min and max angles define the maximum travel in either direction from the “level” point, and can be taken from the end key frames of your roll animation.

YOKE_MANIP_ROTATE <pitch cent x> <pitch cent y> <pitch cent z> <pitch axis x> <pitch axis y> <pitch axis z> <pitch min deg> <pitch max deg> <roll cent x> <roll cent y> <roll cent z> <roll axis x> <roll axis y> <roll axis z> <roll min deg> <roll max deg>

This tells the system that the manipulator is one that should be treated like a real-world flight stick (like those found in a fighter jet or SuperCub) where the pitch and roll axis are attached to a single stick that is attached to a mount point that can be rotated forward and back as well as left and right about two centroids (that can be co-located).

Pitch and roll centroid x,y,z are in OBJ units and define the centroids about which the pitch and roll axis rotates – you can take them from the static translation that precedes your animation.

Pitch and rolls axis x,y,z define the unit vectors of the rotation axes for pitch and roll; they should be unit vectors and can be taken directly from your pitch and roll animations. Typically the pitch axis will be the X axis and the roll axis will be the Z axis.

The pitch and roll min and max degrees define the maximum amount of rotation that can exist in either direction, for both pitch and roll.

Note that you can use YOKE_MANIP_ROTATE for both flight sticks (like a helicopter or fighter) or for airliner-style column yokes. In the flight stick case, the rotation centroid is at the floor pivot for both axes. For an airliner yoke, the pitch centroid is on the floor but the roll centroid is on the yoke itself.

We do not recommend using YOKE_MANIP_ROTATE for very small side sticks because they are hard to control in VR; prefer JOYSTICK_MANIP instead.

 

8 comments on “Aircraft VR Configuration (_vrconfig.txt) File Format Specification

  1. This is a great article. I plan to modify the vrconfig file to make the GPS knobs less sensitive when you change frequency or adjust the ICAO in the flight plan. Thank you for including these modifiers for developers and users!!

  2. If there is no _vrconfig.txt file, will a VR load of 11.20 fail or hang up? My Log.txt file complains it can’t find iPad_vrconfig.txt, which seems to be the point at which the load fails. I started having this problem when I loaded the Oculus app after I bought a Rift. I didn’t have this problem with the vr beta, running iVRy, iTunes, and SteamVR with my iPhone.

  3. I was wondering if there are plans to add more ACTION “manip type” options to change manipulators without having to globally change it in the obj. Right now ACTION axis knob works incredibly, but I’m having trouble with ACTION “any other manip” (not getting vr_config error, but crashes sim when using manip). Would love to change some throttle and mixture drag axis’s to “drag rotates”. Thanks!

  4. I made a VERY simple config file for the Zenith Zodiac 650 that I imported from version 10. Loaded it into Plane Maker and saved it. Using joystick and rudder peddles for controls, the plane would fly off and leave me. I thought making a couple hotspots would be the solution once I found this.

    I followed the directions, and then confirmed that I had it correct by referencing the included configs for the 172’s. It still didn’t work.

    I looked in the logs. In consecutive statements it told me that it was loading the config file, it could not find the config file, that the config file was not valid, that it could not find the config file, and again that the config file was not valid. (Yes. It actually said it was not present and invalid twice.)

    I test software for a living and I would open this as a Pri-1 bug, and have a long conversation with the developer until we come to terms. If you are going to bother to put something in a log file, make it useful. Could you give me a hint about what might not have been valid about it? I mean, you had to have looked at it and had some sort of decision logic of WHY it wasn’t valid. If nothing else you could spit the line that gave you indigestion back at me. “The file is invalid” is simply lazy programming.

    I don’t mean to be preachy, but I run into this constantly and it just makes everyone’s (and by “everyone’s”, I mean “my”) life difficult.

    1. Hi Ernest,

      It sounds like there may be a bug in the _logging code itself_. Please file a bug and include your full log.txt file and VR config file even though it’s useless – we may need to fix the logging so it is informative.

      cheers
      Ben

  5. Is it possible to control the current hotspot in use via plugin? I would like to move the user to a specific hotspot using my plugin code.

Leave a Reply

Your email address will not be published. Required fields are marked *

Please do not report bugs in the blog comments.
Only bugs reported via the X-Plane Bug Reporter are tracked.