A simulated fruit-fly brain (FlyWire connectome) plays Game Boy games on a 24/7 stream.
23a4d7379b
The operator's decision of 2026-09-22: pay the fly for keeping a wild Pokemon, bump the adapter properly, and restart the live run from an early checkpoint rather than from scratch. The rule. `catch` is the catalog's ninth kind, appended so the key order `counts` serializes in does not move. 0.30 for a species this run had never owned, 0.10 for a repeat, three payouts per species for the lifetime of the ledger; the `species` rule is untouched, so a first catch of a new species pays 0.80 across two kinds. The catch is read from `wCapturedMonSpecies` ($d11c), whose comment in ram/wram.asm is "0 if no mon was captured": ItemUseBall zeroes it before every throw and writes wEnemyMonSpecies into it only on the branch that keeps the Pokemon, and UseBagItem's `.returnAfterCapturingMon` zeroes it again and sets wBattleResult to 2 -- a value written on exactly two paths in the game, that one and a link battle whose opponent ran. Both are required, so a byte read out of a half-initialised battle cannot pay. Not wPartyCount: a catch with a full party raises wBoxCount instead, and wPartyCount also rises for a gift, a trade and a PC withdrawal. "Never owned this run" is the `species` payout inside the same battle, because nothing else can set a Pokedex bit during one. It is not read off the captured species byte: that is the cartridge's internal index while the owned bitset is by Pokedex number, and nothing in WRAM converts between them. The address was resolved by tools/resolve_wram.py, not written by hand. The tool needed NUM_TMS and NUM_HMS, which the decomp defines through its `const` enumeration, so it now counts them from the file's own add_tm/add_hm definitions and cross-checks NUM_TMS against the literal the same file declares. The feed's kinds are closed, so `catch` publishes on `wildwin` and nothing in packages/feed or apps/stage changed. Deliberately not `pokedex`: the `species` rule already pays for the bit the same catch sets. The stage's ticker copy is keyed on the feed kind, so a catch row reads "wild win" -- stated in docs/rewards-learning.md rather than left to be discovered. v5 -> v6. STATE_VERSION stays 4: the rule adds one counter, `catchCounts`, and changes nothing else, so a v5 state restores with it empty. That migration is opt-in and needs all three of: the adapter segment being the only difference between the two compatibility strings, the running adapter listing the checkpoint's adapter in `migrates_from()`, and the deploy naming it in FLY_ACCEPT_ADAPTERS. flysim applies the rule at restore and 05-deploy's gate applies the same rule before it flips the symlink, writing the variable into fly.env so the two cannot disagree. The restart. infra/bin/fly-reset-to-milestone <N> archives both stores to a dated directory, rewrites milestone-<N>.checkpoint with the ratchet's attempts and recoveries at zero, installs it as the newest generation of both stores, clears the milestone archives above N and the event log, and prints what it did. It refuses while flysim is running and refuses a rung the run never reached. The envelope work is in flysim::reset (`flysim --reset-to-milestone N`); the shell script is the operator's wrapper. Tests: catalog values and order; a synthetic WRAM trace of a catch (new, repeat, cap, already-owned species, trainer/Safari/old-man/missed-ball negatives, rollback replay); a v5 state restoring with the counter at zero; a v5 checkpoint fixture accepted with the opt-in and refused without it; the reset tool against copies of a state dir in temp directories; and a ROM-gated catch from a rung-9 forest checkpoint, driven by the shipping THROW BALL macro. The compatibility string differs from main's in exactly one segment, checked by splitting both on `/`: pokered-unique8-v5 -> pokered-unique8-v6. |
||
|---|---|---|
| .forgejo/workflows | ||
| .github/workflows | ||
| apps/stage | ||
| data/fafb-v783 | ||
| docs | ||
| infra | ||
| packages | ||
| services | ||
| tools | ||
| .gitignore | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| LICENSES.md | ||
| Makefile | ||
| NOTICE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| ROM-POLICY.md | ||
flybrain
A simulated fruit-fly brain that plays video games. A connectome-constrained spiking network reads the screen, its population rates become controller inputs, and a scalar reward nudges a bounded set of Kenyon-cell to MBON gains.
The library is @flybrain/brain in packages/brain. It holds the connectome dataset format, the
LIF kernel, the plasticity rule, the population-rate readout and the activity-map geometry. It
holds no game, no emulator and no reward rules: those belong to whatever embeds it.
Workspace layout
| Path | Contents |
|---|---|
packages/brain |
the library (@flybrain/brain) |
data/fafb-v783 |
FlyWire-derived browser artifacts (CC BY-NC 4.0) |
tools/ |
the Python builder that regenerates data/ from official Codex exports |
docs/ |
overview, dataset format, model, plasticity, readout, integration, limitations, verification |
services/flysim |
the Rust service: brain, emulator, snapshot feed, control API, checkpoints |
apps/ |
planned: one directory per game demo |
infra/ |
planned: deployment for the 24/7 stream (see docs/streaming-plan.md) |
Quick start
npm ci
npm test
npm run typecheck
76 tests, about 7 seconds. There is no build step. npx tsx packages/brain/examples/node-random-frames.ts 60
runs the full 139,255-neuron brain with the Game Boy readout on noise frames in plain Node
(about 0.9x Game Boy real time single-threaded on a WSL laptop).
Usage
import { NeuralAgent, gameboyDecoderConfig, toButtonMask } from '@flybrain/brain';
import { loadBrainDatasetFromDir } from '@flybrain/brain/node';
const dataset = await loadBrainDatasetFromDir('data/fafb-v783');
const agent = new NeuralAgent(dataset, { decoder: gameboyDecoderConfig() });
agent.warmup(firstFrame); // 2,500 ms with plasticity off, then calibrate
// every emulator frame:
const { active } = agent.tick(framebuffer, { // RGBA 160x144 by default; any size via config
rewards: [{ value: 0.5 }], // scalar rewards your game adapter detected
boot: !inGame, // relaxes Start/Select throttling on title screens
});
emulator.setButtons(toButtonMask(active));
const checkpoint = agent.exportState(); // bit-exact resume, validated on import
The lower layers (LifNetwork, RewardModulatedStdp, PopulationDecoder) are exported too for
hosts that want to run the loop themselves.
integration.md has the full per-frame loop, the fractional frame timing and the checkpoint contract.
Documentation
- Overview: the pipeline, the layer map and the design principles.
- Dataset format: artifacts, CSR layout, weight encoding, every role and its count, fingerprinting, regeneration, license.
- Model: the 1-ms LIF kernel step by step, every default constant, the retina projection, the RNG, state export and version strings.
- Plasticity: edge selection, the eligibility and reinforcement equations, statistics, topology hash and the explicit non-claims.
- Readout: scores, exclusive groups, pulse channels, the blocked-direction cooldown, the Game Boy preset table and checkpoint versions.
- Integration: what a game must provide, the Pokemon Red integration as a worked example, and a sketch of a platformer adapter.
- Limitations: what is not claimed, what is unproven, measured throughput.
- Verification: the oracle-test strategy and what each test file covers.
- Streaming plan: headless capture, Twitch, VM design and the phased plan for a 24/7 stream.
- Artifact builder: how to regenerate and verify
data/fafb-v783. - Data attribution: source, license and citations.
Provenance
The network, plasticity rule, readout, FlyWire pipeline and activity viewer were extracted from
the fly-plays-pokemon prototype so several game demos can share one core. The default
configuration reproduces that prototype's kernel bit for bit, and verbatim copies of its modules
live in packages/brain/tests/legacy/ as oracles. Built with Astra.
Licensing
The data/fafb-v783 artifacts are derived from the FlyWire FAFB public Codex v783 exports and are
licensed CC BY-NC 4.0. That is a
non-commercial license, so a commercial demo needs a different data source or separate permission.
Citations and the list of modifications are in
data/fafb-v783/ATTRIBUTION.md.
No license has been chosen for the code in this repository yet.
ROMs and save states never enter this repository.