SpaTeX

A CSS/JSON-style declarative language for 3D diagrams, designed for AI chat interfaces.

SpaTeX lets you describe interactive 3D scenes using a simple, human-readable syntax — similar to how Mermaid works for flowcharts, but for Three.js 3D scenes.

Installation

npm install spatex three

Quick Start

ES Module

import Spatex from 'spatex';
import * as THREE from 'three';

// Make THREE available globally (required by the renderer)
window.THREE = THREE;

const code = `
scene {
  background: #1a1a2e;
  camera { angle: 45 30; zoom: 1.5 }

  sphere {
    pos: 0 0 0;
    radius: 1;
    color: steelblue;
    label: "Sphere";
  }

  cube {
    pos: 3 0 0;
    size: 1.5;
    color: coral;
    label: "Cube";
  }

  arrow {
    from: 0 0 0;
    to: 3 0 0;
    color: white;
  }
}
`;

// Option 1: Render directly into a container
Spatex.render(code, document.getElementById('my-container'));

// Option 2: Parse first, then render manually
const sceneTree = Spatex.parse(code);
console.log(sceneTree);

UMD (Script Tag)

<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
<script src="path/to/spatex.umd.js"></script>
<script>
  const SpaTeX = Spatex.default;
  SpaTeX.render(code, container);
</script>

Auto-Render (Markdown Code Blocks)

If your page contains fenced code blocks with the language spatex:

<pre><code class="language-spatex">
scene {
  background: #1a1a2e;
  sphere { pos: 0 0 0; radius: 1; color: steelblue; }
}
</code></pre>

<script>
  Spatex.default.autoRender();
</script>

API

Spatex.parse(code)

Parse a spatex string and return a JSON scene tree.

• code {string} — Raw spatex source code
• Returns {Object} — Parsed scene tree

Spatex.render(code, container)

Render a spatex string into a given DOM container element.

• code {string} — Raw spatex source code
• container {HTMLElement} — DOM element to render into
• Returns {{ scene, camera, renderer }} — Three.js handles

Spatex.autoRender()

Auto-scan the page for <code class="language-spatex"> and <code class="language-3d"> blocks and render them all in-place.

Syntax Reference

Scene

scene {
  background: #1a1a2e;
  fog: false;

  camera {
    angle: 45 30;
    zoom: 1.5;
    target: 0 0 0;
  }

  // Objects go here...
}

3D Shapes

| Shape | Properties | |-------------------|----------------------------------------------| | cube | size | | cuboid | width, height, depth | | sphere | radius | | hemisphere | radius | | cylinder | radius, height | | cone | radius, height | | hollow_cylinder | radius, inner_radius, height | | hollow_cone | radius, inner_radius, height |

2D Shapes

| Shape | Properties | |--------------|----------------------| | square | size | | rectangle | width, height | | circle | radius | | semicircle | radius | | triangle | size | | plane | width, height |

Universal Properties

All shapes support:

• pos: x y z — Position in 3D space
• rotate: rx ry rz — Rotation in degrees
• color: #hex | name — Color
• opacity: 0-1 — Transparency
• wireframe: true/false — Wireframe mode
• shadow: true/false — Cast and receive shadows
• label: "text" — Floating label above the shape

Connectors

arrow {
  from: objectName;    // or: from: x y z;
  to: otherObject;     // or: to: x y z;
  color: white;
  label: "connects";
}

line {
  from: 0 0 0;
  to: 3 0 0;
  color: yellow;
}

Groups

group myGroup {
  pos: 0 3 0;

  cube a { pos: -1 0 0; size: 0.5; color: cyan; }
  cube b { pos:  1 0 0; size: 0.5; color: purple; }

  arrow { from: a; to: b; color: white; }
}

Development

# Install dependencies
npm install

# Run demo with hot reload
npm run dev

# Build the library
npm run build

# Preview the built demo
npm run preview

License

MIT