HexGL

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

▶ Run in browser

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

Tags: port tier-2

HexGL: SimVX Port

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

Run

# Interactive (Vulkan window)
uv run python ported_games/hexgl/simvx_port/main.py

# Headless capture sweep: writes 8 PNGs into screenshots/
uv run python ported_games/hexgl/simvx_port/main.py --test

# Smoke harness (no graphics)
uv run python ported_games/hexgl/simvx_port/harness.py

# Web export (single HTML)
uv run simvx export web ported_games/hexgl/simvx_port/main.py \
    -o ported_games/hexgl/simvx_port/web/index.html

Controls

Action	Keys
Thrust	W / Up
Brake	S / Down
Steer left / right	A / D / Left / Right
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

"""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 }
# ///

Run:
    uv run python ported_games/hexgl/simvx_port/main.py            # interactive
    uv run python ported_games/hexgl/simvx_port/main.py --test     # headless capture
"""

from __future__ import annotations

import math
import sys
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 ChaseCamera  # noqa: E402
from nodes.hud import HexHUD  # 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,
    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 (P5);
    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 + ChaseCamera + RaceManager + HUD."""

    def on_ready(self) -> None:
        # Input: root.on_ready (web export skips main()).
        InputMap.add_action("thrust", [Key.W, Key.UP])
        InputMap.add_action("brake", [Key.S, Key.DOWN])
        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 = ChaseCamera(
            target=self.ship,
            distance=8.0,
            height=2.8,
            lerp=6.0,
            look_ahead=6.0,
            fov=68.0,
            near=0.1,
            far=600.0,
            name="ChaseCam",
        )
        self.add_child(self.camera)

        # Race manager.
        self.race = RaceManager(ship=self.ship, track=self.track, max_laps=3, name="Race")
        self.race.start()
        self.add_child(self.race)

        # HUD on top.
        self.hud = HexHUD(ship=self.ship, race=self.race, name="HUD")
        self.add_child(self.hud)

    def on_process(self, dt: float) -> None:
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if 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 schedule: (capture_frame_idx, description, mutator).
    stages: list[tuple[int, str, callable]] = []

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

    # Frame 30: spawn, first proper render after the countdown banner shows.
    stage(30, "01_spawn.png", lambda r: None)

    def _force_running(r):
        """Skip countdown so the GO! banner clears for screenshots after stage 1."""
        r.race._countdown = -1.0
        r.race.race_started = True

    # Frame 90: thrust on a straight section.
    def go_straight(r):
        _force_running(r)
        r.ship.t = 0.05
        r.ship.lateral = 0.0
        r.ship.speed = 50.0
        r.ship._sync_world_transform()
        r.camera._smoothed_pos = None  # snap camera to new position
        r.camera._smoothed_target = None
    stage(90, "02_straight.png", go_straight)

    # Frame 130: banked turn.
    def banked(r):
        _force_running(r)
        r.ship.t = 0.30
        r.ship.lateral = 2.0
        r.ship.speed = 45.0
        r.ship._sync_world_transform()
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(130, "03_banked_turn.png", banked)

    # Frame 170: boost pad effect (mid-pad).
    def boosting(r):
        _force_running(r)
        r.ship.t = 0.51
        r.ship.lateral = 0.0
        r.ship.boost = r.ship.booster_speed
        r.ship.speed = 60.0
        r.ship._sync_world_transform()
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(170, "04_boost.png", boosting)

    # Frame 210: AI overtake, ghost is just ahead, player drawing alongside on the inside.
    def overtake(r):
        _force_running(r)
        r.ship.t = 0.42
        r.ship.lateral = -2.5  # inside lane
        r.ghost.t = 0.425  # slightly ahead, on the right
        r.ghost._sync_world_transform()
        r.ship.speed = 65.0
        r.ship._sync_world_transform()
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(210, "05_ai_overtake.png", overtake)

    # Frame 250: lap completed UI, fake the race state.
    def lap_done(r):
        _force_running(r)
        r.ship.t = 0.02
        r.ship.lateral = 0.0
        r.ship.speed = 55.0
        r.ship._sync_world_transform()
        r.race.lap = 2
        r.race.elapsed = 47.235
        r.race.best_lap = 47.235
        r.race.lap_times = [47.235]
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(250, "06_lap_complete.png", lap_done)

    # Frame 290: final straight, high speed motion blur showcase.
    def final_straight(r):
        _force_running(r)
        r.ship.t = 0.92
        r.ship.lateral = 0.0
        r.ship.speed = 72.0
        r.ship.boost = r.ship.booster_speed
        r.ship._sync_world_transform()
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(290, "07_final_straight.png", final_straight)

    # Frame 330: race finished UI.
    def finished(r):
        _force_running(r)
        r.ship.t = 0.0
        r.ship.lateral = 0.0
        r.ship.speed = 25.0
        r.ship._sync_world_transform()
        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.race_ended = True
        r.race.dnf = False
        r.camera._smoothed_pos = None
        r.camera._smoothed_target = None
    stage(330, "08_finish.png", finished)

    capture_frames = [s[0] for s in stages]
    schedule: dict[int, callable] = {}
    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):
        # Force opaque alpha: Wave 2 rollup: alpha-blend dst factor truncates.
        try:
            img[..., 3] = 255
        except Exception:
            pass
        save_png(out_dir / name, img)
        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()


# Silence unused-import warnings for type-only imports on cold scenes.
_ = math