Gameplay
Input
Read named actions from keyboard, mouse, gamepads and touch through engine.input, with local multiplayer, rebinding and on-screen controls.
engine.input is an InputService from just_inputs. Your game reads named actions such as jump and move, and an input asset binds them to keyboard keys, mouse buttons, gamepads and touch controls. Gameplay code never asks which device was used.
How input works
| Piece | What it is |
|---|---|
| Asset | a .input.json file (InputActionAsset) holding everything below |
| Map | actions switched on and off together, such as player while playing and ui in menus |
| Action | something the player does: a button, an axis or a vector2 |
| Binding | a control path such as <Keyboard>/space or <Gamepad>/leftStick, or a composite such as 2DVector for WASD |
| Interaction, processor | how a press becomes the action (press, hold, tap) and changes on the way (dead zones, invert, scale) |
| Scheme | a way of playing (keyboard and mouse, gamepad, touch) and its bindings |
Keys are bound by position, so WASD stays under the left hand on an AZERTY keyboard. GameWidget sends keys and pointers to engine.input, and the engine updates it once per fixed step, and every frame while paused so menus and rebinding keep working.
The input asset
Actions live in an asset, not in code. The Input Actions editor (the just_input_editor plugin, from the editor's Asset Store) writes these files; you can also write them by hand. List the folder under flutter: assets: in pubspec.yaml.
{
"format": "just_inputs",
"version": 3,
"nextId": 11,
"name": "game",
"maps": [
{
"id": "m1",
"name": "player",
"actions": [
{
"id": "a1", "name": "move", "type": "vector2",
"bindings": [
{
"id": "b1", "composite": "2DVector",
"parts": [
{ "id": "b2", "part": "up", "path": "<Keyboard>/w" },
{ "id": "b3", "part": "down", "path": "<Keyboard>/s" },
{ "id": "b4", "part": "left", "path": "<Keyboard>/a" },
{ "id": "b5", "part": "right", "path": "<Keyboard>/d" }
]
},
{ "id": "b6", "path": "<Gamepad>/leftStick" }
]
},
{
"id": "a2", "name": "jump", "type": "button",
"bindings": [
{ "id": "b7", "path": "<Keyboard>/space" },
{ "id": "b8", "path": "<Gamepad>/buttonSouth" }
]
}
]
},
{
"id": "m2",
"name": "ui",
"actions": [
{
"id": "a3", "name": "pause", "type": "button",
"bindings": [
{ "id": "b9", "path": "<Keyboard>/escape" },
{ "id": "b10", "path": "<Gamepad>/start" }
]
}
]
}
]
}To build an asset in code, import package:just_inputs/just_inputs.dart for the asset model (InputActionDef, ControlBindingDef and the rest) and validation; the engine re-exports only what a game uses at run time.
Load and read actions
Load the asset after engine.initialize(); until then no action is bound. InputSystem, a default system, then copies each player's player-map actions onto every entity with an InputComponent, by action name.
import 'package:flutter/services.dart' show rootBundle;
import 'package:just_game_engine/just_game_engine.dart';
Future<void> loadInput(Engine engine) async {
final text = await rootBundle.loadString('assets/input/game.input.json');
engine.input.loadAsset(InputActionAsset.parse(text));
// Players' saved bindings, so they apply from the start.
await engine.input.players.preloadOverrides();
// Gamepads are opt-in: attaching them opens platform channels.
await engine.input.attachGamepads();
// Actions outside the player map are read from the service. Input keeps
// updating while the engine is paused, so this can also resume it.
engine.input.actions.action('ui/pause').onPerformed((_) {
engine.isPaused ? engine.resume() : engine.pause();
});
}
/// Moves every entity that has an InputComponent, top-down style.
class WalkSystem extends System {
static const double speed = 240;
// After InputSystem (100) has copied the actions in.
@override
int get priority => SystemPriorities.playerControl;
@override
List<Type> get requiredComponents => [InputComponent, VelocityComponent];
@override
void update(double deltaTime) {
forEach((entity) {
final input = entity.getComponent<InputComponent>()!;
final velocity = entity.getComponent<VelocityComponent>()!.velocity;
final move = input.vector('move'); // y is down, like the world
velocity.x = move.dx * speed;
velocity.y = move.dy * speed;
});
}
}InputComponent reads player 1 by default; InputComponent(playerIndex: 1) reads player 2 and playerIndex: -1 reads every device at once.
| Method | Returns |
|---|---|
vector('move') | a vector action's value as an Offset, y down |
axis('throttle') | how far an axis or button action is pushed |
isDown('jump') | whether a button is held |
wasPressed('jump') | whether it went down this step (true for one step only) |
wasReleased('jump') | whether it was let go this step |
wasPerformed('jump') | whether the action completed this step, for example a hold |
Outside the ECS, read an action by its map/name path: engine.input.actions.action('player/jump') has isPressed, wasPressedThisFrame(), readVector2(), readAxis() and the callbacks onStarted, onPerformed and onCanceled. Switch a whole map off for a menu with engine.input.actions.map('player')!.disable() and back on with enable().
Gamepads
Gamepads are opt-in: call await engine.input.attachGamepads() once. Bind them with paths such as <Gamepad>/leftStick and <Gamepad>/buttonSouth, and list the connected pads with engine.input.gamepads. On the web, gamepads work in JavaScript and WebAssembly builds once a button is pressed, because browsers hide pads until then.
Local multiplayer
engine.input.players is a PlayerInputManager. A single-player game can leave it off and read the shared actions. Call start() and players come and go as the asset's players block says, for example "players": {"max": 2, "joining": "onJoinAction", "joinActions": ["player/join"]}:
- 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 the join action a hold, so a quick press can mean something else);
- a player whose pad is pulled out is lost until it, or another pad, comes back (
deviceLost,deviceRegained,dropLost).
void startCoop(Engine engine) {
final players = engine.input.players;
players.joined.listen((player) {
engine.world.createEntityWithComponents([
TransformComponent(),
VelocityComponent(),
InputComponent(playerIndex: player.index),
Rectangle2DComponent(width: 32, height: 48),
], name: 'Player ${player.index + 1}');
});
players.start();
}players[1] is player 2's PlayerInput, or null while nobody is playing as them, and engine.input.actionsFor(1) is their live actions. Set players.joiningEnabled = false to stop new players joining, for example while paused.
Rebinding
rebindPlayer(player, bindingId) listens for the next control the player touches, keeps it and saves it, swapping with any binding it clashes with. It works while the game is paused, takes keys before any focused widget, and Escape alone cancels. player.resetOverrides() goes back to the asset's bindings. The control just bound waits to be let go before it acts, so the key that finished a rebind does not also jump.
The engine saves each player's bindings in its own settings store (CacheInputOverrideStore), apart from the cache's entries, so engine.cache.clearAll() leaves them alone. Call engine.input.players.preloadOverrides() after loadAsset, as above, to apply them at the next start. A PlayerInput exists once its player has joined, so start the player manager when your game offers rebinding.
On-screen controls
The asset's onScreen list places touch buttons and sticks relative to the screen, for example {"id": "jump", "kind": "button", "anchor": [0.8, 0.6], "label": "A"}. anchor runs from -1 to 1 on each axis like Flutter's Alignment, and size is a share of the screen's shorter side. A stick's mode is fixed or floating (under the thumb, inside its region). Bind them like any other control: <OnScreen>/jump.
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_engine/widgets.dart';
Widget gameScreen(Engine engine) => GameWidget(
engine: engine,
overlay: Positioned.fill(
// Shown on phones and tablets; OnScreenVisibility.always shows them
// everywhere.
child: OnScreenControls(input: engine.input),
),
);
/// A controls page: each action with a button to rebind it.
Widget controlsPage(Engine engine) {
final player = engine.input.players[0];
if (player == null) return const Text('Press any key to join.');
return RebindList(player: player, maps: const ['player']);
}widgets.dart also has RebindButton, RebindRow and BindingLabel for building your own rebinding screen.
Mouse look and pointer lock
For mouse look, set engine.input.lockPointerOnClick = true. GameWidget then takes hold of the pointer on a press on the game: the cursor hides, stays in the window, and raw mouse movement feeds the mouse device. Escape lets go, as does the window going behind another, and the next click takes hold again. You can also call engine.input.pointerLock.lock() and unlock() yourself. Pointer lock works on Windows today; elsewhere pointerLock.isSupported is false and nothing happens.
A camera should read look input once per rendered frame rather than once per fixed step. LookActions.addTo(asset) adds a look action for the mouse and lookStick for the right stick, and LookInput(engine.input.actionsFor(0)!).read(dt) returns the turn in radians.