# ascee

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

Latest version **3.0.1** (published 2026-05-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install ascee
pnpm add ascee
yarn add ascee
bun add ascee
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2026-05-08 |
| First published | 2023-09-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 0 |
| Unpacked size | 34.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Daniel Preil |
| Maintainers | danielpreil |
| Keywords | ascii, 3d, threejs, gltf, renderer |

## Links

- npm: https://www.npmjs.com/package/ascee
- Repository: https://github.com/DanielPreil/ascee
- Homepage: https://github.com/DanielPreil/ascee#readme
- Issues: https://github.com/DanielPreil/ascee/issues
- npm.io page: https://npm.io/package/ascee

## Recent versions

- 3.0.1 (latest) — 2026-05-08
- 2.0.0 — 2023-09-03

## README

# 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](./README.hu.md)

## 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

```bash
npm install ascee three
# or
pnpm add ascee three
```

## Quick Start

```ts
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:

```ts
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:
```bash
cd package
npm install
```

2. Build and validate package:
```bash
npm run release:check
```

3. Start a static server from repository root:
```bash
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

---
_Source: https://npm.io/package/ascee · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
