j129: virtual-bullet debug overlay (TR_VBULLET_DEBUG, default off) - travelled path, predicted aim ring, hit/miss vector; shared turret colour table

docs/env_reference.md

@@ -449,6 +449,22 @@ Measured byte-identical on `bmPath`. Kept for experiments; leave at defaults.
 | `TR_RADAR_SCAN_LOG_PATH` | `/tmp/radar_scan_log.jsonl` | where that goes |
 | `TR_TRACKER_PROBE` | off | presence-based; per-tick enemy tracker vs server enemy count |
 | `TR_TRACKER_PROBE_PATH` | `/tmp/tracker_probe.jsonl` | where that goes |
+| `TR_VBULLET_DEBUG` | off | presence-based; overlay the virtual bullets in the GUI debug graphics (see below) |
+| `TR_VBULLET_DEBUG_GUN` | selected gun | `all`/`*` for every gun, or a gun name (e.g. `Pattern`); unset = only the currently selected gun |
+| `TR_VBULLET_DEBUG_MAX` | `32` | cap on bullets drawn per tick |
+
+The **virtual-bullet overlay** (`TR_VBULLET_DEBUG`, off by default) makes the
+selector's training signal visible. Turn it on with:
+
+    TR_VBULLET_DEBUG=1 TR_VBULLET_DEBUG_GUN=all ./out/ModularBot
+
+- **travelled path** — thin line from the fire point along the fire direction,
+  as far as the bullet has actually flown.
+- **aim ring** — small hollow circle at the predicted target position.
+- **miss vector** — line from the aim ring to the closest-approach point; a
+  filled dot there is a HIT, a hollow ring a MISS (the score the selector sees).
+- colour per gun is the SAME table as the turret (`vbullet_draw.gunColors`), with
+  a one-line legend in the top-left corner.
 
 The **adaptive-melee radar** has no env knobs. Its tuning lives in compile-time
 constants in `radars/adaptive_melee_radar.nim:36-50`: `MaxRadarTurnRate=45`,