3D Rendering API

WebGPU-powered 3D rendering for terminal UIs using Three.js

Overview

OpenTUI provides a complete 3D rendering system powered by WebGPU and Three.js, allowing you to render 3D scenes directly in terminal applications. The API includes support for textures, sprites, animations, and physics.

ThreeRenderable

The main component for rendering 3D scenes in your terminal UI.

Constructor

import { ThreeRenderable } from "@opentui/core"
import { Scene, PerspectiveCamera } from "three"

const scene = new Scene()
const camera = new PerspectiveCamera(75, 16/9, 0.1, 1000)

const renderable = new ThreeRenderable(ctx, {
  scene,
  camera,
  renderer: {
    backgroundColor: RGBA.fromValues(0, 0, 0, 1),
    superSample: SuperSampleType.GPU,
    alpha: false
  },
  autoAspect: true,
  width: 80,
  height: 40
})

ctx · RenderContext · required

The render context (typically a CliRenderer instance)

options · ThreeRenderableOptions · required

Configuration options

Show properties

scene · Scene | null

Three.js scene to render

camera · PerspectiveCamera | OrthographicCamera

Camera to use for rendering

renderer · ThreeCliRendererOptions

Renderer configuration options

Show ThreeCliRendererOptions

backgroundColor · RGBA

Background color for the scene

superSample · SuperSampleType · default: "SuperSampleType.GPU"

Anti-aliasing mode:

• SuperSampleType.NONE - No anti-aliasing
• SuperSampleType.GPU - GPU-based super sampling (fastest)
• SuperSampleType.CPU - CPU-based super sampling

alpha · boolean · default: "false"

Enable alpha channel transparency

focalLength · number

Camera focal length for perspective calculations

libPath · string

Path to native WebGPU library

autoAspect · boolean · default: "true"

Automatically adjust camera aspect ratio on resize

width · number

Width in terminal cells

height · number

Height in terminal cells

live · boolean · default: "true"

Enable live rendering mode

Properties

renderer · ThreeCliRenderer

Access to the underlying renderer

aspectRatio · number

Current aspect ratio of the render area

Methods

getScene()

Gets the current scene.

const scene = renderable.getScene()

scene · Scene | null

The current Three.js scene

setScene()

Sets a new scene to render.

renderable.setScene(newScene)

scene · Scene | null · required

The new scene to render

getActiveCamera()

Gets the active camera.

const camera = renderable.getActiveCamera()

camera · PerspectiveCamera | OrthographicCamera

The active camera

setActiveCamera()

Sets a new active camera.

renderable.setActiveCamera(newCamera)

camera · PerspectiveCamera | OrthographicCamera · required

The new camera to use

setAutoAspect()

Enables or disables automatic aspect ratio adjustment.

renderable.setAutoAspect(true)

autoAspect · boolean · required

Whether to automatically adjust aspect ratio

ThreeCliRenderer

Low-level renderer for Three.js scenes.

Constructor

import { ThreeCliRenderer, SuperSampleType } from "@opentui/core"

const renderer = new ThreeCliRenderer(cliRenderer, {
  width: 160,
  height: 80,
  superSample: SuperSampleType.GPU,
  backgroundColor: RGBA.fromValues(0, 0, 0, 1),
  alpha: false,
  autoResize: true
})

cliRenderer · CliRenderer · required

The CLI renderer instance

options · ThreeCliRendererOptions · required

Renderer options (same as ThreeRenderable’s renderer options, plus width/height/autoResize)

Methods

init()

Initializes the WebGPU renderer. Must be called before rendering.

await renderer.init()

drawScene()

Renders a scene to a buffer.

await renderer.drawScene(scene, buffer, deltaTime)

scene · Scene · required

Scene to render

buffer · OptimizedBuffer · required

Target buffer to render into

deltaTime · number · required

Time elapsed since last frame in seconds

setSize()

Resizes the renderer.

renderer.setSize(100, 50)

width · number · required

New width in cells

height · number · required

New height in cells

forceUpdate · boolean · default: "false"

