Skip to content

3D engine that AI agents drive

3.8 KB
Raw Blame

Install

This page makes a new web project and adds Crucible to it. At the end, you have a project that the first-scene tutorial builds on.

Before you start

You need these two things:

  • Node.js 20.19 or later. Run node --version to see your version. Get Node.js from nodejs.org.
  • A browser with WebGL2. Current Chrome, Edge, Firefox and Safari have it.

1. Make a project

Make a new project with Vite. Vite is a development server that loads npm packages in the browser.

npm create vite@latest my-scene -- --template vanilla

Go into the folder and install its packages:

cd my-scene
npm install

The my-scene folder now has index.html, package.json and a src folder.

2. Add Crucible

Install the package with the name crucible:

npm install crucible@npm:@codepawlhq/crucible

The package on npm is @codepawlhq/crucible. The crucible@npm: part gives it the shorter name crucible, so your code writes import { CrucibleRenderer } from 'crucible'. If you install it without that part, import from @codepawlhq/crucible instead.

3. Check the install

Run this command in the project folder:

npm ls Crucible

It prints the installed version:

[email protected]
`-- crucible@npm:@codepawlhq/[email protected]

Your version can be newer. The changelog lists what each version adds.

Use Crucible without npm

A plain HTML page can import Crucible from this site. Take the module path from the release metadata and put it after https://crucible.codepawl.com. Replace <version> below with the version in that file. The site keeps only the current release, so read the file again after a release and update the URL.

<script type="importmap">
  { "imports": { "crucible": "https://crucible.codepawl.com/releases/<version>/67.module.js" } }
</script>
<script type="module">
  import { CrucibleRenderer, box } from 'crucible';
</script>

Serve the page over HTTP, for example with npx serve. A page opened from a file:// path cannot import modules. This file has the core only. Addons such as crucible/addons/gltf need the npm package.

Use Crucible from jsdelivr

From version 0.20.0 the npm package holds one self-contained module, build/67.standalone.js. It has no relative imports, so jsdelivr (and unpkg) serve it from one URL. Pin the version in the URL. This works in a plain HTML file and in a claude.ai artifact, which loads scripts only from cdnjs, jsdelivr and unpkg.

<canvas id="view" width="640" height="400"></canvas>
<script type="module">
  import { CrucibleRenderer, box } from 'https://cdn.jsdelivr.net/npm/@codepawlhq/[email protected]/build/67.standalone.js';

  const parts = [{
    name: 'Cube',
    geometry: box(),
    matrix: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
    material: { color: [0.8, 0.3, 0.2], metallic: 0, roughness: 0.4, emission: 0 },
  }];
  const renderer = new CrucibleRenderer(document.querySelector('#view'), parts, { samples: 4 });
  renderer.render({ eye: [2.5, 2, 3.5], target: [0, 0, 0] });
</script>

The file has the core only. Addons such as crucible/addons/gltf need the npm package. Versions before 0.20.0 have no standalone file; their build/67.module.js also loads from jsdelivr, but it imports 16 chunk files.

Good to know

Note: Crucible is plain JavaScript and has no TypeScript types. In a strict TypeScript project, add the line declare module 'crucible'; to a .d.ts file. The imports then have the type any.

Tip: Addons are separate imports, such as crucible/addons/gltf for GLB models. You only download the addons that you import.

Next: your first scene | #first-scene | Draw, color, place and animate shapes step by step.