SirRoboGarage/common_libs/guns/bitbrain_gun.README.md

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.