RIFTSTORM: FOUNDRYWORLD BIBLE

The thousand-foot view

Foundry is a grounded civilization builder. You begin with a small community that must feed itself, give people useful work and connect its buildings. That same community becomes the capital of a region, a country, a unified world, and eventually a civilization spread across several star systems. You can keep returning to its streets as the economy, buildings, vehicles and command tools change around it.

The central loop is discover a constraint → research a solution → build and staff it → connect it → observe the result → choose the next ambition. Population is useful labor and a set of needs. Transport moves actual goods. Research opens capabilities, requires investment and time, and creates new obligations. Governors help manage complexity under the player's policies.

The final design is an operating multi-system civilization: several inhabited worlds with different environments and industries, colonies that require life support, mining and manufacturing networks, fleets in transit, and governors answerable to your priorities. There is no final button that makes every problem disappear. The challenge becomes resilience, coordination and choosing what kind of civilization to build.

Civilization progression

What is real today, and what is the design target?

• Live foundation at the start of this expansion: Town, Region, overseas settlements, National Charter, Country formation and the first Council project.
• Country chapter (0.5): local settlement development, industrial buildings and electricity, motor and air transport, longer research, stronger Steward training, an optional local Decider connection, better ships, and research-linked dashboard technology. Release receipts establish which items are tested and published; this document does not replace those receipts.
• Future design: World unification, orbital infrastructure, planetary colonies, asteroid mining and interstellar expansion. Their descriptions below are design commitments to evaluate, not claims that those systems already run.

The design rules

1. Your existing work matters. Settlements, research, expertise, trade history and infrastructure count toward later stages. A new age expands an existing civilization rather than resetting it.
2. Capability comes from infrastructure. An aircraft needs an airfield, trained workers, operating funds and sufficient power. A researched icon alone cannot move cargo.
3. Every valuable upgrade has a visible result. Buildings gain modeled additions, traffic changes, workers perform appropriate tasks, and dashboard instruments reveal the new system. A cosmetic change does not substitute for an economic effect.
4. Greater power brings greater decisions. The player chooses specialization, reserve levels, routing priorities, research direction and delegation. The best research takes longer and requires more capable production.
5. Failure is explainable. Show where goods are waiting, which job is vacant, what a route costs and why research or dispatch has stopped. Avoid invisible penalties, surprise food drains and irreversible losses without warning.
6. The world feels physical. Structures have grounded footprints and usable entrances. Wheels turn on roads; hulls sit in water; rotors and propellers have correct orientation. Heat, sunlight and wind influence relevant systems.
7. Detail follows the camera. A browser does not simulate every person and bolt across an entire civilization at once. Nearby activity is detailed; distant cities keep their economy and scheduled transport in aggregate.

Progression by scale

World unification is a substantial chapter

Country must not jump directly from a few transport upgrades to a rocket. The World chapter should add other nations or political regions, shared projects, agreements and competing priorities. The intended peaceful paths include a trade federation, a negotiated political union, or a common response to a planetary infrastructure problem. Each path should require material contributions and public legitimacy. A single payment that paints the map one color is insufficient.

Research: decisions, time and prerequisites

Research has three separate requirements: knowledge investment, research work time, and the physical capability to pursue the subject. More advanced benefits require longer work and more infrastructure. Training and laboratories improve the work rate; they do not erase the knowledge bill.

The Country implementation establishes these branches:

These are game-time work requirements before training bonuses. Research also waits for sufficient knowledge. Speed controls change simulation speed. The game must display the knowledge balance, work progress, remaining work and missing infrastructure separately.

The next research families should be explicit before the World chapter ships: public health and sanitation; materials and manufacturing; energy and storage; communications; administration and diplomacy; transport; environmental resilience; and space systems. A later technology should unlock a new action or solve a specific constraint. Repeated percentage upgrades belong at the end of a mature branch, with diminishing returns and a visible opportunity cost.

Research choices can converge. Motor transport helps a growing industrial country; power and manufacturing are needed before aviation. The player can improve food distribution first, expand factories first, or build freight capacity first. Research availability is not permission for an AI to choose every expensive project automatically.

