go-boids

A go implementation of the boids simulation described by Craig Reynolds in 1986.

https://dl.acm.org/doi/10.1145/37402.37406

Output

Runs in the terminal with sparse ANSI updates, so only cells that changed are written on each rendered frame.

Scales the number of boids to the terminal size. Works best on larger terminals. Very large terminal sizes may cause performance issues.

Installation

go get github.com/cpcf/go-boids

Usage

go-boids

Headless mode

Run a deterministic simulation offline and print one summary line:

go-boids --headless --frames 10 --width 80 --height 24

Example output:

frames=10 width=80 height=24 boids=26 avg_speed=... min_speed=... max_speed=... centroid_x=... centroid_y=...

Set SEED in .env to make outputs reproducible between runs.

Runtime controls

During interactive terminal mode:

• Status/help output uses the last terminal row.
• q quits
• space pauses/resumes
• . advances a single step while paused
• s toggles the status line between help and simulation stats
• [ decreases RADIUS by 0.5
• ] increases RADIUS by 0.5
• - decreases MAX_SPEED by 0.1
• = increases MAX_SPEED by 0.1

These runtime adjustments apply immediately and persist until the simulation is resized or restarted.

Parameters

Configurable parameters are set in the .env file. Resize window or restart to apply changes.

Defaults and descriptions are as follows:

FPS               = 120   # Simulation steps per second
RENDER_FPS        = 60    # Terminal render frames per second; lower to reduce terminal I/O
BOUNCE            = true  # Bounce off walls
CLAMP_MIN_SPEED   = true  # Sets the minimum speed
TARGET_MIN_SPEED  = 0.05  # Minimum speed of boid if clamped
CELLS_PER_BOID    = 75    # Terminal cells per boid; smaller values mean more boids
SEED              = <unset> # Seed for deterministic initial positions/velocities; use 0 as valid seed

RADIUS            = 7.0   # Tiles from boid that affect it
MAX_SPEED         = 1.0   # Maximum speed of boid
ADJUST_RATE       = 0.025 # Rate of adjustment for alignment, cohesion, and separation
ALIGNMENT_RATE    = 1.0   # Muliplier for alignment adjustment
COHESION_RATE     = 1.0   # Muliplier for cohesion adjustment
SEPARATION_RATE   = 1.0   # Muliplier for separation adjustment