Input and Movement

Drive a node from the keyboard with input actions.

▶ Run in browser

Tags: tutorial beginner input

Input and Movement

Now make something move when the player presses a key. SimVX does not ask you to check raw key codes scattered through your game. Instead you name an action (“move_right”) and bind keys to it once; your gameplay reads the action. Rebinding keys or adding a gamepad later never touches the movement code.

By the end you will drive a square around the window with WASD or the arrow keys, or by dragging with the mouse or a finger.

Step 1: Declare the actions on the root node

Put an input_actions dictionary at class scope on your root node. Each action name maps to a list of bindings (here, two keys each):

class MovementDemo(Node2D):
    input_actions = {
        "move_left":  [Key.A, Key.LEFT],
        "move_right": [Key.D, Key.RIGHT],
        "move_up":    [Key.W, Key.UP],
        "move_down":  [Key.S, Key.DOWN],
    }

Why the class attribute, not main()? SimVX registers input_actions when the scene starts, before the first frame. Registering actions inside main() works on the desktop but is silently skipped by the web export (which never runs main()), so your web build would have no input. The class attribute is the canonical path. Registering from a node callback such as on_ready() works everywhere too, because those callbacks run on every backend; only code outside the scene’s lifecycle (main(), module scope after App.run() returns) is skipped on the web.

Step 2: Read the actions and move

Input.get_strength(action) returns how hard an action is held, from 0 to 1. It reads identically for a key (0 or 1) or a gamepad axis (anything between), so the same line of code handles both. Subtract opposite directions to get a signed axis:

class Player(Node2D):
    SPEED = 360.0

    def on_update(self, dt):
        dx = Input.get_strength("move_right") - Input.get_strength("move_left")
        dy = Input.get_strength("move_down")  - Input.get_strength("move_up")
        self.position += Vec2(dx, dy) * self.SPEED * dt

Step 3: Diagonals are faster, so normalise

That code has the classic movement bug. Hold right and down together and the vector is (1, 1), whose length is about 1.41: the square travels 41% faster diagonally than it does along an axis. Capping the direction at length 1 fixes it, and Input.get_vector does exactly that for the four actions at once:

direction = Input.get_vector("move_left", "move_right", "move_up", "move_down")
self.position += direction * self.SPEED * dt

get_vector is the same subtraction as Step 2 on both axes, plus the normalise. Prefer it whenever you read a direction from four actions.

Step 4: Stay frame-rate independent

Multiplying by dt (seconds since the last frame) is what keeps the speed the same on a 60 fps and a 144 fps machine. Never add a fixed amount per frame: the game would run faster on faster hardware.

Step 5: Keep the square on screen

Vec2.clamped bounds both components at once against a minimum and a maximum corner, so there is no need to clamp x and y by hand:

half = self.SIZE / 2
moved = self.position + direction * self.SPEED * dt
self.position = moved.clamped(Vec2(half, half), Vec2(WIDTH - half, HEIGHT - half))

Step 6: The same movement code, from another device

Actions decouple gameplay from hardware, and so does anything else that produces a direction. A browser build may be running on a phone with no keyboard, so when no direction key is held the example steers towards a held pointer instead (a touch reports as the left mouse button):

def _pointer_direction(self) -> Vec2:
    if not Input.is_mouse_button_pressed(MouseButton.LEFT):
        return Vec2(0, 0)
    offset = Input.mouse_position - self.position
    return offset.normalized() if offset.length() > self.POINTER_DEAD_ZONE else Vec2(0, 0)

The movement lines never change: they consume a direction and do not care whether a key, a gamepad stick, or a fingertip produced it.

Run it

# In your own copy of this directory
python main.py

# From the root of a repository checkout
uv run python examples/tutorials/input_and_movement/main.py

What’s next

• Bouncing Balls – Property descriptors and spawning many children.

• Pong – put input, signals, and collision together into a full game.

Source

