Controller Setup

Linux controls

For Linux pairing, device access, Steam Input, and shortcut differences, follow Controllers and keyboard. Windows driver and calibration steps below apply to Windows.

Your arcade cabinet or gaming setup deserves proper controls. HyperHQ makes it easy to configure arcade sticks, buttons, gamepads, keyboards, and even trackballs so everything works exactly how you want.

What Controllers Does HyperHQ Support?

HyperHQ works with virtually any input device:

Arcade Controls

• Joysticks and buttons (USB or keyboard encoder)
• LED buttons with lighting effects
• Spinners and trackballs
• Multi-player setups (2, 4, or more players)

Gamepads

• Xbox controllers (wired and wireless)
• PlayStation controllers (DualShock and DualSense)
• Generic USB gamepads
• Retro USB controllers (Genesis, Saturn, etc.)
• Modern USB gamepads

Keyboards

• Standard keyboards
• Keyboard encoders (I-PAC, J-PAC, etc.)
• Programmable keyboards

Specialty Devices

• Trackballs (arcade-style or USB)
• Steering wheels and pedals
• Light guns
• Flight sticks

Confirm your operating system recognizes the device, then check detection and mapping in HyperHQ.

Understanding Input Types

HyperHQ uses different input systems depending on your hardware:

Gamepad API (SDL2)

Modern gamepads connect through SDL2, a powerful input library:

• Automatic detection of most controllers
• Standard button mapping across brands
• Analog stick and trigger support
• Rumble/vibration support
• Hot-plug support (connect/disconnect anytime)

This is what handles your Xbox, PlayStation, and Switch controllers.

Keyboard Input

Arcade controls usually show up as keyboard presses:

• Each button sends a keyboard key
• Configured through encoder software or firmware
• Works with I-PAC, J-PAC, and similar encoders
• Simple and reliable

If you're using arcade buttons, they're probably sending keyboard commands.

Hat Switch / D-Pad Input

Some arcade control panels use hat switches (8-way directional switches on a PCB) instead of standard joystick axes for direct input. HyperHQ and HyperSpin both support hat switch input natively.

• Hat events are converted to standard D-pad press/release events automatically
• No special configuration needed - plug in your control panel and it works
• Covers all 8 directions: up, down, left, right, and all diagonals
• Works alongside regular joystick and button inputs on the same device

If your control panel uses hat switches for directional input, it should work out of the box without any remapping.

Direct Input

Some older controllers use DirectInput:

• Legacy gamepad protocol
• Less common these days
• HyperHQ supports it but prefers SDL2/XInput
• Consider upgrading to XInput drivers if available

Setting Up Your First Controller

Let's walk through configuring a controller:

1. Connect Your Controller

Plug in your controller or arcade controls:

• USB controllers: Just plug and play
• Bluetooth: Pair through your operating system settings first
• Arcade encoders: Connect and install drivers if needed

Confirm the device appears in your operating system before mapping controls.

2. Open Controller Settings

In HyperHQ:

1. Click Settings in the bottom left
2. Navigate to Controllers
3. You'll see all detected controllers listed

3. Select Your Controller

Click on the controller you want to configure. You'll see:

• Controller name and type
• Current button mappings
• Configuration options

4. Configure Buttons

Click Configure Buttons to start mapping:

For Gamepads:

1. HyperHQ shows you which button to press
2. Press the button on your controller
3. HyperHQ records it
4. Move to the next button
5. Repeat until done

For Arcade Controls:

1. Press the arcade button you want to map
2. HyperHQ detects the keyboard key
3. Assign it to a function (Up, Down, Left, Right, Button 1, etc.)
4. Continue for all buttons

5. Test Your Setup

Once mapped, test it:

• Navigate the test screen
• Press each button to verify it works
• Check diagonal directions on joysticks
• Make sure everything feels right

6. Save Your Profile

Click Save Profile and give it a name:

• "Player 1 Arcade"
• "Xbox Controller"
• "2-Player Setup"
• Whatever helps you remember

You can create multiple profiles and switch between them anytime.

HyperSpin default controls

