luckeyfaraday / swbf2-browser-reconstruction

# SWBF2 Browser Reconstruction
Tools for rebuilding **Star Wars Battlefront II (2017)** maps in a web browser from **your own installed copy of the game**. The pipeline reads the installed data (read-only), converts meshes, textures, collision, lighting, animations, sounds and gameplay values into browser formats, and a three.js runtime plays them back.
The reference target is **Death Star II — Command Sector North** with Blast (team deathmatch) and Free for All, original trooper models, first-person arms, E-11 / A280 rifles, bots, and a playable **Darth Vader** (saber combos, block/deflect, Force choke, saber throw, Focused Rage) built from the game's own animation and kit data.
> **No game content is included in this repository.** You need a legitimately owned, installed copy of Star Wars Battlefront II. Everything the tools extract stays on your machine under ignored folders (`exports/`, `web/public/assets/`). Do not redistribute extracted files.
This is research-grade software: the reconstruction is checked against the original data wherever possible (decoders are cross-checked against independent implementations, native shader math against the original bytecode run on WARP), and every remaining guess is labelled in the code and docs. It is not a finished game and not a port of the original engine.
## What the pipeline does
| Stage | Tools | Docs |
| --- | --- | --- |
| Archive index, selective EBX/RES/chunk export, meshes, textures, map placement, collision | `tools/bf2-extract` (C# adapter on Frosty Editor 1.0.5.2) | `tools/bf2-extract/USAGE.txt` |
| Exact shader-section material binding; hand-written reimplementations of the map's material math; static lighting atlases, probes, reflections, exposure, bloom, shadows | `tools/materials` | `tools/materials/README.md` |
| Native render LODs | `tools/lod-recovery` | `tools/lod-recovery/README.md` |
| Characters: skinned meshes on the source skeleton, ANT animation decoding (raw and DCT codecs), first-person rigs | `tools/characters` | `PROGRESS.md`, `VADER.md`, `VADER-ANIMATION.md` |
| Audio: EA XAS and EALayer3 decoding | `tools/audio` | `PROGRESS.md`, `VADER.md` |
| Gameplay values from EBX (weapons, heat, recoil, round rules, hero kits) | `tools/gameplay-recovery` | `README.md`, `vader-evidence.md` |
| Browser runtime, tests and GPU checks | `web/` | `web/README.md` |
The order in which to run them is in **docs/PIPELINE.md**. There is no single "build everything" command yet; each stage documents its own commands and checks.
## Requirements
- Windows 10/11 (the extractor and several reference checks are Windows-only).
- Star Wars Battlefront II (2017) installed. The tools were developed against the final PC patch; the extractor's schema is pinned to Frosty's `StarWarsBattlefrontII` profile (DataVersion 20171117). Set `BF2_GAME_DIR` if your install is not at `C:\Games\Star Wars - Battlefront 2`.
- Frosty Editor **1.0.5.2** unpacked to `tools/frosty-1.0.5.2/` (download it yourself; it is not b