contro-max

Contro Max 🎮 ⌨️ 🚀

The package is ESM

Why Fork?

• Was not that complete
• Contro used e.key instead of e.code so your app/game won't work with different layouts
• Fixed bugs with keyboard and alt+tab
• [DX] Great typings support!
• And more...

MCRAFT.FUN is using this module!

Testing Input

• Keyboard: https://keycode.info – you need event.code
• Gamepad: https://gamepad-tester.com

Contro Max is a framework rather than library. The main goal is to give easiest way for handling all possible input types in web.

API

Features

• Handles annoying edge cases where key was unpressed while alt+tabing, but...

Usage

contro-max doesn't share concept of being flexible and doesn't provide abstractions that would allow you to craft custom inputs (but maybe you shouldn't?). Instead, we suggest should define so called schema of all commands

Define Controls

First of all, you need to create controls schema for your app/game:

export const controls = createControlsSchema({
    core: {
        openInventory: ["KeyE", "LB"] // Can also use mouse input like Mouse1 insdead of KeyE
    }
});

As you can see, schema is the object with event names and arrays: [KeyboardKey, GamepadButton].

Also, you can add options for the event (options we'll cover later):

{ openInventory: ["KeyE", "LB", { disabled: true, /* other options */ }] }

If your event doesn't have binding for Gamepad, just don't pass anything:

{ sayHello: ["Comma"] } // or
{ sayHello: ["Comma", { /* event specific options */ }] }

If your command doesn't have default keyboard binding:

{ sayHello: null }
// or if you have to specify options
{ sayHello: [null, { /* event specific options */ }] }
// with gamepad button specified
{ sayHello: [null, "LB", { /* event specific options */ }] }

Using Controls

Okay, when we defined schema, you can use it anywhere in your app for executing/listening to commands

Trigger Programmatically

There are two ways of triggering:

1. Obvious and recommended:

controls.trigger()
// this will fire trigger and then release events with the given command

1. Universal method (works not only with this library):

window.dispatchEvent(new KeyboardEvent("keydown", {
   code: "Escape"
}))

1. Elegant method:

controls.trigger("openInventory");

React

Without global state:

const DisplayControls: React.FC = () => {
   const {  } = useKeyboard(["space", "arrowKeys"], { preventDefault: true })
}

Key Groups

• WASD
• Digits – all digits usual and Numpad

Enablement

(experimental)

Contro max would fire events only when it actually sees the canvas.

Here is how it works:

You specify canvasElem as an option for your createControlsSchema. If you don't specify this feature won't and events will always fire skipping the check.

createControlsSchema start watching for the changes of document.body. When it detects change of its children (some root element is added or removed), the check is performed that element in center of the screen is canvasElem.

But with this approach you must ensure that all modals and menus are being showed in root of DOM (document.body). Most UI libraries does this for you (e.g. MUI).

Contro max doesn't rely on document.activeElement and instead would unlock controls only when

Notes

TODO

Odd Gamepads

Gamepads like this the most probably won't work at all. (use tester above) But if you're under Windows and OS sees gamepad as gamepad (not keyboard) or can remap buttons using TocaEdit in pair with vJoy, but it's quite not easy to do so I'll post instructions later here.

Similar Libraries

• https://www.npmjs.com/package/keyboardist
• Mousetrap - not that good
• cheet.js - dead