▜▘▞▘▞▄▚▝▛

2D Turing machine for your terminal.

Installation | Examples

Demo background by Raphael Rau

About

trmt can simulate multiple turmites simultaneously with customizable rules, colors, and characters, and has support for both relative and absolute turmites.

Running trmt will start a simulation with the default config.

Features

• Full Unicode support
• Up to 256 simultaneous heads
• Full color support: 16-color, 256-color, and RGB/hex
• Randomized rule generator with roughly 10^15 possible rules
• Deterministic seed-based simulation for reproducible patterns
• Highly configurable parameters for simulation, display and keybinds
• Several rule formats for various degrees of complexity
• Real-time interaction with configurable keybinds
• Toroidal grid with seamless wrapping

Installation

trmt only requires Rust with Cargo as a prerequisite.

From crates.io

cargo install trmt

From AUR (Arch Linux)

paru -S trmt

Using Flakes (Nix)

Add trmt to your flake as an input,

{
  inputs = {
    ... # other inputs
    trmt.url = "github:cenonym/trmt";
  };
}

Then, you can add inputs.trmt.packages.${pkgs.stdenv.hostPlatform.system}.default directly into your environment.systemPackages or home.packages:

{
  outputs = { nixpkgs, trmt, ... }: {
    nixosConfigurations.<mysystem> = nixpkgs.lib.nixosSystem {
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [ trmt.packages.${pkgs.stdenv.hostPlatform.system}.default ];
        })
      ];
    };
  };
}

{inputs, ...}: {
  imports = [
    inputs.trmt.homeManagerModules.default
  ];
programs.trmt = {
enable = true;
config = {
simulation = {
autoplay = true;
heads = 3;
rule = "RL";
speed_ms = 20;
trail_length = 30;
color_cells = true;
seed = "";
};
display = {
keycast = false;
colors = ["rgb(241, 113, 54)" "#45a8e9" "229"];
fade_trail_color = "";
state_based_colors = false;
live_colors = false;
head_char = ["██"];
trail_char = ["▓▓"];
cell_char = "░░";
randomize_heads = false;
randomize_trails = false;
direction_based_chars = false;
};
controls = {
quit = "q";
toggle = " ";
step = ".";
reset = "r";
faster = "+";
slower = "-";
config_reload = "c";
help = "h";
statusbar = "b";
randomize_seed = "s";
randomize_rule = "n";
randomize = "R";
};
};
};
}

Install from source

cargo install --git https://github.com/cenonym/trmt

Usage

Simply run trmt in your terminal to start a simulation.

trmt

Examples

Check out the examples to see some of the possibilities.

https://github.com/user-attachments/assets/eefc272b-09b2-4c9c-93dc-984c1ae60ed0

Controls

trmt has controls that can be used while the simulation is running. Keybinds can all be customized through the config file, but the defaults are:

Configuration

trmt automatically generates a default config file on first run, or if no config file is present. The location depends on your system:

• Unix/Linux: $XDG_CONFIG_HOME/trmt/config.toml or ~/.config/trmt/config.toml
• macOS: ~/Library/Application Support/trmt/config.toml
• Windows: %APPDATA%\trmt\config.toml

Config options

[simulation]
autoplay = true                     # If true, simulation starts running automatically on launch, reset and config reload
heads = 3                           # Number of heads on initialization
rule = "RL"                         # Rules for the simulation
speed_ms = 20                       # Simulation speed in milliseconds
trail_length = 24                   # Number of trail characters following the head
color_cells = true                  # If true, leaves behind an infinite trail of colored cell chars
seed = ""                           # Seed for initial position/direction. Empty = random
[display]
keycast = false                     # Displays the pressed key in bottom left corner, if key has an action
colors = [                          # Array of colors mapped to number of heads sequentially, using hex, RGB or 256-colors.
"rgb(241, 113, 54)",            # If there are more heads than colors, remaining colors are generated.
"#45a8e9",
"229",
]
fade_trail_color = ""               # Creates gradient trail from head color to this. Set to terminal bg color to fade out. Empty = no gradient
state_based_colors = false          # Printed cells use color config per state
live_colors = false                 # Heads change color with state, only works with state_based_colors = true
head_char = ["██"]                  # Array of head characters, cycles through it sequentially per step
trail_char = ["▓▓"]                 # Array of trail characters, where first character is mapped to first trail, and so on
cell_char = "░░"                    # The characters left behind the trail when color_cells = true
randomize_heads = false             # Randomize head character in head_char array
randomize_trails = false            # Randomize trail characters in trail_char array
direction_based_chars = false       # Map characters based on movement direction and turns
[controls]
quit = "q"                          # Quit
toggle = " "                        # Pause/resume simulation
step = "."                          # Step one tick (when paused)
reset = "r"                         # Reset simulation
faster = "+"                        # Increase simulation speed
slower = "-"                        # Decrease simulation speed
config_reload = "c"                 # Reload config
help = "h"                          # Toggle help overlay
statusbar = "b"                     # Toggle statusbar overlay
randomize_seed = "s"                # Generate random seed
randomize_rule = "n"                # Generate random rule
randomize = "R"                     # Generate random seed and rule

