Knightrock

A 2D hack 'n' slash platformer in Python with pygame-ce — frame-data combat, a deterministic fixed-timestep simulation, data-driven gameplay values and a built-in debug test bench.

Requires Python ≥ 3.14 (.python-version) and uv.

uv sync --dev                    # --dev adds pytest, pytest-cov, ruff, mypy
uv run python main.py            # play
uv run python main.py --debug    # play with the debug overlay (DEBUG=1)

--help prints the usage. uv run python main.py --debug and DEBUG=1 uv run python main.py are equivalent.

• What it is
• Controls
• In-game options
• Debugging
  • Test bench
  • Debug overlay
  • Frame timings & benchmarks
• How it works
  • Framing
  • Camera, rounding and culling
  • Physics and assists
  • Combat and knockback
  • The ground pivot
  • Draw planes
• Data-driven gameplay
• Architecture
• Conventions
• Tests & quality
• Packaging & releases
• Further notes

Keyboard

Gamepad

Three details of the menu navigation, all in src/core/settings.py under Input:

• A stick is a position, not a press. A quarter of its travel moves one row; pushing further scrolls, and easing back stops it without stepping backwards.
• The D-pad has no partial travel to read, so holding it scrolls on its own.
• Only the four directions auto-repeat, stick and D-pad included — a held confirm would otherwise open and close a menu in a loop.

Options is a navigation hub, not a list: every setting lives in the screen that owns it. Reachable from the main menu and from the pause screen.

Each controls screen ends on a separated, greyed block — the Y inversion, Reset to defaults and Back. They are choices, not slots, so they carry no key: a row that looks like the others and cannot take a binding is a row you press a key on and nothing happens.

Choices are written to ~/.knightrock/settings.json and apply without restarting. Each sub-menu has its own Reset, restoring exactly what it owns — the video one leaves your controls alone. A file that cannot be read is reported in the log with its reason rather than silently replaced, and the file being overwritten is kept as settings.json.bak.

Everything below is inert unless the game runs with DEBUG=1 (or --debug). Pressing an F-key without the flag shows a transitory notice naming it once, then stops — a key that silently does nothing is indistinguishable from a bug, but the flag is never implied either.

Every showcase feature is reachable from a single hotkey, live in game.

The full list is recalled on screen by the DEBUG KEYS panel.

What the overlay draws. Hitboxes are blue (player), red (enemy), grey (neutral); overlaid with a green hurtbox and an orange offensive box. Velocity arrows are a tapered shaft, a filled head and a pivot dot, all wrapped in a dark rim so the silhouette survives a bright sky — the head length is clamped and short vectors are stretched, so a walk and a dash both stay legible. The arrow is red while the hit that caused it is fresh or while the knockback state still carries the entity, gold on a parry, yellow for locomotion. Outlines: cyan = OTG guard, purple = juggle gravity. Labels are short cards, with a second line only during an attack or when a flag is set; projectiles carry speed, lifetime and pierce; tiles are skipped. Multi-box indices are drawn as in-situ vector points, the first filled and the following ones hollow.

Everything is scaled by the density of the world it annotates (WorldOverlayMetrics), because the overlay is a description of the world: an unscaled 1 px hitbox outline arrives at 53 % of its intent on a window whose density is 1.889, and a debug layer too thin to see is not a debug layer. Culling is Camera.is_visible, the one world-space cull in the renderer. Melee, projectile AABB and moving-hazard geometry use swept collision; static hazards and contact damage keep discrete collision.

Why F4 ships off. A level carries 839 terrain tiles whose outline tells you nothing, and drawing them is the most expensive thing the overlay does. Measured on level 0 at 1280×720, dropping the layer took the whole overlay pass from 1.98 ms to 0.09 ms — 1.9 ms of a 16.7 ms budget, for a picture of the tileset. (notes/perf_debug_overlay.md)

There is no always-on frame readout: the measurement used to run on every frame of every session to paint two lines in the corner, which made it noise the rest of the time. The PERFORMANCE panel under DEBUG=1 carries what is still worth reading — frame rate, frame time, overlay and panel cost, sprite counts, text cache.

