GMR::Input

January 10, 2026 · View on GitHub

GMR::Input

Keyboard, mouse, and gamepad input handling.

Functions
- action_down?
- action_pressed?
- action_released?
- char_pressed
- clear_mappings
- current_context
- has_context?
- input
- input_context
- key_down?
- key_pressed
- key_pressed?
- key_released?
- map
- mouse_down?
- mouse_pressed?
- mouse_released?
- mouse_wheel
- mouse_world_x
- mouse_world_y
- mouse_x
- mouse_y
- off
- on
- pop_context
- push_context
- set_context
- unmap

Functions

mouse_x

Get the mouse X position in virtual resolution coordinates. Automatically accounts for letterboxing when using virtual resolution.

Returns: Integer - Mouse X position

Example:

x = GMR::Input.mouse_x

mouse_y

Get the mouse Y position in virtual resolution coordinates. Automatically accounts for letterboxing when using virtual resolution.

Returns: Integer - Mouse Y position

Example:

y = GMR::Input.mouse_y

Get the mouse X position in world coordinates using the current camera. Converts screen mouse position to world space using the camera's projection. If no camera is active, returns the screen position divided by 100 (default PPU).

Returns: Float - Mouse X position in world units

Example:

world_x = GMR::Input.mouse_world_x

mouse_world_y

Get the mouse Y position in world coordinates using the current camera. Converts screen mouse position to world space using the camera's projection. If no camera is active, returns the screen position divided by 100 (default PPU).

Returns: Float - Mouse Y position in world units

Example:

world_y = GMR::Input.mouse_world_y

mouse_down?

Check if a mouse button is currently held down.

Parameters:

Name	Type	Description
`button`	`Symbol, Integer`	The button to check (:left, :right, :middle, or constant)

Returns: Boolean - true if the button is held

Example:

if GMR::Input.mouse_down?(:left)
  player.aim
end

mouse_pressed?

Check if a mouse button was just pressed this frame.

Parameters:

Name	Type	Description
`button`	`Symbol, Integer`	The button to check (:left, :right, :middle, or constant)

Returns: Boolean - true if the button was just pressed

Example:

if GMR::Input.mouse_pressed?(:left)
  player.shoot
end

mouse_released?

Check if a mouse button was just released this frame.

Parameters:

Name	Type	Description
`button`	`Symbol, Integer`	The button to check (:left, :right, :middle, or constant)

Returns: Boolean - true if the button was just released

Example:

if GMR::Input.mouse_released?(:left)
  bow.release_arrow
end

mouse_wheel

Get the mouse wheel movement this frame. Positive values indicate scrolling up/forward, negative values indicate scrolling down/backward.

Returns: Float - Wheel movement amount

Example:

zoom += GMR::Input.mouse_wheel * 0.1

key_down?

Check if a key is currently held down. Accepts a single key or an array of keys (returns true if any key in the array is held).

Parameters:

Name	Type	Description
`key`	`Symbol, Integer, Array`	The key(s) to check (:space, :a, :left, etc.)

Returns: Boolean - true if the key (or any key in array) is held

Example:

if GMR::Input.key_down?([:a, :left])  # Either key works
  player.move_left
end

key_pressed?

Check if a key was just pressed this frame. Accepts a single key or an array of keys (returns true if any key in the array was just pressed).

Parameters:

Name	Type	Description
`key`	`Symbol, Integer, Array`	The key(s) to check

Returns: Boolean - true if the key (or any key in array) was just pressed

Example:

if GMR::Input.key_pressed?(:space)
  player.jump
end

key_released?

Check if a key was just released this frame. Accepts a single key or an array of keys (returns true if any key in the array was just released).

Parameters:

Name	Type	Description
`key`	`Symbol, Integer, Array`	The key(s) to check

Returns: Boolean - true if the key (or any key in array) was just released

Example:

if GMR::Input.key_released?(:shift)
  player.stop_running
end

key_pressed

Get the key code of the last key pressed this frame. Useful for text input or detecting any key press.

Returns: Integer, nil - Key code, or nil if no key was pressed

Example:

key = GMR::Input.key_pressed
  if key
    puts "Key code: #{key}"
  end

char_pressed

Get the Unicode character code of the last character pressed this frame. Useful for text input fields. Returns the character, not the key code.

Returns: Integer, nil - Unicode character code, or nil if no character was pressed

Example:

char = GMR::Input.char_pressed
  if char

map

