deepgrain-foundry/docs/DESIGN.md

# Design

What Deepgrain Foundry is meant to be, how its systems fit together, and the decisions made so
far with their reasons. Read the relevant part before changing how the game plays. When the owner
decides something new, add it under "Decisions" with the date.

## What the owner wants (stated by the owner)

- A **Sandustry-style factory and automation game**. Every cell is a fine falling-sand grain
  (one or two screen pixels at normal zoom), not a Terraria-size tile. The world is a
  Terraria-like side view with dark caves.
- **Strictly a factory game.** No RPG elements, no enemies, and no character items besides the
  dig and build tools.
- **Real physics, and player-built machines** instead of magic converter buildings. Furnaces are
  built from blocks, metal is cast in molds, and heat, air and gravity do the work. Physics
  hazards (heat, molten metal) damage builds only.
- **Loose material falls; solids hold.**
- **Copy and paste of builds.** Pasting places ghosts that the bot builds from the bag.
- **Tool upgrades are earned in a satisfying, not tedious way**, not bought with arbitrary
  credits. So far that means casting them: a drill bit in a Bit mold, a bigger bag in a Tank mold.
  The owner wants the whole upgrade system redesigned (task t14).
- **A hovering bot that flies freely.** A limited bag that can be upgraded.
- **An economy instead of a rocket or other final goal.**
  - Sell materials at the trade dock; refined goods and alloys pay more.
  - Spend the money on buildings.
  - Pay off the $20,000 land claim, then keep growing.
  - A milestone ledger marks progress.
- **Machines run without power**, for simplicity. The power code (water wheel, shaft, steam
  engine) is still there but switched off (`POWER_FREE` in `src/sim/pieces.js`). Those pieces are
  hidden from the menu, and old saves keep them.
- **Look.** Not pixel art. The default is the "smooth look": a smooth, illustrated style with
  soft, clay-like lighting, drawn by WebGL2. The pixel look stays as an option and is what tests
  use.
- **A water cycle, not springs.** Steam rises into clouds and comes back as rain, or as snow
  where it is freezing.
- **Sound.** Generated ambient music that changes with depth, and retro chiptune effects.
- **No external assets.** Everything is drawn and synthesized in code.
- **Controls and settings.** Modern keyboard and mouse, plus gamepad support, and plenty of
  graphics and display settings.
- **Platform.** A web game for now, built and tested by agents locally. A Rust version may come
  much later, for performance; keeping `src/sim/` free of the DOM keeps that open.

## The core loop

1. Dig with the resonance drill. Rock shatters into loose grains: rubble, ore, coal, clay, sand.
2. Vacuum up what you want (a drag takes only the material it starts on), and blow out what's in hand where you need it.
3. Build a furnace from wall blocks, with a grate floor over a mold. Charge it with ore and coal,
   light it, and let the molten metal run into the mold.
4. Bars drop out of the bottom of the mold; collect them and sell them at the trade dock, or fill buyers' orders, which pay more.
5. Better bits (copper, then iron, then steel) open harder rock: granite, then basalt. Deeper
   ores give tin, zinc, silver and gold, and alloys (bronze, brass) pay more.
6. Automate with belts, screw conveyors, filters, fans, pipes and machines. Pay off the claim.

## Systems in brief

Details and numbers live in the code and in `docs/systems/`.

- **World:**
  - sizes 2048×1024, 3072×1280 or 4096×1536 grains;
  - layers: soil, stone, granite and basalt over a magma sea;
  - ores by depth:
    - coal, copper and clay near the top;
    - tin in the upper stone;
    - iron from about a quarter of the way down;
    - zinc in the middle (stone and granite);
    - silver deep in the granite;
    - gold deepest (granite and basalt);
  - ambient temperature falls with height and rises with depth.
- **Materials:** 95 material ids, counting air and a few used for built parts. Each is in a
  phase: solid, powder, liquid, gas, or item (bars).
  - Heat flows between cells. Things melt, freeze, boil, burn and react.
  - Fire needs air: a buried fire chokes, and a fan blowing in makes it hotter.
  - Coal burns at about 1350°C in still air and about 2000°C with a fan.
- **Drill:** see `docs/systems/dig-tools.md`. Pulse widths, tuning to one material, hardness by
  bit tier.
- **Building:** a 4×4-grain block grid.
  - Blocks: walls of any of several materials, belts, screw conveyors, filters, grates, gates,
    pipes, pumps, outlets.
  - Machines: fan, Refiner, Stone cutter, Silo.
  - Molds: ingot, bit, tank. Ingot bars drop out of the bottom onto whatever is under the mold;
    leave one open block below and a belt under that carries them off. Ingot molds empty themselves:
    junk and mixed scrap drop below, slag is thrown away and the grate above is raked. Short stubs
    stay for the next firing. Removing any mold returns its set metal to the bag: whole bars as
    bars, the rest as scrap.
  - Build actions: drag for lines, Shift-drag for rectangles, hold G to replace, hold C / X and
    drag to copy / cut, V to paste, Ctrl+Z to undo, middle mouse to pick,
    Shift+Q/E to switch build tabs.
