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.
0.2.0 - 2026-11-05 #
Requires just_gamepads ^0.2.0, whose stick clicks are GamepadButton.leftStickPress / rightStickPress; the control paths (<Gamepad>/leftStickPress, …) are unchanged. Adds meta (for @internal). Saved data is unchanged: .input.json files, their keys and values, and players' saved bindings read and write as before.
Breaking #
- Players are an extension.
InputService.playersandInputService.actionsForare nowInputServicePlayers.players/actionsFor, exported byjust_inputs.dart: calls read the same (service.players,service.actionsFor(0)), but a library that re-exportsjust_inputswithshowmust showInputServicePlayers. The manager is made the first timeplayersis asked for;actionsFormakes none.PlayerInputManager's constructor is private, andassetLoaded/afterUpdateare gone: it hears the service through the new hooks. InputService.overrideStore→PlayerInputManager.overrideStore(service.players.overrideStore).InputService.releaseKeyboard()→releaseHeld(), which lets go of the mouse buttons held too.InputEvent<T>→InputNotifier<T>, and itsemit→notify.InputAction.isPressed()andisInProgress()are getters:isPressed,isInProgress.readButton()is removed: useisPressed.InputAction.defis read-only.InputActionMap.enabled, a field anyone could set, isisEnabled, a getter: switch a map withenable()/disable().- Device states are named for their devices:
KeyboardState→KeyboardDeviceState,MouseState→MouseDeviceState,TouchState→TouchscreenDeviceState,OnScreenState→OnScreenDeviceState.MouseDeviceState.travelled/TouchscreenDeviceState.travelled→traveled. - American spelling in names:
OnScreenStickPainter(centre:)/.centre→center;PointerLock.lock(pinToCentre:)→pinToCenter:,PointerLock.pinsToCentre→pinsToCenter,PointerLockPlatform.lock(pinToCentre:)→pinToCenter:. The Windows plugin's channel argument changes with it (pinToCenter), so the Dart side and the plugin must be of the same version. StatefulDevice.live/appliedare read-only.InputDevice.settingsis the settings (InputSettingsDef), not a function returning them; what the service sets is internal.CompositeKinds.parts,CompositeKinds.labelandCompositeKinds.allare removed: a composite's parts, label and value are in the newStepCatalog(StepCatalog.composite(type)), which also knows composites a game registers.CompositeKindskeeps the four saved type names.BindingOverrideskeeps an unmodifiable copy of the paths it is given, so its constructor is no longerconst:const BindingOverrides()→BindingOverrides.none.- Runtime plumbing is
@internal:InputService.forget,InputActions.onDevice/tick,InputAction.evaluate/tick,StatefulDevice.applyNext,InputDevice.sink. GamepadDevice.releaseAllandOnScreenDevice.releaseAllare removed; nothing called them (a pad reports its own state, an on-screen control gets its finger's cancel).ParamInfo,StepInfoandParamKindmoved with the descriptions to the model (still exported byjust_inputs.dart).- A pressPoint an interaction sets for itself may no longer be 0 (its range is 0.01 to 1): 0 left the action pressed at rest.
Added #
InputService.listenAssets,listenDisposeandisDisposed: the hooks the player manager hears the service by.StepCatalogandCompositeInfo: what every interaction, processor and composite is — name, label, settings, a composite's parts and value — for validation and the editor.InputInteractions,InputProcessorsandInputCompositesregister into it, and each has anunregisterthat puts a replaced built-in back.StepInfo.rangesnames a step's min/max pairs;StepInfo.param;ParamInfo.accepts.InputSettingsDef.paramsandInputSettingsDef.ranges: each asset setting as aParamInfowith its range, and the dead zones' min/max pairs.InputSettingsDef.valueOf(key).InputNames: the rule a map, action or on-screen control name follows (InputNames.isValid).validateAssetchecks steps and settings. Warnings:unknownInteraction,unknownProcessor,unknownParam. Errors:badParam(a setting of the wrong kind or out of its range),badRange(a clamp's, normalize's or dead zone's min not below its max, an unset end read from the asset's settings),badSetting(an asset setting out of its range).AssetIssuesays where, to the step:stepKind(StepKind.interactionorprocessor),stepIndexandparam. A composite part's issues carry its action's id.PlayerInputManager.isEmptyandcount.RebindingOperation.dispose. An operation that is listening is cancelled by its dispose and by its service's.KeyboardDevice.ignoresPadKeys, whichattachGamepadssets: see Fixed.InputSubscription.none();BindingOverrides.none.InputTester.keyDown/keyUptake alogicalKey:, andInputTester.anyLogicalKeyis the one they send otherwise.public_member_api_docsis on: every public name is documented.- A layout guard,
test/library_layout_test.dart, and the layout in CONTRIBUTING.
Changed #
lib/srcis laid out by feature, in layers, with no import loop between features:paths,pointer→model→devices→runtime→players,rebinding,display→widgets. Each folder has one barrel;just_inputs.dartexports the barrels. The control catalogue moved tomodel/,BindingOverridesandapplyOverridestomodel/,InputOverrideStoretoplayers/. Nothing outside the package importssrc/.- A device plugged in or pulled out, and a change to a live copy's devices, scheme or overrides, take effect at the next update: a pad pulled out while its button is held is released in that update's frame (
wasReleasedThisFrame()), as polling expects. - What a file is read into is unmodifiable: lists, settings maps,
InputActions.overrides,DeviceList.devices. - Callback lists are replaced rather than changed: a callback that listens or cancels while they are called takes effect from the next time, and an update copies nothing.
InputActions.allActionsis aList, kept rather than built at each update;PlayerInputManager.playersis kept, sorted, rather than sorted at each call.- Fewer allocations per update: no copies of the device and instance lists, one host per binding and per interaction, no closure per deadline, one parts map per composite binding, no set per pad snapshot. A queued change is taken from a queue in constant time.
- The Windows plugin: its googletest runner builds (
set(include_just_inputs_tests TRUE)in an app'swindows/CMakeLists.txt); its target name and switch held a slash, so it never could. pointer_lock_platform.dartis formatted.
Fixed #
rebindPlayer: the control just bound no longer performs its action at the next update. A control newly bound while it is held waits to be let go, so rebindingui/submitno longer submits.InputActionAsset.parseandfromJsonthrowFormatExceptionand nothing else for a broken file — a name no enum has, a value of the wrong kind, a list too short — naming the field. It used to throwArgumentError,TypeErrororRangeError.- Closing a screen while a
RebindButtonlistened removed its overlay twice ("An OverlayEntry should be removed only once"). - An asset
validateAssetpassed could throw or misbehave at run time: aclampwith min above max threw at every update (it now orders its bounds), a setting of the wrong kind threw fromloadAsset(it now reads as unset), and a dead zone whose max was not above its min turned a stick around and doubled it (it is now a step). releaseHeld(wasreleaseKeyboard) lets go of the mouse buttons too: one held as the window lost focus stayed held.- A device removed with changes queued, and added back, replayed them out of order; it now starts level.
InputService.disposetwice threw; after it, a late key event reached a disposed notifier.attachGamepadsthat finished afterdisposeadopted the pads into the disposed service.- A rebind abandoned without
cancelkept every action suspended and the keyboard taken;rebindPlayernow disposes its operation when it ends. - While the pads are read, the key events Android sends for a pad (its buttons, and arrow keys made up for a stick pushed over) no longer press the keyboard's keys and make the keyboard the last device used. A keyboard's and a TV remote's keys still count.
- Two fingers on a precision touchpad now turn
<Mouse>/scroll, as the wheel does; Flutter sends them as pan-and-zoom events, which were passed over. - The Windows plugin hands raw mouse input back to whoever had it when the lock lets go, rather than taking it from the whole process, and leaves it alone if something else took it meanwhile.
InputTestertaught the keyboard that every key's face was "A"; its keys now teach no face unless given one.
0.1.1 - 2026-10-16 #
- The pubspec declares all six platforms. pub.dev listed 0.1.0 as Windows only, reading its platforms from the pointer-lock plugin, which is Windows only; the input system is Dart and runs on Android, iOS, Linux, macOS, Windows and the web (JavaScript and WebAssembly). Pointer lock is still Windows only: elsewhere
PointerLock.isSupportedis false and nothing happens. The library's code is unchanged. - An example,
example/example.dart: a dot moved by amoveaction (WASD, the arrow keys or a stick) that bounces onjump, from an input asset that passesvalidateAsset(a test keeps it so). - just_gamepads package is upgraded to 0.1.1
0.1.0 - 2026-10-04 #
A new input system, replacing the old action layer outright.
- Assets.
InputActionAsset, a.input.jsonfile (formatjust_inputs, version 3): maps, actions (button / axis / vector 2, pass-through), bindings as control paths (<Keyboard>/space), composites (2D vector, 1D axis, one and two modifiers), interactions, processors, control schemes, on-screen controls and player settings. Stable ids for everything a player can rebind.validateAssetandfindBindingConflicts(join actions excepted: they listen to other devices). - Runtime.
InputServicereplacesInputManagerandInputActionResolver: one device per pad, physical keys, events queued and replayed in order atupdate(now)on the game's clock; live state for rebinding, applied state for actions.InputActionsper set of devices; polling and callbacks;enable(ignoreHeld:). Registries for composites, interactions and processors. - Players.
PlayerInputManager: first to play is player 1, join by action (hold to join, quick press to switch while alone), lost and regained devices, per-player overrides throughInputOverrideStore. - Rebinding.
RebindingOperation,rebindPlayer,KeyboardCaptureHook. - Widgets.
OnScreenControls(replacesVirtualJoystickandOnScreenActionButtons),BindingLabel,RebindButton,RebindList;BindingDisplayandGamepadGlyphsfor prompts. - Pointer lock (Windows):
InputService.pointerLockhides the cursor, holds it in the window and feeds the mouse's raw movement to the mouse, through a Windows plugin in this package (it wasjust_pointer_lock).lockPointerOnClicktakes hold on a click on the game (GameWidget, and the editor's play-test); Escape lets go whatever widget has the keyboard (PointerLock.releaseKeys), as does the window going behind. - Raw mouse movement.
MouseDevice.injectDeltaadds movement from outside Flutter's pointer events (a locked pointer's raw input).MouseDevice.relativeModeignores the pointer events' own movement while the pointer is locked, so nothing counts twice.InputService.attachRawMouse(deltas, relative:)wires a stream and a lock flag to both. - A frame at a time.
FrameMotionreads an action's movement controls (the mouse's delta and wheel, a finger's drag) once per rendered frame: everything that moved since the lasttake, however many fixed updates ran in between, through the bindings' and the action's processors. Nothing moved while the action is off, or while a rebind is listening, counts. Controls that add up say so (InputControl.accumulates) and read their running total withInputControl.readTotal. - Look.
LookInput.read(dt)turns the two look actions into a frame's yaw and pitch in radians: movement timesLookSettings.radiansPerPixel, plus stick deflection times degrees per second timesdt.LookActions.addToadds them to an asset:look(<Mouse>/delta, optionally<Touchscreen>/delta) andlookStick(<Gamepad>/rightStick, optionally an on-screen stick), each binding in its device's schemes. - Editor. The Input Actions editor is not in this package. It moved to its own package,
just_input_editor, the visual side of this one, along with the module that puts it injust_game_engine_editor.package:just_inputs/editor.dartis gone, and so isdart:io: the runtime runs on the web. - Testing.
package:just_inputs/testing.dart:FakeGamepadSource,InputTester.
Removed: InputManager, InputActionResolver, InputActionSet, InputBinding, Vector2Binding, ControllerInput, VirtualJoystick, OnScreenActionButtons, the old GamepadButton/GamepadAxis copies (use just_gamepads' or the control paths).
153 tests (the editor's 59 went with it to just_input_editor).