Force resize even if dimensions haven’t changed

setBackgroundColor()

Changes the background color.

renderer.setBackgroundColor(RGBA.fromHex("#001122"))

color · RGBA · required

New background color

saveToFile()

Saves the current frame to an image file.

await renderer.saveToFile("/path/to/screenshot.png")

filePath · string · required

Path where the image should be saved

toggleSuperSampling()

Cycles through super sampling modes.

renderer.toggleSuperSampling()
// Cycles: NONE → CPU → GPU → NONE

destroy()

Cleans up renderer resources.

renderer.destroy()

TextureUtils

Utility class for loading and generating textures.

TextureUtils.loadTextureFromFile()

Loads a texture from an image file.

import { TextureUtils } from "@opentui/core"

const texture = await TextureUtils.loadTextureFromFile("./texture.png")

path · string · required

Path to the image file

texture · DataTexture | null

Loaded texture, or null if loading failed

TextureUtils.fromFile()

Alias for loadTextureFromFile().

const texture = await TextureUtils.fromFile("./texture.png")

TextureUtils.createCheckerboard()

Creates a procedural checkerboard texture.

import { Color } from "three"

const texture = TextureUtils.createCheckerboard(
  256,
  new Color(1, 1, 1),
  new Color(0, 0, 0),
  32
)

size · number · default: "256"

Texture size in pixels (width and height)

color1 · Color · default: "white"

First checker color

color2 · Color · default: "black"

Second checker color

checkSize · number · default: "32"

Size of each checker square in pixels

texture · Texture

Generated checkerboard texture

TextureUtils.createGradient()

Creates a procedural gradient texture.

const texture = TextureUtils.createGradient(
  256,
  new Color(1, 0, 0),
  new Color(0, 0, 1),
  "vertical"
)

size · number · default: "256"

Texture size in pixels

startColor · Color · default: "red"

Gradient start color

endColor · Color · default: "blue"

Gradient end color

direction · 'horizontal' | 'vertical' | 'radial' · default: "vertical"

Gradient direction

texture · Texture

Generated gradient texture

TextureUtils.createNoise()

Creates a procedural noise texture.

const texture = TextureUtils.createNoise(
  256,
  1.0,
  4,
  new Color(1, 1, 1),
  new Color(0, 0, 0)
)

size · number · default: "256"

Texture size in pixels

scale · number · default: "1"

Noise scale factor

octaves · number · default: "1"

Number of noise octaves

color1 · Color · default: "white"

High noise value color

color2 · Color · default: "black"

Low noise value color

texture · Texture

Generated noise texture

SpriteUtils

Utility class for creating sprite objects.

SpriteUtils.fromFile()

Creates a sprite from an image file.

import { SpriteUtils } from "@opentui/core"

const sprite = await SpriteUtils.fromFile("./character.png", {
  materialParameters: {
    alphaTest: 0.5,
    depthWrite: true
  }
})
scene.add(sprite)

path · string · required

Path to the sprite image

options · object

Show properties

materialParameters · SpriteMaterialParameters

Three.js SpriteMaterial parameters (excluding map)

sprite · Sprite

Three.js Sprite with loaded texture

SpriteUtils.sheetFromFile()

Creates an animated sprite from a sprite sheet.

const sprite = await SpriteUtils.sheetFromFile("./walk.png", 8)
sprite.setIndex(0) // First frame
scene.add(sprite)

path · string · required

Path to the sprite sheet image

numFrames · number · required

Number of frames in the sprite sheet

sprite · SheetSprite

Sprite with frame selection capability

SpriteAnimator

Advanced sprite animation system with instancing support.

Constructor

import { SpriteAnimator } from "@opentui/core"
import { Scene } from "three"

const scene = new Scene()
const animator = new SpriteAnimator(scene)

scene · Scene · required

Three.js scene to add sprite meshes to

createSprite()

Creates a new animated sprite instance.