- **Economy:**
  - The trade dock pays for anything dropped through its grate, at the market price.
  - Prices dip when you sell a lot of one thing and recover over minutes.
  - Up to 3 orders at a time pay well over market. Builders' orders want bulk rubble, gravel,
    sand or stone bricks.
  - You start with $250 and $20,000 of claim debt.
- **Weather:** steam in the open sky becomes clouds. They drift and rain, or snow when cold.
  The world's water is counted, so rain only returns what evaporated.
- **Waste rock and liquids:** see `docs/systems/stone-and-liquids.md`. It covers the Refiner,
  pipes, the silo, glass bricks, the stone cutter and builders' orders.

## Decisions

The newest are at the bottom. The dates are when the decision was made or built.

**Up to 2026-10-19** (early design, stated by the owner): everything in "What the owner wants"
above, including:
- the economy replacing a rocket goal;
- machines without power;
- the smooth illustrated look;
- the water cycle instead of springs;
- testing in the pixel look unless graphics are being checked.

**2026-10-19 / 20, dig tools.** The resonance drill replaced the old drill. See
`docs/systems/dig-tools.md`.

**2026-10-22:**
- **Rock too hard for your bit never crumbles, however small.** Crumbling it to ore would give ore
  without the right bit and confuse players. Crumbling it to stone would lose ore. Instead, world
  generation makes no tiny hard specks: pieces of 30 grains or fewer become the rock around them,
  and older saves are cleaned once on load. Iron and zinc veins are fewer and chunkier, with the
  same total ore.
- Belts and filters next to each other look like one belt. Belt ends are square with rounded
  corners.
- Dragging belts or filters sets their direction from the drag. R sets it when placing without
  dragging. An arrow shows the direction while dragging, and the selection card names it.
- **Copy and cut** are held keys, not a tool. Hold C or X and drag a box; it acts on release.
  Copy and cut look different. Cut is destructive, but it can be pasted back or undone.
- **Ctrl+Z undoes building** (up to 80 steps). The bot building ghosts is never a step of its own.
- **Holding Ctrl** while placing replaces what is built there (moved to G on 2026-10-23).
- **Fans melt like copper (1085°C).** Put the fan outside the furnace, blowing in through a grate.
  The game warns when a fan gets close to melting.
- **The vacuum takes only marked materials** once any are marked, even if the drag starts on
  something else. The t6 controls below replace the shared ticks; t16 replaces t6's modes; t20
  replaces the marks with pick-what-you-click.
- **The Refiner** grinds stone, granite and basalt rubble, gravel, sand and dirt for trace ore,
  roughly halving the waste. Ore and anything else it cannot grind drop straight through.
- **Pipes, pumps and outlets** move liquids up to 500°C, one liquid per line. A line is stored as
  a count, not simulated grains. Water in pipes counts toward the world's water, so the weather
  does not replace it.

**2026-10-23:**
- **Ingot molds drop bars below automatically.** The owner reported bars being thrown into the
  furnace above and wants belts underneath to carry them off. Blocked bars wait in the trough;
  short stubs stay for the next firing. The mold cleans itself and rakes the grate after dropping bars or clearing junk.
- **Screw conveyors carry no more than belts:** they move every other tick. For more throughput,
  build more lines.
- **A heap on a belt moves as one**, up to 96 grains deep, not just its bottom layer. If a grain is blocked,
  the load above it stands still and the belt slips underneath; the top no longer slides over
  a stuck bottom. Filters still let their chosen materials drop through.
- **Pick** (middle mouse) selects the piece under the cursor with its direction,
  wall material and filter settings. G no longer picks, as the owner requested (it is now Replace).
- **The build menu** is a bar of tabs and icon tiles along the bottom: Structure, Moving,
  Liquids, Machines, Molds. Hover a tile for its full description, cost and placement help;
  gamepad players see the selected tile’s popup. While building, the top-left card describes
  the build tool and shows the R/F settings, Replace, ghosts and status.
- **No length limit when dragging.** Blocks out of the bot's reach become ghosts that it builds
  when it gets there.
- **Pipes are thin:** sand, water and anything else loose passes them. Pumps and outlets are
  solid.
