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/style.css  all styles
src/sim/              the simulation. No DOM. The headless tests load only these files.
src/render/           drawing: the pixel look (CPU) and the smooth look (WebGL2), 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); run_all.py
tools/                serve.py (build, serve, rebuild on change), shot.py (screenshots),
                      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)

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.
• 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

• The pixel look:
  • drawWorld (src/render/world.js) fills one pixel per grain;
  • computeLight (light.js) adds coloured light;
  • overlays (machines, molds, the bot, rain, arrows) are drawn on the 2D canvas afterwards (machines.js, overlays.js).
• The smooth look (src/render/smooth.js) takes the buffers drawWorld fills (colour and a class per cell, the colour behind, trees, fields, light, glow) and shades them with WebGL2.
  • The cell classes are set in world.js and read in the shader: 4 is a crisp built piece, 6 a wall tile, 7/8 a belt, 9–12 a screw conveyor, 13/14 a filter.
  • On software GL it falls back to pixels, unless window.__allowSoftwareGL is set (the test tools set it).

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)
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 (cleat barriers, pocket depth 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/smooth.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 (177 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, 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 (105 lines)

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

• functions: emit, bagCap, discover, alloc, depthU, depthY, meanSurface, computeAmbient, fillNoise, 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, 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 (218 lines)

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

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

src/sim/heat.js (265 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 (155 lines)

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

• functions: engineIntake, fanBlow, machinesTick

src/sim/conveyors.js (197 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, diagonalScrewNext
• variables: CARRY_DEPTH, filterR, filterL, filtersDirty

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

Cleats are moving barriers, not material cells. A cleat supports a finite pocket; the bare face never holds grains.

• functions: cleatFoot, pocketDepth, slopeCleatsTick, screenNudge
• variables: CLEAT_SPACING, CLEAT_HEIGHT, CLEAT_REACH, SCREEN_NUDGE_TICKS, cleatCarrying, cleatMask, cleatCells, slopePhase

src/sim/blocks.js (219 lines)

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

• functions: blockOf, blockCellList, pieceCost, setSlopeSeal, slopeSeal, slopeSealOwner, 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 (288 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, entSlopeBeltTick, entTick, entsInCircle, bagAdd, bagTake, giveOrDrop, refundAt, canAfford, payCost, fmtMoney, costText, needText
• variables: BAR_W, BAR_H, entCurM, droppedLast

src/sim/tools.js (52 lines)

Tool helpers: reach, brushes, and plain digging.

• functions: inReach, forBrush, drillReach, inDrillReach, toolDig

src/sim/drill.js (160 lines)

The resonance drill: tuned pulses that shatter one material.

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

src/sim/nature.js (168 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 (179 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 (87 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/tick.js (28 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/save.js (179 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 (200 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/light.js (103 lines)

Propagated coloured light from glowing and burning cells.

• functions: builtForLight, looseForLight, computeLight

src/render/slope-belts.js (150 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, slopeDetailAt
• variables: slopeBeltJoins, slopeBeltHalo, beltCaps, slopeAcross, slopeAlong, slopeDistance

src/render/world.js (447 lines)

Scale colour without changing the smooth-look class.

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

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 (229 lines)

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

• functions: spawnFloater, drawRain, drawFlowArrows, drawRunOutline, drawFilterTags, drawFloaters, moldLabel, drawMolds, drawBot, spawnDebris, spawnSpark, spawnSuck, drawParticles

src/render/smooth.js (99 lines)

Smooth look: WebGL setup, texture uploads, drawing and adaptive resolution.

• functions: smCompile, smoothAvailable, smUpload, smoothDraw, smoothPace
• variables: SM, smBytes

src/render/slope-belt-shader.js (85 lines)

Smooth slope shading, kept beside the shared CPU geometry in slope-belts.js.

• variables: SM_SLOPE_HELPERS, SM_SLOPE_DRAW

src/render/smooth-shaders.js (369 lines)

Smooth shaders: vertex and fragment programs for the rounded world look.

• variables: SM_VS, SM_FS

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 (75 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/title.js (46 lines)

The title screen art.

• functions: buildTitleCells, drawTitle
• variables: 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 (145 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 (157 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 (125 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 (34 lines)

The tool hotbar and what is selected.

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

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 (120 lines)

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

• functions: pieceSize, pieceUsesWall, setDrillWidth, tuneUnderCursor, cycleItem, cycleWall, rotate, toggleBlow, pickFilterUnderCursor, toggleFilterMat, setBrush, pieceV, 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/info.js (195 lines)

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

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

src/ui/input.js (91 lines)

Keyboard and mouse listeners.

• functions: isTyping
• variables: canvas

src/ui/actions.js (242 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, toolTick
• variables: ovShown

src/ui/gamepad.js (60 lines)

Gamepad input.

• functions: padPressed, pollPad
• variables: PAD

src/ui/previews.js (248 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 (107 lines)

Drill previews: shaken rock cracks, pulse wavefronts and aiming fan. Rock the drill has shaken but not yet broken shows cracks, more and finer as it nears breaking. Each crack is a contour line of a noise field (marching squares, cell by cell), so the lines run on unbroken from one cell to the next and look like real fractures, not a pattern.

• functions: crackSeg, drawCracks, pulseRGB, fanPoints, drawDrillPulses, drawDrillAim
• variables: CRACK_N, CRACK_LV

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/loop.js (134 lines)

The frame loop and boot.

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

Tests and tools

• 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/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/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_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_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_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_light.js: Run the renderer's lighting against real simulation data, with only canvas storage stubbed.
• 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_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_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 WebGL pass compiles, draws, falls back cleanly, 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_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/map.py: Regenerate the file and symbol index at the end of docs/PROJECT_MAP.md.
• tools/perf.py: Times the renderer and the simulation in a headless browser: light, drawWorld (with and without light and glow), the pixel upload and blit, and one simulation tick, in ms. Rebuild first.
• 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/shot.py: Screenshot the game in a headless browser, after setting up a scene with JavaScript.
• 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/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/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.