From 7632aaba06950bbc5dd33dcb021fcc0a2c85e5de Mon Sep 17 00:00:00 2001 From: Davide Cappellini Date: Sun, 27 Sep 2026 18:53:59 +0200 Subject: [PATCH] docs: record the aim-capture blind spot - aim_fire only logs shots that passed setFire j178 flagged it and it is real: the capture cannot show WHY a shot did not happen (gun still hot, turret not aligned). A missing aim_fire record is ambiguous, not a refusal. Docs only, no code change. Adds the TR_CAPTURE_AIM row + a 'Known limitations' note to docs/env_reference.md section 8, and a two-line pointer next to the knob in .env.example. --- ModularBot_garage/.env.example | 4 +++- docs/env_reference.md | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/ModularBot_garage/.env.example b/ModularBot_garage/.env.example index bc34206..5dfd4bf 100644 --- a/ModularBot_garage/.env.example +++ b/ModularBot_garage/.env.example @@ -153,7 +153,9 @@ # TR_SURF_LOG one line per wave-surfing decision # TR_FIRE_DIAG per-reading fire-detection tick/raw/correction # TR_RECORD_WORLDSTATE dump every observed world state to JSONL -# TR_CAPTURE_AIM aim_scan/aim_fire records (gun id + bot belief) +# TR_CAPTURE_AIM aim_scan/aim_fire records (gun id + bot belief). +# KNOWN LIMIT: only shots that PASSED setFire are +# recorded, so a gap is ambiguous - see docs/env_reference.md # TR_RADAR_SCANLOG log every radar scan tick # TR_RADAR_FORCE_SPIN force the old full-360 spin radar # TR_TRACKER_PROBE dump the enemy-tracker internals diff --git a/docs/env_reference.md b/docs/env_reference.md index b3c3a9f..c4090e2 100644 --- a/docs/env_reference.md +++ b/docs/env_reference.md @@ -616,6 +616,7 @@ 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_CAPTURE_AIM` | off | presence-based; append `aim_scan` / `aim_fire` records — what the lead model BELIEVED (gun id, blst, age, boff, aim, turret, terr, heat, ax/ay, tof) to the same capture file as `TR_RECORD_WORLDSTATE` (needs `TR_RECORD_WORLDSTATE=1`) | | `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 | @@ -633,6 +634,21 @@ selector's training signal visible. Turn it on with: - colour per gun is the SAME table as the turret (`vbullet_draw.gunColors`), with a one-line legend in the top-left corner. +### Known limitations — `TR_CAPTURE_AIM` (j177) + +**`aim_fire` only records shots that PASSED `setFire`.** The capture is written +from the bot's own fire call, so a shot the **server rejected or that the bot +never issued** produces no `aim_fire` record at all. + +That is a real blind spot: from these records you can never answer *why* a shot +did not happen — e.g. the gun was still hot, or the turret was not yet aligned. +A missing `aim_fire` is ambiguous between "no target / didn't try" and "tried and +was refused". The `aim_scan` records carry the belief state (age, boff, turret, +heat) for every scan, so you can often *infer* the cause by looking at the scans +that precede the gap, but the capture does not state it. Read the gaps as +"no recorded shot", never as "the server blocked it". Closing this needs a +pre-`setFire` gate record, which is j177+ work, not present today. + 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`, `FreshnessTicks=16`, `FreshStreakTicks=3`, `MarginDeg=20`,