Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(assembly): make Machine Atlas keyboard-drivable and stop it leaking hover materials
nirholas522ebc833106
diff --git a/pages/assembly.html b/pages/assembly.htmlindex ab306059b..b882dacc2 100644--- a/pages/assembly.html+++ b/pages/assembly.html@@ -17,14 +17,14 @@content="No model files. A radial aero engine and a steam locomotive built at runtime from dimensions, profiles and geometry functions, with solved linkages you can take apart."/><meta property="og:url" content="https://three.ws/assembly" />- <meta property="og:image" content="https://three.ws/api/page-og?s=labs&t=Machine+Atlas&d=Two+working+machines+generated+in+the+browser+from+code%3A+no+3D+model+files%2C+solved+linkages%2C+live+parameters%2C+GLB+export.&p=%2Fassembly" />+ <meta property="og:image" content="https://three.ws/api/page-og?s=labs&t=Machine+Atlas&d=A+radial+aero+engine+and+a+steam+locomotive+generated+in+the+browser+from+code%2C+with+no+3D+model+files%3A+solved+linkages%2C+live+dimensions%2C+explode+views+and+a&p=%2Fassembly" /><meta name="twitter:card" content="summary_large_image" /><meta name="twitter:title" content="Machine Atlas · three.ws" /><metaname="twitter:description"content="A radial engine and a steam locomotive, generated at runtime from dimensions and profiles. Move a slider and the geometry is rebuilt."/>- <meta name="twitter:image" content="https://three.ws/api/page-og?s=labs&t=Machine+Atlas&d=Two+working+machines+generated+in+the+browser+from+code%3A+no+3D+model+files%2C+solved+linkages%2C+live+parameters%2C+GLB+export.&p=%2Fassembly" />+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=labs&t=Machine+Atlas&d=A+radial+aero+engine+and+a+steam+locomotive+generated+in+the+browser+from+code%2C+with+no+3D+model+files%3A+solved+linkages%2C+live+dimensions%2C+explode+views+and+a&p=%2Fassembly" /><meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" /><meta property="og:site_name" content="three.ws" /><meta property="og:locale" content="en_US" />@@ -45,7 +45,7 @@<script src="/nav.js"></script><main class="ma-stage" id="maStage">- <div class="ma-canvas" id="maCanvas"></div>+ <div class="ma-canvas" id="maCanvas" tabindex="0" role="application" aria-label="Machine viewport. Drag or use the arrow keys to move the camera."></div><div class="ma-label" id="maLabel" hidden></div><div class="ma-loading" aria-hidden="true"><span></span><span></span><span></span>@@ -64,7 +64,7 @@</div><section class="ma-intro">- <p class="ma-kicker">Two machines. Two eras. Zero assets.</p>+ <p class="ma-kicker">Two machines. Nothing downloaded.</p><h1 id="maName">Radial Nine</h1><p class="ma-subtitle" id="maSubtitle">Air-cooled radial aero engine</p><p class="ma-blurb" id="maBlurb"></p>diff --git a/src/assembly.js b/src/assembly.jsindex 419abec28..ef43f3d02 100644--- a/src/assembly.js+++ b/src/assembly.js@@ -27,10 +27,9 @@ const $ = (id) => document.getElementById(id);const state = {machine: null,values: {},- built: null,angle: 0,speed: 0.55,- playing: true,+ playing: !matchMedia('(prefers-reduced-motion: reduce)').matches,explode: 0,explodeTarget: 0,structure: false,@@ -57,6 +56,8 @@ controls.dampingFactor = 0.07;controls.minDistance = 0.6;controls.maxDistance = 60;controls.maxPolarAngle = Math.PI * 0.495;+// Orbit and pan from the keyboard, so the stage is not pointer-only.+controls.listenToKeyEvents(host);const pmrem = new THREE.PMREMGenerator(renderer);scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;@@ -180,7 +181,8 @@ function build(machineId, values, { frame = 'keep' } = {}) {scene.add(built.root);current = built;state.machine = machine;- state.built = built;+ hovered = null;+ label.hidden = true;built.update(state.angle);applyExplode(built.root, state.explode);for (const g of state.hidden) setGroupVisible(built.root, g, false);@@ -448,6 +450,9 @@ function pick() {function setHovered(obj) {if (obj === hovered) return;if (hovered && hovered.userData.hoverMaterial) {+ // The highlight is a clone of the part's own material, so it has to be+ // freed on the way out; one leaked material per hover adds up fast.+ hovered.material.dispose();hovered.material = hovered.userData.hoverMaterial;hovered.userData.hoverMaterial = null;}@@ -672,7 +677,7 @@ renderHeader();renderParams();wire();build(start.machine.spec.id, start.values, { frame: 'first' });-setPlaying(true);+setPlaying(state.playing);$('maSpeedOut').textContent = `${state.speed.toFixed(2)} rev/s`;$('maStage').classList.add('is-ready');track(ANALYTICS_EVENTS.SURFACE_OPENED, { surface: `visualizer:assembly:${start.machine.spec.id}` });diff --git a/src/assembly/README.md b/src/assembly/README.mdnew file mode 100644index 000000000..0c7ad0d69--- /dev/null+++ b/src/assembly/README.md@@ -0,0 +1,160 @@+# Machine Atlas geometry (`src/assembly/`)++The code behind [three.ws/assembly](https://three.ws/assembly). Two machines,+no model files: everything on that page is generated in the browser from a+handful of dimensions when the page loads, and regenerated whenever a slider+moves.++If you have only read the page, the short version is: dimensions become+profiles, profiles get revolved or extruded, a few surfaces are lofted, and the+motion is solved from the same numbers rather than played back from a clip.++## Layout++| File | What it holds |+|---|---|+| `parts.js` | The parametric vocabulary: revolves, extrusions, sweeps, lofts, merging. No machine knowledge. |+| `rig.js` | The explode runtime and the linkage solvers (`slider`, `circleIntersect`, `slideOnLine`, `placeLink`, `alignSegment`). |+| `materials.js` | One shared palette. Machines own their geometry but never their materials. |+| `radial-engine.js` | Machine 01: a single-row air-cooled radial aero engine. |+| `locomotive.js` | Machine 02: an outside-cylinder steam locomotive with return-crank valve gear. |++The page shell (`src/assembly.js`, `src/assembly.css`, `pages/assembly.html`)+owns the renderer, the panels and the URL state. It knows nothing about either+machine beyond the contract below.++## The machine contract++Every machine module exports three things:++```js+export const spec = {+ id: 'radial', // stable, used in the ?m= query parameter+ name: 'Radial Nine',+ subtitle: 'Air-cooled radial aero engine',+ era: '1932',+ blurb: '...', // one paragraph, shown under the title+ facts: [['Layout', 'Single-row radial, four-stroke']],+ params: [ // one slider each, in panel order+ { key: 'bore', label: 'Bore', min: 110, max: 175, step: 1, value: 155, unit: 'mm' },+ ],+ camera: { position: [2.7, 1.15, 1.55], target: [0, 0, 0.15], radius: 2.1 },+};++// Pure: the seven values the user controls in, every dimension the builder+// needs out. Keeping it pure is what makes the readout, the code panel and the+// geometry agree by construction.+export function derive(values) { /* ... */ }++// The Source panel. Printed from the live values, so it cannot drift away from+// the geometry the way a pasted snippet would.+export function codeFor(values) {+ return [{ label: 'Cylinder barrel', code: 'finnedBarrel({ ... })' }];+}++// Build the tree. `update(angle)` is called every frame with the crank angle in+// radians; `readout` is the derived-values list shown under the sliders.+export function build(values) {+ return { root: THREE.Group, update(angle) {}, readout: [['Displacement', '29.7 L']] };+}+```++Register a new machine by adding it to the `MACHINES` array in+`src/assembly.js`. Nothing else in the page needs to change: the tabs, the+sliders, the parts list, the readout, the code panel, the URL state and the GLB+export all read from the contract.++## Building a part++`parts.js` covers the four ways a machine part gets made. A worked example of+each:++```js+import { lathe, finnedBarrel, roundedBox, rodGeometry, railGeometry, loftedBlade } from './parts.js';++// Revolve a profile about +Y. Profiles are [radius, axial] pairs.+const dome = lathe([[0, 0], [0.34, 0], [0.36, 0.16], [0.24, 0.4], [0, 0.42]]);++// A sawtooth revolve: the fins are part of the same surface as the barrel,+// which is how a real casting works.+const barrel = finnedBarrel({ bore: 0.155, finRoot: 0.086, finTip: 0.114, length: 0.31, fins: 30 });++// Extrude a cross-section. A rail is one closed profile swept down the track.+const rail = railGeometry(21.0);++// A waisted stadium: a connecting rod running +X from a big end at the origin.+const rod = rodGeometry({ length: 0.35, bigEndR: 0.037, smallEndR: 0.019, thickness: 0.025 });++// Loft NACA sections with twist and taper into a propeller blade.+const blade = loftedBlade({ span: 1.0, chordRoot: 0.19, chordTip: 0.1, twistRoot: 34, twistTip: 8 });+```++Everything is in metres. A driving wheel really is 1.68 m across.++## Solving motion instead of animating it++`rig.js` holds the three solvers the machines share. They are the reason the+page behaves like a mechanism rather than like a loop:++```js+import { slider, slideOnLine, circleIntersect } from './rig.js';++// Piston on a cylinder axis, driven by a crankpin: the exact planar+// slider-crank, so a long rod visibly dwells at top dead centre.+const c = slider(crankpin, cylinderAxis, rodLength);++// A pin constrained to a horizontal line, reached by a link: the crosshead and+// the valve spindle both ride lines like this.+const crosshead = slideOnLine(crankpin, centrelineY, mainRodLength);++// Close a four-bar chain. Returns null when the links cannot reach, so a bad+// parameter set holds its last pose instead of producing NaN geometry.+const lowPin = circleIntersect(eccentricPin, eccRodLen, pivot, armLength, branch);+```++Pick the intersection branch once, at build time, and keep it. A branch chosen+per frame flips at dead centre and snaps the linkage through itself.++One consequence worth knowing if you add a machine with valve gear: the return+crank has to be nearly as long as the main crank and set well past a right+angle. The eccentric the gear actually sees is the vector sum of the two, and+that sum has to be small. `RETURN_CRANK_ANGLE` in `locomotive.js` is where that+lives.++## Explode++Parts carry their own explode vector, so taking a machine apart is one lerp over+the tree rather than a hand-keyed animation:++```js+import { part, applyExplode } from './rig.js';++group.add(part(geometry, MATERIALS.castIron, {+ name: 'barrel', // shown when the part is hovered+ group: 'cylinders', // subassembly, shown as a toggle chip+ explode: new THREE.Vector3(0, 0.16, 0), // where it goes at factor 1+}));++applyExplode(root, 0.5); // halfway apart+```++A part whose position is written every frame by `update()` must copy its new+position into `userData.rest`, or the next explode will pull it back to where it+was at build time. `placeLink` and `alignSegment` do this for you.++## Tests++`tests/assembly-machines.test.js` covers the two failure modes that matter: a+build that produces non-finite vertices at some parameter combination, and a+linkage that cannot close. Both machines are built at every parameter extreme+and the locomotive's four-bar is solved through a full revolution for each.++```bash+npx vitest run tests/assembly-machines.test.js+```++## Related++- `/assembly` is listed in `data/pages.json` under the `labs` section.+- `STRUCTURE.md` maps this directory to the surface it powers.+- The GLB export uses three's `GLTFExporter`; the result opens in `/viewer`.diff --git a/src/assembly/parts.js b/src/assembly/parts.jsindex 458cbc576..cadacd2e9 100644--- a/src/assembly/parts.js+++ b/src/assembly/parts.js@@ -378,10 +378,12 @@ export function mergeGeometries(geometries) {return out;}+// Triangles actually being drawn: a hidden subassembly costs nothing, and the+// stat panel should say so.export function triangleCount(object) {let n = 0;object.traverse((o) => {- if (!o.isMesh || !o.geometry) return;+ if (!o.isMesh || !o.geometry || !o.visible) return;const g = o.geometry;const count = g.index ? g.index.count : g.getAttribute('position').count;n += (count / 3) * (o.isInstancedMesh ? o.count : 1);diff --git a/src/labs.js b/src/labs.jsindex a60a006a5..179d6d353 100644--- a/src/labs.js+++ b/src/labs.js@@ -13,6 +13,7 @@ const CATEGORIES = {'/three-live': { label: '3D Live', cat: '3d', color: '#34d399', bg: 'rgba(52,211,153,.12)' },'/diorama': { label: '3D Live', cat: '3d', color: '#34d399', bg: 'rgba(52,211,153,.12)' },'/mocap-studio': { label: '3D Live', cat: '3d', color: '#34d399', bg: 'rgba(52,211,153,.12)' },+ '/assembly': { label: '3D Live', cat: '3d', color: '#34d399', bg: 'rgba(52,211,153,.12)' },'/agenc/embodied': { label: 'AI', cat: 'ai', color: '#60a5fa', bg: 'rgba(96,165,250,.12)' },'/autopilot': { label: 'Crypto', cat: 'crypto', color: '#f97316', bg: 'rgba(249,115,22,.12)' },'/pulse': { label: 'Crypto', cat: 'crypto', color: '#f97316', bg: 'rgba(249,115,22,.12)' },