Joystick Configuration (.joy) Files

In X-Plane 11, we added two new features aimed at making joystick configuration easy for users:

  • “image maps” that show you a picture of your joystick, with each of its buttons/axes labeled, and
  • detailed default configurations for joysticks.

Both are described in the .joy file corresponding to your joystick. These files are located in Resources/joystick configs/.

Creating a default joystick configuration file

The easiest way to create the default joystick configuration: plug in your joystick, configure it as you’d like, then hit the “Save as Default for [device]” button there on the joystick configuration screen.

That will output a .joy file wherever you’d like (recommended that you stick it in Resources/joystick configs/). You can confirm it worked by hitting the “Reset to Defaults for [device]” button and confirming that none of your axis or button assignments changes.

At this point, if you were to delete your preferences, when you plug in your joystick, you would see that your previous configuration gets loaded—your joystick would be instantly ready to use!

Creating an image map

Our image maps consist of two things:

  • a PNG image, which we’ve gotten clearance from a joystick manufacturer to distribute with the sim, and
  • information in the .joy file noting the pixel coordinates of that PNG image where buttons, axes, & hat switches should be labeled.

So, suppose we have an image that is 1,000 px on each side. If the very center of that image corresponds to a particular button, we’d put a line in the .joy file to the effect of “Button x should be labeled at position (500, 500).” (We’ll get to the actual syntax below.)

Unlike the default joystick configuration, we can’t auto-generate the image map. So, you’ll need to use an image editor to figure out where in the image each label for your buttons, axes, and hat switches should go. So, you’ll specify the coordinates for these things in pixels, with (0, 0) in the upper left of the image.

The easiest way I’ve found for getting these coordinates (if you don’t want to spend a zillion years in Photoshop hovering over portions of the images and noting the pixel coordinates in the Info tool) is to use the Easy Imagemap Generator tool. Here’s how that works:

Upload the image you want to work with.

  1. Click the Add Area button.
  2. Click within the image wherever you want to add an annotation. Two things will happen immediately:
    1. A tiny blue dot will appear on the image.
    2. A new line will appear in the source at the bottom of the window, giving you the (x, y) coordinates of that dot.
  3. Continue clicking Add Area and noting the new coordinates until you’ve gotten everything you need.

See the “View” section of the following file format description for the syntax of the image map text.

Notes on the image files

X-Plane only supports .png images with an optional transparent background. While there are no official size limits, we recommend the image be no larger than 2000×2000 pixels to avoid impacting sim performance. X-Plane will also scale large images automatically while maintaining the image map coordinates you specify.

Nitty gritty: the .joy file format, as of X-Plane 11pb13

See examples of finished .joy files in X-Plane 11/Resources/joystick configs.

Note that normally, if you specify image mappings, but leave some controls (axes, buttons, or hat switches) out of all image mapping, X-Plane will add one final “view” called Other Controls to display them. However, sometimes the USB hardware reports controls that don’t actually correspond to any physical axis, button, or hat switch. In that case, you can mark the control as “hidden” in the Assignments section (see examples below). Doing so will cause the UI to not display that control in an “Other Controls” section, or in the calibration screen (if it’s an axis).

I
1100 version
JOY
# ^ The header; must be the first thing in the file, verbatim.

# Operating system(s) this file applies to.
# Windows, macOS, and Linux will index the axes differently, so a file
# that correctly configures your joystick on one platform is *not*
# guaranteed to work on the other. 
OS: Windows
# Other valid options:
# OS: Mac
# OS: Linux
# Zero or more device names (provided by the operating system, as seen in the UI) that this .joy file describes.
# (Note that you need at least one name or one ID, described below.)
# If more than one device is named, we're saying that *any* of those devices should be configured
# using the *same* defaults and the same image maps.
Name: [device name]

# Zero or more USB identifiers (vendor ID + product ID) that this .joy file describes.
# (Note that you need at least one ID or Name, described above.)
# If more than USB identifier is given, we'll use this .joy file to configure *any* of those devices.
# You can specify the IDs in either hex or decimal form.
# For instance, the following are equivalent:
#    ID: VID:0x046DPID:0xC214
#    ID: VID:1133PID:49684
# ...since hex 046D == 1133, and hex c214 == 49684.
ID: VID:[vendor ID]PID:[product ID]

# Optional: Specify the name X-Plane should display for the device in the user interface
# (if this is different from the name the operating system provides)
Display: [device name override]

