Warcraft 3 Replay Viewer — a visual replay analyzer, pro build library, and compare-to-pro coach for Warcraft III.

🌐 Live: wc3v.com — drop a .w3g, parsed locally in your browser, never uploaded.

Three things, all from a .w3g replay file:

1. Visual replay — reconstructs unit movement, building construction, hero levels, research, and combat from raw player inputs and renders them on a 3D heightmap with synced supply-indexed build order timeline.
2. Pro build library — 16 curated competitive builds across all races and matchups, each backed by real pro replays from 12+ tournaments. Filterable by race, matchup, opener, and tournament.
3. Compare to a pro — drop your replay, get auto-matched against the closest pro game by race/matchup/opener, then see letter-graded feedback on macro, production, item economy, idle resources, build order, tech, and hero skill choices — with itemized findings and supply curves overlaid.

Three new entry points into the same library, depending on where you are in your WC3 journey — pick a skill band in the top nav, hit Guide me on any replay for a 12-step coached run-through, or drop your own .w3g to see a milestone scoreboard against the closest pro game.

WC3V parses your replays entirely in your browser — the .w3g never leaves your device. Parsed data lives in IndexedDB, scoped to your origin. No accounts, no uploads, no server. The Node.js parser in this repo is the same code, browserified into client/js/vendor/wc3v-parser.bundle.js via tools/build-parser-bundle.js.

• Game simulation — reconstructs the full match from raw player inputs
• Worker tracking — race-specific mechanics: peon consumption, wisp sacrifice, ghoul lumber, peasant builders
• Hero tracking — levels, skill builds, inventory, revives, item buys
• Research & upgrades — 90 upgrades tracked with icons, costs, and per-level timing (attack/defense/ability)
• Expansion detection — identifies town hall placements at new gold mines
• Transport tracking — Zeppelin load/unload events
• Parse confidence — quantified reliability score (0–1) per player
• Replay validation — flags tier contradictions, missing supply buildings, data inconsistencies
• W3C / FLO support — handles W3Champions and FLO replays alongside standard Battle.net replays

• 3D terrain — Three.js heightmap rendering for 80+ maps, tileset-aware ground colors, fog of war
• Split-view camera — diagonal split for two-player matches; broadcast-style auto-camera modes
• Build order panel — supply-indexed timeline with tier transitions, research/upgrade cards, expansion banners, composition snapshots
• Minimap pips, building tooltips, floating text, hero trails — broadcast-quality overlays
• Scrubbable playback — jump to any moment, rewind, variable speed

• 16 curated builds across Human (4), Orc (3), Night Elf (4), Undead (5)
• Matchup filter — HvO, UvN, etc.
• Tier progression — t1/t2/t3 buildings, units, timing windows, conditional branches
• Replay-backed — every build links to one or more pro games you can play through visually
• 221 pro replay references across 12 tournaments (WGL Summer/Pro, Being Esports, Back2Warcraft, NetEase WGL/WPL, Blizzard Classic, etc.)

• Auto-matcher finds the closest pro replay by race, matchup, opener, archetype, map, and game length
• Compatibility checks — same race, matchup, build archetype, army comp, map, comparable game length
• Letter grades per category: Macro · Production · Item Economy · Idle Resources
• Itemized findings — "Hit supply max at 16:30 and stalled production for 30s, build farms before they fill"
• Top things to fix — prioritized actionable list
• Charts — supply curves, worker counts, side-by-side over time
• Tab drill-downs — Build order events, Tech timing, Economy, Heroes (skill build), Creeps (route + XP), Upgrades

A site-wide switch in the top nav (client/js/BandSwitcher.js, persisted to localStorage) picks the audience the site renders for. Same library, three framings:

• New to WC3 — Your first builds — forgiving timings and the few things that actually matter. Simpler homepage cards, beginner-friendly build order, guided walkthrough surfaced on every replay.
• Ladder — Solid, copyable builds from real tournament play. Full build orders, no hand-holding.
• Pro meta — Current top-level builds from major tournaments — tight execution, the latest strategies. The default for returning visitors.

