docs: quick-recap README for bitbrain gun (inputs/outputs, knobs, verdict)
This commit is contained in:
@@ -0,0 +1,98 @@
|
||||
# bitbrain_gun — quick recap (inputs / outputs)
|
||||
|
||||
Recap card. Everything below is read off `common_libs/guns/bitbrain_gun.nim`.
|
||||
|
||||
## What it is today
|
||||
|
||||
- A **lead-gain corrector on top of Pattern's prediction**. It scales Pattern's lead over the line of sight by a learned gain.
|
||||
- The **ADE/SBC neural network is REMOVED from the gun**. The name still says "BitBrain", but there is no net. The generic `common_libs/bitbrain/` library still exists and is tested separately (`test_bitbrain.nim`).
|
||||
|
||||
## INPUTS
|
||||
|
||||
| Input | Source in code |
|
||||
|---|---|
|
||||
| World state (self pos, enemy pos, tick) | `WorldState state` |
|
||||
| **Base aim** — Pattern's prediction | `g.tmh.pattern.predict(state, bulletSpeed)`: `TmHorizonGun.pattern`, a `PatternMatcherGun` (`guns/pattern_matcher`) |
|
||||
| Range band (5 bands: 0/100/200/300/450) | `bbBandOf(dist)`, `BB_BAND_LO/HI` |
|
||||
| **Gate** — gain applies only from band 3 up | `BB_GAIN_BAND_MIN = 3` → range **≥ ~300 px** |
|
||||
| **Label / feedback** — deferred observation lookup | at fire time store lead + tolerance; `h = round(dist/speed)` ticks later `tmhObservedAt(g.tmh, state.tick, selfX, selfY)` returns the enemy's OBSERVED bearing |
|
||||
| Aim tolerance (target's angular half-width) | `bbTolDeg(dist) = atan(18/range)` in degrees |
|
||||
| Config knobs | env, resolved once in `initBitBrainGun` (see table) |
|
||||
|
||||
## OUTPUTS
|
||||
|
||||
| Output | Formula / meaning |
|
||||
|---|---|
|
||||
| Aim point | `aim = LOS + gain * (patternAim - LOS)` — applied as angular `shift = (gain - 1.0) * lead` deg via `tmhApplyShift`; when `gain == 1.0` the base prediction is returned unchanged |
|
||||
| `gain` | argmax **hit rate** per band over the candidate list; `BB_CAND` default has **5 candidates** `{0.0, 0.25, 0.5, 0.75, 1.0}` (0 = HeadOn, 1 = Pattern); one candidate = fixed gain, no learning |
|
||||
| `[bb]` log line (only if `TR_BITBRAIN_LOG=1`; emitted only when `(gain, band)` changes) | see below |
|
||||
| Does **NOT** output | a predicted angle / bearing. It never aims on its own — it only rescales Pattern's lead. |
|
||||
|
||||
`[bb]` fields, one at a time:
|
||||
|
||||
| field | meaning |
|
||||
|---|---|
|
||||
| `t` | current tick |
|
||||
| `band` | lower edge of the range band in use (e.g. `300+`) |
|
||||
| `gain` | the gain being applied to Pattern's lead |
|
||||
| `shift` | angular shift actually applied = `(gain-1)*lead`, degrees |
|
||||
| `rate` | hit rate of the chosen gain in this band |
|
||||
| `n` | resolved samples in this band |
|
||||
| `ncand` | number of candidate gains |
|
||||
| `trained` | total resolved samples this battle |
|
||||
| `pend` | deferred labels still waiting |
|
||||
| `dropped` | labels that could not be resolved (stale / out-of-order) |
|
||||
| `mode` | memory mode: perRound / retained / decay |
|
||||
|
||||
## KNOB TABLE (`TR_BITBRAIN_*`)
|
||||
|
||||
**LIVE** — the resolved field is read by the learner/predict path:
|
||||
|
||||
| Env | Meaning |
|
||||
|---|---|
|
||||
| `TR_BITBRAIN_GAINS` | comma-separated candidate gains (replaces `BB_CAND`) |
|
||||
| `TR_BITBRAIN_MEM` | perRound / retained / decay memory |
|
||||
| `TR_BITBRAIN_MIN_OBS` | samples before a band is trusted (in `bbGain`) |
|
||||
| `TR_BITBRAIN_DECAY` | decay interval in resolved samples (`resolvePending`) |
|
||||
| `TR_BITBRAIN_DECAY_FRAC` | per-decay shrink of the hit counts (`bbApplyDecay`) |
|
||||
| `TR_BITBRAIN_LOG` | `1` = emit the `[bb]` line |
|
||||
| `TR_BITBRAIN_RESET_ON_TARGET` | wipe learning when the enemy id changes (`targetChanged`) |
|
||||
|
||||
**INERT** — kept only so old configs and the boot report don't warn; never touch the gain learner:
|
||||
|
||||
| Env | Stored as (only read by boot report / guard test) |
|
||||
|---|---|
|
||||
| `TR_BITBRAIN_N` | `nClasses` |
|
||||
| `TR_BITBRAIN_NADE` | `nAde` |
|
||||
| `TR_BITBRAIN_RANGE` | `maxDeg` |
|
||||
| `TR_BITBRAIN_WARMUP` | `warmupN` |
|
||||
| `TR_BITBRAIN_ADAPT` | `adaptEvery` |
|
||||
| `TR_BITBRAIN_CALIB` | `calibEvery` |
|
||||
| `TR_BITBRAIN_SEED` | `seed` |
|
||||
|
||||
*(Also `TR_RACK_BITBRAIN` — the rack admission switch, see below.)*
|
||||
|
||||
## HOW TO TURN IT ON
|
||||
|
||||
Default is **off**; the shipped rack never calls it. Minimal `.env`:
|
||||
|
||||
```
|
||||
TR_RACK_BITBRAIN=both
|
||||
TR_RACK_PATTERN=off
|
||||
TR_BITBRAIN_GAINS=1.0,1.25,1.5,2.0
|
||||
TR_BITBRAIN_MEM=decay
|
||||
TR_BITBRAIN_LOG=1
|
||||
```
|
||||
|
||||
⚠️ **Warning:** the **default** candidate set `{0, 0.25, 0.5, 0.75, 1.0}` can only reach 1.0 — it can only **shrink** the lead (toward HeadOn), which was measured **harmful** at long range. The useful set is the one that allows gains **above 1.0**: `1.0,1.25,1.5,2.0`.
|
||||
|
||||
## MEASURED VERDICT
|
||||
|
||||
- **Neutral vs Pattern** across many opponents: damage/run 214.5 vs 210.9, round wins 49.4% vs 49.8% over 32 opponents (`docs/gauntlet_bitbrain_vs_pattern.md`).
|
||||
- **Specifically worse on DrussGT** alone: −18.1 damage/run (`docs/gauntlet_bitbrain_vs_pattern.md`, `docs/bitbrain_gun_verdict.md`).
|
||||
- The **lead-amplitude (gain) axis is CLOSED** — nothing beats Pattern in either direction (`docs/bitbrain_campaign.md` §Phase 2 / §2.6).
|
||||
|
||||
## PROVENANCE
|
||||
|
||||
- **Derived from code (this file):** what it is today, all inputs, the output formula, the `[bb]` fields, the LIVE/INERT split, and the "how to turn it on" env lines.
|
||||
- **Taken from the named evidence docs:** the numbers in MEASURED VERDICT above — see `docs/gauntlet_bitbrain_vs_pattern.md`, `docs/bitbrain_gun_verdict.md`, `docs/bitbrain_campaign.md`.
|
||||
Reference in New Issue
Block a user