Setting Up 3D Elements (GLB Models)

How to take a .glb file from Blender (or your 3D designer) and get it on the site — optimized, correctly sized, positioned, animated and themed — without writing new Three.js/R3F code each time.

How it fits together#

models-src/*.glb                      ← raw exports from Blender (keep these)
        │  bun run models:optimize
        ▼
public/models/*.glb                   ← web-ready files the site serves
src/packages/configs/model3d.config.ts   ← one entry per model: size, position, animation, effects
src/packages/configs/models.manifest.ts  ← auto-generated list of files that exist (models:sync)
src/components/features/models/
  ClientModelViewer.tsx   ← USE THIS in pages (lazy, SSR-safe, pauses off-screen)
  ModelViewer.tsx         ← Canvas + lights + model + effects
  GlbModel.tsx            ← loads, auto-fits and animates one GLB
  PlaceholderModel.tsx    ← stand-in shown until the GLB exists
  effects/                ← underglow, orbit rings, floating tiles, sparkles, parallax

The normal workflow is: drop the raw file → bun run models:optimize → tune in the Model lab → paste the values into model3d.config.ts → place <ClientModelViewer modelKey="…" />.

Every slot already exists in model3d.config.ts with a procedural placeholder, so you can build the page and the effects before a model is exported. The moment public/models/<file> exists, the real model replaces the placeholder — no code change.

1. Getting the file from your designer#

• Format: .glb (single file, textures embedded), not .gltf + folder.
• Origin at the centre of the model's base, facing +Z, Y up. Apply scale and rotation in Blender before export.
• No backdrop planes or lights baked in — the page provides those. (If one slips through, list its material in optimize.drop.)
• Give emissive parts real emissive materials (screens, neon) — they pick up the theme's glow.
• If there is a baked animation, note the exact clip name for clip.
• Drop the file in models-src/ using the file name from the config (e.g. models-src/avatar.glb).

2. Optimize#

bun run models:optimize                # every model that has a raw file
bun run models:optimize hero-workstation   # one model, by key or file name

Reads models-src/, writes public/models/. It drops unwanted materials, merges meshes that share a material (fewer draw calls), welds vertices, optionally simplifies, quantizes and prunes. Example (the hero desk):

Per-model options live in the config:

optimize: { simplify: 0.4, drop: ["Backdrop_Gradient"], maxTexture: 1024 },

bun run models:sync (runs automatically before dev/build) prints which slots are still placeholders and warns when a file is over budget (1.5 MB, hero 2.5 MB).

Draco/Meshopt compression is deliberately not used: it needs a WASM decoder at runtime, which the site's CSP does not allow.

3. Register and tune it#

// src/packages/configs/model3d.config.ts
{
  key: "showcase-database",          // ← you reference the model by this key
  file: "database.glb",              // ← name inside public/models
  placeholder: "database",           // ← shown until the file exists
  size: 1.7,                         // ← largest axis, in scene units
  position: [0, 0, 0],               // ← nudge after auto-centering
  rotation: [0, 0, 0],               // ← radians
  animation: "float-spin",
  clip: undefined,                   // ← baked clip name, if any
  camera: { position: [0, 1.2, 6], fov: 40 },
  effects: [{ type: "underglow" }, { type: "orbit-rings", count: 2 }],
}

Tune it live: run bun dev, open /dev → Model lab. Pick a slot, drag the sliders for size / position / rotation / camera / effects, watch the FPS counter, then press Copy values and paste them into the entry. The lab only exists in development; it is not in the production build.

4. Sizing#

You don't need to know the scale your designer exported at. On load the model is measured and uniformly scaled so its largest axis equals size, then centred. Change size to make a model bigger or smaller — never ask for a re-export.

5. Animation presets#

A baked clip (clip: "Idle") plays independently of the preset. All motion switches off when the visitor has reduce motion enabled. Wrong clip name? In development the console lists the available names.

6. Effects#

Listed per model in effects. Every colour comes from the active theme (--primary, --accent-foreground, …) and updates when the theme changes — never hard-code a colour in a 3D component.

To add an effect: create a component in models/effects/, add its type to ModelEffect in the config, and map it in effects/index.tsx.

7. Placing it on a page#

Always use ClientModelViewer (the Canvas can't be server-rendered).

import { ClientModelViewer } from "@/components/features/models/ClientModelViewer";

const ShowcaseCard = () => (
  <div className="aspect-square rounded-3xl border border-border">
    <ClientModelViewer modelKey="showcase-database" />
  </div>
);

8. Performance and security notes#

• Three.js loads in its own chunk, only when a viewer is within 300 px of the viewport, and rendering pauses while it is off-screen.
• Pixel ratio is capped and drops automatically if the frame rate falls.
• No WebGL (or a failed GLB) shows a CSS glow / the placeholder — never a broken page.
• Keep the 4-up showcase light: size ≈ 1.7, no interactive, ~1 effect pair each.
• The strict CSP blocks third-party fetches, so don't use drei's <Environment preset="…"> (it downloads an HDR). Lights use a built-in procedural environment.

Troubleshooting#