bxl

A grid-based cellular automata runtime with live C compilation.

What It Does

bxl displays a grid of cells and runs user-defined automata logic on them every tick. The automata code is written in C and compiled at runtime using TCC via the ak24 CJIT module.

The main window shows the cell grid. An optional side panel provides control buttons, and a bottom panel displays up to 3 custom buttons defined by the automata code.

Features:

• Click cells to interact with your automata
• Keyboard input forwarded to automata code
• Custom buttons defined in C
• Multi-threaded cell processing
• Symbols and colors per cell

Dependencies

Dependency	Purpose	Required
ak24	Core library (threads, CJIT, logging, etc.)	Yes
SDL2	Window/rendering	Yes
TCC	Runtime C compilation	Yes (for CJIT)

Building ak24

git clone https://github.com/bosley/ak24
cd ak24
cmake -B build
cmake --build build
sudo cmake --install build

Installing TCC

macOS:

brew install tcc

Linux:

# Debian/Ubuntu
sudo apt install tcc libtcc-dev

# Arch
sudo pacman -S tcc

Building bxl

cmake -B build
cmake --build build

Usage

# Run with a project
./build/cmd/bxl/bxl --project examples/game_of_life.bxlproj

# Custom window size and thread count
./build/cmd/bxl/bxl --project examples/game_of_life.bxlproj --width 1024 --height 768 --threads 8

# Run without a project (default behavior, no automata)
./build/cmd/bxl/bxl

# Show all options
./build/cmd/bxl/bxl --help

Command-Line Options

Option	Description	Default
--project <path>	Load a .bxlproj manifest	None
--width <pixels>	Window width	640
--height <pixels>	Window height	480
--threads <count>	Number of processing threads	2
--help	Show usage information	-

Grid dimensions are auto-scaled based on window size (16 pixels per cell).

Settings can also be specified in the .bxlproj file—CLI arguments override project settings.

Projects

A .bxlproj file defines C source files to compile at runtime. See examples/ABOUT.md for the project format and API reference.

Example project: examples/game_of_life.bxlproj

Architecture

┌─────────────────────────────────────────────────┐
│  bxl                                            │
├─────────────────────────────────────────────────┤
│  main.c        - Application setup, event loop  │
│  process.c     - Thread pool, CJIT loading      │
│  project.c     - .bxlproj manifest parser       │
│  actions.c     - Mouse click handling           │
│  inputs.c      - Keyboard input handling        │
├─────────────────────────────────────────────────┤
│  pkg/grid      - Cell grid data structure       │
│  pkg/screen    - SDL2 window management         │
├─────────────────────────────────────────────────┤
│  ak24          - Threads, CJIT, logging, etc.   │
└─────────────────────────────────────────────────┘

How CJIT Works

1. bxl loads a .bxlproj manifest
2. Source files are compiled in-memory using TCC
3. bxl looks up entry point functions (bxl_automata, optionally bxl_get_buttons, bxl_on_key)
4. Every tick, bxl_automata is called for each cell with neighbor state
5. The returned output determines the cell's next state, color, and symbol

No restart required to change automata logic—just edit, save, and relaunch.