Skip to main content

just_inputs 0.2.0 copy "just_inputs: ^0.2.0" to clipboard
just_inputs: ^0.2.0 copied to clipboard

Input actions for Flutter games: keyboard, mouse, gamepads and touch, with local multiplayer, player rebinding and on-screen controls.

just_inputs #

Input for Flutter games: named actions bound to keyboard, mouse, gamepads and touch, read the same way whatever the device — plus local multiplayer, player rebinding and on-screen controls. Modelled on Unity's Input System.

final input = InputService()
  ..loadAsset(InputActionAsset.parse(await rootBundle.loadString('assets/input/game.input.json')));
await input.attachGamepads();

// Once per fixed step, with your game's clock:
input.update(now);

if (input.actions.action('player/jump').wasPressedThisFrame()) jump();
final move = input.actions.action('player/move').readVector2(); // y down

The pieces #

Asset (InputActionAsset, a .input.json file) Everything below, saved together. Immutable; the editor and the runtime both read it.
Map Actions switched on and off together — player while playing, ui in menus. Each says whether it is on at start.
Action Something the player does: a button, an axis or a vector2. The strongest binding drives it (or, with pass-through, the latest).
Binding A control path, <Keyboard>/space, <Gamepad>/leftStick, <OnScreen>/jump — or a composite: 2DVector (WASD), 1DAxis (Q/E), OneModifier/TwoModifiers (Shift + E).
Interaction How a press becomes the action: press, hold, tap, slowTap, multiTap. Phases: started, performed, canceled.
Processor A change on the way: dead zones, normalize, invert, scale, clamp.
Scheme A way of playing — Keyboard & Mouse, Gamepad, Touch — and its bindings, by group.

Keys are bound by position (PhysicalKeyboardKey), so WASD stays under the left hand on AZERTY. Labels are learned from the player's own presses: BindingDisplay(keyboard: input.keyboard).

Every event is queued as it arrives and replayed in order at update(now), so a press and a release between two updates is still a press. A device plugged in or pulled out, and a player's bindings changed, take effect at the next update too. Input time is the clock you pass — never the wall clock.

InputActionAsset.parse throws a FormatException — and only that — for a file it cannot read, a field of the wrong kind included. validateAsset(asset) lists what is wrong with one that reads: names, paths, unknown interactions and processors, settings of the wrong kind or out of their range, a clamp or dead zone whose min is not below its max. An asset with no errors loads and runs without throwing.

Reading actions #

final jump = actions.action('player/jump');
jump.isPressed;               jump.wasPressedThisFrame();  jump.wasReleasedThisFrame();
jump.phase;                   jump.wasPerformedThisFrame();
jump.onPerformed((a) => ...); // synchronous: see below
actions.map('player')!.disable();
actions.map('player')!.enable(ignoreHeld: true); // the press that closed the menu does not jump

Callbacks run synchronously: at update(now), and also when a map is switched on or off, an asset is loaded, or actions resume after a rebind.

Players #

input.players.start();
input.players.joined.listen((p) => spawnCharacter(p.index));
input.actionsFor(1)?.action('player/jump');

players and actionsFor come with just_inputs.dart (the InputServicePlayers extension). A one-player game never needs players.start(): actionsFor(0) is then the shared input.actions.

With players.start():

  • player 1 is whoever plays first, with whatever they touch;
  • a device nobody uses joins as the next player when a join action is performed on it — give it a hold and a quick press means something else;
  • alone, a quick press on a device nobody uses moves player 1 onto it;
  • a player whose pad is pulled out is lost until it (or another pad) comes back: deviceLost, deviceRegained, dropLost.

The asset's players block sets the most players and the join actions.

Rebinding #

final result = await rebindPlayer(player, bindingId,     // listens, keeps, saves; swaps a clash
    onStart: (op) => cancelOnBack = op.cancel);
player.resetOverrides();

Rebinding hears the next control the moment it changes — it works while the game is paused — takes keys before any focused widget (so Escape and the arrows can be bound; Escape alone cancels), and ignores whatever was already held. The control just bound does nothing until it is let go: binding Enter in a menu does not also press OK. Until it hears a control every action is suspended, so cancel a rebind nobody waits for any more (onStart hands you the operation). Overrides are stored per player through input.players.overrideStore (an InputOverrideStore), apart from the asset. RebindButton and RebindList are ready-made widgets.

On-screen controls #

The asset's onScreen list places buttons and sticks (fixed, or floating under the thumb) relative to the screen. OnScreenControls(input: input) draws them and feeds <OnScreen>/… — they are controls like any other, bound in the same actions.

Look #

A camera that turns reads look once per rendered frame, not once per fixed step: <Mouse>/delta read per step judders when the frame rate and the step rate differ. Look comes as two actions, because a mouse held still turns nothing while a stick held still keeps turning:

final asset = LookActions.addTo(myAsset); // `look` (mouse) and `lookStick` (right stick)
final look = LookInput(input.actionsFor(0)!,
    settings: const LookSettings(radiansPerPixel: 0.0025, yawDegreesPerSecond: 180));

// Every rendered frame:
final turn = look.read(dt); // radians: dx yaw (right +), dy pitch (down +)

FrameMotion is the per-frame read underneath, for any movement action (a wheel zoom, say).

Pointer lock #

For mouse look, input.pointerLock hides the cursor, holds it in the window and streams the mouse's raw movement — never accelerated, never stopped by the edge of the screen — into the mouse, so the look actions read it like any other movement (the pointer events' own is ignored while it holds). A game that looks with the mouse asks for it on a click:

input.lockPointerOnClick = true; // GameWidget, and the editor's play-test

Escape lets go, whatever widget has the keyboard (PointerLock.releaseKeys), and so does the window going behind another; it takes hold again on the next click. Or call input.pointerLock.lock() (pinToCenter: false keeps the hidden cursor anywhere in the window) and unlock() yourself. Windows today: elsewhere isSupported is false and nothing happens. Raw movement from anywhere else goes in through input.attachRawMouse(deltas, relative:).

Gamepads #

await input.attachGamepads() reads pads through just_gamepads, one device each. While it does, the key events Android also sends for a pad (its buttons, and arrow keys made up for a stick pushed over) are the pad's, not the keyboard's. When the window loses the keyboard, input.releaseHeld() lets go of every key and mouse button held; GameWidget calls it.

The editor #

The Input Actions editor is its own package, just_input_editor, the visual side of this one. It edits the asset this package runs: maps, actions and bindings; Pick, or Listen for the next key or button; interactions, processors, schemes and players; a keyboard, a gamepad and a phone to see and click bindings on; and a live test. Its module puts it in just_game_engine_editor.

A game imports just_inputs.dart (through just_game_engine), never testing.dart (FakeGamepadSource, InputTester) and never just_input_editor.

1
likes
150
points
408
downloads

Documentation

API reference

Publisher

verified publisherjustunknown.com

Weekly Downloads

Input actions for Flutter games: keyboard, mouse, gamepads and touch, with local multiplayer, player rebinding and on-screen controls.

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#input #gamepad #keyboard #gamedev #game

License

BSD-3-Clause (license)

Dependencies

flutter, just_gamepads, meta

More

Packages that depend on just_inputs

Packages that implement just_inputs