Input

An action is a symbol that names something the game cares about (up, a, start). A key binding (or button/axis binding) maps a raw hardware event to an action. Game code only ever reads actions — raw SDL keysyms never leak into your update: hook.

The default action list, defined in *default-input-config*, is:

'(up down left right a b start select quit)

These map loosely to a generic two-button gamepad: a D-pad (up, down, left, right), two face buttons (a, b), two system buttons (start, select), and a synthetic quit action the engine uses to terminate game-run! (the default loop exits when quit is held).

You are free to add or rename actions when you build a custom input-config — the action list is just the set of symbols your game agrees to recognise.

*default-input-config* is a input-config record bound at module load time in input.scm. Its contents:

Keyboard map (SDL keysym → action):

Joystick button map (SDL joy button id → action). These ids suit a generic USB pad in the "SNES-ish" layout:

Game-controller button map (SDL SDL_GameController symbol → action). This is the "Xbox-style" API SDL2 exposes for known controllers:

Analog axis bindings. Each binding is (axis positive-action negative-action) — when the axis value exceeds the deadzone, the positive action is held; when it drops below the negated deadzone, the negative action is held.

• Joystick: (0 right left) and (1 down up) (X and Y axes).
• Controller: (left-x right left) and (left-y down up) (left analog stick).

Deadzone is 8000 (SDL axis values range −32768 to 32767).

All of these are accessible via input-config-keyboard-map, input-config-joy-button-map, and so on, but you generally won't touch them directly — you pass a whole replacement record via make-input-config (see below).

The engine calls input-state-update once per frame with the SDL events it has just collected. That produces a new input-state record and stores it on the game via game-input-set!. Your update: hook reads it with (game-input game):

(update: (lambda (game dt)
           (let ((input (game-input game)))
             ...)))

Three predicates live on an input-state:

• (input-held? state action) — #t while the action is currently active (key/button down, axis past deadzone).
• (input-pressed? state action) — #t for exactly one frame: the frame on which the action transitioned from not-held to held.
• (input-released? state action) — #t for exactly one frame: the frame on which the action transitioned from held to not-held.

Press / release are derived from the record itself: input-state carries both a current and previous alist of (action . bool) pairs, and input-state-update rolls the previous snapshot forward each frame. You do not need to maintain any input history yourself.

A fourth convenience, (input-any-pressed? state config), returns #t if any action in the config's action list transitioned to pressed this frame — useful for "press any key to continue" screens.

The call shape throughout the demos is:

(input-held?     (game-input game) 'left)
(input-pressed?  (game-input game) 'a)
(input-released? (game-input game) 'start)

Build a replacement config with make-input-config and pass it to make-game via the input-config: keyword:

(define my-input
  (make-input-config
    actions: '(up down left right fire pause quit)
    keyboard-map: '((up    . up)     (w . up)
                    (down  . down)   (s . down)
                    (left  . left)   (a . left)
                    (right . right)  (d . right)
                    (space . fire)
                    (p     . pause)
                    (escape . quit))
    joy-button-map:          '()
    controller-button-map:   '()
    joy-axis-bindings:       '()
    controller-axis-bindings: '()
    deadzone: 8000))

(make-game
  title: "Custom Controls"
  input-config: my-input
  ...)

All seven slots are required, but any of the map/binding slots can be empty ('()) if you don't want that input type. The actions list determines which symbols input-any-pressed? sweeps, and seeds the initial input-state with an entry per action.

If you want to extend the defaults instead of replacing them, pull each slot off *default-input-config* and cons your extra entries:

(define my-input
  (make-input-config
    actions: (input-config-actions *default-input-config*)
    keyboard-map: (cons '(space . a)
                        (input-config-keyboard-map *default-input-config*))
    joy-button-map: (input-config-joy-button-map *default-input-config*)
    controller-button-map: (input-config-controller-button-map *default-input-config*)
    joy-axis-bindings: (input-config-joy-axis-bindings *default-input-config*)
    controller-axis-bindings: (input-config-controller-axis-bindings *default-input-config*)
    deadzone: (input-config-deadzone *default-input-config*)))

Straight from demo/getting-started.scm: test each horizontal and vertical direction independently, pick a signed step, and write back the updated position.

(define +speed+ 2)

(define (move-player player input)
  (let* ((x  (entity-ref player #:x 0))
         (y  (entity-ref player #:y 0))
         (dx (cond ((input-held? input 'left)  (- +speed+))
                   ((input-held? input 'right)    +speed+)
                   (else 0)))
         (dy (cond ((input-held? input 'up)    (- +speed+))
                   ((input-held? input 'down)     +speed+)
                   (else 0))))
    (entity-set (entity-set player #:x (+ x dx)) #:y (+ y dy))))

The platformer distinguishes a continuous action (running left/right while left=/=right are held) from an edge-triggered action (jumping exactly once when a is first pressed):

(define (player-vx input)
  (cond ((input-held? input 'left)  -3)
        ((input-held? input 'right)  3)
        (else 0)))

(define (update-player player input)
  (let* ((jump? (and (input-pressed? input 'a)
                     (entity-ref player #:on-ground? #f)))
         (player (entity-set player #:vx (player-vx input))))
    (if jump?
        (entity-set player #:ay (- *jump-force*))
        player)))

Using input-pressed? instead of input-held? prevents the player from "spamming" the jump simply by keeping a depressed — the action must be released and re-pressed to fire again.

The same pattern shows up in demo/shmup.scm for firing bullets:

(if (input-pressed? input 'a)
    (values updated (list (make-bullet ...)))
    (values updated '()))

The default config registers bindings for keyboard, joystick, and game controller at the same time — no configuration switch, no "input device" concept. Whichever device fires an event first on a given frame sets the corresponding action, and the next frame reflects it. You get controller support for free as long as you keep the default config (or carry its joy-* / controller-* slots forward into your custom config).

game-run! opens every connected game controller at startup, and handle-controller-device opens any controller hot-plugged during the session, so no extra wiring is needed.

To let players press space for start instead of return, override just the keyboard map (keeping the rest of the defaults):

(define my-input
  (make-input-config
    actions: (input-config-actions *default-input-config*)
    keyboard-map:
      '((w . up) (up . up)
        (s . down) (down . down)
        (a . left) (left . left)
        (d . right) (right . right)
        (j . a) (z . a)
        (k . b) (x . b)
        (space . start)         ;; was (return . start)
        (escape . quit))
    joy-button-map:          (input-config-joy-button-map *default-input-config*)
    controller-button-map:   (input-config-controller-button-map *default-input-config*)
    joy-axis-bindings:       (input-config-joy-axis-bindings *default-input-config*)
    controller-axis-bindings: (input-config-controller-axis-bindings *default-input-config*)
    deadzone:                (input-config-deadzone *default-input-config*)))

(make-game
  title: "Remapped Start"
  input-config: my-input
  ...)

Multiple keys can map to the same action (the defaults already do this: both w and up trigger up), so another approach is to add (space . start) alongside the existing (return . start) entry instead of replacing it.