TinyTiny 3D Engine

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.

To set up a development version of this engine:

1. Clone this repository:

   git clone <repo_url>

2. Install uv (if needed):

   pip install uv

3. Create the environment and install project + dev dependencies:

   uv sync --group dev

4. Compile the Rust version locally:

   uv run maturin develop --profile release

5. Check the demo:

   PYTHONPATH=python uv run python demos/3d/some_models.py

   Browse every demos/2d and demos/3d script from one Textual menu:

   uv run python demos/all.py

6. Run the Rust unit tests.

   Maturin builds enable the Cargo feature extension-module (see pyproject.toml), which links PyO3 like a normal Python extension and avoids linking libpython. cargo test must not use that feature: default crate features are correct so the test harness links against the Python shared library.

   Pin which interpreter PyO3 uses (same idea as .github/workflows/fast-checks.yml) via PYO3_PYTHON—especially if several Python installs are on your machine.

   macOS / Linux (bash/zsh):

   bash scripts/cargo_test.sh

   Pass-through arguments go to Cargo (for example bash scripts/cargo_test.sh --lib).

   Windows (PowerShell):

   scripts/cargo_test.ps1

   Example with Cargo arguments (extra tokens after the script path are forwarded to cargo test):

   scripts/cargo_test.ps1 --lib

   If you are already in PowerShell: .\scripts\cargo_test.ps1 --lib.

   Without uv, set PYO3_PYTHON yourself and run cargo test; on Windows, prepend PATH with the directory containing python.exe, and usually %base_prefix%\DLLs and base_prefix, as in scripts/cargo_test.ps1.

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 pytest

Windows (PowerShell):

$env:PYTHONPATH='.'
uv run pytest

8. 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.sh

On Windows PowerShell:

.\scripts\bench_material.ps1

The 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

9. Regenerate TTSL opcode/ABI files after opcode definition changes:

bash scripts/gen_opcodes.sh

On Windows PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/gen_opcodes.ps1

From the repository root, regenerate the Sphinx HTML docs with:

uv run sphinx-build -b html source source/_build/html

For a fully clean rebuild:

rm -rf source/_build
uv run sphinx-build -b html source source/_build/html

On Windows PowerShell, use:

Remove-Item -Recurse -Force source\_build
uv run sphinx-build -b html source source/_build/html

Due 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...