factoriax.playground.config

Player configuration: persistent settings and remappable input bindings.

Stores environment parameters and input bindings (keyboard + controller) in a JSON file at the project root. The binding system uses a flat map of PlayerAction names to physical key names. A thin resolver converts these into O(1) lookup dicts at startup.

The separation of concerns is:

• What a key does = the binding map (data, configurable).

• When it applies = context logic in the play loop (code).

• How it executes = handler functions (code).

This means the same physical key, for example W, can map to both move_up and nav_up. The play loop checks which one is relevant based on which menu is open.

class factoriax.playground.config.PlayerAction(value)

Every player intention, decoupled from pygame keys and JAX actions.

Gameplay actions matter in the world. Navigation actions matter in menus and as toggle keys. Both groups share the same binding map so a physical key can map to one action from each group.

class factoriax.playground.config.PlayerConfig(env_params: dict[str, int | float]=<factory>, seed: int = 42, keyboard: dict[str, list[str]]=<factory>, controller: dict[str, list[str]]=<factory>, fullscreen: bool = False, ui_scale: int = 0)

Persistent player configuration.

factoriax.playground.config.build_controller_lookup(bindings: dict[str, list[str]]) → dict[str, frozenset[str]]

Build a reverse lookup dict from controller bindings.

Maps input name strings ("BUTTON_0", "HAT_0_UP", "AXIS_1_NEG") to the frozenset of action names bound to that input.

Parameters:

bindings – Action name to input name list mapping.

factoriax.playground.config.build_key_lookup(bindings: dict[str, list[str]]) → dict[tuple[int, int], frozenset[str]]

Build a reverse lookup dict from bindings.

Maps (modifier_flags, pygame_key_int) to the frozenset of PlayerAction names bound to that key combination.

Parameters:

bindings – Action name to key name list mapping.

factoriax.playground.config.config_to_env_params(config: PlayerConfig) → EnvParams

Build an EnvParams from the settings of a player configuration.

A field that the configuration does not hold, or holds with the wrong type, takes the default of EnvParams.

Parameters:

config – Player configuration.

factoriax.playground.config.controller_event_to_name(event: Event) → str | None

Format a controller event as a binding name string.

Handles JOYBUTTONDOWN, JOYHATMOTION, and JOYAXISMOTION events. Returns None for hat center position or axis values within the deadzone.

Parameters:

event – Pygame joystick event.

factoriax.playground.config.default_controller() → dict[str, list[str]]

Return default controller bindings for a standard gamepad.

Button numbering follows SDL2 game controller layout: 0=A/Cross, 1=B/Circle, 2=X/Square, 3=Y/Triangle, 4=LB, 5=RB, 6=Back/Select, 7=Start, 8=L3, 9=R3.

Axis convention: AXIS_{n}_POS for positive deflection, AXIS_{n}_NEG for negative. Left stick = axes 0 (X) and 1 (Y). D-pad = HAT_0_{UP,DOWN,LEFT,RIGHT}.

factoriax.playground.config.default_keyboard() → dict[str, list[str]]

Return default keyboard bindings matching the original hardcoded keys.

factoriax.playground.config.env_params_to_dict(params: EnvParams) → dict[str, int | float]

Convert an EnvParams instance to a plain dict.

factoriax.playground.config.event_to_key_name(key: int, mods: int) → str

Format a key press as a binding name string.

Inverse of _parse_key_name(). Converts a pygame key constant and modifier bitmask into the "K_w" / "SHIFT+K_1" format used in the bindings config.

Parameters:

• key – Pygame key constant, for example pygame.K_w.

• mods – Pygame modifier bitmask from pygame.key.get_mods().

factoriax.playground.config.load_config(path: Path = PosixPath('player_config.json')) → PlayerConfig

Load player config from disk, falling back to defaults.

If the file does not exist or is malformed, returns a config with all default values. Missing fields are filled from defaults.

Parameters:

path – Path to the JSON config file.

factoriax.playground.config.resolve_controller_axis(lookup: dict[str, frozenset[str]], axis: int, value: float) → frozenset[str]

Resolve a controller axis value to player actions.

Values within the deadzone (+/-_AXIS_DEADZONE) produce no actions. Beyond the deadzone, the positive or negative direction name is looked up.

Parameters:

• lookup – Controller lookup from build_controller_lookup().

• axis – Axis index.

• value – Current axis value (-1.0 to 1.0).

factoriax.playground.config.resolve_controller_button(lookup: dict[str, frozenset[str]], button: int) → frozenset[str]

Resolve a controller button press to player actions.

Parameters:

• lookup – Controller lookup from build_controller_lookup().

• button – Button index from the pygame event.

factoriax.playground.config.resolve_controller_hat(lookup: dict[str, frozenset[str]], hat: int, value: tuple[int, int]) → frozenset[str]

Resolve a controller hat/d-pad event to player actions.

A hat value of (0, 0) (centered) produces no actions. Non-zero components are mapped to direction names and unioned.

Parameters:

• lookup – Controller lookup from build_controller_lookup().

• hat – Hat index from the pygame event.

• value – (x, y) hat position from the pygame event.

• int]

factoriax.playground.config.resolve_event(event: Event, kb_lookup: dict[tuple[int, int], frozenset[str]], ctrl_lookup: dict[str, frozenset[str]] | None = None) → frozenset[str]

Resolve any input event to player actions.

The function reads a KEYDOWN, a JOYBUTTONDOWN, and a JOYHATMOTION event, each through its own lookup table. Every other event gives an empty set. A menu therefore takes the same navigation as the game UI, and needs no second copy of this logic.

Parameters:

• event – Event to read.

• kb_lookup – Lookup table from a key to the actions of that key.

• ctrl_lookup – Lookup table from a controller input to its actions. None gives an empty set for every controller event.

factoriax.playground.config.resolve_key(lookup: dict[tuple[int, int], frozenset[str]], key: int, mods: int = 0) → frozenset[str]

Look up a key press and return all matching player actions.

Tries the exact modifier combination first. If no match is found and modifiers were held, falls back to the bare (unmodified) key.

Parameters:

• lookup – Reverse lookup dict from build_key_lookup().

• key – Pygame key constant, for example pygame.K_w.

• mods – Pygame modifier bitmask from pygame.key.get_mods().

factoriax.playground.config.save_config(config: PlayerConfig, path: Path = PosixPath('player_config.json')) → None

Write player config to disk as formatted JSON.

Parameters:

• config – Player configuration to persist.

• path – Destination file path.