tslime 0.1.0

A lightweight terminal screensaver simulating slime mold growth patterns
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# Contributing to tslime

Contributions are welcome — bug fixes, new presets and palettes, terminal
compatibility reports, performance work, and progress on the experimental
features. If you're unsure whether something fits, open an issue first and ask.

## Where help is wanted

- **Experimental features.** Multi-species simulation (#8), choir audio (#9),
  GUI mode (#10), WASM build (#11), and dithering (#12) all exist behind gates
  and need work before they join the default experience. Each tracking issue
  describes the current state.
- **Preset and palette feedback.** If a preset collapses, stalls, or just looks
  wrong in your terminal, an issue with the preset name, seed, and terminal
  details is genuinely useful.
- **Terminal compatibility reports.** tslime targets Linux, macOS, Windows, and
  SSH sessions. Reports from unusual terminals, multiplexers, and font setups
  help.

## Development setup

Requires Rust 1.70 or later.

```bash
git clone https://github.com/tamirelazar/tslime.git
cd tslime
cargo build
cargo run -- -S
```

## Testing

```bash
cargo test --lib                          # unit tests
cargo test --test visual_regression      # golden-file tests (tests/golden/)
cargo bench                               # criterion benchmarks
```

If a change intentionally alters visual output, regenerate the golden files:

```bash
UPDATE_GOLDEN=true cargo test --test visual_regression
```

Commit golden changes only when the output change is intentional — review the
diff and make sure it shows what you meant to change.

## Feature flags

The default build enables only the `terminal` feature. Experimental features
are opt-in:

| Feature | What it adds | Issue | Build |
|---|---|---|---|
| `multi-species` | Multiple agent species with independent parameters | #8 | `cargo build --features multi-species` |
| `audio` | Choir mode: sonifies the simulation via cpal | #9 | `cargo build --features audio` |
| `gui` | Windowed GUI mode built on iced | #10 | `cargo build --features gui` |

## Architecture

```
src/
├── cli.rs          # clap argument definitions, validation, mode dispatch
├── app/            # run loop, mode handlers, --explain output
├── simulation/     # agents (sense/rotate/move/deposit), trail map, presets, config
├── render/         # downsampling, character sets, OKLch palettes, overlays/panels
├── terminal/       # screen lifecycle, input polling, frame buffer, runtime controls
└── export/         # GIF, PNG, and WebM export
```

Data flow per frame: agents sense the trail map, rotate, move, and deposit
pheromone; the trail map is diffused and decayed; the grid is downsampled to
terminal dimensions; cells are mapped through the active character set and
palette; the result is written to stdout as a single ANSI frame.

## Before submitting

```bash
cargo fmt
cargo clippy -- -D warnings
cargo test
```

Work on a feature branch (`feat/...`, `fix/...`, `chore/...`) and open a PR
against `master`. Commit messages use the form `type: description`, where type
is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, or `chore`.