Terminus – ASCII 3D Rendering Engine

Terminus is an ASCII-based 3D rendering engine for the terminal.
It renders real-time 3D scenes using characters, depth, and simple lighting.

How ASCII 3D works

Terminus projects 3D points from a scene onto a 2D terminal grid:

• Each shape is a collection of 3D vertices.
• The camera transforms and projects vertices into screen space.
• A Z-buffer keeps the closest point per character cell.
• A light direction and distance-based falloff produce a brightness value.
• Brightness is mapped to a configurable ASCII ramp (e.g. .:-=+*#%@).

The result is a live-updating ASCII frame buffer written directly to the console.

Installation

Requirements: Node.js (v14+ recommended) and a terminal that supports ANSI escape codes.

Install dependencies and build:

npm install
npm run build

Development / run examples (TypeScript):

# Install once
npm install

# Run a rotating-cube dev example (if provided)
npm run start:rotating-cube

Basic usage

import { Terminus } from "terminus-ascii-3d";

const scene = Terminus.SceneGraph();
const camera = Terminus.OrbitCamera(80 / 40);
const engine = Terminus.EngineFor(scene, camera, 80, 40);

// Create a cube
const cube = Terminus.Cube();
cube.VolumeUnit(Terminus.Measurements.Inches);
cube.Volume = 50;

cube.LengthA = 10;
cube.LengthB = 10;
cube.LengthC = 10;

cube.position.set(0, 0, 0);
cube.rotation.set(0, Math.PI / 4, 0);

scene.add(cube);

// Start engine
engine.start();

Grouping shapes

const group = Terminus.Group();
const cube = Terminus.Cube();
const sphere = Terminus.SphereShape();

cube.position.set(-1.5, 0, 0);
sphere.position.set(1.5, 0, 0);

group.add(cube);
group.add(sphere);
scene.add(group);

Camera and controls

• OrbitCamera: rotates around a target, supports zoom and pan.
• OrbitControls: keyboard + mouse orbit controls.

Keyboard defaults:

• Arrow keys: orbit around target
• • / -: zoom in / out
• Ctrl+C: exit

Mouse (where supported):

• Drag: orbit
• Wheel: zoom

Example:

const camera = Terminus.OrbitCamera(80 / 40);
Terminus.OrbitControls(camera, {
  rotateSpeed: 0.08,
  zoomSpeed: 0.5,
  panSpeed: 0.2
});

Shape list

Terminus ships with 30+ shapes, for example:

• Cube, Sphere, Cylinder, Cone, Pyramid, Torus, Plane, Prism
• Capsule, Wedge, Dome, Ellipsoid, Frustum, Ring, Stair, Arch
• Helix, Star, Gear, Tube, SpiralStair, Cross, Arrow, Heart
• Grid, Pipe, TextBlock, CustomMesh, Group, Scene

Each shape:

• Has dimensions (width, height, depth, radius, etc.)
• Supports translation, rotation, scaling via position, rotation, scale
• Renders as ASCII using the shared renderer

Custom meshes

import { Terminus } from "terminus-ascii-3d";
const { Vector3 } = Terminus;

const vertices = [
  new Vector3(0, 0, 0),
  new Vector3(1, 0, 0),
  new Vector3(0, 1, 0)
];

const mesh = Terminus.CustomMeshShape(vertices);
scene.add(mesh);

API examples

Volume and measurements:

const cube = Terminus.Cube();
cube.VolumeUnit(Terminus.Measurements.Inches);
cube.Volume = 100;
cube.position.set(0, 0, 0);
cube.rotation.set(0, Math.PI / 4, 0);
scene.add(cube);

Combining shapes:

const group = Terminus.Group();

const base = Terminus.CylinderShape();
base.height = 1;
base.radius = 1.5;
base.position.set(0, -0.5, 0);

const dome = Terminus.DomeShape();
dome.radius = 1.5;
dome.position.set(0, 0.5, 0);

group.add(base);
group.add(dome);
scene.add(group);

Contributing

Contributions and bug reports are welcome. Please follow repository guidelines and open issues or PRs.

License

See repository LICENSE file for details.