uv run python tests/benchmarks/ui_benchmark.py       # frame timing, in general
uv run python tests/benchmarks/fx_benchmark.py       # cost to build one particle
uv run python tests/benchmarks/render_benchmark.py
uv run python tests/benchmarks/contact_benchmark.py

The camera shows a fixed rectangle of the world: 1152×648 world units (src/core/display/framing.py). It is render-only, and the simulation reads it and nothing else — window size, DPI, display mode and desktop dimensions are not observable from it.

It is deliberately tight: the player sees 45 % of the width and 34 % of the height of the shipped level, so a level has to be read as it is entered rather than mapped from the menu.

How large the world is drawn is a separate question, answered by the window: a world unit gets window / framing pixels — 1.667 at 1920×1080, 0.694 in an 800×600 window — and the art is magnified once, at load. The camera has no zoom; it has a density, read off the target so the two cannot disagree.

The window is the only source of truth about the window. There is no stored size, no size_mode, no render scale and no smoothing flag, because none of those describes a screen. Four rules replace them:

• the display mode defaults to auto — borderless when the screen already has the shape of the framing, a window otherwise, re-evaluated on every launch. A chosen mode is never re-resolved;
• a windowed game opens as large as fits with room for its own title bar, and that is all. Drag it to whatever you like;
• the render target is the window — more precisely the letterbox rectangle of the window that carries the picture at the framing's aspect. The finished frame is blitted 1:1, so presenting costs a copy rather than a resample;
• whole-pixel art trades filling the window for every art pixel being an exact k×k block: the picture becomes the largest whole multiple of the framing that fits and the bars take the rest. It is a no-op below the framing size, and the row says so.

Resizing the window rebuilds the render target, re-reads the pixel density and re-lays out the interface — the same cascade as a display change, which is why it is one piece of code. What resizing never changes is how much world you see.

• Camera.apply() maps a world rectangle to exact target coordinates — screen = (world - offset) * density. Sprites, health bars, hitboxes, labels and the debug overlays all read the one transform, so none of them can drift from the others.
• Camera.scaled_size() is the single rounding rule in the drawing path: an image is magnified to that size and blitted into a rectangle of that size.
• Camera.is_visible() culls against the framing rect, and the frozen terrain is narrowed to a handful of chunks before it gets there.
• Every frame is a complete repaint of the target, so a stale pixel is not possible rather than merely unlikely.

Assists are on. Set a value to 0 (or 1 for the jump cut) to restore the legacy, assist-free behaviour. All of them live in src/core/settings.py.

The crouch constants live in Physics, not GameFeel. They belong to the collider, not to the feel, and their only readers are src/entities/crouch_posture.py and src/states/player_states.py.

Combat is frame-data driven: startup / active / recovery phases feed HitboxManager and HitResolver through the two-pass deterministic CombatSystem (src/core/level/systems/combat_system.py).

Directional influence is not player-gated. _apply_directional_influence in src/states/reaction_states.py fires for any entity whose move_axis is non-zero, and enemies do set move_axis. In practice a launched enemy rarely carries a stale axis into the air, but the gate is "has an axis", not "is the player".

turn is a state, not a delayed facing write. Reversing on the ground used to mirror the sprite on the same frame the axis flipped, so a pivot read as a teleport. The velocity curve was never the problem — it always took about a third of a second to cross zero. The picture refused to show any of it.

A delay would be a value every interrupter has to be told to undo, and each of them would have to know the rule exists. A state is entered and exited, so an attack, a dash or a jump taken mid-pivot leaves through PlayerTurnState.exit — which is where the facing is finally committed. "An attack inside the pivot still comes out where the player is pointing" is not a special case anyone has to remember.

The pivot is registered in every fighter's state machine under one shared name (Turn.STATE), and activation is decided by group and sub-group rather than by one entity at a time. Groups and sub-groups are named profiles in settings.PROFILES, layered by inheritance; every field is optional, and a field a layer leaves out is inherited.

