Three.js and web engines

If it runs in a browser, it runs here, provided every URL in it is relative. This page covers games that are already HTML and JavaScript: Vite and Three.js, other bundlers, and plain canvas games.

A build is served from https://<slug>.containment.cloud/<buildId>/. A root-absolute URL such as /assets/game.js points at the root of that origin, not at your build, and returns a 404. assets/game.js and ./assets/game.js work.

Vite #

Set base to "./". Vite's default is "/", which writes root-absolute URLs into index.html.

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  // Relative asset URLs. A build is served from /<buildId>/, not from the site root.
  base: "./",
  build: { outDir: "dist", emptyOutDir: true, target: "es2022" },
});

Containment Breach, a Three.js game on Fradiation, builds with this base. Then:

1. Put fradiation.json in public/. Vite copies public/ to the top of dist/, which is where the uploader reads it. See fradiation.json.

2. Build.

3. Open dist/index.html. Script and link URLs should start with ./, not /:

   htmlCopy

   <script type="module" crossorigin src="./assets/index-DgJRjt5S.js"></script>

4. Check and zip. Download check-build.mjs (Node 20 or later):

   bashCopy

   bun run build            # or: npm run build
   node check-build.mjs pack dist game.zip

Upload game.zip, or pick the dist folder, on /dev/<slug>. See Publish a game.

Loading assets in Three.js #

Three.js loaders resolve a relative URL against the page. Put static files in public/ and refer to them with ./:

import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

// public/models/ship.glb becomes dist/models/ship.glb
new GLTFLoader().load("./models/ship.glb", (gltf) => scene.add(gltf.scene));

"/models/ship.glb" breaks. To let Vite fingerprint a file instead, import its URL:

import shipUrl from "./ship.glb?url";

Files that a loader fetches at run time need to be inside the build too:

• Draco. Copy draco_decoder.js, draco_decoder.wasm and draco_wasm_wrapper.js from three/examples/jsm/libs/draco/ into public/draco/, and call dracoLoader.setDecoderPath("./draco/"). Leave the README.md in that folder behind. It isn't an allowed type.
• KTX2. .ktx2 textures are allowed. Copy basis_transcoder.js and basis_transcoder.wasm from three/examples/jsm/libs/basis/ into public/basis/, and call ktx2Loader.setTranscoderPath("./basis/").
• Fonts. woff and woff2 are allowed. Self-host them instead of loading them from another site, especially if you use threads.
• Formats off the list. .hdr, .exr, .fbx, .obj, .mtl and .drc aren't allowed. Convert models to .glb. Loaders that read raw bytes without checking the extension, such as three's RGBELoader and DRACOLoader, work with the file renamed to .bin.

The full list is in Builds and uploads.

Other bundlers #

The rule is the same everywhere: asset URLs are relative.

After a build, open the output index.html and search it for src="/ and href="/. Then check every URL your code builds at run time. A local server that serves the output folder at its root hides this mistake. A draft on the site shows it: a draft always runs its newest build.

Plain HTML and canvas #

A game with no build step needs no tooling. Keep everything in one folder with relative references, and zip the folder.

my-game/
  index.html
  game.js
  fradiation.json
  fradiation-sdk.js
  sprites/
    ship.png
  sounds/
    shot.ogg

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My Game</title>
    <style>
      html, body { margin: 0; height: 100%; background: #000; overflow: hidden; }
      canvas { display: block; width: 100%; height: 100%; }
    </style>
    <script src="fradiation-sdk.js"></script>
  </head>
  <body>
    <canvas id="game"></canvas>
    <script src="game.js"></script>
  </body>
</html>

Zip the my-game folder. The uploader drops a single top-level folder, so index.html ends up at the top. Or run node check-build.mjs pack my-game.

Load the SDK #

The SDK is not on npm. Download a file and ship it inside your build. See SDK for the API.

ES module. Save fradiation-sdk.mjs in your source folder and import it by path:

import { fradiation } from "./fradiation-sdk.mjs";

const { connected, mode } = await fradiation.ready();

await fradiation.unlockMutation("first-blood");
await fradiation.submitScore("high-score", 12345);
fradiation.track("reached-level", { level: 3 });

For TypeScript, save fradiation-sdk.d.mts next to the module. TypeScript picks it up for the .mjs import.

Script tag. Save fradiation-sdk.js next to index.html, load it before your game's scripts, and use window.fradiation:

<script src="fradiation-sdk.js"></script>

Declare mutations and boards in fradiation.json first. Outside the site, every call resolves with defaults, so the same code runs in local dev.

Fill the frame #

The game runs in an iframe. The cabinet letterboxes it to the viewport aspect ratio in fradiation.json, and the frame changes size when the player resizes the window or goes fullscreen. Fill the window and handle resize. Don't hard-code a canvas size.

<style>
  html, body { margin: 0; height: 100%; overflow: hidden; }
  canvas { display: block; position: fixed; inset: 0; width: 100%; height: 100%; }
</style>

function resize() {
  const w = innerWidth;
  const h = innerHeight;
  renderer.setSize(w, h);
  camera.aspect = w / h;
  camera.updateProjectionMatrix();
}
addEventListener("resize", resize);
resize();

If you use a post-processing composer, call composer.setSize(w, h) in the same function.

Audio, pointer lock and fullscreen #

The frame is sandboxed. It allows pointer lock, popups, modal dialogs and orientation lock, and it delegates fullscreen, gamepad, autoplay, accelerometer, gyroscope and xr-spatial-tracking.

• Audio. Browsers can still block sound until the player interacts, even with autoplay delegated. Create or resume your AudioContext inside the first click or key handler.

  tsCopy

  addEventListener("pointerdown", () => audioContext.resume(), { once: true });

• Pointer lock. Request it from a click handler: canvas.requestPointerLock().

• Fullscreen. Request it from a click or key handler: canvas.requestFullscreen().

• Navigation and forms. The game can't navigate the site or submit forms. Scripts, fetch to external APIs and popups work.

Storage #

Each game has its own origin, <slug>.containment.cloud. Its localStorage, IndexedDB and caches belong to that origin and persist across builds. Other games can't read them. Browsers can block storage in an embedded frame, so wrap it and keep the game playable without it:

try {
  localStorage.setItem("best", String(best));
} catch {
  // storage may be blocked
}

Other engines #

Every engine follows the same two rules: relative paths, and file types on the allowed list. This table covers what to watch for. See Unity and Godot for their own guides.

Troubleshooting #