HexGL

3D anti-grav racer, Catmull-Rom banked track, lap-attack, AI ghost.

▶ Run in browser

Upstream: https://github.com/BKcore/HexGL

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-2

HexGL: SimVX Port

A SimVX port of BKcore/HexGL (anti-grav 3D racer in the WipEout tradition).

Run

# from the repo root
uv run python examples/ports/hexgl/main.py            # interactive
uv run python examples/ports/hexgl/main.py --test     # headless capture sweep (8 PNGs into screenshots/)
uv run python examples/ports/hexgl/harness.py         # smoke harness (no graphics)
uv run simvx export web examples/ports/hexgl/main.py \
    -o /tmp/hexgl.html

Controls

The title screen starts the race on Space, Enter or a click; the race is fully playable with a mouse or a touchscreen.

Action	Keys	Pointer
Thrust	W / Up	hold left button
Steer left / right	A / D / Left / Right	slide the held pointer left / right
Brake	S / Down	right button
Air-brake left	Q / Left-Shift
Air-brake right	E / Right-Shift
Restart race	R
Quit	Esc

Track and ships

The track is procedurally generated from an 8-point Catmull-Rom spline, extruded along the curve into a banked floor + side walls. 6 virtual checkpoints, 3 emissive boost pads. The hull and ghost AI are built from SimVX Mesh.cone + Mesh.sphere primitives. No upstream assets are redistributed: upstream’s track meshes and HUD textures are CC-BY-NC.

Source files

File	Summary	Lines
main.py	HexGL: 3D anti-grav racer, Catmull-Rom banked track, lap-attack, AI ghost.	310
harness.py	SceneRunner-driven smoke harness for HexGL.	55
nodes/__init__.py	HexGL port nodes.	1
nodes/ai_ship.py	Ghost AI opponent: drives the centreline at a fixed pace.	74
nodes/camera.py	Racer chase camera: speed pull-back on a roll-free rig.	70
nodes/hud.py	Speedometer / shield / boost / lap timer HUD.	170
nodes/menu.py	Title screen: the port’s menu-first entry point.	88
nodes/race.py	Race manager: checkpoints, lap tracking, end-of-race state.	140
nodes/ship.py	Player ship: anti-grav with thrust, drift, roll, banked turning.	357
nodes/track.py	Procedural anti-grav race track.	352

Source

"""HexGL: 3D anti-grav racer, Catmull-Rom banked track, lap-attack, AI ghost.

# /// simvx
# tags = ["port", "tier-2"]
# upstream = "https://github.com/BKcore/HexGL"
# web = { width = 1280, height = 720, responsive = true }
# ///

A SimVX port of BKcore's HexGL. Nothing is loaded from disk: the track is a
closed Catmull-Rom spline extruded at runtime into a banked floor, side walls
and emissive boost pads. On top of it sit track-frame ship physics, a 3-lap
time-attack race, an AI ghost to chase, WorldEnvironment post-FX (bloom,
motion blur, exponential fog, ACES tonemapping) and a Text2D + on_draw HUD
layered over the 3D scene.

Controls: W/Up thrust, A/D or the arrow keys steer, S/Down brake, Q/E
air-brake, R restart, Esc quit. Mouse and touch play too: hold the left
button to thrust and slide left or right to steer, right button to brake.

Run:
    uv run python examples/ports/hexgl/main.py            # interactive
    uv run python examples/ports/hexgl/main.py --test     # headless capture sweep
"""

from __future__ import annotations

import sys
from collections.abc import Callable
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes.ai_ship import GhostShip  # noqa: E402
from nodes.camera import RacerCamera  # noqa: E402
from nodes.hud import HexHUD  # noqa: E402
from nodes.menu import TitleScreen  # noqa: E402
from nodes.race import RaceManager  # noqa: E402
from nodes.ship import Ship  # noqa: E402
from nodes.track import Track  # noqa: E402

from simvx.core import (  # noqa: E402
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
    Vec3,
    WorldEnvironment,
)
from simvx.graphics import App  # noqa: E402

WIDTH = 1280
HEIGHT = 720