[!NOTE] State takes precedence over config and is used across sessions. Use c to clear states and reload config defaults, s/n to generate new random seeds and rules respectively.

Rules

Rules in trmt are what defines how the simulation will play out, and how the heads will behave. trmt provides you with tools to simulate everything from very basic sequential rules, all the way up to academic-level notation (don't quote me on this).

A rule consists of several states, and a state holds specific instructions on how a head should move when encountered. You can theoretically have several hundred states in a rule, but many of the most interesting patterns will appear with just 3-5 states.

Available states:

• L/R - Turn left/right
• U - U-turn (move backward)
• D - No turn (don't turn, move forward)
• N/S/E/W - Absolute directions
• NW/NE/SW/SE - Diagonal directions

The parser has deterministic left-to-right precedence, so "NE" always becomes diagonal, never N+E.

Basic sequential format Using the states above, we can create simple sequential rules that move through each state in turn. One of the simplest and most famous turmites is Langton's Ant, which can be replicated with trmt using just RL as a rule.

rule = "RL"

Or try something like WRSWNL or RRLL, or even RULE if you're feeling meta.

Rule operators In addition to these basic directional states, trmt also has logical operators for more complex rules:

• > - State transition (e.g. R>1 = turn right, go to state 1)
• , - Separates rule combinations for explicit state rules
• : - Separates states in multi-state rules

For precise control, you can specify which cell state to write:

• L1>1 = turn left, write cell state 1, go to state 1
• R0>0 = turn right, write cell state 0, go to state 0

This lets us translate a traditional turmite notation like {{{1, 8, 1}, {1, 8, 1}}, {{1, 2, 1}, {0, 1, 0}}} into a more opinionated readable syntax:

rule = "L1>1,L1>1:R1>1,D0>0"

Which constructs a Fibonacci spiral.

Standard notation support trmt also supports standard notation for compatibility.

rule = "{{{1, 8, 1}, {1, 8, 1}}, {{1, 2, 1}, {0, 1, 0}}}"

[!TIP] When experimenting with new rules, it is recommended to use 1 head for testing to make the simulation less chaotic.

Planned

• Improved error handling and printing - Added in v0.3.0
• Redesign help and statusbar TUI - Added in v0.3.0
• Per-state color customization - Added in v0.3.0
• Toggleable random characters for both heads and trails - Added in v0.4.0
• Gradient trails - Added in v0.4.0
• Clean up reset and config reload functions - Added in v0.5.0
• Random rule generation - Added in v0.5.0
• Direction based characters - Added in v0.6.0
• Proper wiki/documentation

Acknowledgements

A big thanks to:

• Raphael Rau for letting me use his SLV Console render as the background for the demo gif.
• Developers of cmatrix, pipes.sh, asciiquarium and the like for inspiring the creation of trmt.
• Ferkel on Wikipedia for turmite rule notations used in testing and development of the trmt rule syntax.
• orhun for packaging trmt on AUR
• yunusey for adding Nix flake and home-manager support

Contributing

You are very welcome to contribute to the project, be that through feature requests, improvements to the code or by adding functions. Please follow these steps:

1. Fork the repository
2. Create a branch with a conventional prefix (feat/, fix/, refactor/, etc.)
3. Make your changes
4. Build: cargo build
5. Check for issues: cargo clippy
6. Commit your changes, preferably following conventional commits
7. Push to your branch and open a Pull Request

Found a bug? Open an issue with details and steps to reproduce. Questions or suggestions? Let's discuss them.