raycast: a first-person ray caster on intuiTUIve¶

Round 1: rs-rich raycaster¶

The demo is examples/raycast/, an original first-person shooter in the style of the early-90s ray casters (no id Software assets or names: the levels, textures, sprites and face are generated in code). The algorithm follows Lode Vandevenne's raycasting tutorial (DDA, camera plane, floor casting, sprite projection against a z-buffer), with Wolfenstein-style doors: a thin plane across the middle of the cell that slides into the wall, and a jamb texture on the walls beside it.

What was built (2,924 lines: game.rs 1,005, the model with no framework in it; art.rs 677, procedural textures and sprites; render.rs 271, the ray caster into an RGB framebuffer; view.rs 295, the framebuffer on screen; main.rs 676, the app; tests 593 lines in tests/raycast.rs, 26 tests):

• The 3D view: textured walls (brick, stone, wood, tech panels, a door with a hazard stripe, its jamb, an EXIT switch) with distance fog and darker east-west faces; floor and ceiling cast with textures (or --flat: flat colours fading into the dark); sprites billboarded and depth-sorted against the z-buffer (barrels, columns, hanging lamps, ammunition, medikits, armour, and a hooded sentry with standing, two walking, firing, hurt and three dying frames); the pistol bobbing as the player walks, its muzzle flash lighting the room; red when hurt, gold on a pickup.
• Gameplay: two hand-made levels as strings (E1 Hangar, E2 Depot); doors opened with Space that close by themselves unless something stands in them; hitscan shooting along the view's centre; pickups; enemies that wake on sight, react after a moment, walk at the player and fire with a hit chance by distance; armour soaking a third; an exit switch; death and a tally (kills, items, time); a seeded generator so a test sees the same fight.
• Everything round the view is intuiTUIve nodes: the status bar (digits for ammunition, health and armour in panels, the face as a renderable of rs-rich-art's ImageArt, a text with the level, the time, kills and items, and the frame rate from the core's rate); the map (Tab, a text of markup in a panel placed over the view with layers and .place); the pickup message; the title (big_text, over the first level turning slowly); the level-done, dead and cleared boxes (switch on the state); the pause menu (cx.modal); help (App::help_key("?") from the .bind_in descriptions) and the palette.
• Keys: W/↑ S/↓ walk, A/← D/→ turn, Q/E (Alt+←/→, , .) strafe, capitals run, F or Ctrl+F fires, Space uses, Enter starts and goes on, Tab the map, Esc pauses, ? keys, Ctrl+Q quits; 1 and 2 on the title pick a level.
• Display modes (--mode): blocks (half blocks, two pixels a cell, the default), quadrants, braille, kitty and iterm (real pixels, 4×8 a cell), auto (rs-rich-ext's GraphicsEnvironment::detect: Kitty or iTerm2 when found, else half blocks; Sixel is detected but cannot be drawn, see below). The Kitty and iTerm2 modes are tested headless (the escapes are sent each frame, cells drawn under overlays) but have not been seen in a real Kitty, WezTerm or iTerm2 yet.
• The clock: one every(TIC) at 35 Hz, Doom's tic. In a test each tick is one tic, so Driver::advance(TIC * n) steps the game exactly; run for real (Options::realtime), each tick runs the tics owed by the wall clock, five at most, so a slow frame drops frames, not game time. --uncapped draws on every turn of the loop to measure the cost; --bench SECS walks round by itself and prints the frame rate.
• The tape: docs/tapes/raycast.tape (title, start, map, keys and pause menu as checked screenshots; then the walk to the door, the door opening, the sentry coming through it and the fight, in the cast and the GIF, docs/media/tapes/raycast/raycast.gif). rich record --check passes twice in a row.

Bespoke drawing, and why: the 3D view itself. It is a framebuffer of RGB bytes rendered each tic by the example (render.rs), as any ray caster's is; nothing in a widget library draws a 3D scene. Getting it on screen is not bespoke in the cell modes (rs-rich-art's ImageArt rendered on a Widget's canvas), but is in the pixel modes: the Kitty and iTerm2 escapes and the PlacementSource are written in view.rs, because the art feature exposes neither (see the gaps). The view is a Widget of its own for one more reason: key releases reach widgets only. The Braille mode dithers the frame first (a 4×4 Bayer pass, 15 lines), because rs-rich-art's Braille has no colour and a fixed threshold.

Frame rate (--bench 5, the auto-walk, a real PTY, the reader only draining it; frames a second; capped is one frame a tic, at most 35):

(The columns after the first are uncapped.) The ray caster is not the cost: 0.08 ms a frame at 80×38 and 0.39 ms at 160×90 in release (0.05 and 0.2 ms flat). At 160×50 in half blocks a frame costs about 41 ms in release, of which ImageArt is 7 ms and intuiTUIve's canvas, screen diff and painter the rest (callgrind: 35% Screen::write_lines, 31% StyleTable::intern, mostly SipHash over Styles, 23% Painter::paint, 14% Screen::underlay, then malloc/free and Style::clone). Braille and the pixel modes are fast because they write few or no styled cells. The floor cast stays on by default: it costs a fraction of a millisecond.

Left out: sound (no output in the audio plugin yet); mouse-look (no pointer lock or relative motion); a gamepad; more weapons, secrets, keys and locked doors; Sixel (see the gaps); a status bar drawn as one pixel picture, as the originals' is.

New gaps and bugs¶

Friction with the existing APIs¶

• A model that is not a signal (as blocks found): the game lives in an Rc<RefCell<Game>>, every handler mutates it, and the timer renders and writes a Signal<Rc<Frame>> with replace (a frame never equals the last, so set's comparison would only cost) and a Signal<Hud> with set, which redraws the status bar only when what it shows changed.
• A widget only for releases. The view had to be a Widget anyway, but a game whose view were a stock node would need one just to hear KeyUp.
• Overlays over pixels. A Kitty or iTerm2 picture is drawn after the cells, so the map, the pause menu and the end boxes would be painted over by it. The example draws the view in half blocks while anything covers it (and gives Kitty's image a z-index below cells with a background); a PlacementSource told the rectangles of the layers over its placement could clip instead.
• App::graphics is set outside App::new. The source is built before the app and shares state with the view through an Arc<Mutex<..>>; the view finds its own rectangle through a RectHandle made before it.
• layers are opaque, and .place sizes a layer to its content: an empty message drew a padded blank cell over the view until the padding moved into the text.
• Timers per screen. The game's every keeps running under the pause modal (the screen below keeps drawing), so pausing is the model's flag.
• The test clock is excellent. With catch-up off, `Driver::advance(TIC
• n)` steps the game exactly, so tests assert on the framebuffer (the centre column's wall and distance, a pixel's colour), on the HUD text and accessibility names, and that the same keys give the same frame bytes.

Components that would help¶

Comparable libraries: ratatui games draw a framebuffer as half blocks straight into the Buffer (or through Canvas), and use ratatui-image for Kitty, Sixel and iTerm2 (a StatefulImage widget whose Picker queries the terminal and picks the protocol, half blocks as the fallback): that crate is the pixel surface above. Textual's textual-image does the same for Textual; Bubble Tea has no pixel widget. None of them reports key releases without the kitty protocol; terminal games everywhere latch presses as this one does.

Round 2: rebuilt on round 6¶

The example went from 2,924 lines to 2,891 (main.rs 676 → 662, view.rs 295 → 276; game.rs, art.rs and render.rs unchanged), and tests/raycast.rs from 593 lines to 652 (26 tests to 28). Two bugs found while recording it are fixed in the example, each with a test that fails on round 1's code.

Bugs fixed (example bugs, not library ones)¶

• Kitty mode showed nothing. The image is placed at a z below -2^30, which Kitty draws under every cell that has a background colour, and the root's .style("on #101018") gave every cell of the view one. The z is right (the level's name over the view, in a box with a background, still covers the image); the background moved from the root to the status bar, so the view's cells keep the terminal's own. The map's panel takes on #101018 itself. Test: the_kitty_view_keeps_the_terminals_background (no background in the view's rows but the level-name box; the status bar keeps it).
• An arrow counted as held only after the app had seen a release for it, so until then each press was latched for 8 tics. A movement key is now held from its first press wherever its release will be reported (cx.key() and cx.releases_reported().reported(&key)), until its on_key_up; where none will come (a legacy terminal, or a letter without every key reported) it is latched as before, the terminal's repeats extending it. The app asks for every key (App::all_keys), so under the kitty protocol W/A/S/D are held too, and Shift let go stops running (on_key_up("shift")). Tests: a_key_whose_release_is_reported_is_held_from_its_first_press (replaces a_key_seen_let_go_is_held_until_it_is_released, whose behaviour was the bug) and with_every_key_reported_letters_are_held_and_shift_runs.

Replaced by components¶

The test suite runs in about half the time (2 s instead of 4.5 s in a debug build), the cells now going through the pixel path.

Changed look: Braille is now drawn in two colours a cell (the pixels node's) instead of a dithered black and white; shapes read as before and the scene keeps its colours.

Still hand-built, and why¶

• The pixel view and its PlacementSource (view::Pixels, the PNG encoding and the Kitty and iTerm2 escapes): the pixels node draws cells only; the art plugin's image_bytes_of draws Kitty (by placeholders), Sixel and iTerm2 but takes encoded image bytes and is not built for 35 new pictures a second.
• The latch in game.rs (Held, FIRST_LATCH, REPEAT_LATCH) for keys whose release will not come. held_keys() holds only keys whose release is known (or made up by synthesize_releases, whose hold must outlast the terminal's repeat delay, about 500 ms, far too long for a tap in a game), so the model keeps both kinds in one place. Since 0.0.22, synthesize_releases_with(Holds::new(first, repeat)) lets go soon after the last repeat, as the latch does.
• Pausing is still the model's flag: the modal's screen keeps the game's timer, so Timer::pause would only save the stepping it does not do.
• The bench's frame count and first-frame Instant (it counts frames rendered from the first one, which StatsHandle does not).

New gaps¶

Bugs found in the library¶

None this round. (App::all_keys and the release bindings worked as the guide says; the driver's set_releases made both fixes testable.)

Components that would help¶