Skip to content

03 07 Config maps

Jump to bottom
evets17 edited this page Mar 24, 2026 · 3 revisions

03 07 Config maps

This page explains input mapping (input.maps) in Sprint Boost.

Why maps are useful

Input maps let you remap controls without changing the game ROM.

Common uses:

  • controller remaps for comfort
  • alternate control schemes per game
  • blocking specific inputs

Where maps can be used

Input mapping is relevant for:

  • boost_mode = "enhanced"

In current Sprint Boost behavior, mapping is part of the enhanced input path.

Basic mapping example

[input]
mapping = "default"

[input.maps.default]
C1_1 = "C2_1"
C1_2 = "C2_2"
C1_3 = "C2_3"
C0_RESET = false

Core map concepts

Active map selection

Set which map is active with:

[input]
mapping = "default"

Map entries

Map entries are key/value pairs under:

  • input.maps.<map_name>

Common value meanings:

  • string value: remap to another token
  • false: block/drop input forwarding
  • true: explicit passthrough/no remap
  • object value: conditional mapping with modifier-key behavior

Modifier-key mappings (object form)

You can make one button/key act differently while another button/key is being held.

Think of this like a temporary "shift" button for controller inputs:

  • normal behavior when the modifier is not held
  • alternate behavior while the modifier is held

Object fields:

  • map_to: normal behavior
  • modify_key: the key/button you hold as the modifier
  • modify_map_to: alternate behavior while the modifier is held

Defaults:

  • missing map_to defaults to true (passthrough)
  • missing modify_map_to defaults to true (passthrough)
  • missing/invalid modify_key means only normal behavior (map_to) is used

Latching behavior:

  • Sprint Boost decides normal vs alternate behavior at press time (DOWN).
  • That choice stays fixed until you release that same key/button.
  • Release (UP) follows the same path chosen at press time.

Example:

[input]
mapping = "default"

[input.maps.default]
# Base: C2_ACTION_LEFT -> C2_4
# While C2_5 is held: block C2_ACTION_LEFT
C2_ACTION_LEFT = { map_to = "C2_4", modify_key = "C2_5", modify_map_to = false }

# Base: passthrough (map_to defaults true)
# While C2_5 is held: remap C2_ACTION_RIGHT -> C2_6
C2_ACTION_RIGHT = { modify_key = "C2_5", modify_map_to = "C2_6" }

# Base: remap C1_ENTER -> C0_RESET
# While C1_ACTION_TOP is held: passthrough (modify_map_to defaults true)
C1_ENTER = { map_to = "C0_RESET", modify_key = "C1_ACTION_TOP" }

Common remap pattern

A shared map can be defined at folder level, then turned on by specific games.

Example idea:

  • folder-level defines run_and_gun map
  • game-level sets input.mapping = "run_and_gun"

This keeps map definitions reusable.

Override behavior

Mapping follows normal config precedence:

  • Folder-level map definitions can be shared
  • Game-level config can change active map or override entries

If the active map name does not exist, mapping behavior will not apply as intended.

Token conventions (keycode, joystick, aliases)

Maps support a few token styles:

  • Keycode tokens (example: K1073741914)
  • Joystick button tokens (example: J03)
  • Controller aliases (example: C1_5, C2_ENTER, C0_RESET)

For Sprint-focused config, aliases are usually easiest to read and maintain.

Full alias reference (usable in maps and hotkeys)

These aliases can be used in both input.maps and input.hotkeys.binding.keys.

Controller 1 keypad + actions:

  • C1_1, C1_2, C1_3, C1_4, C1_5, C1_6, C1_7, C1_8, C1_9
  • C1_0, C1_CLEAR, C1_ENTER
  • C1_ACTION_TOP, C1_ACTION_LEFT, C1_ACTION_RIGHT

Controller 1 disc directions:

  • C1_N, C1_NE, C1_E, C1_SE, C1_S, C1_SW, C1_W, C1_NW

Controller 2 keypad + actions:

  • C2_1, C2_2, C2_3, C2_4, C2_5, C2_6, C2_7, C2_8, C2_9
  • C2_0, C2_CLEAR, C2_ENTER
  • C2_ACTION_TOP, C2_ACTION_LEFT, C2_ACTION_RIGHT

Controller 2 disc directions:

  • C2_N, C2_NE, C2_E, C2_SE, C2_S, C2_SW, C2_W, C2_NW

System alias:

  • C0_RESET (physical Sprint reset/debug key)

Directional input note (Sprint controller)

Sprint controllers physically send 8 directional inputs.

The emulator uses those inputs to produce Intellivision movement behavior, including full 16 direction diagonal combinations.

Practical mapping implication:

  • Sprint Boost mappings can only remap the directional inputs that are physically sent (the 8 directions).

Relationship to kbdhackfile

kbdhackfile via jzintv_flags is still a valid approach and can be used together with Sprint Boost maps.

Input flow guidance:

  • Sprint Boost mapping is applied before forwarding input events to the emulator.
  • Emulator-side keyboard hack behavior then applies within emulator processing.

So if both are configured, they may both affect final control behavior.

Blocking inputs intentionally

Setting a map entry to false is the standard way to stop that input from being forwarded to the game.

Example:

[input.maps.default]
C0_RESET = false

This is useful when you want Sprint Boost hotkeys/menu behavior to own that input instead of gameplay forwarding.

Practical tips

  • Keep map names simple (default, run_and_gun, alt_controls).
  • Change only the inputs you need.
  • Test one map change at a time.
  • Use game-level map activation for game-specific control styles.

Next step

Continue to:

Clone this wiki locally