ascee

Three.js model-to-ASCII renderer for web apps.

ascee helps you load a GLTF/GLB scene, render it with Three.js, and display an ASCII output in real time.

Magyar dokumentáció / Hungarian docs

Features

• TypeScript-first API with generated .d.ts types
• ESM package with explicit exports
• Frame-throttled ASCII rendering (asciiFps) for better performance
• Optional GLTF optimization hooks (DRACO, KTX2, Meshopt)
• Explicit cleanup helpers to prevent WebGL memory leaks

Installation

npm install ascee three
# or
pnpm add ascee three

Quick Start

import {
  asceeCreateCanvas,
  asceeCreateLight,
  asceeCreateModel,
  asceeCreateRender,
  asceeDisposeObject3D,
  asceeDisposeScene,
} from "ascee";

const canvas = document.querySelector<HTMLCanvasElement>(".myCanvas");
const ascii = document.querySelector<HTMLPreElement>(".myAscii");

if (!canvas || !ascii) {
  throw new Error("Missing .myCanvas or .myAscii element");
}

const { renderer, scene, camera, dispose: disposeCanvas } = asceeCreateCanvas(canvas, {
  transparent: true,
  cameraZ: 2.5,
  maxDevicePixelRatio: 2,
});

asceeCreateLight(scene, { strength: 3, position: { x: 0, y: 1, z: 1 } });

const model = await asceeCreateModel(scene, "/models/room.glb", { y: -0.5 });

const render = asceeCreateRender(scene, renderer, camera, model, {
  controls: true,
  modelRotateY: true,
  modelRotationY: 0.01,
  ascii: {
    target: ascii,
    width: 140,
    height: 50,
    chars: " .,:;irsXA253hMHGS#9B&@",
  },
  asciiFps: 20,
});

// Cleanup example:
// render.dispose();
// asceeDisposeObject3D(model);
// asceeDisposeScene(scene);
// disposeCanvas();

GLTF Compression Options (Optional)

If your assets use DRACO/KTX2/Meshopt:

import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath("/draco/");

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath("/basis/");

const model = await asceeCreateModel(scene, "/models/asset.glb", {
  dracoLoader,
  ktx2Loader,
  rendererForKTX2: renderer,
  meshoptDecoder: (window as any).MeshoptDecoder,
});

API

asceeCreateCanvas(canvas, options?)

Returns { renderer, scene, camera, resize, dispose }.

Important options:

• autoResize?: boolean
• maxDevicePixelRatio?: number

asceeCreateModel(scene, modelUrl, options?)

Loads GLTF/GLB and returns Promise<THREE.Group>.

Important options:

• x, y, z
• dracoLoader, ktx2Loader, meshoptDecoder
• rendererForKTX2

asceeCreateLight(scene, options?)

Creates and adds a THREE.DirectionalLight.

asceeCreateRender(scene, renderer, camera, model, options?)

Starts the render loop and returns { start, stop, dispose, isRunning }.

Important options:

• controls, controlsDampingEnabled
• modelRotateX, modelRotateY
• modelRotationX, modelRotationY
• ascii, asciiFps

asceeDisposeObject3D(object, options?)

Disposes geometry/material/texture resources for an object tree.

asceeDisposeScene(scene, options?)

Disposes all scene children resources and clears scene.background/environment textures.

Local Testing (this repository)

1. Install package dependencies:

cd package
npm install

2. Build and validate package:

npm run release:check

3. Start a static server from repository root:

cd ..
python3 -m http.server 4173

4. Open demo page:

• http://localhost:4173/tests/

The demo imports ../package/dist/index.js, so npm run build (or release:check) must be run first.

Package Quality Notes

• three is a peer dependency
• publish payload is controlled via files
• CI validates typecheck + build + npm pack --dry-run
• publish workflow is prepared for trusted publishing/provenance

License

MIT