Fresh installs start with these Player 1 bindings. Your saved mappings take priority.

Action	Keyboard	Controller
Wheel Up / Down	Arrow Up / Arrow Down	Left Stick or D-pad Up / Down
Hop Left / Right	Arrow Left / Arrow Right	Left Stick or D-pad Left / Right
Select	Enter	A
Back	Escape	B
Exit Menu	1	Start
Previous / Next Item	Minus / Numpad Plus	Left Trigger / Right Trigger
View Details	X	Y
Menu	M	Modifier + B
Search	F1	Right Bumper
Pause Menu	F2	Modifier + Start
Exit Game	Delete	Modifier + Back

Exit Menu opens the two-choice exit screen. Choose Yes to close HyperSpin or Menu to open frontend settings.

Menu opens frontend settings directly.

Button Mapping for Arcade Controls

Arcade controls need careful mapping. Here's what works best:

Standard Arcade Layout

Map your joystick and buttons to these functions:

Joystick

• Up, Down, Left, Right (obvious but important)
• Test diagonals to make sure they work

Action Buttons

• Button 1: Primary action (Jump, Attack, etc.)
• Button 2: Secondary action
• Button 3: Tertiary action
• Button 4-6: Additional buttons for 6-button games

System Buttons

• Start: Launch games, pause in-game
• Select/Coin: Insert coins in arcade games
• Exit: Return to HyperSpin (usually mapped to Escape)

2-Player Setups

Building a 2-player cabinet? Map each player separately:

Player 1

• Joystick: Arrow keys or WASD
• Buttons: Ctrl, Alt, Space, Shift, Z, X (common defaults)
• Start: 1 key
• Coin: 5 key

Player 2

• Joystick: Usually R, F, D, G (or custom)
• Buttons: A, S, Q, W, I, K (varies)
• Start: 2 key
• Coin: 6 key

These are typical defaults that work with most emulators out of the box.

Multi-Player Cabinets

More than 2 players? Map them similarly:

• Each player gets their own joystick and button set
• Use number keys for Start (1, 2, 3, 4)
• Coin keys: 5, 6, 7, 8
• Make sure no buttons overlap between players

Gamepad Configuration

Gamepads are simpler thanks to SDL2's automatic detection:

Xbox Controllers

Connect through USB or pair through Bluetooth, then open Settings, Controllers.

• Windows: Check device detection and the installed controller driver.
• Linux: Check kernel support for your controller and connection type. Wireless adapters and Bluetooth require separate checks.
• Both: Verify buttons, triggers, player assignment, and reconnect behavior in HyperHQ.

PlayStation Controllers

PlayStation controllers need a little setup:

DualShock 4 / DualSense

1. Connect via USB or pair through your desktop's Bluetooth settings.
2. Confirm device detection in your operating system.
3. On Windows, review any DS4Windows mapping already in use. Avoid duplicate physical and virtual inputs.
4. On Linux, use the Linux device driver and SDL mapping. DS4Windows instructions do not apply.
5. Open Settings, Controllers and test each input.

Touchpad (if available) can be mapped to special functions.

Modern USB Controllers

Modern USB controllers work great:

1. Connect via USB or Bluetooth
2. Confirm your operating system recognizes the controller
3. HyperHQ detects them automatically
4. Button layout is standard

Generic USB Gamepads

Most USB gamepads work out of the box:

• HyperHQ uses SDL2's gamepad database
• Thousands of controllers supported
• If yours isn't recognized, you can add it manually

Keyboard Mapping for Navigation

Using a keyboard to control HyperSpin? Here's a good default setup:

Navigation

• Arrow Keys: Move through wheels
• Enter: Select/Launch game
• Escape: Exit/Go back
• Left/Right: Previous/Next game
• Up/Down: Menu navigation (if used)

Special Functions

• F1: Toggle search
• F2: Toggle favorites
• F5: Refresh
• Tab: Switch between systems

Game-Specific

• Space: Pause emulator
• P: Screenshot
• F12: Fast forward (if emulator supports it)

You can customize all of these in HyperHQ's keyboard settings.

