5.4 KiB
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.0 = identity = aims EXACTLY like Pattern
TR_BITBRAIN_MEM=decay
TR_BITBRAIN_LOG=1
⚠️ TR_BITBRAIN_GAINS=1.0 is the identity — with one candidate at 1.0 the gun aims exactly like Pattern.
Do not read the candidate list as a recommendation. Measured live: fixed gains above 1.0 are
decisively harmful (1.5 → −93.8 dmg/run, p=0.0006; 1.25 → −34.2 dmg/run), a learner restricted to ≤ 1.0
is a wash (−2.5 dmg/run, p=0.87), and zero lead (= HeadOn) is catastrophic (14 vs 279 dmg/run).
So the default set {0, 0.25, 0.5, 0.75, 1.0} is not a recommendation either — it merely allows the gun
to shrink the lead toward HeadOn. Multi-candidate lists are for running the experiment, not for playing.
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.