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 (see NOTES.md).
• 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 (tick materials to take only those), and blow it out 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 tubes, 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 tubes, 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 ticked materials when anything is ticked, even if the drag starts on something else.
• 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 tubes 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 shows a compact summary (name, cost, variant chips, Replace, ghosts, how to place, status); the full description is in the hover popup.

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

• 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 has a compact top-left card like the other tools. The owner asked for it back after it was hidden; the long description stays in the hover popup.

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

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 in the "Future features and ideas" section of NOTES.md.