"""Input and Movement: Drive a node from the keyboard with input actions.

The third lesson: turn key presses into movement. Instead of checking raw keys,
SimVX uses named *input actions* ("move_left") that you bind to one or more keys.
Your game logic reads the action, so rebinding keys (or adding a gamepad) never
touches gameplay code.

Move the square with WASD or the arrow keys, or hold the left mouse button (a
finger on a touch screen counts as the left button) to steer it to the pointer.

# /// simvx
# tags = ["tutorial", "beginner", "input"]
# web = { root = "MovementDemo", width = 800, height = 600, responsive = true }
# ///

## What you will learn

- **Input actions** -- name an intent ("move_right") and bind keys to it.
- **`input_actions` class attribute** -- the canonical way to register actions on the
  root node (registering in `main()` is skipped by the web export, so actions there
  are silently lost).
- **`Input.get_strength(action)`** -- read how hard an action is held (0..1), which
  reads the same for a key or a gamepad axis.
- **`Input.get_vector(...)`** -- read four actions as one direction, already normalised
  so a diagonal is not faster than a straight line.
- **Frame-rate-independent movement** -- multiply speed by `dt` so motion is the same
  on any machine.
- **One movement path, several devices** -- the pointer fallback feeds the same two
  lines of movement code, which never learns where the input came from.

## How it works

`MovementDemo` (the root) declares `input_actions` at class scope, binding each
direction to two keys. The `Player` child turns those four actions into a direction
vector every frame, falls back to steering towards a held pointer when no direction
key is down, and moves by `direction * speed * dt`, kept inside the window with
`Vec2.clamped`. No raw key codes appear in the movement code.

Run: uv run python examples/tutorials/input_and_movement/main.py
Headless self-check: uv run python examples/tutorials/input_and_movement/main.py --test
"""

from simvx.core import Input, Key, MouseButton, Node2D, Vec2
from simvx.graphics import App

WIDTH, HEIGHT = 800, 600


class Player(Node2D):
    """Reads the named actions and moves. Knows nothing about which keys are bound."""

    SIZE = 56
    SPEED = 360.0
    POINTER_DEAD_ZONE = 4.0  # stop when the pointer is this close, so we do not jitter

    def on_update(self, dt: float):
        # get_vector reads the four actions, subtracts each opposing pair, and clamps
        # the result to length 1, so holding right+down is not faster than holding
        # right alone. One axis written out by hand is:
        #     Input.get_strength("move_right") - Input.get_strength("move_left")
        # and get_strength reads the same for a key (0 or 1) or a gamepad stick (0..1).
        direction = Input.get_vector("move_left", "move_right", "move_up", "move_down")
        if direction.length() == 0.0:
            direction = self._pointer_direction()

        half = self.SIZE / 2
        moved = self.position + direction * self.SPEED * dt
        self.position = moved.clamped(Vec2(half, half), Vec2(WIDTH - half, HEIGHT - half))

    def _pointer_direction(self) -> Vec2:
        """Steer towards a held pointer, so the browser build works without a keyboard.

        A touch reports as the left mouse button, so this covers phones and tablets too.
        """
        if not Input.is_mouse_button_pressed(MouseButton.LEFT):
            return Vec2(0, 0)
        offset = Input.mouse_position - self.position
        return offset.normalized() if offset.length() > self.POINTER_DEAD_ZONE else Vec2(0, 0)

    def on_draw(self, renderer):
        half = self.SIZE / 2
        top_left = (self.position.x - half, self.position.y - half)
        renderer.draw_rect(top_left, (self.SIZE, self.SIZE), colour=(0.4, 0.8, 1.0, 1.0), filled=True)


class MovementDemo(Node2D):
    """Root node: declares the input actions and spawns the player."""

    # The canonical, web-safe registration path. SimVX reads this when the scene
    # starts, before the first frame. Each action maps to a list of bindings.
    input_actions = {
        "move_left": [Key.A, Key.LEFT],
        "move_right": [Key.D, Key.RIGHT],
        "move_up": [Key.W, Key.UP],
        "move_down": [Key.S, Key.DOWN],
    }

    def on_ready(self):
        self.player = self.add_child(Player(position=Vec2(WIDTH / 2, HEIGHT / 2)))

    def on_draw(self, renderer):
        renderer.draw_text("Input and Movement", (20, 20), scale=2, colour=(1, 1, 1))
        renderer.draw_text("WASD or arrow keys to move, or hold the pointer to steer", (20, 52), colour=(0.7, 0.7, 0.7))