const sprite = await animator.createSprite({
  initialAnimation: "idle",
  animations: {
    idle: {
      resource: idleResource,
      animNumFrames: 4,
      animFrameOffset: 0,
      frameDuration: 150,
      loop: true
    },
    walk: {
      resource: walkResource,
      animNumFrames: 8,
      animFrameOffset: 0,
      frameDuration: 100,
      loop: true
    }
  },
  scale: 1.0,
  renderOrder: 0,
  depthWrite: true,
  maxInstances: 1024
})

definition · SpriteDefinition · required

Sprite configuration

Show SpriteDefinition properties

id · string

Optional unique identifier

initialAnimation · string · required

Name of the starting animation

animations · Record<string, AnimationDefinition> · required

Map of animation names to definitions

Show AnimationDefinition properties

resource · SpriteResource · required

Sprite sheet resource

animNumFrames · number

Number of frames in this animation

animFrameOffset · number · default: "0"

Starting frame in the sprite sheet

frameDuration · number · default: "100"

Duration per frame in milliseconds

loop · boolean · default: "true"

Whether to loop the animation

initialFrame · number · default: "0"

Starting frame index

flipX · boolean · default: "false"

Flip horizontally

flipY · boolean · default: "false"

Flip vertically

scale · number · default: "1.0"

Initial scale

renderOrder · number · default: "0"

Rendering order for depth sorting

depthWrite · boolean · default: "true"

Enable depth buffer writes

maxInstances · number · default: "1024"

Maximum sprite instances for this definition

materialFactory · () => NodeMaterial

Optional factory function for custom materials

sprite · TiledSprite

Animated sprite instance

update()

Updates all sprite animations.

animator.update(deltaTime)

deltaTime · number · required

Time elapsed since last update in milliseconds

removeSprite()

Removes a sprite by ID.

animator.removeSprite("player-sprite")

id · string · required

ID of the sprite to remove

removeAllSprites()

Removes all sprites.

animator.removeAllSprites()

TiledSprite

Animated sprite instance created by SpriteAnimator.

Properties

id · string

Unique identifier

visible · boolean

Visibility state (get/set)

Methods

setAnimation()

Switches to a different animation.

await sprite.setAnimation("walk")

name · string · required

Name of the animation to switch to

setPosition()

Sets the sprite’s position.

import { Vector3 } from "three"

sprite.setPosition(new Vector3(10, 0, 5))

position · Vector3 · required

New position

setRotation()

Sets the sprite’s rotation.

import { Quaternion } from "three"

sprite.setRotation(new Quaternion())

rotation · Quaternion · required

New rotation

setScale()

Sets the sprite’s scale.

sprite.setScale(new Vector3(2, 2, 1))

scale · Vector3 · required

New scale

play() / stop()

Controls animation playback.

sprite.play()
sprite.stop()

goToFrame()

Jumps to a specific frame.

sprite.goToFrame(5)

frame · number · required

Frame index to jump to

setFrameDuration()

Changes the frame duration for the current animation.

sprite.setFrameDuration(200) // 200ms per frame

duration · number · required

New frame duration in milliseconds

Example: 3D Scene

import { ThreeRenderable, SuperSampleType, TextureUtils } from "@opentui/core"
import { Scene, PerspectiveCamera, Mesh, BoxGeometry, MeshBasicMaterial } from "three"

const scene = new Scene()
const camera = new PerspectiveCamera(75, 16/9, 0.1, 1000)
camera.position.z = 5

// Create a textured cube
const texture = await TextureUtils.createCheckerboard()
const geometry = new BoxGeometry(1, 1, 1)
const material = new MeshBasicMaterial({ map: texture })
const cube = new Mesh(geometry, material)
scene.add(cube)

// Create renderable
const renderable = new ThreeRenderable(ctx, {
  scene,
  camera,
  renderer: {
    backgroundColor: RGBA.fromValues(0.1, 0.1, 0.2, 1),
    superSample: SuperSampleType.GPU
  },
  width: 80,
  height: 40
})

// Rotate cube
setInterval(() => {
  cube.rotation.x += 0.01
  cube.rotation.y += 0.01
}, 16)