deepgrain-foundry/docs/PROJECT_MAP.md

Project map

Where everything is and how the parts connect. The index at the end lists every source file in build order, with its top-level functions and variables. It is generated: run python3 tools/map.py after adding, moving or renaming files or top-level functions. Edit this top part by hand when the structure changes.

Layout

AGENTS.md, CLAUDE.md  instructions for coding agents (local only, not in git)
tasks/, .kandown/     the owner's to-do list: a kandown board (docs/kandown.md; local only, not in git)
build.py              joins src/ into dist/index.html (one self-contained page)
src/manifest.json     the build order: simulation files, then browser files
src/shell.html        page markup (HUD, menus, dialogs); CSS and JS are put in at the markers
src/styles/           base styles and the dev console panel
src/sim/              the simulation. No DOM. The headless tests load only these files.
src/render/           drawing: WebGPU pixel and smooth looks, rare CPU overrides and overlays
src/ui/               the browser shell: input, HUD, build menu, notebook, settings, saves,
                      audio, the frame loop
test/                 headless suites (t_*.js) and their harness; browser tests (play.py,
                      t_smooth.py, t_dev_console.py, t_caps.py, firefox_smoke.py); run_all.py
tools/                serve.py (build, serve, rebuild on change), server.py (isolated HTTP), shot.py (screenshots),
                      browser.py (shared launch/GPU choice), caps.py (capability report),
                      where.py, map.py, perf.py, playthrough.py, use_venv.py (switches browser
                      scripts to .venv), scenes/ (screenshot setups), experiments/
                      (measurements and reports)