Trackball Setup

Got a trackball? Here's how to configure it:

1. Connect Your Trackball

USB trackballs work like mice:

• Plug it in
• Confirm pointer movement in your desktop on Windows or Linux
• No special drivers usually needed

2. Configure in HyperHQ

1. Go to Settings > Controllers > Trackball
2. Enable trackball support
3. Configure sensitivity:
   • Low: Slower, more precise
   • Medium: Balanced (good default)
   • High: Fast, arcade-style

3. Map Trackball Buttons

Most trackballs have buttons:

• Left button: Select/Launch
• Right button: Back/Cancel
• Middle button: Special function (optional)

Map them just like regular buttons.

4. Games That Use Trackball

Trackballs shine in classic arcade games:

• Centipede
• Missile Command
• Marble Madness
• Arkanoid
• Golden Tee

Configure per-game if needed - most emulators detect trackballs automatically.

Trackball Tips

Adjust Sensitivity Per Game

• Slower for precision games (Golden Tee)
• Faster for action games (Missile Command)
• Save profiles for different speeds

Clean Your Trackball

• Dust and dirt affect tracking
• Remove the ball and wipe it down
• Clean the rollers inside
• Better tracking = better gameplay

Saving and Loading Profiles

Profiles let you switch between different controller setups:

Creating a Profile

1. Configure your controller
2. Click Save Profile
3. Name it descriptively
4. Optional: Set as default

Switching Profiles

Need a different setup?

1. Go to Settings > Controllers
2. Click Load Profile
3. Select the profile you want
4. Controllers remap instantly

Profile Use Cases

Multiple Controllers

• "Xbox Player 1"
• "Xbox Player 2"
• Switch between them easily

Different Setups

• "Arcade Mode" (arcade controls)
• "Cabinet Mode" (arcade controls)
• "Couch Mode" (gamepad)
• Quick switching between play styles

Per-System Profiles

• "MAME 6-Button" (fighting games)
• "MAME 2-Button" (classic arcade)
• Load automatically per system

Guest Mode

• "Guest Controller" (simplified layout)
• Quick setup for friends who come over

Multiple Controller Support

Running a multi-player cabinet? HyperHQ handles it:

Auto-Detection

HyperHQ detects multiple controllers automatically:

• Each controller gets a player number
• Player 1, Player 2, Player 3, etc.
• Shown in the controller list

Individual Configuration

Configure each controller separately:

1. Select Player 1's controller
2. Map their buttons
3. Save as "Player 1 Profile"
4. Repeat for Player 2, 3, 4...

Controller Priority

Set which controller is Player 1:

• Useful if multiple controllers are connected
• Drag to reorder in the controller list
• First in the list = Player 1

Hot-Plugging

Connect or disconnect controllers anytime:

• HyperHQ detects changes
• New controllers appear automatically
• Disconnected controllers are marked
• No restart needed

Disabling One Controller

If your operating system or SDL reports an unwanted navigation device, disable input for the specific controller:

1. Go to Settings > Controllers
2. Select the controller from the list
3. Click Disable Input in the controller settings header
4. Save the controller settings

This applies to the selected physical controller. If you have two matching controllers connected, disabling one does not disable the other.

Controller Testing

Always test your controllers after configuring:

Built-in Test Mode

HyperHQ includes a test screen:

1. Go to Settings > Controllers
2. Click Test Controller
3. Press buttons to see if they register
4. Move joysticks to test analog input
5. Check all directions and diagonals

In-Game Testing

Test in actual games:

• Launch a simple game you know well
• Try all buttons
• Test navigation and gameplay
• Make sure everything feels right

Emulator Test ROMs

Use test ROMs to verify arcade controls:

• Input test ROMs (show exact button presses)
• Available for MAME and other emulators
• Great for troubleshooting

Advanced Controller Options

Analog Stick Configuration

For gamepads with analog sticks:

Deadzone

• How much you move the stick before it registers
• Too low: Drift and unwanted movement
• Too high: Slow response
• Default: Usually 15-20%

Sensitivity