Map an action name to input bindings. Supports two forms: Traditional form maps a single action to keys directly. Block form allows defining multiple actions with a DSL.

Parameters:

Name	Type	Description
`action`	`Symbol`	(optional) The action name for traditional form
`keys`	`Symbol, Array`	(optional) Key(s) to bind for traditional form

Returns: Module - self for chaining

Example:

# Block DSL form
  GMR::Input.map do |i|
    i.action :jump, key: :space
    i.action :attack, keys: [:z, :x], mouse: :left
  end

unmap

Remove an action mapping by name.

Parameters:

Name	Type	Description
`action`	`Symbol`	The action name to remove

Returns: Module - self for chaining

Example:

GMR::Input.unmap(:jump).unmap(:attack)

clear_mappings

Remove all action mappings.

Returns: Module - self for chaining

Example:

GMR::Input.clear_mappings.map(:new_action, :space)

action_down?

Check if a mapped action is currently active (any bound input is held).

Parameters:

Name	Type	Description
`action`	`Symbol`	The action name to check

Returns: Boolean - true if the action is active

Example:

if GMR::Input.action_down?(:move_left)
  player.x -= speed
end

action_pressed?

Check if a mapped action was just triggered this frame.

Parameters:

Name	Type	Description
`action`	`Symbol`	The action name to check

Returns: Boolean - true if the action was just triggered

Example:

if GMR::Input.action_pressed?(:jump)
  player.jump
end

action_released?

Check if a mapped action was just released this frame.

Parameters:

Name	Type	Description
`action`	`Symbol`	The action name to check

Returns: Boolean - true if the action was just released

Example:

if GMR::Input.action_released?(:charge_attack)
  player.release_charge
end

on

Register a callback for an action. The callback fires when the action reaches the specified phase. Returns an ID for later removal with off.

Parameters:

Name	Type	Description
`action`	`Symbol`	The action name to listen for
`when`	`Symbol`	(optional, default: :pressed) Phase: :pressed, :down, or :released
`context`	`Object`	(optional) Object to use as self in the callback block

Returns: Integer - Callback ID for later removal

Example:

# With phase and context
  id = GMR::Input.on(:attack, when: :released, context: player) do
    release_charge_attack
  end
  GMR::Input.off(id)  # Remove later

off

Remove input callback(s). Pass an ID to remove a specific callback, or an action name to remove all callbacks for that action.

Parameters:

Name	Type	Description
`id_or_action`	`Integer, Symbol`	Callback ID or action name

Returns: nil

Example:

GMR::Input.off(:jump)        # Remove all :jump callbacks

push_context

Push a named input context onto the stack. Actions defined in this context become active. Previous contexts remain on the stack.

Parameters:

Name	Type	Description
`name`	`Symbol`	The context name to push
`blocks_global`	`Boolean`	(optional) If true, global actions are blocked while this context is active

Returns: Module - self for chaining

Example:

GMR::Input.push_context(:pause, blocks_global: true)
  # :pause actions active, global game actions blocked

pop_context

Pop the current input context from the stack, returning to the previous context.

Returns: Module - self for chaining

Example:

GMR::Input.pop_context  # Return to previous context

set_context

Replace the entire context stack with a single context. Clears the stack and sets the named context as the only active context.

Parameters:

Name	Type	Description
`name`	`Symbol`	The context name to set

Returns: Module - self for chaining

Example:

GMR::Input.set_context(:gameplay)

current_context

Get the name of the current active input context.

Returns: Symbol, nil - Current context name, or nil if no context is active

Example:

context = GMR::Input.current_context

has_context?

Check if a named input context exists (has been defined).

Parameters:

Name	Type	Description
`name`	`Symbol`	The context name to check

Returns: Boolean - true if the context exists

Example:

if GMR::Input.has_context?(:menu)
  GMR::Input.push_context(:menu)
end

input

Define global input actions using a verb-style DSL. Actions defined here are always available regardless of context.

Returns: nil

Example:

input do |i|
  i.jump :space
  i.move_left [:a, :left]
  i.attack :z, mouse: :left
end

input_context

Define input actions for a named context. Context-specific actions are only active when that context is pushed onto the stack.

Parameters:

Name	Type	Description
`name`	`Symbol`	The context name

Returns: nil

Example:

input_context :menu do |i|
  i.confirm :enter
  i.cancel :escape
  i.navigate_up :up
  i.navigate_down :down
end

Back to Input | Documentation Home