Building a leverless controller
Intermediate
Or see every lesson.
- 261parts on the bench
- 31boards running now
- 1.00xreal time, on every board
A leverless controller, often called a hitbox-style or all-button controller, replaces the joystick lever with four buttons: left, down and right under the fingers of one hand, and up under a thumb. The appeal is precision. A button is either pressed or not, so there is no travel through a gate and no diagonal you can miss by a few degrees.
Electrically it is even simpler than a stick, because every input is the same kind of switch. The one new problem is that nothing physical stops you pressing left and right together. The firmware has to decide what that means, and that decision is called SOCD cleaning.
The circuit above is a leverless layout on a Pro Micro in Mokxi. The four direction buttons are the console pad with its rocker turned off, so they act as four separate switches and the arrow keys can hold any of them at once. A slide switch picks the cleaning rule, and four LEDs show the direction that comes out. Hold left and right together and watch what the rule does.
The layout
Most leverless layouts put left, down and right in a row under the left hand’s ring, middle and index fingers, with up as a larger button under the left thumb, and the attack buttons in two rows for the right hand. Many put a second up button under the right thumb as well. There is no single standard, and builders move buttons around to suit their hands and their game.
Plan the layout on paper first, then count inputs. Four directions and eight attack buttons is twelve pins, and start, select and a home button make fifteen. The Pro Micro modeled in Mokxi has 18 input and output pins. A Raspberry Pi Pico has 26 GPIO, which is one reason so many all-button builds use one.
Wiring
Wire every button the same way: one leg to a shared ground chain, the other leg to its own pin, with the pin’s internal pull-up turned on. A pressed button reads LOW. No resistors, no diodes and no matrix are needed as long as every button has its own pin, and it should, because a matrix without diodes cannot read some combinations of buttons held together, and holding several buttons together is exactly what a leverless controller is for.
In the example, up, down, left and right are on pins 2 to 5, the two attack buttons are on pins 6 and 7, and the mode switch is on pin 8. The LEDs on A3 to A0 each have their own 220 ohm resistor. Open the project and move a wire to see what a mistake looks like before you solder one.
SOCD cleaning in the code
The sketch reads the four direction pins and cleans each axis on its own. In neutral mode, left and right together give neither, and so do up and down. In last-input mode, the direction pressed most recently wins, so holding left and then adding right gives right, and letting go of right brings back left. Slide the switch and try both.
Many builders also use up priority on the vertical axis: up and down together give up, which lets a player hold down to crouch and press up to jump without letting go. The example has a one-line setting for it. The SOCD cleaning page goes through each rule and what it changes for the player.
Whichever rule you choose, check the rules of the game or the event you play in. Some tournament rule sets and some games say which cleaning a controller may use.
int clean(bool negative, bool positive, int last, bool lastWin) {
if (negative && positive) {
return lastWin ? last : 0; // last input wins, or neutral
}
return (positive ? 1 : 0) - (negative ? 1 : 0);
}Pro Micro or Pico
Both boards have USB on the chip, which is what a controller needs. The Pro Micro is the classic Arduino choice, with the Arduino Joystick or Keyboard library on top. The Pico’s RP2040 is what GP2040-CE, a popular open source gamepad firmware, runs on, and GP2040-CE already includes SOCD modes, debounce and button remapping, so many builders flash it and write no code at all.
In Mokxi, the Pro Micro runs the example as written. The simulated Pico runs Arduino sketches with digitalRead and INPUT_PULLUP, so the same button logic works there too, but it does not model the Pico’s USB, and it cannot run GP2040-CE itself. Neither board is a real USB controller in the simulator: the examples print what they would report.
Button lighting
Lit buttons are popular on all-button controllers. Most lighting uses WS2812 addressable LEDs, one or more under each button, driven from a single pin. In Mokxi, WS2812 strips run from the ESP32-C3 and ESP32-C6, so the lighting project is on a C3: each of four arcade buttons lights its own pair of LEDs when pressed and fades out when let go. The logic carries over to any board; on a real Pro Micro or Pico the LED driver underneath is different.
Testing before you build
A case with twenty holes in it is hard to change. Testing the layout and the code first saves a lot of drilling. In the simulator you can check that every button reaches the right pin, that two opposite directions do what you expect in each mode, and that holding many buttons at once still reads correctly. What the simulator cannot check is the USB side: whether your console or PC accepts the board. That part happens on the bench.
Questions
What is a leverless controller?
A fighting game controller where the joystick lever is replaced by four buttons for up, down, left and right. It is also called an all-button or hitbox-style controller.
Why does a leverless controller need SOCD cleaning?
Because nothing stops you pressing left and right, or up and down, at the same time. The firmware has to turn that into one direction the game can use, such as neutral or the last one pressed.
How many pins does a leverless controller need?
One per button. Four directions plus eight attack buttons is twelve, and extras such as start and select add more. Give every button its own pin rather than a matrix.
Can I test GP2040-CE in Mokxi?
No. Mokxi runs Arduino sketches on its Pico model and does not model the Pico’s USB, so it cannot run GP2040-CE. You can test your wiring and your own sketch logic.
Keep going
Where the facts on this page come from
Build this for real
Open the editor, change a value and watch the number move with it. Nothing to install, and no account needed.