3D Rendering API

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

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")

string

required

ID of the sprite to remove

removeAllSprites()

Removes all sprites.

animator.removeAllSprites()

TiledSprite

Animated sprite instance created by SpriteAnimator.

Properties

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)

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

​Overview

​ThreeRenderable

​Constructor

​Properties

​Methods

​getScene()

​setScene()

​getActiveCamera()

​setActiveCamera()

​setAutoAspect()

​ThreeCliRenderer

​Constructor

​Methods

​init()

​drawScene()

​setSize()

​setBackgroundColor()

​saveToFile()

​toggleSuperSampling()

​destroy()

​TextureUtils

​TextureUtils.loadTextureFromFile()

​TextureUtils.fromFile()

​TextureUtils.createCheckerboard()

​TextureUtils.createGradient()

​TextureUtils.createNoise()

​SpriteUtils

​SpriteUtils.fromFile()

​SpriteUtils.sheetFromFile()

​SpriteAnimator

​Constructor

​createSprite()

​update()

​removeSprite()

​removeAllSprites()

​TiledSprite

​Properties

​Methods

​setAnimation()

​setPosition()

​setRotation()

​setScale()

​play() / stop()

​goToFrame()

​setFrameDuration()

​Example: 3D Scene

Build docs developers (and LLMs) love

Overview

ThreeRenderable

Constructor

Properties

Methods

getScene()

setScene()

getActiveCamera()

setActiveCamera()

setAutoAspect()

ThreeCliRenderer

Constructor

Methods

init()

drawScene()

setSize()

setBackgroundColor()

saveToFile()

toggleSuperSampling()

destroy()

TextureUtils

TextureUtils.loadTextureFromFile()

TextureUtils.fromFile()

TextureUtils.createCheckerboard()

TextureUtils.createGradient()

TextureUtils.createNoise()

SpriteUtils

SpriteUtils.fromFile()

SpriteUtils.sheetFromFile()

SpriteAnimator

Constructor

createSprite()

update()

removeSprite()

removeAllSprites()

TiledSprite

Properties

Methods

setAnimation()

setPosition()

setRotation()

setScale()

play() / stop()

goToFrame()

setFrameDuration()

Example: 3D Scene