Settlements are playable places

Every established outpost and port should open into a navigable local view. Players can inspect its people and jobs, build on available plots, choose a production focus, upgrade facilities and connect transport. A forest settlement should retain its timber identity; a mineral district should look and operate differently from a fertile port.

The Country chapter uses a bounded development district around existing services. Four residents maintain the inherited settlement. New facilities require explicit local hiring from its remaining population. Production enters a local inventory; that inventory is not the same as goods delivered to the capital. Warehouses, housing, staffing and transport each address a different bottleneck.

Later stages expand the district concept into neighborhoods, cities and worlds. Their local views reuse the same principles, with era-appropriate architecture, terrain and traffic. A remote city remains economically active when its view is closed. Opening it must not create population, manufacture resources or replay a delivery reward.

Transport and logistics

Goods are paid out once when they arrive. Pausing a service stops future departures; cargo already in transit completes its trip. Food exported for automatic aid must respect the capital's protected meals. Vehicles do not produce money merely by existing.

The first implementation can abstract fuel into operating cost. A future fuel chain must add procurement, storage, range and substitution choices; adding a fuel icon without meaningful logistics would create bookkeeping instead of play.

People, Steward and governors

Close views show people going to work, performing jobs and moving supplies. Larger scales use representative movement over aggregate populations, with auditable jobs, inventories and needs. The important promise is economic continuity, not an impossible claim that every person in a galaxy is individually simulated in the browser.

Mara's intended career moves from Apprentice to Town Steward, Quartermaster, Regional Steward, Master Governor, National Steward, Industrial Commissioner, Transport Commissioner, Chancellor and Chief Governor. National ranks require research, experience and training supplies. Talent points are limited: the player cannot maximize every research, settlement, industry and transport discipline.

The player controls priority, reserves, a maximum spend per decision, research direction and permission for national works. Governors must show accepted decisions and explain when no legal useful action is available. Founding a country and choosing its first Council project remain deliberate player choices.

The local Decider is a candidate-selection engine. The game's code creates legal choices; the model scores or selects among them; code checks the current state, permission, reserves and cost before executing anything. It is not an omniscient chat character. The existing local model runs on the owner's computer through an optional companion, with a normal local Steward available when disconnected. This does not place a multi-billion-parameter model in every visitor's browser. Jev can use the same typed governor boundary through a separately configured provider. A future public hosted governor requires its own operational design.

The dashboard evolves with the civilization

Dashboard technology unlocks through the game. Screen styling is never a reason to hide basic controls, make text translucent or replace readable information with decorative lines. Players may retain an earlier unlocked display, reduce motion and reduce effects. A hologram is a presentation of usable information; it must not become another set of unexplained floating boxes.

Graphics and animation standard

The direction is grounded industrial realism, with black, every useful shade of gray, and red for interface accents and warnings. Terrain keeps natural colors. Buildings use modeled geometry with generated PNG surfaces so they retain their painted material character from every camera direction. Silhouettes, entrances, ground contact and construction stages must be checked from street, close and map views.

Every building family needs construction, operation and upgrade states. New levels should add physically readable capacity: another workshop bay, additional storage, machinery, housing stories, more capable loading areas or upgraded power equipment. Workers and vehicles should reveal the purpose of the building.

Visual complexity grows through richer systems and better close detail, not unbounded particles or polygons. Traffic progresses from people and carts to motor fleets, aircraft and space logistics. Lighting progresses with the grid. Remote maps become geographic/planetary/orbital views with meaningful routes. The final civilization still has a consistent material language and legible infrastructure, rather than becoming a magical theme park.

Environment and physical behavior

The design models consequences at a useful game scale: day/night and sunlight, weather and wind, heat and shelter, terrain access, resource availability, water connections, vehicle movement and power demand. A later off-world colony adds environment-specific power, thermal regulation, atmosphere and life support.

This is a game model of those systems, not a claim to engineering-grade fluid, climate or orbital simulation. Each new system must affect decisions, expose its measurements and have a recovery path. Full rigid-body physics for every crate across a world is unnecessary; a convincing loading animation over exact cargo accounting is more useful.

