Brick Builder

A web-based 3D editor for procedurally-generated LEGO-style creations. Every brick is built from parametric geometry (no imported meshes), rendered with realistic plastic shading, shareable via a URL, and live-editable with friends through Supabase Realtime.

Live demo: https://d-dezeeuw.github.io/brick-builder/

• Procedural catalog. ~40 shapes generated at runtime from a discriminated-union spec — bricks, plates, tiles, round pieces, 45° slopes, cheese slopes, jumpers. Authentic bottom detail (hollow anti-stud tubes for ×ばつ2, centreline pins for 1-wide strips). Add a shape by appending one row to packages/shared/src/catalog.ts.
• Instanced rendering. One InstancedMesh per (shape, color, transparent) bucket, matrices packed into a single attribute. 10k bricks typically render in ~50 draw calls.
• Plastic shader. MeshPhysicalMaterial with clearcoat, sheen, and an Oren-Nayar diffuse patch injected via onBeforeCompile at medium+. Studio HDRI with rotation / visible-background / blur / brightness controls. Tone-mapping picker (ACES Filmic / AgX / Khronos Neutral / Linear). 4 quality presets and independent toggles for AO (N8AO), Bloom, SMAA, and post-process Depth of Field (Ultra only).
• GPU path-traced render mode. Top-bar render toggle swaps the rasterizer for @react-three/gpu-pathtracer. Includes shaped-area key light, contact-shadow emissive floor, denoise (À-Trous EAW / Bilateral / NLM), Physical-Camera depth of field with focus tracking the orbit target, ACES/AgX tone-mapping passthrough, configurable bounces (1–8) and resolution (50/75/100%). Camera moves below threshold no longer reset accumulation. Convergence-based early-stop monitors a centre-window RMS delta and freezes the tracer once samples stop changing the picture; pose-keyed LRU cache of converged outputs makes re-entering render mode at a previously-converged pose instant. Frustum culling + chunked geometry merging + studless LOD for distant chunks let it scale to 10k+ bricks.
• Persistence. Versioned schema with runtime validation. Autosave to localStorage, sharable lz-string URL hash, JSON + PNG export (render-to-target, with native share sheet on mobile so screenshots land in Photos), JSON import via picker or drag-drop. Editor settings (lighting, tonemap, quality, PT knobs, baseplate colour, etc.) survive reload via a separate persistence layer.
• Multiplayer rooms. Supabase Postgres + Realtime. Start room or Join room by 8-char code or share link, password-gate optional, room popover collapses copy / change-password / leave behind a single chip. Live-sync brick placements, deletions, edits, title changes, and baseplate growth. No custom server.
• Mobile-first input. Tap-and-drag to position the ghost, release to commit; orbit-release is distinguished from a real tap by a 10px drag threshold. Build / Erase / Hand mode toggle. Top bar collapses non-primary actions behind a kebab below 768px; the render toggle stays one tap away. Long-press text-selection suppressed app-wide.

• Client: React 18 + Vite 6 + TypeScript (strict). React-three-fiber 8, drei, @react-three/postprocessing, @react-three/gpu-pathtracer. Zustand for state.
• Multiplayer: Supabase (Postgres + Realtime + RLS).
• Hosting: GitHub Pages (auto-deploys from main via the static.yml workflow). netlify.toml is still in the repo as a fallback config but is not the production target.
• Monorepo: pnpm workspaces. apps/web (the editor), apps/server (placeholder — unused now that Supabase replaced the planned Fastify + y-websocket stack), packages/shared (brick spec, catalog, schema).

# Requires Node 20+ and pnpm 9+
pnpm install
pnpm --filter @brick/web dev # http://localhost:5173

The web app needs a Supabase project for multiplayer. Copy apps/web/.env and point it at your project, then apply every SQL migration in supabase/migrations/ in order via the Supabase SQL editor. Without these, solo editing still works — only room features are disabled.

pnpm typecheck # all workspaces
pnpm build # production build
pnpm format # prettier write
pnpm lint # eslint (flat config)

• Lazy boundaries: the Supabase client, multiplayer subsystem, admin panel, settings modal, chat panel, exporters, post-processing chain, and path-tracer modules all load on demand. A solo first paint downloads ~330 KB gzipped of JS; multiplayer / admin / PT modes pay their own ~50–200 KB on first use.
• Path-tracer scaling: chunked geometry merging (16-stud chunks) collapses 10k bricks into ~10–200 merged meshes, BVH builds off-thread on a worker. Studless LOD swap above 800mm camera distance.
• WebGL probes dispose their throwaway context up front so the live R3F context isn't evicted on browsers with tight context caps (Safari / iOS).

blockeditor/
├── apps/
│ ├── web/ # Vite + R3F editor — the app
│ │ └── src/
│ │ ├── bricks/ # Geometry builders + material + instanced renderer
│ │ ├── scene/ # Three.js scene: baseplate, cursor, lighting, postfx, pathtracer
│ │ ├── state/ # zustand store, commands, persistence, captureBus
│ │ ├── multiplayer/ # Supabase client + room sync/writes/router (lazy)
│ │ └── ui/ # DOM UI: sidebar, top bar, help modal, hotbar, toasts
│ └── server/ # Placeholder Fastify app (unused in the Supabase architecture)
├── packages/
│ └── shared/ # Shape catalog, dimensions, schema, URL codec
├── supabase/migrations/ # SQL migrations — apply manually in the Supabase SQL editor
└── .github/workflows/ # CI (typecheck/build) + Pages deploy

• Presence cursors (Supabase Realtime Presence on the same channel).
• Auth-gated rooms beyond the room password — today anyone with the room id + password can edit.
• Brick-move sync — the editor doesn't have a move action yet.
• Wall-tolerance inset on brick geometry (decorative; not blocking any feature).
• SSGI — the realism-effects library hasn't cut a stable release in years; revisit when a maintained option lands.
• Screen-space reflections — limited fidelity for stud-density scenes; IBL covers the common case.
• Curved slopes (Tier 3 stretch from the catalog — dispatcher has the stub).

GitHub Actions (.github/workflows/static.yml) builds @brick/web with VITE_BASE_PATH=/brick-builder/ on every push to main and publishes to GitHub Pages. SPA fallback for the ?r=<id> room routes is handled by the hash-free URL convention. The Supabase connection is baked into the client via apps/web/.env — the anon key is safe to commit (RLS gates access).

Small, focused PRs welcome. When adding a feature:

• Favour editing existing files over creating new ones.
• New brick shapes: one row in packages/shared/src/catalog.ts; the dispatcher does the rest.
• New multiplayer mutations: extend both the applier in apps/web/src/multiplayer/roomSync.ts and the diff in apps/web/src/multiplayer/roomWrites.ts.
• Run pnpm typecheck && pnpm build before pushing; CI enforces both.

Apache License 2.0. See LICENSE. Copyright © 2026 Neko Media.

Brick dimensions sourced from Brick Owl, bartneck.de, Bricking Ohio, and GrabCAD. Top-30 shape ranking from Brick Architect. HDRI from pmndrs/assets (CC0).

LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize, or endorse this project.