j135 draw-only geometry overlay (TR_GEO_DEBUG) + global debug-draw switch (TR_DEBUG_DRAW)

ModularBot_garage/src/ModularBot.nim

@@ -44,6 +44,7 @@ import targeting/enemy_tracker
 import targeting/target_selector
 import env_report
 import vbullet_draw
+import geo_overlay
 
 const botJsonPath = currentSourcePath().parentDir / "ModularBot.json"
 const DebugVBullets = false
@@ -176,6 +177,19 @@ let VBulletDebugOn  = vBulletDebugEnabled()
 let VBulletDebugMax = vBulletDebugMaxBullets()
 let VBulletDebugGun = resolveGunFilter(getEnv(VBulletDebugGunEnv, ""), GunNames)
 
+## ── global debug-draw switch (TR_DEBUG_DRAW, default ON) ───────────────────
+## When 0/false/no/off, every mover is built with `debugGraphics = false` and
+## the virtual-bullet overlay is skipped, so nothing but the (independent,
+## default-off) TR_GEO_DEBUG geometry overlay is left on screen. When on, every
+## per-element knob behaves exactly as before.
+let DebugDrawOn = debugDrawEnabled()
+
+## ── geometry overlay (TR_GEO_DEBUG, default OFF) ───────────────────────────
+## Draw-only visual aid (see `geo_overlay.nim`): the two bots as the endpoints
+## of a circle diameter, each heading line, and each line's intersection points
+## with the circle. No decision, movement or gun change.
+let GeoDebugOn = geoDebugEnabled()
+
 const
   CLR_GUN = "\e[33m"    # yellow
   CLR_MOVE = "\e[36m"   # cyan
@@ -1357,7 +1371,7 @@ method run*(bot: ModularBot) =
         of BitBrainId: bot.bitbrain.onResult(fe)
         else: discard
         if fe.hit: inc bot.virtualHits else: inc bot.virtualMiss
-        if VBulletDebugOn:
+        if DebugDrawOn and VBulletDebugOn:
           resolvedMarks.add VbResolved(
             gunId: gunId, aimX: fe.prediction.x, aimY: fe.prediction.y,
             actualX: fe.actualX, actualY: fe.actualY, hit: fe.hit)
@@ -1440,12 +1454,19 @@ method run*(bot: ModularBot) =
 
       setGunTurnRate(normDelta)
 
-      # Virtual-bullet overlay (default off). Drawn AFTER selection so the
-      # default "selected gun only" filter uses this tick's choice.
-      if VBulletDebugOn:
+      # Virtual-bullet overlay (default off; suppressed by TR_DEBUG_DRAW=0).
+      # Drawn AFTER selection so the default "selected gun only" filter uses
+      # this tick's choice.
+      if DebugDrawOn and VBulletDebugOn:
         discard drawVirtualBullets(bot.tracker, resolvedMarks, selectedGun,
                                    VBulletDebugGun, VBulletDebugMax, GunNames)
 
+      # Geometry overlay (TR_GEO_DEBUG, default off). Independent of
+      # TR_DEBUG_DRAW: this is the one thing left when debug drawing is off.
+      if GeoDebugOn:
+        discard drawGeoOverlay(ws.selfX, ws.selfY, ws.selfHeading,
+                               ws.enemyX, ws.enemyY, ws.enemyHeading)
+
     # Emit exactly one config line per tick, at the END of the tick, so the gun
     # field reflects the selection made above rather than the previous tick's.
     if bot.cfgDirty:
@@ -1490,9 +1511,9 @@ when isMainModule:
     bitbrain:    initBitBrainGun(),
     radar:        RadarLockModule(),
     meleeRadar:   initAdaptiveMeleeRadar(),
-    mover:        TFILModule(debugGraphics: true),
-    ringMover:    TFILRingModule(debugGraphics: true),
-    strafeMover:  StrafeModule(debugGraphics: true),
+    mover:        TFILModule(debugGraphics: DebugDrawOn),
+    ringMover:    TFILRingModule(debugGraphics: DebugDrawOn),
+    strafeMover:  StrafeModule(debugGraphics: DebugDrawOn),
     surfMover:    initWaveSurfer(),
     learnedMover: initLearnedSurfer(),
     rammer:       initRammer(),
@@ -1512,6 +1533,8 @@ when isMainModule:
     vBulletDebugGun:  getEnv(VBulletDebugGunEnv, ""),
     vBulletDebugMax:  VBulletDebugMax,
     recordWorldState: RecordWorldState,
+    geoDebug:         GeoDebugOn,
+    debugDraw:        DebugDrawOn,
     radarForceSpin:   RadarForceSpin,
     radarScanLog:     RadarScanLog,
     radarScanLogPath: RadarScanLogPath,

ModularBot_garage/src/env_report.nim

