Getting Started

Installation

Install the library using your preferred package manager:

npm install uzay

HTML Setup

Uzay renders to a container element. Create an HTML file with a container div:

<!DOCTYPE html>
<html>
  <head>
    <title>Uzay Demo</title>
    <style>
      #container {
        width: 100vw;
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <div id="container"></div>
    <script type="module" src="./main.ts"></script>
  </body>
</html>

Your First Scene

Create a main.ts file with a scene, a camera, and a point:

import { Scene3D, View3D, vec3 } from "uzay";

const scene = new Scene3D();

const camera = scene.create("camera3d", {
  position: vec3(5, 5, 5),
  lookAt: vec3(0, 0, 0),
});

scene.create("axes3d", {
  x: [-5, 5],
  y: [-5, 5],
  z: [-5, 5],
});

const point = scene.create("point3d", {
  coords: vec3(2, 1, 0),
  color: "crimson",
  radius: 3,
});

const container = document.getElementById("container") as HTMLElement;
const view = new View3D(scene, camera.id, container);

You can orbit the camera by dragging the background, and the point is already draggable. Try it.

Adding a Line

Connect the origin to the point. Pass point.coords directly as the line's endpoint, so the line tracks the point reactively:

scene.create("line3d", {
  start: vec3(0, 0, 0),
  end: point.coords, 
  color: "crimson",
});

Drag the point and the line follows.

Adding a Label

Use an overlay to display the point's coordinates. The content is a derived atom that reads point.coords and formats it as text:

import { vec2 } from "uzay";

scene.create("overlay3d", {
  position: point.coords, 
  content: scene.atom((get) => { 
    const { x, y, z } = get(point.coords); 
    return `(${x.toFixed(1)}, ${y.toFixed(1)}, ${z.toFixed(1)})`; 
  }), 
  anchor: "bottom-left",
  offset: vec2(8, -8),
});

The label follows the point and updates its text as you drag. This is reactivity in Uzay: change an atom, and everything that depends on it updates automatically.

Next Steps

Core Concepts: Scenes, Views, and Atoms in depth
Items: All available 3D items
Interactions: Drag, click, and hover events