UHT Milk Plant Simulation
A browser-based 3D simulation of a UHT milk plant in three.js, from standardization to ambient distribution: ten stages running live, six fault scenarios, and a guided tour. The research, design and schedule are in plan/; the build is split into phases and agents in plan/agent-plan/.
Live: https://sophanit-keo.github.io/simulation-milk-process/, deployed to GitHub Pages from master each time CI passes there. It needs a browser with WebGL 2; it is checked in Chrome and Edge.
Use it
- Pick a stage in the list on the left, or click a machine in the 3D view: the panel on the right explains it and shows its live values. Drag to orbit, scroll to zoom, Esc for the whole plant.
- The end of the line (stages 8 and 10, best at ×1 or ×10): the palletizer robot picks each tray off the belt and stacks it layer by layer, the stretch wrapper winds film round each pallet, one forklift puts released pallets away into the racks and the other loads the docked truck, and trucks back up to the dock articulated, open their doors, fill and drive off (D22, phase 12).
- Time: pause and the speeds ×1 to ×10,000 in the top bar (Space and the keys 1–5); "Next event" jumps to the next thing that happens.
- Scenarios (top bar): start any of the six faults, reset them, or read the scenario log, which tells what happened and why.
- Report in Let Report (on a fault's banner and in the scenario log): opens Let Report, the QC/QA trouble-report app, in a new tab, with its new-report form filled in for that fault: category, severity, product and what happened (D18). You sign in, sign and send it there; the simulation writes nothing to Let Report itself.
- Tour (top of the stage list): the ten stages in about 3 minutes.
- About (next to the title): what the model is and isn't, and its sources.
- Factory (next to About): the factory board,
factory.html. Sign in with a Let Report account to see the real factory live: UHT 1, 2 and 3, the lines each one feeds, and each line's status, product, lot, CIP and open troubles, as Let Report holds them. A change in Let Report shows within a second (D19, phase 9). Which UHT feeds a line, its filler, speed and pack size are edited in Let Report.
- 3D (on the board, next to Board): the same factory on a floor in 3D: each UHT plant with its aseptic tank and its lines' fillers, packs riding the running lines' belts and milk flowing in their pipes, with the board's lamps and words. Click a machine or its label to fly to it and mark its card, or "Show in 3D" on a card; Esc for the whole floor.
factory.html#3d opens it (D20, phase 10).
The plant opens the same way every time: day 8 at 06:00, ×10, seed 81006. URL options: ?mock runs the UI on the mock snapshot, ?debug adds lil-gui and window.__scene, ?greybox shows the grey boxes instead of the hero models.
Run it
Needs Node 22.13 or later (22.x LTS or 24.x; see .nvmrc).
npm ci
npm run dev # http://localhost:5173
npm run build # production build in dist/ (CI sets BASE_PATH=/simulation-milk-process/ for GitHub Pages)
npm run preview # serves dist/
Test it
npm run check # typecheck, lint, unit tests (Vitest) and asset tests: what CI runs first
npm test # unit tests only: formulas, acceptance runs, the 60-day run, scenarios, the demo script
npm run test:assets # the 3D models and textures against their specs and budgets
npm run e2e # browser tests (Playwright, Chromium); `npx playwright install chromium` once
Performance (needs a build, see tests/perf/baseline.md):
npm run build
node tests/perf/measure.mjs # draw calls, triangles and fps at every stage
node tests/perf/measure.mjs --path 60 --headed --channel chrome # the 60 fps check: a 60 s camera path at ×1 and ×10,000
Documents
Layout
| Path | What | Owner agent |
|---|
src/contracts/ | Types every part shares: PlantConfig, Snapshot, Command, ViewEvent, units | lead |
src/data/plant.json | Default settings; decisions in plan/DECISIONS.md | process |
src/sim/ | Simulation core: clock, event queue, models, fault scenarios. No three.js, no DOM | sim |
src/scene/ | 3D view | scene |
src/ui/, src/styles/, index.html | Screen layout and controls | ui |
public/models/, assets/ | 3D assets and their licences | assets |
factory.html, src/factory/ | The factory board: contracts (types.ts, view.ts), the Let Report client, the model, the floor's layout, the page; no three.js until its 3D view (src/factory/scene/) opens | lead, factory-client, factory-model, factory-scene, factory-ui |
tests/, e2e/ | Unit and browser tests, and the perf check | qa |
docs/ | Report, demo and video scripts, slides | lead, process |
The agents' definitions (phases 9 to 12) are in .claude/agents/.
