- Python 69.2%
- JavaScript 17.1%
- SourcePawn 9.3%
- Shell 2.8%
- PowerShell 0.6%
- Other 0.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ux3qS6w5gtR4j98wvh6Jin |
||
| .githooks | ||
| bin | ||
| decisions | ||
| docs | ||
| insights | ||
| server | ||
| tasks | ||
| tests | ||
| tools | ||
| viewer | ||
| .editorconfig | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| requirements.txt | ||
| ROADMAP.md | ||
| THIRD_PARTY.md | ||
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>(defaultc1m1_hotel)?data=<url>where the built maps are (defaultmaps); a viewer served elsewhere can read a local build fromhttp://127.0.0.1:8765/mapswhentools/serve.py --cors <its origin>runs?lm=<exposure>default lightmap/vertex light exposure (1)?tm=agx|aces|neutral|nonetone mapping,?ev=exposure after tone mapping?pos=x,y,z&ang=pitch,yawstart camera like the game'ssetpos/setang(Hammer units)?merge=0keep every mesh separate (no load-time merging, decision 0005)?cc=0colour correction off, whatever the lighting panel says (A/B measurements)?fl=0start with the flashlight off,?flshadow=0flashlight without shadows- stuck-spot overlay (
data/stuck.json,tools/stuck_probe.py <map> --publish), on by default,?stuck=0turns it off (?stuck=1from 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 givessetpos 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'ssetposin 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 /cliptag on candidates they only partly cover (experimental;tasks/stuck-spots/)
- Console:
viewer.setpos([x, y, z], [pitch, yaw])to compare with in-gamecl_showposscreenshots;viewer.traceMouse(seconds)records the next fly-mode session, logs a mouse/frame summary and resolves with the trace (also kept asviewer.mouseTrace);viewer.loadTimesholds the load phases;viewer.stuck.select(i)flies to stuck candidatei(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).
Legal
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.