# BeeBrain BeeBrain is a Fabric mod that lets Minecraft bees be controlled by a pinned full flybrain connectome simulation in real time. | | Verified value | | --- | --- | | Minecraft / Fabric | Minecraft Java 26.2, Fabric Loader 0.19.3, Fabric API 0.156.0+26.2 | | Connectome | 139,255 neurons, 2,698,236 weighted connections | | Neural state | 100 independent bee states in the production batch path; one shared immutable connectome | | Live scale | approximately 10 neural updates/s per bee at 100 active bees; 1,005 aggregate updates/s in the clean production run | | Correctness | reference-exact parity with pinned upstream flybrain fixtures and topology/weight checks | The project is complete for its defined technical scope and prepared for a public `v1.0.0` BeeBrain source release. The original BeeBrain source/documentation is MIT-licensed; FlyWire-derived data remains separate CC BY-NC 4.0 data and is not included in the repository or release assets. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md) and [LICENSE_STATUS.md](LICENSE_STATUS.md). ## What BeeBrain does ```text Minecraft Bee -> authoritative server sensor snapshot -> explicit synthetic BeeBrain adapter -> real, non-empty neural populations -> unchanged full pinned flybrain connectome simulation -> real neural group activity -> synthetic neural-only movement projection -> server-authoritative Minecraft movement ``` Each bee is identified by its Minecraft UUID and owns independent mutable neural state. The immutable topology, normalized weights, and group layout are loaded once and shared. The live path sends one `/step-batch` cohort every two Minecraft ticks, with one in-flight request and one replaceable latest pending cohort. ## What is real and what is synthetic ### Real / connectome-derived - The pinned upstream topology and group membership. - The 139,255-neuron, 2,698,236-edge runtime artifact. - Connectome weights and normalized float32 storage. - The upstream LIF state transitions, propagation order, refractory behavior, thresholds, and resulting neural activity. ### Synthetic BeeBrain layer - Mapping Minecraft observations onto neural populations. - Mapping neural group activity to Minecraft velocity. - The use of `GNG_DESC` as a generic descending-motor proxy for Minecraft vertical lift. BeeBrain does not claim that a fly brain understands Minecraft, that these mappings are biological Minecraft behaviors, or that the result is a validated biological fly-behavior model. `GNG_DESC` is not presented as an identified flight-command population. ## Production mappings The current Minecraft sensor contract is deliberately small and explicit: ```text dx / dz -> CX_PFN dy -> CX_HDELTA light -> CX_FC, CX_EPG, VIS_R1R6 hasNectar -> OLF_ORN_FOOD, GUS_GRN_SWEET ``` `timeOfDay` is not part of the production contract. Zero-neuron metadata groups are retained in the pinned artifact but are not production stimulation or decoder targets. The movement decoder consumes only neural group activity: ```text walk -> existing real neural walk expression turn -> 0.5 * activity(CX_HDELTA) lift_proxy -> activity(GNG_DESC) vy -> tanh(lift_proxy) * 0.05 ``` Every production stimulation and decoder group is asserted to have at least one real neuron. The decoder does not accept sensors, request objects, Minecraft state, or raw `dx/dy/dz/light/hasNectar` values. ## Correctness The pinned upstream reference is commit [`9191824d17871b7851645782d53d23f213ddb938`](https://github.com/snedea/flybrain/tree/9191824d17871b7851645782d53d23f213ddb938). The loaded compressed connectome artifact has SHA-256 `fbf8d440ca1207c7573e1acdd2366f9d0beb9b533c1710f21681264f81b1cc49`. Verification covers: - topology and normalized-weight bit patterns; - reference-exact differential parity against the pinned `sim-worker.js` behavior; - frozen scalar oracle versus optimized and strict-JIT kernels; - independent batch-lane parity and lane permutation; - causal sensor → stimulation → neural state → decoder → movement traces; - neural-only decoder, zero-neuron exclusion, vertical/turn intervention and ablation tests; - authoritative server-thread movement application; - stale, out-of-generation, timeout and delayed-result rejection. Detailed evidence is in [verification/](verification/), with a compact technical research pack in [research-pack/](research-pack/). The research pack is development/research evidence, not a runtime dependency. ## Performance The table below is the verified live Minecraft/FastAPI batched path. It is not the standalone core benchmark. Aggregate updates are completed full-connectome results across the cohort; per-bee updates are aggregate divided by cohort size. | Active bees | Aggregate updates/s | Updates/s per bee | HTTP p50 / p95 (ms) | Kernel p95 (ms) | Minecraft TPS | MSPT | | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | 1 | 10.00 | 10.00 | 20.07 / 24.98 | 24.11 | 20 | 0.145 | | 10 | 100.00 | 10.00 | 37.37 / 43.21 | 41.56 | 20 | 0.167 | | 30 | 300.00 | 10.00 | 23.34 / 26.80 | 25.16 | 20 | 0.233 | | 64 | 640.00 | 10.00 | 26.91 / 31.67 | 28.91 | 20 | 0.218 | | 100 | 1,005.00 | 10.05 | 29.11 / 36.06 | 32.53 | 20 | 0.374 | The final adapter-cleanup regression window remained within the target at 992.75 aggregate / 9.93 per-bee updates/s. Brain-service working-set RSS was 273.90 MiB mean and 274.47 MiB peak across the measured 100-bee/churn run, with 0.13 MiB RSS growth over the sustained 60-second window. See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) and [verification/live_batch_memory.json](verification/live_batch_memory.json). ## Failure and recovery - If the brain service is unavailable, times out, or produces invalid/stale results, affected bees return to vanilla behavior through the existing hysteresis policy. - Results are checked against UUID, generation, sequence, age, entity eligibility and finite velocity bounds. - A service restart creates a new generation; old results cannot be applied. - Fresh valid neural results restore neural control after the required good-result window. - The live scheduler has one in-flight batch and one replaceable latest pending cohort. Historical neural work is not queued indefinitely. - Minecraft sensor capture and movement application run on the authoritative server thread. HTTP and neural work run off-thread using immutable snapshots; the server tick never waits for the service. ## Architecture ```text beebrain-mod/ Fabric 26.2 server/client entrypoint and isolated run configuration brain-service/ FastAPI service, UUID-owned batch state, validation and telemetry flybrain-core/ headless connectome loader, reference/optimized/batched kernels and adapter flybrain-upstream/ pinned, unmodified upstream implementation and local data artifact verification/ machine-readable parity, live-runtime, failure/recovery and memory evidence research-pack/ compact external research inputs; not required at runtime minecraft-instance/ isolated development/test runtime, generated locally and not the normal .minecraft ``` The connectome data is loaded once. A bee's state is created on first appearance, retained for the documented temporary-unload window, retired after 60 seconds without observation, and recreated after that or after a Minecraft/service restart according to the runtime lifecycle policy. ## Quick start The commands below are for the isolated instance in this repository. They do not use or modify `%APPDATA%\\.minecraft` or launcher profiles. Prerequisites: Windows 11, Git, Java 25, Python 3.12, Gradle 9.5.1, and an authoritative local copy of the required FlyWire FAFB v783 data. The Gradle scripts use the local `gradle-9.5.1` directory when present, otherwise `gradle.bat` on `PATH`. FlyWire-derived data is separate CC BY-NC 4.0 data and is intentionally not bundled. ```powershell cd \beebrain-full .\scripts\setup-upstream.ps1 # If the setup script reports missing data, obtain the authoritative FAFB v783 # files under their separate CC BY-NC 4.0 terms, place the required files in # flybrain-upstream\data, and rerun the setup script. py -3.12 -m venv .venv-jit .\.venv-jit\Scripts\Activate.ps1 python -m pip install -r brain-service\requirements-jit.txt $env:BEEBRAIN_BATCH_JIT = '1' python brain-service\app.py ``` In a second PowerShell window: ```powershell cd \beebrain-full .\scripts\build.ps1 .\scripts\run-minecraft.ps1 ``` To start the optional development client in a third window: ```powershell cd \beebrain-full .\scripts\run-client.ps1 ``` The server and client use `minecraft-instance/` only. The first run may download Minecraft/Fabric dependencies into Gradle’s cache. The service must be running before neural control can become healthy; vanilla fallback remains available when it is not. ## Verification Run the Python verification suite from the repository root: ```powershell powershell -File scripts\verify.ps1 ``` Useful focused checks include: ```powershell python scripts\differential_parity.py python scripts\optimized_parity.py python scripts\batch_parity.py python scripts\jit_propagation_parity.py python scripts\jit_elementwise_parity.py python scripts\adapter_correctness.py .\scripts\build.ps1 ``` The final live trace is [verification/minecraft_runtime_trace.json](verification/minecraft_runtime_trace.json). It records the sensor snapshot, non-empty stimulation targets, neural activity before/after, neural-only decoder values, accepted result and server-thread movement. ## Limitations - Minecraft-to-neural mappings are explicitly synthetic and are not claims about biological fly behavior. - The project follows the semantics of the pinned upstream flybrain implementation and its data snapshot; it is not a new biological model. - `GNG_DESC` is a generic descending-motor projection for Minecraft lift, not an identified flight command. - The connectome is a brain dataset; it does not become a biologically complete Minecraft locomotion controller through the adapter. - Performance and memory measurements are machine, runtime, and workload dependent. - The non-JIT batch path is retained for comparison/reference and is not the production performance path. - Original BeeBrain source and documentation are MIT-licensed; upstream flybrain and FlyWire-derived data retain their separate notices and terms. ## Provenance and attribution The upstream implementation is [snedea/flybrain](https://github.com/snedea/flybrain), pinned to commit `9191824d17871b7851645782d53d23f213ddb938` and carrying its MIT notice in [flybrain-upstream/license.md](flybrain-upstream/license.md). The connectome is derived from FlyWire FAFB v783. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md) for the data identity, checksum, scientific citation and separate data terms. Do not assume that the upstream MIT license covers FlyWire-derived data or BeeBrain-specific code. ## Project status Implementation status: complete for the defined BeeBrain production scope, including correctness, live performance, failure/recovery, bounded memory and final adapter cleanup. The repository is prepared for a public `v1.0.0` source release. The release excludes FlyWire-derived data; users must obtain that data separately under the documented CC BY-NC 4.0 terms.