Architecture

Architecture

Environments, agents and the renderer are decoupled behind small interfaces, so any applicable agent can run in any environment without either knowing about the other.

Package	Responsibility
internal/core	The interfaces connecting environments, agents and the renderer
internal/sim	The simulation loop, parallel evaluation, and telemetry
internal/envs	Environments — racing, cart-pole, maze, cube, flappy, chess
internal/agents	Learning algorithms — genetic algorithm, NEAT, Q-learning, EfficientCube, evochess
internal/nn	A small pure-Go trainable MLP (backprop, Adam) used by EfficientCube
internal/render	The backend-agnostic renderer, with the Ebiten draw backend under internal/render/ebiten
internal/gui	The Ebiten window and the Run/Available seam — built only with the ebiten tag
cmd/galapagos	The command-line entrypoint

Why the seam matters

internal/gui is the only package that needs the ebiten build tag. Everything above it — environments, agents, the simulation loop, even the renderer — is pure Go and runs headlessly. That is what allows:

• --headless training with no display
• the same renderer to target WebAssembly for the browser demo
• the whole learning path to be unit-tested without a GPU

Determinism

Runs are deterministic from their seed. A seed is chosen at random when none is given and logged, so any run can be reproduced afterwards with --seed N or a config seed. This is what makes replay exact rather than approximate.