Masterplan

MASTER PLAN: Chemistry-Driven Industrial Voxel Survival in Unity HDRP

1. Purpose

Build a single-player, first-person chemistry and industrial-survival game on a streamed voxel platform. The platform began with the basic interaction loop of an early voxel sandbox:

Start a new procedurally generated world.
Walk, jump, and look around.
Break cube-shaped blocks with a center-screen raycast.
Collect blocks into a simple inventory/hotbar.
Place collected blocks back into the world.
Stream terrain chunks around the player.
Save edited chunks and player state.
Present the world through Unity’s High Definition Render Pipeline (HDRP), with optional hardware ray-traced effects on supported PCs.

Those eight items describe the platform baseline, not the current product scope. The game built on that baseline is Part II’s chemistry-driven industrial survival game. It is not an attempt to reproduce Minecraft’s feature set, content, progression, networking, or appearance.

Read this before anything else. Sections 1–26 describe the engine platform — a voxel sandbox with a Minecraft-shaped interaction loop — and that work is substantially complete. They are no longer the description of the product. Part II (§27–§49) defines what the game actually is: a chemistry-driven industrial survival game in which progression comes from real thermodynamics and electrochemistry rather than a crafting-recipe tier ladder, the primary threat is the player’s own industrial by-products, and the arc runs from striking a fire to holding a fusion plasma. Part II supersedes the product identity in §1 and §2.1 wherever they conflict. Part I’s engineering rules — determinism, coordinates, streaming, meshing, saves, budgets, assembly layering, asset licensing — remain binding without exception.

The project’s purpose is stated in §27.7: to teach that matter matters. Every rule in Part II follows from it, and the “no-unlearning” requirement it imposes — that every simplification be a simplification in the direction of truth, never a falsehood — is binding on all implementation.

The product Definition of Done is §36.6, not §26. The implementation roadmap is §36.4 (milestones C0–C7 to MVP) and §36.8 (C8–C17 beyond it). The core design loop is §27.6, the block/material model is §37, and the full technology tree is §38.

The project must use original code and legally licensed third-party assets. Do not copy or redistribute Minecraft textures, sounds, models, user interface, names, source code, maps, branding, or other protected content. Use a distinct project name and visual identity before public distribution.

1.1 Authoritative project location

Workspace root: /home/soulwax/workspace/engines/unity/minecraft.
Unity project root: /home/soulwax/workspace/engines/unity/minecraft/Minecraft-HD.
Git repository root: /home/soulwax/workspace/engines/unity/minecraft/Minecraft-HD.
Unity assets, packages, settings, production documentation, tests, and build automation belong under Minecraft-HD.
Authoritative planning and rules live in Docs/MASTERPLAN.md and Docs/GROUND_RULES.md inside the repository. CLAUDE.md remains at the repository root. Parent-directory copies are retired; none of these documents belongs under Unity’s Assets/ directory.

All paths beginning with Assets/, Packages/, ProjectSettings/, or Docs/ in this plan are relative to Minecraft-HD, not the workspace root.

2. Platform Baseline and Product Scope

2.1 Historical platform MVP (completed baseline)

The first complete platform build contains:

A title screen with New World, Continue, Settings, and Quit.
One local save slot initially; the save format should allow multiple slots later.
A procedurally generated, seeded world made from chunks of blocks.
A small block catalog: air, bedrock, stone, dirt, grass, sand, wood, leaves, and one emissive block.
Terrain with height variation, simple material layers, trees, and small caves.
First-person movement with walking, sprinting, jumping, gravity, collision, and mouse/controller look.
Block targeting, breaking, pickup, hotbar selection, and placement.
A nine-slot hotbar and a basic inventory panel.
A crosshair and a visible targeted-block outline.
Day/night lighting, fog, sky, basic shadows, and post-processing.
Positional block interaction sounds, footsteps, ambience, and minimal UI audio.
Chunk streaming and pooling around the player.
Persistence for the seed, edited blocks, player transform, inventory, time of day, and settings.
Quality presets, including an optional DXR preset for supported hardware.
A Windows x64 desktop build. Other platforms are later ports, not MVP targets.

2.2 Historical platform non-goals and supersession

Multiplayer, accounts, servers, or anti-cheat.
Crafting, furnaces, hunger, health, armor, combat, hostile mobs, farming, redstone-like simulation, fluids, weather, dimensions, or achievements.
- Several of these were later authorized as post-MVP work and have since landed (shapeless crafting, a passive and a hostile creature, and the weather + seasonal-climate system — see §2.6 and §17.4). They remain outside the Definition of Done: the MVP gate does not depend on any of them.
- Superseded by Part II. Furnaces, fluids, gases, farming, achievements, health/hazard survival, and a form of “redstone-like simulation” (process control, §32.3) are now core product, not non-goals — see §27 and the §36.6 Definition of Done. Shape-based crafting is superseded in the opposite direction: it is explicitly rejected as a progression mechanism (§27.2, §34.1). What remains a genuine non-goal is unchanged: multiplayer as an MVP requirement, exact Minecraft behaviour, console/mobile/VR/WebGL, runtime mod loading, and ray tracing as a hard requirement.
Destructible items, enchantments, complex recipes, or progression.
A fully infinite persisted world. The generator may be coordinate-unbounded, but disk and tested travel limits are finite.
Exact Minecraft world generation, mechanics, timings, UI, or art.
Console, mobile, VR, or WebGL support.
Runtime mod loading.
Ray tracing as a hard requirement. The game must remain playable through HDRP raster effects.

2.3 Historical platform follow-ons

Add these only after the MVP completion gate passes:

Simple crafting grid and recipes.
Health, fall damage, and respawning.
One passive creature and one hostile creature.
Water using a deliberately limited cellular or height-based system.
Biomes, ores, structures, and improved cave generation.
Item tools and block hardness.
Multiple save slots and world-selection UI.
Local co-op or network multiplayer, after a separate architecture review.

2.4 Standalone-server extension (authorized after the original MVP scope)

The original MVP remains a complete local game and its completion gate does not depend on network play. The project now also has an explicitly authorized standalone-server track. It must preserve one invariant above feature count: the server owns all mutable shared-world and player truth. A client may submit compact intent (move, choose a slot, use an item, target a block); it never submits a final position, inventory, health, hunger, spawn point, chunk contents, or an edit that the host has not validated.

The implementation order is deliberately conservative:

Fixed-rate, bounded UDP ingress and server-side movement/reconciliation, including a stateless endpoint-cookie challenge before any player session is allocated, acknowledged retransmission for one-shot player intents, and a rate-limited RTT probe for diagnostics.
Persisted world identity/seed, world-owned spawn, revisioned chunks, and server-owned entity state for player vitals and inventory.
Port the production deterministic generator into a Unity-free shared library, then add chunk interest management and server voxel collision. Avatar snapshot interest management is already bounded by the server-owned horizontal view distance; chunk interest must reuse that same authoritative visibility decision. Sparse authoritative edit persistence is already bounded and background-written; do not replicate generated chunks before client/server generator parity is mechanically tested.
Add authenticated persistent player identities, owner-only inventory/vital updates, and one validated action pipeline for placement, breaking, eating, combat, cooldowns, and drops. Basic server-side break reach/state validation is complete; placement and every inventory-affecting action still wait for shared content and atomic stack rules.
Simulate creatures/NPCs in the same fixed tick with explicit budgets and spatial interest.

Server extensions are called mods. The CraftBukkit-like answer is a small, owner-installed server lifecycle API plus authoritative events and state queries; a faulty mod is isolated rather than crashing the host. Forge-like content additions are a separate later content-registry/data pipeline, not arbitrary client code and not a way to bypass server validation. Mods are trusted local code unless a real process-isolation design is added; there is no false sandbox or remote download claim.

2.5 Networking charter: solid, truthful, and future-proof

The standalone server is a product surface in its own right, not a Unity scene that happens to be reachable over the network. It must remain deployable as one self-contained process on Linux, Windows, and macOS; run without a Unity installation; and behave predictably on a public UDP endpoint. The following rules are binding for all network features added after this plan.

Non-negotiable authority rules

The fixed server tick is the only writer of shared simulation state. Socket readers, disk workers, HTTP status requests, and mod discovery may enqueue work or read immutable snapshots; they may not mutate player, entity, inventory, chunk, or world dictionaries directly.
The client owns presentation and input sampling only. It may predict its own movement and show provisional local effects, but it never determines a final coordinate, collision result, health, hunger, stack count, cooldown, dropped item, creature decision, or block mutation.
Every state-changing request has a bounded session-scoped idempotency operation ID, explicit success/rejection result, and an authoritative follow-up snapshot. The server records and returns that ID; an acknowledgement alone means only “processed” and must not be misrepresented as “accepted.”
All gameplay validation runs from server data: current pose, collision world, permissions, held stack, content definition, reach, line of sight, cooldown, and target revision. Client hints are optional inputs, never evidence.
A server restart, a packet replay, a duplicate action, an out-of-order packet, and a malformed frame must produce no duplicate item, duplicate edit, duplicate damage, or corrupted save.

Protocol and compatibility contract

Keep UdpProtocol deliberately small, binary, versioned, and allocation-conscious. Every packet must have a magic value, exact protocol version, kind, session ID, sequence/acknowledgement fields, and simulation tick where relevant. Unknown versions, kinds, payload lengths, reserved bits, NaN or infinite values, and impossible enum values are dropped before gameplay work.

Protocol changes are append-only only when an old peer can safely ignore the field. Any changed payload interpretation increments the protocol version and rejects old peers clearly. Do not use heuristic packet parsing or silently “best effort” decode a different version.
Maintain a compact real-time lane: movement/input and normal avatar snapshots must stay inside the existing small datagram budget. Any future bulk lane must stay below a conservative 1,200-byte UDP payload ceiling, never rely on IP fragmentation, and have explicit fragmentation, ordering, retry, timeout, and memory limits.
Define packet ownership and reliability by intent, not by transport: movement is latest-wins and lossy; a block/use/inventory/equip request is a bounded, idempotent operation; world/chunk data is versioned reliable state; chat/admin/control messages are ordered reliable control data.
Use one in-flight reliable gameplay action per player until a later, tested sliding window proves necessary. If a window is introduced, it needs bounded IDs, duplicate suppression, ordered application where semantics require it, per-action expiry, and a resync path.
Reserve a compact result code and optional server revision for each reliable action now. Typical rejection reasons are out of reach, stale target, protected area, no item, cooldown, inventory full, invalid content, and permission denied. UI must consume those results without guessing.
The server advertises a deterministic handshake manifest: protocol version, world ID/seed policy, generator revision/hash, content-registry hash, required-mod manifest, tick rate, view-distance limits, and feature/capability bits. A client with different world-generation or content rules is rejected before it receives gameplay state.
Never put secrets, account credentials, or operator tokens in a packet that is merely obfuscated. Raw UDP is not encrypted. If privacy/authentication beyond a public join token is required, use a reviewed authenticated transport/session layer rather than inventing crypto.

Connection, security, and public-host behaviour

The current stateless endpoint cookie is an admission proof, not an account system. The production handshake must evolve in this order:

Stateless endpoint challenge with strict amplification and per-tick output budgets.
Bounded session allocation, timeout, sequence validation, timing probes, and diagnostic counters.
Named authenticated identity with a server-side persistent player record, password/token verification over an appropriate protected channel, ban/allow-list and role checks.
Optional platform identity or account-provider adapter behind an interface; no gameplay code may depend directly on Steam, a web service, or a launcher SDK.

Additional deployment rules:

Bind only the intended address/port and document that a raw UDP-capable forwarder, NAT rule, or tunnel is required; an HTTP-only tunnel cannot carry gameplay UDP.
Keep status/metrics separate from operator control. Health checks may be unauthenticated and read-only; administrative commands require explicit authentication, authorization, audit logs, and an opt-in listener or network allow-list.
Apply independent budgets to ingress bytes, decoded packets, connect challenges, session count, input rate, reliable actions, chunk transfers, entity snapshots, disk backlog, and outbound bytes. Dropping stale cosmetic/state packets is preferable to retaining unbounded latency or memory.
Treat every client, including a modded client, as hostile. Cookie checks, rate limits, and packet limits reduce abuse but do not replace an OS firewall, provider DDoS protection, authentication, observability, or operator runbooks.

Simulation, prediction, and correction

The server simulates movement, collision, gravity, jumps, liquids, effects, combat, and AI against its own loaded voxel data at a configured fixed tick. It returns an acknowledged authoritative player state. The client keeps a bounded input history, removes acknowledged inputs, replays any remaining input after correction, and smooths only small visual differences. It must hard-snap on teleports, respawns, major divergence, world changes, or invalid prediction history rather than smearing an incorrect state through walls.

Prediction history, remote interpolation history, action queues, fragment reassembly, and chunk caches all have hard item, byte, age, and time limits. On overflow, discard the oldest stale data and request one explicit resync; never grow a queue to “eventually catch up.”
Keep time concepts distinct: local render time, client input tick, authoritative server tick, snapshot tick, and wall-clock RTT. Never derive authority from the client clock.
Measure RTT, packet loss, snapshot age, correction distance, hard corrections, input queue depth, and server tick drift. Use the measurements to tune an interpolation delay within bounded limits; do not claim a fixed delay works for every route.
Remote players and creatures are presented from buffered authoritative snapshots. Missing data expires predictably; a despawn, dimension/world change, or interest exit removes presentation state rather than leaving a ghost entity.

World, chunk, and entity replication

Do not transmit entire mutable worlds as a stream of individual block messages. The server owns generation and persistence; replication is an interest-managed cache protocol.

Port the production generator to a Unity-free deterministic library first. Establish automated parity tests over representative seeds, negative coordinates, biomes, rivers, structures, trees, caves, and all content IDs. A generator hash mismatch is a join failure, not an opportunity for the client to render a subtly different world.
Give every chunk a coordinate, generator baseline/revision, authoritative edit revision, content palette/revision, and checksum. A client that has the same baseline receives only the sparse edit delta; a client with an older/unknown revision receives a compressed full authoritative snapshot.
Interest selection is server-side and shared by chunks, entities, creatures, sounds, block entities, and weather. It is based on configured view distance, player location, dimension, permissions, and explicit visibility rules—not solely the client camera or a client request.
Prioritize transfers: local collision/terrain first, then targetable blocks, then nearby entities, then distant terrain/cosmetics. Cancel or supersede obsolete work as a player moves. Each client has a byte budget and a bounded send queue, so a slow receiver cannot stall the simulation.
Entity replication is component- and change-based. A high-rate avatar record contains only pose, orientation, movement/action flags, held-item visual ID, and a revision. Health, hunger, food use, equipment, inventory, appearance/model state, AI state, and metadata use lower-rate owner- only or interest-scoped reliable updates. Never send an inventory every tick merely to display a held item.
A server-owned block action increments the relevant chunk revision and creates a compact change event for interested clients. Inventory consumption and world edit persist atomically from the same validated transaction; neither is broadcast until the transaction succeeds.

Persistence, recovery, and operations

server.conf declares server name, world name/seed policy, icon, tick rate, limits, mod policy, and network listener settings. The first start resolves and persists immutable world metadata; later configuration edits must not silently regenerate or rename an existing world.
Persist player records by authenticated identity, never endpoint or transient session ID. Store position, inventory, vitals, permissions, last safe location, and format/version metadata with atomic writes or a journal. Disconnect and restart recovery must be idempotent.
The simulation thread never waits on disk, DNS, web calls, mod I/O, or a slow client. Background persistence is coalesced, bounded, retrying, observable, and drained cleanly on shutdown within a configured deadline.
Expose structured /status metrics for tick duration, tick overruns, active/queued chunks, connected/authenticated players, packet/drop reasons, RTT percentiles, correction rate, action rejections, persistence backlog/failures, mod faults, and memory/GC pressure. Metrics must be useful without exposing player addresses, secrets, or operator credentials.
Support orderly shutdown: stop admission, announce shutdown when a messaging layer exists, drain the fixed tick, flush critical world/player edits, stop mods, close sockets, and exit with a meaningful code. Crash recovery must detect incomplete writes and restore the last valid state.

Mods and content compatibility

Mods are server-installed trusted extensions, not network peers. They receive stable world/entity APIs and lifecycle/events after validation; they do not receive raw sockets, unrestricted packet buffers, or permission to mutate collections outside the simulation tick.

Define explicit cancellable/pre/post events for connection admission, player action validation, chunk load/save, entity spawn/despawn, damage, inventory transaction, and world tick. Event ordering, timeout/budget policy, and mutation ownership must be documented.
A mod has an ID, semantic version, API version range, deterministic content manifest, declared permissions, and optional required-client-content flag. The handshake compares the required manifest/hash before joining. Cosmetic-only server mods must not force an unnecessary client mismatch.
Isolate a throwing or over-budget mod: log it once with context, disable it for the process, and preserve the base server tick. A mod cannot make a packet valid, bypass ownership checks, or directly write persistence files.
Keep content IDs stable and server-owned. Removing/modifying a content definition requires an explicit migration or a clear startup refusal; silently reusing an ID corrupts saves and network interpretation.

Required verification gates

No networking phase is “done” because two local clients appear to connect once. Each phase needs automated packet/serialization tests, deterministic server simulation tests, soak tests, and a manual cross-network check. At minimum verify:

Packet fuzzing rejects truncation, oversized payloads, invalid versions, NaN values, duplicate actions, sequence wraparound, stale cookies, malformed fragments, and impossible content IDs without crash, allocation growth, or world mutation.
Loss/reorder/duplicate simulation proves movement remains fluent, a discrete action eventually receives one result, and the server performs it at most once. Test latency, jitter, burst loss, client pause/resume, endpoint rebinding, and reconnect during an action.
A long-running public-host soak test at the configured player/view-distance limits holds tick time, memory, file handles, socket buffers, persistence backlog, and outbound bytes inside stated budgets. Test a slow receiver and a connect/input flood alongside normal players.
Generator/content/mod manifest mismatch, corrupted sparse chunk data, interrupted save, server restart, and mod exception all fail clearly and recover without silent world divergence.
Linux, Windows, and macOS self-contained server publishes start from an empty deployment directory, write a valid first-run configuration/world, answer /status, accept the documented UDP route, and shut down cleanly.

Publish the measured budgets, supported protocol versions, known limits, and compatibility policy alongside every server release. If a guarantee is not tested, document it as a limitation rather than describing the host as authoritative, secure, or scalable by implication.

2.6 Weather and seasonal climate (authorized post-MVP)

Weather is listed as an MVP non-goal in §2.2 and it does not block the Definition of Done. It has nonetheless been built out as a post-MVP system because it composes cleanly with the day/night rig and the HDRP presentation work, and because a voxel sandbox reads as inert without it. The design and current state are in §17.4. The binding constraint is the same one the whole project follows: every weather value is a pure, deterministic function of the world seed and the persisted weather clock — never an RNG, never accumulated hidden state — so a reload reproduces the same sky, the same storm, the same forecast, and the same point in the year. If a weather feature cannot meet that, it is redesigned or dropped, not shipped with a “close enough” caveat.

Weather must never become a correctness dependency of the MVP systems. Terrain generation, meshing, streaming, saves, and the authoritative server continue to work with the weather system absent or disabled. Gameplay consequences of weather (movement, visibility, spawning, block accumulation) are each individually optional and gated behind their own toggle.

2.7 Crisp playable-survival layer (MVP gameplay extension)

The project needs a playable state before it needs a broad content catalogue. This extension turns the existing sandbox loop into a small, original survival game: the player can explore, gather, craft a minimal tool progression, manage health/hunger, survive a basic night threat, and recover from failure. It is deliberately not a promise to clone Minecraft mechanics, timings, recipes, UI, sounds, or art. Numbers, names, content, and presentation remain project-owned and original.

The completion order is gameplay feel first, then survival stakes:

Controls and camera feel. Keyboard and mouse are the reference platform. Movement must be sampled by the Input System, remain smooth from 30 to 144+ FPS, apply acceleration/deceleration deliberately, have bounded coyote-time/jump buffering, predictable sprint/sneak behavior, responsive block targeting, and no camera jitter from head-bob, floating origin, or frame-rate variation. Mouse look must use raw frame delta, sensitivity/FOV/head-bob options, stable pitch clamping, and explicit cursor/action-map transitions. Gamepad support is required as a first-class binding set (move/look, jump, sprint, sneak, interact, break/place, hotbar, inventory, pause), with dead-zone, response curve, sensitivity, inversion, and rebinding settings; it must never compromise the keyboard/mouse path. Test both input families through menu transitions, low/high frame rate, reconnect/load, and camera-mode changes.
Readable immediate feedback. Every movement state, target, break/use action, pickup, damage, hunger change, craft result, and invalid action needs prompt visual/audio feedback without a repeated per-frame allocation. The crosshair, target outline, hotbar, health/hunger display, interaction progress, and pause state must remain legible at supported resolutions. Presentation may interpolate; it must never conceal an authoritative state change or invent an accepted action.
A narrow survival loop. Define a compact initial chain: gather common blocks, craft basic materials/tools, use a tool to access a better resource, maintain health/hunger, and either avoid or overcome one clearly telegraphed hostile risk. Hunger loss, damage, healing, death, respawn, drops, tool requirements/durability (if enabled), and food use must each have data-driven rules, explicit save/network ownership, and testable outcomes. Do not add systems merely because a familiar voxel game has them.
Server parity where multiplayer is enabled. A standalone-server client may only predict presentation. The server validates food use, cooldowns, movement effects, damage, death/respawn, held item and world actions as one authoritative, idempotent transaction. The local single-player implementation must use the same commands/rules where practical, rather than creating a second contradictory game.

The crispness gate is practical rather than aesthetic rhetoric: scripted controller tests plus manual playtests must show stable look and locomotion, no recurring GC allocations while walking or looking, no lost/duplicated action from sustained input, and prompt response from input to visible motion on the supported hardware baseline. Record the measured frame-time/input-latency envelope in the release notes rather than claiming universally “silky” behaviour.

3. Technical Baseline

3.1 Version baseline

Use the existing project’s fixed toolchain for the whole MVP:

Unity 6000.5.8f1, which is the editor version currently recorded by the local package resolution cache. Ensure Unity writes and Git tracks ProjectSettings/ProjectVersion.txt; it is currently missing and must be restored before the first milestone gate.
HDRP 17.5.0, matching the current Packages/manifest.json and package lock.
Windows 10/11 x64 as the primary runtime target.
Direct3D 12 for the ray-tracing build path.
Direct3D 11 or Direct3D 12 raster fallback, selected only after build testing.
The scripting/API compatibility level selected and committed by this Unity version; runtime code must avoid editor-only or platform-specific APIs outside their adapters.
Git with Git LFS for imported binary assets.

Record exact editor and package versions in ProjectSettings/ProjectVersion.txt, Packages/manifest.json, and the project README. Do not upgrade Unity or HDRP in the middle of an MVP milestone unless an identified blocker requires it.

3.2 Required Unity packages

Audit the template’s existing package list, then retain or add packages only when they have an immediate use. The intended gameplay dependencies are:

High Definition RP.
Input System.
Cinemachine only if camera polish requires it; the basic first-person camera does not need it.
TextMeshPro.
Burst.
Collections.
Mathematics.
Test Framework.
Addressables for externally sourced content and UI/audio catalogs, if the content-loading design needs it; it is not currently present.
Memory Profiler for development only.

The current template includes unrelated AI, analytics, collaboration, purchasing, multiplayer, navigation, 2D, and XR-facing packages. Do not remove packages blindly while the editor is resolving. In Milestone 0, use the package audit in Voxel Workshop to classify each dependency as required, editor-only, transitive, or removable, then remove unused direct dependencies one group at a time with a clean compile/build between groups.

Avoid DOTS Entities for the first version. Burst, Jobs, and native collections provide enough control without forcing the whole game into ECS. Reconsider ECS only if profiling proves GameObject orchestration to be a limiting factor.

3.3 Supported quality tiers

Define these tiers from the start:

Tier	Rendering	Intended hardware	Notes
Low	HDRP raster	Older supported discrete GPUs	Short view distance, reduced shadows, no volumetrics, no DXR
Medium	HDRP raster	Mainstream desktop	Moderate view distance and shadows, SSAO/SSR
High	HDRP raster	Strong desktop	Longer view distance, volumetrics, improved shadows/SSR
DXR	HDRP + hardware ray tracing	Supported DXR GPU and driver	Select ray-traced effects with conservative sample counts

The settings menu must hide or disable DXR when SystemInfo.supportsRayTracing is false, the graphics API is not Direct3D 12, or the active HDRP asset lacks ray-tracing support.

4. Core Architectural Rules

These rules prevent expensive rewrites later:

Block data is not stored as GameObjects. A chunk owns a dense block array. A chunk renderer owns one or a few generated meshes.
The world model is authoritative. Rendering, collision, particles, sound, and UI react to world data; they never become the source of block truth.
Chunk coordinates use integers. Never identify chunks by imprecise floating-point positions.
Generation is deterministic. A seed and integer world coordinate must always produce the same unedited block.
Only edits are persisted. Generated terrain is reconstructed from its seed; player changes are stored as chunk-local overrides.
No Unity API is called from worker jobs unless explicitly supported. Jobs generate plain data; the main thread creates or assigns Unity meshes, colliders, renderers, and objects.
Chunk lifecycle is explicit. Requested, generating, meshing, ready, active, unloading, and pooled/cancelled are tracked states.
Every asynchronous result carries a version token. Stale generation or mesh results must not overwrite a recycled chunk.
Block definitions are data-driven. IDs in saves are stable; visual and physical properties live in ScriptableObjects/catalog data.
Raster rendering is the correctness baseline. DXR enriches visuals but cannot be required for gameplay visibility or interaction.
External assets are quarantined. Vendor files remain unchanged in a dedicated directory; project-specific wrappers, materials, prefabs, and import overrides live elsewhere.
Generated runtime meshes are disposable. They can always be rebuilt from chunk data and must never be included in source control.

5. Unity Project Organization

The HDRP template already exists under Minecraft-HD. Normalize it toward the following layout without editing generated Library, Temp, or Logs content:

Assets/
  _Game/
    Art/
      Materials/
      Terrain/
      VFX/
    Audio/
      Mixers/
      Config/
    Data/
      Blocks/
      Biomes/
      Generation/
      Items/
      Settings/
    Input/
    Prefabs/
      Bootstrap/
      Player/
      World/
      UI/
      VFX/
    Rendering/
      HDRP/
      Volumes/
      CustomPasses/
    Scenes/
      Bootstrap.unity
      MainMenu.unity
      Gameplay.unity
      Testbeds/
    Scripts/
      Bootstrap/
      Core/
      Data/
      World/
        Blocks/
        Chunks/
        Generation/
        Meshing/
        Persistence/
        Streaming/
      Player/
      Inventory/
      Interaction/
      Rendering/
      Audio/
      UI/
      Diagnostics/
    Editor/
      VoxelWorkshop/
        Core/
        Modules/
        UI/
        UXML/
        USS/
        Tests/
    Shaders/
    Tests/
      EditMode/
      PlayMode/
  ThirdParty/
    VendorName_AssetName/
  AddressableAssetsData/
Packages/
ProjectSettings/
UserSettings/              # ignored by Git

5.1 Assembly definitions

Use assembly definitions to make dependencies intentional and iteration faster:

Game.Core
  No dependency on Unity scene objects where practical.

Game.Data
  Depends on Game.Core.

Game.World
  Depends on Game.Core, Game.Data, Burst, Collections, Mathematics.

Game.Player
  Depends on Game.Core, Game.Data, Game.World, Input System.

Game.Presentation
  Depends on the runtime assemblies and HDRP.

Game.UI
  Depends on Game.Core, Game.Data, Input System, TextMeshPro.

Game.Editor
  Editor-only shared utilities and adapters.

Game.VoxelWorkshop.Editor
  The user-facing Voxel Workshop shell and modules. Editor-only; depends on
  Game.Editor and only the runtime assemblies it needs to inspect.

Game.VoxelWorkshop.Editor.Tests
  Edit Mode tests for tool commands, validation, and asset transactions.

Game.Tests.EditMode
Game.Tests.PlayMode

Keep interfaces close to the owning domain. Do not create a general Managers directory or a single global GameManager that owns unrelated systems.

Runtime assemblies must never reference either editor assembly. Voxel Workshop uses the same public domain commands and validators as runtime code where that is safe, so a tool preview cannot invent a second, contradictory implementation of world generation, catalogs, or save parsing.

5.2 Scene responsibilities

Bootstrap.unity: the first build scene. Creates persistent services, applies saved settings, initializes Addressables, and routes to the menu. Keep it visually empty.
MainMenu.unity: title UI, save-slot checks, new-world seed entry, settings, loading screen entry point.
Gameplay.unity: camera, player spawn anchor, directional light, sky/fog volumes, world root, audio listeners, and gameplay UI.
Testbeds/*: focused scenes for chunk meshing, generation, block materials, player movement, audio, and DXR validation. Never ship these in the player build.

Use additive scene loading if persistent bootstrap services need to survive scene changes. All subscriptions created by a scene must be removed when that scene unloads.

5.3 Prefabs and data assets

Important prefabs:

AppRoot: save service, scene loader, settings service, input mode service, and diagnostics.
WorldRoot: world database, generator, chunk scheduler, streaming controller, and chunk pool.
ChunkView: MeshFilter, MeshRenderer, MeshCollider, chunk-coordinate component, and optional ray-tracing/rendering metadata.
Player: CharacterController, movement motor, camera pivot, interactor, inventory owner, and footstep source.
GameplayHUD: crosshair, target state, hotbar, interaction progress, debug overlay.

Important ScriptableObjects:

BlockDefinition: stable ID, display name, collision flag, opacity, render class, material/texture references, emitted-light value, sounds, item mapping, and optional hardness.
BlockCatalog: validated mapping between stable numeric IDs and definitions.
BiomeDefinition: surface/subsurface blocks, tree density, and height/noise parameters.
WorldGenerationSettings: seed-independent frequency, amplitude, sea level, cave, and structure settings.
GameQualityProfile: view distance, shadow distance, volumetric quality, mesh budgets, and DXR switches.
AudioSurfaceDefinition: footstep, break, place, and impact clips for a surface family.
ItemDefinition and ItemCatalog: item identity, icon, maximum stack size, and placeable block ID.

ScriptableObjects define content but do not own mutable runtime or save state.

6. Runtime Architecture

6.1 Service composition

Use explicit serialized references inside a scene/prefab and constructor/method injection for plain C# objects. A small bootstrap composition root may expose a service registry during initialization, but ordinary gameplay code should not repeatedly perform global lookups.

Primary runtime services:

SceneFlowService: menu/gameplay transitions and loading screens.
SettingsService: loads, validates, applies, and persists player settings.
SaveGameService: slot metadata, world edit files, player state, atomic writes, and version migration.
WorldService: authoritative access to block queries and edits.
WorldGenerator: deterministic base terrain generation.
ChunkStreamingController: chooses required chunks around the player.
ChunkScheduler: prioritizes generation, meshing, collider work, and unloads.
ChunkPool: reuses chunk views and associated native buffers where safe.
InventoryService: item stacks, transfers, and hotbar state.
AudioService: pooled one-shots, snapshots, and surface sound lookup.

6.2 High-level data flow

Player position
    -> ChunkStreamingController determines desired coordinates
    -> ChunkScheduler requests missing chunk data
    -> WorldGenerator produces deterministic block arrays in jobs
    -> SaveGameService overlays saved edits
    -> Neighbor availability marks chunks meshable
    -> ChunkMesher emits vertices, indices, normals, UVs, and material ranges
    -> Main thread uploads Mesh and assigns MeshCollider
    -> ChunkView becomes visible and interactive

Player block action
    -> PlayerInteractor raycasts/voxel-traverses to a block coordinate
    -> WorldService validates and changes the authoritative block
    -> SaveGameService records the chunk-local edit
    -> Owning chunk and affected boundary neighbor become dirty
    -> ChunkScheduler remeshes dirty chunks
    -> Presentation plays sound/particles and updates inventory

6.3 Update loops

Use Update for input sampling, camera look, UI, target acquisition, and streaming decisions.
Use FixedUpdate only if a Rigidbody-based controller is chosen. The recommended CharacterController motor runs in Update with explicitly integrated gravity.
Use jobs for terrain generation and mesh-data calculation.
Use a frame-budgeted main-thread queue for mesh upload, collider assignment, chunk activation, and destruction/pooling.
Do not start unbounded Task.Run operations. Use Unity Jobs or a small cancellable scheduler whose ownership and shutdown are explicit.

7. World Data Model

7.1 Coordinates

Define three coordinate types:

WorldBlockPosition: integer X/Y/Z block location.
ChunkCoordinate: integer X/Z, and Y too if vertical chunk sections are adopted.
LocalBlockPosition: bounded coordinates within a chunk.

Recommended initial dimensions:

Chunk footprint: 16 x 16 blocks.
World height: 128 blocks for the first implementation.
Vertical storage: eight 16-block-high sections per X/Z column, or one 16 x 128 x 16 array for the earliest prototype.
Block scale: 1 Unity unit per block.

The sectioned representation is preferred for production because empty vertical regions can be skipped, colliders are smaller, dirty updates are localized, and culling is more effective. It adds bookkeeping, so implement one full-height prototype first only if needed to validate generation quickly.

Conversions must correctly handle negative coordinates. Use floor division and a positive modulo helper; C# integer division and remainder alone produce incorrect local positions for negative world coordinates.

7.2 Block representation

Start with a 16-bit stable block ID:

0 = Air (reserved forever)
1..65535 = catalog-controlled definitions

Store block IDs in a flat contiguous array with a documented index function. For example:

index = localX + sizeX * (localZ + sizeZ * localY)

Profile different memory orders only after the algorithms are correct. The generator, mesher, serializer, and tests must share one index helper to prevent mismatches.

Runtime-only block properties should be compact lookup tables copied from the catalog, allowing Burst jobs to test opacity, solidity, and render class without dereferencing ScriptableObjects.

7.3 Render classes

Support only these initially:

Invisible: air.
Opaque: dirt, stone, wood, and similar blocks.
Cutout: leaves or foliage using alpha clipping.
Emissive: opaque blocks with HDR emission.
Transparent: reserved for post-MVP glass/water because sorting and mesh separation add complexity.

Opaque and cutout geometry must be in separate submeshes or renderers/material groups. Do not build one GameObject per material or per block.

7.4 Chunk state

Each loaded chunk/section tracks:

Coordinate.
Lifecycle state.
Version/generation token.
Block buffer ownership.
Base-generation completion.
Loaded edit overlay status.
Mesh dirty flag.
Collider dirty flag.
Neighbor-presence mask.
Last access/frame priority.
Mesh/collider version.
Save dirty flag.

Chunk state changes go through a small state machine. Assertions should reject illegal transitions during development.

8. Procedural Generation

8.1 Determinism contract

Given the same:

World seed.
Generator version.
World block coordinate.
Generation settings version.

the base block must be identical on every run. Do not use UnityEngine.Random inside world generation. Use a coordinate-hashed deterministic PRNG or Unity Mathematics random instances seeded per independent feature and chunk.

Store a generatorVersion in the save metadata. If generation rules change, either keep the old generator available for old worlds or declare saves incompatible and show that clearly in development builds.

8.2 Terrain pass order

Implement generation as explicit passes:

Height field: combine one low-frequency continental noise and one higher-frequency detail noise.
Base fill: bedrock at the bottom, stone below the surface, then a configurable subsurface depth and top block.
Caves: apply a conservative 3D noise threshold below the surface; prevent giant disconnected holes in the first tuning pass.
Surface correction: replace blocks exposed by caves/terrain according to simple rules if required.
Structures: place trees from deterministic candidate points, not once per chunk in isolation, so borders do not create gaps or duplicates.
Edit overlay: apply saved player edits last.

Use a one-block neighbor sampling margin for generation features that cross chunk boundaries. A tree rooted in one chunk may write into a neighbor through a deterministic structure query or deferred cross-chunk placement list.

8.3 Initial world profile

Keep tuning intentionally basic:

One temperate biome.
Rolling hills around a fixed sea-level reference, even if water is omitted.
Dirt/grass surface over stone.
Sand below a selected low-height threshold.
Sparse trees on sufficiently flat grass.
Rare caves below the upper surface band.
Bedrock floor.

Expose tuning through WorldGenerationSettings; do not scatter noise constants through job code.

8.4 Generation validation

Create an editor/testbed preview that can render:

A 2D height map.
Surface block colors for many chunk coordinates.
Cave slices at selected Y levels.
Tree candidate points and cross-chunk extents.

Tests must prove repeatability, negative-coordinate continuity, legal block IDs, valid height bounds, and equivalent shared-edge sampling between adjacent chunks.

8.5 Minecraft-like density-world evolution (authorized post-MVP)

The simple height-field generator is a useful baseline, but it cannot independently represent overhangs, natural bridges, floating remnants, multi-level cave rooms, or the relationship between continental scale, climate, and local relief. Evolve it into an original, Minecraft-inspired layered density generator: deterministic and locally evaluable like modern Java Edition worldgen, but with this project’s own field names, equations, world presets, art direction, content, and data. Do not copy Mojang noise settings, JSON, seed algorithms, biome definitions, structure layouts, or terrain presets.

The governing equation remains pure and generation-order independent:

baseBlock(x, y, z) = Generate(
    worldSeed,
    generatorVersion,
    dimensionProfileId,
    contentRegistryVersion,
    worldPosition)

Every random-looking decision derives a stable coordinate hash or a seed salt owned by its pass. Neither UnityEngine.Random, a global mutable PRNG, frame time, chunk load order, nor player position may influence a base-world answer. Saved player edits still overlay the generated answer last.

8.5.1 Target architecture: authored graph, compiled snapshot, Burst evaluation

Keep authoring friendly without allowing ScriptableObjects into jobs.

Author a WorldGenerationProfile ScriptableObject with a stable profile ID, explicit generatorVersion, vertical range, sea level, field parameters, surface-rule set, feature set, and enabled dimension/preset tags. WorldGenerationSettings remains the active profile’s compact gameplay-facing entry point during migration.
Represent composable math as a small closed DensityNode vocabulary: Constant, Noise2D, Noise3D, YGradient, Add, Multiply, Min, Max, Clamp, Abs, Remap, Terrace, Spline, Cache2D, and InterpolateCell. Nodes are data, not arbitrary managed delegates.
Validate the authored graph in Voxel Workshop before a world can use it: no cycles, every reference resolved, legal cell sizes, finite coefficients, bounded output ranges where required, and a deterministic graph hash.
Compile the graph and its content/rule tables into a blittable TerrainGenerationParameters snapshot. TerrainColumnMath, TerrainGenerationJob, and the server’s future Unity-free generator consume only that snapshot. The managed TerrainGenerator is a parity oracle and must use the same operation order, salts, rounding rules, and lookup tables.
Give each independent field a named salt in one registry (TerrainSeedSalts), rather than scattering magic integers. Retiring or repurposing a salt changes the generator version.
Record the generator version, profile ID, graph hash, and content-registry hash in world metadata. A server/client generator mismatch is rejected before chunk replication. Existing worlds keep their compatible generator path; never silently reinterpret unexplored land under a different formula.

The key separation is intentional:

macro fields -> climate/context -> base density -> fluids -> surface rules
             -> carvers/features/structures -> saved edit overlay -> mesh/presentation

Later stages may query declared outputs of earlier stages but must not mutate them. A tree cannot choose mountain placement; a surface block cannot redefine density; an HDRP effect cannot change world data.

8.5.2 Macro geography and terrain context

Build a TerrainGeographySample from globally continuous fields at each X/Z coordinate. It is a context vector rather than a biome ID. The first target fields are:

Field	Range	Purpose
Continentalness	-1..1	Deep ocean, shelf, coast, inland, and continental-interior tendency
Erosion	-1..1	Smooth rolling terrain versus preserved/rugged relief
Ridge/valley phase	-1..1	Broad valley, slope, ridge, and peak placement
Peakness	0..1	Localized high mountain uplift, not a globally uniform mountain biome
Tectonic spine	0..1	Rare cross-biome escarpments and plateau edges
Structural basin	0..1	Broad enclosed depressions and alternate river catchments
Jaggedness	0..1	High-altitude/local relief modulation without static-like terrain
Coast distance	signed blocks	Explicit shoreline and shelf rules, derived from the density/sea result

Translate these fields through authored curves (TerrainSplineSet) rather than multiplying raw noise indiscriminately. For example, continentalness selects a broad baseline, erosion limits how strongly ridge/peak relief survives, and jaggedness matters only above a configured altitude. This makes profiles understandable in World Studio and prevents every climate region from becoming equally mountainous.

Macro variation must be hierarchical and rare enough to read during exploration:

continental tendencies: approximately 1,024–4,096 world blocks;
provinces/basins: approximately 512–1,536 blocks;
mountain belts/ridges: approximately 256–1,024 blocks;
local relief: approximately 32–256 blocks;
surface breakup: 4–32 blocks.

These are tunable ranges, not hard-coded promises. The World Studio heat-map view must expose each field, the final pre-carver density slice, height, slope, and resulting biome so a designer can tell which field caused a landform.

8.5.3 Climate and biome selection in terrain context

Replace independent rectangular temperature/moisture tests with a deterministic ClimateContextSample:

(temperature, humidity, continentalness, erosion, ridgePhase, elevation, coastDistance)

Biome selection is a weighted nearest-match or scored-rule lookup over authored BiomeClimateRule records. Each record includes desired ranges/weights, priority, transition eligibility, surface-rule set, vegetation set, weather profile, structure tags, and a relief response. The selected biome influences materials and decoration; it must not become the sole source of terrain height.

Required rules:

Evaluate climate from global coordinates and the profile snapshot only; never from chunk-local random state.
Use a transition resolver after primary selection. Extreme neighbors must resolve through at least one compatible intermediate biome/province (for example dry steppe, foothills, snowy march, jungle edge, coastal shelf), not abrupt climate cliffs.
Allow the same climate to appear in lowland, plateau, coast, or highland variants through context tags. A cold high plateau and a cold coastal plain should not share identical trees, surface depth, or relief.
Apply elevation-aware lapse/cold rules only after the preliminary density/height context is known, then run one bounded reclassification pass. Do not create an unbounded biome-height-biome feedback loop.
Provide a deterministic fallback biome and log a validation error for an uncovered climate region; no query may return null or depend on rule-list order accidentally.

8.5.4 Base density: move from one surface height to a 3D solid/void decision

Introduce a signed density convention: density >= 0 is base solid and density < 0 is base void. The initial original composition should remain simple enough to profile and reason about:

terrainDensity(x,y,z) =
    verticalEnvelope(y, macroBaseline(x,z), profile)
  + reliefSpline(geography, y)
  + detailOverhangNoise(x,y,z) * overhangWeight(geography, y)
  + highlandJaggedNoise(x,y,z) * jaggedWeight(geography, y)
  - preliminaryCaveDensity(x,y,z)

Implementation sequence:

Define WorldVerticalRange in profile data. Keep the current vertical range during the first migration, then expand only after storage, meshing, save, spawn, lighting, and network budgets are explicitly retuned. Do not assume a Java Edition height range is automatically suitable for this game.
Produce TerrainColumnContext once per X/Z column: macro sample, climate context, selected biome/transition, baseline, sea/snow thresholds, slope hints, and deterministic feature masks. Cache it in the existing column-generation path.
Sample density on a coarse X/Y/Z lattice per chunk section (initially 4×4×4 or 8×4×8 block cells), trilinearly interpolate within each cell, and evaluate exact rules near sign changes, cave/structure boundaries, and surface placement. This avoids an expensive full graph evaluation for every block while keeping chunk borders continuous.
Use global lattice coordinates and a one-cell halo around every generated section. Neighboring chunks must sample the same lattice points and decide the same shared boundary voxels.
Preserve the current height sampler temporarily as a reference baseline. Add parity and visual comparison modes in World Studio before enabling density generation for a new profile.
Derive the surface height from the highest solid density result per column, not the other way around. Surface rules and vegetation consume that derived result.

The first density release must deliberately cap unsupported extremes. Overhangs, arches, and occasional cliff shelves are allowed only through profile-controlled weights and clearances; unbounded floating terrain, sealed player spawns, paper-thin collision shelves, or density fields that destroy river routing are defects, not “interesting randomness.”

8.5.5 Underground morphology: density caves, directed carvers, and retained pillars

Keep cave styles separate so they can be tuned and debugged independently:

System	Shape	Deterministic implementation	Constraints
Cheese chambers	Large connected/scalloped voids	Thresholded, warped 3D density fields	Depth bands, protected surface roof, maximum void percentage
Spaghetti tunnels	Long winding tubes	Seeded spline/path distance field with 3D perturbation	Radius/length limits, protected spawn/surface bands
Noodle tunnels	Small tight branches	Higher-frequency narrow tube field	Rare, depth-limited, no noisy perforated surface
Ravines/rifts	Directed vertical cuts	Cell-owned path carver with finite route	Biome/context gate, floor/roof clearance, water handling
Pillars/remnants	Solid masses inside chambers	Positive density field after cave subtraction	Avoid navigation blockers at structure entrances
Organic caverns	Memorable rooms	Region-owned chambers with scalloped boundaries	Candidate density, cave floor and roof clearance

Compose cave terms explicitly. A positive pillar term is evaluated after subtractive cave terms; carvers either modify density before threshold or apply a named later carve pass, but never both for the same feature. All cave candidates are owned by global cells and query a halo of neighboring cells so they continue across chunk boundaries without duplicate generation.

Add CaveSafetyRules: no accidental opening inside the spawn safety radius, configured minimum roof thickness below ordinary surface, no fluidless void below the absolute floor, and an upper bound on carved percentage per chunk/vertical band. Expose cave style masks and density slices in World Studio, including a toggle for each cave contribution.

8.5.6 Fluids and aquifers

Do not fill every empty voxel below global sea level. After density/carving has identified void:

Fill above-ground ocean and river channels from their explicit sea/river rules.
Sample a region-owned AquiferCell field with local fluid level, floodedness, fluid kind, barrier strength, and permeability.
Resolve only connected/eligible underground voids against the local aquifer decision. The first implementation may use static generated source blocks; runtime fluid simulation remains a separate, capped system.
Reserve deep/hot profile bands for lava candidates. Prevent incompatible nearby water/lava regions from merging through a barrier rule rather than globally flooding a cavern.
Keep aquifer decisions deterministic and local-queryable. A chunk must never require a flood simulation across unloaded terrain to know whether a cave voxel contains water.

World Studio must render aquifer level, floodedness, barriers, and final water/lava slices. Tests cover local dry caves below sea level, elevated cave lakes, deep lava pockets, neighboring-cell barriers, and cross-chunk fluid continuity.

8.5.7 Surface-rule engine and geological illusion

Replace nested material conditionals with ordered, data-authored SurfaceRule records compiled into burst-safe tables. A rule may test:

biome or biome/context tag;
final surface height, sea/snow thresholds, slope, and aspect;
exposed floor/ceiling/under-surface status;
stone depth, water depth, and local aquifer/fluid state;
deterministic noise thresholds and vertical gradients;
cave biome/underground context;
a stable replacement depth/noise value per column.

Each rule returns a material action such as PlaceTop, PlaceFiller(depthRange), ReplaceExposedStone, ApplySnowLayer, PlaceUnderwaterSediment, or KeepBaseMaterial. Rules are deterministic, ordered, and validated for unreachable/overlapping conditions. Document the winning rule ID in World Studio’s inspect tool.

Initial authored rule families:

irregular bedrock gradient at the absolute lower boundary;
deep stone/deepslate-like project-owned material band with rarer deep lava context;
soil depth varied by a small stable noise field rather than a uniform three-block layer;
beach/shelf sand, gravel, and underwater sediment from coast/water context;
badlands-style original banded strata using height, noise perturbation, and biome tags;
snow as a thin rendered voxel layer over surviving grass/rock, with cold weather accumulation rules distinct from permanent high-altitude caps;
exposed cliff rock and cave-ceiling/floor variants;
biome-specific groundcover/vegetation masks that never overwrite structures or saved edits.

Surface processing occurs after base density and fluids but before trees/features. It may replace materials only; it does not add arbitrary terrain mass or hollow out caves.

8.5.8 Feature and structure placement stages

Use explicit, versioned placement stages with globally owned candidate cells. A stage can query earlier immutable outputs and write only its declared domain. The starting order is:

Base density and floor/ceiling classification.
Static aquifer/ocean/river fluid materialization.
Surface rules and strata.
Ores, geodes/crystals, underground vegetation, and cave decorations.
Natural landmarks, trees, fallen logs, shrubs, rocks, and biome flora.
Hidden structures: ruins, mineshafts, shrines, camps, and other project-original discoveries.
Post-placement repair/validation: remove invalid floating decorations, resolve supported blocks, and record diagnostics. It may not randomly retry a failed candidate.
Player edit overlay, then meshing/colliders/lighting/presentation.

Structure placement needs a separate StructureRegionPlanner, not ad hoc block queries:

Region grid and spacing are globally stable; candidates derive from (seed, structureSetSalt, regionX, regionZ).
A placement plan has an anchor, rotation/mirror, bounding box, terrain-fit query, clearances, palette, template/grammar ID, and deterministic rejection reason.
Plans may repeat motifs while varying layout through a bounded grammar or modular template set; the generator must be able to recompute the same plan from the anchor alone.
Use a padded query region when materializing blocks so a plan spanning chunk borders is identical no matter which chunk loads first.
Reject or adapt plans that collide with protected spawn zones, river mouths, incompatible caves, or a higher-priority structure. Priority and tie-breaking are stable and documented.
Structures write generated baseline blocks only. Player edits remain authoritative overlay data; never re-place a structure over a saved edit during reload.

Add a StructureAtlas inspector to Voxel Workshop: seed/region navigation, candidate/rejection reason, bounds, cross-chunk ownership, template preview, and a materialized-versus-planned diff.

8.5.9 World presets, safeguards, and HDRP presentation

Profiles are content, not hidden compile-time forks. Start with these original presets:

Balanced Wilds: default readable exploration, modest overhangs, navigable caves.
Rugged Frontiers: stronger tectonic spines, plateaus, rifts, and sparse dramatic landmarks.
Mistbound Karst: wetter basins, cave openings, stone towers, and controlled aquifers.
Skybreak Experimental: isolated floating forms and extreme density settings; opt-in only, excluded from ordinary saves/server compatibility until heavily tested.

Every preset declares safe-spawn conditions, expected height/cave bounds, performance class, and whether it is eligible for multiplayer/server generator parity. World creation shows the profile, generator version, and a concise visual/risk description; it does not imply that experimental presets are equivalent to the balanced default.

HDRP consumes generated context only as presentation data: biome palette, wetness, snow cover, cloud shadows, local fog density, wind exposure, and optional ray-tracing participation. It must not introduce material choices that disagree with collision/network/save data. Add fixed World Studio capture viewpoints for coast, basin, mountain spine, cave chamber, aquifer, snow cap, structure, dawn, storm, and night so landscapes remain legible at all supported quality tiers.

8.5.10 Delivery slices and acceptance gates

Ship this evolution as save-versioned slices; do not attempt a one-shot generator rewrite.

Slice	Deliverables	Acceptance gate
A: Field foundation	Salt registry, geography/context samples, spline assets, graph hash, World Studio maps, managed/Burst parity	Fixed-seed coordinates and chunk edges match byte-for-byte; every field is bounded and inspectable
B: Climate provinces	Scored biome rules, transitions, terrain-context variants, coast/elevation inputs	No uncovered climate sample in sweep; extreme biome joins include valid intermediate regions; flora/surface changes remain seamless
C: Density terrain	Coarse lattice interpolation, 3D overhang controls, derived surface cache, safe-spawn checks	Adjacent chunks/sections share density and meshes without seams; profiling meets per-chunk budget; no invalid collision shelves in travel soak
D: Caves and aquifers	Distinct cave terms, carvers, pillars, static aquifer cells, debug slices	Every cave family has deterministic fixtures; fluid boundaries are continuous; carve percentage and roof/floor constraints stay inside profile bounds
E: Surface geology	Compiled surface rules, variable strata/depth, snow/sediment/cave surfaces	Rule inspection identifies one deterministic winner; legal palettes only; snapshots approved across all biomes and elevations
F: Features and structures	Region planner, modular templates/grammars, terrain fitting, flora/ore stages	Candidate ownership is generation-order independent; no duplicate/cut structures at borders; saved edits win reliably
G: Compatibility and shipping	Metadata migration, server shared-library parity, captures, long-travel/save/streaming soak	Old worlds remain on their recorded generator; new profile joins reject mismatch; performance and memory budgets hold

Required automated coverage for every slice:

fixed seeds, negative coordinates, profile hashes, and repeated parallel generation;
shared X/Z and vertical-section boundaries, including features/structures that span them;
managed generator versus Burst job versus future Unity-free server generator equivalence;
density sign, height, material, biome, fluid, and structure snapshots at curated coordinates;
property sweeps for finite/range-bounded values, legal block IDs, safe spawn, no out-of-range writes, and no dependency on evaluation order;
deterministic World Studio golden maps/slices and HDRP screenshot review at fixed cameras;
performance soak while sprinting, editing, saving, and streaming across density-heavy terrain.

No density profile becomes the default merely because it creates impressive screenshots. It must meet deterministic, navigability, save compatibility, mesh/collider, memory, and server-parity gates first.

9. Chunk Meshing and Collision

9.1 Meshing stages

Implement in two stages:

Stage A: face-culling mesher

Visit every solid block.
Emit a face only if the adjacent block does not occlude it.
Query neighbor chunk data for faces on chunk boundaries.
Emit positions, normals, triangle indices, UVs, optional tangents, and material/submesh keys.
Use this simple version to validate all block orientations, UVs, boundary updates, and collision.

Stage B: greedy mesher

Merge adjacent coplanar faces only when their block texture/material, normal direction, light data, and other vertex attributes match.
Keep a debug switch to compare naive and greedy output.
Add automated tests that compare visible surface coverage, not exact vertex order.

Do not begin with compute-shader meshing. CPU Jobs + Burst are easier to test, allow collider reuse, and are sufficient for a basic game.

9.2 UV and material strategy

Preferred simple solution:

Build a texture atlas or Texture2DArray from externally licensed block texture sets during import/editor processing.
Use point filtering for a pixel-art style or appropriate filtering for the selected sourced art direction.
Add padding/extrusion around atlas tiles to prevent mip bleeding.
Store per-face texture indices in BlockDefinition because grass and logs need different top/side/bottom appearances.
Use one HDRP-compatible terrain shader/material per render class wherever possible.

Texture2DArray avoids atlas bleeding and simplifies repeated UVs on greedy faces, but all slices must share resolution and format. If the sourced pack cannot meet that constraint, use a padded atlas initially.

The terrain shader must support:

HDRP lighting and shadows.
Base color and normal map if included in the sourced pack.
Mask map or generated defaults for metallic, ambient occlusion, detail, and smoothness.
Alpha clipping for foliage.
Optional emission for emissive blocks.
GPU instancing/SRP Batcher compatibility where applicable.
Ray-tracing pass compatibility or a documented raster fallback.

9.3 Mesh upload

Generate mesh buffers off the main thread using native collections.
Use Unity’s writable mesh data APIs when stable in the selected editor version.
Upload completed meshes through a limited main-thread budget.
Use 16-bit indices when a mesh is guaranteed below 65,535 vertices; otherwise select 32-bit indices.
Call appropriate bounds calculation or set verified bounds directly.
Dispose native buffers deterministically on completion, cancellation, world unload, and editor play-mode exit.
Mark meshes dynamic only if profiling shows it helps repeated updates; do not assume it is beneficial.

9.4 Colliders

Use a MeshCollider per active chunk section for the MVP:

Generate collider geometry only for solid faces.
Exclude cutout-only non-collidable foliage if the definition says it has no collision.
Assign colliders less aggressively than visual meshes: prioritize the player’s current and immediately neighboring chunks.
Never enable a visible nearby chunk without safe collision beneath/around the player.
Re-cook only dirty colliders, not every frame.
Consider a simplified greedy collision mesh separate from the visual mesh if profiling shows cooking cost is high.

9.5 Boundary behavior

If a neighbor is not yet available, either defer the boundary mesh or temporarily emit its faces. The preferred policy is:

Emit temporary boundary faces so the player never sees a hole into unloaded space.
Mark the chunk boundary dirty when the neighbor arrives.
Remesh both sides after a boundary block edit.

Tests must cover all six chunk faces, including top/bottom section boundaries if vertical sections are used.

10. Chunk Streaming and Scheduling

10.1 Desired-set calculation

Each update, derive chunk coordinates from the player position and compute concentric sets:

Collision radius: smallest and highest priority.
Visible radius: chunks with renderers.
Preload radius: generated/loaded but not necessarily rendered.
Unload radius: slightly larger than preload to add hysteresis and prevent thrashing.

Use squared distance and view-direction weighting for priority. A nearby chunk behind the player still outranks a distant chunk in front if collision safety requires it.

10.2 Work queues

Maintain separate priority queues for:

Load saved edits.
Generate block data.
Build visual mesh.
Build collision mesh.
Upload/activate mesh.
Save dirty chunks.
Unload/pool chunks.

Define per-frame budgets for main-thread activation and collider work. Job concurrency is capped based on worker availability and memory. Cancellation means marking work obsolete with a token; every result must verify its owner coordinate and version before applying.

10.3 Initial tuning targets

Begin conservatively:

Visible radius: 6 chunks on Medium.
Preload radius: 7 chunks.
Unload radius: 8 chunks.
Collision radius: 2 chunks.
At most one or two collider assignments per frame during movement.
At most a small fixed number of mesh uploads per frame, adjusted by measured upload time.

These are starting points, not promises. Quality profiles control the values, and the profiler decides final budgets.

10.4 Player safety

Do not spawn the player until the spawn chunk and a safe collision neighborhood are ready.
Show loading progress based on required spawn chunks, not an artificial timer.
If the player outruns collision generation, constrain movement at the safe frontier or prioritize emergency chunks.
Keep the last valid grounded position for recovery from generation/collider errors in development builds.

11. Player Controller and Interaction

11.1 Input actions

Create an Input System action asset with maps:

Gameplay: Move, Look, Jump, Sprint, Break, Place, HotbarScroll, Hotbar1-9, Inventory, Pause.
UI: Navigate, Submit, Cancel, Point, Click, ScrollWheel.
Debug: ToggleOverlay, ToggleChunkBounds, ReloadChunk, FlyMode; exclude or disable in release builds.

Keyboard/mouse is the reference control scheme and must be polished before adding content breadth. Gamepad is a supported alternative rather than a deferred placeholder: define equivalent bindings, per-device sensitivity/dead-zone/inversion settings, and rebinding from the same action asset. Use the Input System for both; do not branch gameplay logic on a specific device. Switch action maps and cursor lock state explicitly when opening menus, loading, pausing, entering chat, or changing camera mode. Keep look/move sampling separate from simulation so the controller stays smooth under variable render frame rates and can feed a fixed authoritative tick later.

11.2 Movement

Recommended implementation uses CharacterController:

Read and normalize movement input.
Transform it by horizontal camera/player orientation.
Apply walk/sprint speed and acceleration.
Integrate gravity explicitly.
Allow jump only when grounded with small coyote-time and ground-snap tolerances.
Apply collision through CharacterController.Move.
Clamp camera pitch and keep yaw on the player root.
Use a small head-bob effect only after movement is stable and provide an accessibility toggle.

Test slopes, steps, jumping against block edges, ceilings, chunk boundaries, changing colliders, high and low frame rates, and pause/unpause.

11.3 Block targeting

Use one of two approaches:

MVP: Physics raycast against chunk MeshColliders, then offset the hit point slightly inward/outward and floor to determine break/place block coordinates.
Robust follow-up: integer voxel DDA traversal through authoritative world data, independent of collider triangle precision.

Maximum reach should be configurable, initially about 5 blocks. Return:

Target block coordinate.
Adjacent placement coordinate.
Hit face normal.
Target block ID.
Owning chunk coordinate.

Show a pooled wireframe/outline object around the targeted block. Do not alter the chunk material to highlight a target because that would split batching or mutate shared material state.

11.4 Breaking and placing

For instant-break MVP behavior:

Validate that a non-air, non-protected block is targeted.
Ask inventory/world rules whether the action is allowed.
Change the block through WorldService.
Resolve and spawn its physical drop(s) through the drop system (§12.1.1); direct-to-inventory is allowed only for an explicitly configured accessibility/creative-mode rule.
Mark visual mesh, collider, and save data dirty.
If the block lies on a chunk boundary, dirty the neighbor as well.
Play sourced audio and a pooled effect using the block’s surface definition.

For placement:

Compute the adjacent coordinate from the hit face.
Confirm the selected stack maps to a placeable block.
Reject placement if the block would overlap the player’s collision volume.
Reject placement into a protected or non-replaceable block.
Change the world block and consume one item only after success.
Dirty, save, and present feedback as above.

Keep validation and state mutation in one command-like operation so inventory and world edits cannot partially succeed.

12. Inventory and User Interface

12.1 Inventory model

Use plain serializable runtime data:

ItemStack
  stableItemId
  quantity

Inventory
  fixed-size slot array
  selectedHotbarIndex

Initial rules:

Nine hotbar slots.
Eighteen additional inventory slots.
Stack limit comes from ItemDefinition, commonly 64.
Add items by filling compatible partial stacks, then empty slots.
Block breaking must define behavior when inventory is full. For the MVP, reject the break and show feedback, or add a physical drop system; never silently delete items.

Inventory operations return a result rather than assuming success. Unit-test add, remove, merge, split, full inventory, invalid IDs, and save round trips.

12.1.1 Physical drops and miniature item presentation

The world needs a first-class dropped-item entity rather than an invisible overflow path. Breaking, harvesting, dismantling, death recovery, machine output and a deliberate player drop all resolve into physical things in the world. A drop has an authoritative payload, position/velocity, pickup delay, owner/claim rule where applicable, and a stable spawn/operation ID; its visual is presentation only. The server owns creation, merging, pickup and persistence, so a retry, reconnect or two players reaching the same object cannot duplicate it.

Every BlockDefinition, flora/harvest definition, machine and tool defines an explicit DropProfile: condition, required capability, output type, quantity/mass range, and any retained state. Defaults must never be guessed from a display name. Ordinary construction blocks normally drop their matching miniature block; foliage drops only things that physically make sense (for example sticks, fibre, fruit, seeds or a sapling), and mined geology returns its actual rock/ore matter rather than a magical refined resource. A broken machine returns recoverable components and releases its real contents under §§30–32 and 37.8.
Discrete objects — block units, tools, apparatus, seeds, components and containers — use a bounded ItemStack payload and may merge only with an identical, compatible stack. Tools and instruments retain serialised material, wear, temperature, charge and contained state; they do not merge merely because their names match. Bulk matter keeps the §30 batch payload, mass, composition, temperature and provenance. It may be placed only in an appropriate dropped container/sack/crate or spilled using its declared physical rules, never reduced to a stack count to make a pickup convenient.
On spawn, a lightweight deterministic ground-item simulation gives the drop a small outward impulse, gravity, terrain collision and a short pickup delay. Nearby compatible drops coalesce within a hard radius and entity cap; the merge operation is atomic and preserves the complete payload/provenance. Use pooled entities and a simple bounded collision query, not one Rigidbody/GameObject allocation per fragment. At the pickup radius, attempt one inventory/container transfer transaction; on a full or incompatible destination leave the drop in the world and give clear feedback.
Dropped matter and durable equipment do not silently expire. They persist with the relevant loaded chunk or an equivalent bounded regional record and participate in death recovery (§31.6). Cosmetic debris may be short-lived only when it represents no payload. If clutter exceeds a measured budget, coalesce compatible drops, require a container, or reject the generating action; never delete matter to recover performance.

Miniature visuals are generated as part of the same deterministic catalogue/atlas build that produces terrain textures (§14.6, §37.7), never hand-maintained as a second set of item art:

A placeable block pickup is a tiny cube using the block’s actual 16×16 face tiles — including its top, bottom and directional side choices — so a grass, ore or machine casing is recognisably the world block in miniature. It is not a flat inventory icon substituted in the 3D world.
A tool, vessel, plant part or other non-cubic item is baked from its authored/procedural front and back 16×16 pixel views into a small, thickness-bearing mesh. The bake preserves its silhouette, directional markings and 3D profile rather than making a one-sided billboard; a held/dropped tool can therefore turn without disappearing or becoming visually ambiguous. Use deterministic fallback geometry/materials for an incomplete definition and make catalogue validation fail loudly.
The world renderer draws one pooled miniature mesh per render recipe with point-filtered pixel textures, a gentle floating bob, and slow deterministic yaw. Rotation phase derives from the drop’s stable ID, so reloads and clients do not reshuffle a pile. Icons in UI may reuse the same generated recipe through an orthographic catalogue bake, keeping hotbar, inventory and world appearance in agreement without rendering live scene objects into UI.

Test drop-profile coverage, full-inventory pickup rejection, merge/split conservation, save/load and chunk-unload persistence, duplicate-action resistance, negative-coordinate placement, collision settling, tool front/back visibility, and fixed-seed visual baselines for block and tool miniatures.

12.2 UI implementation

Use Unity UI Toolkit or uGUI consistently. For the conservative 2022.3 baseline, uGUI + TextMeshPro is acceptable and lower risk for world-space/canvas workflows. Do not mix systems without a specific need.

Screens and overlays:

Loading overlay with stage/progress text.
Main menu and world creation panel.
Gameplay HUD with crosshair and hotbar.
Inventory panel.
Pause menu.
Settings tabs for controls, audio, display, graphics, and accessibility.
Confirmation dialog for destructive save deletion if multiple slots are added.
Development debug overlay.

UI requirements:

Source and ledger the GUI chrome as a coherent, commercially usable asset set: UI font, nine-slice panel/frame textures, cursor, crosshair, slot states, button/selection treatments and small non-item feedback glyphs. Item, block, tool and material icons are explicitly excluded from that intake: they are generated from the authoritative item textures/meshes (§12.1.1), so the inventory always depicts the thing that exists in the world.
Use nine-sliced sprites where possible.
Keep logical text separate from art for future localization.
Provide scalable UI, readable contrast, subtitle-ready notification area, FOV setting, head-bob toggle, camera-sensitivity controls, and remapping if schedule allows.
Never bake key labels into sprites.

12.2.1 Voxel-survival presentation and logistics inventory

The UI should feel immediately at home beside a crisp voxel world — compact hotbar, tactile pixel-scale item art, strong hover/selection feedback and a calm, beautiful hierarchy — while the full inventory should be as fast to operate as a factory/logistics game. This is an original interface and visual system, not a reproduction of another game’s screens, icons, assets, terminology or layout.

Visual language. Source one licensed, coherent GUI-chrome family and record it in Docs/ASSET_LEDGER.md; use it for panels, frames, cursor, font, buttons, focus/selection states and non-item status symbols. Use the generated item recipes from §12.1.1 for every hotbar, inventory, tooltip and recipe slot icon: a block icon comes from that block’s terrain face tiles; a tool icon comes from its baked front/back, thickness-bearing item recipe. Never replace these with a generic external icon or maintain a manually duplicated item-icon sheet. Present both on original nine-sliced panels with restrained pixel detail, readable type, warm material cues and high-contrast active states. The gameplay HUD stays deliberately quiet: crosshair, compact hotbar, concise pickup feedback and only contextually relevant status indicators. Opening inventory may soften/dim the world behind it, but must retain enough of the scene to preserve orientation.
Inventory layout. The player view has a persistent quickbar along its lower edge and a larger, ordered storage grid when opened. Any chest, machine, vehicle or corpse opens as a second, adjacent pane with an explicit source/destination title, capacity, filters and meaningful state. Discrete items read as countable stacks; bulk matter uses a container card showing mass, fill level, composition/assay state, temperature, pressure and compatibility. A container is never made to look like an ordinary stack of 64 merely to make the grid uniform.
Fast, legible transfers. Support drag/drop and precise split amounts, but do not make speed depend on dragging: primary/secondary activation take/place a whole or partial stack; a modifier quick-moves to the best valid destination; another moves all compatible items; and explicit controller/keyboard equivalents expose every action. Hover and focus previews show the exact destination, transfer amount, capacity result and rejection reason before a chemistry/container transaction commits. Provide deterministic sort, search, filter and slot-filter tools; never reorder player storage implicitly after a transfer.
Information at the right depth. A compact tooltip gives name, quantity/mass, condition and intended use. An inspect action expands to provenance, material, wear, stored energy/heat, hazards, compatible ports and assay uncertainty, respecting the knowledge limits in §§30.4–30.5 and §34.3. Warnings must be specific — for example, “sealed vessel: 82% pressure rating” — rather than a generic red item name. Empty/locked/incompatible slots explain themselves instead of silently ignoring input.
Reliable interaction polish. Slot transitions, pickup motion and successful transfers use brief pooled feedback, not noisy animation that delays input. Preserve the selected slot and focused control across close/reopen, save/load and controller/mouse handoff. The layout must work at 100% and 150% scale, narrow resolutions, colour-vision variants and without relying on colour, hover or tiny text alone.

Acceptance tests cover mouse, keyboard and controller transfers; full and partially compatible destinations; split/merge conservation; filters/search/sort determinism; tooltip knowledge gating; UI scaling; and screenshot baselines for HUD, player inventory and two-pane container/machine views.

13. Saving and Loading

13.1 Save layout

Use one directory per world slot outside Assets, under Application.persistentDataPath:

Worlds/<world-id>/
  world.json             # metadata, seed, versions, last played, display name
  player.json            # transform, look, inventory, selected slot, time
  settings-override.json # only if per-world settings are needed
  regions/
    r.<x>.<z>.bin        # chunk edit records grouped by region

JSON is suitable for small metadata and inspection. Use a compact versioned binary format for region edits once correctness is proven. An initial per-chunk file format is acceptable for the prototype but can create excessive small files.

13.2 Persisted chunk edits

Store only differences from generated terrain:

ChunkEditRecord
  formatVersion
  generatorVersion
  chunkCoordinate
  editCount
  repeated(localIndex, blockId)
  checksum

When a player restores a block to the exact generated value, remove that override. This keeps long-lived save data smaller.

13.3 Reliability rules

Snapshot mutable save data before writing it asynchronously.
Write to a temporary file, flush/close it, then atomically replace the prior file where supported.
Keep a last-known-good backup for metadata/player state.
Never write Unity objects or raw ScriptableObject references.
Validate versions, bounds, counts, IDs, and checksums before applying records.
Treat a corrupt region as isolated; report it and preserve the original file instead of deleting it.
Save on explicit Save & Quit, at safe timed intervals, and after a bounded number of edits.
Complete or safely cancel outstanding writes during application quit and world unload.
Add a development command to simulate interrupted writes and corrupt records.

13.4 Save compatibility

Every file begins with a format version. Migrations are explicit functions with tests. Catalog IDs are never reordered after a released save exists; definitions may be deprecated but their IDs remain reserved.

14. External Asset Sourcing and Integration

All authored visual and audio assets must come from external sources. Runtime voxel meshes, generated texture arrays/atlases, material instances, and import-generated metadata are technical derivatives required by the game, not hand-authored content replacements.

14.1 Asset categories to source

Block base-color textures, plus normal/height/mask information if the art direction includes it.
Sky/HDRI assets if not relying entirely on HDRP’s procedural/physically based sky.
One coherent GUI-chrome family: UI font, panels/frames, cursor, crosshair, slot/background states, buttons and non-item status glyphs. Do not source item, tool, block or material icons: the inventory uses the generated item textures and mesh bakes defined in §12.1.1.
Block-break/place impacts or particles if a suitable VFX pack is selected.
Footsteps and block interaction sounds by surface type.
Wind, birds, cave tone, and nighttime ambience.
Menu and gameplay music, if included.
Optional first-person hands/tool models for post-MVP work.
Optional tree/foliage reference assets; actual voxel trees remain generated from block definitions.

14.2 Source policy

Acceptable sources include reputable commercial asset marketplaces, creator storefronts, public-domain/CC0 libraries, and packs with explicit commercial game licenses. For every imported pack:

Preserve the original license and invoice/receipt outside the Unity import tree and reference it in the ledger.
Verify whether modification, redistribution inside a compiled game, attribution, seat count, and source-control sharing are permitted.
Record author, title, source URL, acquisition date, version, license, attribution text, and modified files.
Reject assets scraped from games, fan recreations using Minecraft content, AI-generated packs with unclear training/provenance terms, and uploads with no defensible license.
Avoid trademarked names in filenames and public-facing content.

Create Docs/ASSET_LEDGER.md before importing the first asset. No third-party asset can enter a release build without a complete ledger row.

14.3 Vendor isolation workflow

Import the unmodified package into Assets/ThirdParty/<Vendor>_<Pack>.
Commit the original license file where redistribution allows it.
Never move or edit vendor files unless the package structure makes isolation impossible.
Create project materials, prefabs, atlases, texture arrays, audio definitions, and Addressables entries under Assets/_Game.
Apply import changes with preset assets or editor automation so they are reproducible.
Remove demos and unnecessary files only after recording what was removed and confirming that upgrades are not expected; otherwise exclude them from builds through references and Addressables groups.
Run attribution and asset-reference validation before a release.

14.4 Texture integration checklist

Select one coherent pack rather than mixing incompatible pixel densities and palettes.
Confirm every required block face is present or can be legally derived from pack contents.
Use consistent texture dimensions.
Choose sRGB correctly: base color/emission color in sRGB; normal/mask/height data as linear.
Set normal texture import type appropriately.
Use no compression or high-quality compression during early evaluation; choose platform compression after visual comparison.
Generate mipmaps and test distant terrain for shimmer and atlas bleed.
Create HDRP mask maps from licensed source channels or use explicit constants; do not invent noisy channels that damage the style.
Verify alpha clipping and shadow casting on foliage.

14.5 Audio integration checklist

Normalize clips by category without destroying dynamics.
Use mono for positioned one-shots and stereo for non-positional music/ambience as appropriate.
Configure load type and compression based on length: short effects decompressed or compressed in memory; long ambience/music streamed.
Create an AudioMixer with Master, Music, Ambience, SFX, UI, and Footsteps groups.
Expose decibel parameters, not direct source volume values.
Add several variations per repeated action and randomize pitch/clip conservatively.
Cap simultaneous sources and use pooling.
Include required attribution in the shipped credits.

14.6 Procedural block-texture authoring and handoff

Project-generated placeholder/variant textures are original technical art, not a substitute for unlicensed copied game art. Tools/TextureGen/generate-block-textures.sh is the deterministic authoring/export entry point; Voxel Workshop’s Texture Foundry remains the one-click skin-family generator used by the scene composer. Both must describe their source recipe and never overwrite a hand-painted approved texture without an explicit output path.

A texture recipe records a stable seed, power-of-two resolution (16 through 1024), base/accent palette, noise family/scale/amplitude, accent threshold, dressing layout, and face target. Supported layouts include flat, horizontal bands, vertical bands, and quadrants; supported face targets include Top, Bottom, North, East, South, and West. A block may initially map multiple lateral faces to one side tile, but the authored source names must preserve the intended direction so the renderer can later promote it to six independent faces without renaming assets.
Keep procedural detail intentional and low-frequency enough to read as a crisp voxel tile: value/cellular grain, strata, veins, speckles, ripples, mortar and bounded accent overlays are valid tools. Randomness is seeded and reproducible; no unseeded editor/RNG output is accepted.
The generator supports --open and a configured --editor/VOXEL_TEXTURE_EDITOR command so a generated tile can immediately open in Krita, paint.net, or the operating system’s associated image editor. Manual edits are exported to a separate handoff path by default and are only adopted into a production material through an explicit asset-intake/review step.
Material binding evolves in stages: current blocks may use top/side/bottom slots; then generic vertical/horizontal/quadrant variants; then six directional side slots. The mesher lookup, block definition, material-array ordering, generated-texture manifest, importer, scene composer, and Edit Mode tests change together. A new face must have deterministic fallback to the base side texture so missing art never produces magenta terrain.
Every generated texture is ffprobe-validated before replacement, imported point-filtered with a deliberate compression/mipmap policy, visual-regression captured in HDRP, and attributed as project-generated in the asset ledger. Normal/mask/emission maps use their own explicit recipes and linear import settings; do not derive fake channels by accident from base-color noise.

15. HDRP Rendering Plan

15.1 Project configuration

Create distinct HDRP assets for raster tiers if necessary, plus a DXR-capable high-end asset. Configure:

Linear color space.
HDR output only as a later tested option; ordinary SDR monitors remain the baseline.
Forward or Deferred rendering after comparing feature compatibility; Deferred is a reasonable desktop starting point for many opaque voxel surfaces.
Shadow atlases and cascade count appropriate to the blocky view distance.
SRP Batcher.
Dynamic batching only if actually beneficial; generated chunk meshes are already coarse batches.
GPU Resident Drawer is not assumed available on this conservative baseline.
Camera frame settings that match each feature rather than enabling everything globally.

Keep rendering settings in version-controlled HDRP assets and Volume Profiles, not hidden per-camera overrides.

15.2 Lighting and atmosphere

The Gameplay scene includes:

One directional light as sun/moon key light.
Physically Based Sky or HDRI Sky chosen to match the sourced art.
Global Volume containing exposure, fog, ambient occlusion, reflections, color adjustments, bloom, tonemapping, and optional depth of field.
Volumetric fog on High/DXR only initially.
A simple time-of-day controller that rotates the directional light, changes intensity/color, blends sky/exposure settings, and advances a persisted normalized time.

Avoid a physically complicated atmosphere until block visibility is proven at noon, dusk, night, caves, and emissive interiors. Gameplay must remain readable without ray tracing.

15.3 Block material response

Most blocks should be non-metallic with restrained smoothness. The sourced art determines whether normals and height maps are appropriate. Exaggerated PBR on low-resolution pixel art tends to look noisy, so compare:

Flat base color with simple mask constants.
Base color + normal.
Base color + normal + height/parallax only on High/DXR.

Avoid tessellation on the deformable chunk terrain for MVP. It increases cost, complicates silhouettes, and conflicts with the intentionally cubic geometry.

15.4 Emissive blocks

An emissive block material can contribute visible bloom in all tiers. It does not automatically provide correct gameplay illumination. Options:

Raster tiers: maintain a tightly capped pool of small point lights near visible emissive blocks, or accept emission-only visuals in the MVP.
DXR tier: allow ray-traced global illumination to pick up emission if the selected HDRP version/settings support it reliably.

Do not create an unlimited Light GameObject for every emissive block. Build a proximity-prioritized light proxy system if raster illumination is required.

16. Hardware Ray Tracing Plan

Ray tracing is a quality feature, not a foundation. Implement it only after raster performance and visual correctness pass.

16.1 Platform setup

Enable Direct3D 12 for the Windows player.
Enable ray-tracing support in the selected HDRP asset.
Use a camera/Frame Settings configuration with the required ray-tracing features.
Add Volume overrides for each tested ray-traced effect.
Verify shaders have valid ray-tracing passes and do not silently turn pink or disappear.
Detect support at runtime and fall back before applying DXR profiles.
Maintain a non-DXR graphics settings preset that can recover from unsupported saved settings.

16.2 Recommended feature order

Add and profile one effect at a time:

Ray-traced ambient occlusion: visually suitable for block corners and the least conceptually disruptive starting point.
Ray-traced reflections: useful only if smooth/reflective sourced materials or later water/glass justify it.
Ray-traced shadows: compare against HDRP cascaded shadows; block terrain may already look good in raster.
Ray-traced global illumination: highest potential benefit for caves and emissive blocks, but also the largest performance and temporal-stability risk.

Do not enable every DXR option merely because it is available. Each effect requires a screenshot comparison, GPU timing, memory measurement, and fallback test.

16.3 Dynamic voxel geometry concerns

Chunk edits and streaming change renderer geometry, forcing ray-tracing acceleration structure updates. Mitigate this by:

Keeping chunks moderately sized so one edit does not rebuild a huge mesh.
Coalescing multiple edits within a short interval into one remesh.
Applying a per-frame cap to chunk mesh activation.
Avoiding collider-only renderer changes that unnecessarily affect ray-tracing structures.
Setting each ChunkView’s ray-tracing mode deliberately and testing whether dynamic or automatic handling produces acceptable update cost in the pinned HDRP version.
Excluding distant or short-lived effect meshes from ray tracing when they add little value.
Using raster fallback during heavy world loading if required, then enabling DXR after the nearby set stabilizes.

Measure both mesh generation time and GPU/driver acceleration-structure build time. CPU optimization alone will not solve DXR streaming spikes.

16.4 DXR acceptance criteria

The DXR preset is accepted only if:

Unsupported hardware always starts successfully in raster mode.
Loading, chunk streaming, block edits, and rapid placement do not produce missing geometry or sustained frame stalls.
Ghosting/noise at chunk boundaries and during edits is within the agreed visual tolerance.
A representative target DXR machine maintains the defined frame target at its intended resolution and view distance.
Turning DXR on/off through settings cleanly applies profiles, with a restart prompt only when the graphics API requires it.
The player can recover from a bad graphics configuration by launching into safe raster defaults.

17. Audio, Effects, and Feedback

17.1 Audio behavior

Resolve footsteps from the block directly beneath the player.
Resolve break/place sounds from BlockDefinition -> AudioSurfaceDefinition.
Randomize among licensed variants without immediate repetition.
Drive pause/menu states through AudioMixer snapshots.
Fade ambience by time of day and simple above-ground/below-ground tests.
Stop and return pooled sources when chunks unload; never parent persistent audio to recycled chunk objects without resetting state.

17.2 VFX behavior

Use externally sourced particle textures/VFX assets, integrated into project-owned prefabs:

Block break burst tinted or selected by block type.
Placement puff.
Optional landing dust.
Subtle target highlight.

Pool effects. Keep particle counts low and disable ray tracing for particles unless a measured benefit justifies it.

17.3 Camera feedback

Add after core input is stable:

Very small landing impulse.
Optional head bob.
Field-of-view sprint easing.
Brief break/place hand or camera response if externally sourced animation/model assets exist.

All continuous motion effects need accessibility toggles or intensity sliders.

17.4 Weather system: simulation and presentation

Authorized post-MVP (§2.6). The system is layered so each layer is a pure, deterministic function of the world seed and the persisted weather clock, and each layer only reads the ones above it.

17.4.1 Layers

Seasonal climate. A slow annual cycle over the weather clock. Produces a temperature offset (deep-winter cold to peak-summer warm), an effective-snow-line offset (winter lowers it, summer raises it), and a mild precipitation bias (shoulder seasons wetter). It shifts where and as what precipitation falls, not whether a given hour is stormy. A “year” is a tuned multiple of the day length.
Synoptic pressure. AtmosphericPressureField is a two-octave value-noise barometric surface over the world plane whose sample point is advected against a prevailing wind as the clock advances, so highs and lows drift through. It also yields a horizontal pressure gradient, which WindField turns into near-geostrophic local wind (direction along the isobars, speed from how tightly they are packed, plus a gust term).
Local weather. WeatherModel reads the pressure at the player’s column, the local biome’s precipitation susceptibility (BiomeWeatherProfile — arid biomes need a near-record low; a rainforest weeps at the first dip), the column height against the season-adjusted snow line, and the seasonal temperature offset, and classifies the column as Clear, Rain, or Snow with a 0..1 intensity and a cloud-cover figure. WeatherForecaster runs the same model forward over the next half hour for an in-HUD “rain in ~N minutes” outlook and a barometric trend.
Moisture. SoilMoistureMath tracks one bounded, persisted sub-surface baseline for future vegetation (rain recharges it, snow melts in slowly, clear weather evaporates it). SurfaceWetnessMath tracks a separate transient surface film that soaks fast under rain and dries within minutes; it is not persisted and re-converges on load, and is published as a shader global for a wet-surface pass.
Presentation. Pooled player-following rain/snow ParticleSystems whose emission and slant scale with intensity and wind; blocky drifting voxel clouds that grey and darken with cover; HdrpStormPresentationRuntime (a private high-priority Volume with height fog, moving local volumetric fog banks, and a seeded lightning flash light during heavy rain); StormThunderRuntime (delayed, distance-attenuated CC0 thunder booms keyed to the flash); and RainAmbienceRuntime (a rain bed that fades with intensity and cover). All presentation state derives only from the weather snapshot, the seed, and the clock, so reloading a save never creates a visual discontinuity. The day-cycle sky palette and the light rig dim for storms; the sky, star field, and moon disc keep their own owners.

17.4.2 Persistence

Only the weather clock and the soil-moisture baseline are saved, in the world metadata alongside time of day. Everything else — the current storm, the wind, the forecast, the season, the surface wetness — is recomputed from those two values plus the seed. A save’s worldSeed and generatorVersion guards already protect against replaying weather from a mismatched world.

17.4.3 Roadmap

In rough order, each increment self-contained, deterministic, and behind its own toggle:

Seasonal climate (as above) feeding WeatherModel and readable by vegetation and sky tint.
Weather-driven surface accumulation: a deterministic snow-depth / rain-puddle figure per column derived from recent weather at that column, surfaced first as a shader/overlay effect (no block or mesh mutation), then optionally as real thin snow-layer blocks through the existing edit-overlay path once the meshing cost is measured.
Gameplay consequences, each optional and toggled: reduced effective view distance in heavy fog; wet/icy surfaces affecting movement; rain extinguishing exposed flame; storm/darkness raising hostile-spawn weight. None may become a correctness dependency of an MVP system.
In-world transition cues: wind and ambience ramps ahead of a front, matching the forecast.
Lightning that strikes: during a heavy storm, a seeded bolt hits a local high point and chars or ignites a single block through the edit-overlay path.

17.4.4 Tooling and diagnostics

The Weather Lab Voxel Workshop module previews the pressure field along the wind, each biome’s precipitation threshold, and the next-30-minute outlook for a seed and clock. The F3 overlay shows current weather, intensity, barometric pressure and trend, wind speed, surface wetness, the sky look, and (roadmap) the season. New weather work adds to these rather than printing to the console.

18. Self-Made Tool Suite: Voxel Workshop

The codebase must be organized around a purpose-built, user-friendly Unity editor suite called Voxel Workshop. It is a core product-development surface, not a collection of unrelated debug windows. Designers and programmers should be able to configure, validate, preview, test, and build the game without hunting through Project Settings, raw ScriptableObjects, scene hierarchies, or magic menu commands.

18.1 Product shape

Expose one primary menu entry:

Tools > Minecraft HD > Voxel Workshop

This opens a dockable UI Toolkit EditorWindow with:

A narrow left navigation rail listing modules.
A persistent project-health summary at the top.
A breadcrumb and plain-language purpose statement for the active module.
A main work area with validation messages next to the fields that caused them.
A right-side contextual help panel that explains concepts and links to the relevant local documentation.
A bottom task strip for progress, cancellation, last operation, and Console shortcuts.
Search across blocks, items, assets, tests, settings, and tool commands.

Remember the last module, selection, filter, and splitter positions in editor-user preferences. Do not store personal window layout or paths in shared game data.

The tool must feel safe:

Read-only inspection is the default.
Mutating operations state exactly which assets/settings they will change.
Multi-asset changes have a preview/dry-run summary.
Use Undo.RecordObject, Undo.RegisterCreatedObjectUndo, and proper dirty/asset-save APIs wherever Unity supports undo.
Destructive operations require explicit confirmation and offer a recoverable backup when practical.
Long tasks show real progress, remain cancellable between safe steps, and never pretend the editor is frozen.
Errors use plain language, show the affected asset, suggest a fix, and provide a ping/open action.
One-click automatic fixes are offered only when deterministic and safe.
The tool never edits third-party vendor source assets in place.

18.2 Tool architecture

Organize the editor suite by feature, not by generic utility type:

Assets/_Game/Editor/VoxelWorkshop/
  Core/
    VoxelWorkshopWindow.cs
    WorkshopModuleRegistry.cs
    WorkshopContext.cs
    WorkshopTaskRunner.cs
    WorkshopSelection.cs
    WorkshopPreferences.cs
    WorkshopReport.cs
  Modules/
    ProjectDoctor/
    AssetIntake/
    BlockLibrary/
    WorldStudio/
    ChunkLab/
    SceneComposer/
    SaveInspector/
    GraphicsLab/
    PlaytestLauncher/
    BuildAndQA/
  UI/
    Controls/
    Binding/
    Icons/
  UXML/
  USS/
  Tests/

Each module implements a small IWorkshopModule contract containing stable ID, display name, icon, order, availability, root visual element creation, selection handling, and refresh/dispose hooks. Modules register through an explicit registry; do not discover arbitrary reflection types on every repaint.

Separate these layers:

View: UI Toolkit UXML/USS and small view controllers.
Editor command: one operation with validation, preview, execution, result report, and undo/transaction behavior.
Domain service: reusable project/runtime logic such as catalog validation or generation sampling.
Unity adapter: AssetDatabase, serialized properties, build pipeline, scene editing, HDRP settings, or file-dialog access.

Editor commands should be callable from Edit Mode tests without opening the window. UI callbacks must not contain catalog generation, file parsing, scene mutation, or build logic.

Use SerializedObject/SerializedProperty for authoring Unity assets so multi-object edits, undo, prefab overrides, and future property changes behave correctly. Plain-data reports may use immutable records/classes. Tool state must never be stored in runtime ScriptableObjects unless it genuinely changes game content.

18.3 Shared visual language

Create a restrained project-owned USS theme using Unity editor variables so it works in light and dark editor themes. Reuse a small control set:

WorkshopHeader: title, description, documentation link, and main action.
HealthBadge: Passed, Warning, Failed, Running, or Unknown with icon and text; never color alone.
ValidationList: group issues by severity and asset, with Fix/Ping/Open actions.
AssetPickerCard: source preview, license state, destination wrapper, and compatibility.
BeforeAfterPanel: preview import/material/build changes.
MetricCard: value, budget, recent trend, and capture source.
EmptyState: explains why there is no content and gives the next safe action.
TaskProgress: stage, completed/total work, elapsed time, cancellation.

Use consistent verbs: Create, Validate, Preview, Apply, Revert, Ping, Open, Run, Capture, Build. Avoid vague buttons such as Do It, Process, or Fix Stuff.

Every module must work at 100% and 150% UI scaling, at a narrow docked width, with keyboard navigation, and without relying solely on hover tooltips.

18.4 Module 1: Project Doctor

Purpose: answer “Is this Unity project correctly configured, and what should I fix next?”

Checks:

Unity project root is Minecraft-HD and the active Git root matches it.
ProjectSettings/ProjectVersion.txt exists and records the expected Unity editor.
HDRP 17.5.0 and all required package versions are internally consistent.
No compilation errors, missing scripts, broken GUID references, or accidental editor assembly references from runtime code.
Color space, graphics APIs, HDRP assets, Quality levels, Input System, serialization mode, visible meta files, and version-control mode are correct.
Required folder, assembly, scene, layer, tag, Addressables, and build-profile structures exist.
Library, Temp, Logs, builds, memory captures, and user settings are ignored.
Direct package dependencies are classified as Required, Optional, Pending Removal, or Unknown.
No production content lives outside _Game or approved ThirdParty roots.

Actions:

Scan Project produces a timestamped WorkshopReport.
Preview Safe Fixes lists deterministic changes.
Apply Selected Fixes changes only checked items with undo/backup where available.
Export Report writes a human-readable file under Docs/Reports, not under Assets.

This module is the first page on a failed health scan and the default page after opening a newly cloned project.

18.5 Module 2: Asset Intake

Purpose: make externally sourced assets legally traceable and technically consistent before gameplay uses them.

Workflow:

Select an imported third-party pack or staged source directory.
Enter vendor, pack name, source URL, version, acquisition date, license identifier, attribution, receipt/license location, and permitted uses.
Scan textures, audio, models, fonts, shaders, demos, scripts, and dependencies.
Display compatibility warnings for built-in/URP materials, unsupported shaders, inconsistent texture sizes, missing normal maps, unsuitable audio import settings, or editor scripts.
Choose project-owned wrapper outputs under Assets/_Game; never alter vendor originals.
Preview the ledger entry, import presets, generated HDRP materials, audio surface definitions, catalog candidates, and Addressables labels.
Apply through one transaction and write/update Docs/ASSET_LEDGER.md.

Required safeguards:

An asset cannot be marked Release Approved without a license value and source evidence.
Unknown or incompatible licenses remain visible as blocking errors in Build & QA.
License fields are metadata, not legal advice; the tool never claims a license is valid merely because fields are filled.
Derived atlases, texture arrays, mask maps, materials, and prefabs record their source asset GUIDs.
Re-running intake is idempotent and shows changed source files.

18.6 Module 3: Block Library

Purpose: author the complete block/item catalog through guided forms and visual previews.

Views:

Searchable table with ID, name, render class, collision, opacity, item mapping, textures, material, sound family, emission, validation state, and usage count.
Detail view with top/side/bottom face assignment and a lit rotatable cube preview.
Side-by-side raster material preview under noon, night, and cave presets.
Stable-ID reservation view showing Active, Deprecated, Reserved, and Missing definitions.
Batch editor for shared physical/audio/render properties.

Actions:

Create a block from an approved Asset Intake candidate.
Duplicate configuration while requiring a new stable ID.
Generate or rebuild project-owned atlas/texture-array data.
Validate texture dimensions, face coverage, render-class/material compatibility, item links, sound links, and save-stable IDs.
Show all chunks/test assets referencing a definition before deprecation.

The tool must prohibit ID reassignment after an ID is recorded in the release manifest. Deletion becomes deprecation with a fallback definition; it never silently shifts later IDs.

18.7 Module 4: World Studio

Purpose: let a developer tune deterministic world generation without repeatedly entering Play Mode.

Features:

Seed field with randomize, copy, paste, and favorite controls.
World-generation profile selector and duplicate-as-new workflow.
2D tabs for height, surface material, cave slice, density, structure candidates, and biome map.
3D preview of a selectable chunk region using the real runtime generator and mesher.
X/Z/Y navigation supporting negative coordinates.
Before/after comparison between two generation profiles or generator versions.
Statistics for height range, block counts, cave percentage, generation time, mesh face count, and structure counts.
Seam inspector that compares shared borders and highlights mismatches.
Golden-snapshot creator for deterministic Edit Mode tests.

Changes update only serialized generation settings. Preview jobs use isolated buffers, are cancellable, and cannot write to a real save.

18.8 Module 5: Chunk Lab

Purpose: make voxel data, meshes, boundaries, performance, and lifecycle observable in one focused test environment.

Features:

Create canonical fixtures: one block, solid chunk, hollow chunk, checkerboard, staircase, boundary faces, random seeded fill.
Inspect a chunk by coordinate and slice its X/Y/Z block data.
Compare naive and greedy mesh output.
Overlay face normals, bounds, submeshes, UV tile indices, collision mesh, neighbor availability, and ray-tracing participation.
Report block count, visible faces, vertices, indices, submeshes, memory, generation time, Burst mesh time, upload time, and collider-cook time.
Apply a scripted edit sequence and detect stale meshes or missed boundary invalidation.
Export a reproducible fixture/report for a bug without exporting licensed source textures.

Chunk Lab uses the same jobs and uploader adapters as gameplay. A special “tool-only mesher” is forbidden because it would hide production defects.

18.9 Module 6: Scene Composer

Purpose: create and validate the small set of required scenes/prefabs predictably.

Features:

Show cards for Bootstrap, Main Menu, Gameplay, and each approved Testbed.
Create a missing scene from project-owned templates.
Validate required roots/components, duplicate service instances, camera/audio listener count, HDRP volumes, directional light, layers, input references, and scene build order.
Open a scene additively or alone with an unsaved-change prompt.
Rebuild only generated wiring; preserve intentional designer changes.
Preview the exact hierarchy diff before applying repairs.

Scene Composer must identify components by stable serialized references or marker components, not fragile hierarchy-name searches.

18.10 Module 7: Save Inspector

Purpose: inspect and safely diagnose world persistence without a hex editor or custom throwaway scripts.

Features:

List save slots, metadata, versions, seed, player position, last played time, disk usage, dirty/backup status, and compatibility.
Browse regions/chunks and view sparse edits over the regenerated base block.
Filter edits by block, coordinate, region, and timestamp if recorded.
Validate checksums, IDs, bounds, generator version, and migration availability.
Compare primary and backup files.
Export a redacted diagnostic report.
Clone a save to a clearly labeled development copy before any repair or migration test.
Run migrations only on the copy by default; require confirmation and backup for an original.

Never open a real save with write access for ordinary inspection. Destructive edit deletion or region repair requires a preview of exact records affected.

18.11 Module 8: Graphics Lab

Purpose: centralize HDRP, material, quality, and ray-tracing validation for this project.

Features:

Matrix of Low/Medium/High/DXR profiles and the HDRP features each enables.
Hardware/API capability readout, including Direct3D version and ray-tracing support.
Validate HDRP Global Settings, pipeline assets, Frame Settings, Volume Profiles, terrain shader passes, material compatibility, and ChunkView ray-tracing modes.
Load fixed lighting test presets: noon, sunset, night, cave, emissive room, foliage edge, and distant mip view.
Toggle one DXR feature at a time and capture labeled raster/DXR comparison screenshots.
Show CPU/GPU frame timing, renderer count, triangle count, memory, and acceleration-structure update behavior during scripted chunk edits.
Apply a selected quality profile to the testbed without silently changing release defaults.

Graphics Lab reports unsupported configurations; it must not force DXR on unsupported machines. All captures record Unity/HDRP version, scene, seed, coordinate, resolution, quality, and active effects.

18.12 Module 9: Playtest Launcher

Purpose: turn common test scenarios into one-click, repeatable entry points.

Scenario assets define:

Scene.
Seed and generator profile.
Spawn coordinate and look direction.
Time of day.
Inventory contents.
Quality tier and allowed DXR behavior.
Debug overlays.
Optional scripted travel/edit sequence.
Temporary-save policy.

Built-in scenarios include Fresh Spawn, Negative Coordinates, Chunk Boundary, Sprint Streaming, Rapid Edit, Cave Lighting, Night Emission, Inventory Full, Save Round Trip, Raster Baseline, and DXR Edit Stress.

The launcher snapshots the developer’s open scenes and play-mode settings, uses a disposable test save unless explicitly told otherwise, and restores editor state after Play Mode.

18.13 Module 10: Build & QA

Purpose: provide one reliable path from current workspace state to a testable player build.

Features:

Named project-owned build profiles for Development Raster, Release Raster, and Release DXR-Capable Windows x64.
Preflight checks for compile errors, tests, scenes, package state, missing references, asset licenses, catalog IDs, save versions, HDRP profiles, graphics API, development-only objects, and build output path.
Selectable Edit Mode, Play Mode, deterministic snapshot, and smoke-test suites.
Build manifest recording Git commit when available, dirty-state flag, Unity/HDRP versions, packages, block catalog hash, generator/save versions, included Addressables/content, quality defaults, and timestamp.
Post-build smoke launch with log capture.
Open build folder and exported report actions.

The Build button stays disabled when a release-blocking license, compile, catalog, scene, or configuration issue exists. Development builds may proceed past explicitly acknowledged non-release warnings, which remain in the manifest.

Voxel Workshop must never commit, sign, or push. Source-control publication remains a separate explicit workflow and, per GROUND_RULES.md, may use only the configured global Git identity.

18.14 Tool quality requirements

Every Voxel Workshop module requires:

A short local user guide under Docs/Tools.
Edit Mode tests for its non-visual command logic.
At least one empty-state test and one error-state test.
No uncaught exception from missing optional content.
No repeating allocations/rebuilds from idle editor repaints.
Correct subscription cleanup on window close, assembly reload, play-mode change, and editor quit.
Undo verification for supported asset/scene changes.
Idempotency tests for create/setup/import commands.
A report object or structured result that can be shown in the UI and tests.

Tool actions must be deterministic where possible. If an action depends on the current scene, selection, build target, graphics API, or save path, show that context before execution.

18.15 Tool implementation order

Build Voxel Workshop vertically instead of scaffolding ten empty tabs:

Shell, module registry, shared controls, task runner, reports, and Project Doctor.
Asset Intake and Block Library before importing/authoring production block content.
World Studio and Chunk Lab alongside generator and mesher implementation.
Scene Composer and Playtest Launcher alongside gameplay scene development.
Save Inspector alongside persistence.
Graphics Lab alongside HDRP/DXR work.
Build & QA before the first distributable milestone build.

A module is considered present only when its primary workflow is usable, tested, and documented. Placeholder navigation entries should be labeled “Planned” and disabled rather than opening empty panels.

19. Runtime Diagnostics and Developer Overlays

Build observability alongside the systems:

On-screen FPS, CPU frame time, GPU frame time, managed memory, and native allocation counters.
Current world/chunk/local coordinates.
Loaded, visible, queued, generating, meshing, collider, and dirty-save chunk counts.
Generation/meshing/upload/collider timing averages and worst recent values.
Drawn chunk bounds colored by lifecycle state.
Player ray target and face normal.
Current seed and generator version.
Current quality/HDRP/DXR state.
Save queue status and last save error.

Add development console commands or debug buttons for:

Teleporting to coordinates, including negatives.
Setting time of day.
Forcing save/load.
Regenerating or remeshing a chunk.
Toggling naive/greedy meshing.
Toggling collider visualization.
Cycling quality profiles and DXR effects individually.
Simulating slow generation and corrupt save data.

Diagnostics must compile out or be inaccessible in release builds where appropriate.

Voxel Workshop provides editor workflows; it does not replace in-player runtime telemetry. Build observability alongside the systems:

20. Testing Strategy

20.1 Edit Mode tests

Prioritize pure and deterministic systems:

Negative and positive world/chunk/local coordinate conversion.
Flat-array indexing bounds and uniqueness.
Catalog validation and stable IDs.
Deterministic noise/generation snapshots at fixed coordinates and seeds.
Neighbor-edge continuity.
Tree placement consistency across generation order.
Visible-face counts for known block patterns.
Greedy mesh surface equivalence.
Inventory merging, splitting, full capacity, and removal.
Edit overlay add/remove behavior.
Save binary encode/decode, checksums, version failures, and migration.
Quality-profile validation.

20.2 Play Mode tests

Bootstrap -> menu -> new world -> gameplay flow.
Spawn waits for safe chunks.
Walk/jump/collision across a chunk boundary.
Break and place blocks on every local boundary face.
Edited blocks survive save, scene reload, and application restart simulation.
Inventory and selected hotbar slot persist.
Repeated world enter/exit leaves no live jobs, native allocations, or orphan meshes.
Unsupported DXR selection falls back without preventing startup.
Pause correctly changes input maps and cursor state.

20.3 Manual test matrix

Test at minimum:

1080p Low/Medium/High raster.
1440p High raster on the main development GPU.
DXR at the chosen target resolution with upscaling only if available and stable in the pinned version.
Fresh world and a heavily edited world.
Standing still, normal travel, sprinting straight across new terrain, rapid turning, rapid block edits, dusk/night, caves, and save/quit during dirty work.
Keyboard/mouse, and gamepad once declared supported.
Normal disk, nearly full disk, read-only/corrupt save scenarios where practical.

20.4 Visual regression captures

Capture fixed seed/camera test scenes for:

Noon terrain.
Sunset terrain.
Night with emissive blocks.
Cave lighting.
Foliage cutout edges.
Distant mip behavior.
Raster versus each DXR effect.
A chunk edit before, during, and after remeshing.

Keep exposure, seed, coordinates, time, resolution, and quality profile in capture metadata.

21. Performance and Memory Budgets

Set budgets early, then tune them on actual target hardware. Initial goals for a 1080p Medium raster build:

60 FPS target with 16.67 ms total frame time.
Main thread normally below 8 ms, leaving headroom for spikes.
No recurring managed allocations during stable gameplay after warm-up.
Chunk activation work spread across frames with no routine frame above 33 ms during normal walking.
World generation and meshing remain off the main thread except upload/Unity object work.
Memory remains bounded by load radii; travelling continuously should reach a stable plateau rather than grow indefinitely.
Save writes do not visibly hitch ordinary gameplay.

For DXR, define a separate target after measuring the chosen reference GPU; 30 or 60 FPS can be selected explicitly. Do not conceal failure with an undefined target.

Profile in built players, not only in the Editor. Use Unity Profiler Timeline, Memory Profiler, Rendering Debugger, Frame Debugger, and a GPU capture tool compatible with the selected hardware/API.

Optimization order:

Confirm work is necessary and scheduled once.
Eliminate per-block GameObjects and repeated allocations.
Fix chunk thrashing and stale work.
Burst/job generation and meshing.
Greedy mesh visible faces.
Limit main-thread mesh/collider upload work.
Reduce material/submesh/render-state count.
Tune shadows, fog, post-processing, and view distance.
Tune individual DXR effects and acceleration-structure updates.

Do not optimize noise functions while chunk lifecycle bugs are scheduling the same chunk repeatedly.

22. Implementation Milestones

Each milestone ends with a runnable build or isolated testbed and a pass/fail gate. Do not start later polish while an earlier correctness gate is open.

From C1 onward, a correctness gate is not the only kind. §36.4a defines the P-gate — the requirement that a slice be reachable, legible and durable for an actual player in a clean build before the next milestone opens — and it binds every milestone in this plan, Part I’s included.

Milestone 0: Project bootstrap and content policy

Tasks:

Create the Unity 2022.3 HDRP project in this directory.
Configure Git ignore rules and Git LFS for appropriate binary types.
Pin packages and record tool versions.
Create folder/assembly structure.
Create Bootstrap, MainMenu, Gameplay, and testbed scenes.
Implement app composition root, scene flow, logging, and settings skeleton.
Create Docs/ASSET_LEDGER.md and record the first sourced assets.
Establish a Windows raster development build.

Gate:

A clean checkout opens without missing packages, reaches the empty Gameplay scene through the menu, and builds for Windows without errors.

Milestone 1: Block catalog and single static chunk

Tasks:

Implement coordinate types, array indexing, block IDs, definitions, and catalog validation.
Integrate a licensed external block texture pack.
Build the HDRP terrain material/shader path.
Generate one in-memory test chunk with a flat layer pattern.
Implement the naive face-culling mesher, MeshRenderer, and MeshCollider.
Add chunk-bound and face-count debug visualization.

Gate:

One chunk renders correctly from all sides, has correct top/side/bottom textures, collides, casts/receives shadows, and passes coordinate/index/mesh-count tests.

Milestone 2: Deterministic generated world

Tasks:

Implement seeded height noise, layering, caves, and trees in deterministic passes.
Add generation preview tools and fixed-seed tests.
Generate a grid of chunks around a fixed origin.
Resolve neighbor face culling and cross-chunk structures.
Validate negative coordinates.

Gate:

A fixed seed reproduces byte-equivalent base block data, adjacent chunks have no seams, trees do not duplicate at borders, and generation-order changes do not alter the result.

Milestone 3: Player and block interaction

Tasks:

Create Input System actions.
Implement CharacterController movement and first-person camera.
Implement block targeting and outline.
Add authoritative break/place operations.
Add a temporary debug hotbar with block selection.
Remesh chunks and boundary neighbors after edits.

Gate:

The player can walk, jump, target, break, and place blocks across every chunk boundary without holes, phantom collision, self-entombing placement, or state disagreement.

Milestone 4: Streaming, jobs, and pooling

Tasks:

Add chunk lifecycle state machine and version tokens.
Move generation and mesh calculation into Burst jobs.
Add desired-set radii, priority queues, cancellation, frame budgets, and chunk pooling.
Add safe spawn loading and collision prioritization.
Add diagnostics for queues and timings.
Travel-test for memory plateau and stale-result safety.

Gate:

Continuous sprint travel generates and unloads terrain without falling through, incorrect recycled chunks, native leaks, unbounded memory growth, or routine long frame stalls on reference hardware.

Milestone 5: Inventory, HUD, and sourced feedback assets

Tasks:

Implement item catalog, stack rules, hotbar, and inventory storage.
Integrate externally sourced UI sprites/icons/font.
Implement HUD, pause, inventory, and settings UI.
Integrate externally sourced footsteps, break/place sounds, ambience, and UI sounds.
Add pooled interaction VFX using sourced assets.
Resolve full-inventory behavior.

Gate:

Every break/place action produces consistent world and inventory state, UI handles mouse/controller focus correctly, repeated audio/VFX are pooled, and all included assets have ledger/license entries.

Milestone 6: Persistence

Tasks:

Implement world metadata and player state files.
Implement generated-terrain edit overlays and region storage.
Add atomic writes, backups, autosave, checksums, and format versions.
Add save/load progress and errors to the UI.
Add round-trip, corruption, and interrupted-write tests.

Gate:

A world with edits in positive and negative coordinates reloads exactly, player/inventory/time persist, restoring generated blocks removes redundant edits, and a deliberately corrupt file does not destroy the last-known-good save.

Milestone 7: HDRP raster presentation

Tasks:

Establish Low/Medium/High HDRP assets and profiles.
Add sky, sun, time of day, exposure, fog, post-processing, and restrained material response.
Implement emissive visual handling and optional capped raster light proxies.
Tune foliage, mipmaps, shadows, and view distances.
Capture fixed-seed visual baselines.

Gate:

Raster tiers are readable at noon/night/caves, meet agreed performance targets on reference systems, switch reliably, and show no severe atlas bleeding, shimmer, broken shadows, or exposure jumps.

Milestone 8: Optional DXR quality tier

Tasks:

Configure D3D12 and a ray-tracing-capable HDRP asset.
Implement hardware/API capability checks and safe fallback.
Add RTAO first, then individually evaluate reflections, shadows, and GI.
Profile chunk streaming, rapid edits, and acceleration-structure updates.
Exclude low-value renderers/effects where needed.
Add settings controls and fixed comparison captures.

Gate:

DXR produces a clear approved benefit, meets its explicit performance target, survives streaming/edit stress, and never blocks raster startup on unsupported hardware.

Milestone 9: Optimization, QA, and release candidate

Tasks:

Implement greedy meshing if profiling justifies it and it has not already landed.
Resolve all steady-state managed allocations and native leaks.
Validate Addressables/build content and remove accidental demo references.
Complete credits, attribution, licenses, settings defaults, and safe mode.
Run automated tests and the full manual matrix.
Make a clean-machine Windows build and perform a long travel/edit/save soak test.
Create known-issues and save-compatibility notes.

Gate:

The release checklist below passes with no critical defects and no unlicensed or untracked asset in the build.

23. Suggested Code-Level Work Breakdown

Implement these types in roughly this dependency order. Names can change, but responsibilities should remain narrow.

Core and data

StableId16: validated ID value type.
WorldBlockPosition, ChunkCoordinate, LocalBlockPosition: integer coordinate value types.
VoxelMath: floor division, positive modulo, flatten/unflatten helpers.
BlockDefinition, BlockCatalog, BlockRuntimeTable.
ItemDefinition, ItemCatalog, ItemStack, Inventory.
WorldGenerationSettings, GameQualityProfile.

World model

ChunkData: owns block memory and revision.
ChunkHandle: coordinate, lifecycle, tokens, data/view ownership.
IBlockReader: read-only block queries for generator/mesher/interaction.
IWorldEditor: validated mutations.
WorldService: loaded chunk registry and authoritative query/edit entry point.
ChunkStateMachine: legal transitions.

Generation and meshing

CoordinateHash: deterministic feature seeds.
HeightSampler, CaveSampler, StructureSampler.
GenerateChunkJob and explicit pass helpers.
BuildChunkMeshJob.
MeshBuildResult: native vertex/index/submesh buffers plus bounds and version.
ChunkMeshUploader: main-thread Mesh application.
ChunkColliderBuilder: prioritized collider mesh assignment.

Streaming

ChunkInterestCalculator: desired sets from player coordinate and profiles.
ChunkWorkItem: coordinate, operation, priority, token.
ChunkScheduler: capped jobs and main-thread queues.
ChunkPool and ChunkView.
WorldLoadingProgress: safe-spawn completion state.

Interaction and player

FirstPersonMotor.
FirstPersonLook.
PlayerInteractor.
BlockTarget value type.
BreakBlockCommand, PlaceBlockCommand, or equivalent atomic operations.
TargetOutlineView.
PlayerInventoryController.

Persistence

WorldMetadata, PlayerSaveData, ChunkEditRecord.
WorldEditTracker: keeps sparse overrides and removes generated-value restores.
RegionFileCodec.
SaveGameService.
SaveMigrationRegistry.

Presentation

TimeOfDayController.
GraphicsSettingsApplier and RayTracingCapability.
TerrainMaterialLibrary.
AudioSurfaceLibrary, PooledAudioSource, PooledEffect.
GameplayHUDPresenter, HotbarPresenter, InventoryPresenter, SettingsPresenter.
WorldDiagnosticsOverlay.

24. Risks and Mitigations

Risk	Consequence	Mitigation
One GameObject per block	Unusable CPU/memory/render performance	Dense block arrays and chunk meshes are non-negotiable
Incorrect negative-coordinate math	Corrupt edits and seams west/south of origin	Central helpers plus exhaustive tests
Generation order affects structures	Trees/caves change or break at borders	Coordinate-hashed sampling and cross-border deterministic queries
Stale jobs write into recycled chunks	Visually wrong chunks and possible memory errors	Coordinate + version token validation on every result
MeshCollider cooking spikes	Movement hitching or falling through	Smaller sections, priority radius, simplified greedy colliders, frame budgets
Save format tied to ScriptableObjects	Saves break after catalog changes	Stable numeric IDs and versioned plain data
Too many tiny save files	Slow saves and filesystem overhead	Region grouping after prototype validation
Atlas mip bleeding	Visible seams and noisy distant blocks	Padding/extrusion, texture arrays, mip testing
HDRP cost overwhelms voxel scale	Low frame rate before gameplay is complete	Raster tiers, short initial distance, profile each feature
DXR acceleration rebuild spikes	Stutter during edits/streaming	Coalesce remeshes, cap activations, tune chunk size, selectively exclude renderers
DXR setting saved on unsupported PC	Game fails or appears broken	Capability checks and safe raster defaults
Unclear third-party license	Release cannot legally ship	Asset ledger and release-time validation from day one
Scope expands into full survival game	Core never reaches shippable quality	Enforce MVP non-goals and milestone gates

25. Release Checklist

Gameplay

New World and Continue both work.
Player cannot spawn or routinely fall through unloaded terrain.
Breaking and placing work on ordinary and boundary blocks.
Inventory never duplicates or silently deletes blocks.
Pause/input/cursor states are correct.
Day/night and settings persist.

World and saves

Fixed seeds are deterministic.
Negative coordinates work.
Cross-chunk trees and meshes have no seams.
Edited blocks survive restart.
Autosave and Save & Quit are safe.
Corrupt save data produces a recoverable error.
Save and generator versions are present.

Performance

Stable gameplay produces no recurring managed allocation.
Continuous travel reaches a memory plateau.
Mesh/collider queues remain bounded.
Raster target is met in a player build.
DXR target is separately measured if shipped.
No native collection, mesh, material, audio source, or job leaks after world exit.

Rendering

All quality tiers boot and switch correctly.
Unsupported DXR hardware uses raster fallback.
Block materials, cutouts, shadows, fog, exposure, and emission are valid.
Rapid edits do not leave stale visual or ray-tracing geometry.
Fixed visual test captures have been reviewed.

Content and legal

Every authored asset is external and appears in ASSET_LEDGER.md.
Every license permits the intended distribution.
Required attribution is in credits and accompanying notices.
No Minecraft-owned asset, trademark, source, or copied UI is included.
Vendor demos and unused content are absent from the build.
Git LFS contains intended large binaries without accidentally tracking build output.

Build

A clean checkout imports and builds.
The Windows x64 build runs on a clean supported machine.
Application icon, product name, company name, save path, and version are set to original project values.
Development console and sensitive diagnostics are disabled in release.
Known issues and minimum hardware/API requirements are documented.

26. Definition of Done

The basic project is complete when a player can launch a Windows build, create a seeded world, safely explore continuously streamed HDRP voxel terrain, break and place a small set of licensed externally textured blocks using a persistent hotbar/inventory, save and reload edits, experience a readable day/night presentation with sourced audio/UI/VFX, and select raster quality levels or an automatically validated optional ray-tracing tier.

Completion also requires deterministic tests, bounded memory during travel, safe save behavior, a clean build from source, and a complete third-party asset/license ledger. Optional crafting, creatures, fluids, multiplayer, and other survival systems do not block this definition.

This is the engine platform gate. It is not the game’s gate. Sections 27 onward define the actual product — a chemistry-driven industrial survival game — and carry their own, stricter Definition of Done in §36.6.

PART II — THE CHEMISTRY GAME

Sections 1–26 describe a voxel engine and a Minecraft-shaped sandbox loop running on it. That work is substantially complete and remains the platform. Sections 27–49 define what the game actually is, and supersede the product identity in §1 and §2.1 wherever they conflict. Where a rule in Part I is about engine correctness — determinism, coordinates, streaming, meshing, saves, budgets, assembly layering, asset licensing — it remains binding and Part II inherits it without exception.

The chemistry product uses an explicit product profile so completed platform features cannot silently redefine the game. Shape-recipe crafting, hostile creatures, conventional combat armour, and the legacy hunger/night-threat loop may remain available to platform test scenes, but are disabled in the chemistry campaign. Player health, injury, death and respawn remain, driven by industrial, environmental and physiological hazards. The chemistry campaign uses process-based manufacture (§37.1), bulk matter (§30.4), and the §36.6 product gate. This profile is data/configuration, not a fork of the simulation rules.

27. Product Identity: What This Game Is

27.1 The one-sentence pitch

You are stranded with rocks, wood, water and air. Everything else — every metal, every acid, every material — you must take apart and put back together yourself, using real chemistry, and then build a factory that does it for you before the by-products kill you.

27.2 Why this is not Minecraft

Minecraft’s progression is a material tier ladder gated by tool hardness, and its crafting is shape-based recipe lookup: the 3×3 grid is a lookup key, not a process. Nothing is transformed; items are exchanged. There is no reason wood plus stone becomes a pickaxe beyond authorial decree.

This game replaces that with three substitutions:

Minecraft	This game
Recipes you memorise or look up	Reactions you discover by experiment and record
Tier ladder (wood→stone→iron→diamond)	Capability ladder: what temperature, atmosphere and voltage you can command
Crafting grid (a lookup table)	Apparatus applying real conditions to a real charge of matter
Ore block → 1 ingot	Ore body at a grade → beneficiation → reduction → metal, with slag and off-gas
Mobs are the threat	Your own plant is the threat
Items appear from nothing	Conservation of mass: every atom came from somewhere

27.3 Why this is not Satisfactory or Factorio either

Those games are excellent at the loop this game also wants — build, automate, scale, optimise — but their recipe ratios are authored. “2 iron ore → 2 ingots” is a balance spreadsheet decision.

Here the ratios are derived, and they are not negotiable:

2 CuO + C  ->  2 Cu + CO2

That balanced equation supplies the theoretical stoichiometric ratio for that selected net route. Sizing a copper line starts with two moles of tenorite per mole of carbon and molar masses (79.55 g/mol and 12.01 g/mol), then accounts for ore grade, competing CO/CO₂ equilibria, incomplete conversion, heat and transport. The journal shows theoretical demand beside measured yield and recycle. A player who internalises the distinction between stoichiometry and actual throughput has learned something true.

27.4 Design pillars

These are binding. A feature that violates one is redesigned or cut, not shipped with a caveat.

Conservation accounting is absolute. Chemical domains conserve each element’s nuclei and net charge through failures, spills, leaks, explosions and interrupted processes. The nuclear endgame is the explicit exception to “atoms are unchanged”: it conserves nucleon number, charge and total mass-energy while tracking fusion products and mass defect. Nothing is created or deleted without a named source, sink or energy conversion. Procedural terrain is the world’s deterministic initial condition, not a reaction; accounting begins when a region is instantiated and every later transfer across an active-domain boundary enters a named reservoir/ledger (§28.9). If a system cannot close the appropriate ledger, it does not ship.
Electromagnetism is the force. Chemistry here is not entropy bookkeeping with a heat gauge on top. Bonding, redox, electrode potentials, electrolysis, batteries, plating, induction and motors are one continuous subject, and the sim treats them as one via ΔG = −nFE (§28.6). The player’s real arc is learning to command electrons, first indirectly through heat and carbon, then directly through applied potential.
Progression is knowledge and capability, never unlocks. There is no research menu, no XP, no tech tree node to purchase. You are limited by what you know, what your apparatus can survive, and what conditions you can reach and hold. Anything you can physically attempt, you may attempt — including things that will hurt you.
Trial and error is the intended verb. You are always allowed to heat the unknown rock and see. The engine resolves it honestly. The notebook records what happened. Discovery is empirical, and being wrong is informative rather than punished by a locked door.
The lab is the monster. The primary threat is carbon monoxide, not a skeleton. Danger is generated by the player’s own competence and ambition and scales with industry. Every avoidable lethal scenario provides a fair, truthful warning path (§31.1); hazards that human senses cannot detect remain invisible until process evidence or an instrument reveals them.
Automate what you understand. Manual operation must be viable and complete through every tier where human speed and endurance are physically sufficient — which is the whole early and middle game. Automation there is an amplifier the player earns by understanding a process well enough to specify it, never a designer’s gate on reaching a material. Beyond that point the requirement inverts honestly: industrial electrolysis and millisecond plasma feedback cannot be hand-operated by anyone, and the control loop becomes a physical necessity rather than a convenience. When automation stops being optional, it must be because reality says so, and the game must say why.
Honesty about the model. This is a curated, approximated subset of real physical chemistry with its simplifications written down (§28.9). Never present it as research-grade, never claim predictive validity outside the validated envelope, and never let presentation invent a reaction the simulation did not resolve.

27.5 The shape of a playthrough

Hours 0–1 — Fire. Burn wood. Discover that limiting the air yields charcoal and a hazardous off-gas mixture. Learn ventilation by observing, preventing or recovering from a small incident; the opening never requires poisoning the player to prove they learned.
Hours 1–4 — Heat. Build a kiln that holds temperature. Calcine limestone to quicklime, slake it (violently), and get mortar — which lets you build a better kiln. The first feedback loop.
Hours 4–10 — Metal. Recognise a green rock. Roast it. Reduce it with charcoal under forced air. Produce copper. This is the game’s first true summit and it must feel like one.
Hours 10–20 — Alloy and industry. Find cassiterite, reduce tin, alloy bronze, and — because doing this by hand is now tedious in a way that teaches — automate: crushers, screens, conveyors, a water wheel, a bellows battery. This is the MVP boundary (§36.6).
Hours 20–40 — Glass. Melt silica with your own soda and lime. Blow and draw glassware: flasks, retorts, condensers, tubing. Glassware is the key that opens aqueous chemistry, because it is the first vessel that resists acid and lets you see the reaction.
Hours 40–80 — Acids and electrons. Distil mineral acids. Build the first cell from two dissimilar metals and an electrolyte, and measure a voltage. Build a generator and drive it with the water wheel you already have. Then run current through brine and drive a direction that is non-spontaneous at those conditions, because you supplied the required electrical work and losses.
Hours 80+ — High tech. Electrolysis unlocks the metals fire cannot reach — aluminium, sodium, magnesium — plus chlorine, pure oxygen and hydrogen, electroplating, and refined copper for the windings of better generators. The ladder from here is electromagnetic, not thermal.

27.6 The engine of progression

The whole game is one loop, run over and over at rising energy density. It is not a tech tree with a shape; it is a cycle that escalates, and every system in Part II exists to keep it turning.

        trial and error
              │
              ▼
         chemistry  ──────────────┐
              │                   │
              ▼                   │
         discoveries              │  each turn of the loop
              │                   │  raises the energy density
              ▼                   │  and the precision required
         engineering              │
              │                   │
              ├──► more discoveries
              │                   │
              ▼                   │
         automation ──────────────┘
              │
              ▼
      unstable plasma
              │
              ▼
       stable plasma

Read as prose: you poke at things until something happens. What happened is chemistry. Understanding what happened is a discovery. Acting on the discovery is engineering. Engineering at scale reveals things hand-work never could, which is more discoveries — and demands automation. Automation is what finally buys you enough power, precision and control to reach plasma: first unstable and dangerous, then, with everything you have learned about control loops and confinement, stable.

Three properties of this loop are binding on every feature:

Trial and error must always be available. The loop’s entry point can never be closed off. There is no point in the game where the answer to “what happens if I heat this?” is a locked door. If a player wants to start over experimentally at hour ninety with an unfamiliar mineral, the engine answers honestly.
Every stage must feed the next and the previous. Engineering produces discoveries, not just throughput; automation produces discoveries, not just scale. A stage that only consumes and never generates new knowledge is a dead end and gets redesigned.
The loop is the difficulty curve. The game does not get harder by adding hit points or timers. It gets harder because each turn of the loop commands more energy in a narrower tolerance, and the consequence of losing control scales with it — from a smoky room, to a ruptured boiler, to a plasma disruption.

27.7 The purpose: matter matters

This game exists to teach that matter matters. Not as a marketing line and not as a mode you can switch on — as the reason every other rule in Part II is written the way it is.

Most people live surrounded by materials they cannot account for. The metal in a phone, the glass in a window, the concrete in a wall, the nitrogen in their food — all of it was dug out of rock by someone who understood chemistry, and almost none of it is visible in the object. This game makes that chain visible by making the player walk it.

The intended audience is children and, much more so, adults — because adults are the ones who have had longer to forget, or who never learned, and because an adult who has spent eighty hours reducing malachite will not thereafter look at a copper pipe the same way.

What “matter matters” actually means, in order of depth

Nothing comes from nothing. Closed-ledger matter and energy accounting is the first rule of the simulation (§27.4 pillar 1). In the chemical game, every copper nucleus in the player’s hands came from the world, and fuel, air, work and knowledge were required to separate it. In fusion, the small mass defect appears as energy rather than being rounded away.
Nothing goes away unaccounted. The slag heap and tailings stay until moved or transformed. Flue gas is transported, diluted, reacted, deposited, captured, or transferred to the regional atmosphere ledger (§28.9, §47.5); none of those is deletion. Pollution may disperse or chemically change, because real pollution does, but its matter and consequences remain accounted for. The player’s base stains downwind of its own smelter, delivering the lesson as a consequence rather than a message.
Materials have reasons. Bronze is not “tier 2”. Suitable Cu–Sn compositions can cast below copper’s melting point because of their phase behaviour, while hardness comes from composition, microstructure and processing (§37.3). Aluminium was once worth more than gold not because it is rare — it is one of the most abundant elements in the crust — but because reducing it needs electricity (§38.6).
Everything is connected by electrons. Burning wood, rusting iron, a battery, electroplating and a fusion plasma are the same subject at different energies (§35.1). A player who feels that continuity has understood something most formal chemistry teaching fails to convey.

Binding consequences for the build

These are requirements, not aspirations, and they constrain implementation:

The no-unlearning rule. Every simplification must be a simplification in the direction of truth, never a falsehood. A player who later studies real chemistry must find that this game was right and incomplete — never that it was wrong. This is why §28.9 lists its approximations openly and why §40.7 forbids invented thermodynamic data outright.
Real units, always shown. Kelvin, moles, kilojoules per mole, volts, amperes, kilograms. Never “heat units” or “energy points”. Using the real units is a large part of the teaching, and it costs nothing.
The notebook teaches method, not just content (§34.2). Record conditions, observe, form a hypothesis, test it, record the result — including the failures. That is the scientific method as a game loop, and it is the most transferable thing the game has to offer.
Failure is data. A batch that does not work must tell the player why in terms they can act on. A game that teaches by punishment teaches only avoidance.
Science must be visible and reviewable. An accurate formula that produces only a hidden state change has failed as game design. Every material simulation event must create truthful sensory or instrumental evidence while it unfolds and a durable, causal answer to “What just happened?” afterwards (§34.2). If the player cannot perceive, inspect, and revisit the science, the formula is serving only as an approximation engine and does not justify its complexity.
Sources are citable in-game. §36.5’s Docs/CHEMISTRY_SOURCES.md is not merely a developer artifact; a curious player should be able to find where a number came from and go read it.
No pseudo-science, ever. No alchemy presented as effective, no invented elements, no “quantum” hand-waving, no energy-from-nothing. The fictional layer is the precursors (§44.5), who are absent people — never impossible physics.
Difficulty must come from rigour, never from obscurity. The game is hard because chemistry is demanding. It is never hard because information was withheld, a signal was hidden, or an interface was unclear. Every design choice in §44 (friction reduction) exists to protect this distinction.

If a feature would make the game more fun by making it less true, the feature is wrong. That trade is not available in this project — because if it were taken, the game would no longer be worth building.

27.8 Moment-to-moment play and a satisfying session

The hour bands in §27.5 are playtest hypotheses, not mandatory waiting times. The game must work in a twenty-to-thirty-minute session as well as a long factory-building session. Every critical-path process has a player-facing purpose beyond acquiring the next material:

Choose: identify a practical need, such as a vessel that lasts longer or a lighter ore shipment.
Try: select a small charge, apparatus and one controllable change; make a prediction if desired.
Notice: see a meaningful response before the full batch completes, with an estimated completion range only when available evidence supports one. A silent progress bar is not observation.
Use: turn the result into a visible improvement to the camp, a tool, a transport route or a repeatable process. A copper bead needs a useful first application, not just a collection badge.
Leave a thread: pin a question, comparison or building intention that explains the next visit.

Use small experimental charges to shorten the cost of learning; production batches earn automation through throughput. Do not make players perform repeated identical gestures to demonstrate knowledge. While a process runs, offer meaningful nearby work and let them pause (§29.5). A process that demands attention must provide controllable decisions; one that does not must be safe to leave once engineered appropriately. Record time spent choosing, building, travelling, observing and merely waiting in C6.

MVP completion is a working bronze-era workshop, including a stable copper line and an understood safety provision (§36.6). Mark it with a review of the player’s own first and recent runs, then let the world continue. Do not make unfinished T6+ content the apparent missing final objective. Optional goals compare yield, fuel per useful output, waste, footprint and reliability; no single score makes maximum throughput the only worthwhile way to play. Decorative building remains useful self-expression and consumes its actual materials without requiring a discovery reward for every wall.

28. Chemistry Simulation Core

Assembly: VoxelSandbox.Chemistry. Pure C#. No UnityEngine reference, no Burst, no Jobs, no allocation in the steady state. It is the most heavily tested assembly in the project and must be runnable headless by the standalone server (§2.4) and by test harnesses without an Editor.

The solver operates on a bounded reaction domain: a control volume with composition, phases, temperature, pressure/volume, energy and defined matter/energy ports. A Vessel is the first and most important domain, not the only one. Later gas cells, reactive surfaces, hydroponic beds and physiology reuse the same catalogues and conservation ledger through domain-specific transport models. They may not create separate, contradictory chemistry implementations.

28.1 Substances

A Substance is an immutable chemical identity with a stable integer SubstanceId, elemental composition, formal charge and a stable content hash. Thermodynamic values belong to a ThermodynamicPhaseDefinition keyed by (SubstanceId, Phase); water vapour and liquid water are the same substance but different phase records. Definitions are authored as ScriptableObjects in VoxelSandbox.Data but the runtime model is a plain struct table so the core stays Unity-free.

Required data per species:

Field	Symbol	Unit	Notes
`MolarMass`	M	g/mol	From composition; validated against the element table
`Formula`	—	—	Element→stoichiometric-number map. The atom-conservation checker reads this, not the name
`FormalCharge`	z	elementary charge	Required for ions and exact charge balance
`PhaseDefinitions`	—	—	Zero or more records for `Solid` / `Liquid` / `Gas` / `Aqueous` / `Solution`
`StandardEnthalpyOfFormation`	ΔfH°	kJ/mol	Per phase, at 298.15 K and the declared standard state
`StandardEntropy`	S°	J/(mol·K)	Per phase, absolute at 298.15 K and the declared standard state
`ShomateCoefficients`	A–H	—	Per-phase Cp(T), H(T) and S(T) data per §28.3, with an explicit validity range
`MeltingPoint` / `BoilingPoint`	Tm / Tb	K	At 1 bar
`EnthalpyOfFusion` / `EnthalpyOfVaporisation`	ΔHfus / ΔHvap	kJ/mol	Latent heats
`Density`	ρ	kg/m³	Per phase
`OxidationStates`	—	—	Per element in the species; drives redox bookkeeping (§28.6)
`HazardProfile`	—	—	§31.2

Elements have a separate table: atomic number, symbol, standard atomic weight and optional sourced descriptive properties such as electron configuration and electronegativity. They do not pretend to be phase definitions. Elemental composition plus formal charge are the ground truth for the atom- and charge-conservation invariants.

28.2 The vessel charge

All chemistry happens to a Charge: a bounded, densely packed list of (SubstanceId, Phase, moles) plus, for solids, a GrainSize in metres. Iteration order over a charge is always ascending (SubstanceId, Phase) — never dictionary or hash order — because summation order changes floating-point results and determinism is non-negotiable (§28.8).

Grain size is not decoration. Heterogeneous solid–gas and solid–liquid reactions carry a specific surface-area term (§28.5), so crushing ore finer genuinely accelerates its reduction. This is the chemical justification for the crusher in §32; the machine exists because the rate law asks for it.

28.3 Heat capacity and temperature-corrected thermodynamics

Standard-state values alone are not enough — a kiln runs at 1200 K, not 298 K. Use the Shomate formulation with t = T / 1000:

Cp(T)          = A + B·t + C·t² + D·t³ + E/t²                      [J/(mol·K)]
H(T) − H(298)  = A·t + B·t²/2 + C·t³/3 + D·t⁴/4 − E/t + F − H      [kJ/mol]
S(T)           = A·ln t + B·t + C·t²/2 + D·t³/3 − E/(2t²) + G      [J/(mol·K)]

Then, for a reaction with stoichiometric coefficients ν (negative for reactants), keeping the unit conversion explicit:

ΔrH°(T) [kJ/mol] = Σ ν·{ΔfH°(298) + [H°(T) − H°(298)]}
ΔrS°(T) [J/(mol·K)] = Σ ν·S°(T)
ΔrG°(T) [kJ/mol] = ΔrH°(T) − T·ΔrS°(T)/1000
K(T) = exp( −1000·ΔrG°(T) / (R·T) ), with R in J/(mol·K)

The superscript ° and each standard state matter: K is dimensionless and is not a concentration with hidden units. API names carry units, conversion happens once at the equation boundary, and tests include a factor-of-1,000 trap.

Every species must declare its Shomate validity range. Evaluating outside it is a hard error in the Editor and a clamped evaluation plus a one-time diagnostic in a release build — never a silent extrapolation into nonsense.

28.4 Activity and the reaction quotient

Q = Π (a_i)^ν_i

with activities by phase:

Gas — partial pressure over standard pressure, a = P_i / P°, where P_i = n_i·R·T / V from the ideal gas law (an explicit approximation, §28.9).
Aqueous — a_i = γ_i·b_i/b°, with activity coefficients γ_i = 1 only for the explicitly ideal MVP/dilute approximation (§28.9). Later models declare solvent, ionic-strength/concentration range and standard-state convention; Debye–Hückel is not used outside its dilute validity.
Pure solid / pure liquid — a = 1.
Solution phase (alloys, brines) — mole fraction, a = x_i. Bronze is modelled as a copper–tin solution, not a compound; this matters and the model must not fake it as Cu₃Sn.

28.5 Kinetics

Equilibrium says where a system is going; kinetics says whether it gets there before the player gets bored or killed. Both are simulated.

k_f(T) = A_f · exp(−Ea,f/(R·T))
r_net  = r_f − r_r

There is no universal rate law that can be inferred from a balanced equation. Each reaction therefore declares a sourced empirical or mechanistic rate-law model, its units, validity envelope and uncertainty. For an elementary reversible mass-action step, r_f uses reactant activities, r_r uses product activities, and detailed balance constrains the two so their ratio reproduces K at equilibrium. For a deliberately coarse relaxation model, an affinity term such as ln(K/Q) may set direction, but it is labelled an approximation and may not be presented as measured kinetics.

A reversible reaction is a candidate when either direction has material to consume. It must run backwards from a product-only state where the physical model predicts it; candidate indexing may not silently disable that direction. The Boudouard equilibrium C + CO₂ ⇌ 2CO is the canonical validation case: equilibrium direction must emerge from Q and K, while the speed remains a sourced kinetic model rather than a scripted special case.

S_area is the specific surface area term, derived from grain size and the solid’s molar volume for heterogeneous reactions and fixed at 1 for homogeneous ones.

Catalysts modify kinetic parameters and never the equilibrium constant. A catalyst that changes K is a bug, and there is a test asserting exactly that. If defensible kinetic data do not exist, the reaction ships with an explicitly bounded approximation or does not ship; A and Ea are never invented merely to hit a desired play time.

28.6 Electrochemistry — the unifying layer

This is the section that makes §27.4 pillar 2 real rather than flavour text.

Every redox reaction carries balanced oxidation-state/electron bookkeeping. Where a real electrochemical cell and standard state are defined, it is decomposed into sourced half-reactions with electron count n and reduction potentials E°. The engine does not apply an aqueous 298 K electrochemical series to a dry high-temperature furnace reaction. The bridge identity is:

ΔG° = −n·F·E°            F = 96485 C/mol

For the same reaction, state and standard-state convention, Gibbs free energy and reversible cell potential are the same driving force in different units. An electrochemical record stores one and derives the other; it must never carry independently authored duplicates that can disagree. Tests assert round-trip consistency for every electrochemical reaction in its stated envelope.

Concentration dependence uses Nernst, which is the same statement as §28.4’s Q:

E = E° − (R·T / (n·F))·ln Q

Three consequences the game is built on:

Spontaneity has a voltage. “Will this happen?” and “what voltage does this cell produce?” are one question. A galvanic cell built from two dissimilar metals in an electrolyte produces exactly the potential the thermodynamics predicts.
Electrical work can drive a non-spontaneous reaction. A reaction with ΔrG > 0 at the stated conditions is not spontaneous in that direction. Apply sufficient external potential to cover the reversible decomposition potential plus activation, concentration and ohmic losses, and it can proceed. This is electrolysis, and it is the single most important capability unlock in the game.
Faraday’s laws give the theoretical charge-to-product ratio. At 100% current efficiency the mass of product at an electrode is
```
m = (Q_charge · M) / (z · F) = (I · t · M) / (z · F)
```
Real cells also have side reactions and current efficiency η_I, so realised product is m_actual = η_I·I·t·M/(zF) and 0 ≤ η_I ≤ 1 comes from the model/measurement, never a hidden balance multiplier. The journal shows theoretical and realised yield side by side.

Activation overpotential may use a Tafel model only inside its sourced validity envelope. Ohmic drop, mass-transfer/concentration loss and current efficiency are separate terms; omitting one is a stated milestone approximation. This makes “why does my cell need more than the reversible voltage?” a real, visible engineering question rather than one magic penalty.

28.7 The solver tick

Fixed 20 Hz simulation tick. Never a variable deltaTime. Per active reaction domain, per tick:

Read charge, temperature T, volume V. Compute ΣnCp(T).
Resolve phase transitions without skipping latent heat. A pure substance may use a sourced pressure-dependent boundary; a mixture uses a sourced phase model or diagram and may transform across a range. Fixed Tm/Tb values are explicitly normal points at the declared pressure, never universal constants. The MVP may clamp pure phases at their normal boundary only inside its validated pressure envelope; it may not teach a fixed boiling point at altitude or a single melting point for bronze.
Build the candidate set for both supported directions. Use stable IDs for storage and reproducible summation, never as chemical priority.
From one immutable sub-step-start snapshot, compute ΔrH°(T), ΔrG°(T), K(T), Q and every candidate’s sourced net rate. Do not let an earlier ReactionId consume material before a later candidate has even been evaluated.
Compute provisional extents ξ = r_net·dt, then resolve competing consumption together with a deterministic bounded positivity projection. No species may go negative, and permuting reaction IDs must not materially change yields. The limiter is an invariant, not a hidden reaction selection rule.
Apply the accepted extent vector as one state transition: Δn = Σν·ξ.
Close a declared control-volume first-law balance. A rigid sealed domain uses internal energy; open/flow apparatus accounts explicitly for enthalpy carried through ports. Heat transfer, shaft/electrical work, phase change and reaction energy appear exactly once. Electrical work that drives electrolysis may not also be counted as free reaction heat. Reject or quarantine a step whose energy residual exceeds the documented tolerance.
Recompute gas pressure from headspace volume (vessel volume minus condensed-phase volume), not total vessel volume. Vent through a bounded flow model if open and above ambient; if P exceeds the vessel’s rated pressure, raise a rupture event (§31.4).
Assert atom, charge and energy accounting. In the Editor and in tests this throws; in release it logs once and quarantines the domain rather than continuing to simulate one that has lost atoms.
Emit a compact causal ScienceEvent from the accepted before/after delta (§34.2): what changed, which reaction/transfer/phase event caused it, conditions, measured quantities, uncertainty, approximation flags and conservation residuals. Presentation and the journal consume this event; neither reverse-engineers a story from final state.

Stiff systems are handled by deterministic sub-stepping: estimate stiffness, quantise the sub-step count to a power of two in [1, 64], and always take exactly that many equal sub-steps. The count must be a pure function of the vessel state so two runs never disagree.

28.8 Determinism contract

This inherits §8.1 and tightens it. The chemistry core is bound by all of:

Fixed tick, fixed sub-stepping rule, fixed iteration order by stable ID. No dictionary iteration, no foreach over a hash set, no ordering that depends on insertion history.
All chemistry arithmetic in double, IEEE-754 strict. Burst is forbidden in the chemistry core, and FloatMode.Fast is forbidden anywhere near it, because reassociation changes results.
No parallel reduction unless the reduction order is fixed independently of thread scheduling.
Moles are quantised to a fixed epsilon (1e-12 mol) through a conservative projection, not by rounding each species independently. Sub-epsilon remainders move to a bounded per-domain trace ledger and re-enter the visible charge when they accumulate to one quantum; they are not deleted. Atom/charge residuals before and after projection must be exactly zero in ledger units.
Saves carry a chemistryVersion alongside generatorVersion, plus content hashes for substance and reaction catalogues. An unsupported mismatch is a hard load error (§13.4), never a silent substitution. An explicitly tested migration may create a new save branch; preserve the original, historical source/model versions and the player’s annotations. Content patches may not silently change a running plant’s ratings or rewrite the explanation of an old experiment.
The acceptance test is bit-identical: the same vessel, the same initial charge, 10 000 ticks, run twice in one process, once across two processes, on every shipped runtime/CPU architecture, and once with the vessel’s neighbours simulated in a different order — all runs must produce byte-identical final charges. A separate catalogue-permutation test renumbers independent and competing reactions and requires physically equivalent results within the published numerical tolerance; deterministic ordering must not disguise chemical priority by ID.

28.9 Stated approximations

Written down here so no part of the project has to pretend otherwise. The game may say “real chemistry”; it may not say “exact chemistry”.

MVP gases use the ideal-gas law only inside a declared low-density temperature/pressure envelope. High-pressure storage, steam power, liquefaction and cryogenics require a sourced real-fluid model or property table before their milestone; the ideal law may not be extrapolated into those regimes.
Aqueous activity coefficients are unity only in the explicitly ideal MVP/dilute envelope. The aqueous/acid milestones require a sourced activity model appropriate to concentration; Debye–Hückel is limited to dilute solutions, and concentrated mineral-acid behaviour does not ship until a defensible model/data set exists.
No intra-particle diffusion limitation beyond the grain-size surface-area term. Real shrinking-core behaviour is not modelled.
Industrial chemistry kinetics are accelerated 60× under §49.3 D1. Thermodynamic state and equilibria are unscaled, and acute physiology/controls/transport do not inherit that clock by accident. Every run records process and wall-clock time and may show a full-scale duration.
MVP pure-substance phase changes use sourced boundaries within declared pressure ranges. Mixtures, non-ideal solutions and broad solidus/liquidus regions require a sourced phase model; until then the journal labels the missing behaviour and never reports a fictional sharp melting point.
Kinetic parameters are frequently less complete and more apparatus-dependent than thermodynamic data. Every rate model is tagged Measured, Correlation, or GameplayScaleApproximation, with a source, units, validity envelope and uncertainty. Only the first two may be described as predictive.
Sparse gas and surface domains are finite-resolution transport models. Matter leaving the actively simulated region is transferred to a persistent regional source/sink ledger, not destroyed; on return it may be represented as a mixed background reservoir rather than reconstructed molecule by molecule.
Wood, tar and pyroligneous liquor are lumped surrogate species with declared average compositions (e.g. biomass as CH₁.₄O₀.₆), not real mixtures. They are marked IsSurrogate in the catalogue and excluded from claims of accuracy.
Reaction catalogues are curated. Absence of a reaction from the catalogue is a content decision, not a physical statement, and the notebook must never imply “this cannot react”.
Thermodynamic data is drawn from published reference tables, recorded with its source in Docs/CHEMISTRY_SOURCES.md, and validated by §36.4’s C0 gate. Values are not invented for balance. If a real value makes something unfun, change the scenario, the scale, or the apparatus — never the constant.

Every approximation above is machine-readable metadata consumed by §34.2’s after-action explanation. The player must be able to tell whether a displayed number was directly measured, inferred by the model, sourced from a reference, or produced by an approximation.

28.10 Model limits are not experimental results

The curated catalogue needs an explicit response for attempted chemistry it cannot represent. Distinguish observed no change, change below measurement resolution, insufficient evidence to explain, and outside the supported model. A solver timeout, missing rate model or invalid state is never a successful zero-yield experiment. Unsupported behaviour must not award an inertness, purity or safety claim, nor silently become a free waste-disposal route.

Model-support notices belong to a clearly labelled simulation-information layer. They may explain the available apparatus/condition envelope without disclosing the identity of an unknown sample or which hidden reaction would have occurred. A known unsupported transition is rejected before mutation; an unexpected numerical failure freezes the affected connected domain at its last valid transaction and offers diagnostics and recovery. It must not repeatedly consume fuel or punish the character for an engine fault. This is an explicit suspension of simulation, never a claim of physical safety.

The content gate is a decision-and-evidence map: for each MVP experiment, identify the player’s choice, the meaningful outcome differences, the evidence channel and the explanation. If a more expensive model changes none of those within the validated scenario, prefer the simpler validated approximation and disclose it. Precision is justified by what it lets the player understand or do.

29. Vessels, Apparatus, and Glassware

29.1 The vessel

A Vessel is the MVP apparatus implementation of §28’s reaction-domain contract. It is a bounded, saveable object owning:

A Charge (§28.2) and a Volume in m³.
Temperature, and a WallMaterial giving thermal conductivity, heat capacity, maximum service temperature and chemical resistance.
Sealing: Open, Vented (one-way above a cracking pressure), or Sealed.
RatedPressure, above which it ruptures (§31.4).
Ports: typed inlets/outlets for solid, liquid, gas and electrical connection.

Vessels are bounded in count and simulated on the fixed 20 Hz tick. A vessel whose charge is inert, thermally settled and unconnected is quiesced — removed from the active set until disturbed — so a large factory’s cost tracks its active chemistry, not its total size.

29.2 Wall material is a real constraint

The apparatus ladder is a materials ladder, and this is the main reason early progression feels earned. A vessel fails in one of three ways, all simulated:

Thermal — exceed the wall’s sourced service envelope and it slumps, cracks, spalls or melts. Dried clay is not a refractory; low-fired earthenware is body- and firing-dependent and cannot be assigned one universal failure temperature. The first crude ceramic cannot cast molten copper, which is why furnace lining, flux practice and upgraded refractory matter.
Chemical — the charge attacks the wall. Molten alkali eats silica. Acids eat metal. An attacked wall loses mass into the charge, contaminating the product, because conservation is absolute.
Mechanical — internal pressure exceeds the rating.

29.3 MVP apparatus

Apparatus	Reaches	Provides	Gates
Fire pit	~900 K	Open combustion, no atmosphere control	Everything starts here
Earth-covered charcoal mound / crude retort	~700 K, oxygen-limited	Pyrolysis; later retorts collect volatiles separately	Charcoal, tar. CO hazard
Pit/clamp kiln	~1050–1200 K	Insulated natural draught; fires small low-grade ceramic batches	Closes the fire→first-vessel bootstrap
Lime kiln	~1300 K, sustained	Continuous feed, long soak	Quicklime → mortar → better kilns
Bellows / tuyère	+300–400 K	Forced O₂; raises attainable temperature	Everything above 1200 K
Crucible furnace	~1500 K	Melting, casting, alloying	Copper, tin, bronze
Condenser	—	Phase separation by boiling point	Distillate collection

29.4 Glassware — the key to the second half of the game

Glassware is called out separately because it is the single most important apparatus unlock, and the player must earn it by making soda-lime glass from materials they already command. The batch is an amorphous silicate mixture, not one stoichiometric compound. Oxide bookkeeping is written as:

Na2CO3  ->  Na2O(in glass network) + CO2   (soda acts as a network modifier/flux)
CaCO3   ->  CaO(in glass network)  + CO2   (lime improves durability)

The solver conserves the full batch composition and uses sourced multicomponent property data. It does not silently replace all soda-lime glass with Na₂SiO₃ and CaSiO₃; those formulae describe specific silicates, not the general glass.

Silica alone melts near 1996 K, far beyond reach. With soda and lime — both already on the player’s path — the working range drops to roughly 1300–1500 K, which the bronze-era furnace already reaches. Glass is therefore the reward for having done the lime chain properly.

Glassware gives three capabilities nothing before it can:

Acid resistance. Borosilicate and soda-lime resist most mineral acids where metal and ceramic do not. Aqueous chemistry is inaccessible until you can hold an acid.
Transparency. You can see the reaction: colour change, precipitate, gas evolution, phase separation. Before glass, you infer; after glass, you observe. This is a genuine information unlock and the notebook (§34) records more from a glass vessel than an opaque one.
Precision forms. Retort, condenser, fractionating column, flask, tubing, burette, and the cell bodies that electrochemistry needs.

Glassworking is its own small process: melt, gather, blow or draw, and anneal. Skipping the anneal leaves residual stress and the piece shatters later, under thermal shock, mid-process, releasing its charge. This is a real failure mode and it is simulated.

29.5 Time, absence, and leaving a plant running

These are single-player campaign rules; deferred multiplayer must declare its own clock policy.

Situation	Required behaviour
Pause menu, journal, inventory or loss of application focus	Freeze all authoritative game clocks and transfers together. Reading and accessible input are not exposure penalties
Ordinary in-world interaction	Simulation runs; inspecting a gauge does not secretly pause only its vessel
Save/quit and application closed	Save at a coherent tick boundary; no offline production, cooling or injury
Player travels beyond rendering distance	Connected operating apparatus remains in the simulation set; unloading meshes does not stop a reaction, vent, belt or exposure source
Resume/load	Show the saved state before accepting actions; no wall-clock catch-up burst or unnoticed interval of injury

Render residency and simulation residency are different. Register active connected process domains independently of chunk GameObjects. Quiescence requires no material, energy, exposure or transport change under the model, and explicit wake conditions; distance alone is never sufficient. At the active-domain budget, reject activation of additional apparatus with a capacity explanation before consuming a charge. Never selectively freeze an already operating safety device or neighbouring tank. If the active graph cannot be advanced safely, pause the campaign with a diagnostic rather than silently losing time or matter. Analytic off-screen stepping is deferred until equivalence is tested.

MVP has no accelerated sleep/wait command. A later one must advance all coupled clocks consistently, stop at relevant alarms/events and retain its observation limits. The journal shows a return summary of interrupted jobs, observed alarms and player-pinned intentions; it does not invent observations from unattended experiments without a recording instrument.

29.6 Building and changing apparatus are physical operations

Rejecting crafting recipes does not remove the need to specify fabrication. Each MVP tool, vessel, mould, belt and shaft requires an authored route from reachable matter and tools: shape, join, dry, fire, cast or assemble as applicable. Each step declares inputs, offcuts/waste, work, apparatus and the material properties it requires. Construction plans describe geometry and operations; they never exchange arbitrary item icons for a machine or act as knowledge unlocks.

Placement previews show footprint, orientation, port direction, support and operating/service access. They expose geometric constraints without identifying an unassayed material or certifying chemical compatibility. Multi-block edits have one stable apparatus identity and a clear commit point; invalid placement consumes nothing. An empty, cold assembly can be moved or dismantled with conserved returns. A charged, hot or pressurised assembly cannot be pocketed as an empty item: move its complete domain only through a supported handling action, or isolate, empty and cool it first. Destructive breaking still works, but resolves damage and releases contents through the same spill/rupture path.

Cancellation before a fabrication/transfer commit changes nothing. Afterwards it stops future work and leaves the real intermediate state, offcuts and residual heat. Undo may reverse uncommitted placement; it is not a way to undo chemistry or clone contents. MVP supports explicit footprints and local apparatus damage, not a general structural-engineering collapse simulation.

30. Geology and Block Composition

30.1 Every block has a composition

BlockDefinition gains a Composition: a mole-fraction map over substances. This is static data, not per-voxel state — it costs nothing at runtime and does not touch chunk storage, meshing, streaming or save size (§27 inherits Part I’s budgets unchanged).

Malachite ore  ->  { Cu2CO3(OH)2: 0.15, SiO2: 0.70, Fe2O3: 0.05, CaCO3: 0.10 }
Limestone      ->  { CaCO3: 0.92, SiO2: 0.06, MgCO3: 0.02 }
Granite        ->  { SiO2: 0.72, Al2O3: 0.14, K2O: 0.05, Na2O: 0.04, ... }

Breaking a block yields matter with that composition. Feeding it to a vessel charges those substances. The atom-conservation invariant runs across this boundary, so the world itself participates in the mass balance.

30.2 Ore grade and gangue

There is no “copper ore” that yields copper. There is rock that is 15% malachite and 85% waste. That single change carries enormous design weight:

Fuel spent heating gangue is fuel wasted, so beneficiation matters: crush, screen, and sort to raise grade before smelting. The crusher and screen in §32 exist for a chemical reason.
Deposits vary. The generator places ore bodies with a grade distribution — a rich core grading out to barren country rock — so where you mine within a body matters and prospecting is a real skill.
Gangue reports to slag, which is not deleted. It is a real silicate melt that must be tapped and disposed of, and its composition affects the melt (a lime flux genuinely improves separation).
Impurities carry through. Iron in your malachite ends up in your copper unless you remove it, and impure copper is measurably worse — lower conductivity, which matters enormously once §32’s electrical tier arrives.

30.3 Prospecting and assay

Early on you cannot know a rock’s composition. You judge by colour, hardness, density and where it sits. Progressively, instruments reveal more (§34.3): a balance gives density, a flame test names the metal, and a proper assay furnace gives quantitative grade. Knowing what you are standing on is itself a progression axis.

Generation follows Part I’s determinism contract (§8.1) exactly: ore bodies, grades and impurity profiles are pure functions of the world seed and coordinates.

30.4 Carrying matter: bulk quantities, not stacks of 64

Part I’s inventory (§12.1) is a discrete item-stack model inherited from the sandbox loop. It is insufficient here and must be extended, because “one stack of copper ore” is not a chemical quantity.

The model splits in two, and the split is the honest one:

Discrete items — tools, instruments, apparatus, machine parts, glassware. Countable, unchanged from Part I. A retort is one retort.
Bulk matter — ore, powder, ingots, liquids, gases. Carried as mass with composition, not as a count. A container holds 3.74 kg of crushed rock that is 14% malachite, and that is the literal stored representation.

Consequences that must be designed for rather than patched later:

Capacity is mass and volume, not slot count. What the player can carry is limited by weight and bulk. Density therefore matters: a backpack of galena is heavier than the same volume of charcoal. This makes ore beneficiation (§30.2) immediately, physically motivated — you crush and sort at the mine because you cannot carry the gangue home.
Containers are typed. Solids need a bin or sack; liquids need a sealed vessel; gases need a pressure vessel and carry all of §31.2’s hazards while carried. Carrying chlorine is a decision with consequences.
Mixtures stay mixtures. Pouring two partial batches of ore together produces one batch with the mass-weighted composition. It does not produce a “mixed ore” item. There is no lossy round-trip through a display name anywhere in this path.
The UI must show composition legibly, at a level of detail gated by the player’s instruments (§34.3): an unassayed rock reads as “greenish ore”, the same rock after assay reads as its real composition. The underlying data is identical; only the legibility changes.
Stack merging rules are mass-conservative by construction, and the atom-conservation invariant (§28.7 step 9) runs across inventory transfers exactly as it runs across vessel ticks.

30.5 Batch identity, sampling, and handling

A bulk batch has stable identity, physical state and provenance distinct from its display label. Splitting and merging preserve matter, energy, origin links and the remaining parent amount. Material has exactly one owner at a time: terrain, inventory container, vessel, transport buffer, spill or regional reservoir. Picking up a hot ingot or moving a charged vessel changes ownership/location, not temperature, contamination or reaction time. Storing it in a hotbar cannot cool, clean or freeze it.

An assay consumes or returns an actual sample. Results describe that sample, method and uncertainty; they are evidence about the parent batch, not exact knowledge of the deposit. Different ore parcels may differ. Retained samples take capacity, can age or react, and cannot be reanalysed after being consumed. Working names, labels and player annotations survive splits and reference their origins; merging two measured batches does not certify a new mixture beyond what those measurements support.

Do not confuse a composition ledger with a separation model. Pouring liquids, draining a lower phase, scooping solids and splitting a well-mixed powder need explicit extraction rules. MVP declares where uniform mixing is approximated; it must not grant a perfect separator by selecting a chemical name from an unknown mixture. Residual charge stays in a vessel until transferred or cleaned, and cleaning produces accounted rinse/waste. Microscopic surface films and contamination mechanisms beyond the declared MVP resolution are deferred, not arbitrary invisible penalties.

For player transfers, preview source, destination and requested quantity, then move a bounded amount. Show actual transferred quantity and the reason for a partial move. A full container stops a manual pour unless the player explicitly continues into overflow; an unattended process follows its physical overflow/back-pressure model (§32.5). Releasing a control stops further transfer, not matter already in flight. All paths support keyboard/controller operation without a precision drag requirement.

31. Hazards: The Lab as the Monster

31.1 The threat design

Danger scales with ambition and is normally created, uncovered or concentrated by the player’s own work. Geology and weather may supply a hazard, but nothing spawns merely to attack. Every hazard obeys three rules:

It is a consequence of real chemistry the player caused, not a spawned entity.
The player has a fair, scientifically honest route to warning — process context, a real smell or appearance where one exists, a sound, symptoms, a gauge, detector or alarm. Some hazards are genuinely undetectable to human senses, so the game never grants a magical cue. Their first teaching encounter is survivable and signposted indirectly; later safe operation may genuinely require an instrument. “Fair” means the player had an actionable opportunity to know, not that the toxin announces itself.
It is preventable by understanding, and the understanding transfers. Ventilation learned from the charcoal retort is the same lesson that saves you at the smelter and, much later, in a spacecraft’s life-support loop (§33.3).

31.2 Gas hazards

Gas vented from a vessel enters a sparse atmospheric reaction/transport domain with position, volume, composition and temperature. There is no per-voxel gas field — domains are bounded in count, advect on the existing WindField from §17.4, exchange matter with the regional ledger (§28.9), and mix, rise or sink using a validated reduced-order buoyancy/dispersion model. Molar mass, temperature, release momentum, wind, turbulence and terrain all matter; “heavier than air” alone is not a pooling algorithm.

Exposure keeps a concentration–time record, but there is no universal dose = concentration × time health law. Each hazard declares a sourced model appropriate to its mechanism: gas partial pressures and oxygen displacement for asphyxiation; a reduced carboxyhaemoglobin uptake/clearance model for CO; concentration- and duration-dependent injury for irritants; heat flux and contact time for burns. Published occupational/emergency values are reference bands with their averaging duration and population, not magic damage thresholds. Gameplay recovery assumptions are labelled separately.

Gas	Source	Why it kills
CO	Incomplete combustion; carbon-fed reduction under some conditions	Odourless and colourless; causes nonspecific hypoxic/neurological symptoms. The signature early killer
CO₂	Calcination, combustion, fermentation	Denser than air, pools invisibly in low ground, asphyxiates
SO₂	Roasting sulfide ores	Acrid, attacks lungs, forms acid with moisture
H₂	Acid on metal, electrolysis	Explosive across a very wide mixture range
Cl₂	Brine electrolysis	Corrosive, lethal at low concentration

Player vitals extend with BloodOxygen, a per-toxin ToxicLoad with clearance rates, and CoreTemperature. These live with the existing vitals work and follow the same authoritative-state rules — presentation may interpolate a gauge, never invent a state (§2.7).

31.3 Thermal and chemical injury

Contact burns from hot vessels, radiant load from an open furnace, molten metal spill, and chemical burns from alkali and acid. Quicklime slaking (CaO + H₂O → Ca(OH)₂, ΔH = −63.7 kJ/mol) is violently exothermic and is deliberately placed early as a memorable, survivable lesson.

31.4 Explosions and rupture

Three mechanisms, all emergent:

Flammable mixture ignition — a gas cloud within its lower and upper flammability limits meeting an ignition source. Overpressure scales with the fuel actually present.
Vessel rupture — P > RatedPressure from gas generation, a blocked vent, or thermal runaway. A sealed vessel with a live gas-producing reaction is a bomb, and the pressure gauge that prevents it is an instrument the player must choose to build.
Dust explosion — fine combustible dust suspended in air, which the crusher and pneumatic conveying in §32 can generate. Industrial housekeeping becomes a real mechanic.

31.5 Mitigation is engineering, not equipment pickups

Ventilation is designed, not bought: draught, stack effect, and forced air with a bellows or later a fan. A damp cloth filters only coarse particles, and an ordinary charcoal-bed respirator does not protect against CO, CO₂ or oxygen deficiency (§46.2); those require ventilation, evacuation or supplied air. Gas detection begins with a canary-equivalent and a limewater bubbler and ends with real instrumentation. Remote operation — running a dangerous process from behind a wall via §32’s control layer — is the mature answer and one of the strongest reasons to automate.

31.6 Injury, death, and recovery

Knowledge is never a death penalty. Journal events, confirmed discoveries, source annotations and achievements survive death transactionally. Death costs position, process time and recoverable physical matter; it may interrupt apparatus, which continues according to the authoritative clock. No duplicate or deleted matter is allowed across corpse/drop recovery and respawn.

Respawn selects a reachable clear recovery location using authoritative terrain and hazard state; it never places the player back inside the same continuing exposure. If none is available, present a paused recovery choice. The recovery map marks the player’s last known location and equipment, not unmeasured toxin boundaries. Matter that burns, spills or corrodes follows those transformations; “recoverable” does not promise every item survives unchanged. A spoiled local resource must have a reachable alternative (§39.9), so losing a furnace does not end the ability to experiment.

Campaign injuries may be long-lasting and require correct treatment, but no exposure irreversibly damages an eighty-hour save. Where real harm can be permanent, the journal says so; the gameplay recovery curve is labelled as a humane campaign rule, not medical fact.

32. Industry: Logistics, Power, and Process Control

This is the Satisfactory-shaped layer. Its distinguishing property remains §27.3: stoichiometric material-conversion ratios come from balanced equations or Faraday’s laws, never arbitrary recipes. Throughput also depends on sourced kinetics, transfer, equipment geometry, power and control; those are modelled or explicitly tuned, not falsely described as stoichiometry.

32.1 Machines

Machines are multi-block structures placed in the voxel world with a footprint, orientation, typed ports, and internal buffers. A machine either owns a Vessel (it does chemistry) or performs a physical transform (it does not).

Physical transforms — no chemistry, but chemically motivated:

Crusher / mill — reduces grain size. Directly raises S_area in §28.5’s rate law, so finer feed genuinely reacts faster. Generates dust (§31.4).
Screen / classifier — separates by particle size.
Jig / shaking table — separates by density; the mechanical half of beneficiation.
Magnetic separator — the first machine that is literally electromagnetic, and an early hint of where the game is going.

32.2 Transport

Belts and chutes for solids, with gravity feed as the free early option. Because §30.4 makes matter mass with composition rather than counted items, a belt carries discrete units — a sack, a bar, a crate, an ingot — and each unit carries its own mass and composition. Throughput in kg/s is therefore derived from unit mass and belt speed, not authored. This keeps the visual language of discrete objects moving along a belt while preserving compositional truth end to end: two visually identical copper bars on the same belt may be 98 % and 99.9 % pure, and the network (§42.4) can tell them apart.
Tubes and pipes for liquids and gases, solving volumetric flow against pressure. Gas lines carry composition, so a leak is a hazard, and pipe material must survive its contents (§29.2).
Drones for point-to-point transport that is flexible where fixed infrastructure is not: bridging a gap, servicing a remote outpost, or — critically — operating inside a hazardous area the player should not enter. Drones are power-hungry and throughput-poor compared to a belt. They are the answer to awkward, never the answer to bulk.

32.3 Process control — programmed apparatus

Real processes are not “on”. They are schedules, and this is where the game’s automation gets its depth:

Programmed heaters hold a temperature profile: ramp rate, soak temperature, soak duration, controlled cool. Annealing glass (§29.4), calcining without over-burning, and every metallurgical heat treatment need a curve, not a setpoint.
Sensors — thermocouple, pressure, pH, gas composition, level, current, voltage — publish real simulated readings.
Controllers close the loop: threshold logic first, then proportional, then full PID with visible and tunable gains. Watching a badly tuned loop oscillate and then fixing it is intended content, and the tuning is real.
Interlocks and safeties — relief valves, rupture discs, high-temperature cutoffs, gas-detection shutdowns. These are player-built and player-forgotten, which is the point.

Manual operation remains complete where the required speed and endurance permit it (§27.4 pillar 6). Later fast control loops may be physical necessities. Players can author schedules before proving them; the interface records them as untested procedures, never grants a safety or success guarantee.

32.4 Power and the electromagnetic ladder

Power is where §27.4 pillar 2 becomes mechanical rather than thematic:

Muscle — crank, treadle. Always available, never scalable.
Water and wind — a wheel on real flowing terrain, transmitted by shafts and gearing. Mechanical power is torque × angular velocity and the network solves for both.
Steam — a boiler is a Vessel, so its behaviour comes from water’s real enthalpy of vaporisation. Boiler explosions are §31.4’s rupture mechanism, not a special case.
Electricity — a generator is Faraday’s law of induction: a conductor moving in a magnetic field. Building one requires copper wire of sufficient purity (§30.2’s impurities now bite), insulation, and magnets. Coupling the water wheel you already own to a generator you built is the game’s second true summit after copper.
Chemical storage — batteries are §28.6’s galvanic cells at scale, with the potential the thermodynamics predicts.
Fusion — §35.

Electricity then feeds back into chemistry as electrolysis, and the loop closes: chemistry made the metal, the metal made the generator, the generator makes the electrons, and the electrons reach the metals that fire never could. Aluminium, sodium, magnesium, chlorine, pure hydrogen and oxygen, and electrorefined copper for better windings — which build a better generator. That feedback spiral is the engine of the entire second half of the game.

32.5 A stopped factory must be diagnosable

Every machine exposes its operating state through available mechanical cues or instruments: idle, running, starved, blocked, power-limited, intentionally isolated, or damaged. The diagnostic view traces what can actually be observed along connected ports and links to the relevant run; it never reports the exact hidden composition as a convenient error code.

Connections have finite capacity, direction and explicit behaviour when the destination fills. Solid handling may stall or spill according to its design; fluid back-pressure, relief and leakage are resolved by their supported models. Ports reserve and commit a transfer once, with both ends and the event record included in the transaction. Disconnecting a loaded connection retains its contents or releases them through a specified path. Loops and junctions must not duplicate material or let iteration order choose the recipient of a shared supply.

Commission a line at small scale: feed a measured charge, observe every output including waste, then compare intended and actual flow. Later controls require defined loss-of-power and restart behaviour; an emergency stop is a command to particular actuators, not a deletion of stored heat, pressure or reactants. A tripped apparatus restarts only under its declared reset policy. Maintenance in MVP is limited to modelled damage, residue and repair with real materials; no random breakdown rolls or mandatory servicing timer without an observable physical mechanism.

The C4 stability fixture must deliberately fill the waste outlet, interrupt drive power, disconnect a loaded belt and restart the line. Each outcome remains conservative, legible and recoverable; a thirty-minute happy-path run alone is not evidence that automation works.

33. Closed Loops: Hydroponics and Life Support

33.1 Why biology belongs in a chemistry game

Plants are chemical reactors that run on light, and they close loops nothing else can. Vertical hydroponics is the mechanism.

Photosynthesis and respiration use atom- and energy-balanced reaction-domain models, not a growth timer. The familiar equation below is the net carbohydrate carbon/oxygen bookkeeping, not a claim that a real plant or biomass consists only of glucose:

6 CO2 + 6 H2O  --light-->  C6H12O6 + 6 O2

Growth also accounts for water, nitrogen, phosphorus, sulfur, mineral ions, maintenance respiration, transpiration and a declared biomass composition. Light supplies energy; it is not decorative text over a spontaneous reaction.

33.2 Hydroponics as solution chemistry

A hydroponic bed is a specialised §28 reaction domain with an aqueous charge. It is genuine solution chemistry coupled to a bounded biological growth model:

Nutrient solution — real N, P, K, Ca, Mg, S and micronutrients as actual dissolved ions, which the player must manufacture. Nitrates, phosphates and potash are chemistry problems.
pH and conductivity are simulated, must be measured, and drift as plants consume ions selectively. This is exactly the aqueous chemistry glassware unlocked (§29.4).
Light — natural via the existing day/night and weather systems, or electric, which is a real power draw on §32.4’s network.
CO₂ enrichment — and here is the closure: the CO₂ your furnaces and kilns produce as waste is a feedstock. Piping flue gas to the grow stack is a genuine efficiency win, and it must be scrubbed of CO and SO₂ first, which is another chemistry problem.

Output is biomass: food, fuel, feedstock, and specific compounds from specific crops.

33.3 Life support is the same system

This is deliberate and it is the game’s structural payoff. The CO₂ scrubbing, O₂ generation, water recycling and thermal balance that make a sealed habitat survivable are the same mechanics the player already learned from ventilating a charcoal retort in hour one and running a grow stack in hour fifty. When §35’s spacecraft needs a closed ecological loop, the player is not handed a new system — they are asked to apply an old one where failure is unforgiving.

34. Knowledge, the Notebook, and Achievements

34.1 There is no tech tree

Restating §27.4 pillar 3 as a build instruction: do not implement a research menu, an unlock graph, a skill tree, or experience points. Any of these would replace the game’s actual subject with a progress bar. The player is gated by four things, all diegetic:

Knowledge — do they know the reaction exists and its conditions?
Capability — can their apparatus reach and hold those conditions and survive the charge?
Materials — do they have the atoms?
Access — can they physically reach, extract and transport the source or operating environment?

This does not mean there is no technology tree. There is an extensive one — §38 — but it is the dependency structure of physical reality, expressed as data in the reaction and material catalogues. It is a content specification and a build-time reachability test, never a screen the player opens and never a thing with node state to persist. §38.1 draws the distinction precisely; read it alongside this section rather than as a contradiction of it. The player reconstructs the tree in their own notebook by doing the chemistry, which is the only place it is ever “displayed”.

34.2 The journal

The journal is the most important interface in the game, because it is where §27.7’s teaching actually lands. It is not an inventory screen with a science skin — it is a neat, well-organised, genuinely useful scientific journal that the player fills in by working, and it must be built to the standard of a tool someone would want to use.

It records only what the player has actually observed. It is never a copy of the catalogue.

Structure

Section	Contents
Elements	A periodic table, blank at the start, filling in as elements are isolated
Substances	One page per species encountered, with measured properties only
Reactions	One page per confirmed reaction: equation, conditions, energetics
Runs	The experiment log — every process attempt, comparable across batches
Apparatus	Vessels and instruments built, with their real limits
Hazards	Encountered hazards, their signals, and what worked
Leads	Open anomalies not yet explained
Map	The reaction graph the player has personally established

The periodic table fills in

The Elements section starts as an empty periodic table and fills in as the player isolates each element in pure form. It is simultaneously a progress bar, a collection, a genuine reference, and the clearest possible statement of what the game is about — and it pairs with the Isolation: <element> achievements of §34.4.

A partially filled table also teaches by its gaps: the player sees the shape of what they have not reached, notices that a whole block of the table is missing, and eventually understands that the missing ones are missing because fire cannot reduce them (§38.6).

Pages carry only what was measured

A substance page shows appearance and where it was found from the first encounter; molar mass, density, melting point and composition appear only as the player measures them, each with the instrument and date. An unidentified species is filed under a player-editable working name — “the green rock” — until identified, and renaming it later preserves the history.
A reaction page shows the balanced equation once the player has established the stoichiometry, the conditions under which it was observed, the measured energetics, and a link to the best run.
A run entry records inputs (mass and composition), conditions, outputs, yield, duration and fuel, with unknown fields retained as unknown. Compare useful output per unit feed/fuel, product quality and waste under comparable conditions; a larger batch alone is not evidence of improvement.
Every page is cross-linked: a substance links to every reaction it appears in, every run it featured in, and every location it was found. The journal is a graph, not a list.
Everything is searchable and filterable, and the player can annotate, tag and star freely. Their notes sit alongside the recorded data and are never overwritten by it.

The journal’s presentation evolves

Matching §43.3’s futurism gradient, the journal itself becomes more sophisticated as the player does. This is one of the game’s best progress mirrors and costs only styling:

The journal is always hand-drawn. It never becomes a printed book. Every page, at every stage, is the work of the character’s own hand — because the moment it turns into typeset plates it stops being theirs and becomes a textbook someone handed them. The evolution is from uncertain to confident, not from handwritten to printed.

Stage	Presentation	The hand
Early	Charcoal, wobbly lines, guesses, question marks, crossings-out, smudged thumbprints	Unsure, hurried
Instruments	Pencil and straightedge, ruled tables, labelled axes, real figures with units, plotted points	Careful, learning
Late	Fine pen, confident linework, dense annotation, error bars, tight curves through real data	Practised, fluent

Early entries read “the green rock blackened and lost weight — something left as a gas?”. The same reaction, revisited at hour sixty, reads as a balanced equation with a measured enthalpy — still in pen, still in their handwriting, now with nothing crossed out. Scrolling back through one’s own journal and seeing that transformation is the intended emotional payoff of the whole design.

The map — the player’s own tech tree

The Map section renders the reaction graph the player has personally confirmed: substances as nodes, reactions as edges, with unexplored leads shown as dangling connections. This is the only place a technology tree is ever displayed (§38.1), and it is displayed because the player drew it themselves by doing the work. It shows what they know — never what exists.

Leads

Recorded anomalies that hint without instructing, generated from what the simulation actually did and never from a script. “Mass was lost. Nothing visible left the vessel.” Leads are the onboarding system and the curiosity engine, and they are the reason a player who is stuck always has somewhere to look.

Observation quality

Gated by apparatus and instruments (§29.4, §34.3): a reaction in an opaque crucible yields a vaguer entry than the same reaction in a glass flask. Improving the journal’s contents is therefore a reason to improve the laboratory — the two progressions drive each other.

“What just happened?” — the mandatory after-action account

Accurate science that remains inside the solver has no educational value. Every consequential ScienceEvent must be visible while it happens and rigorously reviewable afterwards. The run page opens with a short causal account assembled from the event record, not with flavour text and not with a designer-authored guess.

Each account answers, in this order:

What changed? Observable before/after quantities: mass moved, colour/glow, temperature, pressure, phases, gas evolution, precipitate, vessel damage, exposure or yield.
What evidence did I actually have? Direct senses, apparatus visibility and named instrument readings, with sampling time, resolution, calibration state and uncertainty. Absence of a reading is shown as unknown, never silently filled from catalogue truth.
What caused it? The accepted reaction extents, phase/transport events and energy flows that account for the change. Causal language is limited by the player’s evidence: initially “consistent with”; after identification and adequate measurement, “caused by”.
Why did it proceed, stop, or fail? Limiting reagent, sign and magnitude of affinity/ΔrG, Q versus K, activation/rate limitation, heat loss, mass-transfer limit, pressure relief, incompatible wall, or control/interlock action. A zero-yield run is required to address this too. Where observations cannot distinguish causes, state the uncertainty and propose a discriminating observation rather than selecting the correct hidden cause from the solver.
Where did the matter and energy go? Input/output balance, off-gas, spill, deposit, wall uptake, heat loss and work, with conservation residual and explicit unobserved/escaped categories.
How trustworthy is this answer? Source links, validity envelope, uncertainty and every active approximation from §28.9, including the 60× rate scale. Calculated, inferred and measured values are visually and textually distinct.

The event schema is append-only and deterministic: EventId, process/run ID, simulation tick, domain/apparatus ID, before/after state hashes, reaction/phase/transfer IDs, accepted extents, matter and energy flows, conditions, available observations, uncertainty, approximation flags and source IDs. It stores compact deltas and references stable catalogue/source IDs; prose and diagrams are views generated from those facts. Rewording UI copy can never change history. The C0 ScienceEventLog now enforces a bounded, contiguous committed prefix. ScienceVesselRun reserves log capacity before starting the solver, commits the whole batch before advancing its own temperature/tick state, and snapshots charge (including conservation traces), state and causal prefix as one validated restore unit. The remaining persistence integration is to encode that checkpoint in the world save’s single atomic replace transaction; separate vessel and journal files must never let one survive without the other before the journal can claim crash-safe causal history.

Visibility is a coverage contract for content. Every shipped reaction, phase transition, hazard and failure mode declares at least one in-world presentation channel and one journal explanation template. Colour alone never carries the meaning. Invisible hazards remain invisible: their channel is process context, an instrument/alarm, or honest nonspecific physiology—not a fictional coloured gas or toxin-specific superpower. If no truthful channel exists at a tier, the content is moved later, paired with an instrument, or cut.

The journal respects epistemic boundaries. It may retain authoritative event facts so saves and achievements can be verified, but player-facing pages reveal only what was observable or legitimately inferred. Later instruments may reanalyse a retained sample or old raw measurement; they may not retroactively claim a measurement that was never taken. Developer diagnostics may show ground truth, but are clearly marked and unavailable in the campaign.

Runs, observations, and useful explanations

A run starts with an explicit experiment action or a consequential operating change to an apparatus. Its boundary is persisted: completion, player stop, charge removal, failure, or a declared segment of continuous production. Returning to a furnace or reloading a save does not create a duplicate experiment. Continuous operation is grouped into comparable windows and significant changes; it must not produce twenty new journal pages per second.

The event log and the visible notebook have different granularity. Preserve committed causal facts; group routine events into views and deduplicate notifications without discarding history. Record observations at declared sensory/instrument cadence. Being nearby does not mean the character saw inside an opaque vessel, read every gauge continuously, or measured mass without a balance. Unattended equipment records only what its available logging capability supports.

Before advancing authoritative state, reserve bounded event capacity. State, transfers and event sequence share a commit boundary. If durable storage cannot keep up, show a saving pause and retry; do not drop events or grow an unbounded queue. Save/load/crash recovery yields one committed prefix with no duplicated transfers or journal entries. The UI indicates when recent progress is not yet durable; “saved” means the corresponding world and journal checkpoint can both be recovered.

Each run offers an optional prediction, one-change comparison, annotations and a next test. Automatic entries report evidence; player hypotheses stay labelled as hypotheses until supported. Discovery criteria must declare what observations suffice and what alternative explanations remain. A correct guess typed into a label does not certify identity, and background solver knowledge cannot award a revealing achievement before the player has evidence for it. No questionnaire blocks physical action.

The first after-action example should work without a thermometer or assay: “The green pieces became dark. A gas left the vessel. I did not collect or identify it. Try collecting the output and comparing another small sample.” Include mass loss only if mass was measured. Expand to identified chemistry and energy accounting as evidence becomes available; the early page remains a useful truthful account.

Help, legibility, and returning after a break

Help progresses from the player’s last observation to a suggested measurement, then—on request—to a reference-backed worked example. Reference material is labelled as such and does not count as the player’s discovery. This is compatible with “no unlocks”: assistance changes information, not the reaction catalogue. Repeated failure without new evidence must surface this help instead of requiring another identical batch. Templates can be drafted freely; a successful run adds a verified under these conditions label, not permission to use the template.

The journal opens at a short account with expandable evidence and equations. Search supports working names and known terminology; pins and bookmarks keep stable targets when pages reorganise. On return, show the last experiment, outstanding plant conditions that were observed, and the player’s next intention. Nobody should need to reconstruct a twenty-hour project from raw chronology.

Handwriting is the visual identity, but readable type, scalable text, high contrast, full remapping, toggle/hold alternatives and non-colour cues are baseline options. An accessible text view exposes the same evidence and uncertainty as a sketch. In-world diagrams keep numeric geometry correct; stylistic wobble must not shift a plotted measurement. Names, units, symbols, plural forms and explanation templates are localisable data, with persistent IDs independent of language. Store SI internally; optional display conversions retain units and measurement precision. Sources and model limitations have bundled summaries so journal interpretation does not depend on an internet connection.

Growth and reorganisation — the journal’s own arc

The journal grows organically and then reorganises itself, converging on a systematic reference work. This is the single best expression of §27.7’s purpose, because chaos resolving into order is what science actually is. The player does not merely accumulate facts; they watch their own understanding acquire a shape.

The architecture that makes this honest: the log is append-only and immutable; the organisation is a set of views over it. This is how real laboratory notebooks work — you never erase an entry, you supersede it — and it is also simply the correct software design. Nothing is ever lost, and the player can always drop back to raw chronology and read their own history in order.

Phase	Organisation	What triggers the shift
1. Log	Purely chronological. Scattered, duplicated, uncertain, contradictory	The default. This is what a real notebook looks like
2. Consolidation	Observations of the same thing merge into one page	Identification — realising “the green rock” and “the stuff from the ridge” are one substance
3. Classification	Families emerge: acids and bases, metals and non-metals, oxidisers and reducers, fuels and fluxes	Enough members of a family observed to see the pattern
4. Systematisation	The periodic table orders itself; reaction families group; the electrochemical series sorts by potential	Enough elements isolated and enough potentials measured
5. Reference	A complete, ordered, cross-referenced tree	Late game. The journal has become a book worth keeping

Reorganisation events are reward moments and should be presented as such: the journal visibly restructures itself, and the player feels a scatter of notes snap into an order they earned. They are generated only from real understanding — an identification the player actually made, a potential they actually measured — never on a timer and never from a script.

Order becomes prediction — the deepest lesson available

Once the journal systematises, its structure starts predicting. This is the most valuable thing the game can teach and it costs almost nothing to implement, because it falls out of real chemistry:

The periodic table’s gaps point at elements the player has not isolated, and the table’s structure says roughly what those elements should be like. This is precisely what Mendeleev did, and a player who predicts a property from a gap and then confirms it has done real science.
The electrochemical series, once sorted, predicts which metal will displace which — before the player tries it. A prediction that comes true is worth more than any unlock.
Reaction families predict that an untried analogous reaction should work.

The journal therefore stops being a record and becomes an instrument. Leads (above) are the game suggesting where to look; predictions are the player working out where to look — and the transition from the first to the second is the moment they stop being a student.

Extensiveness

The journal is meant to be large. A completed playthrough should produce hundreds of substance pages, hundreds of reaction pages, thousands of run entries, a filled periodic table, a full hazard register and a complete reaction map. It must be built for that scale from the start:

Paged, virtualised rendering; nothing loads the whole journal at once.
Fast search, filter and sort across every field.
Stable, meaningful ordering within every view.
Persisted efficiently and covered by §36.6’s save-integrity requirement — a player’s journal is the single most irreplaceable thing in their save file. Transactional writes, last-known-good recovery, checksums and migration tests must make accepted-event loss a release-blocking fault, not a promise made without a recovery mechanism.

Tone and reading level — binding

A thirteen-to-fifteen-year-old must be able to read and understand every word. This is a hard requirement on all player-facing science text: journal entries, leads, substance and reaction pages, hazard warnings, achievement descriptions and tooltips.

The critical distinction, and the one that is easy to get wrong:

Simplify the sentence. Never simplify the chemistry.

Reading level is about language, not about content. The reaction stays exactly as true as §27.7 demands; only the words used to describe it get easier.

Rules:

Real terms are used, not avoided. “Stoichiometry”, “calcination”, “equilibrium” and “electrode potential” all appear — each defined once, in plain language, at first use, then used confidently thereafter. Hiding a word because it is long is condescension, and it robs the reader of vocabulary they can take with them. Teaching the word is part of the point.
Short sentences. Active voice. Concrete before abstract. Say what happened, then say what it means.
Units always, explained on first use. “1123 K (kelvin — a temperature scale that starts at absolute zero; 1123 K is about 850 °C).” Once. Then just kelvin, forever.
Analogies must be grounded in things a fourteen-year-old has actually seen, and must not be lies (§27.7’s no-unlearning rule applies to analogies too — a misleading metaphor is a falsehood the player has to unlearn later).
No condescension. No mascot, no exclamation marks, no “Great job, scientist!”, no baby talk. The journal is the player’s own record and it addresses them as a capable person.
Measurements carry numbers and uncertainty. Do not replace an available measurement with “very hot”, but do not invent “1358 K” when only glow was observed. Qualitative evidence stays qualitative until an instrument supports a number.

The reading level stays constant as the journal evolves. §34.2’s presentation arc increases precision, not linguistic difficulty — a late-game page has exact figures, plotted curves and error bars, and is written in the same plain English as the first sketch. Sophistication shows up in the data, never in the prose.

Checkable standard: player-facing science text targets a Flesch–Kincaid grade level of roughly 8–10, and a content test asserts that every technical term in the catalogue has a plain-language definition registered for its first-use tooltip. A term without a definition fails the build.

This serves both audiences of §27.7 at once. Writing that a fourteen-year-old can follow is not writing an adult resents — it is simply good writing, and the adult who has forgotten their school chemistry needs exactly the same on-ramp.

Hard concepts are allowed — that is what diagrams are for

Some concepts in this game are irreducibly difficult: chemical equilibrium, Gibbs free energy, redox half-reactions, phase diagrams, the Nernst equation. They are not avoided, softened or replaced with a metaphor. §34.2’s reading-level rule governs the prose; it does not authorise removing the subject.

The answer to a hard concept is a good diagram, because a diagram carries structure that no amount of plain English can:

Diagram	Makes visible
Balanced equations, properly typeset with subscripts and state symbols	Stoichiometry — the ratios that are also the factory ratios (§27.3)
Reaction energy profile	Activation energy, ΔH, and exactly what a catalyst does (and does not) change
Phase diagram	The bronze eutectic (§37.3). One picture explains the Bronze Age
Ellingham diagram	Which reducing agent works at which temperature — see below
Electrochemical series ladder	Which metal displaces which, and why electrolysis is needed at all
Apparatus cross-section	The player’s own vessel, cut open, with heat and gas paths drawn
Process flow diagram	Their factory as a real PFD, with actual mass flows on the arrows
Sankey diagram	Where the fuel actually went — usually a shock, and the best efficiency lesson available

The Ellingham diagram deserves particular attention. It plots the free energy of oxide formation against temperature, and reading it tells you directly which reductant will strip oxygen from which oxide at which temperature — including the crossover where carbon becomes able to reduce a given ore. It is the single most useful diagram in extractive metallurgy, it explains the entire early game, and a player who learns to read one has learned a genuine professional skill. The Boudouard reaction (§36.3) is the line on that chart that makes the whole thing work.

Two rules keep diagrams honest and useful:

Diagrams are generated from the player’s own data, not shipped as stock illustrations. Their Ellingham chart shows the lines they have actually established, with the rest blank. Their Sankey shows their furnace’s real losses. A diagram is a view onto the journal’s log (§34.2), so it inherits the same “only what was observed” rule.
Progressive disclosure — every page is layered. Plain-language summary first, then the diagram, then the full mathematics on demand. Nobody is forced down to the equations; nobody is prevented from reaching them. This is the mechanism that lets one page serve a curious fourteen-year-old and a chemist without patronising either — which is exactly the dual audience §27.7 asks for.

Everything is sketched — the character drew this

Every diagram must look drawn by hand, by the character, at the bench. Not a clean vector chart, not a textbook plate — a sketch by the person holding the pencil.

Wobble and imperfection are the style. Lines are not quite straight, circles are not quite round, axes are ruled but slightly off, labels sit at a slight angle. Nothing is machine-perfect.
Working is left visible. Crossings-out, corrections, an earlier wrong guess with a line through it, arrows added later, a note squeezed into a margin. A page that shows its mistakes is worth more than a clean one, because it is a record of thinking rather than a statement of fact.
The medium tracks the era — charcoal, then pencil, then pen — matching §34.2’s confidence arc.
Notation is correct but hand-lettered. Subscripts, state symbols and coefficients are all chemically right and fully legible; they are simply written rather than typeset. Accuracy is never traded for style — the diagram must still teach.
Annotations are the character’s own voice at §34.2’s reading level: “this only works once it’s hot enough — see where the lines cross”.
Implemented with a hand-drawn rendering style over generated data, so a diagram stays accurate to the underlying measurements while looking sketched. The data is real; the pen is imperfect.

This carries a real design benefit beyond charm. A hand-drawn chart reads as provisional and personal — something the player made and could be wrong about — which invites them to test it. A crisp printed chart reads as authority handed down, which invites them to accept it. The first is science; the second is homework.

The nudge: a mark and a scratch of pencil

When something is recorded, the entire notification is a small symbol and the sound of writing. That is all it needs to be.

The sound does the work. A short scratch of charcoal or pencil on paper — the character noticed something and wrote it down. It is diegetic, quiet, and instantly legible.
The symbol is a small quiet glyph near the journal indicator, with an unread mark that persists until the page is actually opened.
It never says what was learned. This is the rule the whole mechanic depends on: if the notification summarises the finding, the player has already received it and will never open the journal. The cue says “something was written” — never “you have discovered calcination”. Curiosity is the reward loop, and a toast that explains itself destroys it.
Never modal, never pausing, never blocking. No popup, no forced read, no confirmation. The player opens the journal when they choose — mid-process if they are curious, later if they are busy.
Batched. A long run that records six observations gives one cue at a natural pause, not six interruptions.
Weighted only slightly. A major entry — a first isolation, a confirmed reaction — gets a longer, fuller scratch; a minor observation gets a brief tick. Enough to tell “worth stopping for” from “read it later”, and no more.
The writing medium matches the era (§34.2), so the sound itself ages with the player: dry charcoal scrape early, pencil later, fine pen at the end. A small detail that quietly marks progress every single time it plays.
Accessibility per §45.5: the visual cue alone and the audio cue alone must each be sufficient, and both are subject to independent volume and intensity settings.

The target feeling is precise and worth stating: the player hears the pencil, thinks “what did I just figure out?”, and opens the book straight away. If the notification ever makes opening the journal feel like a chore rather than an answer to a question, it has been designed wrong.

Export

The player can export their journal as a readable document. This is a small feature with a large effect: it makes the artifact theirs, it is genuinely shareable, and for the adult audience of §27.7 it turns eighty hours of play into something that looks like — and substantially is — a real record of real science.

34.3 Instruments reveal information, never capability

Every instrument makes something already true legible. None of them unlock a reaction.

Balance (mass, density) → thermometer/thermocouple (measured temperature with uncertainty, replacing glow-colour estimation) → limewater bubbler and gas tests → flame test (identifies metal ions) → hydrometer → pH indicators from plant matter, then real pH → voltmeter and ammeter → spectroscope.

The voltmeter deserves emphasis: it is the instrument that makes §28.6 visible. Before it, redox is inferred; after it, the player can measure a cell potential and check it against the electrochemical series they are assembling in their own notebook.

34.4 Achievements for true chemical milestones

Achievements mark genuine firsts, verified by the simulation. An achievement is granted only when the reaction engine actually resolved the event with conservation intact — never by a quest flag, never by entering a room, never by clicking a node. This is the honesty rule (§27.4 pillar 7) applied to reward design.

Each achievement records the real chemistry that earned it, so the achievement list doubles as a readable history of the player’s science:

Milestone	Earned by
Combustion	First controlled burn
Pyrolysis	First charcoal from a sealed retort
Calcination	First quicklime — first time you decomposed a mineral
Reduction	First metal from an ore. The big one
Alloy	First deliberate solution-phase alloy
Distillation	First separation by boiling point
Vitrification	First glass
Acid	First mineral acid isolated
Galvanic	First measured cell potential
Electrolysis	First reaction driven against ΔG by applied potential
Induction	First current generated from motion in a magnetic field
Faraday verified	Predicting theoretical yield from `m = ItM/zF`, measuring current efficiency, and matching realised yield
Isolation: <element>	Each element first obtained in pure form. A collection that spans the whole game
Closed loop	First self-sustaining ecological cycle
Fusion gain	First sustained fusion run exceeding the declared `Q_plasma` target; not called “criticality”, which belongs to fission chain reactions

Hazard achievements exist too, and they are respectful rather than mocking — surviving a first CO exposure, a first rupture, and a first successful emergency shutdown are all real learning moments.

35. The Energy Ladder and the Endgame

35.1 The game is one climb

Every tier the player reaches is a higher energy density commanded with more precision, and electromagnetism is the tool at every rung. Stating this explicitly keeps the endgame from feeling bolted on — it is the same arc it always was.

Tier	Energy source	Scale	What the player commands
Fire	Chemical bonds	~1 eV	Heat, crudely
Furnace	Chemical, forced air	~1 eV	Temperature and atmosphere
Steam	Chemical → mechanical	~1 eV	Work
Electrical	Mechanical → EM	~1 eV	Electrons, directly
Electrochemical	Applied potential	~1–5 eV	Non-spontaneous reaction directions
Nuclear	Nuclear binding	~1 MeV	Confinement

The jump from the fifth rung to the sixth is six orders of magnitude, and it is earned.

35.2 The stellarator

The endgame is a mobile stellarator: a magnetically confined fusion reactor small enough to fly. It is the correct final object for this game specifically because a stellarator is the purest expression of pillar 2 — it holds a plasma in a twisted magnetic field with no confining material at all. Everything the player has learned about electromagnetism, from the magnetic separator in §32.1 through the generator in §32.4, terminates here.

It demands, and therefore validates, the entire tech chain:

Superconducting coils — the metallurgy, purity and cryogenics chain at its limit.
Cryogenics — liquefied gases, which is distillation and compression from §29 and §32.
High vacuum — pumps, seals, leak detection. A gas-handling problem.
Fuel — deuterium separated from water and, for the D–T route, tritium bred from lithium and accounted with its decay/inventory. Isotope handling is the final chemistry.
Plasma-facing materials — refractory metals, the top of the materials ladder.
Confinement geometry — the coils must actually be built correctly in the world.

Fusion is modelled at the same honesty standard as everything else (§28.9): a curated, approximated model of confinement, fuel, and power balance, with its simplifications written down. Every displayed gain names its definition: Q_plasma = P_fusion/P_external-heating is not wall-plug breakeven or net electric power. The declared target must be achieved by the model, not granted.

35.2.1 Unstable plasma, then stable plasma

Fusion is not a switch. It is the last and hardest turn of §27.6’s loop, and it has two distinct phases that must feel completely different to play.

Phase one — unstable. The player achieves plasma before they can hold it. This is a genuine, playable failure state, not a cutscene. The plasma is real, it is producing neutrons, and it is trying to destroy the machine:

Loss-of-confinement events and radiative collapse — energy and particles reach plasma-facing surfaces rapidly. Do not copy tokamak current-disruption behaviour into a stellarator without a sourced mode model.
Pressure-driven and resonant MHD modes — profiles and magnetic islands degrade confinement; exact mode names appear only where the reduced model supports them.
Impurity radiation — sputtered wall material poisons the plasma and radiates the energy away. This is where §30.2’s purity obsession finally pays off at the top of the ladder.
Density limits and fuelling — too little fuel and it dies, too much and it disrupts.

Phase one is won with diagnostics and instrumentation, which is the same lesson as §34.3’s instrument ladder at maximum stakes: you cannot control what you cannot measure. Magnetic pickup coils, interferometry, spectroscopy of the impurity lines. The player is not fighting the plasma yet; they are learning to see it.

Phase two — stable. Sustained confinement is won first by correct three-dimensional coil and magnetic-surface geometry, then by diagnostics and plant control over density, heating, fuelling, impurities, exhaust/divertor load and magnet protection. Early PID lessons transfer, but the final controller may be coupled/model-based; the game does not claim that one fast PID can suppress every plasma instability by changing stellarator coil current.

The transition between phases is the game’s final and hardest-earned achievement (Fusion gain, §34.4), and it is the exact moment the loop that began with a player poking a rock into a fire closes.

35.3 The ship, the voyage, and the boss

The spacecraft is a vehicle the player builds and provisions. Its life support is §33.3’s closed loop with no margin for error: CO₂ scrubbing, O₂ generation, water recycling and thermal balance, all of which the player already understands, now with a hard failure mode.

The voyage is where the game’s threat model finally externalises — but it does so without abandoning pillar 5. The antagonist is not an HP sponge to be hit with a sword, and the game does not grow a combat system in its last hour. It is a hostile environment and system that must be defeated with the toolkit the player spent eighty hours building: reactions, materials, power, control loops, remote operation via drones, and the discipline to keep their own life support running while under pressure. The design constraint is explicit and binding:

Every phase of the final encounter must be solvable by applying chemistry, materials or electromagnetics the player already understands. No phase may require a mechanic introduced solely for the encounter.

Escape and return home closes the loop the game opened with: you arrived with nothing and understood nothing; you leave having taken the world apart and put it back together, and the way out is the same way everything else was — by knowing what things are made of.

35.4 Scope honesty

§35 is the far goal, not MVP, not the next milestone, and not a promise with a date. It is recorded here so that every system built before it is built in a direction that leads somewhere, and so that no earlier design decision quietly forecloses it. Nothing in §35 may become a correctness dependency of any earlier milestone. If the project ships only through §36.6’s MVP gate, it is still a complete game.

36. Chemistry Implementation Plan

36.1 Assembly layering

Part I’s layering (§5.1) is extended, not rearranged. The one-directional rule is unchanged.

Core  →  Chemistry ─┬─→ Data  →  World ─┬─→ Industry ─┬─→ Player  →  UI
                    │                   │             │
                    └───────────────────┴─→ Inventory ┘

VoxelSandbox.Chemistry — new, and the most important boundary in the project. Substances, reactions, thermodynamics, electrochemistry, kinetics, reaction-domain state transitions and compact ScienceEvent facts. No UnityEngine reference, no Burst, no Jobs (§28.8 forbids Burst here). Headless-runnable so the standalone server and the test harness use the identical implementation.
VoxelSandbox.Data — gains substance/reaction ScriptableObject authoring and BlockDefinition.Composition, and bakes them into the Chemistry core’s plain tables. Catalogue integrity (unbalanced equation, missing thermodynamic data, out-of-range Shomate, duplicate ID) surfaces as ReactionCatalogIssue / SubstanceCatalogIssue, following the existing BlockCatalogIssue pattern.
VoxelSandbox.Industry — new. Machines, vessels-in-world, belts, pipes, drones, power networks, process control. Depends on World, Chemistry and Inventory.
Voxel Workshop gains Chemistry Lab (substance/reaction inspection, a vessel scratchpad, thermodynamic plots), Process Lab (run a vessel headless and chart the result) and Assay Lab (block composition and ore-grade inspection) as modules per §18.2, not standalone windows.

36.2 Staged foundation substance set

Roughly 40 phase-aware species records establish the core catalogue, but only the T0–T5 subset is required to be obtainable and playable for MVP. Entries needed solely for validation or later tiers may ship as unreachable reference content; their presence does not silently expand §36.6.

Gases — O₂, N₂, CO, CO₂, H₂O(g), H₂, CH₄, SO₂
Carbon — C(graphite/charcoal), biomass surrogate CH₁.₄O₀.₆, tar surrogate, pyroligneous surrogate
Silicates and oxides — SiO₂, Al₂O₃, FeO, Fe₂O₃, Fe₃O₄, MgO, Na₂O, K₂O
Calcium chain — CaCO₃, CaO, Ca(OH)₂, CaSiO₃, MgCO₃
Copper chain — Cu₂CO₃(OH)₂ (malachite), CuO, Cu₂O, Cu, Cu₂S, CuFeS₂
Tin chain — SnO₂ (cassiterite), Sn
Solution phases — bronze (Cu–Sn), slag (CaO–SiO₂–FeO)
Water and salt — H₂O(l), H₂O(s), NaCl, Na₂CO₃

36.3 Staged foundation reaction set

Roughly 40 reactions, with the T0–T5 subset forming MVP. Every thermodynamic value is sourced; every kinetic model follows §28.5’s source/approximation contract; and redox records derive rather than duplicate ΔrG°, electron count and E°.

Combustion      C + O2 -> CO2                       ΔH = −393.5 kJ/mol
                2 C + O2 -> 2 CO                     ΔH = −221.0
                2 CO + O2 -> 2 CO2                   ΔH = −566.0
Boudouard       C + CO2 <-> 2 CO                     ΔH = +172.5   ← the keystone
Pyrolysis       biomass -> C + volatiles + tar       endothermic, surrogate
Calcination     CaCO3 -> CaO + CO2                   ΔH°298 ≈ +178.3; equilibrium depends on CO2 pressure
Slaking         CaO + H2O -> Ca(OH)2                 ΔH = −63.7    ← early hazard
Carbonation     Ca(OH)2 + CO2 -> CaCO3 + H2O         mortar sets
Malachite       Cu2CO3(OH)2 -> 2 CuO + CO2 + H2O     roasting
Reduction       CuO + CO -> Cu + CO2                 ΔH = −127.0
                2 CuO + C -> 2 Cu + CO2
                SnO2 + 2 CO -> Sn + 2 CO2
Alloying        Cu(l) + Sn(l) -> solution            NOT a compound
Oxidation       2 Cu + O2 -> 2 CuO                   tarnish
Slag            CaO + SiO2 -> CaSiO3                 flux chemistry
Glass batch     carbonate decomposition + silicate solution (post-MVP; not one compound)

The Boudouard equilibrium is called out because it is the reaction the whole early game rests on, and its direction must emerge from §28.5’s Q, K and reversible-rate contract rather than being special-cased. Validate it over a sourced temperature/pressure/composition range; no single “crossover temperature” is asserted without its state.

36.4 Milestones

Chemistry milestones are numbered C0–C7 so they never collide with Part I’s M0–M9. Each ends with a runnable testbed or build and a pass/fail gate. Do not begin a later milestone while an earlier correctness gate is open — Part I’s rule, unchanged.

Correctness ordering does not defer all player feedback until C5. C0 defines event/observation contracts; each C1–C4 slice includes a thin in-world presentation and after-action view for its own behaviour. C5 expands that tested path into the complete notebook. A model with no readable consequence cannot be declared complete while its interface is postponed to a later milestone.

That rule was stated and not enforced, so it was not followed. C0–C2 produced correct, conserved, thoroughly tested chemistry that no player can touch, and nothing in this plan stopped that from continuing. §36.4a below turns the rule into a gate type — the P-gate — which every milestone from C1 onward must close in a clean build before the next milestone opens. Headless correctness and Editor tooling are necessary and are not sufficient: a slice no player can reach is not a landed slice.

Task format. From C1-P onward, each milestone’s tasks are written as discrete numbered entries in the form below, so that one task is one agent session’s work and its boundaries are legible without reading the rest of the plan:

Depends — the task IDs that must close first. A task with no open dependency is startable.
Touches — the files or directories expected to change. A task that must edit outside its declared surface is mis-scoped; stop and re-split it rather than widening it silently.
Do — the change, in outcome terms.
Done when — one falsifiable assertion. Not “works correctly”, but a condition a test or a gate artifact can be checked against.
Out of scope — the adjacent work this task must not absorb. This field is binding; it is the only defence against a small task growing into its neighbours.

C0’s and C4–C7’s task prose stays as written until each milestone is next in line. Expanding it now would invent detail ahead of the knowledge needed to write it accurately (§49.5).

§36.4a — The player-interaction gate (P-gate)

The gate this plan was missing.

A P-gate closes only when all three conditions hold in a clean build of the Gameplay scene:

Reachable. A player operates the slice with normal input — movement, look, the interact verb, the inventory. No Editor, no Play-mode-only wiring, no inspector field set by hand, no console command, no Voxel Workshop module anywhere in the loop.
Legible. The player learns what happened through an in-world channel or the journal. §27.7’s “matter matters” is not taught by a value that is merely correct: a truth appearing solely in a log line, a test assertion or an Editor inspector has been presented to nobody.
Durable. The slice survives save → quit → reload with its causal record intact, and the reloaded state continues simulating from where it stopped (§29.5).

What does not close a P-gate, however green it is:

An EditMode or PlayMode test. Tests prove the model; they do not prove a player can reach it.
A Voxel Workshop module. Workshop is permanently a diagnostic and authoring surface for the developer (§18). It is never the player’s interface, and a module is never evidence that one exists.
A headless assertion or a console log on its own.
A MonoBehaviour that would work if something instantiated it. Nothing instantiating it is the defect.

Evidence. Each P-gate commits an artifact set under Docs/Gates/<gate-id>/:

the -batchmode Editor harness that drives the slice, living under Assets/_Game/Editor/Gates/ and referenced from the artifact rather than duplicated into it;
<gate-id>.png, a screenshot of the player-visible result;
<gate-id>.txt, the harness’s assertion output, including the run’s conservation residual.

The artifact exists so an agent can close its own gate and a reviewer can audit the claim months later without rebuilding it. A gate asserted in prose with no artifact is open.

Scope discipline. A P-gate demands the thinnest interface satisfying the three conditions. It is not licence to build the milestone’s finished UI. Where a later milestone owns the full surface — C5 owns the notebook — the P-gate builds the minimum readable view and says so explicitly, and the later milestone replaces it rather than being pre-empted by it.

C0 — Thermodynamic core

The riskiest milestone. Do it first, headless, with no Unity in the loop.

Tasks: substance/element tables; Shomate Cp and temperature-corrected ΔH/ΔS/ΔG; equilibrium constant; activity and reaction quotient by phase; sourced forward/reverse kinetics with detailed balance; electrochemical half-reactions, E°, the ΔG = −nFE bridge, and Nernst; energy balance; phase transitions with latent heat; the deterministic sub-stepping rule; compact causal ScienceEvents.

Gate:

Reproduces published reference values within a stated, written-down tolerance for a validation set including: CaCO₃ equilibrium CO₂ pressure across several temperatures (including a sourced one-atmosphere point), Boudouard equilibrium over several stated pressures/compositions, an explicitly defined adiabatic carbon/oxygen flame case, and the standard potential of at least six redox couples.
ΔG = −nFE round-trips consistently for every electrochemical reaction at the same stated conditions/standard state.
Atom conservation and charge conservation hold across 10 000 randomised vessel scenarios.
Determinism: identical results bit-for-bit across a repeat run, a second process, every shipped runtime/architecture, and a different neighbour-simulation order (§28.8); reaction-ID permutation remains physically equivalent within tolerance.
Zero steady-state allocation in the solver.

C1 — Vessels and apparatus

Tasks: Vessel, wall materials with thermal/chemical/mechanical failure, sealing modes, venting, pressure, ports, quiescence; the MVP apparatus (§29.3); heat transfer to environment. Include fabrication/handling (§29.6), pause/off-screen lifecycle (§29.5), and a minimal run view.

Gate: in a testbed, a player can pyrolyse wood to charcoal, calcine limestone to quicklime, and reduce malachite to copper — each with atom/charge balance exact by construction, documented energy residual and plausible fuel consumption. A deliberately inadequate crude vessel fails, while the reachable upgraded furnace/refractory route succeeds; failure may not close the only T0–T5 bootstrap. Every attempt has an inspectable record, including stopped and failed runs; inventory transfer, leaving rendering range, pausing and reloading cannot change its ownership or advance only one clock.

C1-P — The player reaches the chemistry (hard-blocking)

No new C2, C3 or C4 work opens while this gate is open. Work already landed under those milestones stays — it is correct and it is tested. It is simply not yet a game, and no further depth is added beneath a surface that does not exist.

The chain this milestone needs already exists in code and is unit-tested end to end: TerrainGenerator.GetOreGradeAt → MaterialBatchFactory.TryFromMinedBlock → MaterialBatch → MaterialBatchCharging.TryChargeIntoVessel → VesselCharge → VesselDomain. What is missing is every link between a player and its first function call.

C1-P.1 — A vessel exists in the world

Depends — nothing. Startable.
Touches — Assets/_Game/Scripts/Industry/Vessels/, one apparatus definition under Assets/_Game/Data/, and the Scene Composer module under Assets/_Game/Editor/VoxelWorkshop/.
Do — give VesselRuntime a physical form: a placeable, rendered, collidable object with a position in the world, created through the same placement path as anything else the player places (§29.6). Placement validates its footprint and refuses invalid positions. Note the existing convention before choosing an approach: this project contains no .prefab assets at all — every piece of project-owned content is composed procedurally by a Voxel Workshop module (Scene Composer builds the scenes, Texture Foundry the tiles, Enemy Lab the enemy rigs). The vessel’s form follows that path. Introducing a prefab convention as a side effect of this task is out of scope and would be the project’s first, which is a decision, not a detail.
Done when — a headless harness places one from script, and a screenshot shows it standing in the Gameplay scene at the requested coordinate with a collider the player cannot walk through.
Out of scope — ports, wall materials, tiers, fabrication cost, dismantling. One vessel, one form.

C1-P.2 — The player can target it

Depends — C1-P.1.
Touches — Assets/_Game/Scripts/Player/, Assets/_Game/Scripts/Player/*.asmdef, Assets/_Game/Scripts/Industry/*.asmdef.
Do — extend BlockInteractionController’s centre-screen raycast to resolve non-block targets, and show VoxelTargetOutline on one. (§23’s PlayerInteractor was a suggested name and was never the built one; BlockInteractionController plus InventoryBlockInteractionService is the real interaction path.) This task authorises the Player → Industry assembly reference, which §36.1’s one-directional graph permits and which no session may add on its own initiative — it is sanctioned here and nowhere else. Industry gains no back-reference to Player.
Done when — looking at a vessel yields a target result distinct from the block behind it, asserted by test, and the outline appears on it in the gate screenshot.
Out of scope — the interact verb itself, any transfer, any UI panel.

C1-P.3 — Carried ore charges the vessel

Depends — C1-P.2.
Touches — Assets/_Game/Scripts/Player/MaterialBatchDropRuntime.cs, Assets/_Game/Data/Blocks/Definitions/, the Scene Composer module under Assets/_Game/Editor/VoxelWorkshop/, Assets/_Game/Scripts/Industry/Vessels/.
Do — three parts, because the first half of this chain is already written and is nonetheless doing nothing:
1. Author Composition on a real ore block. Only Oil.asset and Water.asset carry one today and both are headless test fixtures, so the runtime below is a silent no-op on every block a player can actually mine. Malachite is the one C1-P needs.
2. Compose MaterialBatchDropRuntime into the Gameplay scene. It already samples GetOreGradeAt at the mined coordinate and merges the batch into PlayerInventory.BulkMatter — and nothing instantiates it, which is precisely §36.4a’s “would work if something instantiated it” defect.
3. Build the missing half: the interact verb on a targeted vessel transfers BulkMatter through MaterialBatchCharging.TryChargeIntoVessel. All-or-nothing, exactly one owner at every instant (§30.5) — a failed transfer leaves the batch with the player, unchanged.
Done when — a harness mines malachite at a known coordinate, charges a vessel, and the vessel’s moles match MaterialBatchFactory’s prediction for that block’s grade within the conservation tolerance, while the player’s carried mass falls by exactly the charged mass.
Out of scope — transfer UI beyond the interact verb, partial transfers, batch volume and carry capacity, multi-phase batches.

C1-P.4 — It runs, and the world shows it

Depends — C1-P.3.
Touches — Assets/_Game/Scripts/Industry/Vessels/, Assets/_Game/Scripts/World/Presentation/.
Do — the player supplies heat and the vessel ticks its VesselDomain at 20 Hz while they watch. Its temperature drives BlackbodyEmission on the vessel’s actual surface — §49.4’s P1 thermal-glow handoff, reaching a real renderer for the first time. The glow is a coarse Planckian thermometer and is journalled as one (§37.4); it is not a readout.
Done when — a harness charges and fires a vessel, and screenshots at two stated temperatures differ in emitted colour in the direction the sourced Planckian curve requires.
Out of scope — smoke and plume VFX (§47), audio, hazard exposure (C3), and any heat source beyond the simplest one that closes this task.

C1-P.5 — The player can read what happened

Depends — C1-P.4.
Touches — Assets/_Game/Scripts/UI/, Assets/_Game/Scripts/Industry/Vessels/.
Do — a minimal in-game view over VesselRuntime.TryBuildLatestAfterActionNarrative, rendering the AfterActionLine[] the §34.2 narrator already produces. It honours the narrator’s epistemic labels exactly: an unmeasured identity stays unmeasured (§28.10), and no catalogue truth reaches the screen that the run did not observe.
Done when — a harness performs one reduction and one deliberately failed run, the committed screenshots show a causal account of each, and a test asserts every displayed line traces to a ScienceEvent and that an unobserved reaction ID cannot appear.
Out of scope — the notebook. LabNotebook, persisted entries, leads, the glossary tooltip layer, achievements and bookmarks are all C5. This is one panel showing the latest run, and C5 replaces it.

C1-P.6 — It survives a reload

Depends — C1-P.5.
Touches — Assets/_Game/Scripts/World/Persistence/, Assets/_Game/Scripts/Industry/Vessels/.
Do — persist the vessel, its charge and its committed ScienceEvent prefix through AtomicWorldSaveFile, carrying a chemistryVersion field and validating before restore, reusing the existing save patterns rather than writing a new one. Restoring resumes the run’s clock where it stopped and never advances it — §29.5 forbids offline catch-up in MVP.
Done when — a harness charges a vessel, saves, reloads, and finds identical charge, identical temperature and a byte-identical event prefix; continued simulation from the reloaded state is bit-identical to the uninterrupted run (§28.8).
Out of scope — save-format migration, compaction, and the journal’s own persistence (C5).

Gate: in a clean Windows build, with no Editor and no Workshop module in the loop, a player walks to an ore body, mines it, places a vessel, charges it, fires it, watches it glow, reads a truthful causal account of what it produced, saves, quits, reloads, and finds all of it intact. The §36.4a artifact set for c1p is committed. Every hop conserves mass and charge, and the run’s energy residual is recorded rather than assumed.

This is the project’s first proof that the chemistry is a game and not a library.

C2 — Block composition, geology, and assay

Much of this milestone’s model has landed headless. Docs/HANDOFF.md holds the authoritative build state; the status marks below are a planning summary and defer to it on conflict.

C2.1 — Block composition · landed

BlockDefinition.Composition, BlockCompositionComponent, BlockCompositionCharging. Conserved and tested; consumed by C1-P.3.

C2.2 — Ore-body grade field · landed

OreGradeMath (rich core, lean halo, skewed lean) and TerrainGenerator.GetOreGradeAt as a deposit-gated query seam that changes no generated blocks. Grade is a pure function computed on demand; nothing in a generated world stores one.

C2.3 — Mined block → vessel charging · landed

The grade-aware BlockCompositionCharging overload plus the MaterialBatch route, cross-checked to the mole against the direct path.

C2.4 — Assay and its honest error bar · landed, developer-side only

OreAssayMath (hand specimen / density / fire assay, with the swept |measured − true| ≤ uncertainty invariant), OreAssayNarrator, and the Assay Lab module. The Workshop module is not the player’s assay (§36.4a); C2.7 owes the in-world one.

C2.5 — Slag as real output

Depends — C1-P (gate), C2.1.
Touches — Assets/_Game/Scripts/Data/Chemistry/ (ReactionDefinition / ReactionCatalog), Assets/_Game/Scripts/Chemistry/.
Do — author the gangue + flux → slag reaction (CaO + SiO₂ → CaSiO₃ and the FeO-bearing case) as a real catalogue entry with sourced thermodynamics, so gangue leaves a smelt as a distinct condensed phase rather than vanishing. Slag is matter and is accounted as matter.
Done when — a reduction charged with gangue-bearing ore closes its atom balance with the gangue ending in a slag phase, and a test rejects any path that discards it.
Out of scope — slag tapping, disposal, its use as a construction material, glass batch chemistry.

C2.6 — Beneficiation changes the outcome

Depends — C2.5.
Touches — Assets/_Game/Scripts/Industry/, Assets/_Game/Scripts/Inventory/.
Do — crushing and screening that raise a batch’s grade at a real cost in work and losses, so the §27.3 distinction between the stoichiometric ceiling and actual yield becomes something the player causes rather than reads about.
Done when — smelting beneficiated ore is measurably better than the same ore unbeneficiated, in both fuel consumed and copper produced, with the difference predicted before it is measured.
Out of scope — the jig, mechanical drive and automated feed — those are C4.

C2.7 — Prospecting and assay in the player’s hands · P-gate

Depends — C1-P (gate), C2.4.
Touches — Assets/_Game/Scripts/Player/, Assets/_Game/Scripts/UI/.
Do — the player takes a sample from a deposit or a carried batch and runs an assay with a current-tier instrument, receiving OreAssayNarrator’s reading with its uncertainty. The sample is conserved and consumed where the method consumes it (§30.5). Unmeasured composition stays unmeasured: §30.4’s instrument-gated legibility is enforced at the UI, not merely in the narrator.
Done when — the §36.4a artifact set for c2-assay shows a player-run assay reporting a grade and an error bar, and a test asserts an unassayed batch displays mass but never composition.
Out of scope — prospecting instruments beyond the first, deposit-wide inference from one sample (§30.5 forbids it), the notebook’s assay history (C5).

C2.8 — Seed sufficiency · landed

The §39.9 quantity- and route-aware seed check.

Gate: atoms are conserved across the world↔vessel boundary; ore grade varies within a body and is measurable by the player; smelting unbeneficiated ore is measurably worse than beneficiated ore in fuel and yield; a fixed seed reproduces identical deposits. C2.7’s P-gate is closed under §36.4a.

C3 — Hazards and vitals

Advanced respirators and detectors remain staged per §49.1. C3 is where C1’s vented gas stops being apparatus-local: §49.4’s P1 note requires those facts to reach a real ledger here, and no implementation may call vented gas harmless or deleted in the meantime.

C3.1 — The atmosphere is a place matter can go

Depends — C1-P (gate).
Touches — Assets/_Game/Scripts/Chemistry/, Assets/_Game/Scripts/World/.
Do — sparse atmospheric domains as §28’s reaction-domain/control-volume contract applied to open air, plus the persistent regional mass ledger that receives matter when a domain merges or sleeps. Budget is §36.7’s ≤ 64 active domains, held by conservative merge and handoff — never by deletion.
Done when — a randomised suite of domain creation, merge, sleep and handoff sequences conserves atoms across the active-plus-regional total, and domain count stays within budget under a stress fixture.
Out of scope — buoyancy, wind, ignition, physiology, visual plumes.

C3.2 — Vented gas arrives

Depends — C3.1.
Touches — Assets/_Game/Scripts/Industry/Vessels/, Assets/_Game/Scripts/Chemistry/.
Do — route VesselGasVented and the rupture path into C3.1’s domains, closing §49.4’s P1 vessel-lifecycle delta. Open vessels and relief valves stop being sinks; the gas they lose becomes gas that is somewhere.
Done when — a vessel vented to open air shows the vented moles present in the receiving domain, and a test rejects any venting path that does not name a destination.
Out of scope — what the gas then does to anyone.

C3.3 — Mixing, buoyancy and wind

Depends — C3.1.
Touches — Assets/_Game/Scripts/Chemistry/, Assets/_Game/Scripts/World/.
Do — inter-domain mixing, density-driven buoyancy, and WindField advection, so a gas accumulates where its density and the geometry say it accumulates. CO pooling in an unventilated space is the case the milestone exists for.
Done when — a sealed low space accumulates CO from a nearby burn while an equivalent ventilated space does not, both conserving the regional total.
Out of scope — weather coupling, inversions, deposition (§49.1 defers all three).

C3.4 — The body keeps its own books

Depends — C3.3.
Touches — Assets/_Game/Scripts/Player/, Assets/_Game/Scripts/Chemistry/.
Do — extend the existing PlayerVitals (today Health and Hunger only, with PlayerVitals the plain model and PlayerVitalsRuntime its driver) with BloodOxygen, ToxicLoad and CoreTemperature, driven by dose — concentration integrated over exposure time — against sourced thresholds. Follow that file’s existing TryXxx(..., out …) shape rather than adding a second vitals model. §31.2’s rule binds: hazard-specific reduced physiology, with published averaging durations preserved as reference bands rather than collapsed into one interchangeable cliff value.
Done when — each modelled hazard reproduces its sourced dose-response fixture within a stated tolerance, and a test rejects any threshold lacking a Docs/CHEMISTRY_SOURCES.md citation.
Out of scope — burns, chronic injury recovery (D2’s treatment arc), neurotoxic and tremor effects (§49.1 defers them).

C3.5 — The warning the player can act on · P-gate

Depends — C3.4.
Touches — Assets/_Game/Scripts/UI/, Assets/_Game/Scripts/Player/, Assets/_Game/Scripts/World/Presentation/.
Do — the truthful warning channels of §31.1 and the §45 shader subset MVP admits — hypoxia, CO, thermal burn. Invisible hazards stay invisible: CO gets no colour, no smell and no magical sensory cue. What the player gets instead is a real inferential path — the fire’s behaviour, the symptoms, the process evidence — that a person can read before it is lethal.
Done when — the §36.4a artifact set for c3-warning shows the pre-lethal warning path for a CO accumulation, and one test per avoidable lethal scenario asserts an available, actionable, honest warning existed and that no test passes by inventing a sense humans lack.
Out of scope — respirator classes and breakthrough, detectors, radiation and irritant shaders.

C3.6 — Ventilation, and rupture into the world

Depends — C3.5.
Touches — Assets/_Game/Scripts/Industry/, Assets/_Game/Scripts/Chemistry/.
Do — the MVP ventilation the player builds to survive C3.5, plus flammability limits, ignition, and vessel rupture expressed into the atmospheric domains rather than as a local effect.
Done when — an unventilated charcoal operation can kill via CO and a correctly designed one cannot, both conserving the regional ledger; a rupture’s contents appear in the receiving domain.
Out of scope — mechanically driven bellows (C4), structural collapse (§49.1 defers it).

Gate: an unventilated charcoal operation can kill via CO, and correctly designed ventilation prevents it. Each avoidable lethal exposure has a prior available, actionable and scientifically honest warning path under §31.1; tests verify the path and never require a magical sensory cue. Atmospheric domains stay within budget without deleting matter from the active/regional ledger. C3.5’s P-gate is closed under §36.4a.

C4 — Industry: logistics, power, and control

Tasks for MVP: machines with typed ports; crusher, screen and jig; gravity chutes and mechanically driven belts; muscle/water power, shafts/gearing, mechanically driven bellows; bounded buffers; and period-appropriate governors, reliefs and shutoffs. Pipes, drones, steam/electric networks, electronic sensors and P/PID control are post-MVP at their §38 tiers.

Gate: a hands-off automated line converts ore and wood into copper for 30 minutes of continuous runtime. Measured throughput matches a prediction that includes stoichiometry, feed grade, conversion, separation, energy and transport limits, within a stated tolerance. There are no unintended leaks, unbounded buffers or frame-budget violations. Grain size demonstrably changes reduction rate. The blocked-output, interrupted-power, disconnection and restart cases in §32.5 also pass.

C5 — Knowledge, notebook, and achievements

Tasks: LabNotebook persisted model; observation quality gated by apparatus transparency; leads generated from real simulation events; §34.2 after-action accounts and provenance; the T0–T5 slice of the instrument ladder; simulation-verified achievements (§34.4).

Gate: a fresh player with no external documentation reaches copper using in-game affordances alone in a recorded playtest. They can answer “what just happened, why, and where did it go?” from the journal after every required success and failure. Every achievement is provably granted only by a conservation-intact simulation event with sufficient player evidence — asserted by test, and no achievement is reachable by a flag. Unsupported chemistry and inconclusive experiments remain distinguishable (§28.10); a journal cannot pass by explaining every failure using hidden truth.

C6 — Content, balance, and onboarding

Tasks: the full §36.2/§36.3 content set with sourced thermodynamic data and Docs/CHEMISTRY_SOURCES.md; pacing to §27.5’s hour targets; hazard signal tuning; audio/VFX for reactions, gases and failures; the first-hour experience.

Here “full” means the T0–T5 obtainable subset plus validation fixtures; post-MVP catalogue entries do not become playable merely because their data was authored.

Gate: §27.5’s hours 0–20 arc completes in playtest within a stated tolerance, with the copper moment landing as a summit. Every tester encounters an opportunity to recognise and prevent a hazard or recover from a survivable incident; no playtest is required to injure its player. Use the session, comprehension and recovery acceptance protocol in §36.9, not completion time alone.

C7 — Chemistry MVP release candidate

Tasks: performance to §36.7’s budgets; save round-trip with chemistryVersion; the full test matrix; a long soak; known issues; a clean Windows build.

Gate: §36.6.

36.5 Testing strategy

Extends §20. The chemistry core carries the project’s heaviest test burden because it is pure, headless and fast to test — there is no excuse for weak coverage.

Validation suite — reference values from Docs/CHEMISTRY_SOURCES.md with explicit tolerances. A failing validation test is a data or physics bug and blocks the milestone.
Conservation invariants — atoms, charge and first-law energy accounting asserted across every reaction, phase change, transfer, rupture, spill, atmospheric handoff and interrupted process.
Determinism and neutrality — the cross-runtime bit-identity and reaction-ID permutation tests from §28.8, run in CI-equivalent form.
Equilibrium properties — Le Chatelier behaviour asserted as a property test: raising a product’s partial pressure must shift extent in the correct direction for every reversible reaction.
Catalyst invariant — a catalyst changes rate and never K.
Electrochemical round-trip — ΔG = −nFE consistency for every applicable catalogue record at matching conditions/standard state.
Faraday accuracy — an ideal 100%-efficient fixture matches m = ItM/zF; non-ideal fixtures match η_I·ItM/zF and account for side products.
Hazard fairness — one test per avoidable lethal scenario asserting a truthful actionable warning path was available; invisible hazards are verified to remain invisible without an instrument.
Throughput prediction — measured output matches the supported process prediction, with the theoretical stoichiometric ceiling shown separately from actual conversion and flow limits (§27.3).
Science visibility — every shipped event type has an in-world channel, after-action account, epistemic labels, approximation/source links and accessibility-equivalent presentation. Tests trace each displayed claim back to the ScienceEvent and reject catalogue truth leaked as observation.
Kinetic validity — rate models reproduce source fixtures inside their envelope, are rejected or flagged outside it, reverse correctly when supported, and never depend materially on reaction ID.
Ownership and lifecycle — sample/split/merge, interrupted transfers, loaded deconstruction, pause, focus loss, chunk unload and crash recovery retain exactly one owner and one event commit.
Evidence boundaries — unsupported, undetectable and inconclusive outcomes remain distinct; unmeasured identity cannot leak through names, notifications, filters, achievements or exported pages.
Operations — full outputs, drive loss, restart, disposal and equipment failure preserve balances and expose an actionable diagnosis; failed engine transactions never masquerade as chemical failure.

36.6 Chemistry MVP Definition of Done

Supersedes §26 as the product gate. The game is at MVP when a player can, in a clean Windows build:

Start a seeded world with nothing, and discover fire, pyrolysis, calcination and reduction by experiment, guided only by in-game affordances.
Produce copper from a real ore body at a real grade, having beneficiated it, and feel it as an achievement earned rather than granted.
Find tin, reduce it, and alloy bronze as a genuine solution phase.
Recognise and prevent a potentially lethal chemical hazard, or survive and understand an incident, using truthful evidence. Safe design satisfies this outcome; injury is never a progression gate.
Automate the copper line end to end, deriving theoretical material demand from balanced equations and explaining the difference between that ceiling and actual throughput, yield and losses.
Read their own notebook back as a coherent record of what they discovered, with achievements marking every genuine chemical first.
Save, reload, and find every vessel, machine, network, notebook entry and achievement intact and bit-identical in continued simulation.
Perceive every required process and hazard through truthful in-world evidence, then open the journal and obtain a source-linked, uncertainty-labelled causal account of what changed, why it proceeded/stopped/failed, and where matter and energy went—without revealing unmeasured ground truth.

Plus, non-negotiably: conservation of mass and charge holds everywhere; the determinism contract (§28.8) passes; the validation suite passes against published data; performance meets §36.7; and Docs/CHEMISTRY_SOURCES.md cites every scientific constant/model in the shipped catalogue, while gameplay scale factors and approximations are separately and visibly labelled.

Nothing in §35 — glassware, acids, electrolysis, hydroponics, the stellarator, the voyage — blocks this definition.

Every P-gate under §36.4a is a condition of these eight outcomes. Each of the eight is phrased as something a player does, and none of them can be satisfied by a system that only a test can operate.

The interaction and lifecycle contracts in §§27.8–32.5 and the evidence/legibility contracts in §34.2 are conditions of these eight outcomes, not additional technology tiers. The playable acceptance protocol is §36.9. The MVP-ending review uses only the player’s own earned evidence (§27.8).

36.7 Performance budgets

Extends §21. Measured on the same reference hardware.

Budget	Limit
Simulation tick	20 Hz fixed, decoupled from render
Active vessels	≤ 256, with quiescence keeping typical counts far lower
Chemistry solver	≤ 1.0 ms per simulation tick, amortised ≤ 0.25 ms per rendered frame at 60 FPS
Active atmospheric domains	≤ 64, with conservative merge/handoff to the regional ledger
Belt items in flight	≤ 4096
Power network solve	≤ 0.2 ms per tick
Steady-state managed allocation	Zero in the chemistry core and the vessel tick
Science-event recording	Bounded ring/batch per tick; durable append is background-written without dropping accepted events
Save size for an MVP-complete world	Measured and regression-capped by category; initial target ≤ 64 MB compressed, never achieved by lossy science-history deletion

If a budget cannot be met, reduce simulated scope — fewer active vessels, coarser quiescence — rather than degrading validated physics or dropping its explanation trail. Visible, interrogable physics is the product.

36.8 Post-MVP roadmap

The road from §36.6 to §35, in dependency order. Each is a milestone in its own right and none is scheduled here.

C8 — Glassware. Soda-lime glass, glassworking with annealing, transparent vessels, the observation-quality upgrade to the notebook.
C9 — Aqueous chemistry. Solutions, pH with declared activity convention, precipitation, a validated concentration-appropriate activity model (Debye–Hückel only when dilute), leaching, crystallisation.
C10 — Acids. Mineral acid production and distillation, corrosion as a first-class material interaction, acid-resistant materials.
C11 — Electrochemistry. Galvanic cells, the voltmeter, batteries, and then electrolysis — the single largest capability unlock in the game (§28.6).
C12 — Electromagnetics. Magnets, induction, generators, motors, transformers. Electrorefining closes the purity→conductivity→better-generator spiral.
C13 — Reactive metals. Aluminium, sodium, magnesium; chlorine, pure O₂ and H₂; the metals fire cannot reach.
C14 — Hydroponics and closed loops. §33 in full, including flue-gas CO₂ enrichment.
C15 — Advanced materials. Steel, refractories, superconductors, cryogenics, high vacuum.
C16a — Unstable plasma. First confinement, disruptions, instabilities, impurity radiation, and the diagnostic instrumentation needed to see any of it (§35.2.1 phase one).
C16b — Stable plasma. Real-time feedback control of coil currents, fuelling and heating; sustained confinement; the declared Q_plasma target achieved rather than granted (§35.2.1 phase two).
C17 — The voyage. Spacecraft, closed-loop life support with no margin, and the final encounter under §35.3’s binding constraint.

36.9 Playable acceptance: decisions, comprehension, and recovery

Before expanding the content catalogue, run a formative test with at least five first-time players covering both little and substantial prior chemistry knowledge. Include separate keyboard/mouse and controller/accessibility checks. This is an issue-finding gate, not a statistical claim about the whole audience. Record observations with participants’ consent; no external telemetry is required.

Initial gates, to be revised only with a written rationale before the next test round:

At least four of five new players create fire, find its run entry and name a feasible next experiment within twenty minutes without facilitator instructions (§49.3 D3).
On an early success and a failed/inconclusive attempt, at least four of five can explain what changed, what evidence supports that, what remains unknown and one useful next action. Correctly stating uncertainty is success; guessing the hidden equation is not required.
A tester can pause safely, resume a deliberately interrupted twenty-to-thirty-minute session, recover their intention from the notebook and make progress without repeating completed work.
A player can diagnose a seeded blocked line, handle a retained sample and recover from one lost apparatus using only current-tier tools. Track material cost and recovery time against an agreed C6 scenario budget; no prerequisite may depend on the destroyed apparatus itself.
Record repeated actions without new decisions and intervals of compulsory idle waiting. A required idle interval longer than one minute needs a specific review: shorten the experimental charge, offer a meaningful observation/task, or remove the wait. Do not alter scientific constants to pass.
Relevant tasks remain completable with colour discrimination unavailable, sound muted and strong physiological screen effects disabled. Equivalent cues preserve the same knowledge limits.

Longer C6 tests then verify the complete T0–T5 arc and the player’s reason to continue building after their first copper. Use more than one valid seed, including low-grade and awkward-terrain fixtures; a hand-tuned opening alone does not validate procedural progression. Separate numerical bugs, unclear interaction, missing evidence and pacing problems in the report so balance changes do not hide errors.

37. Voxel Creation and Material Differentiation

Part I’s blocks are hand-authored ScriptableObjects with three textures and a boolean or two (BlockDefinition, BlockRenderClass, ToolType). That model is correct for fifteen blocks and collapses at four hundred. Part II needs blocks for every material the player can make — every alloy composition, every ceramic, every glass, every degree of purity — and hand-authoring that is neither possible nor desirable.

The answer: a block is a view onto a material, and a material is a view onto a composition. Almost nothing about a block is authored; almost everything is derived.

37.1 Blocks are manufactured, not crafted

Every placeable block above raw geology is the output of a real process with a real vessel, real conditions, and conserved mass. There is no recipe grid that turns eight cobblestone into a furnace.

Process	Input	Output block	Real mechanism
Casting	Melt above Tm, poured into a mould	Ingot, block, plate, pipe	Solidification
Forging	Hot solid + mechanical work	Wrought bar, sheet	Plastic deformation, work hardening
Sintering	Powder + heat below Tm	Porous solid, refractory	Diffusion bonding
Firing	Shaped clay + staged heat	Brick, tile, crucible	Dehydration, sintering and partial vitrification according to clay body/temperature
Setting	Binder + aggregate + water + time	Mortar, plaster, concrete	Carbonation / hydration
Vitrification	Melt + soda + lime, then anneal	Glass block, pane, tube	Amorphous solidification
Deposition	Electrolytic cell	Plated surface, foil	Faradaic reduction at a cathode

The player does not “unlock the bronze block”. They pour bronze into a mould, and the mould’s shape determines the form. Form is a property of the mould, not of a recipe, so one alloy yields ingots, plates, pipes, rods and blocks from the same melt.

37.2 The Material → Block derivation

Three layers, each generated from the one below:

Composition          {Cu: 0.88, Sn: 0.12}          — chemistry (§28.1)
     │
     ▼
Material             composition
                     + microstructure  (cast | wrought | annealed | quenched | sintered | fired | amorphous)
                     + porosity, grain size
                     + processing history
     │
     ▼
MaterialBlock        derived appearance, derived physics, derived render class

A MaterialBlockDefinition is generated, not authored, but chemical identity and voxel geometry use separate namespaces. BlockId identifies a bounded form/render family; a content-addressed MaterialRecord stores the exact quantised composition and processing state. Chunks use compact local material palettes that reference those records. Consequences:

Adding a new alloy costs zero content work — the block, its appearance, its physics and its item form all fall out.
BlockId remains a ushort; it is not asked to enumerate a continuum of alloy compositions. The number of form/render families, per-chunk palette entries and per-save MaterialRecords each have a tested bound and an explicit “cannot create another material” error path. No hash collision or palette overflow may alias one composition to another.
Stable IDs are non-negotiable (Part I’s rule). Catalogue IDs come from the release manifest. Player-created MaterialRecords use a canonical serialisation plus full content hash and collision check; multiplayer transmits the record/hash, never assumes two saves assigned the same local index.
Materials the player invents (an off-ratio alloy nobody designed) are first-class. An 83:17 bronze is a real material with real derived properties, not an error and not rounded to the nearest authored recipe.

37.3 Physical properties are sourced or derived, never arbitrary

This is the mechanical half of differentiation, and it is where §27.4’s honesty pillar earns real gameplay. No designer types “bronze hardness = 5”, but the game also does not pretend composition alone predicts every engineering property. Each value is a sourced measurement, a validated model, or an interpolation with a declared envelope and uncertainty.

Property	Derived from	Gameplay consequence
Density	Sourced phase data; validated mixture model where applicable	Carry weight (§30.4), buoyancy, jig separation
Solidus/liquidus	Sourced phase diagram, including eutectics	See below — this one matters enormously
Hardness / toughness	Measured composition + microstructure + work/heat history correlations	Mining speed, tool quality, wear, failure mode
Thermal conductivity / expansion	Sourced data plus bounded porosity/composition model	Refractory quality, kiln efficiency, thermal shock
Electrical conductivity	Sourced alloy/purity data; Matthiessen-type model only in its validated regime	Generator and wiring quality — see §37.3.1
Corrosion behaviour	Environment-specific sourced kinetics/potentials	Vessel wall lifetime (§29.2)
Optical properties	Measured spectral data plus labelled mixture approximation	Colour and reflectance (§37.4)

The phase diagram is a designed reward. Pure copper melts near 1358 K and pure tin near 505 K. Cu–Sn alloys have composition-dependent solidus/liquidus temperatures and eutectic regions, so a suitable bronze can begin melting below pure copper. Its hardness comes from alloy composition, microstructure and processing—not “because eutectic”. A player who maps both casting range and hardness has discovered two related but distinct truths.

37.3.1 Purity is the spine of the late game

Impurities scatter conduction electrons. A few tenths of a percent of iron in copper measurably drops its conductivity, and that single fact carries the entire electrical progression:

crude copper  →  crude generator  →  a little electricity
      ↑                                      │
      │                                      ▼
better generator  ←  purer copper  ←  electrorefining

This is a genuine bootstrap spiral, not a linear unlock: you need electricity to refine the copper that makes the generator that makes the electricity. The player breaks in with a poor generator built from smelted copper, uses its weak current to electrorefine a small batch, rewinds a better generator, and climbs. Each turn of §27.6’s loop is visible as a measurable conductivity number in the notebook.

37.4 Appearance is computed from chemistry

The visual half of differentiation. Four independent contributions, all derived, composited into the HDRP material:

1. Base albedo from measured optical data. Metals use sourced spectral reflectance where available; mixtures and alloys use a declared, validated interpolation rather than a claim of first-principles prediction. Mineral colour depends on oxidation state, crystal field, defects, grain size and impurities, so catalogue ranges—not one “exact” swatch—drive deterministic variation. Sources and model limits live in Docs/CHEMISTRY_SOURCES.md.

2. Roughness and metallic response from microstructure. Cast is rough, wrought is directional, polished is smooth, sintered is matte and porous. One Material yields visibly different blocks depending on how it was processed, which makes processing legible at a glance.

3. Corrosion as a surface layer that changes over time. Copper does not simply “get a patina texture”. It can form Cu₂O/CuO and, depending on moisture and atmospheric carbonate, sulfate or chloride, several green/blue corrosion products including basic copper carbonates. Environment and kinetics decide the layer; “patina equals malachite” is not hard-coded. The player can recover that matter, so the visual loop remains chemical without claiming one universal weathering path.

4. Thermal emission from a Planckian reference. Hot opaque solids trend along the blackbody locus, but real materials are grey/selective emitters and flames are not blocks. The implementation uses a documented Planck-spectrum-to-CIE-to-linear-sRGB approximation for chromaticity, with sourced or bounded emissivity affecting radiance and an HDRP exposure/display transform affecting appearance. It must never call screen brightness an exact pyrometer. Glow is a truthful coarse thermometer; §34.3’s thermocouple replaces estimation with a measurement and the journal records the uncertainty.

BlockRenderClass extends from Part I’s {Invisible, Opaque, Cutout, Emissive, Transparent} with Refractive for real glass (index of refraction from composition) and Fluid. Emissive becomes dynamic, driven by the temperature overlay in §37.5 rather than the static emissionIntensity float.

37.5 Mutable block state without dense storage

§28’s granularity decision (bounded reaction domains and reactive surfaces, not per-voxel bulk chemistry) still holds, but some blocks genuinely need mutable state: temperature near a furnace, corrosion progress, moisture, machine internals.

Storing that densely would be catastrophic — 16³ per chunk × the streaming radius. Instead:

The dense array stays exactly as it is: one BlockId per voxel, unchanged, with all of Part I’s meshing, streaming and save behaviour intact.
A sparse per-chunk BlockStateOverlay holds state only for voxels that have any, reusing the proven WorldEditOverlay pattern from §13.2. A voxel absent from the overlay is at ambient and uncorroded, which is the overwhelming majority.
Budgeted and bounded. Overlay entries per chunk are capped; exceeding the cap means the design is wrong, not that the cap should rise.
Slow tick. Corrosion and heat diffusion run at a fraction of the chemistry tick and iterate only the sparse set, never the dense volume. Both are deterministic under §28.8’s ordering rules.
Thermal/moisture-only overlay entries are evicted when they return to baseline. Persistent corrosion, deposits, contamination or material loss remain as sparse state or are baked into a stable material record; cooling may not erase chemical history.

Heat conduction into surrounding blocks is what makes furnace design real — insulate with a porous refractory and the heat stays in; build it out of dense stone and you heat the neighbourhood and burn your fuel for nothing.

37.6 Construction materials are apparatus materials

The single most important structural consequence of all this: the blocks you build with and the vessels you cook in are the same materials, judged by the same derived properties. There is no separate “building block” category.

A better furnace needs a better refractory. A better refractory needs better chemistry. Better chemistry needs a better furnace. That is §27.6’s loop expressed in walls.

wattle · thatch · rammed earth        ~600 K      shelter only
fired brick                           ~1200 K     the first real kiln
lime mortar + stone                   ~1300 K     sustained calcination
fireclay refractory                   ~1600 K     iron
silica · alumina refractory           ~2000 K     steel, glass tanks
magnesia · zirconia                   ~2500 K     specialty melts
graphite · tungsten                   >3000 K     plasma-facing (§35)

Structural properties matter identically: a pressure vessel needs real tensile strength, a blast-resistant wall needs real toughness, a cryogenic line needs a real thermal-expansion match, and a plasma chamber needs all of them at once.

37.7 Procedural texture generation

Extending §14.6’s procedural block-texture authoring, derived material blocks generate their textures rather than shipping them:

A base pattern per material class — crystalline, granular, fibrous, amorphous, cast, laminated — as a small deterministic procedural generator.
Tinted by §37.4’s computed albedo, so the colour is chemically correct by construction.
Perturbed by a hash of the MaterialId, so two similar alloys are visually distinguishable but a given material looks identical in every world.
Baked into the existing atlas at catalogue build time, not at runtime, so meshing and streaming budgets are untouched.

Hand-authored art always wins where it exists: the derived path is the fallback that makes a four-hundred-material game tractable, not a replacement for authored hero blocks.

37.8 Functional and multi-block voxels

Machines (§32.1) occupy voxels but are one logical entity: a footprint of voxels referencing a single machine record held in the sparse overlay. Breaking any voxel of a machine breaks the machine, returns its materials, and spills its vessel contents — because conservation is absolute, and a smelter destroyed mid-heat spills what was actually in it.

Belts, tubes and wires are voxel-placed with connection state derived from neighbours, meshed as Cutout, and carry real contents that a break will release — with all of §31.2’s consequences if that content was chlorine.

37.9 ToolType must generalise

Part I’s ToolType { None, Pickaxe } is far too narrow. It becomes a capability check against derived material properties rather than an enum comparison:

A block is mineable if the tool’s derived hardness exceeds the block’s, with speed from the ratio.
Tool wear is real: work done against a harder material removes material from the tool, and a tool can be re-forged rather than discarded.
The tool categories that remain (cutting, crushing, prying, boring) describe what motion is applied, and the material decides whether it works. A bronze chisel and a steel chisel are the same tool type and enormously different tools.

38. The Technology Tree

38.1 What this tree is, and what it is not

§34.1 states there is no tech tree, and that remains true of the user interface. There is no research screen, no node to purchase, no points, no unlock button. Nothing here is ever “bought”.

What follows is the dependency structure of physical reality — the map of what must exist before something else can. It is a design artifact and a content specification, not a menu. The player discovers it by doing chemistry; they never see it drawn.

The distinction is load-bearing:

A tech tree UI	This tree
Nodes are purchased with a currency	Nodes become possible when their preconditions physically exist
The tree is shown to the player	The player reconstructs it in their own notebook (§34.2)
Skipping ahead is impossible by rule	Skipping ahead is impossible by physics — you cannot melt copper in a clay pot
Progress is a percentage	Progress is a temperature, a voltage, a purity

38.2 Gating primitives

Every edge in the tree is gated by a declared diegetic constraint. There are no abstract currencies; adding a new constraint requires a plan review and reachability coverage rather than being forbidden by an arbitrary count.

Gate	Meaning	Raised by
Peak temperature	Highest sustainable T	Fuel quality, forced air, insulation, geometry
Atmosphere	Oxidising / reducing / inert / vacuum	Sealing, flux, purge gas, pumps
Vessel	Service temperature, chemical resistance, pressure rating	Material chain (§37.6)
Potential	Volts available	Generator, cell stack
Current	Amps available	Generator scale, conductor purity
Purity	Impurity fraction in feedstock	Beneficiation, refining, electrorefining
Access	Reach, extractability, transport and environmental survivability	Logistics, excavation, pressure protection, remote operation
Knowledge	Does the player know the reaction and its conditions?	Experiment, observation, the notebook

Mechanical power is a derived gate (it buys forced air, crushing, and electricity), and it is not listed separately.

38.3 The tree at a glance

T0  HAND ─────────────────────────────────────────────────────┐
     │ wood, stone, clay, sand, fibre, water                   │
     ▼                                                         │
T1  FIRE  ~900 K ──────────────► ash ──► POTASH ────┐          │
     │ charcoal (pyrolysis)                          │         │
     ▼                                               │         │
T2  CERAMIC  ~1050–1200 K                            │         │
     │ crucible, retort, brick, pipe                 │         │
     ▼                                               │         │
T3  LIME  ~1300 K ──► mortar ──► better kilns        │         │
     │ CaO, Ca(OH)2, flux, limewater test            │         │
     ▼                                               │         │
T4  COPPER  ~1350 K + forced air ◄───────────────────┼─────────┘
     │ malachite → CuO → Cu                          │       (bellows need
     ▼                                               │        no metal)
T5  BRONZE  composition-dependent casting range      │
     │ Cu + Sn.  TOOLS.                              │
     │                                               │
     ╞═══════════════ MVP CUT LINE (§36.6) ══════════╪═══════════════
     │                                               │
     ▼                                               ▼
T6  GLASS  ~1400 K ◄──────── soda ◄──── T8  ALKALI & SALTS
     │ transparent vessels, tubing, LENSES           ▲
     │                                               │
     ├──────────────► T9  ACIDS ────────────────────┘
     │                 │ H2SO4, HCl, HNO3
     ▼                 │
T7  IRON & STEEL       │        T10  OPTICS & INSTRUMENTS
     ~1500-1800 K      │              │ lens, microscope, thermocouple,
     │ needs refractory│              │ balance, barometer
     │                 │              │
     └────────┬────────┴──────────────┘
              ▼
T11 ELECTRICITY ──── magnet + wire + motion = INDUCTION
     │ generator, motor                      ▲
     ▼                                       │
T12 ELECTROCHEMISTRY                         │
     │ cells, batteries, ELECTROLYSIS        │
     ├── electrorefining ──► pure Cu ────────┘   ◄── BOOTSTRAP SPIRAL
     │
     ▼
T13 REACTIVE METALS   Al, Na, Mg, Cl2, pure O2/H2
     │
     ▼
T14 ADVANCED MATERIALS  alloy steel, refractories, Si, Ti
     │
     ▼
T15 CRYOGENICS & VACUUM  liquefaction, air separation, high vacuum
     │
     ▼
T16 SUPERCONDUCTORS  Nb-Ti, Nb3Sn ──► high-field magnets
     │
     ▼
T17 FUSION FEEDSTOCK  D2O/D + lithium blanket ◄── isotope separation
     │
     ▼
T18 PLASMA: UNSTABLE  first D-D confinement, loss events, diagnostics
     │
     ▼
T19 PLASMA: STABLE  coupled control, declared Q_plasma target
     │
     ▼
T20 SPACE  propulsion, closed-loop life support, the voyage

38.4 Tiers T0–T5: the MVP arc

Tier	Gate	Key process	Yields	Achievement
T0 Hand	—	Knapping, cordage, digging, wattle	Stone tools, shelter, clay, fibre	—
T1 Fire	~900 K, open	`C + O₂ → CO₂`; sealed pyrolysis of wood	Charcoal, tar, ash	Combustion, Pyrolysis
T1b Potash	Water leach	Ash + water → filtrate → evaporate	K₂CO₃ — the first alkali	—
T2 Ceramic	~1050–1200 K pit/clamp kiln, then upgrades	Clay shaping + staged firing	Crude crucible/retort first; better brick, pipe and tile after refiring	—
T3 Lime	~1300 K sustained	`CaCO₃ → CaO + CO₂`	Quicklime, mortar, flux, limewater test	Calcination
T4 Copper	~1350 K + forced air, reducing	Roast then reduce malachite	Copper, slag	Reduction, Isolation: Cu
T5 Bronze	Cu–Sn phase diagram + suitable furnace	`SnO₂ → Sn`; Cu–Sn solution	Bronze, cast tools	Alloy, Isolation: Sn

Notes that matter for implementation:

T1b potash is deliberately early and easy to miss. Leaching wood ash gives the player their first alkali long before they understand what an alkali is. It is a flux, a soap precursor, and a glass former, and finding it rewards curiosity about waste products.
T3’s limewater is the game’s first analytical test. Bubble an unknown gas through limewater; if it turns milky, it contained CO₂. This is the player’s first instrument and it costs nothing.
T2 gates everything but is reachable from T1. An earth-covered charcoal mound needs no fired vessel; its charcoal and an insulated pit/clamp kiln fire the first crude ceramic. That ceramic then improves the kiln. The bootstrap is a tested cycle, not an implied jump from a 900 K fire to a 1200 K vessel.
T4’s forced air is why bellows matter, and bellows require no metal — wood, leather and cordage from T0. The tree is careful never to require a metal to make the first metal.

38.5 Tiers T6–T10: glass, iron, acids, instruments

Tier	Gate	Key process	Yields	Achievement
T6 Glass	~1400 K + silica + soda + lime	Carbonate decomposition into a multicomponent silicate melt; blow/draw, anneal	Transparent vessels, tubing, condensers, lenses	Vitrification
T7 Iron	~1500 K bloomery, fireclay	`Fe₂O₃ + 3CO → 2Fe + 3CO₂`	Wrought iron	—
T7b Steel	Carburise + quench/temper	Controlled C content, heat treatment	Steel — tools, springs, pressure vessels	(first steel)
T8 Alkali	Varies	Natron → synthetic soda	Na₂CO₃ at scale, NaOH, soap	—
T9 Acids	Glass vessels	Vitriol roasting; `NaCl + H₂SO₄ → HCl`	H₂SO₄, HCl, HNO₃	Acid
T10 Instruments	Glass + dissimilar metals	Lens grinding; Seebeck effect	Microscope, telescope, thermocouple, barometer	—

The thermocouple is quietly the most important item in this band. Two dissimilar metals joined produce a voltage proportional to temperature difference — the Seebeck effect. It is the player’s first electrical instrument, built long before they understand electricity, and it converts §37.4’s glow-colour estimation into real measurement. It is also the first hint of pillar 2.

38.6 Tiers T11–T13: the electromagnetic turn

Tier	Gate	Key process	Yields	Achievement
T11 Electricity	Magnet + drawn wire + motion	Faraday induction	Generator, motor, transformer	Induction
T12 Electrochemistry	Potential > cell EMF	Galvanic cells; electrolysis; electrorefining	Batteries, pure metals, H₂/O₂, plating	Galvanic, Electrolysis, Faraday verified
T13 Reactive metals	Very high current	Hall–Héroult (Al in molten cryolite); Downs cell (Na); chlor-alkali	Al, Na, Mg, Cl₂, NaOH, pure O₂/H₂	Isolation: Al / Na / Mg / Cl

This is the hinge of the whole game. Before T12, chemistry is something the player coaxes with heat and carbon. After it, chemistry is something they command with electrons — and directions that are non-spontaneous at the operating conditions proceed because the player supplies the required electrical work and losses (§28.6).

Aluminium deserves special mention as a difficulty statement: it is one of the most abundant elements in the crust and was, historically, more valuable than gold, because no amount of fire will reduce Al₂O₃. It is the perfect demonstration that the tree is gated by capability, not by rarity.

38.7 Tiers T14–T20: the road to plasma

Tier	Gate	Key process	Yields
T14 Advanced materials	Alloying metals + purity	Alloy/stainless steel; alumina, zirconia, magnesia refractories; zone-refined Si; Kroll-process Ti	Materials that survive the next tier
T15 Cryogenics & vacuum	Compression + Joule–Thomson	Linde cycle; fractional distillation of air; mechanical → diffusion → turbo pumps	Liquid N₂/O₂/He, high vacuum, leak detection
T16 Superconductors	Nb, Ti + cryogenics	Nb–Ti and Nb₃Sn wire, winding, quench protection	High-field magnets
T17 Fusion feedstock	Large-scale staged isotope separation	D₂O/deuterium enrichment; lithium blanket inventory	Deuterium plus the material needed to breed tritium
T18 Plasma: unstable	Vacuum + magnets + power + D fuel	First D–D confinement; poor gain, neutrons and a small tritium seed; loss-of-confinement/radiative events	Plasma diagnostics and the bootstrap neutron/tritium inventory
T19 Plasma: stable	Geometry + coupled plant control + bred T	D–T fuelling; density/heating/impurity/exhaust and magnet-protection control	Declared `Q_plasma` target (Fusion gain)
T20 Space	All of the above	Propulsion, structures, closed-loop life support (§33.3)	The voyage (§35.3)

T17 reuses the electrochemical principle learned at T12, but isotope enrichment is a staged cascade with a small separation factor, large energy cost and material inventory—not “the same cell, simply run longer”. The old Faradaic and mass-balance skills transfer while the apparatus honestly scales.

38.7.1 T14b — Petrochemistry and polymers

A branch off T14 that runs parallel to the metals track and is required for the endgame. It is the answer to “what is everything actually made of once metal is not enough”.

Stage	Process	Yields
Extraction	Seeps, bitumen, drilling; natural gas from salt domes (§39.2)	Crude oil, bitumen, methane
Fractionation	Continuous fractional distillation — the column is a scaled-up §29.4 condenser	Gas, naphtha, kerosene, gas oil, residue
Cracking	Thermal, then catalytic with zeolites and Pt (T14)	Ethylene, propylene, aromatics
Monomers	Halogenation, oxidation	Ethylene, vinyl chloride (needs Cl₂, T13), tetrafluoroethylene (needs F, from fluorite via HF)
Polymerisation	Addition and condensation, with initiators and catalysts	Polyethylene, PVC, PTFE, butyl and neoprene rubbers, polyamides

The dependency that makes this tier feel earned: PVC needs chlorine and PTFE needs fluorine, and both come from the electrochemical tier. You cannot make the good plastics until you can command electrons. Fluorine chemistry in particular — hydrofluoric acid is the substance that attacks glass, so it is the one reagent the player’s entire glassware chain cannot hold, and handling it demands polymer vessels the player must first learn to make. That circularity is real and it is the point.

What polymers buy, beyond §46.8’s suit: electrical insulation far better than fibre and tar (feeding back into T11’s generators), chemically inert pipework and seals, gaskets that let high vacuum work (T15), containers that acid cannot eat, and lightweight structure.

38.8 Bootstrap spirals — where the tree is not a ladder

These are the most interesting edges in the graph, and each is a deliberate design feature. In every case the player must break in with a crude version and iterate upward.

1. Copper purity ↔ electricity (T4 ↔ T12) — the defining spiral of the late game.

smelted copper (impure, poor conductor)
   → crude generator, weak current
      → electrorefine a small batch
         → pure copper
            → better windings → stronger generator → refine faster ⟳

2. Refractory ↔ temperature (T2/T3 ↔ T7/T14) — you cannot fire a better refractory than your current furnace can reach, so every furnace generation is built by the one before it.

3. Glass ↔ acid (T6 ↔ T9) — acids need glass to be held, better glass (borosilicate) needs boron compounds that acid processing provides. Break in with crude acid in glazed ceramic, accepting contamination and vessel loss.

4. Soda ↔ glass (T8 ↔ T6) — synthetic soda at scale needs sulfuric acid, which needs glass, which needs soda. Break in with natural natron and wood-ash potash (T1b), which is exactly why T1b is placed so early.

5. Optics → plasma diagnostics (T10 → T18) — the lens ground for a magnifying glass becomes the spectroscope that reads impurity lines out of a dying plasma. An hour-thirty tool solving an hour-hundred problem.

6. Vacuum ↔ cryogenics (T15 internal) — good vacuum needs cryopumping, cryogenics needs vacuum insulation. Break in with mechanical pumps and accept poor vacuum.

7. Tritium ↔ fusion neutrons (T17↔T19) — a D–T blanket needs neutrons to breed tritium, but a D–T run needs tritium. Break in with difficult, low-gain D–D plasma using enriched deuterium; retain the small tritium/neutron output, breed against lithium, then transition to D–T. No precursor cache or quest flag creates the first fuel inventory.

38.9 Cross-cutting tracks

Three tracks run alongside the material tiers rather than inside them.

Power — muscle → water/wind → steam (T7 pressure vessels) → electrical (T11) → fusion (T19). Each tier of chemistry demands more power, and power is what buys forced air, crushing and current.

Automation (§32) — hand → gravity chutes → mechanical belts → powered belts and pipes → sensors and threshold control → PID → drones and full process control → real-time plasma feedback (T19). The automation track and the plasma track converge: stabilising a plasma is the final control problem, and it is the same skill as tuning a kiln loop, at a thousand times the speed.

Biology (§33) — foraging → agriculture → hydroponics → CO₂-enriched closed loops → life support (T20). Enters as food, ends as the thing keeping the player alive in vacuum.

38.10 Implementation notes

The tree is data, not code. It is expressed as the reaction and material catalogues plus their gating conditions; there is no TechTree class, no unlock graph, and no node state to persist. What the player has done lives in the notebook (§34.2) and their achievements (§34.4).
Reachability is a build-time test. A tooling pass walks the catalogue from a bare-hands starting state and asserts every tier is reachable. It proves physical reachability only — temperature, atmosphere, vessel, potential, current, purity, access and available materials — and treats knowledge as always available, because a build-time test cannot model what a player has worked out. The test therefore answers “is this possible”, not “is this discoverable”; discoverability is covered by C5’s playtest gate instead. A node that becomes physically unreachable after a content change fails the build. This is the chemistry equivalent of Part I’s generation-validation tests, and it lives in the Voxel Workshop as a Tech Reachability report.
No node may be reachable by a flag. Same rule as achievements: the only way a capability becomes available is that its physical preconditions exist in the world.
Content order follows §36.4/§36.8: T0–T5 is milestones C0–C7 (MVP), T6–T13 is C8–C13, T14–T20 is C14–C17. The tree is specified in full here so that no earlier milestone quietly forecloses a later one — §35.4’s scope-honesty rule applied to content.

39. Exotic Biomes and Chemical Geography

39.1 The binding principle

A biome is defined by the chemistry it makes possible. Scenery is a consequence, never the reason. Every biome in this list exists because it is the only convenient source of some reagent, some element, or some physical condition, and travelling to it is therefore a chemical decision.

This changes what exploration is. In Part I you explored to see terrain. Here you explore because your glass is stuck at soda-lime and you need borax, and borax is in a playa four kilometres east.

Four rules govern the set:

MVP chemistry is never stranded by generation. Every T0–T5 requirement has a guaranteed reachable source plus a worse fallback where chemically plausible. Later elements have redundant world sources and seed-level reachability guarantees, but they need not exist beside the spawn; access and logistics are legitimate physical gates (§38.2). The generator never invents an implausible local ore merely to avoid travel.
Biomes carry their own hazards, and the hazard is chemically honest: CO₂ pools in karst sinkholes because CO₂ really does pool in karst sinkholes.
All generation stays under §8.1’s determinism contract. Biome placement, deposit grade and impurity profile are pure functions of seed and coordinate.
Exotic biomes are almost always far away and yield the most interesting substances — the distance-band rule of §39.8, which is the game’s second progression axis.

39.2 Evaporite and alkali biomes

Biome	Yields	Why it matters
Salt flat / playa	Halite (NaCl), trona / natron (Na₂CO₃), gypsum (CaSO₄·2H₂O), borax	Breaks the soda↔glass bootstrap (§38.8 spiral 4) outright, and borax is the road to borosilicate — the glass that survives acid and thermal shock
Soda lake	Natron, trona, extremophile biomass	Alkali at scale; alkaline hot springs
Salt dome / evaporite	Sylvite (KCl), potash, anhydrite, trapped hydrocarbons	Potassium for hydroponics (§33.2); the first natural gas
Guano cave / seabird colony	Phosphates, nitrates	Phosphorus for hydroponics and, with acid, for match chemistry; nitrate for HNO₃

39.3 Volcanic and geothermal biomes

Biome	Yields	Why it matters
Fumarole field / solfatara	Native sulfur, sulfates, alunite, free geothermal heat	Sulfur without roasting pyrite → the shortest road to H₂SO₄. Geothermal heat is a genuine tedium-reducer: a process heat source that costs no fuel. Hazards: H₂S, SO₂
Ash plain / tephra	Obsidian, pozzolan, zeolites, pumice	Obsidian is natural glass — sharp tools at T0 and a look at vitrification long before you can make it. Pozzolan is natural cement, which builds a real furnace far earlier than lime alone
Kimberlite pipe	Diamond (industrial), garnet, olivine	Abrasives and cutting — the tooling tier that makes precision possible
Hydrothermal vent field (submarine)	Massive polymetallic sulfides: chalcopyrite, sphalerite (Zn), galena (Pb), barite	Zinc → brass and, critically, the first galvanic cells. Lead → chamber process, radiation shielding

39.4 Weathering and sedimentary biomes

Biome	Yields	Why it matters
Laterite (tropical)	Bauxite (Al₂O₃), nickel laterite, goethite	The aluminium ore. T13 is unreachable in quantity without it
Banded iron formation	Massive hematite, magnetite	Iron at industrial scale; magnetite is also your first magnet
Karst / limestone caves	Pure CaCO₃, speleothems, niter (saltpetre)	Clean limestone for lime and glass; nitrate for HNO₃. Hazard: CO₂ pooling in sinkholes, invisible and lethal
Bog / peatland	Bog iron, peat fuel, tannins, sphagnum	Smeltable iron reachable with bloomery temperatures; acidic water; anaerobic preservation (§41). Hazard: methane
Placer river / alluvial	Native gold, cassiterite, monazite (Th, rare earths), zircon, ilmenite (Ti)	Density separation with a pan or jig — the earliest possible beneficiation, and a rare-earth source with no chemistry required to find
Petrified forest / chert beds	Chalcedony, agate, flint	Flint for fire and knapping; very pure silica for optical glass

39.5 Rare-element and hazardous biomes

Biome	Yields	Why it matters
Pegmatite outcrop	Spodumene (Li), beryl (Be), columbite–tantalite (Nb, Ta), lepidolite, cassiterite, rare earths	The single most important late-game biome. Nb and Ta are the superconductor path (T16); Li is batteries; Be is neutron work. Coarse crystals mean high grade with simple hand-sorting
Serpentinite / ophiolite	Chromite (Cr), magnesite (Mg), olivine, nickel, natural H₂ seeps	Chromium → stainless steel. Serpentinisation genuinely produces hydrogen, so this is free H₂ before electrolysis. Hazard: asbestiform minerals — a real, slow, lung hazard
Roll-front sandstone (uranium)	Pitchblende / uraninite, vanadium, selenium	Radioactivity as a hazard class of its own; radiogenic heat; the nuclear path
Impact crater	Meteoric nickel–iron, shocked quartz, coesite, impact glass	Free metallic iron with no smelting at all. Historically exactly how iron working began, and the game’s cleanest natural shortcut
Glacial / periglacial	Erratics from distant geology, cryoconite, ice cores	Erratics are a sampling mechanic — boulders carried from far away, letting a player encounter a mineral whose home biome they have not found. A hint, not a supply
Mercury retort deposit (cinnabar)	HgS → Hg	Liquid metal: amalgams, barometers, thermometers. A serious, cumulative, permanent toxic hazard, and treated with the seriousness it deserves

39.6 Atmospheric and extreme-condition zones

Not biomes in the terrain sense, but chemically distinct environments that gate processes:

High altitude — lower ambient pressure genuinely shifts boiling points and gas-phase equilibria. Distillation behaves differently on a mountain, and that is simulated, not flavour.
Deep mine — elevated temperature with depth, poor ventilation, gas accumulation. Where §31.2’s gas model bites hardest.
Underwater — pressure, no combustion, and the vent fields of §39.3.
Polar cold — free refrigeration and condensation. A cold biome makes early gas liquefaction and fractional crystallisation dramatically easier, which is a real, earned shortcut into T15.

39.7 Native metals — the deliberate on-ramp

Some metals occur natively and require no chemistry at all, only recognition and mechanical work. This is historically exactly right and it is the kindest possible tutorial:

Native metal	Where	What it teaches
Native copper	Basalt traps, oxidised zones	Cold-hammering, annealing, work hardening — metal behaviour before smelting
Native gold	Placers, quartz veins	Density separation; a non-reactive reference metal
Native silver	Oxidised veins	Conductivity, tarnish, and later the best conductor you have
Meteoric iron	Impact craters	Iron working before iron smelting
Native sulfur	Fumaroles	A pure element you can simply pick up

Native copper is the intended first metal experience: the player hammers a nugget into a blade, learns that it work-hardens and cracks, learns that heating restores it, and only then has a reason to care where copper comes from. The smelting chain in §38.4 is what makes copper plentiful, not what makes it available.

39.8 Distance is the reward curve

Exotic biomes are almost always far away, and they yield the most interesting substances. This is a binding generation rule and it gives the game a second progression axis — spatial — running alongside the capability axis of §38.

It works because distance is an honest access gate. Nothing is locked by UI; it is simply a long way off, and getting there requires preparation the player must engineer. That is §38.2’s access constraint expressed spatially — food, water, fuel, transport, and eventually breathable air.

Distance bands

Band	Range	Contains	Serves
0 — Home	Immediate	Wood, clay, sand, stone, limestone, water, native metals	T0–T3. Everything needed to start, within walking distance
1 — Near	Short walk	Common ores: malachite, cassiterite, bog iron, coal	T4–T7. The MVP arc is comfortably reachable on foot
2 — Regional	A journey	Evaporites, sulfur, salt, good limestone, clay beds	T8–T10. Wants a cart and a return trip
3 — Remote	An expedition	Pegmatite, laterite, serpentinite, banded iron, kimberlite	T11–T14. Wants rail, power, and an outpost
4 — Extreme	A campaign	Rare-earth pegmatite cores, uranium roll fronts, impact craters, deep vents, polar and high-altitude sites	T15+. Wants vehicles, supply lines, and PPE

Verticality and hostility count as distance. A deep mine, a high peak, an underwater vent field and a fumarole basin are all “far” in the only sense that matters — effort and preparation — even when they are close on the map. This lets the generator place a genuinely exotic site nearby without cheapening it, provided reaching it safely is real work.

The rule that keeps it fair

For the T0–T5 MVP, distance gates quality and convenience, never basic completion:

Soda from wood ash at home, or trona from a distant playa at ten times the yield.
Iron from a nearby bog at low grade, or a banded iron formation that never runs out.
Copper from a small oxidised lens next door, or a proper deposit two valleys over.

A player can complete the MVP near home, slowly and at poor yield. The post-MVP tree deliberately requires expeditions where geology does; the fairness requirement is that every valid seed provides a reachable route and signals where to search, not that every element exists locally.

Transport is the enabling tier

Because distance is the gate, transport is one of the game’s real progressions, and it earns its place in the tech tree:

foot            → band 0–1
cart, packbeast → band 2
rail (T7 iron)  → band 3, and the first time hauling stops being the bottleneck
powered vehicle → band 3–4
flight (T20)    → band 4 and beyond

Each step visibly extends practical reach, which makes building a railway feel like what it actually was historically: the thing that made industry possible at all. Establishing a remote outpost with its own logistic network (§42.2) and connecting it back to the main base is late-game content in its own right.

Why this matters for pacing

It solves the mid-game problem cleanly. Once local chemistry is exhausted, the player is not stuck and not waiting — they are underequipped for where they need to go next, and the fix is to build better transport and better supplies. Exploration stops being scenery and becomes a resourcing decision, and the most interesting substances in the game are the reward for solving it.

39.9 Finite resources, recovery, and meaningful exploration

Reachability must prove usable quantities and routes, not just that a substance exists somewhere in a seed. For every campaign seed, validate reachable T0–T5 feedstock, fuel, water, construction and waste capacity using an explicit starter scenario: first apparatus, several small failed experiments, one replacement apparatus and first successful production. Publish those quantities with the content profile; tuning a deposit changes this proof. A resource behind an impassable approach, or requiring the very tool it enables, does not satisfy it.

Critical deposits and basic access routes are validated at world creation using bounded deterministic generation. If they fail, select a deterministic valid spawn or reject the campaign profile before play with a useful message; never secretly add ore after the player runs out. Validate recovery from loss of the initial workshop and access to a second source, without guaranteeing recovery from every possible deliberate destruction of the world. Native metals and precursor finds remain optional.

Deposits have finite recorded inventories. “Never runs out” elsewhere in the plan means large relative to the tested playthrough, not an infinite extraction source. Renewable biomass or water exchange requires an explicit regeneration/boundary model and its ledger. MVP may use abundant finite resources where those models are deferred, but must budget them for the intended arc. Already mined terrain does not refill when a chunk unloads or the game reloads.

The first failed batch should normally cost a small sample; routine experiments must not demand another long ore-hauling trip. Prospecting leaves useful field notes—location, appearance, sampled grade and access route—even without a discovery. Return journeys should benefit from signs, markers, stockpiles and later transport. The map records surveyed routes and sampled claims, not exact unseen deposit boundaries. Exploration is valuable through better feed, safer sites and new options rather than compulsory blind digging.

Waste needs an MVP destination before a production loop ships: slag/tailings storage and supported recovery or construction uses where validated; liquids/gases through their named reservoirs. Full waste capacity is a production constraint (§32.5), not an auto-delete rule. The player can relocate or contain material without a hidden morality score. Detailed ecosystem recovery and broad waste-to-product chains remain post-MVP unless required by a tested starter route.

40. The Extended Element Roster

40.1 Scope and staging

The full roster is roughly 71 elements plus selected isotope records, staged so that the catalogue grows with the milestones and no milestone carries data it cannot yet validate (§36.1’s catalogue-integrity rules apply throughout). Every element ships with §28.1’s separate element record and cited sources; thermodynamic phase data belongs to substances containing that element, not to an abstract element entry.

40.2 Stage 1 — MVP (14 elements)

H · C · N · O · Na · Mg · Al · Si · S · K · Ca · Fe · Cu · Sn

Enough for combustion, pyrolysis, lime, silicates, copper and bronze. Al and Mg appear here only as oxides in gangue — present in the world, unreachable by fire, and quietly foreshadowing T13.

40.3 Stage 2 — glass, iron, acids (adds 16)

Cl · P · Mn · Zn · Pb · Ag · Ti · Cr · Ni · B · F · Ba · Sr · Li · As · Sb

Element	Enters as	Unlocks
Cl	Halite	HCl, chlorides, later chlor-alkali
P	Apatite, guano	Hydroponic nutrient; phosphoric acid. White phosphorus is a hazard
Zn	Sphalerite	Brass; the first galvanic couple with copper
Pb	Galena	Lead-chamber sulfuric acid; shielding; low-melting alloys
Ag	Native, argentite	The best electrical conductor there is — a purity reference
B	Borax	Borosilicate glass; neutron absorption later
Cr / Ni / Mn	Chromite, laterite, pyrolusite	Alloy and stainless steels
Ti	Ilmenite, rutile	Kroll process — strong for its mass and corrosion-resistant in many environments, not universally corrosion-proof
Li	Spodumene	Batteries; low-density alloys
As / Sb	Sulfosalts	Historical alloy hardeners, and genuinely lethal. Handled with §31’s full hazard machinery

40.4 Stage 3 — electricity and reactive metals (adds 14)

He · Ne · Ar · Co · Mo · W · Nd · Y · La · Ce · Se · Te · Br · I

Element	Why it exists in this game
Ar	Inert atmosphere. Welding and melting reactive metals is impossible without it
He	Cryogenics and high-sensitivity helium tracer leak detection, one of several practical leak-test methods
Nd	Neodymium permanent magnets. A step-change in generator and motor power density
W	Highest melting point of any metal — filaments, electrodes, plasma-facing surfaces
Mo / Co	Superalloys, high-temperature strength
Y / La / Ce	Rare earths from monazite; catalysts, phosphors, high-temperature superconductors
Se / Te	Semiconductors, photocells — light becomes electricity
Br / I	Halogen chemistry; iodine as an early analytical reagent

40.5 Stage 4 — advanced materials and nuclear (adds 27 elements + D/T isotope records)

Be · Sc · V · Ga · Ge · Rb · Zr · Nb · Ru · Rh · Pd · Cd · In · Cs · Hf · Ta · Re · Os · Ir · Pt · Au · Hg · Tl · Bi · Ra · Th · U plus D · T

Element	Why it exists
Nb / Ta	Nb–Ti and Nb₃Sn superconductors (T16). The pegmatite biome exists for these
Zr / Hf	Zirconia refractories; nuclear cladding. Hf is the neutron absorber Zr must be purified of
Pt / Pd / Rh	Catalysts — the contact process for H₂SO₄, and catalysis generally
Ge / Ga / In	Semiconductors and, with As, compound semiconductors
Be	Neutron reflector; beryllium bronze; toxic in a way that demands respect
U / Th	Fission, radiogenic heat, and the game’s radiation hazard class
D (²H)	Fusion fuel, from heavy-water enrichment (T17)
T (³H)	Bred from lithium under neutron flux — which is why Li appears back in stage 2
Hg / Tl / Cd	Genuinely dangerous, genuinely useful. Included precisely because handling them safely is content

40.6 Isotopes

Isotopes are modelled only where they matter, and they matter in exactly three places:

H / D / T — separation is real (electrolytic enrichment), and fusion depends on it.
U-235 / U-238 — fission and enrichment.
Li-6 / Li-7 — tritium breeding.

Everywhere else, an element is its natural isotopic mixture with an averaged atomic weight. Adding isotopic bookkeeping to the other sixty-odd elements would cost a great deal and change nothing the player can act on.

40.7 Element data integrity

Every element, substance and phase record entering the catalogue is subject to the §36.5 rules. Element records require sourced atomic/isotopic data. Thermodynamic phase records require sourced ΔfH°, S° and heat-capacity data with a validity range and citation in Docs/CHEMISTRY_SOURCES.md. Catalogue integrity fails on missing required data, an unbalanced equation, or a validity range that does not cover its use.

No element, isotope or substance phase ships with invented scientific data. If required data cannot be sourced or defensibly modelled inside a declared envelope, that content does not enter the catalogue.

41. Wild Terrain and Exposed Geology

41.1 Why the landscape must get wilder

Part I’s terrain is a heightmap with caves — correct for a sandbox, wrong for this game. A chemistry game needs verticality and exposure, because the player’s central question is what is this made of, and where do I find more of it? A rolling heightmap answers that question only by digging. A thousand-metre canyon wall answers it for free.

This section extends and supersedes §8.5’s density-world evolution with Part II’s requirements.

41.2 From heightmap to 3D density field

The generator moves from “height at (x, z)” to “solidity at (x, y, z)”, which is what makes everything below possible:

Base 3D fractal noise (Perlin/simplex, several octaves) defining a density field; solid where density exceeds a threshold that varies with depth.
Domain warping — perturb the sample coordinates with another noise field before evaluating. This is the single highest-value technique available: it breaks up the characteristic “noise grid” look and produces organic, folded, geologically plausible forms for very little cost.
Ridged multifractal for mountain spines and sharp ridgelines rather than rounded lumps.
A vertical gradient biasing solidity with depth, so the field naturally produces ground below and air above without a heightmap.

What this buys, none of which a heightmap can express: overhangs, arches, natural bridges, sea stacks, floating masses, undercut cliffs, hoodoos, spires, and caves that are part of the same field as the surface rather than carved out of it afterwards.

41.3 Erosion and structure

Noise alone reads as noise. Two cheap post-passes make it read as landscape:

Hydraulic erosion — simulated water flow carving valleys, depositing sediment in basins, and producing dendritic drainage. Deposition is where the placer biome (§39.4) comes from, so erosion is not cosmetic: it decides where the gold is.
Thermal erosion / talus — material above the angle of repose slides, producing scree slopes at cliff bases and softening otherwise impossible geometry.

Both must remain deterministic and order-independent under §8.1 — they run as fixed-iteration passes over a fixed domain, never as an unbounded simulation whose result depends on how long it ran.

41.4 Verticality and scale

A much taller world. Deep enough that mines are genuine expeditions, mountains are genuine climbs, and the depth-banded resources of §30.2 have room to band.
Massive cave systems as a first-class feature: phreatic tubes, vertical shafts, large chambers, sumps. Caves are where the game’s most dangerous gas behaviour lives (§31.2), and where karst chemistry (§39.4) happens.
Canyons and gorges cutting deep enough to expose many strata at once.

41.5 Exposure is the point — geology you can read

This is the section’s payoff and the reason wild terrain is a chemistry feature rather than an art feature. Because §30.1 gives every block a real composition and the world generates in real strata, any vertical cut is a free geological cross-section.

A canyon wall, a sea cliff, a sinkhole rim or a riverbank shows the player the layer sequence directly. With a trained eye — or an assay (§30.3) — they can read what is below without digging.
Prospecting becomes a landscape skill. You learn that the green staining appears where a particular bed meets a particular contact, and then you look for that contact elsewhere.
Erratics from the glacial biome (§39.5) and float in stream beds are clues pointing uphill to a source, which is exactly how real prospecting works.
Ore bodies should intersect the surface sometimes and not others, so gossans and oxidised caps are visible surface expressions of something worth following down.

Wild terrain therefore reduces tedium as well as adding drama: the alternative to reading a cliff face is digging exploratory shafts, and digging exploratory shafts is the least interesting thing in the game.

41.6 Constraints

Determinism, negative coordinates, seam-freedom and generation-order independence are unchanged (§8.1). A 3D field is easier to keep seam-free than a heightmap plus carving passes.
Streaming and meshing budgets from §10 and §21 are unchanged. If verticality costs more than the budget allows, reduce vertical streaming radius — never the determinism, never the exposure.
Overhangs and floating masses must not break the player-safety rules in §10.4.

42. Logistic Networks

42.1 Staging

Drones and network logistics arrive at T11+ (electricity) and not before. They need motors, batteries and current. Everything before that is belts, chutes, pipes and gravity, and the contrast is deliberate: the transition from physically routing every material to declaring what you want where is one of the game’s great relief moments, and it must be earned.

This section extends §32.2’s transport with the full network model.

42.2 The hangar

A hangar is the network node. It projects a coverage radius, and its overlapping radii define a connected logistic network exactly as one would expect.

Charges and stores drones; drones must return to recharge, so radius and traffic are real constraints.
Draws real power from §32.4’s network, and a network under heavy logistic load is a visible electrical load.
Networks are separate unless their coverage overlaps, so a remote outpost is genuinely a separate problem until connected.

42.3 The five container types

Directly modelled on the Factorio pattern, because it is the correct solution to this problem and players already understand it:

Container	Behaviour	Typical use
Passive Provider	Offers contents when something requests them. Never pushes	Default output of a production line
Active Provider	Pushes contents into the network immediately	By-products and waste that must not accumulate — slag, spent liquor, off-spec batches
Storage	General sink; drones deposit here when there is nowhere else	Overflow, deconstruction returns
Buffer	Requests and provides	Forward staging near a consumer, so drones do not cross the base for every kilogram
Requester	Requests specified contents be delivered	Machine feed, workshop supply

42.4 Requests are compositional, not countable

This is where the model departs from its inspiration, and it departs because §30.4 made it necessary. Matter here is mass with composition, so a request is a specification:

Requester:  copper          ≥ 99.9 % purity      keep 500 kg
Requester:  malachite ore   ≥ 12 %  grade        keep 2 t
Requester:  charcoal        ≤ 5 %   ash          keep 800 kg
Buffer:     bronze          88–90 % Cu           keep 200 kg

Consequences that make this better than a count:

Purity is a first-class logistic property. The electrorefinery’s output and the smelter’s output are both “copper” and are not interchangeable — §37.3.1’s spiral becomes visible in the network.
Grade routing is automatic. High-grade ore goes straight to the roaster; low-grade is requested by the beneficiation line. The network sorts by quality, which is exactly the real problem.
Off-spec output has somewhere to go — an Active Provider pushes it to reprocessing rather than jamming the line, and nothing is ever deleted, because conservation is absolute.

42.5 The network inventory

The always-available answer to “how much of what do I have?” — the specific tedium the player asked to be rid of:

Totals across the whole network, live, by substance and by quality band.
Set-and-forget targets. Declare “always keep 500 kg of ≥99.9 % copper” once and the network maintains it; the dashboard shows current against target at a glance.
Production and consumption rates per substance, so a deficit is visible as a trend before it is a stall — and the rate can be checked against the stoichiometric prediction (§27.3), turning the dashboard into a diagnostic instrument.
Deficit and surplus surfacing. What is falling behind, what is backing up, and — because the engine knows the balanced equations — which upstream step is the bottleneck.

42.6 Drones and hazardous work

The strongest reason to build a drone network is not convenience, it is §31.5: drones work where the player cannot breathe. Servicing a chlorine cell, tapping a furnace, or recovering material from an area with an uncontrolled gas release are all jobs for a machine. Remote operation is the mature answer to hazard, and the logistic network is how it is delivered.

Drones remain deliberately power-hungry and throughput-poor relative to belts (§32.2). They are the answer to awkward, distant and dangerous, never the answer to bulk.

43. Art Direction and Visual Identity

43.1 The deliberate split

The game has two visual languages, and the tension between them is the point:

	The world	What you build
Language	Pixel art — chunky, readable, Minecraft-lineage	Futurist industrial — Satisfactory-lineage
Feels	Ancient, geological, indifferent	Purposeful, engineered, deliberate
Texel density	Low (32²/face), point-filtered	Higher, with panel detail and greebling
Silhouette	Voxel-honest, blocky	Machined forms, conduits, frames, housings

The world is rock. It was here before you and does not care. Everything sharp-edged, glowing and intentional in the frame is something you made. That contrast is the whole story of the game told visually, and it means a screenshot of a mature base reads instantly: primitive planet, advanced industry, one person’s work in between.

43.2 Pixel art with modern lighting

Low-resolution textures and HDRP are not in conflict — the combination is the look:

Point (nearest-neighbour) filtering. No bilinear smearing. Texels stay crisp and square.
Low texel density on world blocks. The project’s existing 64² procedural block textures should drop toward 32² for natural materials so the pixel grid is legible at play distance.
Full PBR regardless. Albedo, metallic, roughness and normal maps all at the same low resolution. Pixel-art albedo with real metallic response is exactly why a copper block will look like copper and not like an orange square.
HDRP does the heavy lifting. Physically informed shadows, GI, exposure, and — critically — emission and bloom. §37.4’s Planckian thermal glow is legible against flat pixel albedo, because the crisp texel grid makes the bloom bleed read as heat rather than as blur.
Mipmapping stays disciplined. §15 and §21 already forbid shimmer; low-res point-filtered textures make aliasing more likely at distance, so mip generation and anisotropy must be tuned and the fixed-seed visual baselines (§20.4) must specifically include distant terrain.

43.3 The futurism gradient

Constructs are not uniformly futuristic — the futurism escalates with the tech tier, and that escalation is one of the clearest ways the player sees their own progress:

Tier	Construct language
T1–T3 fire, ceramic, lime	Earthen, hand-built, irregular. Barely “constructs” at all
T4–T5 copper, bronze	First deliberate engineering: cast fittings, purposeful joints, visible craft
T6–T7 glass, iron	Frames, vessels, plumbing. It starts to look like a plant
T9–T11 acids, electricity	Panels, gauges, conduits, insulated runs, the first indicator lights
T12–T14 electrochemistry, materials	Clean housings, modular units, emissive readouts, real machine design
T16–T19 superconductors, plasma	Sealed, luminous, cryogenic, humming. Unmistakably beyond

A base built across the whole tree therefore shows its own stratigraphy: the crude lime kiln still standing next to the electrolysis hall, because the player never had reason to tear it down.

43.4 Material honesty — the reconciliation

The form language is futuristic; the material is whatever you actually made it from. This is the rule that keeps §43.3’s gradient from contradicting §37.4’s chemically-derived appearance.

An electrolysis cell built in the bronze era is a sleek, purposeful, obviously-engineered shape — rendered in bronze, glass and wood, with the source-backed approximate colour for its Cu:Sn ratio and processing state. The same cell built later in stainless steel looks like the same design in a better material.

So the player sees their progress twice over: in the sophistication of the forms they can build, and in the quality of the materials they can build them from. Neither is faked, and a machine never displays a material the player did not actually supply.

43.5 Emissive language — light that means something

Every glowing thing in the frame carries information. Nothing glows decoratively:

Blackbody glow is temperature (§37.4). Learning to read furnace colour is a real skill the game teaches by simply being correct.
Indicator lights are sensor state (§32.3). A green light is a satisfied setpoint; amber is drift; red is an interlock tripped. A player scanning their plant is reading actual telemetry.
Process light is chemistry — flame colour from the metal ions actually present (the flame test of §34.3, happening continuously and for free), plasma glow from the species actually excited.
Emergency signalling is loud, unambiguous and, per §31.1, always earlier than the danger.

43.6 Constraints

The atlas, meshing and streaming budgets of Part I are unchanged. Derived material textures (§37.7) bake at catalogue build time and must not grow the atlas beyond budget; a material-count cap is a build-time assertion.
Machines are meshes, not voxel art, and follow §21’s renderer and draw-call budgets. Multi-block constructs must batch.
All third-party art remains under §14’s ledger and licence rules without exception.

44. Precursor Finds and Friction Reduction

44.1 The binding principle

Rare finds may shortcut search and inherited knowledge, never physical law or permanent capability.

§34.1 names four gates: knowledge, capability, materials and access. A find may hand the player knowledge — this reaction exists, here are its reported conditions — because another person could genuinely have written that down. A physical find may also contain a finite, conserved sample or component. That can demonstrate or temporarily supply a capability, but it does not teach manufacture, create an unlock, or make the reachability graph depend on salvage.

This keeps every pillar intact. You can be told how to reduce alumina; you still cannot do it until you can supply the current.

44.2 What a find can and cannot do

A find may	A find may never
Reveal a reaction and its conditions	Perform a reaction
Reveal a deposit’s location or composition	Create a deposit
Supply a working temperature profile	Raise your peak temperature
Provide a real catalyst sample (lowers Ea)	Change an equilibrium constant
Provide one finite component you cannot yet manufacture	Make that component reproducible or provide infinite/unanalysable material
Skip searching	Skip doing

The last row is the design test. A find may replace searching or provide a finite experiment; it may not replace the repeatable process, infrastructure and understanding needed to reproduce the result.

44.3 Find types

Find	Effect	Rarity
Blueprint plate	Adds a provenance-labelled external claim about reagents, conditions and apparatus. It becomes confirmed only after the player reproduces it	Rare
Assay slate	Adds somebody else’s recorded composition of the deposit, clearly distinct from a current measurement	Uncommon
Process card	Supplies a reported temperature/pressure profile for a programmed heater (§32.3); the player must validate and retune it for their apparatus	Uncommon
Catalyst sample	A genuine catalyst — a pinch of platinum sponge, a zeolite. Lowers Ea for a real reaction. Consumable, poisonable, and analysable	Rare
Survey map	Marks deposits across a region. Turns hours of prospecting into a journey	Uncommon
Salvaged component	A working part beyond current manufacture — a vacuum pump, a lens, a coil, a pressure vessel	Rare
Alloy sample	A piece of an alloy the player cannot yet make. Its value is analysis: learn the composition, then reproduce it when able	Rare
Seed stock	Improved crop strains for hydroponics (§33.2)	Uncommon
Instrument	An intact precursor instrument — usually broken, usually repairable, always more precise than the player’s own	Very rare

44.4 Reverse engineering

The core interaction with any physical find, and it scales with the player’s own progress:

Analysis quality is gated by instruments (§34.3). A bare-hands player sees “a dense grey metal”. With a balance, a density. With a flame test, its principal metal. With a spectroscope, its full composition including trace elements.
A find is therefore worth revisiting. The alloy sample from hour ten yields its real composition at hour sixty, when the player finally has the instrument to read it. Finds do not expire.
Salvaged components can be sacrificed to analysis. Destroying an irreplaceable precursor vacuum pump to learn what its seals are made of is a genuine decision with no correct answer.
Reverse engineering produces notebook knowledge, which is a §34.1 gate-one shortcut and nothing more.

44.5 The precursors — restraint

The futurism stays subtle. Someone climbed this ladder before and is gone. That is the entire statement, and it is delivered in materials rather than in text:

No dialogue, no lore dumps, no logs explaining the setting. The evidence is physical: an alloy that should not exist yet, a ceramic that survived far too long, wire of a purity the player will not match for eighty hours.
They are absent, not hostile, not helpful. No faction, no benevolent AI, no guiding voice.
What they left is industrial, not ceremonial — the wreckage of a working civilisation, not a temple.
The player’s realisation should arrive chemically: “I finally have the spectroscope, and this wire is 99.999 % copper — I cannot make copper that pure.” That sentence is worth more than any codex.
The connection to §35’s voyage is left deliberately loose here, and any narrative payoff belongs to that far-goal milestone. It must never become a correctness dependency of anything earlier (§35.4).

44.6 Rarity and placement

Roughly one significant find per two to four hours of active exploration. Rare enough to be remembered; common enough to be worth exploring for.
Placement is deterministic under §8.1 — a seed places the same finds in the same locations forever.
Biome-appropriate. Anaerobic bogs (§39.4) preserve organics that nothing else would; deep karst and impact craters shelter durable artefacts; salt domes preserve almost anything.
Never on the critical path. A build-time test asserts the §38.10 reachability proof holds with every find removed. If any tier becomes unreachable without finds, the content is wrong.

44.7 Friction reduction the player earns

Finds are the rare, lucky form of relief. These are the reliable forms, and they matter more:

Process templates. Players may draft a procedure or save any run for comparison and repetition. A successful run earns a provenance-linked “verified under these conditions” label. A template is a proposed operation, never an unlock or a guarantee for different feed, scale or apparatus.
Batch and queue. Repeat a procedure n times without re-specifying it, within the available apparatus/control capability. Retain actual inputs and outcomes for each run; no success flag is required to attempt an unproven schedule.
The logistic network (§42) — declaring what you want where instead of routing every kilogram.
Natural shortcuts that are historically true: native copper and meteoric iron (§39.7), free geothermal process heat (§39.3), polar cold for condensation (§39.6), natural pozzolan cement, and serpentinite hydrogen seeps (§39.5). Every one of these is a real thing that really helped, and finding one should feel like being handed a gift by the planet.
Readable geology (§41.5) — the alternative to reading a cliff face is digging blind shafts, which is the least interesting activity in the game.

The design target: the player should never be bored, but should often be busy. Tedium is repeated work with no new information. Effort is work that teaches or builds. Cut the first without ever touching the second.

45. Physiological Effects and Screen Shaders

45.1 The screen reports physiology; instruments identify hazards

Chemical exposure is rendered as full-screen post-processing, but the governing rule is that the screen represents physiological impairment, not chemical identification. Real poisonings overlap, and several dangerous exposures have no unique early symptom. The player learns that something is wrong from their body; they identify the cause from process context, sampling and instruments.

This is one presentation channel in §31.1’s fairness rule, never a substitute for detection. Before the player owns a gas detector, symptoms may be a late and nonspecific warning. The journal says so plainly and never trains the player to rely on a cinematic tell in real life.

Binding constraints inherited from Part I and Part II:

Presentation never invents state (§2.7). Every effect is driven by an authoritative vitals value the simulation actually produced. The shader may interpolate; it may never imply an exposure that is not real, nor hide one that is.
No per-frame allocation, pooled materials, and a private HDRP Volume owned by the effect runtime rather than edits to a shared profile — mirroring the established HdrpStormPresentationRuntime / RayTracedAmbientOcclusionRuntime pattern.
Effects degrade legibility gradually and never hide the information needed to survive. Critical HUD and gauge readability is the last thing to go, always.

45.2 Effect classes

Class	Cause	Visual signature	Why it reads this way
Hypoxia	CO, CO₂, N₂ displacement, low O₂	Peripheral darkening closing to tunnel vision, desaturation, grey-out, pulse-synced brightness throb	Real hypoxic vision loss: periphery fails first, colour before form
Carbon monoxide	Incomplete combustion	Nonspecific headache/confusion, weakness and hypoxic visual loss; no unique colour signature	CO is colourless and odourless, and symptoms cannot reliably identify it
Solvent / neurotoxic	Vapours, mercury, lead, tetraethyl compounds	Lens warping, chromatic aberration, slow FOV drift, breathing distortion, delayed and imprecise camera response	Impairment portrayed as danger: you misread gauges and mis-set valves
Tremor	Chronic mercury, manganese	Fine involuntary camera shake, worsening with dose	Real, cumulative, and largely permanent
Irritant	Cl₂, SO₂, NH₃, acid mist	Streaming blur, involuntary blinks, wet-lens distortion, forced squint	Eyes and airway react before you decide to
Thermal burn	Radiant heat, contact, molten spill	Heat-shimmer refraction, red vignette pulses, bloom bleed at the edges	Standing too close to an open furnace should feel like it
Chemical burn	Strong acid or alkali on skin	Sharp localised vignette, desaturation crawling inward	Alkali burns are slow, deep and worse than they first look
Pain	Any acute injury	Hard vignette pulses synced to the injury event, brief desaturation, screen jolt	Punctuation, not a state
Radiation	U/Th ores, later neutron flux	No exposure-linked screen shader; only later illness where modelled	Humans do not sense ionising radiation. A dosimeter/instrument is the warning

45.3 Legibility without false diagnosis

Urgency and impairment classes must be distinguishable enough to play, but two causes may share the same symptoms when reality does. A scripted pass tests legibility of syndrome classes and confirms that colour alone is never required. It must not be possible to identify chlorine versus CO from a magic shader; a detector, observation of the process, or sample does that work.

The progression is deliberate:

Early — symptoms mean “leave, ventilate, and investigate”, not “I know the molecule”.
Middle — a limewater bubbler, a canary equivalent, a flame that changes colour. Corroboration.
Late — real gas analysis and dosimetry. The screen effect becomes confirmation of something you already knew, because you were monitoring.

That arc is §27.6’s loop applied to your own body: trial and error, then instrumentation, then control.

45.4 Insidiousness is the design, and it is fair

The genuinely frightening hazards are the ones with weak early signals — CO, CO₂ and radiation. They are allowed to be subtle, and they are kept fair by four rules:

A truthful warning path is available before an avoidable lethal dose: process evidence, instrumentation/alarm, or a deliberately survivable first exposure—not necessarily a bodily cue.
Instrument and process signals are learnable and reproducible; nonspecific symptoms remain nonspecific.
The first serious exposure is survivable by design, placed early (the charcoal retort, §27.5) and paired with a hazard achievement (§34.4) that names what happened and why.
Recovery is possible if the player acts on the signal, and consequences of ignoring it scale rather than jumping straight to death.

45.5 Accessibility is mandatory

Non-negotiable, and treated as a correctness requirement rather than an option:

No strobing or flashing above documented photosensitive-safety thresholds. Pulse effects are slow and shallow by default.
A master intensity slider plus per-class sliders, including zero.
A “reduce screen effects” mode that replaces the full-screen treatment with clear, distinct iconography and a text readout — conveying exactly the same physiological information, but never naming a toxin unless an instrument identified it. Reducing the effect must never reduce what the player can know, or the setting becomes a difficulty penalty.
Motion-sensitivity options covering warping, camera shake and FOV drift independently.
Colour-blind-safe distinctness. §45.3’s requirement holds without relying on hue alone: each class differs in form, motion or structure as well as colour.
Effects never take control of the camera away from the player entirely, and never black the screen out for longer than a documented maximum.

45.6 Implementation notes

A PhysiologicalStateRuntime reads authoritative vitals (BloodOxygen, per-toxin ToxicLoad, CoreTemperature, injury events, dose) and drives a private HDRP Volume plus a small set of custom post-process passes.
Effect intensity is a pure function of vitals, so it is deterministic and reproducible for tests and for the fixed-seed visual baselines of §20.4.
Passes are individually toggleable and individually budgeted; the whole system has a frame-cost cap in §36.7’s terms and must degrade by disabling classes in a documented order rather than by overrunning.
Audio moves with vision — muffling and heartbeat under hypoxia, coughing under irritants, tinnitus after a blast — under §17.1’s existing rules.

46. Protective Equipment and Emergency Response

46.1 Armour protects against chemistry, not swords

There is no combat armour in this game, because there is no combat. What Part I would have called armour is personal protective equipment, and it is rated against the things that actually threaten the player: gas, splash, heat, cold, radiation and vacuum.

This follows directly from §27.4 pillar 5. The monster is the plant, so the armour is a respirator.

Every piece of PPE is manufactured from materials the player produces, so the PPE ladder is another face of the material ladder (§37.6): leather, then rubber, then synthetic polymer, then reflective metal, then a sealed suit.

46.2 What each class actually protects against

PPE	Protects against	Does not protect against
Damp cloth	Coarse dust, some particulates	Any gas. Any vapour. Anything that matters
Charcoal respirator	Organic vapours, some acid gases	CO. CO₂. Oxygen deficiency. See §46.3
Cartridge respirator	The specific gas class its cartridge is rated for	Every other class, and oxygen deficiency
Supplied-air / SCBA	Everything airborne, including CO and low O₂	Splash, heat, absorption through skin
Goggles	Splash to the eyes	Vapour that attacks the eyes; the rest of the face
Face shield	Splash, spatter, minor spray	Gas; impact from a rupture
Gloves (by material)	The chemicals that material resists	Chemicals that permeate it — see breakthrough, §46.3
Apron / chemical suit	Splash and immersion to the covered area	Anything reaching the gaps
Heat-reflective gear	Radiant heat at the furnace	Contact with molten metal; heat stress
Cryogenic gloves	Cold burn from liquefied gas	Oxygen enrichment; asphyxiation from boil-off
Lead apron	Some ionising radiation	Neutrons. Ingestion. Inhalation
Pressure suit	Vacuum, at the cost of dexterity and heat rejection	Puncture

46.3 The wrong PPE is more dangerous than none

This is the section’s most important mechanic, and it is real. Protective equipment creates confidence, and confidence in the wrong equipment is what kills people.

Three properties are simulated for every piece:

Protection factor against a specific hazard class. Not a single “defence” number. A charcoal respirator has an excellent factor against solvent vapour and a factor of zero against carbon monoxide, because activated charcoal does not adsorb CO. A player who dons a respirator and walks into their own retort shed dies wearing it, and the game must let that happen — with the signal of §45.2 still present, still readable, still ignored.
Breakthrough time. Gloves do not block chemicals indefinitely; the chemical permeates the material at a rate. A glove rated for an acid still fails after enough exposure, and a glove that has been through a splash is compromised even if it looks intact.
Service life and saturation. Filters load up and stop working. A cartridge has a finite capacity for the gas it adsorbs, and a saturated cartridge passes everything through. Tracking cartridge life is real maintenance, and forgetting it is a real, teachable death.

The player learns to match protection to hazard, which requires knowing what the hazard is — tying PPE selection directly back to §34’s knowledge progression. Guessing at PPE is guessing at chemistry.

46.4 Emergency response: rinse

Water is the single most important piece of safety equipment in the game.

For most splash exposures the correct response is immediate, copious, prolonged rinsing, and the mechanic is built around the three things that actually determine the outcome:

Immediacy. Seconds matter. The difference between rinsing at three seconds and thirty is the difference between irritation and a permanent injury.
Volume. Dilution is the mechanism. A cup of water spreads the chemical; a flood removes it.
Duration. The real standard is fifteen minutes and the game holds to it. A player who rinses for ten seconds and walks away has not finished, and the injury continues to develop.

Contaminated clothing must also be removed — fabric holds the chemical against the skin and keeps the reaction running. A player who rinses without stripping the soaked apron is rinsing the wrong side.

This turns plumbing into safety infrastructure. A water supply near the process is not convenience, it is survival, and running a pipe to the acid bench is one of the most valuable construction decisions in the game.

46.5 When water is wrong

The counter-cases are what make this content rather than a button, and every one is real. Getting this wrong is the trial-and-error lesson with the highest stakes in the game.

Substance	Water does	Correct response
Alkali metals (Na, K, Li)	Reacts violently — H₂ plus heat, i.e. fire or explosion	Smother with dry sand or mineral oil. Never water
Quicklime (CaO), dry	Slakes exothermically against the skin, burning worse	Brush off dry first, then rinse copiously
Concentrated H₂SO₄, in a vessel	Violently exothermic; spatters acid	Never add water to the acid. Acid into water, always
Molten metal or hot slag	Flashes to steam — a steam explosion throwing molten metal	Dry sand; let it cool
Burning magnesium	Reacts, releasing H₂ and feeding the fire	Class D dry powder or dry sand
White phosphorus	Water is correct — it prevents re-ignition	Immerse and keep wet

Note the last row deliberately: the rule is not “water is dangerous”, it is “know what you are dealing with.” Some of the exceptions have exceptions, and the only defence is knowledge — which is precisely §34.1’s first gate, and precisely the game’s subject.

Concentrated sulfuric acid carries a genuine double lesson the game should teach separately: for acid on skin, copious water is still correct because dilution wins; for acid in a container, adding water is a spattering hazard. Same substance, opposite answers, and the difference is context.

46.6 Emergency infrastructure

Buildable, and it should feel like real relief to have built it:

Safety shower — a plumbed overhead deluge. High flow, long duration, hands-free.
Eyewash station — sustained low-pressure flow, because holding your own eyelids open under a deluge is not possible.
Quench tank — for hot work.
Dry-agent bin — sand or powder, sited where water is the wrong answer.
Spill containment — bunds and trays that keep a spill from spreading and let it be recovered rather than lost. Conservation is absolute, so a contained spill is material you can still use.
Ventilation and fume hood — dealt with in §31.5, and the first line of defence for everything airborne.
Emergency shutdown — an interlock (§32.3) that safes a process from a distance.

A well-run plant is legible at a glance by its safety infrastructure, and that legibility is a real aesthetic reward for competence.

46.7 The PPE progression

Tier	Available	Real limitation
T0–T3	Damp cloth, leather apron and gloves, wooden shield	Almost nothing. Ventilation and distance are your real protection
T4–T6	Fitted leather, glass goggles, charcoal respirator	Goggles are a genuine step change. The respirator is dangerously reassuring
T7–T9	Rubber gloves and apron, acid-resistant gear, cartridge respirators	Breakthrough and saturation become real maintenance
T11–T13	Supplied-air systems, powered ventilation, full chemical suits	Heat stress becomes the limiting factor — a sealed suit does not breathe
T14–T16	Cryogenic gear, radiation shielding, remote manipulation	Some hazards can no longer be worn against, only handled remotely (§42.6)
T18–T20	Pressure suits, active thermal control, closed life support	The suit is the habitat (§33.3)

The arc is deliberate: early on you protect yourself by not being there — ventilation, distance, patience. PPE is always the last line of defence, never the first, and the game should reward engineering the hazard away over dressing up to face it.

46.8 The endpoint: lead apron, then the encapsulating suit

The lead apron is narrow, situational protection against some photon energies and geometries; it is not the default answer to uranium ore. Dust control, containment, distance, handling time and dosimetry matter first, because an apron does nothing about inhaled/ingested contamination, gas, splash, heat or neutrons. It is the clearest example in the game of §46.3’s lesson: protection must be matched to a measured exposure route.

The true endpoint is a fully encapsulating, supplied-air, maximum-security hazmat suit, and it is deliberately gated behind petrochemistry (§38.7.1), because that is what it is actually made of:

Layer	Material	Why
Outer shell	Selected compatible laminate (often fluoropolymer-based)	No universal suit material exists; choose from sourced permeation/compatibility data for the actual reagent set
Seams and seals	Butyl or neoprene, heat-welded	A suit is only as good as its seams — permeation happens at the joins first
Visor	Laminated polymer over borosilicate	Chemical and impact resistance with real optical clarity
Gloves	Multi-layer laminate, taped to the sleeve	Breakthrough time is the limiting number (§46.3)
Atmosphere	Positive-pressure supplied air	Positive pressure means leaks blow out, not in — the whole design principle
Thermal	Active cooling loop	A sealed suit does not breathe; heat stress becomes the limiting factor, not the chemical

So the ultimate armour in the game is a plastic bag with a fan in it, and it is the correct answer. Getting there requires oil, cracking, chlorine, fluorine, electrochemistry and polymer processing — the player must command electrons and hydrocarbons before they can safely stand next to what they have built.

Even then it is not invulnerability. The suit has a finite air supply, a finite breakthrough time, a real heat-rejection limit and a puncture risk, and §46.7’s arc still holds: engineering the hazard away beats dressing up to face it, at every tier including the last.

47. Fumes, Steam, Smoke, and Plumes

47.1 The central rule: visibility is not a toxicity meter

Many lethal gases are colourless, carbon monoxide is odourless, and several visible aerosols are also dangerous. Therefore neither “clear means safe” nor “visible means harmless” is allowed. The visual system shows only what would physically scatter or emit light; toxicity comes from composition, concentration and dose:

Emission	Appearance	Danger
Smoke	Thick, grey to black, sooty	Irritant, and a warning sign of incomplete combustion
Steam (wet)	White, billowing, dissipates on mixing	Scalding, but obvious
Metal fume	Fine, coloured by the metal, hangs low	Metal fume fever; cumulative
Acid mist	Faint haze, wet-looking	Corrosive
Dust	Depends on the mineral	Silicosis; explosive (§31.4)
NO₂	Red-brown	Severely toxic — the rare visible killer
Cl₂	Yellow-green	Severely toxic — the other one
Br₂ / I₂ vapour	Red-brown / violet	Toxic, corrosive
CO	Nothing at all	The most lethal thing in the game
CO₂	Nothing at all	Asphyxiant, pools in low ground
H₂	Nothing at all	Explosive across a very wide range
Superheated steam	Nothing at all	Burns you through air that looks clear

The player may fear a black plume and relax in clear air over a retort. The lesson is not to reverse that instinct; it is to stop using visibility as a gas detector.

47.2 Smoke is a diagnostic instrument

Smoke colour and density are a direct readout of combustion quality, and reading it is a real skill that smiths and firefighters genuinely have:

Thick black smoke — fuel-rich, oxygen-starved combustion with soot and unburnt hydrocarbons. It is evidence that conditions can favour carbon monoxide, not a quantitative CO measurement; clean- looking combustion can still produce CO.
Thin blue-grey — organics volatilising; pyrolysis proceeding.
White — usually steam, i.e. wet fuel wasting your heat on evaporation.
Clean, near-invisible shimmer — complete combustion, and the thing you are aiming for.

So “my fire is smoking badly” and “my fire is making CO” are the same observation, available from hour one with no instrument at all. Tuning the bellows until the smoke clears is the player’s first control loop, long before §32.3 gives them a PID.

47.3 The steam distinction

Worth modelling precisely because it is counter-intuitive and dangerous:

Steam proper is an invisible gas. The white plume is condensed droplets — water that has already left the gas phase on mixing with cooler air.
The visible plume therefore begins a short distance from the outlet, not at it, and the clear gap between the nozzle and the white is the hottest, most dangerous part.
Superheated steam is invisible entirely, and a leak from a high-pressure line is a jet that can cut and burn through air that looks clear. Detection is remote: isolate the line, inspect pressure loss, or use a sacrificial probe from cover. The game never instructs the player to search with a hand or body.

47.4 Plume behaviour

Plumes are the visual presentation of §31.2’s GasCloud entities and are never independent of them — the particles show what the simulation actually holds, and a cloud with no visible species produces no particles while remaining fully lethal.

Buoyancy from temperature and mean molar mass. Hot plumes rise; cold dense gas sinks and creeps.
Wind advection on the existing WindField (§17.4), so weather genuinely decides where your exhaust goes.
Stack effect. A tall chimney disperses at height; a short one delivers your own off-gas back into your yard. Chimney height is real engineering with a real consequence, and it is one of the most satisfying cheap fixes in the game.
Inversion layers. Under the right weather — cold, still, high pressure — plumes stop rising and spread at a ceiling, pooling over the base. A morning inversion turning a well-behaved plant into a hazard is a genuine, deterministic, weather-driven event, and it uses the seasonal system already built in §17.4.
Terrain interaction. Valleys and pits trap; ridges disperse. Siting a smelter is a decision.

47.5 Deposition — the plant gets dirty, and that is information

Some plume matter deposits locally; some reacts, remains airborne, or leaves the active region for §28.9’s persistent regional atmosphere ledger. Conservation requires accounting, not the false claim that every emission settles nearby:

Soot blackens surfaces downwind of incomplete combustion, recorded in the sparse BlockStateOverlay (§37.5) rather than as dense state.
Sulfur compounds stain and, with moisture, acidify — attacking metal structures over time.
Metal fume settles as fine dust that can be recovered: flue dust from a zinc-bearing charge is genuinely worth reprocessing, so a filtered stack pays for itself in material as well as in health.
Corrosion accelerates downwind of an acid process, which the player will notice as their own structures failing near the plant they built.

Deposition patterns are a free, always-on visualisation of where the player’s emissions actually go. A base with a clean white lime kiln and a black-stained smelter yard tells its own story, and the stain is the map of what the player has been breathing.

47.6 Implementation notes

Rendered with VFX Graph, pooled, budgeted under §36.7 and §21, with a hard cap on simultaneous plume systems and graceful degradation by distance and count.
Particle density, colour and opacity are derived from the GasCloud’s actual composition, temperature and concentration — a pure function of simulation state, so it is deterministic and reproducible in the fixed-seed visual baselines (§20.4).
Colourless species emit no particles. This is a correctness requirement, not an optimisation, and it is asserted by test: rendering a visible plume for pure CO would be the presentation layer lying about an authoritative state, which §2.7 forbids.
Flame colour comes from the metal ions actually present in the charge (§43.5) — the flame test of §34.3 running continuously and for free.
Heat shimmer over hot outlets uses the same refraction pass as §45.2’s thermal effects.

48. Stored Atmosphere and Life Support

48.1 The final exam is arithmetic

Everything in §35’s voyage reduces to one question: can you carry enough air, and if not, can you make it as fast as you use it?

The player must do a real mass balance. The values below are a nominal one-person planning case, not universal physiology; actual consumption depends on activity, body size, diet, temperature and mission assumptions, all recorded in the journal:

Quantity	Per person per day
Oxygen consumed	~0.84 kg
CO₂ produced	~1.0 kg
Potable water intake (not total hygiene/process water)	~2.5 L

At that nominal load, thirty days is roughly 25 kg of consumed oxygen and 30 kg of produced CO₂ that must go somewhere, before crew count, stored cabin gas, leakage, reserves or contingency. Every kilogram must be lifted, so provisioning is a genuine optimisation whose answer depends on declared mission assumptions — exactly the kind of problem the whole game has been training the player to solve.

This section is where §33.3’s promise is collected: the life-support loop is not a new system, it is the hydroponics and gas handling the player already knows, with the margin removed.

48.2 Making oxygen

Two routes, both already on the tech tree:

Water electrolysis (T12). Reuses the electrochemical principles and components learned in metal refining; the isotope-enrichment cascade is related but not literally the same cell. Water electrolysis produces O₂ at the anode and H₂ at the cathode. Faraday’s law gives theoretical yield; current efficiency and side products give realised yield (§28.6). Power-hungry, and the H₂ must be handled rather than vented into an enclosed volume.
Cryogenic air separation (T15). Liquefy air and fractionally distil it — O₂ boils at 90 K, N₂ at 77 K. Yields O₂, N₂ and argon together, and argon is what makes welding reactive metals possible (§40.4). Efficient at scale, useless in space where there is no air to separate.

48.3 Storing oxygen

Method	Density	Cost
High-pressure gas	Poor	Heavy vessels; a rupture is §31.4’s mechanism at full force
Liquid oxygen (LOX)	Excellent	Cryogenic (90 K) — needs T15, insulation, and constant boil-off management
Chemical (chlorate candle)	Good, one-shot	Emergency reserve only; not renewable

Oxygen is not a safe gas, and the game must be emphatic about this. It is a powerful oxidiser and storing it introduces hazards the player has not met before:

Everything burns in enriched oxygen — steel wool, aluminium, cloth, things that will not burn in air at all. A fire in an oxygen-enriched compartment is not a fire the player has seen.
LOX plus any organic is an explosive. Grease on a fitting, oil in a valve, an asphalt spill under a LOX line — all genuine, all catastrophic.
Adiabatic compression ignition — opening a valve too fast on an oxygen system can ignite the system itself.
Oxygen toxicity at elevated partial pressure. More is not better; the partial pressure must be controlled, not maximised.

48.4 Removing carbon dioxide

Producing oxygen is only half of it. CO₂ accumulates, and §31.2 already taught the player what that does — this time in a volume they cannot leave.

Lithium hydroxide — 2 LiOH + CO₂ → Li₂CO₃ + H₂O. Reliable, simple, one-shot, and consumable mass that scales linearly with mission duration. Lithium from the pegmatite biome (§39.5), which is why it was placed in the roster so early.
Regenerable amine or zeolite beds — adsorb CO₂, then bake it out to vacuum and reuse. Higher fixed mass, near-zero consumable mass. Needs power and control (§32.3).
Plants — §33.2’s hydroponics, consuming the CO₂ and producing both O₂ and food.

48.5 The crossover — why the loop must close

This is the design payoff, and it is a real engineering trade the player computes themselves:

Open loop   :  mass  =  small fixed  +  large per-day
Closed loop :  mass  =  large fixed  +  small per-day

Below the crossover duration, carrying everything is lighter and simpler. Above it, the closed loop wins decisively — and §35’s voyage is deliberately placed beyond the crossover, so that “just carry more tanks” is not a viable answer and the player is forced to close the loop they have spent the whole game learning to build.

The hydroponics stack the player built at hour fifty to enrich their kilns’ flue gas is, structurally, the thing that keeps them alive at hour a hundred. Nothing new is introduced. An old system is asked to work without margin.

48.6 Failure modes

All of them are §31 hazards the player already understands, in a volume with no exit:

Scrubber saturation — CO₂ climbs, and §45.2’s hypoxia and CO₂ signatures appear with nowhere to walk to.
Leak — pressure falls. Helium leak detection (§40.4) is how you find it before it finds you.
Fire in enriched atmosphere — fast, hot, and consuming the oxygen that is keeping you alive.
Power loss — electrolysis stops, scrubbers stop, thermal control stops. Everything is downstream of power, which is why §32.4’s network reliability finally matters absolutely.
Thermal runaway — a sealed volume has no ambient to dump heat into; radiators are the only path, and they are the same heat-transfer problem as §29.1’s vessel walls.

48.7 Why this is the right ending

The voyage is not a new genre bolted onto a chemistry game. It is the chemistry game with the tolerances tightened to zero:

Ventilation, learned at the charcoal retort in hour one, becomes atmosphere management.
Gas storage and pressure ratings, learned at the first sealed vessel, become the oxygen system.
Control loops, learned tuning a kiln, become life support.
Mass balance, the game’s first and most absolute rule, becomes the mission plan.

The player does not need new knowledge to survive space. They need the knowledge they already have, applied where being wrong is fatal. That is what makes §35.3’s constraint — no mechanic introduced solely for the finale — achievable rather than aspirational.

49. Plan Review: Risks, Gaps, and Scope Control

This section is the maintained critical pass over Part II. It exists because a plan that only argues for itself is not a plan. Everything below is a problem found, a resolved decision, a remaining risk, or a scope cut. New contradictions belong here and must also be fixed at their authoritative section; this table is an audit trail, not an override layer.

49.1 The scope problem, stated plainly

§36.4’s milestones C0–C7 and the MVP Definition of Done in §36.6 were written before §37–§48 existed. They do not account for derived materials, wild terrain, logistic networks, art direction, precursor finds, screen shaders, PPE, plumes or life support.

Read literally, the MVP has roughly tripled since it was defined. That is the single largest risk to this project, and it is fixed here rather than discovered in month nine.

The rule: §36.6 is the sole MVP definition. Its eight outcomes include visible, reviewable science and give hazard prevention equal standing with incident recovery. Everything in §37–§48 is admitted to MVP only in the minimum slice those criteria require. The gameplay refinements in §§27.8, 28.10, 29.5–29.6, 30.5, 32.5, 34.2, 36.9 and 39.9 specify how the existing loop works; they do not add tiers. Offline catch-up, accelerated sleep, general structural collapse, microscopic contamination and broad ecosystem recovery remain deferred. Ship the smallest handling, diagnosis and evidence path that passes the stated tests before adding depth to those systems.

What is in MVP, and what is deferred

Section	In MVP	Deferred
§37 Materials	Block composition; source-backed properties needed by T0–T5; coarse Planckian thermal glow	Generated `MaterialBlockDefinition`, broad derived appearance, procedural textures — hand-author ~20 material blocks instead
§38 Tech tree	T0–T5 only	T6+
§39 Biomes	4–6 biomes; distance bands (§39.8) — structural and cheap	The exotic set; most of §39.2–§39.5
§41 Wild terrain	Nothing. Part I’s terrain plus exposure where it is free	The 3D density-field rewrite. This is a large engine cost with no chemistry dependency
§42 Logistics	None of the §42 network; §32’s gravity chutes and mechanical belts only	Hangars, drones, the five containers, the network inventory
§43 Art direction	Yes — it is the look	The late-tier futurism gradient
§44 Finds	A handful of blueprint plates	Salvage, reverse engineering, instruments, the precursor layer
§45 Shaders	Hypoxia, CO, thermal burn — the hazards that exist at T1–T5	Neurotoxic, tremor, irritant, radiation
§46 PPE	Damp cloth, leather, goggles, water rinse and §46.5’s counter-cases	Respirator classes, breakthrough, the suit
§47 Plumes	Smoke, steam, and the invisible-CO rule — core to the hazard teaching	Deposition, inversions, metal fume
§48 Atmosphere	Nothing	All of it — it is T20

§41 is the most important cut. Wild terrain is genuinely desirable and has no chemistry dependency whatsoever; it is engine work that can land any time after MVP without disturbing a single reaction. Doing it before C0 would delay the thing that makes this game distinctive in order to make the ground prettier.

49.2 Technical risk register

R1 — Cross-platform determinism will break. Severity: critical

§28.8 promises bit-identical results across processes, and §2.4 requires the standalone server to run on Linux, Windows and macOS using the same chemistry core. System.Math.Exp, Log and Pow are not guaranteed to be bit-identical across platforms, runtimes or libm versions. The entire engine rests on K = exp(−ΔG/RT) and on Q = Π aᵢ^νᵢ, so this is not a corner case — it is every tick of every vessel.

Left unaddressed, this produces a class of bug that is nearly impossible to diagnose later: two machines silently diverging after ten thousand ticks.

Decision resolved (C0-001): ship our own transcendentals.

Implement DeterministicMath with in-house Exp, Ln, Pow, Sqrt — minimax polynomial approximations over reduced ranges, fully specified, using only IEEE-754 add/multiply/divide.
Forbid System.Math transcendentals inside VoxelSandbox.Chemistry, enforced by a test that scans the compiled assembly for the disallowed calls. An enforced ban is worth more than a convention.
Validate against reference values to a stated ulp bound, and include it in C0’s gate.

Rejected alternatives: fixed-point (the dynamic range of moles and of exponent arguments is too wide), and narrowing the determinism claim to one platform (breaks §2.4’s server, and §28.8 is load-bearing for saves).

R2 — The chemistry frame budget is optimistic. Severity: high

§36.7 allows 1.0 ms per tick for 256 vessels. Naïvely, that is 256 vessels × every reaction in the catalogue × several transcendentals, and it will not fit once the catalogue passes a few hundred reactions. A budget without a mechanism is a wish.

Three mechanisms are required, not optional:

Bidirectional candidate indexing. Index both consumable sides of reversible reactions; a domain evaluates a direction only when that direction has material to consume. Optimisation may not make product-only reversal impossible.
Validated thermodynamic cache. Cache exact evaluations by canonical temperature key, or use a bounded interpolation whose error is below the published chemistry tolerance and whose approximation is exposed under §34.2. Never silently quantise K enough to move an observable equilibrium.
Quiescence (§29.1), already specified — the largest win, since a mature base is mostly idle.

R3 — Save size will exceed budget. Severity: medium

The original §36.7 allowed 8 MB, but §34.2 specifies a journal holding thousands of run entries plus hundreds of substance and reaction pages, alongside the sparse block-state overlay, vessels and networks.

Decision: do not “solve” this by deleting experimental history. §36.7 now uses a measured, category-specific compressed-save target. Events store compact deltas and stable references; summary rows, diagrams and best-run pages are rebuildable indexes. Lossless compression and deduplication are allowed. Lossy compaction is not append-only, so it requires an explicit player export/archive action and may never be part of an automatic save.

R4 — Multiplayer chemistry is unaddressed. Severity: medium, deferred

§2.4 requires the server to own all mutable truth. The chemistry simulation is now a large, stateful, 20 Hz mutable system, which makes it server state.

VoxelSandbox.Chemistry being Unity-free (§36.1) was the right call and makes this tractable — the server can run the identical assembly. Decision: multiplayer chemistry is explicitly out of scope until after §36.6, and no chemistry API may assume a Unity main thread or a single local player.

49.3 Product decisions and resolved foundations

D1 — Process time scale. Resolved by C0-001.

A real lime kiln burns for three to five days. A real electrolytic refining cell runs for weeks. At 1:1 the game is unplayable; instantaneous, and automation has no purpose and §27.5’s hour targets are meaningless.

Adopted policy: a 60× industrial-process rate scale, with explicit clock domains.

Kinetics are scaled. Thermodynamics is not. Equilibrium positions, K, ΔG and E stay exactly real — what can happen is untouched. Only how fast is compressed.
Within the industrial chemistry catalogue, the factor is uniform, so relative modelled rates are preserved. It does not silently scale input, animation, network timeouts, pressure-wave propagation or acute player physiology. Long-horizon metabolism/life support uses the stated game calendar. Every coupling declares which clock it consumes and is tested for pause/save behaviour.
It must be declared openly in §28.9’s approximations list, and stated in the journal in real units (“this would take about four days at full scale”).
Clock definition: a game calendar day remains 24 process hours and lasts 1,440 wall-clock seconds (24 minutes). §48’s daily physiological requirements use a real 24-hour process day, not an ambiguous visual day/night cycle.

D2 — Death, injury, and what is lost. Resolved.

Unspecified anywhere in Part II, and it interacts badly with an eighty-hour journal.

Knowledge is never lost. Death costs recoverable materials, position and time — never a journal entry, never an achievement, never a discovered reaction. This is mechanically merciful and thematically exactly right: what you know is what you are, and §27.7’s whole purpose is defeated by a design that can delete understanding.

Chronic injury is long-lasting but recoverable with correct treatment and process time. The journal may truthfully explain that some real-world injury can be permanent, but this campaign does not irreversibly damage an eighty-hour player save.

D3 — The first twenty minutes. Resolved as a C6 acceptance flow.

The plan is strong on systems and silent on the opening, which is a serious gap for a game whose entire thesis is that trial and error teaches. A player dropped into a world with no guidance, no recipes and no tech tree can simply be lost — and “lost” is the failure mode §44’s friction reduction exists to prevent.

The fixed opening contract is: spawn within sight of wood, water, loose stone, clay and a sheltered work area; the journal begins with one question, not a recipe; collecting and inspecting those materials records sensory evidence; a first fire produces heat/light/smoke and an after-action entry; covering a small wood burn yields charcoal plus a warning to ventilate; native copper, when present, is a bonus demonstration rather than a required gate; the first lead points toward the pit/clamp kiln bootstrap (§29.3). A no-input observer test verifies resources/reachability, and recorded fresh-player tests verify that most players create fire, open its run entry, and can state one next experiment within twenty minutes. The route teaches that experimentation is productive before demanding chemistry.

49.4 Contradictions found, and their fixes

Contradiction	Fix
§27.4 pillar 6 requires manual operation to be “viable and complete for every process”, but industrial electrolysis and millisecond plasma feedback cannot be manual	Pillar 6 amended in place — manual viability holds through the tiers where human speed and endurance suffice; beyond that, control loops are a physical requirement, not a designer’s gate
§38.10’s reachability test walks the tree using “the seven gates”, but one of those gates is knowledge, which a build-time test cannot model	Amended in place — the test proves physical reachability only, treating knowledge as always available
§42.2 specifies belt throughput in kg/s, but §30.4 makes matter mass-with-composition while belts visually carry discrete objects	Amended in place — belts carry discrete units (sack, bar, crate), each carrying its own mass and composition; throughput in kg/s is derived from unit mass and belt speed
§34.2 said the journal becomes “typeset” at late tiers, contradicting the hand-drawn identity	Already fixed: the journal is always hand-drawn; the arc is uncertain→confident, never handwritten→printed
Part I’s crafting/combat/hunger extension conflicts with Part II’s process manufacture and “no combat” identity	Added an explicit chemistry-campaign product profile after the Part II heading; legacy systems may remain in platform test scenes but are disabled in the campaign
The thermodynamic equations mixed kJ and J and described Shomate as A–E while using A–H	§28.1/§28.3 now define phase records, formal charge, A–H and explicit `/1000` / `×1000` boundaries, with a factor-of-1,000 test
Aqueous standard electrode potentials were implied for every redox reaction, including dry high-temperature furnace chemistry	§28.6 now separates oxidation-state bookkeeping from electrochemical half-cell data and applies `ΔG = −nFE` only at matching states/conventions
“Debye–Hückel and no further” was paired with concentrated mineral-acid gameplay outside that dilute model’s validity	§§28.4, 28.9 and 36.8 now require concentration-appropriate sourced activities and defer content outside the validated envelope
“Ideal gas throughout” contradicted high-pressure oxygen, steam power, liquefaction and cryogenics	§28.9 now confines ideal gas to an MVP envelope and makes real-fluid data/model validation a prerequisite of later milestones
The former universal `r = kΠa^order(1−Q/K)` claimed measured kinetics, failed product-only reversal, and let `ReactionId` choose winners	§28.5/§28.7 now require sourced reaction-specific kinetics, bidirectional candidates, simultaneous snapshot evaluation and a deterministic competition projection with ID-permutation tests
“A vessel is the only place chemistry happens” conflicts with gas ignition, corrosion, hydroponics and physiology	§28 introduces a shared reaction-domain/control-volume contract; vessels are the MVP implementation, not a second law of nature
“No hazard kills without a perceivable signal” invented toxin-specific vision and visible radiation for hazards human senses cannot identify	§§31, 45 and 47 now require an available truthful warning path, keep invisible hazards invisible, and reserve identification for process evidence and instruments
One concentration×time scalar with “real thresholds” treated unlike toxic mechanisms as interchangeable cliff values	§31.2 now requires hazard-specific reduced physiology and preserves published averaging durations/populations as reference bands, not damage points
Accurate formulae could change hidden state without teaching the player what occurred	§27.7 and §34.2 now make in-world evidence plus a durable, provenance-linked “What just happened?” account a release-gated content contract
Absolute conservation conflicted with capped gas entities, finite saves and the claim that all pollution deposits locally forever	§§27.7, 28.9, 31.2 and 47.5 now use explicit active control volumes plus a persistent regional atmosphere ledger; dilution/reaction/transport are accounted transformations, not deletion
Per-species mole rounding and removal below `1e-12 mol` silently deleted atoms while pillar 1 called conservation absolute	§28.8 now requires a conservative projection and bounded trace ledger, tested in atom/charge ledger units
“Atoms and mass are always conserved” contradicted a fusion endgame where nuclei change and binding-energy mass defect matters	Pillar 1 now distinguishes chemical element/charge conservation from nuclear nucleon/charge/mass-energy accounting
A `ushort BlockId` cannot enumerate every continuous alloy composition, and save-local allocation order is not a network-stable identity	§37.2 separates bounded block form IDs from content-addressed material records and chunk-local palettes, with collision/overflow paths and manifest checks
“Every property is derived from composition” overstated predictive science for hardness, toughness, colour and corrosion; blackbody “full stop” ignored emissivity/display	§37.3/§37.4 now distinguish sourced measurements, validated models and labelled approximations; thermal glow is a Planckian coarse thermometer, not an exact pyrometer
“Exactly seven physical quantities” included nonphysical knowledge while geography introduced an undeclared logistics gate	§§34.1, 38.2 and 39 now name access explicitly and test seed-level physical reachability without pretending every element exists near spawn
The 900 K fire jumped to a ~1200 K ceramic gate without reachable apparatus	§§29.3 and 38.4 add the earth-covered charcoal and pit/clamp-kiln bootstrap, with a reachability/playtest gate
C3/C4 required advanced respirators, drones, electricity and PID inside a T0–T5 MVP while §49 deferred them	§36.4 now limits MVP hazards and automation to ventilation, mechanical handling/power and period-appropriate passive controls
Automatic lossy run-log compaction contradicted the immutable append-only journal	§36.7 and R3 now use category budgets, compact event deltas, lossless compression and rebuildable indexes; automatic saves never discard experiment facts
Precursor finds claimed to shortcut knowledge only while granting components, instruments and “confirmed” results	§44 now permits finite conserved artifacts without permanent capability, and records external claims as provenance-labelled claims until reproduced
Fixed melting/boiling points contradicted altitude, mixtures and the bronze phase diagram	§28.7 now requires pressure-aware pure-phase boundaries and sourced mixture phase models, with missing behaviour labelled rather than fabricated
§40 assigned phase thermodynamics to abstract elements, counted As/Sr twice, and counted D/T as new elements	§40 now separates element, isotope and substance-phase records and states the unique staged roster accurately
Life-support daily values were presented as universal exact needs and omitted crew/activity/leak/reserve assumptions	§48.1 now labels a nominal planning case and requires the journaled mission mass balance to state its assumptions and margins
The stellarator copied tokamak “disruption” language, implied one fast PID stabilises the plasma, omitted tritium, and called fusion gain “criticality”	§§34, 35 and 38 now distinguish stellarator confinement/plant control, account D–T fuel, and name the exact `Q_plasma` metric and Fusion gain achievement
D–T fusion required tritium bred by fusion neutrons but supplied no source for the first tritium	§38 adds an explicit D–D startup → neutron/tritium seed → lithium breeding → D–T bootstrap spiral
The hour-scale progression did not specify satisfying short sessions or a self-contained MVP ending	§27.8 defines choose/try/notice/use/return intentions, useful first products and a continuing bronze-workshop end state
Reading the notebook, quitting and unloading chunks had no agreed effect on live hazards or production	§29.5 separates render residency from simulation, pauses all campaign clocks together and forbids offline catch-up in MVP
Rejecting recipe crafting left the manufacture and dismantling of apparatus unspecified	§29.6 requires reachable fabrication operations, placement validation and conserved intermediate/charged states
Inventory transfers could implicitly cool hot matter, erase contamination or turn an assay into knowledge of an entire deposit	§30.5 defines one owner, batch provenance, retained samples, extraction rules and persistent physical state
“Explain every failure” could turn the journal into an oracle, or misrepresent missing chemistry as observed inertness	§§28.10 and 34.2 distinguish model limits, detection limits and inconclusive evidence, with useful next observations
Durable per-event science history had no bounded run lifecycle or response to storage back-pressure	§34.2 defines run boundaries, observation cadence, grouped views and coherent state/event commits with a saving pause
Automation acceptance covered only steady output and treated stoichiometry as a throughput forecast	§§32.5 and 36 require blocked-output, power-loss and restart fixtures, and distinguish theoretical ratios from actual yield/rate
Templates required prior success despite the prohibition on knowledge unlocks	§§32.3, 34.2 and 44.7 permit untested procedures; successful runs certify only their recorded conditions
Mandatory near-death and survived-hazard gates punished players who understood prevention	§§27.5, 31.6 and 36 make prevention valid, define recovery and prohibit injury as progression
A mathematically reachable tier could still lack enough accessible fuel/material for mistakes or replacement apparatus	§39.9 adds quantity- and route-aware seed validation, finite inventories and a tested recovery scenario
C5 was the first explicit UI milestone even though invisible chemistry could fail long before it	§36.4 requires minimal evidence/after-action views in C1–C4; §36.9 tests comprehension and session continuity before content expansion
Open-vessel and relief-valve logic removed gas after the solver’s tick summary, so the player could lose matter with no causal record	C1 now commits a contiguous `VesselGasVented` lifecycle fact for every recorded escape and a `VesselFailed` fact for wall failure; the latest-run review reads that same prefix and never substitutes a hidden reaction identity
Hand-drawn identity and precise prose could exclude accessible reading or invent precision before instruments	§34.2 adds equivalent readable views, localisable units/templates, stable bookmarks and uncertainty-preserving display
The old workspace rules prohibited the documentation location explicitly requested by the user	§1.1, `Docs/GROUND_RULES.md` and root `CLAUDE.md` now agree on the `Docs/` layout, with `CLAUDE.md` staying at root
§36.4 required “a thin in-world presentation” per C1–C4 slice but made no gate depend on it, so three milestones’ worth of chemistry landed that no player can reach	§36.4a defines the P-gate — reachable, legible, durable, evidenced by a committed artifact — and names EditMode tests and Voxel Workshop modules as things that explicitly do not close one. §22 and §36.6 now bind to it
Milestone task lists were single paragraphs of semicolon-separated clauses, which cannot be split across sessions without each one re-deriving scope and drifting into its neighbours	§36.4’s preamble now mandates a `Depends` / `Touches` / `Do` / `Done when` / `Out of scope` task format, applied in full to C1-P, C2 and C3; `Out of scope` is binding
The `Player → Industry` assembly edge was needed by any player-facing chemistry, forbidden by `CLAUDE.md`’s description of the layering, and owned by nobody — so no session could add it	C1-P.2 authorises it explicitly and solely; `Industry` still gains no back-reference to `Player`

Implementation deltas exposed by this review

These are not new design options. They are concrete gaps between the corrected contract above and the current C0-era implementation, and they remain visible here until tests close them:

P0 — the player cannot reach any of it. The mine → grade → batch → charge → vessel → narrate chain is complete, conserved and unit-tested end to end, and has no runtime consumer whatsoever: VesselRuntime is a bare MonoBehaviour with no mesh and no interaction, and Player holds no reference to Industry. This was recorded in Docs/HANDOFF.md as an open decision awaiting an owner. It is resolved: C1-P is that work, it is hard-blocking, and §36.4a is the rule that stops the same gap reopening at C2, C3 and C4. Until C1-P’s gate closes, no milestone may report a slice as landed on the strength of headless tests and a Workshop module.
P0 — coupled reaction stepping: ReactionKineticsMath / ReactionEvaluator still implement the former (1−Q/K) relaxation law. VesselSolver now evaluates snapshot proposals, uses one shared consumption/energy scale, and orders arithmetic by physical reaction definition rather than stable reaction ID; fixtures cover input permutation and ID renumbering. The remaining §28.5/§28.7 gate is a sourced production-kinetics validation set, especially competing reversible paths, before adding a production catalogue; preserve old kinetics fixtures only as explicitly labelled approximation tests.
P0 — conservative quantisation: VesselCharge now projects visible amounts downward to the 1e-12 mol grid and carries positive remainders in its bounded canonical trace ledger; remainders promote back into visible charge and contribute to mass/fingerprints. Multi-species reaction steps preflight ledger capacity. The remaining acceptance gate is a long-run atom/charge ledger test and persistence of trace entries with the vessel snapshot before claiming complete interrupted-run conservation.
P0 — science event spine: C0 now has a bounded caller-owned ScienceEventBuffer, opt-in VesselSolver event path and ScienceEventLog. The solver emits aggregate accepted reaction extents plus a complete-tick fact only after conservation passes; the log accepts only a contiguous whole batch and validates a restorable event prefix. ScienceAfterActionBuilder now emits localisable player claims through declared contents/temperature/pressure/identity channels, and tests prove an unobserved reaction ID cannot leak into the account. It is intentionally authoritative fact data, not player observation or prose. Next, atomically commit that prefix with the matching run/vessel state and add apparatus/instrument calibration, sampling and provenance before C1 presentation, so explanations are not reconstructed later from incomplete saves or leaked from hidden solver truth.
P1 — vessel lifecycle evidence: C1’s open-lid and relief paths now append explicit gas-transfer facts after the corresponding closed-domain tick; thermal and overpressure limits append an explicit failure fact. VesselDomain.TryBuildLatestAfterAction reconstructs one committed interval from that prefix, including those lifecycle facts, and its tests cover visible gas escape and a wall failure without a temperature reading. These facts remain apparatus-local until C3 transfers them into the atmospheric mass ledger; no current implementation may call vented gas harmless or deleted.
P1 — phase/energy/headspace: current C0 phase boundaries and pressure arithmetic are useful isolated fixtures, but the §28.7 control-volume energy convention, condensed-volume headspace and mixture/pressure envelopes are not complete. Do not describe those fixtures as general vessel physics.
P1 — thermal glow handoff: BlackbodyEmission is a deterministic Planckian colour utility, not yet an emissivity-aware material model or a player-visible thermometer. Keep the utility, add material emissivity/exposure uncertainty, wire it only to actual temperature-bearing surfaces, and journal what the glow can and cannot establish.
P1 — platform determinism: same-runtime deterministic-math tests exist; the §28.8 shipped- runtime/architecture bit-identity matrix remains a C0 release gate.

The living, session-to-session record of which of these deltas are closed, what is built ahead of its consumer, and what blocks the next milestone step is Docs/HANDOFF.md. This section states the contract gaps; that file states where the code currently is. Keep them consistent: when a delta here is closed, note it in the handoff’s State and Next steps, and when a delta is fully retired, strike it here.

49.5 What remains deliberately unspecified

Recorded so that silence is not mistaken for an oversight:

Narrative content of §35.3’s final encounter. Deliberately loose; §35.4’s scope-honesty rule applies, and it must not become a dependency of anything earlier.
Exact balance numbers — ore grades, deposit sizes and biome frequencies. These are tuning, they belong to C6, and fixing them now would be false precision.
Art asset specifics beyond §43’s direction, which remain subject to §14’s licensing rules.
Precursor backstory. §44.5’s restraint is the design; there is no hidden document to write.

49.6 The one-paragraph verdict

The core thesis — that thermodynamics, kinetics and electrochemistry can carry progression — remains sound only if the player can see and interrogate their consequences. The plan now has one product gate, a closed T0→T5 bootstrap, explicit control-volume boundaries, honest epistemic labels and a causal journal contract. It now also specifies session continuity, physical handling, diagnosis, recovery, resource sufficiency and what the notebook must honestly leave unknown. The highest remaining risks are cross-runtime numerical identity, coupled-reaction neutrality, bounded atmospheric/event storage, source-quality kinetics, and whether players can form and enjoy the next experiment. Numerical tests and the §36.9 comprehension/session tests must both pass; neither stands in for the other.

User-contributed notes

Corrections, clarifications, and practical tips for this page. Anonymous is fine — a name is optional. Basic Markdown works: **bold**, *italic*, `code`, and links.

Notes policy

Notes are lightly filtered for spam and may be edited or removed. Keep them about this page — no support requests, no personal data, nothing you would not publish. Links are limited and marked nofollow.

Loading notes…