Appendix C: Controller Button Reference

Complete reference of The Vault's Universal Button Mapping system with 70+ supported aliases.

Universal Button Mapping

The Vault normalizes button names across DualSense, Xbox, and Nintendo Pro controllers. All aliases below map to the same physical button, so you can use whichever naming convention you prefer in your controller profiles and running scripts.

Face Buttons (Bottom/Right/Left/Top)

Position	PlayStation	Xbox	Nintendo	Generic	Symbols
Bottom	cross	a	b	buttona	—
Right	circle	b	a	buttonb	o
Left	square	x	y	buttonx	—
Top	triangle	y	x	buttony	—

Shoulder Buttons

Position	PlayStation	Xbox	Nintendo	Generic
Left Shoulder	l1	lb	l	leftshoulder, leftbumper
Right Shoulder	r1	rb	r	rightshoulder, rightbumper

Trigger Buttons

Position	PlayStation	Xbox	Nintendo	Generic
Left Trigger	l2, lefttrigger	lt, lefttrigger	zl, lefttrigger	l2, lt
Right Trigger	r2, righttrigger	rt, righttrigger	zr, righttrigger	r2, rt

Thumbstick Clicks

Position	PlayStation	Xbox	Nintendo	Generic
Left Stick	l3	ls	lstick	leftthumbstick, leftthumbstickbutton
Right Stick	r3	rs	rstick	rightthumbstick, rightthumbstickbutton

Center Buttons

Position	PlayStation	Xbox	Nintendo	Generic
Left Center	share, create	view	minus, capture	select, buttonoptions
Right Center	options	menu	plus	start, buttonmenu
Home	ps	xbox, guide	home	home, buttonhome

D-Pad

Direction	Aliases (All Platforms)
Up	up, dpadup, dup
Down	down, dpaddown, ddown
Left	left, dpadleft, dleft
Right	right, dpadright, dright

Special Buttons (DualSense Only)

Button	Aliases
Touchpad	touchpad, clickpad

Usage Examples

Controller Profile Mapping

{
  "showcase": {
    "navigationActions": {
      "confirm": ["cross", "a", "b"],      // PlayStation, Xbox, Nintendo
      "cancel": ["circle", "b", "a"],
      "menu": ["options", "menu", "plus"]
    }
  }
}

Running Script with Multiple Aliases

::controller+share+options {
    -- Works with share+options (PS), view+menu (Xbox), minus+plus (Nintendo)
    do shell script "kill -INT {{{PID}}}"
}

::controller+l1+triangle {
    -- Works with l1+triangle (PS), lb+y (Xbox), l+x (Nintendo)
    do shell script "screencapture ~/Desktop/{{{GAME}}}.png"
}

Implementation Notes

Case Insensitive: Button names are normalized to lowercase (e.g., CROSS = cross)
Space Stripped: Spaces are removed (e.g., left shoulder = leftshoulder)
Symbol Support: A few symbol aliases resolve (e.g., o = circle, + = start, - = select)
Priority Order: If multiple aliases match, the first valid one is used
Extensible: New aliases can be added to normalizeButtonName() in UnifiedControllerService.swift

Source Code Reference

The Universal Button Mapping system is implemented in:

UnifiedControllerService.swift:1099-1181 - normalizeButtonName() function
GlobalHotkeyService.swift - Running script trigger matching
ProfileLoader.swift - Controller profile loading

💡 Pro Tip

When writing scripts or configuring profiles, use the naming convention you're most comfortable with. The Universal Button Mapping system will automatically translate it to the correct physical button regardless of which controller is actually connected.