- **Uses for waste rock and sand:**
  - glass bricks (sand melted with a fan furnace, cast in an Ingot mold);
  - a Silo for storing one loose material, which should look like a real silo, not a magic
    black hole;
  - builders' orders for bulk rubble, gravel, sand and stone bricks;
  - a Stone cutter that makes stone bricks, which build cut-stone walls.
- **Rubble sells for a pittance** ($0.02 a grain, gravel $0.03). Dirt still earns nothing.
- **Re-refining sand stays allowed.** Refiner sand can be refined again, even in stacked
  refiners until none is left. The owner's reason: it is less profitable than making glass, so
  players will do it only when they need more ore rather than more money.
- The project moved from a claude.ai artifact to local development with coding agents. It is
  built from small files, with `NOTES.md` as the owner's to-do inbox (since 2026-10-24, a
  kandown board in `tasks/`).
- **Replace is held G, not Ctrl.** The owner hit the browser's Ctrl+W (close tab) and Ctrl+D
  (bookmark) while replacing and flying with WASD, and the game ignored WASD while Ctrl was held.

- **The build tool's top-left card describes the build tool**, like the other tools' cards:
  how to place, the build keys, the R/F settings (material, direction, filter), Replace · G and
  ghosts waiting. The selected piece's name, cost and description are in the menu and its hover
  popup. The owner asked for a general description rather than the selected building.
- **Ingot molds need no F.** They push junk and mixed metal out of the bottom as loose grains with the bars, throw slag away and rake the grate. Removing any mold returns its set metal: whole bars as bars, the rest as scrap. The owner asked what F was for once bars dropped on their own, and chose this over keeping F for cleaning.

- **Fewer, smaller messages.** Molds show only a small percentage, red when blocked or spoiled and gold when a casting waits for F; details are in the hover panel. Bars dropping, blocked molds and set castings no longer pop up cards or toasts. Fan heat is a red marker on the fan; melted screw conveyors and machines get a short red label where they were. Status lines are one short sentence. The owner found the messages too large and too many.

- **World sounds are local.** Sounds from the world (water sizzling on hot metal or lava, and
  any other event with a place) are heard around the bot, whatever the zoom: full volume within
  24 grains, fading to silent at 96, panned left or right. The owner heard a constant snapping
  that followed the bot in an older world but not in a new one. It was the sizzle: in the
  owner's world, water that had found its way down to hot basalt and granite (480-800°C, about
  500 grains below the surface) boiled about 48 times a minute, every one at full volume. The
  first fix faded sounds with distance from the view; zoomed out they were still heard, so the
  owner asked for a radius around the bot instead.
- **The silo has pixel art in the pixel look**, drawn grain by grain like the rest of the world;
  the smooth look keeps the illustrated silo. The owner noticed it looked the same in both.

- **Screw conveyors use all their lanes.** Grains in an up or down screw conveyor shift sideways toward the
  emptier lanes of the block, and grains taken in from the side go to the far lanes first. A
  block-wide lift fed by a belt from the side now carries about 90% of what the belt brings
  (before, only the edge lane filled: the owner saw one line on either side). Belts keep their
  speed.
- **Screw conveyors carry bars**, one whole bar at a time, in line with the grains: a belt pushes a
  bar into a screw conveyor's side, it rides through corners and leaves the mouth. The owner asked how bars
  should be moved and chose screw conveyors over a separate bar lift.
- **Several worlds are kept.** Each world has its own save and autosave; the title screen's Worlds
  list loads, renames and deletes them, and a new or imported world never overwrites another. An
  old single save becomes 'World 1'. The owner asked for multiple saves.

**2026-10-24:**
- **The to-do list is a kandown board.** `NOTES.md` became one task file per note in
  `tasks/` (Todo for tasks, Backlog for discussions and ideas, Review for "done, please check").
  The owner wanted a task tool built for AI agents.
- **Wall and mold materials have a menu (F).** It lists every wall material with what you have,
  the cost and the heat it stands; R still cycles. The owner chose F to match the filter menu.
- **The camera's drift toward the pointer is a setting** ("Camera looks toward the pointer", on
  by default). The owner doesn't like it.
- **Fog of war reveals by line of sight.** Unexplored ground is black with a soft edge; the sky
  and the surface start seen. The owner chose line of sight over a plain circle around the bot.
- **Bars pile neatly, and a Bar rack stores them (t1).** Bars that come to rest snap to a tidy
  brick pattern so piles have no air gaps; a Bar rack machine (the Silo for bars) takes them from
  a belt or screw conveyor, counts them and lets them out with F. The owner wanted bar storage that doesn't
  waste space, like stacked ingots in real life.
  As built: a resting bar snaps to a 2-grain grid, and one with fewer than 2 of its 4 bottom cells
  supported tips into the gap beside it. Storage became Rack blocks rather than a machine, like
  the t4 hoppers: 50 bars of any kind per block, a column is one rack; bars landing on top go in
  (into the lowest block with room), F opens the gate at the bottom of the column, and bars come
  out oldest first, one every 20 ticks, onto whatever is below. Taking a block back returns its
  bars.