The band controls the homepage library, the viewer's default mode, and the language the guided walkthrough uses (we/our for the followed player; the opponent called by name).

▸ Guide me on any replay opens a 12-step coached run-through. Each step jumps the scrubber, frames the camera (zoom to base / follow the hero / fit both armies / walk the creep route), highlights the matching build-order rows, and shows a short coaching line — action (what happened) · contrast (what the opponent did) · why it matters · takeaway for your own games.

Step roster: the opening (top-to-bottom command order with worker / building / hero rows) · the route to level 3 (creep camps cleared, in order) · the level 3 spike (skill picks for both heroes, side-by-side, with L1→L2 stat deltas for the doubled-up basic) · Tier 2/3 timing · expansion · first army upgrade · counters (e.g., your first Destroyers when they have 3+ casters out) · siege · midgame composition check · final composition.

Voice is grounded and factual — short "why it matters" lines from a small knowledge base, the rest is the actual game. Generated by client/js/ReplayGuide.js; rendered by the walkthrough HUD in client/js/app.js.

In the New band, where the opponent's full build order normally lives the viewer renders a pure-data "you vs them" scoreboard instead (_renderRaceComparison in client/js/BuildOrderRenderer.js):

• XP race (headline block) — hero on the field, reached level 3 / 5, with the faster side coloured.
• Economy — milestones in plain English (Early army / Standing army / Maxed army for 20 / 30 / 50 food) plus worker counts at 5:00 and 10:00.
• Teching up — T2 / T3 timing, second base.
• Army built — icon strips of every unit type with ×N count badges; hover for name, attack type, armor type. Stacked per-player so a long roster reflows naturally instead of wrapping into 80-px columns.

No advice in this panel — just milestones a new player can read to gauge how fast they're going.

Just go to wc3v.com and drop a .w3g file. Parsing happens in your browser; nothing is uploaded.

Prerequisites: Node.js 18+

# 1. Drop .w3g files in ./replays/  (pattern: ./replays/<name>.w3g)
# 2. Parse one — `happy-vs-grubby` is the canonical example used throughout
#    these docs; substitute any file name you dropped in ./replays/
node wc3v.js --replay=happy-vs-grubby
# Outputs ./client/replays/happy-vs-grubby.wc3v.gz

# 3. Serve the client
cd client && npx http-server
# open the printed URL

If you don't have a .w3g handy, the parsed output of happy-vs-grubby is checked into docs/ — see Output format below for a guided walkthrough.

Note that the viewer needs WC3 game data (icons, unit balance, map files) to be set up before it can render anything — see Data Setup below. Without those, the parser still works but the viewer renders blank.

Keep the uncompressed .wc3v JSON alongside the .gz for inspection:

node wc3v.js --replay=happy-vs-grubby --debug

node inspect-replay.js --replay=happy-vs-grubby --show=summary
node inspect-replay.js --replay=happy-vs-grubby --show=events --player=1 --filter=research
node inspect-replay.js --replay=happy-vs-grubby --show=units --search=Blademaster

Sections: players, events, workers, units, tiers, expansions, summary, all. Don't cat/grep the .wc3v files directly — they're 1M+ lines of JSON. The inspect tool is the proper interface.

