TermMatrix

Zero-Dependency Linux Terminal Sub-Pixel Dot-Matrix Graphics Engine (C11 & Python 3) — Featuring Forminal (Real-Time 2D FDTD Wave Physics & 4D Spacetime Tesseract Simulation)

---

1. Architectural Overview: Turning Any SSH Terminal Into a High-Density Framebuffer

Standard terminal interfaces are constrained by character-cell granularity (80×24 or 160×50) and a 1:2 vertical-to-horizontal aspect ratio distortion. TermMatrix bypasses these limits without requiring X11, Wayland, SDL, or external C libraries by treating every Unicode 8-dot Braille block (U+2800..U+28FF) as a 2 × 4 addressable sub-pixel matrix paired with 24-bit ANSI TrueColor luminance and SGR-1006 sub-cell mouse telemetry.

   Character Cell (cx, cy)              Unicode Bitmask (U+2800 + mask)
  ┌───────────┬───────────┐            ┌───────────┬───────────┐
  │ (0,0) Dot1│ (1,0) Dot4│            │   0x01    │   0x08    │
  ├───────────┼───────────┤            ├───────────┼───────────┤
  │ (0,1) Dot2│ (1,1) Dot5│   ──────►  │   0x02    │   0x10    │   chr(0x2800 | mask)
  ├───────────┼───────────┤            ├───────────┼───────────┤
  │ (0,2) Dot3│ (1,2) Dot6│            │   0x04    │   0x20    │
  ├───────────┼───────────┤            ├───────────┼───────────┤
  │ (0,3) Dot7│ (1,3) Dot8│            │   0x40    │   0x80    │
  └───────────┴───────────┘            └───────────┴───────────┘

Native Retro & Scientific Framebuffer Mapping

Because each character cell multiplies horizontal resolution by 2× and vertical resolution by 4×:

• Nintendo Game Boy (160 × 144 pixels): Fits 1:1 pixel-perfectly inside a standard 80 × 36 terminal window over plain SSH.
• Classic VGA Mode 13h / DOOM / PDE Grid (320 × 200 pixels): Fits 1:1 inside a 160 × 50 terminal window.
• Phosphor CRT Persistence (tm_blend_max): Implements additive max-luma RGB blending across decaying frame ring-buffers to simulate authentic Amber CRT (#FFB000 / #CC5500) cathode-ray persistence and ghost trails.
• Non-Clobbering HUD Cutouts: Automatically masks out underlying sub-pixel regions around ASCII telemetry labels and rounded box perimeters (╭─╮) so vector lines never corrupt readable text.

---

2. Repository Structure

TermMatrix/
├── include/
│   └── termmatrix.h              # Single-header C11 2x4 Braille framebuffer, Bresenham & SGR-1006 mouse engine
├── python/
│   └── termmatrix.py             # Zero-Pip Python 3 BrailleCanvas, 30° isometric SceneGraph pipeline & 3D demo
├── demos/
│   └── forminal/                 # Flagship C11 Demo: Forminal (2D FDTD Wave Solver + 4D Tesseract Simulation)
│       ├── Makefile              # Zero-dependency GCC C11 build + headless physics unit test runner
│       ├── scripts/              # One-click build.sh and run.sh wrappers
│       ├── src/
│       │   ├── core/             # GameOrchestrator state machine (Levels 0 through 7 Omega State)
│       │   ├── physics/          # 320x200 2D FDTD discrete wave solver (PML damping) & Minkowski EntropyLedger
│       │   ├── geometry/         # 3D Reality Cube & 4D Spacetime Tesseract Schlegel projection + Worldline ring buffer
│       │   ├── input/            # Decoupled bimanual SGR-1006 mouse & causal keyboard dispatcher
│       │   └── render/           # Amber CRT palette & TermMatrix sub-cell rasterization driver
│       └── tests/                # Deterministic C11 unit tests (FDTD conservation, Euler invariants, Novikov gate)
├── docs/
│   ├── FORMINAL_SPECIFICATION.md # Complete System Architecture, Physical Axioms & 9-Tier Storyboard Spec
│   └── dimensional_field_stack.html # Interactive Burnt-Orange CRT visual schematic of the 9-tier stack
├── tests/
│   └── test_termmatrix_c.c       # Headless C11 verification for 160x144 sub-pixel encoding & HUD cutouts
└── Makefile                      # Unified build and test suite

---

3. Flagship Demo: Forminal (Codename: Reality Operator)

Included in demos/forminal/ is Forminal, an ontological physics and 4D geometry simulation written in pure C11 on top of termmatrix.h.

Rather than simulating Newtonian point-masses, Forminal models reality as an emergent field stack inside an Amber CRT viewport (#FFB000 phosphor gradient framed by a #CC5500 Burnt Orange bezel):

1. 2D FDTD Wave Equation Solver (field_pde.c): Solves the discrete 2D wave equation over a 320 × 200 tensor with Perfectly Matched Layer (PML) boundary damping and an invariant energy conservation simplex ($\Phi(t) + \Psi(t) = E_0$).
2. 3D Reality Cube & 4D Spacetime Tesseract (cube_metric.c): Projects a canonical 3D Unit Cube ($\chi = V - E + F = 2$) and a 16-vertex, 32-edge 4D Hypercube ($\chi = V - E + F - C = 0$) through a $4\text{D} \to 3\text{D} \to 2\text{D}$ Schlegel perspective pipeline with 1:2 terminal aspect-ratio compensation.
3. Level 5 Phase Space Telemetry (Worldline Ghost Trails): Caches pre-projected 2D ScreenLine arrays in a 50ms temporal ring buffer and composites decaying phosphor worldlines beneath the active Tesseract using tm_blend_max.
4. Level 6 Novikov Relaxation Gate & Level 7 Omega State (entropy_ledger.c): Tracks relativistic Minkowski entropy debt ($\Delta S = \gamma (v^2/c^2) \Delta t$), runs a 10-pass harmonic relaxation solver on closed timelike curves (CTCs), and safely halts upon CFL thermal runaway.

Forminal Bimanual Controls

Input Channel	Hardware Device	Action	Physical Function
Spatial Breach	Mouse Left-Click / Drag	SGR-1006 Coordinates	Pierces the 320×200 field fabric (Level 1+ permanent/transient wave punctures).
Causal Fulcrum	Keys A / D or Mouse Wheel	Continuous $C$-Slider	Adjusts fabric impedance ($C$-rod) between Field Potential ($\Phi$) and Manifest Effect ($\Psi$).
Dimensional Shift	Keys W / S	Layer Stepper	Steps the viewport up/down across unlocked dimensional layers (Levels 0 – 7).
Field Flush	Shift + C	False Vacuum Reset	Triggers a supercritical phase flush, resetting active field defects to ground state.
Terminate	Key Q or Ctrl+C	Clean Shutdown	Restores POSIX termios state and exits alternate screen buffer.

---

4. Quick Start (Zero External Dependencies)

Build & Run Everything (C11 Engine + Forminal + Unit Tests)

Requires only gcc (or clang), make, and python3 on any Linux distribution:

git clone https://github.com/Tethtibis/TermMatrix.git
cd TermMatrix

# Run all C11 framebuffer, FDTD physics, 4D Euler invariant, and Python tests
make test

# Launch Forminal (Interactive C11 2D Wave + 4D Tesseract Simulation)
make run-forminal

Run the Zero-Pip Python 3 Demos

# Real-time 3D rotating wireframe cube in Unicode Braille
python3 python/termmatrix.py --demo-cube

# Render a 30-degree isometric 3D SceneGraph architecture diagram in the terminal
python3 python/termmatrix.py --preset pipeline
python3 python/termmatrix.py --preset forminal

Embedding termmatrix.h in Your Own C Project (Game Boy / Framebuffer Example)

#include "termmatrix.h"

int main(void) {
    tm_term_init();
    /* 80x36 character grid = 160x144 sub-pixel framebuffer (Game Boy resolution) */
    TmCanvas *canvas = tm_canvas_create(80, 36);

    tm_canvas_clear(canvas);
    tm_draw_rounded_border(canvas, TM_COLOR_BURNT_ORANGE);
    tm_draw_line(canvas, 4, 8, 155, 135, TM_COLOR_AMBER_PEAK);
    tm_put_str(canvas, 3, 0, " [160x144 DOT-MATRIX FRAMEBUFFER] ", TM_COLOR_AMBER_PEAK);
    tm_canvas_present(canvas);

    usleep(2000000);
    tm_canvas_destroy(canvas);
    tm_term_shutdown();
    return 0;
}

---

5. License

Released under the MIT License. Designed and engineered by Bill Fullen (@Tethtibis).