- **Hopper blocks replace hopper machines (t4).** 1-block Grinder and Saw blocks each work what
  lands on them and drop it below, so a wider row is a wider, faster hopper. The Refiner and Stone
  cutter leave the build menu; built ones in old saves keep working. The owner wanted hoppers of
  any width.
  As built: a block is solid and works the grains resting on its top edge; results drop out of
  its bottom, and it stops when that space is full. Same speed and price per width as the old
  machines (Grinder 0.25 grains/tick, $60; Saw 0.5, $90). In a vertical stack only the top block
  takes input and the result passes down through the rest, so a Saw on a Grinder cuts stone and
  grinds everything else. Partial brick counts are not saved.
  After the owner played it: the Refiner and Stone cutter code is gone (an old save that still has
  one loads without it and refunds its price). Grinders draw as a pair of grinding wheels and
  Saws as a round blade, turning while busy. The Saw also cuts wood chunks into Planks (2 build a
  wood wall). Its stone output is now called a Stone block, so that only fired clay is a brick.
  Items piling up under a block stay a thing to build around (a belt or an open drop), and the
  Saw's text says so.

- **A world that lasts: deep ore, rock that pays, Huge worlds, new claims (t3, 2026-10-24).**
  The owner found worlds small and quickly mined out, so the only way on was a new game. Keep the
  bot and drill at today's pace and add more to find instead:
  - Deeper is richer: ore gets more common the deeper you dig, about 4.7x the ore in a Medium
    world (coal and copper ~5x, iron, zinc and tin ~4.5-5x, silver and gold ~3.4x, kept lower for
    their price). The top quarter of the underground is unchanged; copper also forms in deep stone
    and granite, coal in basalt, tin deeper. Lenses grow from lower noise thresholds only:
    stretching the noise with depth sheared it into diagonal streaks.
    No ore is placed where the natural rock temperature would light it (coal) or melt it (metal
    ores, within 200°C): deep coal and gold next to the magma burned and ran forever once a
    reload woke those areas, and a Huge world dropped to about 10 fps. So deep coal stays in a
    cooler mid band, and coal is about 3.2x rather than 5x; total ore about 4.2x.
  - Waste rock pays: grinding granite and basalt finds about twice the ore, and builders order
    granite and basalt rubble in bulk.
  - A Huge size (6144 x 2048); saves are gzip-compressed (a Medium save went from 29 MB to 0.4 MB).
  - New claims: once a claim is paid off, open another for $5,000 down and twice the last debt
    ($40,000, $80,000, ...). Money, bag, upgrades, discoveries, milestones and stats belong to the
    career and come along; buildings stay on their claim and wait (they don't run) until you
    travel back from the notebook's Claims page.

- **A minimap and a full map (t32, 2026-10-24).** Bottom right: a minimap around the bot with
  zoom (1 to 16 grains per pixel) and a Map button; M opens the full map (wheel zoom, drag to
  pan, centre on bot, markers for the bot and the dock). Both draw from one low-resolution colour
  image of the world (1 pixel per 2 grains, 4 on worlds wider than 4096) that refreshes a few
  32-grain areas a frame, nearest the bot first, and respects fog of war. Onboarding cards moved
  to the bottom centre to make room; mute moved to Shift+M. Bigger worlds and several claims
  made it easy to get lost.

- **Long waits show what's happening (t30, 2026-10-24).** Generating, loading, opening a claim
  and travelling show the loading overlay with a title, a moving bar and the current step
  ("Laying rock and ore", "Unpacking", "Building the world"...). Generation runs as steps that
  give the browser a frame every 30 ms, producing exactly the same world as before. A small
  "Saving…" chip shows bottom right only when a save takes longer than 150 ms. The owner found big
  worlds froze on a 0% bar with no sign of progress.

- **Clay bricks come from a Brick press (t28, 2026-10-24).** A hopper block like the Saw: every
  8 clay lumps on top become a Green brick below, and a Green brick fires into a Brick above about
  900°C (any fire). 2 Bricks build a brick wall block; builders order them. The owner found it odd
  that clay bricks (first planned as a mold) and stone bricks would be made in different ways, and
  chose a press over a heated kiln block or a mold. Loose clay still fires into brick rubble.
- **The bag is the vacuum's control panel (t6).** Each bag row has separate pick-up and blow
  marks; a chip on the tool card sets pick-up to everything, only marked, or the same as the
  first click; R over a grain toggles its pick-up mark. The owner found the shared ticks confusing.
  As built: T or the chip cycles What I click → Only marked → Everything; adding a mark switches
  to Only marked and removing the last goes back to What I click. A bag name or Q/E blows one
  material; ⬆ marks build an even mix (bars are never mixed).
- **The vacuum menu replaces the modes (t16, 2026-10-24).** Pick-up has no mode: nothing marked
  takes everything, anything marked takes only those, Shift takes everything for one click. F with
  the Vacuum (when nothing in reach can be used) or a click on the card opens a menu with ⬇ Pick up
  and ⬆ Blow toggles per material; the bag rows lose their buttons. T no longer does anything for
  the vacuum. The owner found t6's version had too many modes.
  Later the same day the owner added: Shift + right click blows an even mix of everything loose in
  the bag; Ctrl+click a bag name adds it to the blow mix and Ctrl+right-click to pick-up; the menu
  is one line per material because the first version was too large.

- **Air streaks for the nozzle (t25, 2026-10-24).** On top of the grains that fly in and out, the
  owner chose air streaks: while sucking, short teal streaks swirl in toward the ring; while
  blowing, amber streaks run from the bot to the cursor and spread to the brush width. Drawn only
  (time-based, no random numbers, so the simulation is unchanged), only in reach, and off with
  "Sparks and debris" or in unexplored fog.

- **The Vacuum is the Pneumatic nozzle (t26, 2026-10-24).** The owner's choice of name, since the
  tool blows as much as it sucks. It shows as the tool card's title row, with the nozzle width as a
  chip, and in the hotbar tooltip and all player text ("the nozzle" after the first mention). Code
  ids and names stay `vacuum`.

- **Tool messages are toasts (t27, 2026-10-24).** Every tool's messages ("Nothing selected", "Out
  of reach.", "Nothing to use there.") show as toasts at the top of the screen, and the red line in
  the tool card is gone. The owner asked for it for the vacuum and chose every tool. Errors have a
  red edge, info a patina one. A message that repeats every tick while a button is held keeps one
  toast alive instead of stacking more.

- **Pick up what you click, blow out what's in hand (t20, 2026-10-24).** Replaces t16's pick-up
  marks and the vacuum menu; the owner wanted something simpler and more intuitive. A left drag
  takes only the material it starts on (or the first loose grain it reaches); Shift takes
  everything. The hand is the blow selection: click a bag name or Q/E for one material, Ctrl+click
  for a mix, Shift + right click for everything loose. When something in hand runs out it leaves
  the hand (this settles the old t18 question), and an empty hand blows nothing and says so.
  Picking something up fills an empty hand, never a chosen one. One tool, no menu; R and F do
  nothing special with the Vacuum. The owner mostly uses it to collect ore and fuel and feed furnaces.
  Follow-up the same day: the hand became **one selection for both** picking up and blowing out,
  because there was no way to choose several materials to pick up, or ones not in the bag yet. With
  anything selected, a drag takes only the selection wherever it starts; with nothing selected it
  takes what you click. Holding Ctrl lists every material found so far below a "Not in bag" divider
  (no menu). Selected materials stay selected when they run out, and picking up never selects
  anything (both reverse the first t20 version). Clear: a button in the bag, clicking the only
  selected row, or gamepad B.
  Then, after playing: blowing out the last of a material deselects it again (an empty selection
  goes back to picking what you click; a selection kept on an empty material got in the way). A
  material selected before you have any stays selected. Ctrl + wheel scrolls the bag instead of
  zooming the page, and a click while Ctrl is held adds to the selection even when the click
  arrives without the Ctrl flag (seen on the owner's Linux setup).

- **Fog of war also reveals the ground around the bot (t17, 2026-10-24).** About 20 grains in every
  direction, through rock, fully clear with a soft edge. Line of sight alone hid everything inside
  the ground, so the owner couldn't see what was around them or where to dig.
  As tuned: clear to 12 grains, fading out by 24, with a grainy edge; the owner found the first
  version's narrow fade too sharp.
  Unexplored ground is pure black, not dark grey (the owner: "should be black anyway").

- **Water pours faster, and boiled-off rain spreads out (t21, 2026-10-24).** The owner found water
  running off a ledge slower than expected. Only the top layer of a pool flows, so pools emptied
  at a trickle and the old code left 24-650 grains stranded on a wide ledge for good.
  - A liquid now steps up to 8 cells a tick toward a drop instead of 1, fewer the thicker it is
    (water 8, molten copper 5, slag 4, magma 2, glass 1). A grain on top may look 4 times as far
    for a drop, so thin film left behind drains too. A 100-wide pool empties in about 50 s
    (it never fully emptied before); settled lakes still sleep.
  - Raining clouds keep drifting downwind at half pace, and rain falls over a cloud's band and the
    band either side. Before, a waterfall into a shaft hot enough to boil it could rain straight
    back on its own lake.
  - World generation settles the land at the old water speed, so every seed keeps making the
    same world.

- **Piles near the player sort, and quickly (t21, 2026-10-24).** A grain at least twice as heavy as
  the powder under it sinks through it at 20 times the old pace (ore through ash: 4 rows to the
  bottom in about 7 s). Before, a resting pile went to sleep and never sorted. Now areas with loose
  grains within about 100 grains of the bot get a sorting chance every 8 ticks; far away, piles
  still sleep. Through burning fuel sinking stays at the old slow pace: furnace beds are tuned to
  it, and dirt heaped on a burning pile must smother it into charcoal rather than sink through.

- **A loaded world starts around the player first (t21, 2026-10-25).** Loading used to start every
  area of the world at once, and a Huge world then took 15 ms a tick for its first 10 seconds,
  with ticks up to 80 ms. Now the areas within 150 grains of the bot start at once, the rest 12 a
  tick, nearest first (a Huge world is fully started after 17 s), and flying toward areas still
  waiting starts them. Nothing is skipped: the same settling happens, spread out.

- **Sloped walls and diagonal wall lines (t36, 2026-10-25).** The owner wanted funnel walls that
  material slides down instead of catching on block steps. A Sloped wall is a half-block triangle
  with a flat 45° face, in four orientations, built of any wall material at half a wall block's
  cost. Dragging walls or slopes at about 45° lays a diagonal line; for slopes the drag direction
  picks the orientation (solid side below) and T flips it, or turns a single piece. Each slope
  also fills one cell past its corner so a diagonal run is sealed (grains move diagonally and
  would otherwise slip through where two pieces meet). Square walls placed diagonally still
  touch only at corners and leak there, like any square blocks.
  Later the same day the owner asked for the Wall piece itself to work diagonally, the way screw conveyors
  do, so the separate Sloped wall piece left the build menu: a wall drag at about 45° lays slopes
  (solid side below, T flips it during the drag), straight drags and clicks lay squares, and for a
  single block T cycles square and the four corners. Slope ids are unchanged, so saves still load.

- **Diagonal screw conveyors (t35, 2026-10-25).** Screw conveyors run in eight directions. A drag at about 45°
  lays a diagonal run pointing along the drag, and R cycles all eight for a single screw conveyor. Diagonal
  runs carry grains at the same rate as straight ones, join straight screw conveyors and belts, and carry
  bars level, a block every eight ticks. They use new part ids (11-14) because part ids are saved.

- **Sloped belts and filters (t40, 2026-10-25).** The owner asked for belts, then filters, to work
  diagonally like screw conveyors and walls. A Belt or Filter drag at about 45° lays slope-shaped blocks
  whose face is a running belt, carrying grains and bars up or down in the drag's direction at
  flat-belt speed; the face grips its load, so nothing slides back. A sloped filter drops what it
  passes out underneath and carries the rest. New block codes (19-22), so saves still load.
- **Square corners hold grains (t39, 2026-10-26).** The owner wants square wall staircases to
  hold material instead of leaking through each touching corner. Powder, liquid and gas cannot
  step diagonally between two solid neighbours; powder neighbours still allow free piles to
  slide as before. Free flyers and diagonal screw conveyor intakes obey the same solid-corner boundary.
  Screw lane transport is unchanged. World generation disables cell corner sealing while
  settling loose ground, preserving existing seed layouts. This supersedes the square-wall
  leakage described in the t36 decision below.
- **Silo contents are visible without opening the gate (t38, 2026-10-26).** The owner wants
  contents beside the cursor anywhere over the outline and a material-coloured fill window at
  every zoom in both looks, while keeping the real steel silo shape.
- **Distant drill aim is normal (t41, 2026-10-26).** The owner normally points beyond the
  drill's reach and expects players to do the same. Keep the pulse colour and light crosshair,
  mark the pulse's far edge, and omit distance warnings for the drill. Other tools still warn.
- **Screw conveyors (t44, 2026-10-26).** The owner chose the real machine name for screw
  conveyors; code uses `screw` because `conveyor` also covers belts and filters. Transport,
  numeric ids and save versions stay unchanged.
- **No backward compatibility for now (2026-10-26).** The owner will start a new world after
  changes: no one is playing the game for real yet. Changes may break old saves and blueprints;
  don't add migration or alias code for them (first used by the t44 rename to screw conveyors).
- **No uphill sloped filters (t43, 2026-10-26).** The owner wants sloped belts and filters to be
  realistic in how they look and behave. Real sorting screens run flat or tilted downhill and
  shake; none climbs a 45° slope. So filters are flat or downhill
  only; to sort while lifting, run a sloped belt up, then a filter. Not built yet.

- **Conveyor drawing and sleep follow-up (t42/t43, 2026-10-26).** The owner wants visible
  rubber ribs on the actual cleat raster, filled corrugated far walls behind the load, and
  smooth continuous mesh with rails for inclined screens. Walls stop at the slope ends;
  only loaded screens shake. Empty moving cleats must let chunks sleep. Keep pocket transport,
  uphill throughput near 71 grains/s and exact sorting unchanged.

- **Sidewall belts with moving cleats (t42, 2026-10-26; physics replaced by the entry below).** To replace the old full-column
  grip, use moving barrier lines rather than material cells: the barrier mask blocks normal
  powder movement without overwriting grains, terrain or parts. Cleats stand perpendicular
  to the face, spaced 8 horizontal face cells apart and 6 grains tall (integer normal reach
  4); named constants keep these tunable. A finite periodic pocket envelope carries only
  what fits, stepping every other tick. End pockets continue while the cleat rounds the band.
  Between steps no grains are stamped: bare face slides and excess rolls back. Water drains;
  bars stay level. Dark corrugated far walls sit behind visible grains; drawing uses the
  actual barrier mask, including after save/load. The envelope is a discrete transport model,
  not a calculation of contact forces. A generous flat feed delivers about 71 grains/s uphill
  versus 90 flat; accepting that reduction remains the owner's playtest decision.
- **Inclined vibrating screens built (t43, 2026-10-26).** Diagonal filters always travel
  downhill, even when dragged uphill. R leaves a picked slope unchanged; flipping a blueprint
  mirrors its slope and keeps downhill travel. Placement and filter settings enforce the
  same direction. Sloped filters have neither column carry nor grip: gravity moves grains,
  with one mesh-contact nudge every 4 ticks (15 downhill steps/s plus gravity). Unselected
  bars step on that same cadence; selected bars fall through. Flat filters retain their
  linear transport. Sorting both slope shapes in either mode conserves the complete mix.
  Both looks use a sturdy mesh frame with a small tick-based shake only while loaded;
  idle mesh has no running belt animation. No old uphill-save migration was added.

- **Screw conveyors stay, in every direction (2026-10-26).** The owner asked whether screw
  conveyors are still needed now that belts climb 45°, whether they're realistic, and what a
  downward screw is for. Kept as they are: real plants use both (screws for steep, vertical and
  enclosed runs; belts for long, cheap, high-volume ones), and a downward screw is the same
  machine turning the other way, useful for letting material down at a steady rate.
- **Stalls are the player's to fix, but visible; belts carry a realistic depth (t45,
  2026-10-26).** An overloaded belt line jammed against a screw conveyor above it. The owner
  agreed that's realistic and stays the player's problem, but wants a warning on the stalled
  belt and the animation stopped on everything affected, and belts limited to a realistic
  load depth instead of carrying 96-grain stacks. Not built yet.

- **Cleats really push their pockets (t42 feedback, 2026-10-26).** The owner found the first
  cleats passed through heavy loads while the material climbed as before, and wants cleats that
  hold the material and drag it up. Now nothing carries the load on a slope but the ribs and a
  friction drag on the layer touching the belt (which gravity beats on 45°, so loose grains slide
  back until a rib holds them). Each belt step every rib moves one face cell and pushes the
  grains in its way ahead of it; whatever is heaped above the rib is left to roll back. A rib
  never moves into a grain, never crosses a machine, and stops short of anything built. If any
  rib of a run can't push its way, the whole run stalls that step and every move is undone (the
  stall t45 will show). At the foot of an uphill run, each rib coming up around the end roller
  scoops what lies on the feeding belt behind it into its pocket, like a real boot section.
  Measured: about 80-86 grains/s uphill under a heavy feed (flat 90); downhill about 38, since
  the top only feeds a layer two grains deep onto the face.
