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(play): put the real Trench Car on the road for traffic and for players to drive
nirholas51fb89d3664b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 642e83bc1..2954d4c0c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,10 @@Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).+## 2026-08-17++- **The viewer's backdrop picker stops vanishing while you read it, and sharing no longer posts "Meet Agent"**: Five fixes to the 3D model viewer at /app. Opening the Backdrop picker and taking a few seconds to read the six choices used to make the picker fade out from under the cursor: the viewer hides its controls after five seconds of stillness, and the picker was not on the list of surfaces that keep them awake, so an open picker went invisible and unclickable while still counting as open. It now stays put until you choose a backdrop or close it, and the controls resume fading once it is shut. Typing in the animation search while the clips were still loading stacked a second, contradictory message under the first, so the panel read "Loading clips" and "No clips matching" at the same time, and clearing the box left behind the nonsense line "No clips matching" with nothing in the quotes; the search now stays quiet until there are clips to search. Sharing the viewer to X, Farcaster or Telegram published "Meet Agent", an internal placeholder name, for anyone who had not loaded an agent of their own, and now uses the generic line instead. The page also shipped a sign-in panel and a welcome card that its own stylesheet blanked unconditionally, four links nobody could ever reach, and the preview card shown when the page is shared described the platform instead of the viewer. The avatar gallery behind the Avatar button is now announced to screen readers as a named dialog. (`/app`) `[fix, improvement]`+## 2026-08-16- **Docs · Avatar Artifact viewer** (`/docs/avatar-artifact`): The standalone avatar viewer you paste into any site as a one-line iframe: its ?agent= and ?model= parameters, the hosts a model may come from, how a clip-less rig still comes to life, and the sentence the page shows for every way it can fail.diff --git a/data/changelog.json b/data/changelog.jsonindex eb8521fe7..c2d2c4127 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,26 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-17",+ "title": "The viewer's backdrop picker stops vanishing while you read it, and sharing no longer posts \"Meet Agent\"",+ "summary": "Five fixes to the 3D model viewer at /app. Opening the Backdrop picker and taking a few seconds to read the six choices used to make the picker fade out from under the cursor: the viewer hides its controls after five seconds of stillness, and the picker was not on the list of surfaces that keep them awake, so an open picker went invisible and unclickable while still counting as open. It now stays put until you choose a backdrop or close it, and the controls resume fading once it is shut. Typing in the animation search while the clips were still loading stacked a second, contradictory message under the first, so the panel read \"Loading clips\" and \"No clips matching\" at the same time, and clearing the box left behind the nonsense line \"No clips matching\" with nothing in the quotes; the search now stays quiet until there are clips to search. Sharing the viewer to X, Farcaster or Telegram published \"Meet Agent\", an internal placeholder name, for anyone who had not loaded an agent of their own, and now uses the generic line instead. The page also shipped a sign-in panel and a welcome card that its own stylesheet blanked unconditionally, four links nobody could ever reach, and the preview card shown when the page is shared described the platform instead of the viewer. The avatar gallery behind the Avatar button is now announced to screen readers as a named dialog.",+ "tags": [+ "fix",+ "improvement"+ ],+ "link": "/app"+ },+ {+ "date": "2026-08-17",+ "title": "Avatar Studio now shows your whole avatar, and its Save button fits on a phone",+ "summary": "The studio camera was framing the base body from the shoulders to the knees: the face you were sculpting and the shoes you were picking were both outside the picture, and the only way to see them was to orbit the camera yourself every time the page loaded. The framing is now solved from the lens rather than guessed at, so a full-body shot really does hold the avatar head to toe, arms included, on any window shape, and the half-body and headshot views stay as tight as their names promise. On a 320px phone the top bar had been running past the edge of the screen and taking the Save avatar button with it, so a look built on a phone could not be saved at all; the bar now fits, with the Back and title labels standing down to make room. The tab strip on that same narrow layout had been hiding its labels without putting anything in their place, leaving six blank buttons, and now shows an icon per tab. The Parametric body badge that read 120+ sliders was white text on a white pill and invisible everywhere. A failed save now says the connection could not be reached and that your look is still there, instead of repeating the browser phrase Failed to fetch, and every accessory search box, every tab and the Back link now carry names a screen reader can read. Opening avatar-studio in local development also serves the same page production does, which it previously did not.",+ "tags": [+ "fix",+ "improvement"+ ],+ "link": "/avatar-studio"+ },{"date": "2026-08-16","title": "The Commons now fills with citizens in seconds instead of standing empty",diff --git a/multiplayer/src/rooms/WalkRoom.js b/multiplayer/src/rooms/WalkRoom.jsindex 5efc9fa73..1c459a4c7 100644--- a/multiplayer/src/rooms/WalkRoom.js+++ b/multiplayer/src/rooms/WalkRoom.js@@ -2425,6 +2425,12 @@ export class WalkRoom extends Room {this._releaseVehicleOf(client.sessionId, id); // give up any other car firstv.driver = client.sessionId;v.tsServer = Date.now();+ // Peers pose a player from `motion`, and a driver never sends 'move' again+ // until they step out, so seat them here. 'drive' is server-authored only:+ // MOTION_VALUES deliberately excludes it, so a player on foot cannot claim+ // to be sitting in a car they aren't in.+ player.motion = 'drive';+ player.tsServer = v.tsServer;client.send('vehicle', { event: 'enter', id });}@@ -2480,7 +2486,7 @@ export class WalkRoom extends Room {player.x = v.x;player.z = v.z;player.y = Math.max(0, Math.min(3, v.y + vehicleSpec(v.type).seat.y));- player.motion = 'idle';+ player.motion = 'drive';player.tsServer = v.tsServer;// The ordinary 'move' handler drives zone-entry detection, but a seated// driver never sends 'move', they stream 'vsync' instead. Without this, a@@ -2538,13 +2544,20 @@ export class WalkRoom extends Room {// Release any vehicle driven by this session (except `keepId`, when re-claiming)._releaseVehicleOf(sessionId, keepId = null) {+ let released = false;for (const [, v] of this.state.vehicles) {if (v.driver === sessionId && v.id !== keepId) {v.driver = '';v.speed = 0;v.tsServer = Date.now();+ released = true;}}+ // Out of the seat, out of the seated pose. An eviction sweep (disconnect,+ // switching cars) is the one path that clears a driver without going through+ // the exit handler, so a peer would otherwise keep seeing them sitting.+ const player = released ? this.state.players.get(sessionId) : null;+ if (player && player.motion === 'drive') player.motion = 'idle';}// Heading (radians about the up axis) extracted from a vehicle's quaternion.diff --git a/multiplayer/src/schemas.js b/multiplayer/src/schemas.jsindex e3af44ff0..c64186ca2 100644--- a/multiplayer/src/schemas.js+++ b/multiplayer/src/schemas.js@@ -118,7 +118,7 @@ export class Vehicle extends Schema {constructor() {super();this.id = '';- this.type = 'sedan'; // VEHICLE_TYPES key, picks the mesh + handling profile+ this.type = 'trench'; // VEHICLE_TYPES key, picks the mesh + handling profilethis.color = 0xffffff;this.x = 0;this.y = 0;diff --git a/multiplayer/src/vehicles.js b/multiplayer/src/vehicles.jsindex 45ea9230e..0cae20d36 100644--- a/multiplayer/src/vehicles.js+++ b/multiplayer/src/vehicles.js@@ -16,11 +16,49 @@// Handling profiles. Lengths in metres, mass in kg, forces in Newtons, speeds in// m/s, angles in radians. Each type has a distinct feel:+// trench — the world's default car, the Trench Car GLB, balanced and quick// coupe — low, fast, light, twitchy steering, less grip (slides)// sedan — the balanced everyday car// pickup — heavy, slower, planted, wide turning, lots of grip// buggy — light off-roader, high grip + stiff suspension, nimble+//+// A type with a `model` drives a real GLB (src/game/vehicle-model.js) instead of+// the procedural silhouettes in src/game/vehicle-mesh.js. Its dims, wheel+// geometry and seat are measured off that mesh, so the physics chassis, the+// wheels the player watches turn, and the driver in the seat all agree.export const VEHICLE_TYPES = {+ trench: {+ id: 'trench',+ label: 'Trench Car',+ // The community model staged at public/vehicles/trench-car.glb by+ // scripts/build-trench-car.mjs. The client resolves this to a URL; the+ // server only ever passes the string through.+ model: 'trench-car',+ mass: 1400,+ topSpeed: 26, // ~94 km/h+ engineForce: 5000,+ brakeForce: 125,+ reverseForce: 2500,+ steerMax: 0.5,+ steerSpeed: 2.9,+ grip: 2.4,+ // Measured off the GLB (tests/vehicles-trench-car.test.js re-measures it):+ // 1.85 m wide, 4.31 m long, roof 1.31 m above the road, wheel centres at+ // z +1.21 / -1.29, x ±0.70, radius 0.30. Height is road-to-roof, so the+ // collider wraps the whole visible car.+ dims: { l: 4.31, w: 1.85, h: 1.31 },+ wheel: { radius: 0.3, halfWidth: 0.11, inset: 0.22, frontZ: 1.21, rearZ: -1.29 },+ // rest=0.58 follows the clearance rule the other types learned the hard+ // way (see coupe below): the chassis collider's underside sits+ // 1.3 * (h/2) below the body origin, so the resting chassis centre+ // (vehicleRestHeight = 1.011) has to clear it. 0.58 leaves 0.16 m of air+ // under the collider, matching the sedan's proven margin, so the wheels+ // carry the car instead of the hull grinding on the road.+ suspension: { rest: 0.58, stiffness: 25, travel: 0.18, compression: 0.84, relax: 0.9 },+ // Driver's seat: the model's footwell floor, 0.30 m above the road.+ seat: { x: -0.42, y: -0.71, z: -0.15 },+ color: 0x1b1d22,+ },coupe: {id: 'coupe',label: 'Coupe',@@ -45,7 +83,12 @@ export const VEHICLE_TYPES = {// (not the hull) carry the car's weight and traction (10.8 m/s after the// same 3s in the same repro).suspension: { rest: 0.4, stiffness: 26, travel: 0.16, compression: 0.82, relax: 0.88 },- seat: { x: -0.42, y: 0.62, z: -0.2 }, // driver seat offset in chassis space+ // Driver's seat, as the offset from the chassis CENTRE to where the+ // driver's rig origin (their feet) belongs — the footwell floor, which is+ // below the chassis centre on every car, hence the negative y. Both the+ // client (VehicleManager._seatAvatar) and the server (WalkRoom's rider+ // height) read this, so a driver sits in the same place for everyone.+ seat: { x: -0.42, y: -0.53, z: -0.2 },color: 0xc8402f,},sedan: {@@ -66,7 +109,7 @@ export const VEHICLE_TYPES = {// Verified: stock 0.36 never moves (0.00 m/s after 3s full throttle) in// the real-Rapier repro; 0.5 reaches 7.9 m/s in the same window.suspension: { rest: 0.5, stiffness: 24, travel: 0.18, compression: 0.85, relax: 0.9 },- seat: { x: -0.44, y: 0.72, z: -0.1 },+ seat: { x: -0.44, y: -0.61, z: -0.1 },color: 0x2f6fc8,},pickup: {@@ -88,7 +131,7 @@ export const VEHICLE_TYPES = {// real-Rapier repro. 0.6 clears the chassis off the ground and reaches// 4.1 m/s in 3s, matching a heavy/planted truck's slower character.suspension: { rest: 0.6, stiffness: 22, travel: 0.22, compression: 0.85, relax: 0.9 },- seat: { x: -0.5, y: 0.92, z: 0.35 },+ seat: { x: -0.5, y: -0.55, z: 0.35 },color: 0x2b2f36,},buggy: {@@ -105,7 +148,7 @@ export const VEHICLE_TYPES = {dims: { l: 3.4, w: 1.8, h: 1.0 },wheel: { radius: 0.4, halfWidth: 0.24, inset: 0.06, frontZ: 1.2, rearZ: -1.15 },suspension: { rest: 0.46, stiffness: 28, travel: 0.26, compression: 0.8, relax: 0.86 },- seat: { x: -0.4, y: 0.66, z: -0.1 },+ seat: { x: -0.4, y: -0.62, z: -0.1 },color: 0xe0a52e,},};@@ -116,8 +159,12 @@ export function isVehicleType(t) {return typeof t === 'string' && Object.prototype.hasOwnProperty.call(VEHICLE_TYPES, t);}+// The world's default car: what an unknown/blank type resolves to, what ambient+// traffic drives, and what a player finds parked at the spawn plaza.+export const DEFAULT_VEHICLE_TYPE = 'trench';+export function vehicleSpec(type) {- return VEHICLE_TYPES[type] || VEHICLE_TYPES.sedan;+ return VEHICLE_TYPES[type] || VEHICLE_TYPES[DEFAULT_VEHICLE_TYPE];}// The chassis-centre height a parked/resting vehicle sits at, derived from the@@ -139,15 +186,18 @@ export function vehicleRestHeight(type) {// plaza-edge cars sit near the Downtown spawn so a freshly-dropped player finds a// ride within a few seconds' walk (clear of the totem (0,0,-12), the jumbotron// (0,0,-30) and the Agent Exchange (8,0,-6)). yaw is the resting heading (0 = +z).+// The default car takes the two plaza bays and the North Depot, so the first+// vehicle a player ever walks up to is the one ambient traffic is driving past+// them; the other depots keep the handling variety.export const VEHICLE_SPAWNS = [// Avenue bays — keep in sync with world-zones.js type:'vehicle' points.- { id: 'veh-north-ave', type: 'coupe', x: 6, z: -90, yaw: 0 },+ { id: 'veh-north-ave', type: 'trench', x: 6, z: -90, yaw: 0 },{ id: 'veh-south-ave', type: 'sedan', x: -6, z: 90, yaw: Math.PI },{ id: 'veh-east-ave', type: 'pickup', x: 90, z: 6, yaw: -Math.PI / 2 },{ id: 'veh-west-ave', type: 'buggy', x: -90, z: -6, yaw: Math.PI / 2 },// Plaza-edge starters for discoverability.- { id: 'veh-plaza-1', type: 'sedan', x: -16, z: 14, yaw: Math.PI },- { id: 'veh-plaza-2', type: 'buggy', x: 18, z: 14, yaw: Math.PI },+ { id: 'veh-plaza-1', type: 'trench', x: -16, z: 14, yaw: Math.PI },+ { id: 'veh-plaza-2', type: 'trench', x: 18, z: 14, yaw: Math.PI },];// --- Anti-cheat limits (server-enforced) ----------------------------------diff --git a/package.json b/package.jsonindex 7197bbc8b..aff933448 100644--- a/package.json+++ b/package.json@@ -281,6 +281,7 @@"build:extension:prod": "node scripts/build-extension-icons.mjs && node scripts/build-extension.mjs --prod","optimize:glb": "node scripts/optimize-glb.mjs","compress:glbs": "node scripts/compress-glbs.mjs",+ "build:trench-car": "node scripts/build-trench-car.mjs","fetch-animations": "node scripts/download-animations.mjs","fetch:mixamo-catalog": "node scripts/fetch-mixamo-catalog.mjs","mixamo:catalog": "node scripts/mixamo-all.mjs --catalog",diff --git a/pages/app-next.html b/pages/app-next.htmlindex 662cde193..e960988a7 100644--- a/pages/app-next.html+++ b/pages/app-next.html@@ -22,10 +22,10 @@<!-- Open Graph --><meta property="og:type" content="website" />- <meta property="og:title" content="three.ws — The First Embodied AI Agent" data-i18n-attr="content:app_next.meta_og_title"/>+ <meta property="og:title" content="3D Model Viewer: drop in a glTF or GLB" data-i18n-attr="content:app_next.meta_og_title"/><metaproperty="og:description"- content="Agents have always been imagined as present. We made that real."+ content="Drag and drop a 3D model to inspect it in the browser: orbit the camera, play animations, switch the backdrop, then share or embed the result."data-i18n-attr="content:app_next.meta_og_description"/><meta property="og:url" content="https://three.ws/app" /><meta property="og:site_name" content="three.ws" />@@ -35,10 +35,10 @@<!-- Twitter / X --><meta name="twitter:card" content="summary_large_image" />- <meta name="twitter:title" content="three.ws — Embodied AI" data-i18n-attr="content:app_next.meta_twitter_title"/>+ <meta name="twitter:title" content="3D Model Viewer on three.ws" data-i18n-attr="content:app_next.meta_twitter_title"/><metaname="twitter:description"- content="The first three.ws with a body, a place, an identity, and memory."+ content="Drop a glTF or GLB in the browser, orbit it, play its animations, and share or embed the result."data-i18n-attr="content:app_next.meta_twitter_description"/><meta name="twitter:site" content="@trythreews" /><meta name="twitter:creator" content="@nichxbt" />@@ -186,77 +186,6 @@3D model viewer: drag and drop a glTF or GLB file</h1>- <!-- Auth gate — shown only to anonymous visitors -->- <aside class="auth-gate" id="auth-gate">- <div class="auth-gate__inner">- <div class="auth-gate__eyebrow">- <svg class="auth-gate__lock" aria-hidden="true" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">- <rect x="3" y="11" width="18" height="11" rx="2" />- <path d="M7 11V7a5 5 0 0 1 10 0v4" />- </svg>- <span data-i18n="app_next.unlock_the_agent">Unlock the agent</span>- </div>- <h2 class="auth-gate__title" data-i18n="app_next.your_agent_lives_here">Your agent lives here</h2>- <p class="auth-gate__desc" data-i18n="app_next.sign_in_to_access_animations_scene_controls">- Sign in to access animations, scene controls, and your agent's on-chain- identity, memory, and skills.- </p>- <div class="auth-gate__actions">- <a class="auth-gate__btn auth-gate__btn--primary" href="/login" data-i18n="app_next.sign_in_2">Sign in</a>- <a class="auth-gate__btn" href="/register" data-i18n="app_next.create_account">Create account</a>- </div>- <ul class="auth-gate__perks">- <li data-i18n="app_next.animations_presence_controls">Animations & presence controls</li>- <li data-i18n="app_next.save_avatars_to_your_account">Save avatars to your account</li>- <li data-i18n="app_next.register_on_chain_agent_identity">Register on-chain agent identity</li>- <li data-i18n="app_next.scene_lighting_material_editor">Scene, lighting & material editor</li>- </ul>- </div>- </aside>-- <!-- Post-creation onboarding banner — shown once after creating an agent -->- <aside- class="agent-onboarding"- id="agent-onboarding"- role="dialog"- aria-labelledby="agent-onboarding-title"- hidden- >- <div class="agent-onboarding__inner">- <button- class="agent-onboarding__close"- id="agent-onboarding-close"- type="button"- aria-label="Dismiss welcome message"- data-i18n-attr="aria-label:app_next.dismiss_welcome_message_arialabel">- ×- </button>- <h2 class="agent-onboarding__title" id="agent-onboarding-title" data-i18n="app_next.your_agent_is_ready">- Your agent is ready 🎉- </h2>- <p class="agent-onboarding__desc" data-i18n="app_next.this_is_your_agent_s_studio_try">- This is your agent's studio. Try an animation from the chips below, drop a- new GLB to swap its body, or publish it on-chain so anyone can find and- embed it.- </p>- <div class="agent-onboarding__actions">- <a- class="agent-onboarding__btn agent-onboarding__btn--primary"- href="/deploy"- id="agent-onboarding-deploy"- data-i18n="app_next.deploy_on_chain">Deploy on-chain →</a- >- <a- class="agent-onboarding__btn"- id="agent-onboarding-share"- target="_blank"- rel="noopener noreferrer"- data-i18n="app_next.view_public_profile">View public profile</a- >- </div>- </div>- </aside>-<!-- Switchable scene backdrop — bottommost layer behind the transparent canvas.Painted by app-next-overlay.js (saved preset, picker, or agent chat). --><div class="nxt-stage-backdrop" id="nxt-stage-backdrop" aria-hidden="true"></div>diff --git a/public/app-next.css b/public/app-next.cssindex 54cf9c15a..82e3cda96 100644--- a/public/app-next.css+++ b/public/app-next.css@@ -71,10 +71,13 @@ body.app-next-body {}/* Hide every chrome element produced by the production app.js that the- demo overrides. None of these are required for the viewer to work. */+ demo overrides. None of these are required for the viewer to work.+ The auth gate and the "Your agent is ready" onboarding card used to be+ listed here AND shipped in this page's markup, so the page rendered two+ panels it then hid unconditionally: four links nobody could ever reach.+ The markup is gone; app.js only ever queried those ids, never created+ them, and every one of its lookups is null-guarded. */body.app-next-body #agent-presence-sidebar,-body.app-next-body #auth-gate,-body.app-next-body #agent-onboarding,body.app-next-body .dropzone,body.app-next-body footer,body.app-next-body .h-footer,diff --git a/public/changelog.json b/public/changelog.jsonindex 2b9776f01..e0fb22433 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,11 +1,22 @@{- "generated_at": "2026-08-16T22:41:51.246Z",+ "generated_at": "2026-08-17T00:47:21.753Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},"entries": [+ {+ "date": "2026-08-17",+ "type": "update",+ "title": "The viewer's backdrop picker stops vanishing while you read it, and sharing no longer posts \"Meet Agent\"",+ "summary": "Five fixes to the 3D model viewer at /app. Opening the Backdrop picker and taking a few seconds to read the six choices used to make the picker fade out from under the cursor: the viewer hides its controls after five seconds of stillness, and the picker was not on the list of surfaces that keep them awake, so an open picker went invisible and unclickable while still counting as open. It now stays put until you choose a backdrop or close it, and the controls resume fading once it is shut. Typing in the animation search while the clips were still loading stacked a second, contradictory message under the first, so the panel read \"Loading clips\" and \"No clips matching\" at the same time, and clearing the box left behind the nonsense line \"No clips matching\" with nothing in the quotes; the search now stays quiet until there are clips to search. Sharing the viewer to X, Farcaster or Telegram published \"Meet Agent\", an internal placeholder name, for anyone who had not loaded an agent of their own, and now uses the generic line instead. The page also shipped a sign-in panel and a welcome card that its own stylesheet blanked unconditionally, four links nobody could ever reach, and the preview card shown when the page is shared described the platform instead of the viewer. The avatar gallery behind the Avatar button is now announced to screen readers as a named dialog.",+ "link": "/app",+ "tags": [+ "fix",+ "improvement"+ ]+ },{"date": "2026-08-16","type": "launch",diff --git a/public/changelog.xml b/public/changelog.xmlindex e63aebfe2..9f27c30dc 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -6,6 +6,14 @@<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/><description>What's new on three.ws: features, improvements, and releases, newest first.</description><language>en</language>+ <item>+ <title>The viewer's backdrop picker stops vanishing while you read it, and sharing no longer posts "Meet Agent"</title>+ <link>https://three.ws/app</link>+ <guid isPermaLink="false">2026-08-17:The viewer's backdrop picker stops vanishing while you read it, and sharing no longer posts "Meet Agent"</guid>+ <pubDate>Mon, 17 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>Five fixes to the 3D model viewer at /app. Opening the Backdrop picker and taking a few seconds to read the six choices used to make the picker fade out from under the cursor: the viewer hides its controls after five seconds of stillness, and the picker was not on the list of surfaces that keep them awake, so an open picker went invisible and unclickable while still counting as open. It now stays put until you choose a backdrop or close it, and the controls resume fading once it is shut. Typing in the animation search while the clips were still loading stacked a second, contradictory message under the first, so the panel read "Loading clips" and "No clips matching" at the same time, and clearing the box left behind the nonsense line "No clips matching" with nothing in the quotes; the search now stays quiet until there are clips to search. Sharing the viewer to X, Farcaster or Telegram published "Meet Agent", an internal placeholder name, for anyone who had not loaded an agent of their own, and now uses the generic line instead. The page also shipped a sign-in panel and a welcome card that its own stylesheet blanked unconditionally, four links nobody could ever reach, and the preview card shown when the page is shared described the platform instead of the viewer. The avatar gallery behind the Avatar button is now announced to screen readers as a named dialog.</description>+ </item><item><title>Docs · Avatar Artifact viewer</title><link>https://three.ws/docs/avatar-artifact</link>diff --git a/public/features.json b/public/features.jsonindex 2763a3dbb..db235c1e8 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-16T22:41:51.141Z",+ "generated_at": "2026-08-17T00:47:21.637Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/public/locales/en.json b/public/locales/en.jsonindex 0f9a448cc..22ca23409 100644--- a/public/locales/en.json+++ b/public/locales/en.json@@ -1254,11 +1254,11 @@"keyboard_shortcuts": "Keyboard shortcuts","marketplace": "Marketplace","meta_description": "Drag and drop a glTF or GLB file to inspect it in the browser: orbit the camera, play animations, switch the backdrop, then share or embed the result.",- "meta_og_description": "Agents have always been imagined as present. We made that real.",- "meta_og_title": "three.ws — The First Embodied AI Agent",+ "meta_og_description": "Drag and drop a 3D model to inspect it in the browser: orbit the camera, play animations, switch the backdrop, then share or embed the result.",+ "meta_og_title": "3D Model Viewer: drop in a glTF or GLB","meta_title": "3D Model Viewer (glTF/GLB) | three.ws",- "meta_twitter_description": "The first three.ws with a body, a place, an identity, and memory.",- "meta_twitter_title": "three.ws — Embodied AI",+ "meta_twitter_description": "Drop a glTF or GLB in the browser, orbit it, play its animations, and share or embed the result.",+ "meta_twitter_title": "3D Model Viewer on three.ws","my_profile": "My profile","online": "Online","open_animation_picker": "Open animation picker",diff --git a/public/vehicles/trench-car.glb b/public/vehicles/trench-car.glbnew file mode 100644index 000000000..8eff66e9eBinary files /dev/null and b/public/vehicles/trench-car.glb differdiff --git a/scripts/build-trench-car.mjs b/scripts/build-trench-car.mjsnew file mode 100644index 000000000..32bf73c88--- /dev/null+++ b/scripts/build-trench-car.mjs@@ -0,0 +1,115 @@+#!/usr/bin/env node+/**+ * Stage the Trench Car GLB into public/vehicles/trench-car.glb.+ *+ * The Trench Car is a community model published to the three.ws avatar gallery+ * (avatar e702d59a-d29f-4f21-af8a-6400dd1a2c6f, slug `trench-car`). It is the+ * default car in the world: ambient traffic drives it and it is the vehicle+ * parked at the /play spawn plaza for players to take the wheel.+ *+ * The published master is 16 MB, almost all of it two oversized textures (a+ * 2048² metal-roughness PNG and a 5333×5292 body-wrap JPEG). Every /play visitor+ * downloads this file, so the master is unusable as-is. This script pulls the+ * master from the live avatar API (no hardcoded storage URL, so a re-upload of+ * the same avatar re-stages cleanly), caps texture resolution, and runs the same+ * geometry chain scripts/compress-glbs.mjs uses, landing well under 2 MB with no+ * visible change at gameplay distance.+ *+ * The output keeps EXT_meshopt_compression, which every loader that touches it+ * already wires a decoder for (src/game/vehicle-model.js, shared with+ * src/game/avatar-rig.js).+ *+ * npm run build:trench-car # fetch + optimize + write+ * npm run build:trench-car -- --dry # report the sizes, write nothing+ */++import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { NodeIO } from '@gltf-transform/core';+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';+import { dedup, prune, resample, weld, simplify, quantize, meshopt, textureCompress } from '@gltf-transform/functions';+import { MeshoptEncoder, MeshoptDecoder, MeshoptSimplifier } from 'meshoptimizer';+import sharp from 'sharp';++const ROOT = path.resolve(fileURLToPath(import.meta.url), '../..');+const AVATAR_ID = 'e702d59a-d29f-4f21-af8a-6400dd1a2c6f';+const API = process.env.THREE_WS_API_BASE || 'https://three.ws';+const OUT = path.join(ROOT, 'public', 'vehicles', 'trench-car.glb');+const DRY = process.argv.includes('--dry');++// The body wrap carries the model's identity (the collage livery), so it keeps+// the larger cap; the metal-roughness map is a grayscale detail texture that+// reads identically at half resolution.+const COLOR_CAP = [2048, 2048];+const DATA_CAP = [1024, 1024];++function fmt(n) {+ if (n < 1024) return `${n} B`;+ if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;+ return `${(n / (1024 * 1024)).toFixed(2)} MB`;+}++async function fetchMaster() {+ const metaUrl = `${API}/api/avatars/${AVATAR_ID}`;+ const metaRes = await fetch(metaUrl, { headers: { accept: 'application/json' } });+ if (!metaRes.ok) throw new Error(`avatar lookup failed: ${metaRes.status} ${metaUrl}`);+ const { avatar } = await metaRes.json();+ const src = avatar?.model_url || avatar?.url;+ if (!src) throw new Error(`avatar ${AVATAR_ID} has no model URL`);+ console.log(`[trench-car] source: ${avatar.name} (${avatar.slug}) → ${src}`);+ const glbRes = await fetch(src);+ if (!glbRes.ok) throw new Error(`model download failed: ${glbRes.status} ${src}`);+ return Buffer.from(await glbRes.arrayBuffer());+}++async function main() {+ await Promise.all([MeshoptEncoder.ready, MeshoptDecoder.ready]);+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS).registerDependencies({+ 'meshopt.encoder': MeshoptEncoder,+ 'meshopt.decoder': MeshoptDecoder,+ });++ const master = await fetchMaster();+ console.log(`[trench-car] master: ${fmt(master.byteLength)}`);++ const document = await io.readBinary(new Uint8Array(master));+ await document.transform(+ dedup(),+ prune(),+ resample(),+ // The master is a 263k-triangle studio model. A world with a lane of+ // traffic plus a parked fleet draws a dozen of these at once, with shadow+ // casting on top, so decimate to a game budget: `error` is a fraction of+ // the AABB, and 0.5% keeps the silhouette, the wheel arches and the rims+ // reading correctly while cutting the triangle count by ~2/3.+ weld(),+ simplify({ simplifier: MeshoptSimplifier, ratio: 0.35, error: 0.005 }),+ quantize(),+ meshopt({ encoder: MeshoptEncoder, level: 'medium' }),+ textureCompress({+ encoder: sharp, targetFormat: 'webp', quality: 88,+ slots: /metallicRoughness|occlusion|normal/, resize: DATA_CAP,+ }),+ textureCompress({ encoder: sharp, targetFormat: 'webp', quality: 90, resize: COLOR_CAP }),+ );++ const bytes = await io.writeBinary(document);+ const pct = ((1 - bytes.byteLength / master.byteLength) * 100).toFixed(1);+ console.log(`[trench-car] optimized: ${fmt(bytes.byteLength)} (-${pct}%)`);++ for (const tex of document.getRoot().listTextures()) {+ const size = tex.getSize();+ console.log(` texture ${tex.getName() || '(unnamed)'}: ${size?.join('x')} ${tex.getMimeType()} ${fmt(tex.getImage()?.byteLength || 0)}`);+ }++ if (DRY) { console.log('[trench-car] --dry: nothing written.'); return; }+ fs.mkdirSync(path.dirname(OUT), { recursive: true });+ fs.writeFileSync(OUT, bytes);+ console.log(`[trench-car] wrote ${path.relative(ROOT, OUT)}`);+}++main().catch((err) => {+ console.error('[trench-car] fatal:', err.message);+ process.exit(1);+});diff --git a/src/app-next-overlay.js b/src/app-next-overlay.jsindex 160963d45..ec45f6e53 100644--- a/src/app-next-overlay.js+++ b/src/app-next-overlay.js@@ -733,6 +733,12 @@ function wireAnimationSheet() {if (match) visible++;});grid.querySelectorAll('.nxt-anim-empty[data-search]').forEach((n) => n.remove());+ // No cards means the grid is showing its own status ("Loading clips…", "This+ // avatar has no animations", a rig warning). The search box is focused 60ms+ // after the sheet opens, so typing straight away is the normal flow, and+ // appending a second message there stacks two contradictory answers under+ // each other. An empty query has nothing to report either way.+ if (!cards.length || !q) return;if (visible === 0) {const empty = document.createElement('div');empty.className = 'nxt-anim-empty';@@ -845,11 +851,16 @@ function wireShare() {const farcasterBtn = document.getElementById('nxt-share-farcaster');const telegramBtn = document.getElementById('nxt-share-telegram');+ // The stock identity is literally named "Agent", so a visitor who has not+ // loaded an agent of their own used to broadcast "Meet Agent" to X, Farcaster+ // and Telegram. A placeholder name is no name: fall through to the generic+ // line instead of publishing the default.+ const PLACEHOLDER_NAMES = new Set(['agent', 'untitled', 'unnamed', 'avatar']);const shareText = () => {const app = window.VIEWER?.app;- const name = app?.identity?.name;- return name- ? `Meet ${name} — an embodied AI agent on @trythreews`+ const name = app?.identity?.name?.trim();+ return name && !PLACEHOLDER_NAMES.has(name.toLowerCase())+ ? `Meet ${name}, an embodied AI agent on @trythreews`: 'Check out this embodied AI agent on @trythreews';};@@ -1497,7 +1508,18 @@ function wireAutoHide() {}function anyPanelOpen() {- const ids = ['nxt-anim-sheet', 'nxt-share-popover', 'nxt-help', 'nxt-more-menu', 'nav-user-menu'];+ // Every dismissible surface belongs here. Auto-hide drops pointer-events on+ // the action bar, and the backdrop picker lives INSIDE that bar: leave it out+ // and a user who opens the picker and spends five seconds reading the six+ // swatch names watches their open picker fade out from under the cursor.+ const ids = [+ 'nxt-anim-sheet',+ 'nxt-share-popover',+ 'nxt-backdrop-popover',+ 'nxt-help',+ 'nxt-more-menu',+ 'nav-user-menu',+ ];for (const id of ids) {const el = document.getElementById(id);if (el && !el.hidden) return true;diff --git a/src/avatar-gallery-picker.js b/src/avatar-gallery-picker.jsindex eeca6af78..70c5eb016 100644--- a/src/avatar-gallery-picker.js+++ b/src/avatar-gallery-picker.js@@ -117,6 +117,13 @@ export class AvatarGalleryPicker {this._overlay = document.createElement('div');this._overlay.className = 'agp-overlay';+ // Modal semantics, so a screen reader announces the picker as a dialog with+ // a name instead of an unlabelled div, and treats the page behind it as+ // inert. Only the modal path gets these: mountInline() renders the same+ // shell as ordinary in-page content, where a dialog role would be a lie.+ this._overlay.setAttribute('role', 'dialog');+ this._overlay.setAttribute('aria-modal', 'true');+ this._overlay.setAttribute('aria-label', this.opts.title);this._overlay.addEventListener('click', (e) => {if (e.target === this._overlay) this.close();});diff --git a/src/game/vehicle-model.js b/src/game/vehicle-model.jsnew file mode 100644index 000000000..154980bb9--- /dev/null+++ b/src/game/vehicle-model.js@@ -0,0 +1,169 @@+// Shared GLB car models for the world's traffic and its drivable fleet.+//+// The Trench Car (a community model published to the three.ws avatar gallery,+// staged into public/vehicles/ by scripts/build-trench-car.mjs) is the default+// car everywhere in /play: ambient traffic drives it and it is what a player+// takes the wheel of. Both surfaces want the same thing from a car GLB, so the+// splitting work lives here once:+//+// • one download + parse per URL, shared by every car on screen (a clone+// shares geometry and textures with its template, exactly like the avatar+// template cache in avatar-rig.js);+// • the four wheel nodes lifted out into pivot/spinner pairs so a caller can+// steer and roll them, matching the contract the procedural meshes in+// vehicle-mesh.js already expose to VehicleManager;+// • the brake-light material cloned per instance, so one car braking does not+// light up every other car sharing the template.+//+// Positions are returned in MODEL space: the body group's origin is the car's+// contact patch with the road (y=0), and each wheel pivot sits at that wheel's+// centre. Callers that work in chassis-centre space (the drivable fleet) offset+// the body themselves; callers that sit cars on the ground (ambient traffic)+// use it as-is.++import { Box3, Group, Vector3 } from 'three';+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';+import { dracoLoader, meshoptReady } from './avatar-rig.js';+import { log } from '../shared/log.js';++// The staged, optimized copy. The 16 MB gallery master is unusable on a page+// every visitor loads; see scripts/build-trench-car.mjs for how this is built.+export const TRENCH_CAR_URL = '/vehicles/trench-car.glb';++// Blender exports the wheels as siblings named wheel1..wheel4 (with a space in+// two of them). Matching on the name prefix keeps this working through the+// gltf-transform pass, which preserves node names but re-parents the body mesh.+const WHEEL_NODE = /^wheel/i;+// Material names from the source model. `stoplamp` is the rear brake bar.+const BRAKE_MATERIAL = /^stoplamp$/i;++const _loader = new GLTFLoader();+_loader.setDRACOLoader(dracoLoader);+let _decoderWired = false;++const _templates = new Map(); // url → { promise, refs }+const _box = new Box3();+const _centre = new Vector3();++function loadTemplate(url) {+ let entry = _templates.get(url);+ if (entry) return entry;+ entry = { refs: 0, promise: null };+ entry.promise = (async () => {+ // Staged car GLBs keep EXT_meshopt_compression, so the decoder has to be+ // on the loader before the first parse or GLTFLoader throws on bufferView 0.+ const decoder = await meshoptReady;+ if (decoder && !_decoderWired) { _loader.setMeshoptDecoder(decoder); _decoderWired = true; }+ const gltf = await _loader.loadAsync(url);+ gltf.scene.updateMatrixWorld(true);+ return gltf.scene;+ })();+ // A failed load must not poison the URL for the rest of the session.+ entry.promise.catch(() => { if (_templates.get(url) === entry) _templates.delete(url); });+ _templates.set(url, entry);+ return entry;+}++/** True once a model is downloaded (or downloading), so another car is free. */+export function hasVehicleModel(url) {+ return _templates.has(url);+}++// Lift one wheel node onto a pivot/spinner pair centred on the wheel itself.+// `attach` preserves the node's world transform through the re-parent, so this+// survives whatever transforms the export (and gltf-transform's quantization)+// left on the node chain.+function liftWheel(node) {+ _box.setFromObject(node);+ _box.getCenter(_centre);+ const pivot = new Group();+ pivot.position.copy(_centre);+ const spinner = new Group();+ pivot.add(spinner);+ pivot.updateMatrixWorld(true);+ spinner.attach(node);+ return { pivot, spinner };+}++/**+ * Clone a car model into a fresh, drivable set of parts.+ *+ * @returns {Promise<{ body: Group, wheels: Array<{pivot: Group, spinner: Group}>,+ * wheelRadius: number, setBrake: (on: boolean) => void, dispose: () => void }>}+ * `body` holds the chassis with the wheels removed; `wheels` are ordered+ * front-left, front-right, rear-left, rear-right to match the wheel order+ * PhysicsWorld.createVehicle uses.+ */+export async function instantiateVehicleModel(url) {+ const entry = loadTemplate(url);+ const template = await entry.promise;+ entry.refs++;++ const body = template.clone(true);+ body.updateMatrixWorld(true);++ const wheelNodes = [];+ body.traverse((n) => { if (WHEEL_NODE.test(n.name || '')) wheelNodes.push(n); });+ const wheels = wheelNodes.map(liftWheel);+ // Front wheels first (+z is forward), then left before right on each axle, so+ // index 0..3 lines up with the steered-front-pair order the vehicle+ // controller and VehicleManager._updateDrivenWheels both assume.+ wheels.sort((a, b) => (b.pivot.position.z - a.pivot.position.z) || (b.pivot.position.x - a.pivot.position.x));++ // Wheel radius from the model itself, so a caller can sanity-check the+ // handling spec against the mesh it is actually driving.+ let wheelRadius = 0;+ for (const w of wheels) wheelRadius = Math.max(wheelRadius, w.pivot.position.y);++ // Per-instance brake material: cloned so this car's brake lights are its own.+ const ownMaterials = [];+ const brakeMaterials = [];+ body.traverse((n) => {+ if (!n.isMesh) return;+ n.castShadow = true;+ n.receiveShadow = true;+ const mats = Array.isArray(n.material) ? n.material : [n.material];+ mats.forEach((mat, i) => {+ if (!mat || !BRAKE_MATERIAL.test(mat.name || '')) return;+ const own = mat.clone();+ ownMaterials.push(own);+ brakeMaterials.push(own);+ if (Array.isArray(n.material)) n.material[i] = own; else n.material = own;+ });+ });+ for (const w of wheels) w.spinner.traverse((n) => { if (n.isMesh) n.castShadow = true; });++ const restColor = brakeMaterials.map((m) => m.color.getHex());+ let braking = false;++ return {+ body,+ wheels,+ wheelRadius,+ // Brake lights: brighten the lamp and add emissive so it reads at night+ // and in the shade, then restore the model's own paint when released.+ setBrake(on) {+ const next = !!on;+ if (next === braking) return;+ braking = next;+ brakeMaterials.forEach((mat, i) => {+ mat.color.setHex(next ? 0xff3b30 : restColor[i]);+ mat.emissive?.setHex(next ? 0x5a0f0c : 0x000000);+ });+ },+ // Per-instance materials only: geometry and textures belong to the shared+ // template, which outlives this car.+ dispose() {+ for (const mat of ownMaterials) mat.dispose();+ entry.refs = Math.max(0, entry.refs - 1);+ },+ };+}++/**+ * Warm the shared template so the first car on screen is already textured.+ * Fire-and-forget: a failure is logged and every caller falls back on its own.+ */+export function preloadVehicleModel(url = TRENCH_CAR_URL) {+ loadTemplate(url).promise.catch((e) => log.warn('[vehicle-model] preload failed:', e?.message));+}diff --git a/tests/camera-presets.test.js b/tests/camera-presets.test.jsindex 90537d4ee..7b2c44e09 100644--- a/tests/camera-presets.test.js+++ b/tests/camera-presets.test.js@@ -96,6 +96,60 @@ describe('computeFraming — preset semantics', () => {});});+describe('computeFraming: the preset keeps its subject in frame', () => {+ // What the frustum actually sees at the returned distance. A preset that+ // promises "entire avatar in frame" has to be checked against the projection,+ // not against a distance multiplier: the multiplier alone once left the+ // avatar studio cropping the head and the feet off the base body.+ const visible = (framing, aspectRatio) => {+ const distance = framing.position.z - framing.target.z;+ const height = 2 * distance * Math.tan((framing.fov * Math.PI) / 360);+ return { height, width: height * aspectRatio };+ };++ it('full frames the whole body, head to toe, on every viewport shape', () => {+ for (const aspectRatio of [0.5, 0.75, 1, 1.33, 1.78, 2.4]) {+ const r = computeFraming({ box: HUMANOID, preset: 'full', aspectRatio });+ const { height, width } = visible(r, aspectRatio);+ const bodyHeight = HUMANOID.max.y - HUMANOID.min.y;+ const bodyWidth = HUMANOID.max.x - HUMANOID.min.x;+ // Both extremes of the body sit inside the vertical frustum.+ expect(r.target.y - height / 2, `aspect ${aspectRatio}`).toBeLessThanOrEqual(HUMANOID.min.y);+ expect(r.target.y + height / 2, `aspect ${aspectRatio}`).toBeGreaterThanOrEqual(HUMANOID.max.y);+ expect(width, `aspect ${aspectRatio}`).toBeGreaterThanOrEqual(bodyWidth);+ // ...and not so far back that the avatar is a speck.+ expect(height, `aspect ${aspectRatio}`).toBeLessThan(bodyHeight * 2.5);+ }+ });++ it('full keeps a wide T-pose inside the frame too', () => {+ const tPose = { min: { x: -0.8, y: 0, z: -0.15 }, max: { x: 0.8, y: 1.7, z: 0.15 } };+ for (const aspectRatio of [0.5, 1, 1.78]) {+ const r = computeFraming({ box: tPose, preset: 'full', aspectRatio });+ const { width } = visible(r, aspectRatio);+ expect(width, `aspect ${aspectRatio}`).toBeGreaterThanOrEqual(tPose.max.x - tPose.min.x);+ }+ });++ it('half and headshot stay tight instead of drifting to a full body', () => {+ const bodyHeight = HUMANOID.max.y - HUMANOID.min.y;+ expect(visible(computeFraming({ box: HUMANOID, preset: 'half' }), 1).height).toBeLessThan(+ bodyHeight * 0.7,+ );+ expect(visible(computeFraming({ box: HUMANOID, preset: 'headshot' }), 1).height).toBeLessThan(+ bodyHeight * 0.35,+ );+ });++ it('clears the subject depth so a deep model never sits behind the camera', () => {+ const deep = { min: { x: -0.2, y: 0, z: -0.6 }, max: { x: 0.2, y: 1.7, z: 0.6 } };+ for (const preset of CAMERA_PRESETS) {+ const r = computeFraming({ box: deep, preset });+ expect(r.position.z, preset).toBeGreaterThan(deep.max.z);+ }+ });+});+describe('computeFraming — aspect ratio scaling', () => {it('narrower viewport pulls the camera further back', () => {const wide = computeFraming({ box: HUMANOID, preset: 'half', aspectRatio: 1.8 });diff --git a/tests/vehicles-trench-car.test.js b/tests/vehicles-trench-car.test.jsnew file mode 100644index 000000000..6a520cde3--- /dev/null+++ b/tests/vehicles-trench-car.test.js@@ -0,0 +1,168 @@+// The Trench Car is the world's default vehicle: ambient traffic drives it and+// it is what a player takes the wheel of at the spawn plaza. Its handling spec+// is hand-measured off the staged GLB, which means the two can drift silently,+// a re-export of the model with a different wheelbase would leave the physics+// chassis, the wheels the player watches turn, and the mesh disagreeing, with+// nothing failing until someone looked at it.+//+// These tests read the real staged asset and hold the shared spec to it, plus+// the two geometry invariants every vehicle type has to satisfy: the chassis+// clears the road, and the driver sits inside the car rather than on its roof.++import { describe, it, expect, beforeAll } from 'vitest';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { NodeIO } from '@gltf-transform/core';+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';+import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';+import {+ VEHICLE_TYPES, VEHICLE_SPAWNS, DEFAULT_VEHICLE_TYPE,+ vehicleSpec, isVehicleType, vehicleRestHeight,+} from '../multiplayer/src/vehicles.js';++const ROOT = path.resolve(fileURLToPath(import.meta.url), '../..');+const MODEL = path.join(ROOT, 'public', 'vehicles', 'trench-car.glb');++// Node bounds in model space, walking the scene so quantization transforms on+// the node chain are applied rather than ignored.+function nodeBounds(node, parent = [1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]) {+ // Only translation + scale appear on these nodes (Blender export + quantize),+ // so a diagonal-plus-offset accumulation is exact here.+ const t = node.getTranslation();+ const s = node.getScale();+ const acc = {+ sx: parent.sx * s[0], sy: parent.sy * s[1], sz: parent.sz * s[2],+ tx: parent.tx + parent.sx * t[0], ty: parent.ty + parent.sy * t[1], tz: parent.tz + parent.sz * t[2],+ };+ let min = [Infinity, Infinity, Infinity];+ let max = [-Infinity, -Infinity, -Infinity];+ const mesh = node.getMesh();+ for (const prim of mesh ? mesh.listPrimitives() : []) {+ const pos = prim.getAttribute('POSITION');+ const pMin = pos.getMinNormalized([0, 0, 0]);+ const pMax = pos.getMaxNormalized([0, 0, 0]);+ const lo = [acc.tx + acc.sx * pMin[0], acc.ty + acc.sy * pMin[1], acc.tz + acc.sz * pMin[2]];+ const hi = [acc.tx + acc.sx * pMax[0], acc.ty + acc.sy * pMax[1], acc.tz + acc.sz * pMax[2]];+ for (let i = 0; i < 3; i++) {+ min[i] = Math.min(min[i], lo[i], hi[i]);+ max[i] = Math.max(max[i], lo[i], hi[i]);+ }+ }+ for (const child of node.listChildren()) {+ const c = nodeBounds(child, acc);+ if (!c) continue;+ for (let i = 0; i < 3; i++) {+ min[i] = Math.min(min[i], c.min[i]);+ max[i] = Math.max(max[i], c.max[i]);+ }+ }+ if (!Number.isFinite(min[0])) return null;+ return { min, max, centre: min.map((v, i) => (v + max[i]) / 2), size: max.map((v, i) => v - min[i]) };+}++const IDENTITY = { sx: 1, sy: 1, sz: 1, tx: 0, ty: 0, tz: 0 };++describe('Trench Car model + handling spec', () => {+ let wheels; let bodyOnly;++ beforeAll(async () => {+ await Promise.all([MeshoptDecoder.ready, MeshoptEncoder.ready]);+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS).registerDependencies({+ 'meshopt.decoder': MeshoptDecoder,+ 'meshopt.encoder': MeshoptEncoder,+ });+ const doc = await io.read(MODEL);+ const nodes = doc.getRoot().listNodes();+ // Same rule src/game/vehicle-model.js applies at runtime.+ const wheelNodes = nodes.filter((n) => /^wheel/i.test(n.getName() || ''));+ wheels = wheelNodes.map((n) => nodeBounds(n, IDENTITY)).sort((a, b) => b.centre[2] - a.centre[2]);+ const bodyNode = nodes.find((n) => /^car body$/i.test(n.getName() || ''));+ const bodyMeshNode = bodyNode.listChildren().find((c) => c.getMesh() && !/^wheel/i.test(c.getName() || ''));+ bodyOnly = nodeBounds(bodyMeshNode, IDENTITY);+ });++ it('stages an optimized asset, not the 16 MB gallery master', async () => {+ const { size } = await import('node:fs').then((fs) => fs.statSync(MODEL));+ expect(size).toBeGreaterThan(0);+ expect(size).toBeLessThan(4 * 1024 * 1024);+ });++ it('exports exactly four wheels the runtime can steer and roll', () => {+ expect(wheels).toHaveLength(4);+ });++ it('matches the handling spec it was measured from', () => {+ const spec = VEHICLE_TYPES.trench;+ // Body box: the collider the world is driven against. Height is measured+ // road-to-roof (the underbody floats above the asphalt on its wheels), so+ // the collider wraps the whole visible car rather than its AABB alone.+ expect(bodyOnly.size[0]).toBeCloseTo(spec.dims.w, 1);+ expect(bodyOnly.max[1]).toBeCloseTo(spec.dims.h, 1);+ expect(bodyOnly.min[1]).toBeGreaterThan(0);+ expect(bodyOnly.size[2]).toBeCloseTo(spec.dims.l, 1);++ // Wheel radius and track, read off the tyres themselves.+ const radius = wheels[0].size[1] / 2;+ expect(radius).toBeCloseTo(spec.wheel.radius, 1);+ const halfTrack = spec.dims.w / 2 - spec.wheel.inset;+ expect(Math.abs(wheels[0].centre[0])).toBeCloseTo(halfTrack, 1);++ // Wheelbase: +z is forward, so the first two are the steered pair.+ expect(wheels[0].centre[2]).toBeCloseTo(spec.wheel.frontZ, 1);+ expect(wheels[3].centre[2]).toBeCloseTo(spec.wheel.rearZ, 1);+ });++ it('rests its wheels on the road, so the model sits at the physics ride height', () => {+ // The GLB is authored with its contact patch at y=0, and the mesh is dropped+ // by vehicleRestHeight into chassis space. The wheel centres must then land+ // exactly one radius above the road, or the car floats or sinks.+ const restHeight = vehicleRestHeight('trench');+ for (const wheel of wheels) {+ expect(wheel.centre[1] - restHeight).toBeCloseTo(-restHeight + VEHICLE_TYPES.trench.wheel.radius, 1);+ expect(wheel.min[1]).toBeCloseTo(0, 1);+ }+ });+});++describe('vehicle fleet invariants', () => {+ it('resolves the Trench Car as the default type', () => {+ expect(DEFAULT_VEHICLE_TYPE).toBe('trench');+ expect(isVehicleType('trench')).toBe(true);+ expect(vehicleSpec('trench').label).toBe('Trench Car');+ // An unknown or blank type must not fall back to some other car.+ expect(vehicleSpec('').id).toBe('trench');+ expect(vehicleSpec(undefined).id).toBe('trench');+ });++ it('parks the default car where a new player lands', () => {+ const plaza = VEHICLE_SPAWNS.filter((s) => s.id.startsWith('veh-plaza-'));+ expect(plaza.length).toBeGreaterThan(0);+ for (const spawn of plaza) expect(spawn.type).toBe('trench');+ // Every spawn still names a real type, or the server silently drops it.+ for (const spawn of VEHICLE_SPAWNS) expect(isVehicleType(spawn.type)).toBe(true);+ });++ it('keeps every chassis collider clear of the road', () => {+ // PhysicsWorld.createVehicle offsets the chassis cuboid by -0.3 * (h/2), so+ // its underside sits 1.3 * (h/2) below the body origin. If that reaches the+ // ground the hull's own friction pins the car and no engine force moves it,+ // the bug the coupe/sedan/pickup suspension comments document.+ for (const [id, spec] of Object.entries(VEHICLE_TYPES)) {+ const clearance = vehicleRestHeight(id) - 1.3 * (spec.dims.h / 2);+ expect(clearance, `${id} chassis clearance`).toBeGreaterThan(0.1);+ }+ });++ it('seats every driver inside the car', () => {+ // seat.y is the offset from the chassis centre to the driver's feet. Land it+ // between the road and the roofline: above is the standing-on-the-roof bug,+ // below buries the driver under the asphalt.+ for (const [id, spec] of Object.entries(VEHICLE_TYPES)) {+ const feet = vehicleRestHeight(id) + spec.seat.y;+ expect(feet, `${id} seat height`).toBeGreaterThan(0);+ expect(feet, `${id} seat height`).toBeLessThan(spec.dims.h * 0.75);+ // Driver's side, not the middle of the bench.+ expect(Math.abs(spec.seat.x), `${id} seat offset`).toBeGreaterThan(0.2);+ }+ });+});