# Optional: Specify relaxed calibration rules for this device.
# This is useful if your USB hardware reports a wider range of axis motion than
# the device is actually capable of sending. (For instance, if you're a custom cockpit
# builder, and your axis reports 16 bits of travel, but you only use 10 bits.)
# This is *not* recommended if you have off-the-shelf hardware from a
# consumer hardware company like Saitek, Logitech, Thrustmaster, CH Products, etc.
Calibration: Relaxed

# Zero or more view sections
# These will be presented in the UI, and you can select different views for the same device
# (e.g., you might have one looking at the front of the device, one looking at the back, 
# and a third looking at the throttle quadrant). Presumably you will annotate *different* 
# controls for each view.
View: [view name]
-----------------------------------------------------------------------
Image: [image_name.png]

# Then, within the view section, you can zero or more of the following:
#   - buttons
#   - hat switches
#   - axes
#   - axis groups

# Buttons are easy; just specify which button you're talking about, and where in the image you
# want the "dot" for that button positioned.
# Note that these (x, y) pixel coordinates---like all the coordinates that follow---use the top left as (0, 0).
Button [button index]: [x coordinate in the image] [y coordinate in the image]

# Buttons can also take an optional *label* to display in the UI, like this:
Button [button index] ([label for UI]): [x coordinate in the image] [y coordinate in the image]

# Hat switches also take an optional label, so you can use either of the following:
Hat Switch [hat switch index]: [x coordinate in the image] [y coordinate in the image]
Hat Switch [hat switch index] ([label in the UI]): [x coordinate in the image] [y coordinate in the image]

# Axes, like buttons and hat switches, can take an optional label.
Axis [axis index]: [x coordinate] [y coordinate]
Axis [axis index] ([axis label]): [x coordinate] [y coordinate]

# In addition, axes can take an optional *axis direction*. This must be one of x, y, or z (lowercase).
# If you provide a direction, we'll use that letter when labeling the axis in the UI.
# So, the following are also valid axis labels:
Axis [axis index] ([x/y/z]): [x coordinate] [y coordinate]
Axis [axis index] ([axis label]; [x/y/z]): [x coordinate] [y coordinate]

# Finally, you can optionally group axes together in the UI.
# For instance, you probably don't want to display the x and y axes on your joystick separately.
Axis Group ([label for this group, displayed in the UI]): [1st axis index in this group] [2nd axis index]
Axis [index] ([x/y/z]): [x coordinate in the image] [y coordinate in the image]
Axis [index] ([x/y/z]): [x coordinate in the image] [y coordinate in the image]

# Zero or one assignment section
# This describes the default configuration for the device.
################################################################
# NOTE: 
# You almost certainly don't need to know the syntax for the
# assignments section, because you should be auto-generating
# it from an actual configuration (by hitting the 
# "Save as Default for [Device]" button in Settings > Joystick).
################################################################
Assignments:
------------------------------------------------------------------------

# Any number of axes, buttons, and hat switches.

Axis [axis index]: hidden
Axis [axis index]: [joy use]
Axis [axis index]: [joy use] reverse
#	Valid joy uses are:
#	 joy_use_none	joy_use_ptch	joy_use_roll
#	 joy_use_hdng	joy_use_thro	joy_use_coll
#	 joy_use_lbrk	joy_use_rbrk	joy_use_prop
#	 joy_use_mixt	joy_use_heat	joy_use_flap
#	 joy_use_vect	joy_use_swee	joy_use_sbrk
#	 joy_use_disp	joy_use_reverse	joy_use_elev_tr
#	 joy_use_ailn_tr	joy_use_rudd_tr	joy_use_thro1
#	 joy_use_thro2	joy_use_thro3	joy_use_thro4
#	 joy_use_prop1	joy_use_prop2	joy_use_prop3
#	 joy_use_prop4	joy_use_mixt1	joy_use_mixt2
#	 joy_use_mixt3	joy_use_mixt4	joy_use_reverse1
#	 joy_use_reverse2	joy_use_reverse3	joy_use_reverse4
#	 joy_use_gear	joy_use_tiller	joy_use_back_thro	joy_use_view_lr
#	 joy_use_view_ud	joy_use_view_zoom	joy_use_camera_lr
#	 joy_use_camera_ud	joy_use_camera_zoom	joy_use_gun_lr
#	 joy_use_gun_ud

Button [button number]: hidden
Button [button number]: [command path, like "sim/operation/quit"]
Hat Switch [hat switch number]: hidden
Hat Switch [hat switch number] Direction [hat switch direction]: [command path, like "sim/operation/quit"]
#	See X-Plane/Resources/plugins/Commands.txt for a complete list of commands
  • Facebook
  • Reddit
  • StumbleUpon
  • Twitter
  • Google Buzz
  • LinkedIn