Difficulty, fairness and long runs

The long-run challenge is managing competing commitments. Advanced factories need labor and inputs. Air service competes for power and funds. New settlements consume construction resources before their exports repay the investment. Research occupies time and knowledge that could support a different branch.

Essential recovery remains possible. The game should announce bottlenecks before catastrophe, allow services to be paused, preserve manually assigned jobs, protect basic meals during automatic aid, and retain completed research. Disasters and long-distance failures should become optional, researched or clearly signaled challenges rather than arbitrary punishment.

Future difficulty presets should change the economic margin and recovery window, not hide arithmetic. An optional demanding mode may add maintenance chains, environmental pressure and stricter reserves. A learning mode should preserve the same understandable rules with more forgiving starting conditions.

What the endgame looks like

You open a holographic system map and see three settled systems. One specializes in food and biological research, another in metals and orbital manufacturing, and a frontier system needs local water processing before it can support more people. A governor proposes a new refinery. You reject it because its power margin is too small, authorize a storage project, and redirect a supply ship while a long-range propulsion program continues.

Then you return to the original capital. Its old core is still recognizable. Roads carry modern traffic, workers enter real facilities, upgraded harbors move freight, and the city has visibly grown through the ages. You can walk the streets that began with six settlers. The civilization view and the human view describe the same saved world.

Interstellar travel and distant planning will use explicit game-time compression. No faster-than-light system is assumed to be scientifically established. If a fictional breakthrough is later chosen, the Bible must identify it as a fictional rule and define its costs and limits before it becomes gameplay.

Browser and implementation rules

• Keep strict TypeScript modules for population, economy, research, territory, settlement development, transport, governors and rendering.
• Store authoritative resources and scheduled arrivals once. Rendering and AI proposals cannot mint resources, duplicate people or execute arbitrary code.
• Save optional stage extensions compatibly. Capacity increases require in-transit save/load tests. Later settlement growth requires matching validation.
• Keep detailed simulation and rendering concentrated on the active place; aggregate distant populations and transport. Cache terrain and reuse model data.
• Measure desktop and phone layouts, reduced quality, frame time, model memory, repeated view switching and long-run save validity. Physical-device acceptance remains separate from browser emulation.
• Retain explicit code, model, texture and total-download budgets. Optimize or justify a measured budget change; never silently remove the gate to ship art.
• Do not call a future stage playable because its enum, mockup or documentation exists. Every stage needs a complete normal-control loop and release evidence.

Research references and adaptation

These are reference patterns, not copied code or promises to reproduce another game. Foundry's implementation and balance remain its own.

• Factorio research mechanics: separates research cost, work time and research capacity. Foundry adapts that distinction to knowledge, work time and staffed infrastructure.
• OpenTTD vehicles and stations: transport modes have distinct obligations, facilities and cargo roles. Foundry uses those general principles for its own scheduled routes.
• Ubisoft's Anno 1800 overview: workforce, production chains, expeditions and trade support a growing settlement network. This informs the need for playable local economies at each scale.
• NASA's ISRU overview: local material use, processing and transport provide grounded problems for the future space chapter, rather than effortless colonies.
• Mapika Decider source and model card: bounded decisions guide the optional Steward provider. Installed and current upstream versions are documented separately by the model integration review.

Release order and completion standard

1. Finish Country depth: research, staffed industry and power; open every settlement; real national vehicles; capable Steward; dashboard evolution; credible ships; save compatibility and normal-control playtests.
2. Build a real World chapter: multiple national actors, agreements and major shared infrastructure, with a concrete unification path.
3. Qualify first space operations: launch, orbit, repeatable resupply and one survival-capable off-world settlement.
4. Expand interplanetary industry: distinct environments, resource chains, fleets and specialized governors.
5. Introduce interstellar commitments: multiple systems, delayed logistics, higher autonomy and the final holographic command interface.

A stage is complete when a player can reach it through normal play, understand its new choices, use its facilities, recover from a foreseeable shortage, save and return safely, and see its activity clearly on desktop and mobile. The whole game remains an expandable world, with the capital and the player's history intact.