- **No cleats on downhill belts (t42 feedback, 2026-10-26).** The owner asked why a downhill
  belt has cleats: on 45° the load slides anyway. A downhill sloped belt is now a plain belt, with
  no ribs and no sidewall, that carries at belt speed like a flat one (90 grains/s); only uphill
  runs are sidewall belts. A whole run also shares one cleat phase, so pieces added later line up
  with it.
- **Build range about the size of the screen (t64, 2026-10-27).** The owner asked whether
  building needs a range limit at all, since the bot needs no arms to build. Agreed: keep a limit,
  but make it about what's on screen, so anything the player can see and aim at builds directly
  and anything beyond stays a blueprint built when the bot comes near. No limit at all would let
  players build in places they've never been and link far claims instantly. Not built yet.
- **Sticky materials slide freely on built surfaces (t61, 2026-10-27).** Stickiness (STICK) is the
  chance per tick a grain takes a diagonal step, which made clay lumps, snow, wood chunks, ash and
  dirt creep down sloped walls (a single clay grain never got down a 20-piece slope). The owner
  chose to make stickiness grain against grain only: on anything built, every material slides
  freely, so slopes are useful for every material, while heaps keep their shape. Real chutes clog
  with sticky material and need cleaning, but that is micromanagement the game doesn't need.
