just_inputs 0.2.0
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
holdand 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.