# src/core/settings.py — all the enemies take it...
PROFILES["enemy"] = TurnProfile(inherits="default", enabled=True)
# ...except this one, which plants more slowly and leans further.
PROFILES["enemy_goblin"] = TurnProfile(inherits="enemy", brake_control=12.0, skew_px=28.0)
PROFILES["enemy_slime"] = TurnProfile(inherits="enemy", enabled=False)

// data/gameplay/enemies.json — which sub-group each type belongs to
{ "goblin": { "turn_profile": "enemy_goblin" } }

The world is drawn from three planes, split by one property: whether the sprite moves.

That split is what makes the index pay: leaving the tiles in all_sprites would force the renderer to walk all 839 of them every frame just to discover it had already drawn them. Measured on level 0: 0.22 ms against 0.28 ms for the scan; at 22 000 tiles, 0.07 ms against 2.67 ms. The tile layers stay in collision_sprites as before, so physics is untouched.

Anything that genuinely wants the whole world — the debug overlay, the sprite counter — reads SpriteGroups.every_sprite instead of one group. The index decides which sprites are worth asking about; Camera.is_visible still decides which are drawn, so a chunk can over-select but never under-select.

Attacks, enemies, the player and the level registry live in tracked JSON under data/gameplay/. These files are versioned — unlike assets/ — so balance changes are reviewable in a pull request. The frozen dataclasses stay the runtime model.

Loading is strict: unknown keys, missing fields, bad versions and unknown attack references raise GameplayDataError. A missing file falls back to the historical in-code values with a warning, so the game never refuses to boot over a data problem.

Environment variables

src/
├── application/   Scene stack, event bus, save game, settings store
│   └── scenes/    menu · level select · options · video · controls category ·
│                  controls · gameplay · pause · game over · victory
├── combat/        Frame data, hit resolver, knockback, charge and combo
│                  tracking (CombatSystem lives in core/level/systems/)
├── core/          Bootstrap (game.py), settings, paths, colors, object pool,
│                  hazards, sprites, sprite groups, asset library, audio
│   ├── animation/ Animator
│   ├── display/   Framing, letterbox, Viewport, Stage, Presentation, detection
│   ├── fx/        Draw, particles, spawners
│   ├── input/     Bindings, providers, managers, input state
│   ├── level/     Level facade + ordered fixed-tick systems
│   ├── rendering/ Camera (fixed framing + a density read off the target),
│   │              renderer, tile chunk index, world-overlay port
│   └── rollback/  Snapshot ring buffer and deterministic restore
├── data/          Strict JSON loaders + in-code fallback values
├── entities/      Entity base, player + controllers, projectiles, vitals,
│                  crouch posture
│   └── enemies/   Data-driven configs, factory, per-type behaviour
├── physics/       Collisions, gravity, movement, spatial hash, entity grid
├── states/        State machines (player, enemies, shared reactions, turn)
└── ui/            Player HUD, panels, world-space debug overlay
                   (dimensions in `world_overlay_metrics.py`, bars in
                   `world_overlay_bars.py`, menus in `metrics.py`)

data/gameplay/     Tracked JSON gameplay values
assets/            TMX levels and sprites — required at runtime
notes/             Refactoring plans, audit reports, measurements, open gaps

The frame loop is paced exactly once: with vsync off the Clock holds the frame limit, with vsync on the present already blocks on the vertical blank, so the clock is ticked only against a runaway ceiling derived from that rate. Targeting 60 on top of a 60 Hz present waits twice for one refresh and alternates between on time and one refresh late. The ceiling is a backstop, not a frame rate control, and it is derived rather than hardcoded so raising the limit can never leave it underneath. Display.FPS is a build target that feeds that ceiling — not the player-facing frame rate, which lives in settings_store.FRAME_LIMITS. A frame runs at most Simulation.MAX_TICKS_PER_FRAME ticks and the surplus is dropped.

The interface reaches the world by injection, not by import. The renderer takes a WorldOverlay and draws nothing beyond the world without one, so core never imports ui. GameplayScene does name UIManager concretely, which is the point: application is where the two layers are allowed to meet. tests/unit/test_layer_boundaries.py enforces the direction, so the next convenient import does not put it back.

