Input Library Reference

The input library is the shared data model at the heart of Joystick Diagrams. Parser plugins produce ProfileCollection objects; output plugins consume Device objects. This page is the complete reference for both sides.

ProfileCollection

The top-level container. Your parser plugin's process() method creates one and returns it.

from joystick_diagrams.input.profile_collection import ProfileCollection

collection = ProfileCollection()

Profile

A profile represents a logical group of device and input configurations. In DCS World, each aircraft is a profile. A profile produces one or more diagrams depending on how many devices it contains.

name

Display name shown to users (e.g. "A-10C II").

devices

Device dictionary. Use add_device() and get_device(); don't modify directly.

Methods

profile.add_device(guid, name)

Adds a device to the profile and returns the Device_ object. If a device with the same GUID already exists, returns the existing one.

profile.get_device(guid)

Returns the Device_ object for the given GUID, or None if not found.

Profile Merging

Plugins can merge profiles for games with inherited bindings (e.g. Joystick Gremlin). Calling instance_a.merge_profile(instance_b) uses B as the base and layers A on top. Users can also apply parent profiles through the UI.

Building a Profile

This is the complete creation flow from collection to modifiers:

example.py

from joystick_diagrams.input.profile_collection import ProfileCollection
from joystick_diagrams.input.button import Button
from joystick_diagrams.input.axis import Axis, AxisDirection
from joystick_diagrams.input.hat import Hat, HatDirection
from joystick_diagrams.input.axis_slider import AxisSlider

# 1. Create the collection
collection = ProfileCollection()

# 2. Create a profile
profile = collection.create_profile("A-10C II")

# 3. Add a device (GUID, display name); returns the device object
device = profile.add_device(
    "150D55D0-D984-11EE-8001-444553540000",
    "VPC Stick MT-50CM2"
)

# 4. Add inputs
device.create_input(Button(1), "Weapon Release")
device.create_input(Button(2), "Countermeasures")
device.create_input(Hat(1, HatDirection.U), "Trim Up")
device.create_input(Hat(1, HatDirection.D), "Trim Down")
device.create_input(Axis(AxisDirection.X), "Roll")
device.create_input(Axis(AxisDirection.Y), "Pitch")
device.create_input(AxisSlider(1), "Zoom")

# 5. Add modifiers (library creates base input if needed)
device.add_modifier_to_input(Button(1), {"Ctrl"}, "Pickle")
device.add_modifier_to_input(Button(1), {"Ctrl", "Shift"}, "Jettison")

return collection

Control Types

Type	Fields	Identifier Format
`Button`	`id: int`	BUTTON_{id}
`Axis`	`id: AxisDirection`	AXIS_{X\|Y\|Z\|RX\|RY\|RZ\|SLIDER}
`AxisSlider`	`id: int`	AXIS_SLIDER_{id}
`Hat`	`id: int`, `direction: HatDirection`	POV_{id}_{U\|UR\|R\|DR\|D\|DL\|L\|UL}

The library handles de-duplication automatically. Adding the same input twice updates it rather than creating a duplicate.

Device Model

The Device_ object holds all inputs for a single hardware device within a profile.

Properties

device.guid

Unique device GUID string.

device.name

Display name of the hardware device.

Methods

device.get_inputs()

Returns all inputs grouped by type as a nested dictionary.

device.get_combined_inputs()

Returns all inputs as a flat dictionary, keyed by identifier.

device.get_input(type, id)

Returns a specific Input_ object, or None if not found.

get_inputs() returns inputs grouped by type:

{
    "buttons":     {"BUTTON_0": Input_, "BUTTON_1": Input_, ...},
    "axis":        {"AXIS_X": Input_, "AXIS_Y": Input_, ...},
    "axis_slider": {"AXIS_SLIDER_0": Input_, ...},
    "hats":        {"POV_0_U": Input_, "POV_0_D": Input_, ...},
}

Input_ Object

input_obj.identifier

String identifier, e.g. "BUTTON_0", "AXIS_X", "POV_1_U".

input_obj.command

The bound command or action name.

input_obj.modifiers

List of Modifier objects representing the modifier key combinations for this input.

input_obj.input_control

The underlying control type object (Button, Axis, AxisSlider, or Hat).

Modifiers

Each modifier represents a key combination that changes what an input does:

modifier.modifiers

Set of modifier key strings, e.g. {"Ctrl", "Shift"}.

modifier.command

The command bound when these modifier keys are active.

example.py

for mod in input_obj.modifiers:
    print(mod.modifiers)  # {"Ctrl", "Shift"}
    print(mod.command)    # "Jettison"
    print(str(mod))       # "Jettison - Ctrl+Shift"

Building plugins? See Creating Parser Plugins to learn how to produce this data, or Creating Output Plugins to learn how to consume it.