BT411/phases/phase-14-ppc-sync-distortion.md

Phase 14 — PPC hit = scrambleVideo, the cockpit-CRT sync detune

Goal: restore the PPC's authentic secondary effect — a PPC strike scrambles every secondary cockpit display for 0.8 s, leaving the main view untouched.

Status: ✅ IMPLEMENTED 2026-08-06 (branch ppc-sync-distortion) [T2 — visual screenshot-verified, trigger by construction]. Discovered 2026-08-06 by disassembly of the shipped BTL4OPT.EXE (md5 a97075bcb5634d13263e9ad5a2b96fd0) after playtesters reported "being hit by a PPC makes it look like all of the secondary CRTs were being degaussed." Full findings: context/gauges-hud.md §"PPC HIT = a deliberate CRTC horizontal-sync DETUNE"; cross-ref in context/combat-damage.md.

What shipped (all three work items):

• A — trigger: game/reconstructed/mech.cpp, Mech::TakeDamageMessageHandler @0x4a03f3 position (after the cylinder resolve, before the burst loop) — fires GetGaugeRenderer()->SpecialEffect(scrambleVideo, damageType*0.2f) once per EnergyDamageType message. BT_DMG_LOG prints [ppc-scramble].
• B — visual: SVGA16::FunkyVideo (was the 2007 stub) now arms scrambleActive; SVGA16::ScrambleRowShift (new) is the per-source-row horizontal shear, read by BOTH DrawDevSurface (surround/dock) and ExpandPlaneToBGRA (glass windows), so all secondary surfaces + the rotated radar shear together and the main 3D view (a separate timing chain) is untouched. Tunable: BT_SCRAMBLE_SHEAR (px/line, default 4), BT_SCRAMBLE_ROLL (px/sec, default 220). BT_SCRAMBLE_TEST=1 forces it always-on for tuning by eye without waiting for a PPC hit.
• C — non-stacking latch: L4GaugeRenderer::SpecialEffect now ignores the re-arm while scrambleVideoFlag is set (matches the binary's modified latch); a second PPC during the window no longer extends it.
• Verified: Release links clean; surround boots + runs with the effect forced on, every secondary MFD + the radar shear while the out-the-window view stays clean, no crash. Open: live PPC-fire confirmation (one arm per hit, non-stacking across two hits) + the by-eye shear tuning belong to the playtesters who filed the report — k/roll are not recoverable from the binary.

Good news up front: the engine half already exists in our tree under the original VWE names (SpecialEffect / scrambleVideo / FunkyVideo). Only two things are missing: the trigger (never ported) and the visual (stubbed out in 2007). This is a small, well-bounded job.

---

1. What the original did [T1 — disasm-verified]

On the victim's machine, Mech::TakeDamageMessageHandler @0x4a0230 tests the damage type between the collision divert and the burst loop:

004a03f3  mov  ecx,[esi+0x2c]      ; damage.damageType
004a03f6  cmp  ecx,4               ; EnergyDamageType
004a03f9  jne  0x4a0423            ; everything else -> burst loop
004a03fb  mov  eax,[0x4efc94]      ; global `application`
004a0400  mov  eax,[eax+0x4c]      ; -> gauge renderer
004a0405  je   0x4a0423            ; null-guarded
004a0407  fild dword [esi+0x2c]    ; (float)damageType == 4.0
004a040a  fld  xword [0x4a0c08]    ; long double 0.2
004a0410  fmulp st(1)              ; => 0.8
004a041d  call dword [edx+0x4c]    ; vtable slot 19 == SpecialEffect(0, 0.8f)

→ L4GaugeRenderer::SpecialEffect(scrambleVideo, 0.8f) @0x46ffcc → SVGA16::FunkyVideo(True) @0x47d76d, which reprograms the VGA CRT controller:

out(0x3D4,0x11); v=in(0x3D5); out(0x3D5, v & 0x7F)   ; unlock CRTC regs 0-7
out(0x3D4,0x00)                                      ; CRTC 0 = HORIZONTAL TOTAL
saved = in(0x3D5);  out(0x3D5, saved - 9)            ; shorten every scanline
out(0x3D4,0x11); out(0x3D5, v)                       ; restore write-protect

A per-frame timer @0x47003c writes saved back 0.8 s later.

Why only the PPC: a BTL4.RES census gives damageType 4 (Energy) = 14 subsystem records, every one PPC or ERPPC. Everything else is Ballistic (16), Explosive (30), Laser (78). The branch is structurally PPC-exclusive — no extra gating needed.

Why only the secondaries: all six secondary displays are derived by the VDB from that one VGA's timing, so they break together. The main out-the-window view comes off the Division VPX card on an independent timing chain and is unaffected. Playtesters confirm both halves.

---

2. What our tree already has

Piece	Where	State
enum VideoEffectType { scrambleVideo } (value 0)	engine/MUNGA/GAUGREND.h:482	✅ present
virtual void GaugeRenderer::SpecialEffect(VideoEffectType, Scalar) {}	engine/MUNGA/GAUGREND.h:488	✅ base no-op
L4GaugeRenderer::SpecialEffect — sets scrambleVideoFlag, scrambleVideoTimeout = Now()+duration, calls FunkyVideo(True)	engine/MUNGA_L4/L4GREND.cpp:806	✅ implemented
L4GaugeRenderer::ProcessVideoEffects() — on timeout, FunkyVideo(False)	engine/MUNGA_L4/L4GREND.cpp:832	✅ implemented
…called every frame from ExecuteForeground	engine/MUNGA_L4/L4GREND.cpp:370	✅ live
SVGA16::FunkyVideo(Logical)	engine/MUNGA_L4/L4VB16.cpp:6358	❌ STUBBED (//STUBBED: VIDEO RB 1/15/07, body commented out)
Any caller of SpecialEffect	—	❌ NONE

The base-class declaration carries its original comment:

// Quick and dirty hack to allow calling L4GaugeRenderer::SpecialEffect // from non L4 level. GDU 2/28/96

That hack exists because the damage handler (non-L4 level) had to call it — independent corroboration that the trigger belonged in mech.cpp, and the reason you can call it through the base pointer without dragging L4 headers into a game-layer TU.

---

3. Work item A — the trigger (game/reconstructed/mech.cpp)

In Mech::TakeDamageMessageHandler, after the damageType==0 collision divert and before the burst loop, add the type-4 branch.

// @0x4a03f3 [T1] -- PPC/ERPPC only: EnergyDamageType is authored on exactly
// the 14 PPC/ERPPC subsystem records and nothing else.  Duration is DERIVED
// from the type ordinal, not a constant: (float)damageType * 0.2 == 0.8f.
if (damage.damageType == Damage::EnergyDamageType)      // == 4
{
    GaugeRenderer *gauges = (application != 0)
        ? application->GetGaugeRenderer() : 0;          // APP.h:355
    if (gauges != 0)                                    // binary null-guards too
    {
        gauges->SpecialEffect(
            GaugeRenderer::scrambleVideo,
            (Scalar)damage.damageType * 0.2f);          // long double 0.2 @0x4a0c08
    }
}

Placement matters. The binary's branch is outside the burst loop, so it fires once per damage message, not once per burst. Putting it inside the loop would re-arm it burstCount times.

Use the named accessor — do not raw-read application+0x4c (databinding rule, context/reconstruction-gotchas.md).

---

4. Work item B — the visual (SVGA16::FunkyVideo)

There is no CRTC to detune, so reproduce the look, applied to the gauge composite only.

What the original did physically: Horizontal Total sets character clocks per scanline. Subtracting 9 shortens every line by roughly 9%, far outside any monitor's sync lock range, so the picture breaks into a rolling diagonal tear until the value is restored. VWE's own name for it — scrambleVideo — is the best description of the intended result.

Suggested model (per-scanline horizontal displacement of the gauge buffer):

shift(y, t) = ( y * k + roll(t) ) mod width

• k — per-line shear, the fraction of a line lost. ~9% of width is the physically-derived starting point; tune by eye against the playtester description rather than treating it as exact, because the on-screen result depended on how each pod monitor's H-sync PLL misbehaved — that is not recoverable from the binary.
• roll(t) — a time-varying offset so the tear drifts rather than sitting static. The original rolled because the monitor never re-locked.

Constraints:

• Gauge composite only. Apply to the SVGA16 pixelBuffer (engine/MUNGA_L4/l4vb16.h:243) or at the point the strip/surfaces are presented — never the main 3D view. The main view being clean is a confirmed observation, not an assumption.
• All secondary surfaces together. They are bit-planes of one shared buffer, so a single buffer-level effect is authentic by construction; do not implement it per-MFD.
• Keep the existing timing path. SpecialEffect / ProcessVideoEffects already own the flag and the 0.8 s timeout and are already called per frame. FunkyVideo should only set/clear state — no timing logic of its own.

---

5. Fidelity constraints (do not "improve" these)

1. Duration is damageType * 0.2f, not a literal 0.8f.
2. Fires on EnergyDamageType — never add an explicit PPC class check; the data authorship is the gate.
3. Idempotent, non-stacking. The binary latches on modified @0x4fe0fe: a second PPC hit while the effect is live does not re-save the (already detuned) value and does not extend or double the effect. Our SpecialEffect currently does overwrite scrambleVideoTimeout, which extends the effect on a second hit — that is a divergence. Match the binary: ignore re-arm while scrambleVideoFlag is set. (The original's latch was in FunkyVideo; ours must go in SpecialEffect or FunkyVideo, but it must exist.)
4. Victim-side only. The shooter sees nothing; this runs in the victim's damage handler.
5. Null-guard the gauge renderer — the binary does, and headless/bench runs have none.

---

6. Verification

• Headless: add a one-line log in the new branch; fire a PPC at a dummy with BT_DMG_LOG. Expect exactly one arm per PPC message, zero for laser / autocannon / missile / Gauss.
• Non-stacking: two PPC hits ~0.2 s apart must produce one 0.8 s effect measured from the first hit, not 1.0 s or two effects.
• Live: confirm every secondary MFD scrambles together and the main view stays clean. Have the playtesters who filed the report compare — they are the only ground truth for k and roll.
• Against the original (optional, decisive): in the DOSBox-X fork, log writes to CRTC index 0 via 0x3D4/0x3D5 during a real BT mission. Prediction: exactly one write of saved-9 per PPC strike, one restore 0.8 s later, zero for every other weapon.

---

7. Gotchas

• Do not confuse this with SVGA16::FlashPalette (the pixel-mask cycler on ports 0x302/0x30A/0x312). That machinery is linked and its per-frame cycler runs, but FlashPalette @0x46d5f4 has zero call sites and zero address-of references in BTL4OPT.EXE — BT never arms it. RP does (RPL4OPT.EXE @0x4addce, palette 1, rate 2.0, masks {FF,BF,7F,3F}) for alarm blinking. Wrong mechanism, wrong game.
• The LampTesla1/2/3 "solid-state relays" in L4CTRL.HPP are not involved and are driven by nothing in the surviving tree.
• Scope note: callers of gauge-renderer vtable slot 19 were not exhaustively enumerated (virtual dispatch), so another arming site may exist. The low-level path is exhaustive — @0x47d76d has one caller, @0x46d840 two (set @0x47002b, restore @0x470076).

References

• context/gauges-hud.md §"PPC HIT = a deliberate CRTC horizontal-sync DETUNE"
• context/combat-damage.md §Mech::TakeDamageMessageHandler (Energy branch)
• HISTORY.md (TeslaRel410) §"Anatomy of a surviving weapon — the PPC"