input
FreeBodyEngine.core.input
#
CHARACTERSTRINGMAP = {'A': Key.A, 'B': Key.B, 'C': Key.C, 'D': Key.D, 'E': Key.E, 'F': Key.F, 'G': Key.G, 'H': Key.H, 'I': Key.I, 'J': Key.J, 'K': Key.K, 'L': Key.L, 'M': Key.M, 'N': Key.N, 'O': Key.O, 'P': Key.P, 'Q': Key.Q, 'R': Key.R, 'S': Key.S, 'T': Key.T, 'U': Key.U, 'V': Key.V, 'W': Key.W, 'X': Key.X, 'Y': Key.Y, 'Z': Key.Z, '1': Key.ONE, '2': Key.TWO, '3': Key.THREE, '4': Key.FOUR, '5': Key.FIVE, '6': Key.SIX, '7': Key.SEVEN, '8': Key.EIGHT, '9': Key.NINE, '0': Key.ZERO, 'MINUS': Key.MINUS, 'EQUAL': Key.EQUAL, 'LEFT_BRACKET': Key.LEFT_BRACKET, 'RIGHT_BRACKET': Key.RIGHT_BRACKET, 'BACKSLASH': Key.BACKSLASH, 'SEMICOLON': Key.SEMICOLON, 'APOSTROPHE': Key.APOSTROPHE, 'TILDE': Key.TILDE, 'COMMA': Key.COMMA, 'PERIOD': Key.PERIOD, 'SLASH': Key.SLASH, 'SPACE': Key.SPACE, 'RETURN': Key.RETURN, 'ENTER': Key.RETURN, 'BACKSPACE': Key.BACKSPACE, 'TAB': Key.TAB, 'ESCAPE': Key.ESCAPE, 'CAPS_LOCK': Key.CAPS_LOCK, 'L_CTRL': Key.L_CTRL, 'R_CTRL': Key.R_CTRL, 'L_SHIFT': Key.L_SHIFT, 'R_SHIFT': Key.R_SHIFT, 'L_ALT': Key.L_ALT, 'R_ALT': Key.R_ALT, 'L_SUPER': Key.L_SUPER, 'R_SUPER': Key.R_SUPER, 'INSERT': Key.INSERT, 'DELETE': Key.DELETE, 'HOME': Key.HOME, 'END': Key.END, 'PG_UP': Key.PG_UP, 'PG_DOWN': Key.PG_DOWN, 'UP': Key.UP, 'DOWN': Key.DOWN, 'LEFT': Key.LEFT, 'RIGHT': Key.RIGHT, 'F1': Key.F1, 'F2': Key.F2, 'F3': Key.F3, 'F4': Key.F4, 'F5': Key.F5, 'F6': Key.F6, 'F7': Key.F7, 'F8': Key.F8, 'F9': Key.F9, 'F10': Key.F10, 'F11': Key.F11, 'F12': Key.F12, 'F13': Key.F13, 'F14': Key.F14, 'F15': Key.F15, 'F16': Key.F16, 'F17': Key.F17, 'F18': Key.F18, 'F19': Key.F19, 'F20': Key.F20, 'F21': Key.F21, 'F22': Key.F22, 'F23': Key.F23, 'F24': Key.F24, 'NUMPAD_0': Key.NUMPAD_0, 'NUMPAD_1': Key.NUMPAD_1, 'NUMPAD_2': Key.NUMPAD_2, 'NUMPAD_3': Key.NUMPAD_3, 'NUMPAD_4': Key.NUMPAD_4, 'NUMPAD_5': Key.NUMPAD_5, 'NUMPAD_6': Key.NUMPAD_6, 'NUMPAD_7': Key.NUMPAD_7, 'NUMPAD_8': Key.NUMPAD_8, 'NUMPAD_9': Key.NUMPAD_9, 'NUMPAD_DECIMAL': Key.NUMPAD_DECIMAL, 'NUMPAD_DIVIDE': Key.NUMPAD_DIVIDE, 'NUMPAD_MULTIPLY': Key.NUMPAD_MULTIPLY, 'NUMPAD_SUBTRACT': Key.NUMPAD_SUBTRACT, 'NUMPAD_ADD': Key.NUMPAD_ADD, 'NUMPAD_ENTER': Key.NUMPAD_ENTER, 'GAMEPAD_A': GamepadButton.A, 'GAMEPAD_B': GamepadButton.B, 'GAMEPAD_X': GamepadButton.X, 'GAMEPAD_Y': GamepadButton.Y, 'GAMEPAD_LB': GamepadButton.LB, 'GAMEPAD_RB': GamepadButton.RB, 'GAMEPAD_LS': GamepadButton.LS_DOWN, 'GAMEPAD_RS': GamepadButton.RS_DOWN, 'DPAD_UP': GamepadButton.DPAD_UP, 'DPAD_RIGHT': GamepadButton.DPAD_RIGHT, 'DPAD_DOWN': GamepadButton.DPAD_DOWN, 'DPAD_LEFT': GamepadButton.DPAD_LEFT, 'GUIDE': GamepadButton.GUIDE, 'AXIS_LEFT_X': GamepadAxis.LEFT_X, 'AXIS_LEFT_Y': GamepadAxis.LEFT_Y, 'AXIS_RIGHT_X': GamepadAxis.RIGHT_X, 'AXIS_RIGHT_Y': GamepadAxis.RIGHT_Y, 'AXIS_LEFT_TRIGGER': GamepadAxis.LEFT_TRIGGER, 'AXIS_RIGHT_TRIGGER': GamepadAxis.RIGHT_TRIGGER}
module-attribute
#
KEY_PRESS = 'ENGINE_key_press'
module-attribute
#
KEY_RELEASE = 'ENGINE_key_release'
module-attribute
#
KEY_REPEAT = 'ENGINE_key_repeat'
module-attribute
#
comparison_ops = {'>': operator.gt, '<': operator.lt, '>=': operator.ge, '<=': operator.le, '==': operator.eq, '!=': operator.ne}
module-attribute
#
Action(input, check=None)
#
A single physical input (key/button/axis) bound to an action, with an optional threshold check - an action fires if any one of its bound Actions passes its check.
Binds input to this action, optionally gated by check (no check means "pressed" is just value > 0).
ActionCheck(check_type, val)
dataclass
#
Gamepad(id, window)
#
Represents a single connected gamepad, identified by its backend-assigned id.
Stores the gamepad's id and the window backend used to query its state.
GamepadAxis
#
Bases: Enum
Engine-level gamepad analog axis identifiers (sticks and triggers), independent of any windowing backend's native gamepad mapping.
LEFT_TRIGGER = auto()
class-attribute
instance-attribute
#
LEFT_X = auto()
class-attribute
instance-attribute
#
LEFT_Y = auto()
class-attribute
instance-attribute
#
RIGHT_TRIGGER = auto()
class-attribute
instance-attribute
#
RIGHT_X = auto()
class-attribute
instance-attribute
#
RIGHT_Y = auto()
class-attribute
instance-attribute
#
GamepadButton
#
Bases: Enum
Engine-level gamepad button identifiers, independent of any windowing backend's native gamepad mapping.
A = auto()
class-attribute
instance-attribute
#
B = auto()
class-attribute
instance-attribute
#
DPAD_DOWN = auto()
class-attribute
instance-attribute
#
DPAD_LEFT = auto()
class-attribute
instance-attribute
#
DPAD_RIGHT = auto()
class-attribute
instance-attribute
#
DPAD_UP = auto()
class-attribute
instance-attribute
#
GUIDE = auto()
class-attribute
instance-attribute
#
LB = auto()
class-attribute
instance-attribute
#
LS_DOWN = auto()
class-attribute
instance-attribute
#
RB = auto()
class-attribute
instance-attribute
#
RS_DOWN = auto()
class-attribute
instance-attribute
#
X = auto()
class-attribute
instance-attribute
#
Y = auto()
class-attribute
instance-attribute
#
Input(actions={})
#
Bases: Service
Central input service - polls the window backend every frame and turns raw key/gamepad state into named, engine-defined actions (each action can be bound to several physical inputs via actions).
Stores the action bindings and sets up empty pressed/released tracking state.
actions = actions
instance-attribute
#
gamepads = {}
instance-attribute
#
pressed = {}
instance-attribute
#
pressed_set = set(self.pressed.keys())
instance-attribute
#
released = set()
instance-attribute
#
action_exists(name)
#
Checks whether name is a registered action.
bind_action(name, inputs)
#
Intended to add extra input bindings to an existing action at runtime - not yet implemented.
get_action_pressed(name)
#
Returns whether name is currently pressed (held down this frame); warns and returns None if name isn't a registered action.
get_action_released(name)
#
Returns whether name was released this frame (it was pressed as of the last poll, but isn't anymore); warns and returns None if name isn't a registered action.
get_action_strength(name)
#
Returns name's current analog strength (the highest check-passing value among its bound inputs this frame); warns and returns None if name isn't a registered action.
get_vector(neg_x, pos_x, neg_y, pos_y)
#
Get a vector from the strengths of 4 actions.
on_destroy()
#
Unregisters update() from the EARLY update phase and the key events registered in on_initialize().
on_initialize()
#
Registers update() to run every frame's EARLY phase, grabs the 'window' service ('window' is a declared dependency, so it's guaranteed to already be registered), and registers the KEY_PRESS/KEY_RELEASE/KEY_REPEAT events _key_callback() emits - previously never registered anywhere, so anything subscribing to them with register_event_callback() (rather than just emitting/ignoring them, which emit_event() tolerates on an unregistered event) hit a raw KeyError. Input owns these constants, so it registers them, the same way Window.on_initialize() registers WINDOW_RESIZE/FRAMEBUFFER_RESIZE.
parse_actions(source)
classmethod
#
Parses an actions.toml-style config ({action_name: ["INPUT_NAME", "INPUT_NAME OP VAL", ...]}) into the dict[str, list[Action]] form Input uses at runtime.
Each input string is an input name (a key from CHARACTERSTRINGMAP)
optionally followed by a comparison operator and threshold value,
e.g. "AXIS_LEFT_X > 0.5" for a thresholded gamepad axis, or
"SPACE" alone for a plain digital press.
Raises:
| Type | Description |
|---|---|
ValueError
|
If an input string doesn't match the expected format. |
reset()
#
Called at the start of each poll: carries this frame's still-pressed actions into released (so a released action reads True for exactly one frame), then clears pressed/pressed_set for update() to repopulate.
set_actions(actions)
#
Replaces the entire action-bindings dict.
update()
#
Polls the window backend's key and gamepad state and recomputes every registered action's pressed/strength state for this frame.
Each distinct physical input is only read from the backend once per
frame (cached in input_vals), even if several actions share it, so
a key/axis bound to multiple actions doesn't get polled redundantly.
Key
#
Bases: Enum
Engine-level keyboard key identifiers, independent of any windowing backend - each backend (GLFW/X11/Wayland) translates its own native key codes to/from these values.
A = auto()
class-attribute
instance-attribute
#
APOSTROPHE = auto()
class-attribute
instance-attribute
#
B = auto()
class-attribute
instance-attribute
#
BACKSLASH = auto()
class-attribute
instance-attribute
#
BACKSPACE = auto()
class-attribute
instance-attribute
#
C = auto()
class-attribute
instance-attribute
#
CAPS_LOCK = auto()
class-attribute
instance-attribute
#
COMMA = auto()
class-attribute
instance-attribute
#
D = auto()
class-attribute
instance-attribute
#
DELETE = auto()
class-attribute
instance-attribute
#
DOWN = auto()
class-attribute
instance-attribute
#
E = auto()
class-attribute
instance-attribute
#
EIGHT = auto()
class-attribute
instance-attribute
#
END = auto()
class-attribute
instance-attribute
#
ENTER = RETURN
class-attribute
instance-attribute
#
EQUAL = auto()
class-attribute
instance-attribute
#
ESCAPE = auto()
class-attribute
instance-attribute
#
F = auto()
class-attribute
instance-attribute
#
F1 = auto()
class-attribute
instance-attribute
#
F10 = auto()
class-attribute
instance-attribute
#
F11 = auto()
class-attribute
instance-attribute
#
F12 = auto()
class-attribute
instance-attribute
#
F13 = auto()
class-attribute
instance-attribute
#
F14 = auto()
class-attribute
instance-attribute
#
F15 = auto()
class-attribute
instance-attribute
#
F16 = auto()
class-attribute
instance-attribute
#
F17 = auto()
class-attribute
instance-attribute
#
F18 = auto()
class-attribute
instance-attribute
#
F19 = auto()
class-attribute
instance-attribute
#
F2 = auto()
class-attribute
instance-attribute
#
F20 = auto()
class-attribute
instance-attribute
#
F21 = auto()
class-attribute
instance-attribute
#
F22 = auto()
class-attribute
instance-attribute
#
F23 = auto()
class-attribute
instance-attribute
#
F24 = auto()
class-attribute
instance-attribute
#
F3 = auto()
class-attribute
instance-attribute
#
F4 = auto()
class-attribute
instance-attribute
#
F5 = auto()
class-attribute
instance-attribute
#
F6 = auto()
class-attribute
instance-attribute
#
F7 = auto()
class-attribute
instance-attribute
#
F8 = auto()
class-attribute
instance-attribute
#
F9 = auto()
class-attribute
instance-attribute
#
FIVE = auto()
class-attribute
instance-attribute
#
FOUR = auto()
class-attribute
instance-attribute
#
G = auto()
class-attribute
instance-attribute
#
H = auto()
class-attribute
instance-attribute
#
HOME = auto()
class-attribute
instance-attribute
#
I = auto()
class-attribute
instance-attribute
#
INSERT = auto()
class-attribute
instance-attribute
#
J = auto()
class-attribute
instance-attribute
#
K = auto()
class-attribute
instance-attribute
#
L = auto()
class-attribute
instance-attribute
#
LEFT = auto()
class-attribute
instance-attribute
#
LEFT_BRACKET = auto()
class-attribute
instance-attribute
#
L_ALT = auto()
class-attribute
instance-attribute
#
L_CTRL = auto()
class-attribute
instance-attribute
#
L_SHIFT = auto()
class-attribute
instance-attribute
#
L_SUPER = auto()
class-attribute
instance-attribute
#
M = auto()
class-attribute
instance-attribute
#
MINUS = auto()
class-attribute
instance-attribute
#
N = auto()
class-attribute
instance-attribute
#
NINE = auto()
class-attribute
instance-attribute
#
NUMPAD_0 = auto()
class-attribute
instance-attribute
#
NUMPAD_1 = auto()
class-attribute
instance-attribute
#
NUMPAD_2 = auto()
class-attribute
instance-attribute
#
NUMPAD_3 = auto()
class-attribute
instance-attribute
#
NUMPAD_4 = auto()
class-attribute
instance-attribute
#
NUMPAD_5 = auto()
class-attribute
instance-attribute
#
NUMPAD_6 = auto()
class-attribute
instance-attribute
#
NUMPAD_7 = auto()
class-attribute
instance-attribute
#
NUMPAD_8 = auto()
class-attribute
instance-attribute
#
NUMPAD_9 = auto()
class-attribute
instance-attribute
#
NUMPAD_ADD = auto()
class-attribute
instance-attribute
#
NUMPAD_DECIMAL = auto()
class-attribute
instance-attribute
#
NUMPAD_DIVIDE = auto()
class-attribute
instance-attribute
#
NUMPAD_ENTER = auto()
class-attribute
instance-attribute
#
NUMPAD_MULTIPLY = auto()
class-attribute
instance-attribute
#
NUMPAD_SUBTRACT = auto()
class-attribute
instance-attribute
#
O = auto()
class-attribute
instance-attribute
#
ONE = auto()
class-attribute
instance-attribute
#
P = auto()
class-attribute
instance-attribute
#
PERIOD = auto()
class-attribute
instance-attribute
#
PG_DOWN = auto()
class-attribute
instance-attribute
#
PG_UP = auto()
class-attribute
instance-attribute
#
Q = auto()
class-attribute
instance-attribute
#
R = auto()
class-attribute
instance-attribute
#
RETURN = auto()
class-attribute
instance-attribute
#
RIGHT = auto()
class-attribute
instance-attribute
#
RIGHT_BRACKET = auto()
class-attribute
instance-attribute
#
R_ALT = auto()
class-attribute
instance-attribute
#
R_CTRL = auto()
class-attribute
instance-attribute
#
R_SHIFT = auto()
class-attribute
instance-attribute
#
R_SUPER = auto()
class-attribute
instance-attribute
#
S = auto()
class-attribute
instance-attribute
#
SEMICOLON = auto()
class-attribute
instance-attribute
#
SEVEN = auto()
class-attribute
instance-attribute
#
SIX = auto()
class-attribute
instance-attribute
#
SLASH = auto()
class-attribute
instance-attribute
#
SPACE = auto()
class-attribute
instance-attribute
#
T = auto()
class-attribute
instance-attribute
#
TAB = auto()
class-attribute
instance-attribute
#
THREE = auto()
class-attribute
instance-attribute
#
TILDE = auto()
class-attribute
instance-attribute
#
TWO = auto()
class-attribute
instance-attribute
#
U = auto()
class-attribute
instance-attribute
#
UP = auto()
class-attribute
instance-attribute
#
V = auto()
class-attribute
instance-attribute
#
W = auto()
class-attribute
instance-attribute
#
X = auto()
class-attribute
instance-attribute
#
Y = auto()
class-attribute
instance-attribute
#
Z = auto()
class-attribute
instance-attribute
#
ZERO = auto()
class-attribute
instance-attribute
#
KeyCallbackType
#
get_action_pressed(name)
#
Returns whether the action name is currently pressed.
get_action_released(name)
#
Returns whether the action name was released this frame.
get_action_strength(name)
#
Returns the action name's current analog strength.
get_action_vector(neg_x, pos_x, neg_y, pos_y)
#
Get a vector from the strengths of four actions.