/machine-skill

name: machine
description: Turn one line ("a turbofan jet engine", "a mechanical watch", "an LVAD heart pump") into a photoreal, physics based, interactive 3D simulation of that machine in a single HTML file, plus a 20 to 30 second film to post it. Real proportions in metres, real materials (PBR metals, paints, polymers, glass), studio lighting with soft shadows, moving parts driven by a small solver that computes real numbers (thrust, torque, rpm, flow, pressure, efficiency), and modes to explode it, cut it open with clean section caps, x-ray it, slow it down, label it and break it. Use this whenever someone asks to build, simulate, visualise, explain or "show how X works" for any machine, engine, mechanism, device, instrument or piece of hardware, wants an interactive 3D model or a cutaway, or wants a video of a machine for a post, even if they never say "simulation" or "three.js".

Machine Skill

You build a machine the way a product studio photographs one and an engineer explains one: the real thing at its real size, in real materials, on a clean studio set, running on real equations. One line in, one HTML file out, and a film in one command.

The output is always:

1. `<name>.html`: a single self contained page (three.js 0.170 from jsDelivr, the kit inlined). It opens from disk, from any static host, or inside an iframe. 2. A film: `node scripts/record.mjs <name>.html out/<name>.mp4 --music freepd:<Category>/<Name>`.

Open `examples/` first. Every example was made from the one line at the top of its page. `examples/turbofan.html` is the reference: read it end to end before you write anything.

The bar

Before you start, picture the frame a viewer sees after three seconds. It must already look like a studio product photograph of the real machine: correct silhouette and proportions, metal that reads as metal, a soft shadow on a paper floor, nothing floating, nothing clipping, nothing placeholder. Then it moves, and every number on screen is computed.

A result is not done while any of these is true:

• a part a mechanic would expect is missing (no fuel nozzles in a combustor, no escapement in a watch, no valves in an engine)
• something floats, intersects, or has a visible seam or gap at a joint
• a material looks like plastic when it should be metal, or everything is one grey
• a number on screen is typed in rather than computed by the solver
• the cutaway shows hollow shells instead of solid section faces
• the first frame of the film is not beautiful

Workflow

1. Research the real machine (5 minutes, no code)

Write down, in a comment block at the top of the machine script, from what you know (and the web if you have it):

• **The real dimensions** in metres of the 5 to 10 parts that define the silhouette (a turbofan: fan diameter 2.85 m, length 4.9 m, nacelle max diameter 3.44 m).
• **The parts list** in assembly order, each with its material. Aim for 15 to 40 named parts; repeated parts (blades, teeth, bolts, coils) count individually.
• **The physics** that makes it work, as 3 to 6 equations you will actually compute, with real constants and the operating point (a turbofan: Brayton cycle, take-off at N1 100 %, OPR 42, T4 1,750 K, about 330 kN).
• **The one number** a viewer cares about: the hero (thrust, torque, beats per hour, flow, power). It gets a huge serif readout and a thin bar.
• **The input** a viewer wants to drive: one slider (throttle, wind speed, rpm, pump speed, grind size).
• **The break**: the failure an engineer worries about, and what the solver says happens (fan blade off and the imbalance load, valve float above the redline, a stalled pump, overpressure). This must be a computed consequence, not an animation.

2. Build the page from the template

Copy `kit/template.html` to `<name>.html`. It has the import map (pinned three@0.170.0), the fonts, a marked block where the kit goes, and the four sections you fill in:

const { THREE, Lab, MAT, GEO, heatGlow, clamp, lerp, approach, fmt } = window.LabKit
const lab = new Lab({ prompt, no, title, sub, size, view, cut })   // 1. the lab
// 2. the parts      lab.mesh(GEO..., MAT..., { name, pos, explode, xray, count })
// 3. the solver     lab.hero(...); lab.slider(...); lab.onTick((dt, lab) => { ... lab.setHero(...) })
// 4. break, explain, film      lab.breakIt(...); lab.how(...); lab.autoFilm(...); lab.start()

Right after copying, run `node <skill dir>/scripts/inline.mjs <name>.html`: it pastes the kit into the marked block so the page is one self contained file wherever it lives (the template's `src="../kit/lab-kit.js"` only resolves inside this repo). Then write your machine in the second script block.

3. Geometry: real solids at real size

Work in metres in the machine's own frame, Y up, the floor at y = 0 unless you set `ground`. Set `size` to the longest real dimension; the kit scales the display so every machine sits the same on the set, and the scale bar shows real size.

• **Round parts** (shafts, discs, casings, nozzles, cones, spinners, pistons, bezels): `GEO.lathe([[r, y], ...])` with a CLOSED profile. Walls: `GEO.shell(profile, thickness)`, tubes: `GEO.tube(rOut, rIn, h)`, chamfered discs: `GEO.disc(r, h)`. Corners stay crisp and curves shade smooth automatically.
• **Blades and vanes**: `GEO.rotor({ count, axis, r0, r1, chord, thick, camber, twist, pitch, sweep })` builds real cambered, twisted airfoils (NACA thickness) as closed solids and rings them. Use `[root, tip]` arrays for chord, thick and camber.
• **Gears**: `GEO.gear({ teeth, module, width, bore, helix, spokes, rim })`. Mesh two gears at centre distance `(z1 + z2) * module / 2` and turn them at the inverse tooth ratio, offset by half a tooth.
• **Pipes, hoses, wires**: `GEO.pipe(points, r)` (closed, capped). Route them along the structure from port to port, never through a part.
• **Fasteners**: `GEO.bolts(n, R, size, h)` on every flange. Springs: `GEO.spring(R, wire, turns, len)`. Boxes: `GEO.rbox(w, h