@@ -33,6 +33,7 @@ import guns/tm_horizon
 import guns/bitbrain_gun
 import guns/pattern_matcher
 import vbullet_draw
+import geo_overlay
 
 const EnvReportEnableEnvVar* = "TR_ENV_REPORT"
 
@@ -49,6 +50,8 @@ type
     vBulletDebugGun*:  string
     vBulletDebugMax*:  int
     recordWorldState*: bool
+    geoDebug*:         bool
+    debugDraw*:        bool
     radarForceSpin*:   bool
     radarScanLog*:     bool
     radarScanLogPath*: string
@@ -209,6 +212,9 @@ proc printEffectiveValues(ctx: EnvReportContext) =
        sourceOf(VBulletDebugGunEnv))
   emit("TR_VBULLET_DEBUG_MAX", $ctx.vBulletDebugMax,
        sourceOf(VBulletDebugMaxEnv))
+  # global debug-draw switch (default on) + the draw-only geometry overlay
+  emit(DebugDrawEnv, onOff(ctx.debugDraw), sourceOfPresence(DebugDrawEnv))
+  emit(GeoDebugEnv, onOff(ctx.geoDebug), sourceOfPresence(GeoDebugEnv))
   emit("TR_POWER_LOG", onOff(ctx.powerLog), sourceOfPresence("TR_POWER_LOG"))
   emit("TR_RESULT_LOG", onOff(ctx.resultLog), sourceOf("TR_RESULT_LOG"))
   emit("TR_RECORD_WORLDSTATE", onOff(ctx.recordWorldState),
@@ -488,6 +494,7 @@ proc knownEnvNames*(): seq[string] =
     "TR_RADAR_FORCE_SPIN", "TR_RADAR_SCANLOG", "TR_RADAR_SCAN_LOG_PATH",
     "TR_TRACKER_PROBE", "TR_TRACKER_PROBE_PATH", "TR_VBULLET_ADMIT_ONLY",
     VBulletDebugEnv, VBulletDebugGunEnv, VBulletDebugMaxEnv,
+    DebugDrawEnv, GeoDebugEnv,
     "TR_POWER_LOG",
     "TR_RESULT_LOG",
     # the .env loader's own environment hook (TR_ENV_FILE names the file)

ModularBot_garage/src/geo_overlay.nim

@@ -0,0 +1,225 @@
+## Geometry overlay (TR_GEO_DEBUG) — a DRAW-ONLY visual aid.
+##
+## No decision, no movement, no gun change: this module only emits SVG for the
+## GUI. DEFAULT OFF, so the shipped bot is byte-for-byte unchanged. It exists so
+## the owner can reason about a specific piece of geometry:
+##
+##   * the two bots are the endpoints of a DIAMETER, so both lie exactly on the
+##     circle (centre = midpoint, radius = distance / 2);
+##   * a line along OUR heading through our position;
+##   * a line along the ENEMY heading through the enemy position;
+##   * the intersection points of each line with the circle, marked. A line
+##     through a point that is ON the circle meets it twice — the bot itself and
+##     ONE OTHER point — and the OTHER point is drawn visually distinct (that is
+##     the one worth looking at). A tangent line's two points coincide; we draw
+##     what the maths gives.
+##
+## Env knobs (read once at boot by ModularBot, registered in env_report.nim):
+##   TR_GEO_DEBUG   presence/1 = on. default OFF.
+##   TR_DEBUG_DRAW  presence/1 = on (default); 0/false/no/off disables every
+##                  mover's `debugGraphics` and the virtual-bullet overlay, so
+##                  the geometry overlay is the ONLY thing left on screen.
+##
+## The geometry is pure and unit-tested by `tests/test_geo_overlay.nim`; only
+## `emitGeoPrims` touches the GUI buffer.
+
+import std/[math, os, strutils]
+import robocode_tankroyale_botapi
+
+const
+  GeoDebugEnv*  = "TR_GEO_DEBUG"
+  DebugDrawEnv* = "TR_DEBUG_DRAW"
+
+const DegToRad = PI / 180.0
+
+# ── env resolution (pure, so a test can pin it) ──────────────────────────────
+
+proc envFlagOn(value: string, default: bool): bool =
+  ## "" -> `default`; explicit 0/false/no/off -> false; anything else -> true.
+  let s = value.strip().toLowerAscii()
+  if s.len == 0: return default
+  s notin ["0", "false", "no", "off"]
+
+proc geoDebugEnabled*(): bool =
+  ## `TR_GEO_DEBUG`: default OFF (the shipped bot draws nothing new).
+  envFlagOn(getEnv(GeoDebugEnv, ""), false)
+
+proc debugDrawEnabled*(): bool =
+  ## `TR_DEBUG_DRAW`: default ON. When off, every mover is built with
+  ## `debugGraphics = false` and the virtual-bullet overlay is skipped.
+  envFlagOn(getEnv(DebugDrawEnv, ""), true)
+
+# ── the geometry (pure) ──────────────────────────────────────────────────────
+
+type
+  GeomCircle* = object
+    cx*, cy*, r*: float
+
+  GeomPoint* = object
+    x*, y*: float
+
+proc makeDiameterCircle*(ax, ay, bx, by: float): GeomCircle =
+  ## The circle whose DIAMETER is the segment a-b: centre at the midpoint,
+  ## radius half the distance. Both a and b therefore lie on the circumference.
+  ## A degenerate (coincident) pair yields r = 0; callers skip the draw.
+  result.cx = (ax + bx) * 0.5
+  result.cy = (ay + by) * 0.5
+  result.r  = 0.5 * hypot(bx - ax, by - ay)
+
+proc distTo*(p: GeomPoint, c: GeomCircle): float {.inline.} =
+  hypot(p.x - c.cx, p.y - c.cy)
+
+proc onCircle*(p: GeomPoint, c: GeomCircle): bool {.inline.} =
+  abs(p.distTo(c) - c.r) < 1e-6
+
+proc lineCircleIntersections*(px, py, headingDeg: float,
+                             c: GeomCircle): seq[GeomPoint] =
+  ## The two intersection points of the INFINITE line through (px, py) along
+  ## `headingDeg` with circle `c`. The line is parametrised P(t) = p + t*d with
+  ## d a unit vector, so the quadratic has a = 1 and the roots are signed
+  ## distances along d. Returns the two roots when the line meets the circle
+  ## (coincident when tangent), and nothing when it misses.
+  ##
+  ## Tank Royale bearings: 0° = east, positive counter-clockwise.
+  let h  = headingDeg * DegToRad
+  let dx = cos(h)
+  let dy = sin(h)
+  let ox = px - c.cx
+  let oy = py - c.cy
+  let b  = 2.0 * (ox * dx + oy * dy)
+  let cc = ox * ox + oy * oy - c.r * c.r
+  let disc = b * b - 4.0 * cc
+  if disc < 0.0: return @[]
+  let s  = sqrt(disc)
+  let t1 = (-b - s) * 0.5
+  let t2 = (-b + s) * 0.5
+  result.add GeomPoint(x: px + t1 * dx, y: py + t1 * dy)
+  result.add GeomPoint(x: px + t2 * dx, y: py + t2 * dy)
+
+type
+  GeoPrimKind* = enum
+    gpCircle      ## the diameter circle outline
+    gpLineSelf    ## line along OUR heading
+    gpLineEnemy   ## line along the ENEMY heading
+    gpMarkSelf    ## intersection that coincides with the bot (hollow ring)
+    gpMarkOther   ## the OTHER intersection (filled, distinct)
+
+  GeoPrim* = object
+    kind*: GeoPrimKind
+    x1*, y1*: float        ## lines: first endpoint
+    x2*, y2*: float        ## lines: second endpoint
+    cx*, cy*, r*: float    ## circles: centre + radius
+    color*: string
+
+const
+  GeoCircleColor*   = "#888888"  # grey  — the diameter circle
+  GeoSelfLineColor* = "#00FFFF"  # cyan  — OUR heading line
+  GeoEnemyLineColor* = "#FF8000" # orange— ENEMY heading line
+  GeoSelfMarkColor* = "#FFFFFF"  # white — the bot itself (hollow ring)
+  GeoOtherMarkColor* = "#FF00FF" # magenta — the OTHER intersection (filled)
+  GeoCircleWidth*   = 1.0
+  GeoLineWidth*     = 1.0
+  GeoMarkWidth*     = 1.5
+  GeoSelfMarkRadius*  = 4.0
+  GeoOtherMarkRadius* = 4.0
+  GeoLineMargin*    = 10.0
+    ## Extra length (px) the heading segment extends beyond the far
+    ## intersection; a segment of half-length 2r + margin always contains both
+    ## intersections because a chord of a circle is at most 2r long.
+
+proc pickSelfOther*(pts: seq[GeomPoint], ax, ay: float):
+    tuple[self, other: GeomPoint, hasOther: bool] =
+  ## The intersection nearest the anchor `(ax, ay)` is the bot itself (the
+  ## anchor lies ON the circle, so the distance is ~0); the farther one is the
+  ## OTHER point. `hasOther` distinguishes a real second point from a tangent
+  ## coincidence.
+  if pts.len == 0: return
+  var iSelf = 0
+  var dSelf = hypot(pts[0].x - ax, pts[0].y - ay)
+  for i in 1 ..< pts.len:
+    let d = hypot(pts[i].x - ax, pts[i].y - ay)
+    if d < dSelf: dSelf = d; iSelf = i
+  result.self = pts[iSelf]
+  var iOther = -1
+  var dOther = 0.0
+  for i in 0 ..< pts.len:
+    if i == iSelf: continue
+    let d = hypot(pts[i].x - ax, pts[i].y - ay)
+    if iOther < 0 or d > dOther: iOther = i; dOther = d
+  if iOther >= 0:
+    result.other = pts[iOther]
+    result.hasOther = true
+
+proc headingSegment(px, py, headingDeg, halfLen: float): tuple[x1, y1, x2, y2: float] =
+  ## Segment centred on (px, py), `halfLen` long each way along `headingDeg`.
+  let h  = headingDeg * DegToRad
+  let dx = cos(h) * halfLen
+  let dy = sin(h) * halfLen
+  (px - dx, py - dy, px + dx, py + dy)
+
+proc collectGeoPrims*(selfX, selfY, selfHeading,
+                      enemyX, enemyY, enemyHeading: float): seq[GeoPrim] =
+  ## Pure: the primitives the overlay draws. Empty in the degenerate case where
+  ## the two bots coincide (distance ~0) — skip rather than divide by zero.
+  let c = makeDiameterCircle(selfX, selfY, enemyX, enemyY)
+  if c.r < 1e-6: return
+
+  result.add GeoPrim(kind: gpCircle, cx: c.cx, cy: c.cy, r: c.r,
+                     color: GeoCircleColor)
+
+  let halfLen = 2.0 * c.r + GeoLineMargin
+
+  # OUR heading line + its two intersection points.
+  let segSelf = headingSegment(selfX, selfY, selfHeading, halfLen)
+  result.add GeoPrim(kind: gpLineSelf, x1: segSelf.x1, y1: segSelf.y1,
+                     x2: segSelf.x2, y2: segSelf.y2, color: GeoSelfLineColor)
+  let ipSelf = lineCircleIntersections(selfX, selfY, selfHeading, c)
+  let soSelf = pickSelfOther(ipSelf, selfX, selfY)
+  if soSelf.hasOther:
+    result.add GeoPrim(kind: gpMarkSelf, cx: soSelf.self.x, cy: soSelf.self.y,
+                       r: GeoSelfMarkRadius, color: GeoSelfMarkColor)
+    result.add GeoPrim(kind: gpMarkOther, cx: soSelf.other.x, cy: soSelf.other.y,
+                       r: GeoOtherMarkRadius, color: GeoOtherMarkColor)
+
+  # ENEMY heading line + its two intersection points.
+  let segEnemy = headingSegment(enemyX, enemyY, enemyHeading, halfLen)
+  result.add GeoPrim(kind: gpLineEnemy, x1: segEnemy.x1, y1: segEnemy.y1,
+                     x2: segEnemy.x2, y2: segEnemy.y2, color: GeoEnemyLineColor)
+  let ipEnemy = lineCircleIntersections(enemyX, enemyY, enemyHeading, c)
+  let soEnemy = pickSelfOther(ipEnemy, enemyX, enemyY)
+  if soEnemy.hasOther:
+    result.add GeoPrim(kind: gpMarkSelf, cx: soEnemy.self.x, cy: soEnemy.self.y,
+                       r: GeoSelfMarkRadius, color: GeoSelfMarkColor)
+    result.add GeoPrim(kind: gpMarkOther, cx: soEnemy.other.x,
+                       cy: soEnemy.other.y, r: GeoOtherMarkRadius,
+                       color: GeoOtherMarkColor)
+
+# ── emit to the GUI debug-graphics buffer ────────────────────────────────────
+
+proc emitGeoPrims*(prims: seq[GeoPrim]): int =
+  ## Emit the primitives into the current tick's SVG buffer. Thin lines.
+  for p in prims:
+    case p.kind
+    of gpCircle:
+      setStrokeColor(p.color)
+      setStrokeWidth(GeoCircleWidth)
+      drawCircle(p.cx, p.cy, p.r)
+    of gpLineSelf, gpLineEnemy:
+      setStrokeColor(p.color)
+      setStrokeWidth(GeoLineWidth)
+      drawLine(p.x1, p.y1, p.x2, p.y2)
+    of gpMarkSelf:
+      setStrokeColor(p.color)
+      setStrokeWidth(GeoMarkWidth)
+      drawCircle(p.cx, p.cy, p.r)
+    of gpMarkOther:
+      setFillColor(p.color)
+      fillCircle(p.cx, p.cy, p.r)
+  result = prims.len
+
+proc drawGeoOverlay*(selfX, selfY, selfHeading,
+                     enemyX, enemyY, enemyHeading: float): int =
+  ## Entry point called once per tick by ModularBot when `TR_GEO_DEBUG` is on.
+  ## Returns the number of primitives drawn.
+  emitGeoPrims(collectGeoPrims(selfX, selfY, selfHeading,
+                               enemyX, enemyY, enemyHeading))