Status: pre-1.0. APIs may still change before a stable 1.0 release.

@glyphcss/react

React components for glyphcss — an ASCII polygon mesh renderer that projects 3D scenes into a single <pre> element. Loads OBJ, glTF, GLB, and MagicaVoxel .vox files; renders the result as monospace text in the browser.

Install

npm install @glyphcss/react

Requires React 18 or 19 as a peer dependency.

Quickstart

import {
  GlyphCamera,
  GlyphScene,
  GlyphMesh,
  GlyphOrbitControls,
} from "@glyphcss/react";

export function App() {
  return (
    <GlyphCamera rotX={0.4} zoom={0.32}>
      <GlyphScene cols={80} rows={40}>
        <GlyphOrbitControls />
        <GlyphMesh src="/cottage.glb" />
      </GlyphScene>
    </GlyphCamera>
  );
}

Component reference

<GlyphCamera> / <GlyphOrthographicCamera>

Orthographic camera. GlyphCamera is the ergonomic default alias. Wraps <GlyphScene> — the camera is always the outermost element.

| Prop | Type | Default | Description | |---|---|---|---| | rotX | number | 0 | Tilt in radians | | rotY | number | 0 | Azimuth in radians | | zoom | number | 0.4 | Mesh fraction of min(cols, rows) |

<GlyphPerspectiveCamera>

Perspective (foreshortened) camera. Required for <GlyphFirstPersonControls>.

| Prop | Type | Default | Description | |---|---|---|---| | rotX | number | 0 | Tilt in radians | | rotY | number | 0 | Azimuth in radians | | distance | number | 3 | Perspective distance in world units | | zoom | number | 0.4 | Mesh fraction of min(cols, rows) |

<GlyphScene>

Root of every React glyphcss render tree. Owns the <pre> output element and rasterizes all meshes on camera or state change. Must be a child of a camera component.

| Prop | Type | Default | Description | |---|---|---|---| | cols | number | 80 | Grid width in character cells | | rows | number | 40 | Grid height in character cells | | mode | "wireframe" \| "solid" \| "voxel" | "solid" | Render mode | | className | string | — | CSS class on the <pre> container |

<GlyphMesh>

Loads and displays a 3D mesh. Supports .obj, .glb, .gltf, .vox.

| Prop | Type | Description | |---|---|---| | src | string | URL of the mesh file | | color | string | Override mesh color |

<GlyphOrbitControls> / <GlyphMapControls>

Mouse/touch/keyboard camera controls.

Hooks

• useGlyphCamera() — access the camera context
• useGlyphSceneContext() — access scene state
• useGlyphMesh(handle) — mesh state and imperative API
• useGlyphAnimation(clips, controller) — three.js-style animation mixer

License

MIT