No description
  • Python 69.2%
  • JavaScript 17.1%
  • SourcePawn 9.3%
  • Shell 2.8%
  • PowerShell 0.6%
  • Other 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
mwiegand 849b5b6807
docs: keep project findings out of the team memory
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ux3qS6w5gtR4j98wvh6Jin
2026-10-10 22:22:03 +02:00
.githooks chore: reject game assets and build outputs in commits 2026-10-02 13:50:59 +02:00
bin docs(server): Windows client VM build guide and bin/win wrapper 2026-10-03 17:33:33 +02:00
decisions docs(decisions): 0020 — no candidate filter may lose a warp, cuts only from the mechanism 2026-10-04 13:38:18 +02:00
docs feat(stuck): verdict v2 — separate start, coverage, geometry and mechanism axes 2026-10-05 12:21:28 +02:00
insights docs(stuck): insight 0054 — the rounding coin: stored plane and per-face float residue 2026-10-05 03:32:34 +02:00
server docs(warp_test): 1.22 tr move covers the forward probe and StayOnGround only 2026-10-05 00:48:15 +02:00
tasks docs(tasks): coordinator handoff — midday state, server on c13m4, owner's open choices 2026-10-05 13:58:36 +02:00
tests feat(stuck): verdict v2 — separate start, coverage, geometry and mechanism axes 2026-10-05 12:21:28 +02:00
tools feat(stuck): verdict v2 — separate start, coverage, geometry and mechanism axes 2026-10-05 12:21:28 +02:00
viewer fix(viewer): infer tap / contact from stuck_t0, not from a 10 s warp_after 2026-10-04 15:18:36 +02:00
.editorconfig feat: static prop vertex lighting, modular viewer, build script 2026-10-01 21:11:32 +02:00
.gitignore chore: reject game assets and build outputs in commits 2026-10-02 13:50:59 +02:00
AGENTS.md docs: keep project findings out of the team memory 2026-10-10 22:22:03 +02:00
CLAUDE.md docs: add README, agent instructions, insights and decisions 2026-10-01 21:03:37 +02:00
LICENSE docs: MIT licence and third-party notices 2026-10-02 13:56:43 +02:00
Makefile feat(tools): make bench — frame cost A/B in headless Chrome 2026-10-02 17:02:26 +02:00
README.md feat(viewer): hide untested candidates the verified rules predict no warp for 2026-10-04 12:56:49 +02:00
requirements.txt feat!: data format 5 — KTX2 (UASTC) textures 2026-10-02 16:29:44 +02:00
ROADMAP.md docs(tasks): verify bot-ai sources in a browser and link the task 2026-10-03 19:57:21 +02:00
THIRD_PARTY.md feat!: data format 5 — KTX2 (UASTC) textures 2026-10-02 16:29:44 +02:00

L4D2 WebGL Map Viewer

Proof of concept: convert Left 4 Dead 2 maps (Source engine BSP v21) into browser-friendly assets and fly through them in WebGL, with item spawns (pills, defibs, laser sights, …) shown as markers. Long-term goal: a site where anyone can add points of interest to a map.

Currently converted: c1m1_hotel (Dead Center 1) and c2m1_highway (Dark Carnival 1, the current test map). Open items: ROADMAP.md; the structural work in progress: docs/refactoring-plan.md.

Pipeline