- **Belts and other transport pieces never fill a rectangle (2026-10-27).** The owner said Shift
  doesn't need to fill a rectangle for belts, conveyors and the like. Belts, filters, screw
  conveyors, shafts, pipes, pumps and outlets (`lineOnly()`) always draw a line, Shift or not, and
  a diagonal belt drag stays sloped. Walls, grates and gates still Shift-fill.
- **The dev console ships in every build (t66, 2026-10-27).** The owner is happy for players to
  experiment and play their own way, so the console isn't hidden behind a dev build. Turning it
  on warns first that the save will be marked, and the mark stays with the world; any future
  achievements won't unlock in a marked world. Besides money, items and upgrades it may have
  game speed and other things just for fun.
- **One join rule for every transport piece: the next piece goes right after the end
  (2026-10-27, replaces the t62 same-row rule).** The owner wants all pieces to place and join
  the same way, so players know what to expect when building. Joins follow the direction the
  material travels: a piece's outlet points at the block right after its end, which is the
  next block along a straight piece, or the block diagonally past a diagonal's end. The next
  piece joins when it starts in that block and carries the same general way. So a horizontal
  then a diagonal (up or down) starts the diagonal in the next block on the same row; a
  diagonal then a horizontal or vertical starts it diagonally past the diagonal's end; a
  vertical going up then a diagonal starts the diagonal directly above. Any other placement is
  two separate ends that pass nothing. Belts carry grains on top, so they bend the rule where
  grains can't follow it: an uphill belt's top feeds a flat belt on the same row, and a flat
  belt one block below an uphill belt's low end also feeds it. The owner first approved a rule
  based only on shape, then found in testing that horizontal → uphill and vertical → diagonal
  didn't join the way the other pieces did.
