A minimalistic 2D/3D engine implemented in Rust and bound to Python, designed to render 3D objects using ASCII art.
It focuses on terminal-friendly rendering experiments while keeping the engine small and hackable.
- Rendering Primitives: Supports points, lines, and triangles in both 2D and 3D contexts.
- ASCII Output: Renders 3D scenes in a charming ASCII art style.
- Color Shading Support: Renders with RGB colors.
- Materials: Supports 14 materials, including:
- Texture Mapping: Supports textures up to 256x256 pixels.
- Double Raster: Allows the use of 2 colors per ASCII character (background and foreground).
- Perlin Noise: Basic Perlin noise mapped texture.
| Terminal | Windows | macOS | Linux |
|---|---|---|---|
| wez Terminal | ⭐ Fastest rendering accross all terms | ||
| tabby | ⭐ Runs ok, struggle at big resolutions | ||
| default Windows Terminal | ❌ Can't keep up with the rendering | ||
| VScode terminal | ❌ Does not even works | ❌ Can't keep up with rendering | ❌ |
| gostty | ⭐ Perfect! | ⭐ Perfect, assuming you have your graphics drivers installed | |
| kitty | Almost perfect, start to slow down at HighRes | untested | |
| iTerm/iTerm2 | Won't keep up with high refresh rate (>10fps) |
To set up a development version of this engine:
-
Clone this repository:
git clone <repo_url>
-
Install uv (if needed):
pip install uv
-
Create the environment and install project + dev dependencies:
uv sync --group dev
-
Compile the Python extension locally:
uv run maturin develop --uv --profile release
-
Check the demo:
PYTHONPATH=python uv run python demos/3d/some_models.py
Browse every
demos/2danddemos/3dscript from one Textual menu:uv run python demos/all.py
-
Run the Python-independent Rust core tests.
The Cargo workspace separates the reusable engine in
crates/tt3de-corefrom the PyO3 extension incrates/tt3de-py. Core tests therefore need neither a Python interpreter nor PyO3 configuration:macOS / Linux (bash/zsh):
bash scripts/cargo_test.sh
The helper defaults to
cargo test -p tt3de-core; pass-through arguments go to Cargo (for examplebash scripts/cargo_test.sh --lib).Windows (PowerShell):
scripts/cargo_test.ps1Example with Cargo arguments:
scripts/cargo_test.ps1 --lib
If you are already in PowerShell:
.\scripts\cargo_test.ps1 --lib.The equivalent direct command on every platform is:
cargo test -p tt3de-coreTo check every Rust target, including the binding crate, run
cargo check --workspace --all-targets. Build and test the Python surface through Maturin and pytest as described in steps 4 and 7. -
Run the Python unit tests.
Build the extension in develop mode first (step 4); tests import the native tt3de module.
Pytest loads packages under tests/ (for example from tests.tt3de…), so keep the repository root on PYTHONPATH, matching CI’s working directory and AGENTS.md.
macOS / Linux (bash/zsh):
PYTHONPATH=. uv run pytestWindows (PowerShell):
$env:PYTHONPATH='.'
uv run pytest- Material shading threading benchmark (
test_bench_material_apply):
captures serial vs Rayon (1/2/4/8 threads) over several canvas sizes, writes benchmarks/material_apply.json, and prints a compact Rich KPI report (~100-column friendly). From the repository root:
./scripts/bench_material.shOn Windows PowerShell:
.\scripts\bench_material.ps1The report summarizes speedup vs serial (×ser), per-thread efficiency (η/T), scaling loss vs ideal linear speedup (loss), and a throughput bar per configuration. Expect roughly one minute on a typical CPU.
Equivalent manual invocation:
mkdir -p benchmarks
PYTHONPATH=python uv run pytest \
tests/benchs/r_code/test_bench_r_pix_shader.py::test_bench_material_apply \
--benchmark-only -q --benchmark-json=benchmarks/material_apply.json
uv run --no-sync python scripts/dev_material_bench_report.py benchmarks/material_apply.json- Regenerate TTSL opcode/ABI files after opcode definition changes:
bash scripts/gen_opcodes.shOn Windows PowerShell:
powershell -ExecutionPolicy Bypass -File scripts/gen_opcodes.ps1- TTSL execution benchmark (
cargo bench -p tt3de-core --bench all -- ttsl):
times Cranelift from the post-SSA CFG (jit / jit_cell) plus one-time compilation. See crates/tt3de-core/README.md for how to read the arms.
Its fixtures are generated from demos/, so regenerate them after editing a demo shader or the TTSL compiler:
make gen-ttsl-bench-fixturesOn Windows PowerShell:
uv run --no-sync python scripts/gen_ttsl_bench_fixtures.pyFrom the repository root, regenerate the Sphinx HTML docs with:
uv run sphinx-build -b html source source/_build/htmlFor a fully clean rebuild:
rm -rf source/_build
uv run sphinx-build -b html source source/_build/htmlOn Windows PowerShell, use:
Remove-Item -Recurse -Force source\_build
uv run sphinx-build -b html source source/_build/htmlDue to the mix of Python and Rust in this project, the Python code is located in the python folder. More information can be found here.
In launch.json for VSCode:
"env": {"PYTHONPATH": "${workspaceFolder}/python"}In settings.json:
{
"python.analysis.extraPaths": [
"python"
]
}- Many...