BSP (Steam install) ──► Blender + SourceIO ──► assets/world.glb (geometry, props, overlays)
        │                                 ├─► ../textures/<sha256>-<enc>.ktx2 (UASTC, shared by all maps)
        │                                 ├─► assets/lightmap.exr  (baked brush/displacement lighting)
        │                                 └─► assets/vlight.bin/.json (static prop vertex lighting)
        ├─► tools/export_pois.py ──► data/pois.json (spawns per game mode, sun, fog)
        ├─► tools/export_skybox.py ─► assets/sky/*.png (2D skybox faces)
        └─► tools/export_details.py ─► assets/detail.png/.bin/.json (grass sprites)
                 all in viewer/maps/<map>/ with manifest.json; viewer/maps/index.json lists the maps
                                          │
                                          ▼
                              viewer/index.html (three.js)
Step Script Notes
Import BSP tools/import_map.py SourceIO, ~10 s; writes work/<map>.blend, cached until the BSP, its .lmp files or the import tools change (work/<map>.import.json)
Export GLB tools/export_glb.py loads props as instances, strips tool brushes, builds overlays (tools/overlays.py), rebuilds materials (tools/gltf_materials.py), poses skinned props (tools/prop_pose.py), tags game modes and doors, bakes lighting data; ~45 s
Lighting data tools/apply_lightmaps.py, tools/bsp_lightmaps.py, tools/static_prop_lighting.py, tools/bsp_lighting.py lightmap atlas + UVs, static prop vertex lighting (VHV), ambient cube + world lights for dynamic props; called by export_glb.py
Game modes tools/game_modes.py which entities exist per mode (per-mode .lmp, point_template, info_gamemode I/O; insight 0014); used by the GLB and POI export
BSP readers tools/bsp.py, tools/bsp_entities.py, tools/bsp_extras.py bsp.py: the one lump reader (LZMA lumps, game lumps, pakfile, .lmp headers, face/texinfo/displacement structures); entity lump / .lmp (CLI prints JSON), overlays and detail props; numpy only
Game content tools/source_assets.py SourceIO content manager, VMT and VTF loading shared by the Blender steps
POIs tools/export_pois.py stdlib only, reads the per-mode entity lumps (update/maps/*.lmp, fallback BSP lump)
Skybox tools/export_skybox.py decodes HDR sky VTFs via SourceIO's library in plain Python (no Blender; finds the add-on in Blender's add-on folder or SOURCEIO_ADDONS)
Detail sprites tools/export_details.py game lump dprp + the worldspawn detail material; plain Python like the skybox
Serve tools/serve.py 127.0.0.1:8765, sends Cache-Control: no-cache (shared textures: immutable)
Spawn table tools/spawn_summary.py [--mode M] <maps dir> pills/defib/laser counts per map and game mode, from the same POIs as the viewer
SourceIO setup tools/enable_sourceio.py one-time: enables the installed SourceIO add-on and saves the Blender preferences
Diagnostics tools/diag/*.py the measurements the insights cite (displacement seams, detail light, blend materials, game-mode and lump surveys); see each script's docstring
All of the above tools/build_map.py one command per map
Repository check tools/check_repo.py rejects game assets and build outputs (pre-commit hook in .githooks/)

Running it

make hooks                             # once per clone: reject game assets in commits
tools/build_map.py c1m1_hotel          # import (if needed), export, lighting, POIs, skybox
tools/build_map.py c1m1_hotel --skip-export   # only POIs, skybox and detail sprites
tools/build_map.py --campaign c1 --jobs 2      # several maps (or --all); a table at the end
tools/serve.py                         # then open http://127.0.0.1:8765/?map=c1m1_hotel
make test                              # unit tests (Python without Blender, Node), seconds
make check                             # tests + repository check + JS syntax
make bench B=merge=0                   # frame cost, viewer against a variant (headless Chrome; make serve)

L4D2_DIR and BLENDER override the default game and Blender paths (defaults: Steam's library on macOS, ~/.local/share/Steam on Linux, untested). A full build takes ~1 minute per map; logs go to work/, each step's summary numbers to work/<map>.stats.json. With --jobs N each map runs its own Blender process (peak ~3.4 GB each, campaign 1 with 2 jobs: 108 s for 4 maps); a failed map does not stop the others. --debug-blend also keeps the exported scene as work/<map>_export.blend for the diagnostic scripts.

Requirements: Blender 5.2 with SourceIO 5.5.4 enabled, L4D2 installed via Steam, Python 3 with numpy and Pillow (requirements.txt), basisu 2.50 for the KTX2 textures (brew install basis_universal; BASISU to point elsewhere), Node for the viewer tests. The pipeline refuses other Blender or SourceIO versions, because it patches SourceIO internals (tools/sourceio_patches.py; SOURCEIO_UNCHECKED=1 to try anyway).

One-time SourceIO setup: install SourceIO-5.5.4.zip as a Blender add-on (Preferences → Add-ons → Install from Disk), then enable it for headless runs:

/Applications/Blender.app/Contents/MacOS/Blender -b --python tools/enable_sourceio.py

Source paths in the insights (library/..., blender_bindings/...) refer to SourceIO 5.5.4. The unpacked copy in tools/x/SourceIO-master (ignored) is that version: its files are identical to the installed add-on (checked with diff -rq -x __pycache__ on 2026-10-02).

Viewer

  • Click or press WASD to fly: WASD, mouse look, Space up, C/Ctrl down, Shift 3× speed; Q or Esc releases the mouse.
  • Markers can be clicked in and outside fly mode; a click flies to the marker and stops in front of walls. A dashed ring marks a random spawn, a white halo a marker in plain view.
  • Top right: map picker (every built map from maps/index.json, by campaign and chapter with the game's names; switching reloads with ?map=, keeping the other parameters), game mode selector (Coop, Versus, Survival, Scavenge: filters spawns and mode-specific geometry) with a "Versus (player-controlled infected)" checkbox for the stuck spots' TLS clip set (preset by the mode, then free) and spawn filter; both remembered per browser.
  • Lighting panel (bottom right): exposure and shadow lift (default 0.04), applied identically to lightmaps, prop vertex lighting and ambient cubes; distance fog strength (default 0.75); the map's colour correction on/off (default on); doors on/off; raw mouse input on/off. Remembered per browser.
  • Mouse look: frames without a mouse sample are filled automatically when the mouse reports slower than the display refreshes (insight 0020); the HUD shows gap fill on/off (mouse N vs M fps).
  • F: flashlight with shadows (a spot light from just right of and below the eye; on at start).
  • HUD: map name, frame rate, frame interval and CPU time per frame, draw calls, mouse event rates while turning.
  • URL parameters:
    • ?map=<name> (default c1m1_hotel)
    • ?data=<url> where the built maps are (default maps); a viewer served elsewhere can read a local build from http://127.0.0.1:8765/maps when tools/serve.py --cors <its origin> runs
    • ?lm=<exposure> default lightmap/vertex light exposure (1)
    • ?tm=agx|aces|neutral|none tone mapping, ?ev= exposure after tone mapping
    • ?pos=x,y,z&ang=pitch,yaw start camera like the game's setpos/setang (Hammer units)
    • ?merge=0 keep every mesh separate (no load-time merging, decision 0005)
    • ?cc=0 colour correction off, whatever the lighting panel says (A/B measurements)
    • ?fl=0 start with the flashlight off, ?flshadow=0 flashlight without shadows
    • stuck-spot overlay (data/stuck.json, tools/stuck_probe.py <map> --publish), on by default, ?stuck=0 turns it off (?stuck=1 from older links still works and reports a missing file): by default only the confirmed engine warps that no reachability check rules out (decision 0018: player verdict, inside terrain, bot walk, far from nav, nav island; one switch per check, plus "not measured", shows those again, tagged) and the owner's ground-truth spots; further switches in the same list show every warp whatever the checks say, the tested candidates without a warp, the untested ones, the untested ones the verified rules predict no warp for (decision 0018 addendum 2; all three within the top N) and the TLS spots. A warp is drawn as its replay: a small disc at the start (where the validator's player stood), one arrow to where the walk stopped, the standing hull there (head band in the overhang green); selecting it shows the steps to reproduce it, a "player view" button puts the camera at the player's eye on the start, and the copy button gives setpos x.x y.y z.z; setang 0 yaw 0 (tasks/stuck-spots/viewer-replay-design.md). The pocket box and mouth arrow stay for the candidates without a warp. Hull boxes (crouched part blue, blocked standing part orange), a list that flies to a candidate, ] / [ step through the listed ones, the candidate's setpos in the HUD and tooltip; pockets the TLS script clips close in grey behind the panel's "Closed by TLS" box (off by default), a grey dot / clip tag on candidates they only partly cover (experimental; tasks/stuck-spots/)
  • Console: viewer.setpos([x, y, z], [pitch, yaw]) to compare with in-game cl_showpos screenshots; viewer.traceMouse(seconds) records the next fly-mode session, logs a mouse/frame summary and resolves with the trace (also kept as viewer.mouseTrace); viewer.loadTimes holds the load phases; viewer.stuck.select(i) flies to stuck candidate i (0-based, unless ?stuck=0).

Layout

Path Content
tools/ conversion scripts (Blender steps and stdlib/numpy helpers); tools/diag/ the measurements the insights cite
tests/ unit tests without Blender (make test); golden counts against a local install
docs/ data contract between pipeline and viewer, refactoring plan
viewer/ static web viewer: js/ modules (main.js UI and render loop, load-map.js load steps, sky.js, fog.js, bake-data.js, baked-materials.js, marker-glow.js, markers.js, details.js, batching.js, controls.js, modes.js; pure helpers with Node tests: config.js, angles.js, stacks.js, mouse-filler.js), css/; viewer/maps/ holds generated assets (gitignored)
work/ intermediate .blend files and logs (gitignored)
insights/ findings: how the formats and tools actually behave
decisions/ decisions with the rejected alternatives

Known limitations

  • Textures are KTX2/UASTC in a folder shared by all maps (insights 0022, 0023); geometry is not compressed (Meshopt deferred, insight 0025).
  • No 3D skybox (city skyline); bump-mapped lightmaps use the mean of the three basis maps, not the per-pixel normal.
  • Dynamic props get an engine-style ambient cube plus world lights, without per-pixel normal mapping.
  • Some L4D2-specific shaders (dead bodies) have no texture after SourceIO import; infected are rebuilt from the base texture (insight 0018).

Map data, models and textures belong to Valve. Generated assets stay local and are not committed or published (decision 0009). The code is MIT-licensed (LICENSE); third-party components: THIRD_PARTY.md.