- **Warehouses replace the trade dock, eventually (t68, 2026-10-27).** The dock only exists to
  get selling working for testing; the owner finds it unengaging. The plan: a warehouse at each
  edge of the map, on indestructible ground, served by a road and trucks. Warehouses accept
  loose grain as well as packaged goods (pallets, barrels or sacks from packaging machines).
  Trucks matter to play, not just looks: what's waiting is collected when a truck comes, on its
  schedule. Finding them: the player spawns a short walk from the left warehouse, which takes
  loose and bulk goods at lower prices with frequent trucks; the right one pays more for
  packaged goods and is the long-haul goal. Both always show on the minimap and full map with an
  edge-of-screen arrow, the first-start card names both and suggests starting left, signposts
  stand on indestructible plinths at spawn, and each warehouse is a landmark (crane or silo,
  beacon at night) with its road running a little way inland.
- **Screws melting under hot loads stays, but must read clearly (t69, t70, 2026-10-27).** Hot
  material still damages screw conveyors (above 1000°), but the owner wants the damage obvious
  (a scorched or broken look, hover text, a first-time message), cheap to repair (build over it),
  and warned about before it happens (a glow near the limit). A heat-resistant screw comes later
  as an upgrade. Prompted by a long vertical screw that seemed to leak for no reason while it
  carried hot rubble.
- **Melts that cool loose are ordinary rock (2026-10-27).** Magma poured from the bag became an
  invisible, undrillable basalt the game treated as built. Now any melt except metal and glass
  cools into natural rock wherever it came from, and any solid no block, mold or machine owns can
  be drilled, so nothing can get permanently stuck in the world.
- **Resonance pylon: metal sets hardness, power sets reach (t47, 2026-10-27).** A pylon is built
  in copper, iron or steel, which caps the hardest rock it can break (4, 5, 6), the same way
  bits and tanks step up through metals. Power from the shaft network sets its radius and pulse
  rate, up to a cap per metal; power never sets hardness, so it can't skip the steel bit. It is
  tuned like the drill and never harms anything built. It waits until power is switched back on,
  since today every machine runs without power.

## Ideas not built yet

- **Concrete**, as a stronger wall material from rubble.
- **Upgrade ideas for the drill**: an amplifier, a tuning fork, harmonics. Also a Grav pick
  upgrade tool and mining charges. See `docs/systems/dig-tools.md`.
- The owner's ideas for later are tasks tagged `idea` in the Backlog of the task board.