def _selftest() -> bool:
    """Headless: drive the player with each device the lesson claims works.

    Both keys bound to an action are pressed in turn, so the "one intent, several
    keys" claim is measured rather than asserted; a diagonal is compared against a
    straight line to check the direction really is normalised; and the pointer is
    held down to check it feeds the same two lines of movement code. Every input
    goes through ``InputSimulator``, so the action map is part of what is tested.
    """
    from simvx.core.testing import InputSimulator
    from simvx.graphics.testing import assert_not_blank, save_png

    HELD = 30  # half a second of holding, long enough to measure but short of any wall
    RUNS = (
        ("D", (Key.D,), Vec2(1, 0)),
        ("the Right arrow, bound to the same action", (Key.RIGHT,), Vec2(1, 0)),
        ("W", (Key.W,), Vec2(0, -1)),
        ("D and S together", (Key.D, Key.S), Vec2(1, 1).normalized()),
    )
    CORNER = (WIDTH - 4.0, HEIGHT - 4.0)  # a pointer held past the far corner

    app = App(title="Input and Movement", width=WIDTH, height=HEIGHT, visible=False)
    scene = MovementDemo(name="MovementDemo")
    sim = InputSimulator()
    seen: dict[str, object] = {}
    moves: list[tuple[str, Vec2, Vec2]] = []  # (label, measured travel, expected direction)

    def place(x: float, y: float) -> None:
        scene.player.position = Vec2(x, y)

    def on_frame(idx: int, _t: float) -> bool:
        step = idx // (HELD + 4)
        phase = idx % (HELD + 4)
        if step < len(RUNS):
            label, keys, direction = RUNS[step]
            if phase == 0:
                place(WIDTH / 2, HEIGHT / 2)
                seen["from"] = Vec2(scene.player.position)
            elif phase == 1:
                for key in keys:
                    sim.press_key(key)
            elif phase == 1 + HELD:
                for key in keys:
                    sim.release_key(key)
                moves.append((label, Vec2(scene.player.position) - seen["from"], direction))
        elif step == len(RUNS):
            if phase == 0:
                place(WIDTH / 2, HEIGHT / 2)
                seen["pointer_from"] = Vec2(scene.player.position)
            elif phase == 1:
                sim.press_mouse(MouseButton.LEFT, CORNER)
            elif phase == 1 + HELD:
                seen["pointer_to"] = Vec2(scene.player.position)
            elif phase == 2 + HELD:
                sim.release_mouse(MouseButton.LEFT)
        elif step == len(RUNS) + 1:
            if phase == 0:
                place(WIDTH - 10.0, HEIGHT - 10.0)
            elif phase == 1:
                sim.press_key(Key.D)
                sim.press_key(Key.S)
            elif phase == 1 + HELD:
                sim.release_key(Key.D)
                sim.release_key(Key.S)
                seen["corner"] = Vec2(scene.player.position)
        return True

    total = (HELD + 4) * (len(RUNS) + 2)
    frames = app.run_headless(scene, frames=total, on_frame=on_frame, capture_frames=[total - 1])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/input_and_movement_test.png")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    expected = Player.SPEED * HELD / 60.0
    for label, travel, direction in moves:
        want = direction * expected
        check(
            f"holding {label} moves the player {expected:.0f}px that way",
            (travel - want).length() < 1.0,
            f"({travel.x:.1f}, {travel.y:.1f}) against ({want.x:.1f}, {want.y:.1f})",
        )
    diagonal = next(t for label, t, _ in moves if "together" in label)
    straight = next(t for label, t, _ in moves if label == "D")
    check(
        "so a diagonal is no faster than a straight line: get_vector normalises it",
        abs(diagonal.length() - straight.length()) < 1.0,
        f"{diagonal.length():.1f}px diagonally against {straight.length():.1f}px straight",
    )

    towards = (seen["pointer_to"] - seen["pointer_from"]).normalized()
    aim = (Vec2(*CORNER) - seen["pointer_from"]).normalized()
    check(
        "holding the pointer steers the player towards it, through the same movement code",
        (seen["pointer_to"] - seen["pointer_from"]).length() > expected - 1.0 and (towards - aim).length() < 0.02,
        f"moved {(seen['pointer_to'] - seen['pointer_from']).length():.1f}px " f"towards ({aim.x:.2f}, {aim.y:.2f})",
    )

    half = Player.SIZE / 2
    check(
        "and it stops at the window edge rather than leaving it",
        abs(seen["corner"].x - (WIDTH - half)) < 0.01 and abs(seen["corner"].y - (HEIGHT - half)) < 0.01,
        f"came to rest at ({seen['corner'].x:.1f}, {seen['corner'].y:.1f}) on an {WIDTH}x{HEIGHT} window",
    )

    print("screenshot: /tmp/input_and_movement_test.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Input and Movement", width=WIDTH, height=HEIGHT).run(MovementDemo())