simvx.core.input.map

InputMap: the flattened result of the active input contexts, plus the override layer.

InputMap is not a registry a game writes into and reads back. It is what the active :class:~.contexts.InputContext stack currently means: the contexts are flattened into one binding map when the stack changes, and every query reads that map rather than walking the stack.

Two things write bindings and they are not the same thing:

• A game declares them, on a node’s input_context (a plain dict, or an

  class:

  ~.contexts.InputContext with a name or hides), or in the project’s settings. :meth:_InputMap.add_action declares on the tree’s own context, for code that builds its entries as it runs.

• A player rebinds them, which writes the override layer:

  meth:

  _InputMap.rebind. An override is persistent, survives every rebuild of the stack, and is reapplied to each flatten, so a rebound key stays rebound across a scene change, a pause and a vehicle being entered.

  meth:

  _InputMap.export and :meth:_InputMap.load persist it.

Module Contents

Classes

BindingRole	Which part of one source a rebind replaces.
ActionExplanation	What :meth:_InputMap.explain finds out about one name.
Rebind	One override: what a player put in place of what the game declared.

Functions

to_binding	Coerce one written or bare binding spelling into an :class:InputBinding.
roles_of	The parts of source a player can rebind separately.
set_project_input	Make entries the project layer of every tree’s map: what ProjectSettings.apply_input does.
current_input_map	The map the bare InputMap means: the tree whose code is running, else the tree in play.
set_active_input_map	Context manager to set the active InputMap for the current context.

Data

log
REBIND_FORMAT_VERSION
InputMap
__all__

API

simvx.core.input.map.to_binding(b: simvx.core.input.events.InputBinding | simvx.core.input.controls.DeviceButton | simvx.core.input.controls.DeviceAxis | str) → simvx.core.input.events.InputBinding

Coerce one written or bare binding spelling into an :class:InputBinding.

The one place a binding spelling is understood, so what an InputMap accepts is also what an Axis1D component, a simvx.toml and a rebind file accept. A control is its own binding; a written control is its str(), "mouse:right", "tablet:button(2)" or "pointer:secondary"; a key may also be written by its combo name, "space" or "shift+tab".

simvx.core.input.map.log

‘getLogger(…)’

simvx.core.input.map.REBIND_FORMAT_VERSION

6

class simvx.core.input.map.BindingRole

Bases: enum.StrEnum

Which part of one source a rebind replaces.

An action’s value comes from its sources, and a source is a whole value on its own: a button, an :class:~.actions.Axis1D with two halves, or an

Class:

~.actions.Axis2D with four directions. A rebind screen shows one row per part, and this is what that row is called.

Initialization

Initialize self. See help(type(self)) for accurate signature.

WHOLE

‘whole’

LOW

‘low’

HIGH

‘high’

UP

‘up’

DOWN

‘down’

LEFT

‘left’

RIGHT

‘right’

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

simvx.core.input.map.roles_of(source: simvx.core.input.actions.Source) → tuple[simvx.core.input.map.BindingRole, ...]

The parts of source a player can rebind separately.

class simvx.core.input.map.ActionExplanation

What :meth:_InputMap.explain finds out about one name.

Attributes: name: The name asked about. declared: Whether anything declares it: a context, the project or the engine. active: Whether it can fire right now. kind: Its type, or None for a name nothing declares. sources: Its sources as declared, rebinds applied; a hidden one’s as it will read when it comes back. bindings: What those sources resolve to, device binding by device binding. context: The declaration in force, or the one it will come back as while hidden: a node’s context, the tree’s, the project’s or the engine’s. node: The node whose context that is, or None for the tree, the project and the engine. hidden: Whether a context above takes it away right now. hidden_by: The context doing so, or None. shadowed: The declarations beneath the one in force, which it overrides. rebinds: The player’s overrides that apply to it.

name: str

None

declared: bool

None

active: bool

None

kind: simvx.core.input.actions.ActionKind | None

None

sources: tuple[simvx.core.input.actions.Source, ...]

None

bindings: tuple[simvx.core.input.events.InputBinding, ...]

None

context: simvx.core.input.contexts.InputContext | None

None

node: simvx.core.node.Node | None

None

hidden: bool

None

hidden_by: simvx.core.input.contexts.InputContext | None

None

shadowed: tuple[simvx.core.input.contexts.InputContext, ...]

None

rebinds: tuple[Rebind, ...]

None

class simvx.core.input.map.Rebind

One override: what a player put in place of what the game declared.

Addressed by (action, slot, role), which is exactly the row a rebind screen draws. slot is the position in the action’s source list, so rebinding the keyboard half of a movement action leaves the stick alone, and role is the part within that source, so rebinding one direction of a movement action leaves the other three.

An override is reapplied to every flatten. Where the active contexts no longer define that slot and role, it is inert rather than dropped, so entering a vehicle and leaving it again gives the rebound key back.

Attributes: action: Which entry: an action’s or a device alias’s name, or an engine entry such as Controller.A. binding: What to put there (a binding, or another entry’s name), or None to leave the part unbound. slot: Which source of the action, in declaration order. role: Which part of that source. player: Whose rebind it is, or None for everybody’s. A player-scoped override gives that player their own copy of the action and leaves every other player reading the declared one.

action: str | simvx.core.input.controls.DeviceControl

None

binding: simvx.core.input.events.InputBinding | str | None

None

slot: int

0

role: simvx.core.input.map.BindingRole

None

player: int | None

None

property key: tuple[str | simvx.core.input.controls.DeviceControl, int, simvx.core.input.map.BindingRole, int | None]

What this override is addressed by, which is what replaces an earlier one.

simvx.core.input.map.set_project_input(entries: collections.abc.Mapping[str | simvx.core.input.controls.DeviceControl, list[simvx.core.input.actions.SourceSpec] | simvx.core.input.actions.SourceSpec]) → None

Make entries the project layer of every tree’s map: what ProjectSettings.apply_input does.

Engine code and the launcher call this with the project’s [input] table; a game declares its own entries on a node’s input_context.

simvx.core.input.map.current_input_map() → simvx.core.input.map._InputMap

The map the bare InputMap means: the tree whose code is running, else the tree in play.

Inside a tree’s span that tree’s, which is where node code always is; outside one the tree most recently activated, as the bare Input does. With no tree at all there is no map to mean, and saying so is the answer: a registration from main() goes in the project settings or on a node’s input_context.

simvx.core.input.map.set_active_input_map(instance: simvx.core.input.map._InputMap)

Context manager to set the active InputMap for the current context.

simvx.core.input.map.InputMap

‘_InputMapProxy(…)’

simvx.core.input.map.__all__

[‘ActionExplanation’, ‘BindingRole’, ‘InputMap’, ‘Rebind’, ‘REBIND_FORMAT_VERSION’, ‘roles_of’, ‘set…