Mouse

Category: Listener Tier: Basic

Purpose

Detects mouse buttons, movement, wheel, and hover events.

Visual Reference

As added to your scene

When To Use

• Follow-mouse and strafe-style 2D control graphs.

• Capture mouse position into variables for indirect targeting.

• Read wheel and delta values into gameplay logic without custom code.

• Feed {prefix}_world_2d or {prefix}_position directly into Servo or into Track To position-variable mode for top-down/tower-style targeting.

Runtime Behavior

Triggers: Based on the selected mouse event and input mode.

• Buttons support While Held, On Press, and On Release.

• Movement and wheel events use the runtime mouse_state cache.

• Hover supports both Mouse Over and Mouse Over Any.

• invert=true flips the final active state like other listeners.

Generated UI Mockup — showing expanded properties

Mouse

-

x

Name:

Label this brick...

Event:

Left Button

Input:

On Press

Move Thresh:

1.0

v

Wheel Sens:

1.0

v

Expose Scope:

Local

Expose Prefix:

mouse

v

Lock Center

Confine

Tap Mode

Expose Data

Invert

Properties

Property	Type	Default	Notes
Event	option	Left Button	Type of mouse event to detect
Input	option	On Press	When to trigger (for button events)
Tap Mode	bool	False	Trigger once per click (prevents multi-firing). Enable for single-click behavior
Move Thresh	float	1.0	Minimum pixel movement to trigger (for Movement events)
Wheel Sens	float	1.0	Wheel scroll sensitivity multiplier (for Wheel events)
Expose Data	bool	False	Write mouse position, world position, delta, and wheel values into variables
Expose Scope	option	Local	Where exposed mouse variables are written
Position Var	variable_name		Variable that receives screen/viewport mouse position
World2D Var	variable_name		Variable that receives 2D world mouse position
Delta Var	variable_name		Variable that receives mouse delta
Wheel Var	variable_name		Variable that receives wheel delta
X Var	variable_name		Variable that receives mouse screen X
Y Var	variable_name		Variable that receives mouse screen Y
World X Var	variable_name		Variable that receives 2D world X
World Y Var	variable_name		Variable that receives 2D world Y
Delta X Var	variable_name		Variable that receives mouse delta X
Delta Y Var	variable_name		Variable that receives mouse delta Y
Expose Prefix	string	mouse	Compatibility fallback when explicit output variables are empty
Lock Center	bool	False	Capture mouse to center (FPS Mode)
Confine	bool	False	Keep mouse within window (RTS Mode)

Notes

• Native implementation: src/listeners/mouse_listener.cpp

• gdlink_runtime.gd maintains mouse_state with:

  • mouse_position

  • mouse_position_world_2d

  • mouse_delta

  • wheel_delta

• mouse_position and mouse_position_world_2d are refreshed every runtime tick, not only on mouse motion, so Camera2D zoom/offset and viewport changes remain reflected in exposed variables.

• Exposed values are sampled every tick when expose_mouse_data=true, even if the selected mouse event is not currently firing. Event firing still controls whether the listener output passes to gates.