• How fast the stick responds
• Lower: Precise control
• Higher: Quick movements
• Adjust to preference

Trigger Configuration

Modern controllers have analog triggers:

Full Range Mode

• Uses entire trigger pull
• Good for racing games
• Gradual input

Button Mode

• Trigger acts like a digital button
• Press past threshold = button press
• Better for retro games

Rumble/Vibration

Enable or disable controller rumble:

• Some emulators support it
• Can be distracting in menu navigation
• Per-controller setting

Button Combinations

Map special functions to button combos:

• Hold Select + Start = Exit game
• Hold L + R = Save state
• Customizable in settings

Troubleshooting Controllers

Controller Not Detected?

Check these things:

USB Connection

• Try a different USB port
• Check the cable isn't damaged
• Make sure it's plugged in all the way

Bluetooth Controllers

• Verify pairing in your desktop Bluetooth settings
• Check battery level
• Re-pair if necessary

Drivers

• Some controllers need drivers
• Check manufacturer's website
• Windows: Check controller driver updates.
• Linux: Check distribution/kernel support and device permissions.

HyperHQ Recognition

• Restart HyperHQ after connecting
• Check Settings > Controllers for the device
• View logs for error messages

Buttons Not Working?

If specific buttons don't respond:

Test outside HyperHQ

• Windows: Open Set up USB game controllers and test the button.
• Linux: Use your desktop or distribution's controller test tool. Confirm user access to the device.
• Fix missing operating-system input before changing HyperHQ mappings.

Check Mapping

• Verify the button is actually mapped
• Re-map if necessary
• Save the profile after changes

Conflicts

• Make sure multiple controllers aren't using the same buttons
• Check for keyboard conflicts with arcade encoders

Joystick Acting Weird?

Joystick problems are usually calibration:

Check calibration

• Windows: Open Set up USB game controllers, select the joystick, then open Properties, Settings, Calibrate.
• Linux: Check axes with a controller test tool, then adjust the device or emulator calibration where supported.
• Both: Recheck HyperHQ deadzone settings after calibration.

Check Deadzone

• If the joystick drifts, increase deadzone
• If it feels sluggish, decrease deadzone

Physical Issues

• Arcade joysticks can wear out
• Check switches and microswitches
• Clean contacts
• Replace if necessary

Multiple Inputs Registering

Getting double inputs?

Keyboard + Gamepad Conflict

• Arcade encoders might be seen as both
• Open the specific controller and click Disable Input if you do not want HyperHQ to use that device
• Or map them to different functions

Multiple Gamepads

• Make sure you're configuring the right one
• Disconnect others while mapping
• Re-connect after configuration

Wrong Controller Being Used

If HyperHQ uses the wrong controller:

Set Priority

• Reorder controllers in the list
• First controller = highest priority
• Drag and drop to reorder

Disable Unused Controllers

• If you have controllers you don't use
• Select the controller and click Disable Input
• Prevents confusion
• The setting is per physical controller, so matching controllers can be enabled or disabled one at a time

Keyboard Encoder Specifics

Using I-PAC, J-PAC, or similar? Here's what to know:

What Are Keyboard Encoders?

Keyboard encoders convert arcade buttons to keyboard presses:

• Arcade buttons connect to the encoder
• Encoder connects to PC via USB
• Each button sends a specific keyboard key
• PC thinks it's a keyboard

Popular encoders:

• I-PAC: Supports up to 4 players
• J-PAC: JAMMA harness support
• Zero Delay: Budget USB encoder
• BX-Controller: Bluetooth option

Setting Up Encoders

1. Connect Your Arcade Controls

   • Wire buttons to encoder screw terminals
   • Follow encoder's wiring diagram
   • Test continuity

2. Configure Encoder Software

   • Download encoder software (I-PAC has WinIPAC)
   • Map each input to a keyboard key
   • Use standard keys (Arrow keys, Ctrl, Alt, etc.)
   • Upload config to encoder

3. Configure in HyperHQ

   • HyperHQ sees it as a keyboard
   • Map keyboard keys to HyperSpin functions
   • Test thoroughly

