Left 4 Dead 2 Director System Research

Reverse-engineering notes, sanitized runtime evidence, and reproducible tools describing how Left 4 Dead 2's adaptive AI Director is organized.

This repository is written for two audiences:

• junior programmers who want to understand adaptive game pacing;
• reverse engineers who want addresses, control flow, confidence levels, and repeatable evidence.

No reusable game library is implemented inside this evidence repository. The separate sbox-adaptive-director repository contains the clean-room reference implementation.

Ready to implement it? Give another coding agent the reusable library implementation prompt.

Auditing the existing implementation? Use the evidence-to-component traceability map.

What is the Director?

The Director watches the survivors, estimates how much pressure they are under, and decides when to create action or relief. It coordinates ordinary enemies, special encounters, panic waves, bosses, finales, survival rounds, item placement, and mode-specific scripts.

flowchart LR
    W[Game world snapshot] --> I[Per-survivor intensity]
    I --> T[Tempo controller]
    T --> E[Encounter scheduler]
    E --> P[Spawn placement]
    P --> H[Game engine executes request]
    H --> W

    S[Mode and script policy] --> T
    S --> E
    S --> P

Loading

Important results

• The analyzed binary is the June 30, 2026 x86 server.dll, SHA-256 a93ec916a8f26fbea85688c321d2ba8dd346d435fab09a0b926dd950c2e1ea12.
• The Director singleton has 1,292 direct code references grouped into 474 candidate functions.
• Native tempo is BUILD_UP -> SUSTAIN_PEAK -> PEAK_FADE -> RELAX -> BUILD_UP.
• Tempo uses the maximum instantaneous intensity among eligible living survivors. It does not use TimeAveragedIntensity.
• Panic events use exact states INITIAL_DELAY(0), MEGA_MOB(1), WAIT_FOR_COMBAT_TO_END(2), PAUSE(3), and DONE(4).
• Boss/hazard placement uses recovered first-valid threat-area shuffling, maximum-flow route advancement with first ties, five-point visibility hulls, exact area filters, and a bounded random fallback. See the placement and specials recovery.
• The Music Director is recovered end to end: 85 server callbacks, continuous mixer equations, combat/special/boss/hazard rules, the MusicCmd transport, client track arbitration, and 398 effective authored event records. See the Music Director recovery.
• Finale, survival, scavenge, item-management, scripting, and versus-allocation responsibilities were separated into reusable concepts.

Start with these documents:

1. Plain-language architecture
2. Intensity coefficients and gameplay events
3. Recovered function catalog
4. Generalized clean-room specification
5. Coverage and remaining limits
6. System diagrams
7. Prompt for building a generalized library
8. Reference implementation traceability
9. Music Director recovery
10. Generalized music implementation specification

Intensity in plain language

Each survivor owns an intensity tracker. Gameplay events add pressure in one of five severity categories. With default settings, their effective increments are:

Category	Typical recovered use	Effective increment
1	distant or low-threat enemy death	+0.0125
2	small damage or nearby ordinary enemy death	+0.05
3	medium damage, ledge grab, nearby boss death	+0.125
4	major damage or later incapacitation	+0.25
5	first incapacitation or qualifying defibrillator revival	immediately reaches 1.0

After an event, instantaneous intensity is held for five seconds. It then decays linearly from full to zero over 30 seconds.

stateDiagram-v2
    [*] --> Calm
    Calm --> Pressured: intensity event
    Pressured --> Held: add severity and clamp to 1.0
    Held --> Decaying: five-second hold expires
    Decaying --> Calm: reaches zero
    Decaying --> Held: another intensity event

Loading

The exact TimeAveragedIntensity equation was validated against 209 native updates with maximum absolute error 2.20e-8. It has unusual overshoot-and-snap behavior and is documented carefully in INTENSITY_RECOVERY.md.

The defibrillator guard is also exact: revival applies category 5 only when the active mode has base == "coop" and difficulty is Easy or Normal.

Tempo in plain language

stateDiagram-v2
    BUILD_UP --> SUSTAIN_PEAK: timer ready and max instant intensity > 0.9
    SUSTAIN_PEAK --> PEAK_FADE: sustain timer expires
    PEAK_FADE --> RELAX: combat clears and max instant intensity < 0.9
    RELAX --> BUILD_UP: relax timer or travel condition

Loading

The same value is not used everywhere:

Decision	Intensity used?
End buildup	maximum instantaneous intensity
End sustained peak	no; timer-driven
End peak fade	maximum instantaneous intensity
End relax	no; timer/travel-driven
Spawn relax wanderers	maximum instantaneous intensity with difficulty-specific threshold

Repository layout

research/
  *.md                 Human-readable findings and specifications
  analysis/            Machine-readable xrefs, disassemblies, and validation
  oracle/              Sanitized runtime traces and validated memory layout
  tools/               Read-only PE/disassembly/trace analysis scripts
tools/
  OfflineCaptureVsp/   Source for the local offline observation plugin
docs/
  SYSTEM_DIAGRAMS.md   Larger subsystem and data-flow diagrams

Reproducing the static analysis

Requirements:

• a legally installed copy of Left 4 Dead 2;
• Python 3;
• Capstone for disassembly-oriented scripts;
• the exact server.dll build above if you expect matching RVAs.

Example:

python research\tools\extract_director_evidence.py `
  "D:\SteamLibrary\steamapps\common\Left 4 Dead 2\left4dead2\bin\server.dll"

Validate the averaged-intensity equation against the included sanitized trace:

python research\tools\validate_averaged_intensity.py `
  research\oracle\intensity_averaged_runtime_trace.jsonl

See research/tools/README.md and the research method for the complete workflow.

Evidence labels

• Proven means direct disassembly, string xref, constructor default, or runtime observation establishes the claim.
• Inferred means multiple nearby facts support a responsibility, but the stripped binary does not retain its original symbol.
• Clean-room design means a proposed generalized interface or formula, not copied Valve source.

RVAs are offsets relative to the loaded server.dll module. They are not fixed process addresses because ASLR changes the module base.

Safety and scope

The runtime traces were collected in local -insecure sessions and sanitized before inclusion. The capture plugin is research tooling and should never be loaded while connecting to VAC-secured servers.

This repository does not contain Valve source code, game binaries, PDBs, or decompiled source reproduction. It contains independently produced observations, small instruction-level evidence, derived documentation, and analysis tools.

Can this recreate the Director?

It is sufficient to build a generalized behavioral equivalent: pressure tracking, tempo, population budgets, encounter scheduling, boss/hazard planning, navigation-constrained placement, scenario stages, scripting hooks, persistence, and deterministic replay.

It does not claim source-identical or byte-identical reconstruction. The retail binary is stripped, so some private function names and engine-specific helper semantics cannot be recovered honestly.