Standalone track. This tutorial is independent of the main cumulative chain (Sign-in → Achievements → Leaderboards → Game Saves → Lobby → MPA → Party → Capstone). You can read it before, after, or in parallel with that chain — it does not depend on a signed-in XBOX user or any PlayFab state.
A GameInputActionMap resource that bridges a Microsoft GameInput
gamepad into Godot's standard InputMap. By the end:
- The
godot_gameinputruntime polls the first connected gamepad every frame, with no manual_processcode in your scenes. - A
GameInputActionMapresource maps face buttons and thumbsticks to your project's actions (ui_accept,move_left,jump, …). - Anywhere in your gameplay code you keep using
Input.is_action_pressed("jump")— GameInput appears under the hood without your character controller knowing. - You react to hot-plug via the
GameInput.device_connected/device_disconnectedsignals.
When it works, a Sprite that uses move_left / move_right /
jump reacts to gamepad input even when the player's XBOX
controller would otherwise be routed through GameInput-only paths
(some Windows builds, all Microsoft GDK title-process builds).
- The
godot_gameinputaddon is enabled in Project Settings → Plugins (the addon installs aGameInputBootstrapautoload). - A scratch Godot project with a single scene to attach the mapper to. You do not need to have followed any tutorial in the main cumulative chain — GameInput is entirely independent of XBOX / PlayFab sign-in.
game_input/runtime/initialize_on_startupis set totrue. This defaults tofalse, so flip it explicitly in Project Settings → Game Input → Runtime (or callGameInput.initialize()yourself before the first mapper poll). The bootstrap autoload reads this on_ready.game_input/runtime/auto_pollistrue(the default; the bootstrap pumpsGameInput.poll()every process frame). Without auto-poll,GameInputMappercalls poll defensively per frame anyway — auto-poll is mostly a perf optimization when multiple consumers share state.- A wired or wireless XBOX controller (or other GameInput-compatible
gamepad) plugged into the dev PC. The action bridge is
GDScript-only on top of
GameInput— it works on any GameInput-supported device kind. - One-page primer on async patterns: Async patterns — GameInput is mostly synchronous, but the surrounding addon conventions still apply.
GameInput—is_initialized,poll,get_devices,get_connected_device_count, signalsdevice_connected/device_disconnected.GameInputActionMap— the typedResourceyou author in the inspector (or in code).GameInputBinding— one row per action / source pair.GameInputMapper— theNodethat polls and feedsInput.action_press/Input.action_releaseevery frame.GameInputDevice— wrapper exposingget_device_id,get_display_name, and theSRC_*constants.
GameInput vs. Godot's built-in joypad backend. Godot has its own joypad backend that delivers
InputEventJoypadButtonandInputEventJoypadMotion. GameInput is the Microsoft GDK runtime that exposes the same hardware through the XBOX-supported input stack. Use this tutorial when your project ships to Microsoft GDK targets (so the built-in backend may not see the controller) or when you want richer feedback like impulse triggers and per-motor rumble.
Open Project Settings → Input Map and add the actions you want to drive from the gamepad. For this tutorial:
| Action | Default event |
|---|---|
ui_accept |
Keyboard Enter (already defined by Godot) |
move_left |
Keyboard A |
move_right |
Keyboard D |
jump |
Keyboard Space |
You do not need to add gamepad events here. The mapper hands the
press / release through Input.action_press directly. (You can
keep keyboard events; the bridge is additive.)
One gotcha: if you also bind
ui_acceptto "Joypad Button A" in the Input Map, the built-in joypad backend will fire it too — the mapper detects this and skips its own synthetic event for that one binding so you don't double-fire. The polled state (Input.is_action_pressed("ui_accept")) is still refreshed each frame either way.
- In the FileSystem dock, right-click your
res://root and pick New Resource…. - Search for GameInputActionMap and create it. Save as
res://input/gamepad.tres. - With the resource selected, switch to the Inspector. The
bindingsfield is a typed array ofGameInputBinding. - Click the
+to add a binding for each row in this table:
action |
source |
is_axis |
axis_invert |
Notes |
|---|---|---|---|---|
ui_accept |
SRC_BTN_A |
false | false | A button. |
jump |
SRC_BTN_A |
false | false | Same source as ui_accept. |
move_left |
SRC_AXIS_LEFT_X |
true | true | Inverted so "stick left" reads as positive. |
move_right |
SRC_AXIS_LEFT_X |
true | false | Right is the native positive direction. |
dpad_up |
SRC_BTN_DPAD_UP |
false | false | If you've added it. |
For axis rows, leave deadzone at 0.2 and axis_threshold at
0.5 to start — those defaults match Godot's deadzone convention.
The bindings field is a real typed array, so you can also build
the map in code:
func _build_default_map() -> GameInputActionMap:
var map := GameInputActionMap.new()
var accept := GameInputBinding.new()
accept.action = &"ui_accept"
accept.source = GameInputDevice.SRC_BTN_A
map.add_binding(accept)
var jump := GameInputBinding.new()
jump.action = &"jump"
jump.source = GameInputDevice.SRC_BTN_A
map.add_binding(jump)
var left := GameInputBinding.new()
left.action = &"move_left"
left.source = GameInputDevice.SRC_AXIS_LEFT_X
left.is_axis = true
left.axis_invert = true
map.add_binding(left)
var right := GameInputBinding.new()
right.action = &"move_right"
right.source = GameInputDevice.SRC_AXIS_LEFT_X
right.is_axis = true
map.add_binding(right)
return mapEither path produces the same resource; the inspector path is better for designers, the code path is better for tests and for runtime remapping screens.
The mapper is a Node. The pattern is to add it once high up in
your scene tree (an autoload, or the root of your main scene) and
let every gameplay scene rely on standard Input calls below it.
The simplest approach: a one-line autoload.
# res://input/gamepad_autoload.gd
extends Node
func _ready() -> void:
var mapper := GameInputMapper.new()
mapper.name = "GamepadMapper"
mapper.action_map = preload("res://input/gamepad.tres")
add_child(mapper)Register it in Project Settings → Globals → Autoload:
| Path | Node Name |
|---|---|
res://input/gamepad_autoload.gd |
Gamepad |
That's it for the wiring. Every existing
Input.is_action_pressed("jump") call in your project now sees the
gamepad.
No change to gameplay code. The reason this tutorial is short is exactly because gameplay code stays oblivious:
extends CharacterBody2D
const SPEED := 200.0
const JUMP_VELOCITY := -400.0
func _physics_process(delta: float) -> void:
var direction := Input.get_action_strength("move_right") - Input.get_action_strength("move_left")
velocity.x = direction * SPEED
if Input.is_action_just_pressed("jump") and is_on_floor():
velocity.y = JUMP_VELOCITY
move_and_slide()Input.get_action_strength("move_right") returns the post-deadzone
strength fed in from the mapper, which lets analog stick movement
work without any extra logic.
For a single-player game, the mapper's default
target_kind_mask = KIND_GAMEPAD and target_device_id = -1 is
enough: it always uses the primary connected gamepad in
insertion order, so a controller plugged in mid-game is picked up
automatically.
For split-screen or per-player binding you need to pin each mapper
to a specific device id when its owner connects. Listen to
GameInput.device_connected:
extends Node
@export var _mappers: Array[GameInputMapper] = []
func _ready() -> void:
GameInput.device_connected.connect(_on_device_connected)
GameInput.device_disconnected.connect(_on_device_disconnected)
# Bind any devices that were already connected before _ready.
for device in GameInput.get_devices(GameInput.DEVICE_GAMEPAD):
_bind_device(device)
func _on_device_connected(device: GameInputDevice) -> void:
print("[Pad] connected: id=%d (%s)" % [device.get_device_id(), device.get_display_name()])
_bind_device(device)
func _on_device_disconnected(device_id: int) -> void:
print("[Pad] disconnected: id=%d" % device_id)
for mapper in _mappers:
if mapper.target_device_id == device_id:
mapper.target_device_id = -1 # fall back to primary
func _bind_device(device: GameInputDevice) -> void:
for mapper in _mappers:
if mapper.target_device_id == -1:
mapper.target_device_id = device.get_device_id()
returnThe two events are queued from the GameInput worker thread and
fire on the main thread during the next GameInput.poll() —
the device wrapper is safe to use from your handler.
Device ids are session-local and never recycled, so storing the id of "player 1's pad" in a dictionary is safe for the entire process lifetime.
When a build runs without a GameInput-capable host (for example a
non-Microsoft GDK Windows build that did not satisfy
GameInputCreate()), every GameInput call soft-fails into a safe
default and GameInput.is_initialized() returns false. Your
gameplay code keeps working off keyboard input; the mapper just
does nothing.
For a one-shot diagnostic in development:
func _ready() -> void:
if not GameInput.is_initialized():
push_warning("[Pad] GameInput runtime not available — gamepad input disabled.")
return
print("[Pad] %d gamepad(s) currently connected" % GameInput.get_connected_device_count())With one gamepad connected, running the scene prints:
[Pad] 1 gamepad(s) currently connected
Pressing the A button fires ui_accept (focused UI elements
react) and jump (the character jumps). Tilting the left stick
fires move_left / move_right with smooth analog strength
visible in Input.get_action_strength.
Common failures:
| Output | Diagnosis | Fix |
|---|---|---|
Single push_warning per missing action like [GameInputMapper] Action not found in InputMap: 'jump' |
The action name on a GameInputBinding does not exist in Project Settings → Input Map. |
Add the action, or fix the typo on the binding. |
| Action fires twice (e.g., your jump triggers a double-jump) | A native joypad event for the same button is bound in the Input Map AND the mapper is also firing. | Either remove the native joypad event for that action, or accept the mapper's automatic skip (it should detect this case — if it doesn't, file a bug). |
| Analog stick "snaps" to full strength at a small tilt | deadzone on the axis binding is too low. |
Raise deadzone to 0.2 or higher (the default). |
[Pad] GameInput runtime not available on a Microsoft GDK build |
GameInputCreate() failed at runtime. |
Check that the Microsoft GDK is installed on the target machine and the addon bin/ ships with the build. |
The end-state lives in the standalone GameInput sample at
sample/tutorial_gameinput/:
Layout note. The tutorial splits the work across an autoload (
res://input/gamepad_autoload.gd), a resource (res://input/gamepad.tres), and a gameplay scene that consumes the autoload. The sample collapses this into a singlemain.tscn
main.gdthat builds the action map in code (the Step 2 code path) and adds theGameInputMapperat scene_readyinstead of via autoload. Same wiring, fewer files — and it adds visible debug UI (device list, hot-plug log, live action strengths, jumping player) so you can see the bridge react.
-
Add rumble.
GameInput.set_vibration(device, low, high, lt, rt)takes the sameGameInputDevicewrappers the bridge uses. The GameInput addon doc covers the rumble patterns the addon supports. -
Per-player binding for split-screen. The hot-plug handler in Step 5 is the starting point — extend it to pin specific device ids to per-player
GameInputMappernodes. -
Wire GameInput into a signed-in XBOX session. If you also built through the main cumulative chain (signs in, lobbies, Party, MPA), the capstone integration tech demo is the natural place to drop the gamepad autoload alongside the identity / lobby / Party panels.
-
Reference:
GameInput,GameInputActionMap,GameInputBinding,GameInputMapper,GameInputDevice