mi4t/brain
OKF v0.2
projectstableby: omp

Three.js Knowledge Castle

A WebGL castle on /castle where each room is a knowledge area and each exhibit is a concept note, built as an Astro island over the OKF bundle.

#threejs#webgl#astro#react#visualization#second-brain

Three.js Knowledge Castle

A walkable 3D castle served at /castle, rendered with three.js from the existing OKF bundle. One room per area; one exhibit plinth per concept note; the courtyard holds the bundle map, walled by a bailey with a single gate on the south face. The bundle stays the single source of truth — the castle is a second view of the same content, generated at build time, never authored separately 1 2.

Goals

  • Replace the flat catalog with spatial recall: a learner locates “where osmosis lives” before reading it.
  • Derive every room, wall, and label from getBrainKnowledge(); zero duplicated content.
  • Stay usable on a mid-range laptop and on a phone, with a non-WebGL fallback.

Non-Goals

  • Editing, search, or study logic inside the castle — those stay on their existing pages.
  • Text rendering of full note bodies; exhibits show title, status, and a link.

Data Contract

src/lib/castle.ts is pure — no three.js import — so every number is unit-tested with vitest in src/lib/__tests__/castle.test.ts:

export function parseConceptClaims(areaBody: string): string[];
export function buildCastle(areas: CastleArea[], concepts: CastleConcept[]): CastleData;

CastleData carries rooms (each with exhibits, world center, size, worldSize, doorway, walls, and a stable per-area color), archive, courtyardRadius, well, bounds, and totals. Exhibit positions are world-space, so the renderer and the first-person collider read the same numbers.

Room membership comes from the Foundational Concepts list of each area note, matched against the content layer’s extensionless ids (concepts/osmosis). Today: 35 Biology, 20 Chemistry, 11 Mathematics, 0 Systems Architecture (it has no such list), leaving 2 concepts for the courtyard archive — 68 concepts placed, none lost 1.

Scene Composition

  • One client:only="react" island pair — src/components/castle/CastleScene.tsx (React shell, HTML overlay) and src/components/castle/castle-world.ts (scene, camera modes, picking, disposal) — because WebGL has no SSR. three@0.186 with @types/three are the only new runtime dependencies; no @react-three/fiber, so React never touches the frame loop 3.
  • Plan: a courtyard at the origin, one wing per area on the four sides at quarter-turn yaws, and a slot per extra area so a fifth area never overlaps. A wing grows with its exhibit count (4 pedestals per row) and spills onto an upper gallery past 40.
  • The bailey is a square ring sized from the outermost wing plus curtainGap, with a tower on each corner, a taller pair flanking the gate, and one gate opening. The gate does not sit on the castle axis: it takes the aisle nearest that axis that clears every wing by gateAisle, because pointing it at a wing parks the player in front of a blank back wall. The walk mode spawns 9 m out on the road, facing the castle.
  • Each wing is three draw calls: floor, one merged wall mesh, one InstancedMesh of pedestals tinted by status through instance color. The whole bailey — curtain, corner towers, gate towers, road — is three more. Shadows and antialiasing are dropped under 640px.

Interaction

InputResult
Drag / wheelOrbit the keep (overview mode)
Click exhibitHTML panel: title, description, status, “Open note” link
1–4Fly the camera to room n
FFly down to the gate and enter first-person walk (WASD walks, ←/→ or the mouse steer)
EscLeave walk, fly back to the orbit overview
Search boxDim rooms with no match, never unmount them

The ten nearest pedestals of the focused room carry HTML labels projected each frame. The full exhibit list renders below the canvas and doubles as the no-WebGL fallback.

Walk input is frame-rate independent: velocity eases toward the pressed keys (0.16s to full speed, 0.08s to bleed off) and look angles ease over 0.05s. The drive vector is clamped, not normalized, so releasing a key brings the player to a full stop in about 0.3s instead of coasting. Movement and steering run in the same frame, so W plus a turn walks a curve rather than one axis or the other. Steering has two hands: ←/→ turn at 1.7 rad/s — about 100°/s, which arcs the walk at a 5 m radius instead of spinning on the spot — and the mouse sweeps, and both write the same look goal. The mouse handler reads that goal back instead of a private copy, so turning on the keys and then nudging the mouse continues from where the keys left off rather than snapping the view back. A/D keep the strafe, and the walk keys call preventDefault so the arrows do not scroll the page out from under the canvas.

Looking has two paths, because a lock-only design goes dead in a real browser. The pointer lock is requested inside the click or keypress that starts the walk, not on arrival: browsers only grant it from a live user gesture, and a 1.1–3s flight can outlast the activation, so a lock asked for at the landing is refused and the mouse does nothing while the keys still work. The arrival request stays as a retry, and clicking the canvas re-asks. When no lock is held — refused, released by Esc, or blocked by frame policy — holding the mouse button on the castle steers instead, tracked as a client-coordinate delta so a drag never jumps on the first move, and the HUD says so. Entering walk arcs the camera over the bailey on a quadratic bezier (duration scales with distance, 1.1–3s) and leaving walk flies back to the overview the same way; movement is held until the flight lands, since the camera is on rails. Collision is the curtain and wing walls plus isWalkableGround(), which fences the player to the bailey interior and the gate road.

Budgets and Lifecycle

Measured in Chromium on the 68-concept bundle: 32 draw calls per frame (budget 60) and about 2.9k triangles per frame counted through the WebGL calls. The loop stops on document.hidden (verified: zero draw calls while hidden) and on unmount, where geometries, materials, and the WebGLRenderer are disposed. prefers-reduced-motion replaces camera flights with a snap, gate entry included.

Milestones

All five shipped, each closing with pnpm run check (Astro check 0 errors, validator clean), pnpm test (70 tests), and browser evidence:

  1. M1 Data — castle.ts plus 14 vitest cases: claims parsing, multi-area concept, tag fallback, archive, gallery spill, doorway orientation, and a real-bundle test that every concept is placed.
  2. M2 Static scene — grey-box castle, orbit camera, /castle page, header nav link.
  3. M3 Content binding — instanced pedestals, area colors, status tint, projected labels.
  4. M4 Interaction — raycast panel, room hotkeys, first-person walk with wall collision, search dimming, fallback list.
  5. M5 Polish — lighting, shadows, reduced-motion, dispose audit, draw-call budget.

Risks

  • Bundle growth: pedestals stay flat in cost, but wings do not — a fifth wing takes the next slot, a ninth starts a second ring.
  • Label legibility: capped at the ten nearest pedestals of the focused room.
  • Mobile GPU cost: orbit-only and no shadows under 640px.

Footnotes

  1. three.js Documentation - Scene graph, WebGLRenderer, InstancedMesh, raycasting, and dispose semantics. ↩ ↩2

  2. Astro Islands Architecture - Framework components ship zero JavaScript until a client:* directive hydrates them. ↩

  3. three.js Manual - Installation - ES module install, bundler usage, and the @types/three type package. ↩