.w3g replay file
      │
      ├── tools/build-parser-bundle.js
      │     │
      │     ▼
      │   client/js/vendor/wc3v-parser.bundle.js  (browser)
      │
      ▼
  wc3v.js (Node.js parser)
  ┌─────────────────────────────────────┐
  │  w3gjs decodes raw replay actions   │
  │  Game engine simulates:             │
  │    unit registration & backfilling  │
  │    building construction queue      │
  │    worker mechanics per race        │
  │    research/upgrade tracking        │
  │    expansion detection              │
  │    tier progression                 │
  │  Post-processing:                   │
  │    parse confidence scoring         │
  │    ReplayValidator checks           │
  │    spawn camp filtering             │
  └─────────────────────────────────────┘
      │
      ▼
  .wc3v.gz (compressed JSON)  ──────►  IndexedDB (browser, never uploaded)
      │
      ▼
  Client (browser)
  ┌──────────────────────────────────────────────────────────┐
  │  Wc3vViewer (coordinator, app.js)                        │
  │   ├─ ThreeMapRenderer    — 3D terrain (Three.js)         │
  │   ├─ MapRenderer         — 2D canvas overlay             │
  │   ├─ BuildOrderRenderer  — supply-indexed BO panel       │
  │   ├─ BroadcastCamera     — auto-camera modes             │
  │   ├─ TimeScrubber        — playback control              │
  │   ├─ FogOfWar            — non-playable area mask        │
  │   └─ FloatingText / Pips / Tooltips / Splats             │
  │                                                          │
  │  ReplayAnalyzer  + CompareMatcher  + CompareInline       │
  │   ├─ Auto-matches user replay vs pro library             │
  │   ├─ Letter grades + findings + charts                   │
  │   └─ AdvancedComparePicker for manual override           │
  └──────────────────────────────────────────────────────────┘

See docs/DESIGN.md for a deeper dive into replay parsing, unit registration, backfilling, and simulation mechanics.

The parser produces .wc3v files — JSON documents containing the full simulated game state:

Full schema: docs/wc3v-schema.json (JSON Schema draft 2020-12)

Example output: docs/happy-vs-grubby.wc3v.gz (gzip-compressed JSON, ~1.1 MB) — Happy (UD) vs FollowGrubby (Orc) on Concealed Hill, the same replay used as --replay=happy-vs-grubby throughout this README. See docs/wc3v-example.md for a guided walkthrough of the file's structure with real values, plus a trimmed docs/wc3v-example.json you can read in an editor.

WC3V needs data extracted from a legally owned copy of Warcraft III to render anything visually. These files are not distributed in this repository — provide them yourself from your own game install. The repo is structured so every required path is gitignored; drop your files in and the parser/viewer will pick them up.

Recommended tool for CASC extraction: Ladik's CASC Viewer — point it at your WC3 install's Data folder.

1. Unit balance data

# Extract unitbalance.slk into slk/UnitBalance.slk first, then:
cd slk && node slk.js && cd ..
cp slk/UnitBalance.json helpers/UnitBalance.json
node tools/add-attack-types.js   # enriches with attackType fields

2. Research / upgrade metadata (helpers/researchMeta.json is tracked — only regenerate if needed)

node tools/parse-upgrade-data.js

3. Maps

node tools/data-tool.js --source=/path/to/w3x/folder --version=v11
# Flags: --source, --version, --list, --prefix

4. Icons — follow war3observer and place .jpg files in client/assets/wc3icons/.

The 3D terrain renderer can fall back to flat shading if these aren't set up.

3D assets land in client/assets/{terrain,models,textures,buildings,trees,cliffs}/ (all gitignored).

For the full pro-replay onboarding workflow (acquiring packs, matching to builds, adding tournaments), see docs/REPLAY_ONBOARDING.md.

node wc3v.js --test       # parse the regression suite + manifest replays
node wc3v.js --promaps    # parse only manifest replays

These verify the parser produces valid output without fatal errors across the full library.

• w3gjs — W3G replay file decoder
• w3g_format.txt — replay format documentation
• war3observer — icon extraction
• Three.js — 3D terrain rendering
• D3.js v5 — timeline math and chart rendering
• RBush — spatial indexing for unit grouping

GNU General Public License v3.0

All code, assets, names, and concepts are used for educational purposes only and have no commercial or retail usage. All copyright and trademark are respective to their original owners. All software learned from public sources and from rightfully owned copies of the game.