npm.io
3.0.1 • Published 6 months ago

ascee

Licence
MIT
Version
3.0.1
Deps
0
Size
35 kB
Vulns
0
Weekly
0
Stars
2

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
  1. Build and validate package:
npm run release:check
  1. Start a static server from repository root:
cd ..
python3 -m http.server 4173
  1. 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

Keywords