def _make_environment_map() -> dict:
    """Return the WorldEnvironment.environment_map spec.

    If `assets/sky.hdr` exists, load it as an equirect HDR cubemap; otherwise
    return a procedural twilight gradient.
    """
    hdr_path = _PORT_DIR / "assets" / "sky.hdr"
    if hdr_path.exists():
        return {"path": str(hdr_path)}
    return {"colour": (0.04, 0.05, 0.10)}


class HexGLRoot(Node):
    """Root scene: Track + Ship + GhostShip + RacerCamera + RaceManager + HUD + title."""

    def on_ready(self) -> None:
        # Input: root.on_ready (web export skips main()). The pointer bindings
        # keep the web/touch build playable: touch arrives as MouseButton.LEFT.
        InputMap.add_action("thrust", [Key.W, Key.UP, MouseButton.LEFT])
        InputMap.add_action("brake", [Key.S, Key.DOWN, MouseButton.RIGHT])
        InputMap.add_action("steer_left", [Key.A, Key.LEFT])
        InputMap.add_action("steer_right", [Key.D, Key.RIGHT])
        InputMap.add_action("airbrake_left", [Key.Q, Key.LEFT_SHIFT])
        InputMap.add_action("airbrake_right", [Key.E, Key.RIGHT_SHIFT])
        InputMap.add_action("restart", [Key.R])
        InputMap.add_action("quit", [Key.ESCAPE])

        # Environment with race-feel post-FX. Bloom on emissive thrusters,
        # motion blur for speed, mild fog for depth.
        env = WorldEnvironment(environment_map=_make_environment_map())
        env.bloom_enabled = True
        env.bloom_threshold = 0.95
        env.bloom_intensity = 0.85
        env.tonemap_mode = "aces"
        env.tonemap_exposure = 1.05
        env.motion_blur_enabled = True
        env.motion_blur_intensity = 0.55
        env.motion_blur_samples = 12
        env.fog_enabled = True
        env.fog_mode = "exponential"
        env.fog_colour = (0.06, 0.08, 0.13, 1.0)
        env.fog_density = 0.008
        env.ambient_light_colour = (0.10, 0.12, 0.18, 1.0)
        env.ambient_light_energy = 0.7
        self.add_child(env)

        # Sun.
        sun = DirectionalLight3D(name="Sun", intensity=1.7)
        sun.colour = (1.0, 0.9, 0.78)
        sun.position = Vec3(40.0, 60.0, 30.0)
        sun.look_at(Vec3(0.0, 0.0, 0.0))
        self.add_child(sun)

        # Track.
        self.track = Track(width=14.0, length_segments=400, name="Track")
        self.add_child(self.track)

        # Player ship.
        self.ship = Ship(track=self.track, name="Ship")
        self.add_child(self.ship)

        # AI opponent: start about 10 % of the track ahead so the player overtakes.
        self.ghost = GhostShip(track=self.track, base_speed=58.0, t_offset=0.1, name="Ghost")
        self.add_child(self.ghost)

        # Chase camera: close enough to see hull detail, but high enough to see road.
        self.camera = RacerCamera(
            target=self.ship,
            distance=8.0,
            height=2.8,
            look_ahead=6.0,
            half_life=0.12,
            fov=68.0,
            near=0.1,
            far=600.0,
            name="ChaseCam",
        )
        self.add_child(self.camera)

        # Race manager. It stays idle until the title screen hands over.
        self.race = RaceManager(ship=self.ship, track=self.track, max_laps=3, name="Race")
        self.add_child(self.race)

        # HUD, then the title card on top of it.
        self.hud = HexHUD(ship=self.ship, race=self.race, name="HUD")
        self.add_child(self.hud)

        self.title = TitleScreen(name="Title")
        self.title.started.connect(self.begin_race)
        self.add_child(self.title)

    def begin_race(self) -> None:
        """Leave the title screen and arm the start lights."""
        self.title.active = False
        self.ship.reset()
        self.race.start()

    def on_update(self, dt: float) -> None:
        # The ship only answers to the controls once the lights are out.
        self.ship.controls_enabled = self.race.racing

        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if self.race.phase != "idle" and Input.is_action_just_pressed("restart"):
            self.ship.reset()
            self.race.start()


# -----------------------------------------------------------------------------
# Headless --test capture
# -----------------------------------------------------------------------------