• Typed code. mypy src main.py tools is blocking (disallow_untyped_defs = true, disallow_incomplete_defs = true) with no per-module override left in pyproject.toml. tests/ is excluded, on purpose.
• Formatted & measured. ruff format for style, C901 for cyclomatic complexity (threshold 10, every exception justified).
• Deterministic simulation. Fixed timestep (Simulation.TICK_RATE = 60). Nothing may introduce non-determinism into the tick.
• Centralized tuning. Gameplay constants live in src/core/settings.py — no magic numbers in the systems. A constant shared by two modules has exactly one home, and it belongs to the module that acts on it: HP-bar geometry is defined once in src/ui/world_overlay_metrics.py, which every layer that draws a bar reads, and it reaches the renderer through the WorldOverlay port rather than by core importing ui. Two copies agree only until someone edits one. UI-only constants (HUD_PIP_SIZE, HEALTH_BAR_*) stay in their UI module, and renderer internals (DASH_STRETCH_*) stay next to their only user.
• One table for the interface. src/ui/metrics.py holds every layout dimension of the menus as a DESIGN_* constant, and Metrics is the only thing that multiplies one by a scale. A view may not contain a layout literal. The reason is not tidiness: at a window density of 1.889 the grid used to pair a 49 px font with 34 px rows, so a clickable band covered 44 % of the label above it and clicking the row you read activated the row above.
• A row is never shorter than its text, at any scale, in any window. A list that does not fit gives up font size (down to MIN_TEXT_RATIO) instead, because smaller text is still readable while an overlapping row is not clickable at all. GridView measures the real fonts rather than trusting the design constants, since a fallback face has different metrics again.
• No dead menu options. User-facing hotkeys are mirrored by tests.

uv run pytest

Current baseline: 2491 tests · 94 % instruction coverage · 82 % branch coverage · Ruff clean · mypy clean (175 files across src main.py tools; mypy src alone is 172).¹

Tests run headless through the SDL_*_DRIVER=dummy variables, so they need no display. Coverage, from:

uv run pytest --cov=src --cov-report=term-missing --cov-fail-under=80
uv run pytest --cov=src --cov-branch --cov-report=term-missing

Branch coverage is measured but not gated: CI compares the instruction percentage against 80 % and nothing else. There is no [tool.coverage] section, so --cov-branch is opt-in per command.

Static analysis — every check below is blocking in CI (.github/workflows/build.yml):

uv run ruff check src tests main.py tools            # lint
uv run ruff format --check src tests main.py tools   # formatting
uv run mypy src main.py tools                         # types

C901 has no standalone CI step — it is enforced because it sits in the ruff select list consumed by the lint step. Ruff covers all four paths, 328 files.

tests/ is deliberately not type-checked, which is why the mypy command omits it.² The suite pins behaviour, not annotations, and test doubles are intentionally loose; Ruff does cover tests/. Do not add tests to the mypy command in build.yml without treating that debt first.

pre-commit runs the lint and format passes locally, auto-fixing rather than checking, and does not run coverage:

uv run pre-commit install   # once
uv run pre-commit run --all-files

tests/unit/test_readme_claims.py runs as part of the suite and re-checks this file: it recounts the collected tests and asserts that every test-count figure here equals the real one, and that the coverage badge and the coverage pair agree with each other. It checks internal consistency, not truth — keep this section in sync when the numbers move.

The game ships as a standalone PyInstaller bundle driven by knightrock.spec (it embeds assets/ and data/):

uv run --with pyinstaller==6.22.2 pyinstaller knightrock.spec --noconfirm --clean

.github/workflows/build.yml then:

1. runs tests, lint, format and mypy on every push / pull request to master;
2. builds knightrock-linux, knightrock-windows and knightrock-macos artifacts, with a headless smoke test that boots the packaged binary;
3. publishes a GitHub Release with those artifacts when a v* tag is pushed.

Written in French unless stated otherwise.