docs/                 this map, DESIGN.md, TESTING.md, systems/ (notes per system),
                      history/ (the owner's requests), agent-log.md
dist/, shots/         build output and screenshots (not committed)

The dev console pairs src/sim/devconsole.js (headless command dispatch, mark, log and runtime controls) with src/ui/devconsole.js (confirmation and bottom panel). Save metadata keeps dev and the last 200 devLog entries; free building, speed and dev pause reset on load. The frame loop applies speed and queued steps while keeping the per-frame tick limit.

How it runs

• One script. All files share one global scope; there is no import/export.
  • A function may call functions in any file.
  • Top-level const/let must be declared before top-level code that uses it at load time. That is why the manifest order matters: sim, then render, then ui.
  • 'use strict' at the top of src/sim/base.js covers everything.
• The frame loop (frame in src/ui/loop.js):
  1. read input;
  2. run up to SET.maxSteps simulation ticks, at 60 ticks a second of game time (none while paused);
  3. draw the world (drawWorld) and the overlays;
  4. update the HUD.
• One tick (simTick in src/sim/tick.js), in this order:
  • update the sky roof line (every 20 ticks);
  • weather, machines (including belts and screw conveyors), pipes, drill pulses;
  • bars (entTick) and grains in flight (flyTick);
  • falling sand (simMove), then heat (heatPass);
  • every so often: molds, milestones, plants, cold, tree support;
  • the dock, the market and orders, saplings;
  • the bot building ghosts.
• Events. The simulation reports what happened with emit({ t: ... }). drainEvents (src/ui/events.js) turns each event into sounds, toasts and cards.

The world (src/sim/world.js)

• The grid is W × H grains; cell i = y * W + x. Worlds are 2048×1024, 3072×1280 or 4096×1536.
• Per-cell typed arrays:
  • mat: material id;
  • temp: °C;
  • flags: F_NAT natural rock, F_CAST, F_BURN burning;
  • stamp: moved this tick;
  • part: which built part a cell belongs to (P_*: screw conveyor directions, grate, open gate, filter, pipe...);
  • mach: machine id;
  • digp: drill damage;
  • occ: covered by a bar;
  • bgm: the background layer (trees);
  • also life, netId and noiseB.
• Blocks: the 4×4-grain build grid (BS = 4). blockP holds the piece code (BP_*) and blockV the variant (direction, wall material, flags) of each block, over BW × BH.
• Chunks of 32×32 grains. awake marks chunks where things move and hot where heat flows; only those are simulated. setCell wakes what it touches; after writing arrays directly, call wakeXY / wakeHeatXY.
• Other state:
  • fog: exploration at one cell per 2×2 grains; see fog;
  • machines: index = machine id; removed ones are null. Each is { type, x, y, w, h, dir, on, ... }. Its footprint is hull cells (solid) and void cells (open inside).
  • molds;
  • ents (bars, 4×2 grains, with their own physics);
  • flyers (grains in the air: blown, off belt ends, out of screw conveyor mouths, rain);
  • pipeNets;
  • ghostBlocks, ghostMachines, ghostMolds.
• Player: bot (position), bag (count per material), player (bit and tank tier, lens, flask), ledger (milestones reached), stats, money, debt, orders.

Materials (src/sim/materials.js)

• Ids are constants (EMPTY = 0 to BARSB = 94, NMAT = 95). They are stored in saves: never renumber them, only add new ones at the end.
• def(id, {...}) sets each material's properties:
  • ph (phase), col, dens;
  • k (heat conduction), cap;
  • hard (which bit can break it), yld (what it breaks into);
  • melt / meltTo, freeze / freezeTo, boil / boilTo;
  • ign, flame, fuel, burnTo;
  • bag (can be carried), desc (the text players read). These are copied into per-material typed arrays (PH, DENS, KC...).
• Phases: PH_SOLID holds, PH_POWDER falls and piles, PH_LIQUID, PH_GAS, and PH_ITEM (bars, which are ents, not cells).
• Naming:
  • ...V: ore vein (solid);
  • ...ORE: loose ore;
  • M...: molten;
  • SCR...: scrap;
  • BAR...: bar;
  • R...: rubble (RSTONE);
  • L...: loose (LDIRT, LCLAY, LWOOD).

Building

• PIECES (src/sim/pieces.js) lists everything buildable:
  • kind block (a code BP_*);
  • kind machine (bw × bh blocks);
  • kind mold. hidden pieces are not in the menu. The menu's tabs and order are BUILD_CATS in src/ui/build-menu.js.
• Transport geometry: joins.js owns travel-directed ends and mutual joins for belts, filters and screws. pieceEnds(code, v) returns precomputed geometric left/right ends (vertical screws: up/down), with travel and inlet/outlet roles. endJoin(bx, by, endIndex, planned = null) returns neighbourBlock * 2 + neighbourEnd, or -1; pieceJoins returns bits 0/1. Plans override world blocks, including the queried block. Outlets target the next block along travel, with the belt surface exceptions. Inlet ties prefer same-shape travel, then top-to-bottom, left-to-right; a join must be reciprocal. Both looks, ghosts, previews, diagonal screw grain/bar transfers and straight screw entry into diagonals share this rule. Flat-belt bar entry uses entBeltScrewEnter and the swept-path collision check. Straight screw side-feeding into lifts remains independent. Edge elbows bend inside the diagonal; diagonal outlets bend inside the receiving straight block.
• Placing and removing:
  • placeBlock / removeBlock (blocks.js);
  • placeMachineAt / addMachine / removeMachine (actions.js, machines.js);
  • addMold / removeMold (molds.js);
  • removePieceAt (actions.js) takes back whatever is at a cell;
  • interactAt (actions.js) is the F key.
• Ghosts are what a paste or an out-of-reach drag leaves. The bot builds them from the bag (ghostTick in undo.js).
• Undo: undoRecord(label, fn) wraps one player action; the place and remove functions record their own steps with undoNote(op).
• Blueprints (blueprints.js): copyRegion, cutRegion, flipBlueprint, pasteGhost.

Drawing

Both looks require WebGPU. cell.js colours rare built geometry and objects.js adds bars, flyers and blueprint ghosts. The GPU canvas sits behind the transparent overlay canvas.

• gpu/device.js compiles every pipeline asynchronously at startup, submits both looks during world loading, and handles one device recreation followed by an autosaved Reload notice.
• gpu/textures.js owns world/view textures and bindings; gpu/uploads.js merges dirty 32x32 chunks into horizontal strips, retaining clean chunks across camera moves. Simulation writes mark renderDirty in sim/world.js; hot chunks include the conduction halo.
• gpu/colour.js colours plain grains. Smooth uses a second pass for its four outputs so no pipeline exceeds four storage textures. gpu/cracks.js supplies drill contour shading.
• gpu/light.js computes sky, heat emission, lamp and light propagation. No CPU light sweep.
• gpu/shaders.js provides pixel upscaling and bloom. gpu/smooth*.js shapes smooth grains, field AO and glow; gpu/surface.js caches the parallax horizon.
• Smooth classes are set in cell.js: 4 crisp built piece, 6 wall tile, 7/8 belt, 9–12 screw, 13/14 filter, 19–22 diagonal screw, 23–30 slope belt/filter, 31/32 slope sidewall and cleats. diagonal-screws.js and slope-belts.js share the simulation join geometry with pixel colours, smooth tags, ghosts and previews.

The browser shell

• GAME (src/ui/state.js) holds the UI state: tool, selected piece, build tab, drag, clipboard, paste mode, overlays. SET holds the settings, kept in localStorage.
• Saves:
  • worlds are kept in IndexedDB (src/ui/saves.js);
  • world files can be exported and imported;
  • serializeWorld / deserializeWorld (src/sim/save.js) do the conversion and migrate older saves.

Where to find...

What	Where
Material properties and descriptions	src/sim/materials.js (def)
Prices, orders, the dock	src/sim/economy.js
Piece costs and descriptions	src/sim/pieces.js (PIECES)
Build menu tabs, tiles, status and hover popup	src/ui/build-menu.js
Key bindings	src/ui/input.js (keydown); what they do: src/ui/actions.js
Mouse building and dragging	src/ui/actions.js (primaryPress, primaryRelease, secondaryPress, toolTick)
Cursor previews (ghosts, drill aim, selection box)	src/ui/previews.js
Controls help text	src/ui/notebook.js (controlsHtml)
Cached vein membership, ore identification and label timing	src/ui/cursor.js
Hover info and discovery cards	src/ui/info.js
Milestones	src/sim/progress.js (MILESTONES), checked in src/sim/ledger.js
Starter furnace designs	src/sim/progress.js (STARTER_DESIGNS, smelterBlueprint)
Falling sand, liquids, gases	src/sim/cells.js
Heat, melting, fire, reactions, alloys, steel	src/sim/heat.js
Belts, filters, screw conveyors	src/sim/conveyors.js, src/sim/slope-conveyors.js (uphill cleat barriers and screen nudges), src/sim/machine-tick.js
Fans	src/sim/machine-tick.js (fanBlow)
Refiner, Stone cutter, Silo	src/sim/processors.js
Pipes, pumps, outlets	src/sim/pipes.js
Molds and casting	src/sim/molds.js
The drill	src/sim/drill.js; reach in src/sim/tools.js
Vacuum and blowing	src/sim/vacuum.js
Trees and saplings	src/sim/nature.js
Weather	src/sim/weather.js
World generation	src/sim/worldgen.js
Save format and migrations	src/sim/save.js
Machine drawing (silo, refiner...)	src/render/machines.js
Smooth-look shader	src/render/gpu/smooth-shader.js
Settings screen	src/ui/settings.js (settings and defaults: SET in src/ui/state.js)
Sound and music	src/ui/audio.js

Index of source files (build order)

src/sim/base.js (24 lines)

Deepgrain Foundry: simulation core (src/sim/). No DOM anywhere in src/sim/: plain data and functions, so the headless tests can run it and the layout can be ported to Rust later. This file: the random number generators and the phase ids every material has.

• functions: rnd, mulberry32, hash2
• variables: RS, PH_EMPTY, PH_SOLID, PH_POWDER, PH_LIQUID, PH_GAS, PH_ITEM

src/sim/materials.js (119 lines)

Material definitions: ids, properties and metal families. ids, and drill/tank tiers.

• functions: def, metalFamily
• variables: EMPTY, GRASS, DIRT, LDIRT, SAND, GRAVEL, CLAY, STONE, GRANITE, BASALT, NMAT, MD, FIRETO

src/sim/material-tables.js (54 lines)

Material tables: typed properties, casting groups, flags, parts and tool tiers. Typed property tables

• variables: PH, DENS, KC, ICAP, CASTMETAL, METAL_TIER, SOLIDMETAL, F_NAT, F_CAST, F_BURN, P_NONE, P_SCREW_U, P_SCREW_D, P_SCREW_L, P_SCREW_R, P_GRATE, P_GOPEN, P_WHEEL, P_INTAKE, P_FILTER, P_PIPE, P_SCREW_UR, P_SCREW_DR, P_SCREW_DL, P_SCREW_UL, SCREW_PARTS, SCREW_DIRS, IS_SCREW, SCREW_DX, SCREW_DY, BIT_TIERS, TANK_TIERS, REACH

src/sim/pieces.js (179 lines)

Everything the player can build (PIECES): blocks, machines and molds, with costs and descriptions; filter settings; wall materials and their cost.

• functions: isSlopeBelt, isFilter, isBelt, beltGrade, slopeShape, beltFaceY, filterVariant, beltDirection, isSlope, isWall, slopeCell, slopeCode, isPipeCode, lineOnly, filterable, cleanFilterCfg, filterRec, filterPassAt, filterInfo, sameFilter, wallCost
• variables: BS, BP_WALL, BP_BELT, BP_SCREW, BP_SHAFT, BP_GRATE, BP_GATE, BP_FILTER, BP_PIPE, BP_PUMP, BP_OUTLET, BP_GRIND, BP_SAW, BP_PRESS, BP_RACK, BP_SLOPE_BL, BP_SLOPE_BR, BP_SLOPE_TL, BP_SLOPE_TR, BP_BELT_UP, BP_BELT_DOWN, BP_FILTER_UP, BP_FILTER_DOWN, filterCfg, WALL_OF, WALL_LIST, BAR_OF, GRAINS_PER_BAR, POWER_FREE, CASH, PIECES, PIECE_BY_ID, PIECE_BY_CODE, BELT_POWER, SCREW_POWER, FAN_POWER, WHEEL_K, ENGINE_K, MOLDS

src/sim/economy.js (152 lines)

Money, prices, market saturation, the trade dock, buyer and builder orders.

• functions: saleAs, priceFactor, priceNow, sellUnit, marketTick, resetEconomy, payClaim, dock, inDock, dockTick, sellToDock, standing, makeBuildersOrder, makeOrder, ordersTick, completeOrder, placeDock
• variables: money, debt, earned, CLAIM_DEBT, PRICE, SAT_K, SAT_FLOOR, SAT_HALF, mkRecent, shipLog, saleAcc, floatAcc, orders, ordersDone, nextOrderT, orderSeq, ORDER_SLOTS, STANDING, BUILD_GOODS

src/sim/progress.js (48 lines)

Starter furnace designs and the milestone list shown in the notebook.

• functions: smelterBlueprint
• variables: STARTER_DESIGNS, MILESTONES

src/sim/world.js (123 lines)

World state: the per-cell typed arrays, alloc(), ambient temperature by depth, waking.

• functions: emit, bagCap, discover, sharedArray, alloc, depthU, depthY, meanSurface, computeAmbient, fillNoise, renderDirtyXY, renderDirtyChunk, renderDirtyIdx, wakeXY, wakeHeatXY, wakeIdx, wakeHeatIdx
• variables: W, H, N, CW, CH, NCH, mat, temp, life, flags, stamp, part, mach, digp, noiseB, airS, netId, isPow, occ, surfY, dirtY, graniteY, basaltY, magmaY, roofY, AMB, worldSeed, surfBase, underD, shallowD, lapse, BW, BH, NB, blockP, blockV, ents, bgm, flyers, ghostBlocks, ghostMolds, renderDirty, awake, hot, hotLvl, powderArea, roofDirty, loadWakeOrder, loadWakePending, loadWakeIndex, tick, tickStamp, machines, molds, nets, pcells, powerDirty, beltL, beltR, screwLists, brokenMachines, ghostMachines, ghostBlocked, EV, bot, bag, bagTotal, player, seen, ledger, stats

src/sim/fog.js (52 lines)

Exploration only: never changes grains or the random stream.

• functions: fogAlloc, fogMark, fogSeen, fogInit, fogLook, fogRevealAround, fogRevealAll
• variables: FOG, FOG_SENSE, FOG_SENSE_FADE, fog, FW, FH

src/sim/cells.js (223 lines)

Cell helpers (setCell, move, enter) and the falling-sand movement of powders, liquids and gases (simMove).

• functions: setCell, swapCells, swapCellData, move, enter, enterFree, powder, passable, liquid, liquidSearch, gas, wakeBotPowder, simMove, moveChunk
• variables: SORTP, SORTP_FUEL, LSTEP, LFILM, CORNER_SEAL

src/sim/heat.js (266 lines)

Heat: conduction, melting and freezing, reactions, fire and air, steel.

• functions: curAir, airflowAt, alloyMix, airy, hasO2, condPair, heatPass, heatChunk, neighborDir, react, char, quench, burningNear, burn, steelCheck
• variables: POROUS, SOIL, HOTLIQ, REACT_MIN, ALLOY

src/sim/machines.js (157 lines)

Machines: the power network, footprints, placing and removing machines.

• functions: markPow, partLost, rebuildPower, netSat, evictCells, cellBuildable, machineFootprint, canPlaceMachine, addMachine, removeMachine
• variables: nextPowerBuild

src/sim/processors.js (113 lines)

Processing: Grinder and Saw blocks, and the Silo.

• functions: isProcCode, rebuildProcessors, procBottom, procSlot, procFeed, procBlocksTick, siloTick, siloFull
• variables: REFINE, REFINE_SAND, CUT_PER_BRICK, SAW_CUTS, procState, procBlocks, procDirty, SILO_CAP, SILO_RATE

src/sim/racks.js (56 lines)

Each rack block owns its bars; only the bottom of a column releases them.

• functions: newRack, rackTop, rackBottom, rackPush, rackShift, rackIntake, rackRefill, rackTick
• variables: RACK_CAP, rackState

src/sim/pipes.js (114 lines)

Pipes, pumps and outlets: each joined line holds one liquid as a count, not as grains.

• functions: sideOf, pipeClosedSide, pipeJoins, rebuildPipes, pipeNetOf, pipeTakeShare, faceCell, pumpDraw, outletPour, pipesTick
• variables: PIPE_CAP, PUMP_RATE, OUTLET_RATE, PUMP_MAX_T, SIDE_V, PUMP_V, OUTLET_V, pipeNets, pipeNetAt, pipesDirty

src/sim/machine-tick.js (157 lines)

Per-tick machine work: steam engines, fans, belts, filters, screw conveyors (machinesTick).

• functions: engineIntake, fanBlow, machinesTick

src/sim/joins.js (125 lines)

Travel-directed transport ends. Precomputed probes; world/plan queries allocate nothing. End indices stay geometric: left/right, or up/down for vertical screws.

• functions: pieceEnds, joinCandidate, endJoin, pieceJoins, endAt, joinIsDrop, joinSnap, nearMiss
• variables: JOIN_ENDS, NO_PIECE

src/sim/conveyors.js (213 lines)

How belts, filters and screw conveyors move what is on or in them. What rests on a belt or filter rides along: the whole stack standing on the carrying surface steps one cell toward d together (belts run front of the line first, so the way ahead is clear). If a powder grain is blocked, the load above it stands still and the belt slips underneath. A filter's own material drops through it instead, unless it is already full.

• functions: conveyorStep, carryColumn, beltDrain, launchGrain, rebuildFilters, filterCarry, carryBeltsAndFilters, setFilter, filterRun, roomFor, screwSpread, screwIntake, screwAccepts, straightScrewNext, diagonalScrewNext
• variables: CARRY_DEPTH, filterR, filterL, filtersDirty

src/sim/flow.js (26 lines)

Throughput for the info overlay (t49): how many grains each belt, filter and screw conveyor block hands on, per second of game time. Counting runs only while the overlay is on, so normal play pays one flag check per carried grain. Bars are not counted.

• functions: setFlowCounting, flowNote, flowCross, flowSlopeUnder, flowTick
• variables: flowOn, flowCount, flowRate

src/sim/slope-conveyors.js (231 lines)

Cleats are rubber ribs standing up from a sloped belt's face, one every CLEAT_SPACING face cells. Loose grains treat them as solid (cleatMask). Nothing grips the bare face: grains slide down it until a cleat stops them. Each belt step moves every cleat one face cell along the belt, and the rib pushes whatever is in its way ahead of it, so the pocket in front rides along while anything heaped above the rib is left to roll back. If a rib can't push its way, its whole run stalls. Only uphill runs have cleats: downhill, the belt carries its load like a flat one.

• functions: ribMove, cleatFoot, ribCells, slopeUphill, slopeFaceAt, pushRow, scoop, pocketRoom, advanceCleat, slopeRunKey, slopeCleatsTick, rebuildCleatMask, expelFromRib, screenNudge, wakeCleatLoad
• variables: CLEAT_SPACING, CLEAT_HEIGHT, CLEAT_REACH, SCREEN_NUDGE_TICKS, cleatChunks, cleatMask, cleatCells, slopePhase, ribLog

src/sim/blocks.js (237 lines)

Building blocks: placing, integrity, removing, lines and rectangles of blocks.

• functions: blockOf, blockCellList, pieceCost, setSlopeSeal, slopeSeal, slopeSealOwner, blockOwnsCell, clearStraySeals, wallCells, canPlaceBlock, placeBlock, blockIntegrity, removeWallCell, removeBlock, diagonalDrag, blockLine, blockRect, blockInReach, blockIs, placeBlocks

src/sim/molds.js (317 lines)

Molds: cavities for castings; ingot troughs empty themselves below. Removal returns set metal.

• functions: moldCellsAt, canPlaceMold, newMoldRecord, addMold, castMix, cavityState, troughState, clearCavity, moldPlugCells, rakeAbove, furnaceJunkHint, unplugMold, ejectIngot, checkMolds, moldAt, tally, collectMold, removeMold
• variables: DROSS, grains, barWord

src/sim/items.js (318 lines)

Bars and other loose objects (ents), and the bag: adding, taking, costs and refunds.

• functions: entSolidCell, entSupportCount, entFreeAt, entMark, spawnBar, removeEnt, entScrewAt, entScrewFree, entScrewMove, entScrewLane, entScrewEdge, entScrewEnter, entScrewTick, entDiagonalScrewTick, entBeltScrewEnter, entSlopeBeltTick, entTick, entsInCircle, bagAdd, bagTake, giveOrDrop, refundAt, canAfford, payCost, fmtMoney, costText, needText
• variables: BAR_W, BAR_H, entCurM, droppedLast

src/sim/tools.js (65 lines)

Tool helpers: reach, brushes, and plain digging.

• functions: setBuildRange, inBuildRange, inReach, forBrush, drillReach, inDrillReach, toolDig
• variables: BUILD_MAX, buildBox

src/sim/drill.js (177 lines)

The resonance drill: tuned pulses that shatter one material.

• functions: drillOrigin, pulseRay, builtCell, toolPulse, crumbleAround, crumbly, shatterCell, pulseTick, pingRadius, resonancePing
• variables: PULSE_W, PULSE_EVERY, PULSE_SPEED, PULSE_K, drillPulses, lastPulseTick, drillWidth, THIN_BONUS, CRUMBLE_MAX, THIN_BONUS_OFF, PING_VEINS

src/sim/nature.js (170 lines)

Trees (background layer), acorns, saplings, and waking freezing water.

• functions: cutTree, treeHeld, findTreeBases, treeSupportTick, woodRoom, treeFall, coldTick, plantTick, setTreeCell, saplingTick, igniteTree
• variables: treeBases, saplings, treeDraw

src/sim/vacuum.js (199 lines)

The vacuum, blowing grains out, grains in flight (flyers), and the flame tool. Material the vacuum would start on at the cursor: a bar, else the nearest loose grain.

• functions: vacuumTargetAt, toolVacuum, nozzle, toolBlow, flyOpen, depositNear, bagTemp, landFlyer, flyTick, toolIgnite
• variables: blowRR, FLY_G, FLY_Q

src/sim/actions.js (92 lines)

Player actions on built things: take back, place a machine or mold, gates, F to interact. Take back whatever piece is at (x,y): machine, mold or block. Returns a message.

• functions: removePieceAt, removePieceAt0, placeMachineAt, placeMoldAt, toggleGateAt, interactAt

src/sim/blueprints.js (105 lines)

Blueprints: copy, cut, flip, cost and paste (as ghosts) a region of built pieces.

• functions: copyRegion, flipBlueprint, bpCost, pasteGhost, cutRegion, footprintBlocker, clearFootprint

src/sim/undo.js (93 lines)

Undo (Ctrl+Z) for building, and the bot building ghosts.

• functions: undoNote, undoPush, undoRecord, undoLast, clearAllGhosts, ghostTick, ghostTick0
• variables: UNDO_MAX, undoStack, undoRec, ghostMissing, ghostIter

src/sim/bot.js (55 lines)

The bot: movement and collision with the world.

• functions: botBlocked, botOverlapSolid, botSlide, botStep
• variables: SLIDE_MAX, SLIDE_STEP

src/sim/ledger.js (54 lines)

Milestone checks (the ledger) and the sky roof line used for cooling.

• functions: checkLedger, updateRoof, updateDirtyRoof, scanRoof

src/sim/weather.js (87 lines)

Weather: clouds from steam, rain and snow, and the world water count.

• functions: wrnd, resetWeather, rainGap, worldWater, absorbSteam, spawnRain, rainAt, weatherTick
• variables: WBAND, WS, weather

src/sim/workers.js (153 lines)

The same chunk schedule runs inline or in workers. Workers only own a pass at a time.

• functions: threadWorld, threadBind, threadContext, resetChunkWork, inlineChunkWork, chunkEvent, chunkWake, chunkHeat, chunkSeed, runChunks, mergeChunkWork, chunkPasses, threadParams, threadSetParams, threadSlot, threadExecute, threadPass, threadWait, threadFailure, threadMessage
• variables: simPool, chunkWork, inlineWork

src/sim/tick.js (29 lines)

simTick: one simulation step, in order.

• functions: simTick

src/sim/worldgen-helpers.js (61 lines)

World generation helpers: noise and removal of tiny hard rock specks.

• functions: makeNoise, fbm, clearHardSpecks
• variables: SPECK_MIN

src/sim/worldgen.js (286 lines)

World generation: staged terrain, ore, caves and placement, with synchronous and async entry points.

• functions: generateWorld, generateWorldAsync

src/sim/devconsole.js (114 lines)

Dev commands are pure simulation operations; the browser owns the panel and confirmation.

• functions: resetDevConsole, enableDevConsole, devMaterial, devCommand
• variables: devWorld, devLog, devFree, devSpeed, devPaused, devSteps, DEV_HELP, DEV_MATERIALS

src/sim/save.js (185 lines)

Saving and loading a world (serializeWorld / deserializeWorld) and old-save migration.

• functions: serializeWorld, deserializeWorld, startLoadWake, wakeLoadArea, wakeLoadNearBot, loadWakeTick
• variables: SAVE_VERSION, TOFF

src/render/setup.js (190 lines)

Drawing (src/render/): browser only. This file: the renderer state R, colour tables (glow, thermal palettes, pipes, trees, sky), canvas setup and the camera.

• functions: glowIndex, thermIdx, pipeCellColor, pipeBodyCell, thinPipeColor, beltLike, buildSky, initRender, resizeRender, viewCells, updateCamera, snapCamera, screenToWorld, worldToScreenPx, renderMonoFont
• variables: R, GLOW_W, GLOW_R, GLOW_G, GLOW_B, THERM, PC, TREE_R, TREE_G, TREE_B, BG, SKY_R, SKY_G, SKY_B

src/render/slope-belts.js (167 lines)

Drawing only: the face stays on its simulation cells; the band hangs below it.

• functions: slopeBeltConnections, flatBeltCaps, prepareSlopeBelts, slopeBeltSegment, slopeBeltCorner, slopeBeltShape, slopeBeltAt, slopeBeltColor, screenLoaded, slopeWallShape, slopeWallAt, slopeDetailAt, slopePreviewCleat
• variables: slopeBeltJoins, slopeBeltHalo, beltCaps, slopeAcross, slopeAlong, slopeDistance, slopeWallOwner

src/render/diagonal-screws.js (79 lines)

Screw casing geometry shared by both looks, ghosts and placement previews. smooth-look class of a screw conveyor cell by direction: 9 up, 10 right, 11 down, 12 left

• functions: diagonalScrewJoins, straightScrewJoins, diagonalScrewShape, diagonalScrewBlock
• variables: SCREW_CLASS, diagonalJoins, diagonalAcross, diagonalAlong, diagonalCap

src/render/cell.js (276 lines)

Rare-cell shading also treats built pieces as transparent surroundings.

• functions: builtForShade, cellPixel

src/render/objects.js (80 lines)

Loose bars, flying grains and queued blueprint blocks in the grain buffer.

• functions: worldObjects

src/render/gpu/cracks.js (79 lines)

The drill's three seeded Perlin contour fields, uploaded once with the material tables.

• functions: gpuCrackTables
• variables: GPU_CRACKS, GPU_CRACK_COLOUR, GPU_CRACK_DRAW

src/render/gpu/colour.js (101 lines)

The plain-cell rules mirror cellPixel; built geometry stays in the CPU override.

• functions: gpuColourShader
• variables: GPU_COLOUR, GPU_COLOUR_SMOOTH

src/render/gpu/shaders.js (42 lines)

Half-resolution separable Gaussian bloom, then nearest colour + linear light.

• variables: GPU_BLUR, GPU_DRAW

src/render/gpu/light.js (143 lines)

GPU sources retain the CPU roof and transmission rules; directional relaxation follows only left/up, then right/down, so it cannot introduce extra light paths.

• functions: gpuLightGrid, gpuLightBindings, gpuLight
• variables: GPU_LIGHT, GPU_LIGHT_SPREAD, GPU_LIGHT_PACK

src/render/gpu/smooth-slope.js (107 lines)

Smooth slope geometry and cleats, ported from slope-belt-shader.js.

• variables: GPU_SMOOTH_SLOPE_HELPERS, GPU_SMOOTH_SLOPE_DRAW

src/render/gpu/smooth-shader.js (368 lines)

Literal port of the legacy smooth shader; dpdy is reversed for WebGPU's top-left origin.

• variables: GPU_SMOOTH

src/render/gpu/surface.js (5 lines)

• functions: smoothSurface
• variables: SM

src/render/gpu/smooth.js (48 lines)

Field mip levels preserve the legacy trilinear AO sample at level 2.2.

• functions: gpuSmoothInit, gpuSmoothTextures, gpuSmoothBindings, gpuSmoothUpload, gpuSmoothMips
• variables: GPU_FIELD_MIP

src/render/gpu/device.js (90 lines)

All pipelines compile during startup; rendering never falls back.

• functions: gpuLimitsOK, gpuInit, gpuFail, gpuRecover, gpuWarmWorld, worldPixelContext
• variables: GPU_LIMITS, GPU

src/render/gpu/textures.js (98 lines)

Whole-world textures retain clean chunks across camera moves.

• functions: gpuTexture, gpuWrite, gpuBuffer, gpuWorldTextures, gpuViewTextures, gpuBindings, gpuUpload

src/render/gpu/uploads.js (48 lines)

Upload full chunks so scrolling within a resident chunk needs no extra copy.

• functions: gpuUploadChunks, gpuUploadStrip, gpuCheckUploads

src/render/gpu/draw.js (92 lines)

Only exceptional blocks and their geometric neighbours run the CPU colour rules.

• functions: gpuOverrideHas, gpuOverrides, gpuDraw, gpuPresent
• variables: GPU_PATTERN

src/render/world.js (46 lines)

Scale colour without changing the smooth-look class.

• functions: fogColor, drawWorld

src/render/machines.js (256 lines)

Machine overlays: fans, engines, silo and the rest, drawn on top of the world.

• functions: cellRect, drawHazardRims, drawMachines, drawProcBlocks, drawSilo, drawSiloPixel, drawSiloWindow, drawRackBlocks

src/render/overlays.js (370 lines)

Other overlays: floating text, rain and snow, flow arrows, filter tags, molds, the bot, particles.

• functions: spawnFloater, drawRain, drawFlowArrows, drawJoinMark, drawJoinMarks, flowLoaded, drawFlowRates, pingImage, drawPing, drawHoveredVein, drawPingRecharge, drawRunOutline, drawFilterTags, drawFloaters, moldLabel, drawMolds, drawBot, spawnDebris, spawnSpark, spawnSuck, drawParticles
• variables: PING_SPEED, PING_HOLD, PING_FADE, PING_BANDS, PING_GLINTS, GLINT_MS

src/ui/audio.js (230 lines)

Audio: chiptune effects and generative music that changes with depth. Everything is synthesized with WebAudio, no samples.

• functions: auInit, auVolumes, rateOk, tone, noiseBurst, sfxPlace, playSfx, auAmbient, mtof, zoneForDepth, scaleNote, musicScheduler
• variables: AU, SFX, SFX_NEAR, SFX_FAR, ZONES

src/ui/state.js (76 lines)

Game shell (src/ui/): browser only. This file: settings, the GAME state object, DOM helpers, toasts and tool status.

• functions: loadSettings, saveSettings, el, esc, rgbOf, fmtT, toast, setStatus
• variables: SET_DEFAULT, SET, TOOLS, ICONS, BAG_ORDER, GAME, keys, hudDirty, $

src/ui/threads.js (39 lines)

Browser transport only; the simulation owns the schedule and shared state.

• functions: startThreads
• variables: threadStarting

src/ui/title.js (77 lines)

Startup capabilities and title art.

• functions: checkCapabilities, renderCapabilityNotice, canStartGame, buildTitleCells, drawTitle
• variables: REQUIRE_WEBGPU, REQUIRE_THREADS, CAPS, CAPS_CHECK, FONT5, TITLE

src/ui/saves.js (224 lines)

Saves in IndexedDB, world files (export / import) and the blueprint library.

• functions: newWorldId, worldWrite, listWorlds, putWorldEntry, worldNewest, deleteWorld, cleanWorldName, renameWorld, migrateWorlds, saveWorld, newestSave, b64FromBytes, bytesFromB64, gz, packBuffers, unpackBuffers, exportWorld, importWorldFile, libLoad, libSave, bpEncode, bpValid, bpDecode
• variables: DB, worldIdTime, worldIdCounter, worldWrites, savingCount

src/ui/claims.js (146 lines)

Shared player state; the world save remains a complete standalone fallback.

• functions: careerState, validCareer, applyCareerState, loadCareer, claimName, openNewClaim, travel, renderClaimsTab
• variables: career, claimBusy

src/ui/session.js (162 lines)

Starting, loading and quitting a game; modal dialogs; the pause menu.

• functions: showLoading, enterGame, setupNewWorld, startNewWorld, startFromSave, loadSavedWorld, quitToTitle, refreshContinue, anyModal, openModal, closeModal, closeAllModals, topModal, dialog, openPause, renderWorlds

src/ui/settings.js (124 lines)

The settings screen.

• functions: openSettings, renderSettings, applySettings, toggleFullscreen, confirmWipe
• variables: SET_TABS, setTab

src/ui/notebook.js (91 lines)

Notebook: tab navigation, ledger, materials, pieces and controls.

• functions: openNotebook, renderNotebook, controlsHtml
• variables: nbTab

src/ui/notebook-market.js (68 lines)

Notebook market: prices, orders, claim payments and wallet.

• functions: fmtClock, orderName, orderLeft, renderMarketTab, fmtPrice, itemsText, renderWallet
• variables: MARKET_GROUPS

src/ui/notebook-blueprints.js (47 lines)

Notebook blueprints: starter designs, saved library and code sharing.

• functions: renderBlueprintTab, copyCode

src/ui/hud.js (40 lines)

The tool hotbar and what is selected.

• functions: renderHotbar, toolId, steering, modShift, grainAt, selectTool, bagMaterials, blowList, blowAllList, blowingAll, piece
• variables: IN_BAG_ORDER

src/ui/build-menu.js (111 lines)

The build menu along the bottom: categories, piece tiles and their icons.

• functions: pieceIcon, catOf, selectBuildCat, cycleBuildCat, buildVariantChips, renderBuildBar, setupBuildBar
• variables: BUILD_CATS, BUILD_ORDER, PIECE_ICONS, lastBuildKey, lastBuildMenu

src/ui/selection.js (133 lines)

Tool selection: cycling, drill tuning, piece variants and costs.

• functions: pieceSize, pieceUsesWall, setDrillWidth, tuneUnderCursor, cycleItem, cycleWall, rotate, toggleBlow, pickFilterUnderCursor, toggleFilterMat, setBrush, pieceV, dragPlan, pieceExtra, filterBlockAt, chipCost, pieceCostNow, pieceCode, turnSlope

src/ui/selection-pickers.js (61 lines)

Selection pickers: filter rules, filter settings and wall materials. What a filter can hold: loose things and bars you have found, plus anything it already holds

• functions: filterChoices, matList, filterParts, filterSentence, applyFilterRun, openFilterPicker, openWallPicker

src/ui/selection-panels.js (90 lines)

Selection panels: current tool card and bag materials.

• functions: renderSelCard, renderBag
• variables: lastBagKey

src/ui/cursor.js (47 lines)

Hover work is shared by the cursor label and the vein outline.

• functions: oreLike, bitNeeded, pingVisible, cursorVein, hoveredVein, cursorLabelAlpha
• variables: CURSOR_ORES, cursorVeinCache, cursorLabelKey, cursorLabelSince

src/ui/info.js (208 lines)

Discovery cards, hover info (I) and the cursor label.

• functions: showCard, howText, discoveryCard, reactionsOf, hoverInfo, renderInfo, drawCursorLabel, pipeContentsText

src/ui/devconsole.js (42 lines)

Bottom panel; command dispatch and state live in sim/devconsole.js.

• functions: closeDevConsole, showDevConsole, toggleDevConsole, devPrint, runDevCommand

src/ui/input.js (92 lines)

Keyboard and mouse listeners.

• functions: isTyping
• variables: canvas

src/ui/actions.js (256 lines)

What input does: overlays, F, pick, copy / cut / paste, undo, building and tool use each frame. Which overlays are on, shown as a coloured frame round the screen and a named badge

• functions: updateOverlayUI, toggleLens, doInteract, pickUnderCursor, aimBlock, stampOrigin, selModeHeld, startPaste, stopSelectAndPaste, plural, piecesIn, doUndo, endRmbRecord, dragDirFor, blockLabel, primaryPress, primaryRelease, secondaryPress, pingWait, firePing, toolTick
• variables: ovShown, PING_RECHARGE

src/ui/gamepad.js (60 lines)

Gamepad input.

• functions: padPressed, pollPad
• variables: PAD

src/ui/previews.js (241 lines)

Cursor previews: shared grid helpers, air streaks and tool preview dispatch.

• functions: blockRectPx, drawGrid, previewColor, drawAirStreaks, drawReachCircle, drawPreviews, previewBlock

src/ui/preview-drill.js (67 lines)

Drill pulse wavefronts and aiming fan. The pulses in flight: a wavefront running out from the face of the bot, fading as it goes

• functions: pulseRGB, fanPoints, drawDrillPulses, drawDrillAim

src/ui/preview-selection.js (81 lines)

Selection previews: labelled tags, copy and cut boxes, and paste ghosts. a small labelled tag drawn on the world (screen pixels)

• functions: drawTag, drawSelection, drawPastePreview
• variables: SEL_COL

src/ui/events.js (42 lines)

Events from the simulation (emit) turned into sounds, toasts and cards.

• functions: drainEvents

src/ui/map.js (93 lines)

Shared world colours, minimap and full map.

• functions: resetMap, mapArea, updateMap, drawMap, mapFit, drawFullMap, openMap, zoomMap, zoomMinimap
• variables: MAP_S, MAP

src/ui/perf.js (15 lines)

Browser-only clocks; simulation code stays usable without a browser or a clock.

• variables: PERF_MARKS, PERF_FRAME, perfMarks, perfTimes, perfLast

src/ui/loop.js (149 lines)

The frame loop and boot.

• functions: scanVisible, frame, boot
• variables: lastT, acc, lastRender, frameMs, simMs, fpsSm, ambientT

Tests and tools

• test/firefox_smoke.py: An isolated Firefox title screen and three seconds of a new pixel world.
• test/furnace_play.js: Fires a starter furnace design repeatedly the way a player would, without cleaning it out between firings, to see whether it clogs. Usage: node test/furnace_play.js [design] [ore] [coal] [firings] [roll] [mode] mode: 'mix' (even ore/coal mix blown in), 'layers' (ore first, coal on top), 'vent' (blown in from above through the vent)
• test/gpu-readback.js: Read the four actual smooth textures without adding COPY_SRC usage to game resources.
• test/harness.js: Loads the simulation (the src/sim/ files listed in src/manifest.json, joined in order into one script, the same way build.py joins them) so scenarios can drive it headlessly in Node. Errors point at the real file and line (sim/pipes.js:42), not at the joined script.
• test/light-cases.js: Lighting behaviour checks executed by the GPU browser harness.
• test/light-readback.js: Read float source channels, including transmittance, from the WGSL light pass.
• test/play.py: Play-test in a real browser: mouse, keyboard and a mocked gamepad drive the game; save and continue. Screenshots go to shots/play/ (or the folder given as the first argument). Pixel look unless the second argument is 'smooth'.
• test/run_all.py: Run the test suites and report.
• test/t_bar_stacking.js: Resting bars snap into pairs of grains and tip off narrow supports.
• test/t_basics.js: Basics: drilling to rubble, the vacuum and blowing, walls, the ingot mold and bars, belts, blueprints, save/load.
• test/t_build.js: Building: undo (Ctrl+Z), cut, replace a machine with Ctrl, pasting ghosts, and the fan heat warning.
• test/t_caps.py: Capability detection, title notices and the required-WebGPU startup gate.
• test/t_conveyors.js: Screw conveyors that never carry liquid (it flows through), screw and belt throughput, filters.
• test/t_corner_seal.js: Corner-touching square walls seal loose grains without changing free piles or worldgen.
• test/t_cursor.js: Ore identification, cached connected veins, ping timing, settings and label lifetime.
• test/t_dev_console.js: Dev command validation, discovery, build costs, runtime controls and save metadata.
• test/t_dev_console.py: Dev console confirmation, keyboard isolation, HUD, time controls and saved badge.
• test/t_diag_screws.js: Diagonal screws: sealed four-lane corner transfers, bars, joins and persistence.
• test/t_drill.js: The resonance drill: pulses from the bot shake rock until it shatters. Widths trade area for speed, tuning shatters only one material and drains it out of the wall, built blocks are left alone, and the drill says why when nothing breaks.
• test/t_econ.js: Economy: the dock (instant sale), orders, prices, the market dip, money for machines, alloys.
• test/t_flow.js: Throughput overlay (t49): grains per second per transport block, counted only while the overlay is on, never changing what the simulation does.
• test/t_fog.js: Fog: surface, sight, range, saves and simulation independence.
• test/t_furnace_repeat.js: The starter furnaces keep working when fired again and again without cleaning, however the charge goes in: mixed, ore first with coal on top, or blown in through the vent. Each case plays furnace_play.js, which builds the design and fires it like a player.
• test/t_gpu.py: Dirty uploads, default limits, warm pipelines, world replacement and device recovery.
• test/t_gpu_golden.py: Frozen legacy references, captured before retirement; compare the WebGPU world only.
• test/t_gpu_light.py: The former CPU light behavioural checks, now read from the actual GPU light grid.
• test/t_joins.js: The oracle states the geometric rule independently of the precomputed neighbour tables.
• test/t_load.js: Reload wakes nearby areas first, without losing distant water, fire or saved state.
• test/t_molds.js: Molds and furnaces stay usable: ingots drop below and keep their stubs, plugs over molds are cleared, spoiled castings can be knocked out, grains never drop through a grate by teleporting, and slag lets the fire breathe.
• test/t_nozzle.js: Blowing aims within the nozzle's reach, with room for the brush and settling.
• test/t_perf.js: Profiling fixtures start in the same state after previous scenes and warm-up ticks.
• test/t_physics.js: Sand and other powders, molten metal and gases: heaps, sorting, sinking, setting, rising and fading. Water has its own suite (t_water.js). Tall worlds keep geothermal heat out of the way.
• test/t_pipes.js: Pipes, pumps and outlets move liquids; the Grinder grinds waste rock for trace ore.
• test/t_racks.js: Rack intake, FIFO storage, gate, removal and saved-state validation.
• test/t_render_dirty.js: Render invalidation must not depend on whether a grain moved or the chunk stayed awake.
• test/t_silo_contents.js: Stored snow keeps its identity and remains in the world's water budget.
• test/t_sim_optimizations.js: Optimized paths must match the full roof scan and the original heat loop exactly.
• test/t_slope_belt_art.js: Drawing geometry against real parts, without changing transport.
• test/t_slope_belts.js: Sloped belts: transport, joins, sorting, persistence and the actual drag controls.
• test/t_slopes.js: Sloped walls: flow, sealed joints, building, refunds and persistence.
• test/t_smooth.py: The smooth look: the WebGPU pass compiles and draws, and the thermal lens still works.
• test/t_stone.js: Uses for waste rock and sand: glass bricks from a fan furnace, the Saw, the silo and builders' orders.
• test/t_threads.js: Shared allocation, checkerboard independence, and real worker-count determinism.
• test/t_water.js: Water conservation, settling, ledge pouring, boundaries, pipes and phase changes. Tall worlds keep geothermal heat out of the ponds.
• test/t_weather.js: Weather: no more springs; steam rises into clouds and rains back; showers; snow when it is freezing.
• test/t_world.js: Trees from acorns, charcoal, brick, density, water/lava/snow/ice, full-bag refunds, drill reach, ballistic blowing, snowy mountains.
• tools/browser.py: Shared isolated HTTP sessions; callers attach hooks before navigating to url.
• tools/caps.py: Print isolation, WebGPU adapter info and GL renderer for installed browsers.
• tools/map.py: Regenerate the file and symbol index at the end of docs/PROJECT_MAP.md.
• tools/perf-measure.js: Temporary wrappers live only in the profiling page, never in the simulation bundle.
• tools/perf-scenes.js: Seeded worlds, no storage round-trip (saves quantize heat and land flying grains).
• tools/perf.py: Profile a seeded world on the real GPU, with isolated HTTP serving. Times are milliseconds.
• tools/playthrough.py: Headless browser run: load the page, start a world, play a little, take screenshots.
• tools/serve.py: Build, serve and rebuild when sources change: python3 tools/serve.py [--port 8000].
• tools/server.py: Serve dist/ with isolation headers; isolated_server() owns a free-port background server.
• tools/shot.py: Screenshot the game in a headless browser, after setting up a scene with JavaScript.
• tools/test_perf.py: Profiler checks: headers, summaries/comparison, and unchanged pixels/simulation with clocks on.
• tools/use_venv.py: Let browser scripts run with plain python3 by switching to the repo's .venv.
• tools/where.py: Turn a line number in dist/index.html into the source file and line it came from.
• tools/experiments/cast_sunk_mold.js: Block-sized bit mold sunk into the ground with a stone furnace built over its funnel.
• tools/experiments/factory_cost.js: What does a running factory cost when the player is somewhere else? Builds K self-running modules in a generated world, far from the bot, and measures simulation time per tick. Each module: a coal + copper-ore furnace burning in a stone-block box, a spring feeding a water wheel, a shaft carrying its power to a 10-block belt that hauls sand off a hopper.
• tools/experiments/flow.js: Throughput of belts and screw conveyors: grains delivered per second. Whatever lands past the outlet is taken away, so the output pile never backs up into the line.
• tools/experiments/furnace.js: Furnace scenarios on a flat test world: builds a chamber, charges it with ore and coal, lights it and prints temperatures, burning cells and what has melted or set at intervals.
• tools/experiments/section.js: ASCII cross-section of a stone furnace firing, with a temperature digit per cell (0-9), printed at intervals. Usage: node tools/experiments/section.js [WALL_MATERIAL] (default STONE).
• tools/experiments/slope-cost.js: Many loaded slopes, with a fresh deterministic world for each timing sample.
• tools/experiments/slope-flow.js: Reproducible generous-feed throughput and settled pile angles for t42.
• tools/experiments/smelter.js: Smelter design experiments, built with the same block pieces a player uses. Layout (block rows, 4x4 grains each), on flat ground at row 25: roof with a vent ........ row g-CH-1 chamber, CH blocks tall .. charge of coal + copper ore inside grate floor ............. row g = 23 (liquids pass, powders do not) ingot mold .............. row 24, sitting on the ground side walls run from the roof down past the mold. Usage: node t_smelter.js [key=value ...]
• tools/experiments/starter.js: Plays a starter design the way a player would: paste the blueprint, let the bot build it from the bag, blow an even ore/coal mix inside, light it, wait, knock out the castings. Usage: node tools/experiments/starter.js [design id] [ore] [coal]
• tools/experiments/worldgen.js: World generation report: time to generate, how many cells of each material, where the bot starts, and what idle ticks and ticks after digging cost.
• tools/scenes/bar-lift.js: A mold drops copper bars onto a belt, through a screw lift and onto the upper belt.
• tools/scenes/belt-heap.js: A belt feeding an upward screw: sand underneath a deep heap of copper ore. Run clear-sky.js first, e.g. python3 tools/shot.py /tmp/belt-heap.png --setup tools/scenes/clear-sky.js --js "$(cat tools/scenes/belt-heap.js)" --ticks 240 --zoom 7
• tools/scenes/clear-sky.js: A clear work area left of the bot's starting point (the trade dock is to its right): open sky 160 grains wide and 40 tall, over a flat stone floor. Money and a bag of building stuff to build with. Sets FLOOR (the first row of the floor), BX, BY (the leftmost block of the area that stands on the floor) and CAM (the middle of the area).
• tools/scenes/joins.js: Travel join grid: UR/DR/DL/UL, both ends, and all three neighbouring placements. Screw H and V, then belt H; each tries the side, above/below, and E. Self-contained, paused and empty. Use --zoom 4 --viewport 2100x1500 --no-light.
• tools/scenes/mold-labels.js: Run after clear-sky.js: filling, blocked, set, and hot machinery in one view.
• tools/scenes/silo.js: Run after clear-sky.js; leave paused so the open gate keeps its demonstration charge.
• tools/scenes/slope-conveyors.js: Loaded sidewall conveyor and screen. Use --js 'slopeScene(false)' (belt) or 'slopeScene(true)' (screen).
• tools/scenes/stone-uses.js: The stone and sand machines: a half-full silo with its gate open over a belt, a stone cutter fed with rubble, and cut stone and glass brick walls. Run clear-sky.js first, e.g. python3 tools/shot.py /tmp/stone.png --setup tools/scenes/clear-sky.js --js "$(cat tools/scenes/stone-uses.js)" --ticks 240 --zoom 7
• tools/scenes/t-screen-joint.js: Downhill screen whose outlet belt sits level with its last block (the jam the owner saw).
• tools/scenes/t33-ground.js: Paused dug pocket: copper ore, rubble and dirt against stone, granite and dirt. Use --js "..." to set daylight or R.lens after this setup; CAM frames the pocket.
• tools/scenes/t35-diagonal.js: Run after clear-sky.js: a belt takes sand from a pile, up a diagonal screw to an upper belt.
• tools/scenes/t35-joins.js: Run after clear-sky.js. Paused, empty pipes make casing, flights and mouths easy to inspect.
• tools/scenes/t36-funnel.js: A twelve-block funnel, one block open at the bottom, draining 400 grains of sand.
• tools/scenes/t40-sloped-belt.js: Self-contained: a flat feed climbs, crosses the top, and runs downhill; a filter sorts below.
• tools/scenes/t88-light.js: Frozen light comparisons, also used by the WebGPU browser regression suite.
• tools/scenes/t88-renderer.js: Paused comparison scene: ordinary grains, fog, heat, trees and exceptional geometry.