def _run_headless() -> None:
    """Capture 8 staged screenshots with run_headless."""
    from simvx.graphics import save_png

    out_dir = _PORT_DIR / "screenshots"
    out_dir.mkdir(exist_ok=True)

    app = App(width=WIDTH, height=HEIGHT, title="HexGL (test)", visible=False)
    root = HexGLRoot()

    Stage = Callable[[HexGLRoot], None]

    # Stage schedule: (capture_frame_idx, description, mutator).
    stages: list[tuple[int, str, Stage]] = []

    def stage(idx: int, name: str, fn: Stage) -> None:
        stages.append((idx, name, fn))

    def racing(r: HexGLRoot) -> None:
        """Leave the title card and drop straight into the green flag."""
        r.begin_race()
        r.race.skip_countdown()

    # Frame 30: the title card over the lit track.
    stage(30, "01_title.png", lambda r: None)

    # Frame 90: thrust on a straight section.
    def go_straight(r):
        racing(r)
        r.ship.teleport(0.05, speed=50.0)
        r.camera.snap()

    stage(90, "02_straight.png", go_straight)

    # Frame 130: banked turn.
    def banked(r):
        racing(r)
        r.ship.teleport(0.30, lateral=2.0, speed=45.0)
        r.camera.snap()

    stage(130, "03_banked_turn.png", banked)

    # Frame 170: boost pad effect (mid-pad).
    def boosting(r):
        racing(r)
        r.ship.teleport(0.51, speed=60.0, boost=r.ship.booster_speed)
        r.camera.snap()

    stage(170, "04_boost.png", boosting)

    # Frame 210: AI overtake, ghost is just ahead, player drawing alongside on the inside.
    def overtake(r):
        racing(r)
        r.ship.teleport(0.42, lateral=-2.5, speed=65.0)  # inside lane
        r.ghost.teleport(0.425)  # slightly ahead, on the right
        r.camera.snap()

    stage(210, "05_ai_overtake.png", overtake)

    # Frame 250: lap completed UI, fake the race state.
    def lap_done(r):
        racing(r)
        r.ship.teleport(0.02, speed=55.0)
        r.race.lap = 2
        r.race.elapsed = 47.235
        r.race.best_lap = 47.235
        r.race.lap_times = [47.235]
        r.camera.snap()

    stage(250, "06_lap_complete.png", lap_done)

    # Frame 290: final straight, high speed motion blur showcase.
    def final_straight(r):
        racing(r)
        r.ship.teleport(0.92, speed=72.0, boost=r.ship.booster_speed)
        r.camera.snap()

    stage(290, "07_final_straight.png", final_straight)

    # Frame 330: race finished UI.
    def finished(r):
        racing(r)
        r.ship.teleport(0.0, speed=25.0)
        r.race.lap = 3
        r.race.elapsed = 142.18
        r.race.best_lap = 47.235
        r.race.lap_times = [47.235, 47.5, 47.4]
        r.race.dnf = False
        r.race.phase = "finished"
        r.camera.snap()

    stage(330, "08_finish.png", finished)

    capture_frames = [s[0] for s in stages]
    schedule: dict[int, Stage] = {}
    for capture_idx, _name, mutator in stages:
        # Run the mutator a few frames *before* the capture so physics catches up.
        schedule[max(0, capture_idx - 4)] = mutator

    total_frames = max(capture_frames) + 4

    def on_frame(idx, _t):
        fn = schedule.get(idx)
        if fn is not None:
            try:
                fn(root)
            except Exception as exc:  # don't crash the sweep
                print(f"[--test] stage at frame {idx} failed: {exc!r}")
        return None

    captured = app.run_headless(
        root,
        frames=total_frames,
        capture_frames=capture_frames,
        on_frame=on_frame,
    )

    for (_idx, name, _fn), img in zip(stages, captured, strict=False):
        # The captured frame keeps the blended destination alpha; force it opaque
        # so the PNG is not written half-transparent.
        try:
            img[..., 3] = 255
        except Exception:
            pass
        save_png(img, out_dir / name)
        print(f"saved {out_dir / name}")


def main() -> None:
    if "--test" in sys.argv:
        _run_headless()
        return
    app = App(width=WIDTH, height=HEIGHT, title="HexGL (SimVX)")
    app.run(HexGLRoot())


if __name__ == "__main__":
    main()