Recommended Key Mappings

Here's a proven layout that works with most emulators:

Player 1

• Joystick: Up, Down, Left, Right (arrow keys)
• Button 1: Left Ctrl
• Button 2: Left Alt
• Button 3: Space
• Button 4: Left Shift
• Button 5: Z
• Button 6: X
• Start: 1
• Coin: 5

Player 2

• Joystick: R, F, D, G
• Button 1: A
• Button 2: S
• Button 3: Q
• Button 4: W
• Button 5: I
• Button 6: K
• Start: 2
• Coin: 6

These are MAME defaults and work across most emulators.

Per-System Controller Profiles

Different systems need different button layouts:

MAME (Arcade)

Most arcade games use 6 buttons or fewer:

• Standard layout works great
• 6-button setup for fighters
• 2-3 buttons for classics

Sega Genesis

Genesis uses a simple 3 or 6-button layout:

• D-Pad: Movement
• A, B, C Buttons: Actions
• X, Y, Z Buttons: Additional actions (6-button games)
• Start: Pause/Menu

Map your controller to match the original feel.

Sega Saturn

Saturn has a complex button layout:

• D-Pad: Movement
• A, B, C, X, Y, Z: Six face buttons
• L, R: Shoulder buttons
• Start: System button

Use a gamepad for the authentic experience.

PlayStation

PlayStation has even more buttons:

• D-Pad or Left Stick: Movement
• Face buttons: X, O, Square, Triangle
• Shoulder buttons: L1, R1, L2, R2
• Analog sticks: L3, R3 (clickable)

Modern gamepads match this layout perfectly.

Custom Per-Game Controls

Some games need unique setups:

• Driving games: Map to steering wheel
• Light gun games: Configure gun input
• Flight sims: Use flight stick

HyperHQ can save per-game profiles for these special cases.

Best Practices

Test Before You Commit

Always test new mappings:

• Use the test mode
• Try multiple games
• Make sure everything feels natural
• Adjust as needed

Document Your Setup

Keep notes on your controller config:

• Which buttons do what
• Special mappings
• Profile names and uses
• Future reference

Back Up Your Profiles

Save your controller profiles:

• Export from HyperHQ
• Store somewhere safe
• Easy restoration if you reinstall
• Share with friends building cabinets

Start Simple

Don't map everything at once:

• Configure basic controls first
• Test and refine
• Add advanced features later
• Iterate as you play

Use Consistent Mappings

Keep layouts similar across systems:

• Button 1 is always "primary action"
• Start always launches/pauses
• Exit always goes back
• Muscle memory is powerful

Common Controller Questions

Can I use multiple controllers at the same time? Connect each controller, confirm detection in Settings, Controllers, and assign players. Test your full player count on Windows or Linux.

Do I need a gamepad for HyperSpin navigation? Nope! You can navigate entirely with keyboard, arcade buttons, or whatever input you prefer.

Can I change controls per game? Yes! Create per-game profiles for special cases. Most games use system-wide defaults though.

What if my controller isn't recognized? Check cables, device drivers, and SDL mapping. On Linux, also check device permissions. On Windows, review virtual-controller tools for duplicate input.

Can I use wireless controllers? Pair the gamepad in your desktop Bluetooth settings, then test detection and reconnect in HyperHQ.

How many buttons do I need for arcade controls? Depends on your games. 6 buttons per player covers most arcade games. Fighting game fans might want 8.

Can I add more buttons later? Sure! Expandable encoders let you add buttons anytime. Just re-map in HyperHQ when you do.

Do arcade sticks wear out? Eventually, yes. Quality sticks (Sanwa, Seimitsu) last years. Microswitches are replaceable when they do wear out.

What's Next?

Controllers configured? Your arcade is getting close to complete!

Want to add LED lighting effects? Check out LED Lighting Setup to make those buttons dance.

Building a cabinet with marquee or companion hardware? Explore Plugins for supported integrations.

Need help? The Troubleshooting guide covers common issues, or visit the community at HyperSpin-fe.com.

Your arcade, your rules. Let's keep building.