Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/at6132/econ/llms.txt

Use this file to discover all available pages before exploring further.

Precision matters in Realm’s design because the primitives, laws, and mechanics interlock tightly. When two documents — or two people — seem to disagree, check here first. Usually one of them is using a term loosely. This glossary is the authoritative source for terminology across the entire spec. When you add a new term to design discussions, add it here before it appears in three different documents.
These definitions are canonical. When design discussions drift from these terms, return to this glossary to realign.
If a term is missing, it either hasn’t been precisely defined yet (add it) or it’s a special case that should be expressed using existing terms. Do not let undefined terms accumulate — drift is cheap to prevent and expensive to fix.

​
A

A financial entity that holds capital. Owned by a player, business, or the system. Identified by an account ID. Balances are mutated only via transactions — direct mutation outside the transaction layer is never legal. See Capital.
Any state-changing operation a player, AI agent, or service attempts: place order, propose contract, hire labor, build, transfer money, and so on. Actions are proposed — the engine validates each one and either commits or rejects it. The engine is the only entity that commits state. See Authoritative simulation.
An AI participant in the simulation. See Tier 1 agent, Tier 2 agent, Tier 3 agent. In solo mode, agents fill all the roles that human players fill in multiplayer.
Anything that can be held, valued, or traded: materials, equity in a business, currency, a contract receivable. Assets always have an owner and a location. Assets cannot exist without both.
The principle (Law 10) that the simulation is the only source of truth about world state. Clients propose actions; the engine decides what happens. No client ever writes directly to world state — it proposes an action and receives either a commit or a rejection.

​
B

See Tier 1 agent.
The visual drag-and-drop interface for the user-code layer (Phase 4+), aimed at non-programmers. Block programs compile to Lua under the hood. Beginner templates such as “auto-restock” and “price alerts” ship with the feature to lower the entry barrier.
The risk that an emergent economy cannot start because every business waits for another business to exist first. Addressed in the bootstrap and seeding design doc via genesis bonuses, NPC seed economies, and frontier zone mechanics. See Genesis bonus.
A player- or agent-run economic enterprise. Not itself a primitive — businesses emerge from compositions of primitives (plots + capital + labor + contracts + sometimes code). The game does not pre-define businesses; it provides the atoms and lets players invent the molecules.

​
C

Primitive 5. Money. Conserved (Law 1) — it cannot be created or destroyed except through designed channels (e.g., the starting mint, transaction fees routed to system reserve). Held in accounts. Mutated only via transactions.
An invite-only multiplayer scenario with hand-picked participants, time-boxed (typically 90 days). Used for high-prestige play, balance testing, and marketing. See Season. The first closed cohort is the Phase 5 test gate.
See Service.
A group of players in a time-boxed multiplayer scenario. See Season.
Law 1. Matter and money cannot be created or destroyed except through designed channels. Enforced at the transaction and inventory layers. The engine runs conservation-invariant tests on every path that touches money or matter. See Transaction.
Primitive 8. A multi-step, multi-condition, engine-enforced agreement between parties. Contracts are templates plus parameters, not free-form code. Templates in v1: supply, loan, employment, equity, service-subscription. Players parameterize templates (price, quantity, duration, etc.) rather than writing contracts from scratch. The engine enforces deadlines, deposits, and liquidated damages.
A predefined contract structure with named parameters (price, quantity, duration, etc.). Players parameterize templates rather than writing contracts from scratch. This prevents the contract system from becoming an arbitrary scripting environment while still allowing complex multi-step agreements.

​
D

Law 5. Buildings, equipment, vehicles, and stockpiles deteriorate without maintenance. Code services do not decay but require periodic CPU payment to remain active. Decay is implemented via tick_building_decay; the maintenance fee is max(1_000, cost // 5). Building labor bonuses are gated by the building’s current condition.
Law 9. Same starting state + same inputs = same outputs. Implemented by routing all randomness through make_rng(tick, purpose) — no wall-clock reads inside the simulation. Determinism enables replays, debugging, save/load, and anti-cheat without a separate audit system.
Primitive 7a. A one-shot mutual exchange between two specific parties. Distinct from order book trading, which matches anonymous counterparties. Supports an optional idempotency key and returns stable structured error codes on failure.

​
E

A required input to production (Law 4). A tradeable good with location constraints — energy does not transmit globally for free. Local grids mean energy supply and demand are spatially differentiated. Appears in recipes as a metered input alongside matter and labor.
The simulation core. Authoritative. Tick-based. Deterministic. Implemented in Python (FastAPI). The engine is the only entity that mutates world state — the frontend and all clients propose actions and receive responses.
The principle that solo mode must prove the design is fun before multiplayer infrastructure is built. If solo mode isn’t fun, nothing built on top of it will be fun either. This is why the phase plan gates multiplayer on a passed Phase 2 playtest.

​
F

A region of the map periodically opened for new plot claims, used to mitigate the late-joiner problem in long-running shards. New players entering an established world can claim plots in the frontier zone rather than competing for scraps in the settled core economy.

​
G

A unit of in-game time. In public persistent multiplayer mode: 1 game-day = 1 real hour. In solo mode: configurable. Many ticks make up a game-day.
A starting-capital boost given to early players in a new shard who fill needed economic roles (shipping, finance, agriculture, etc.). Phases out as the role becomes saturated. Addresses the bootstrap problem by rewarding players who take on founding roles.

​
I

A player’s persistent in-game self. Has a reputation, a contract history, and a public profile. Creating a new identity has a cost (Law 8) to prevent reputation laundering — you cannot simply discard a tarnished reputation and start fresh for free.
Law 6. Not all world state is automatically visible. Some information costs money or effort — surveys to reveal subsurface composition, fees to access extended market history, analytics subscriptions. Implemented via purchase_market_intel; the free tier shows only the last FREE_MARKET_HISTORY_TICKS ticks; the paid tier extends visibility. See Visibility.

​
L

Primitive 3. Time-bounded capacity to do work. Comes from players, hired NPCs, or AI agents. Located somewhere — labor must be where the work is, it cannot teleport. In the engine, 40% of a recipe’s labor_cents is paid to distinct stub_hires employees per production batch (even split); the remainder goes to the production reserve.
The opening period of a new shard when plots are claimed at high speed by early players. A naturally emergent phenomenon in any new world start. Genesis bonuses shape who participates and in what roles.
One of the 10 engine-enforced rules in the laws spec. Distinct from a pillar — laws are enforced by the engine code and cannot be violated by any player or agent action. Pillars are design principles enforced by judgment. Examples: Law 1 (conservation), Law 5 (decay), Law 9 (determinism), Law 10 (authoritative simulation).
See Tier 3 agent.
The embedded scripting language for the user-code layer (Phase 4+). Sandboxed (no file or network access), deterministic, and resource-metered (CPU and memory budgets billed in in-game currency). The block-based programming UI compiles to Lua.

​
M

Primitive 7. The mechanism for exchanging goods, services, or capital. Two layers: order books (7b) for high-volume assets, direct P2P trade (7a) for everything else. Markets are emergent — order books appear when an asset reaches sufficient volume; no designer places them.
Primitive 2. Physical stuff with properties (mass, density, conductivity, etc.). Has a quantity and a location. Conserved — matter cannot be created or destroyed except through recipes (which model physical transformation). The formal primitive name is “Material,” not “resource” or “resource node.”
Synonym for material in casual usage. The formal primitive name is “Material.”
The iOS/Android companion app. Read-heavy, designed for 5 specific quick-action flows (check inventory, check market prices, honor a contract, approve a trade, monitor production). Not a full game client — the full game runs in the browser. Mobile companion v1 ships in Phase 6; v2 (full functionality) in Phase 7.
Primitive 4, in conjunction with time and distance. Moving goods, labor, or capital between locations takes time and may cost money. Shipping fee = BASE + manhattan_distance × PER_TILE. Goods in transit are in transit state — visible to owner but not usable or sellable until arrival.

​
N

A Tier 3 LLM-driven AI character with a persistent personality, memory, and storyline. Examples: Margaux the Industrialist, Rico the Speculator. Distinct from generic NPCs — named agents generate the narrative texture of solo mode. Few per world (5–15) due to LLM cost.
A non-player character. Almost always a Tier 1 or Tier 2 agent. In Realm, NPCs are functional (consumers, laborers, baseline suppliers) — they are not characters with personalities. Personality-driven NPCs are named agents (Tier 3).

​
O

See Tier 2 agent.
Primitive 7b. A public list of buy and sell orders for an asset. Emerges automatically when an asset hits a volume threshold. Implemented with asks + bids, escrow on bids, iceberg clips, counterparty reputation minimum (min_counterparty_honored), and FIFO matching by price then order_id.

​
P

A discrete stage in the build plan (Phase 0 through Phase 7+). Each phase has a build list and a phase test gate. You are in exactly one phase at a time and do not move to the next phase until the gate is passed. See the phases page for the full plan.
The pass/fail criterion that gates progression to the next phase. Skipping phase test gates is the single biggest risk to the project. If a gate fails, iterate within the current phase or revise the design. Do not move forward with a failing gate.
One of the 7 design principles from the design pillars doc. Distinct from a law — laws are engine-enforced and cannot be violated; pillars are guidance for design decisions, enforced by judgment. When a feature proposal violates a pillar, the proposal needs revision, not the pillar. See design pillars.
Primitive 1. A bounded region of the world with intrinsic properties (terrain, climate, hidden subsurface composition) and derived properties (owner, improvements, survey results). The terrain and subsurface are set at world-generation time and do not change. Ownership and improvements change through player actions.
An economic atom — an entity, resource, or capability the engine knows about natively. There are 9 in v1: land (plots), matter (materials), labor, time/distance (movement), capital, production, markets, contracts, and code (services). Players compose primitives into businesses; the game does not pre-define the businesses. See economic primitives.
Primitive 6. A process that consumes inputs (matter, labor, energy, money) at a location over time and produces outputs (matter, services), governed by recipes. Conservation laws are enforced: every input is accounted for in every output. Buildings on a plot may provide bonuses (e.g., tool_cache lowers labor_cents per batch via BPS).
The persistent multiplayer mode. Many human players, real economic consequences, never pauses, slow real-time (1 game-day ≈ 1 real hour). Multiple shards can run in parallel. See game modes.

​
R

A configured production process with declared inputs, outputs, throughput, and energy needs. Validates against conservation laws — the engine rejects any recipe that violates matter or money conservation. Players choose from a recipe library; anything physics-legal is a valid recipe. Phase 2 shipped 20 recipes across 27 materials.
Primitive 9-adjacent and Law 7. A public, append-only summary of a party’s contract history (honors vs. breaches). Cannot be deleted or revised. Order books can filter matches by min_counterparty_honored. New identities start with no history — reputation is earned, not inherited or purchased.
A reconstruction of past world events using a snapshot plus event log. Possible because the engine is deterministic (Law 9). Replays enable debugging, spectator mode, and anti-cheat investigation without storing full state at every tick.

​
S

The isolated execution environment for player-deployed code services. Restricts file and network access; meters CPU and memory. Implemented as a Lua sandbox with resource budgets billed in in-game currency. Services that exceed budget are paused until the player pays.
A configured starting world for solo mode or a closed cohort. Defines the map size, initial AI agents, starting capital, and any optional objective or economic pressure. Phase 2 shipped 4 scenarios: Frontier (default grid, standard start), The Bootstrapper (5,000start,32×24grid),∗∗TheSpeculator∗∗(5,000 start, 32×24 grid), **The Speculator** (20,000 start, 40×30 grid), The Cartel (grain-side competitive pressure overlay).
A time-boxed multiplayer cohort, typically 90 days. Ends with rankings and world archive; the world resets for the next season. Seasons are the unit of competitive multiplayer in Phase 5 and Phase 6.
A player-deployed code function in the user-code layer (Phase 4+). Can be called by other players (paid via subscription or per-call). Has reputation, versioning, and usage metrics. In solo mode, pre-shipped services fill the marketplace so it is not empty at launch. The service layer is Primitive 9.
A single instance of the multiplayer world. Each shard has an independent economy. Multiple shards run in parallel (Phase 7+); each is its own world with its own prices, politics, and history. A player has one account but can participate in multiple shards.
Single-player versus AI agents. Pausable, configurable speed, save/load via SQLite. The existence test of the design — if solo mode isn’t fun, nothing built on top of it will be fun. Solo must pass Phase 2’s $30 playtest gate before multiplayer infrastructure begins.
The hidden material content of a plot. Not visible until surveyed. Part of the information-asymmetry design (Law 6) — players who invest in surveying have a genuine informational advantage over those who don’t. Set at world-generation time; does not change after generation.
An action that reveals some of a plot’s subsurface composition. Costs money (routed to system reserve) and time. Can be performed by the plot owner or by surveyors hired under contract. Survey results show terrain type and applicable recipe_ids. A deeper tradable survey intel market is planned as an optional extension.

​
T

The smallest unit of simulation time. The engine processes a fixed amount of work per tick: handle inbound actions, run scheduled events, tick agents, and clear markets. Tick rate ≠ game-time rate — many ticks make up a game-day. All randomness is scoped to (tick, purpose) to preserve determinism.
A hand-coded behavioral NPC. Cheap, predictable, used in volume to populate the world. Approximately 100 lines per archetype. Phase 1 shipped 6 archetypes: grain consumer, lumber buyer, timber relister, coal buyer, clay buyer, electricity buyer. Also called “behavioral agent.”
An algorithmic optimizing NPC. Solves a defined economic problem — market-making, logistics routing, production planning, employing labor. Provides credible mid-tier competition. Phase 2 shipped 5 archetypes in agents_tier2.py. Also called “optimizing agent.”
An LLM-driven named character with a persistent personality, memory, and natural-language messaging capability. Few per world (5–15) due to LLM cost. Phase 3 ships the first Tier 3 agents. Also called “LLM-driven agent” or “named agent.” Examples: Margaux the Industrialist, Rico the Speculator.
Law 2. The fixed ratio between game-time and real-time. In public persistent multiplayer: 1 game-day = 1 real hour. In solo mode: configurable (speed setting). The time scale cannot be changed mid-world in public mode — it is part of the world’s physical constants.
A double-entry-bookkeept state change. The only legal way to mutate world state involving capital or materials. Conservation laws (Law 1) are enforced at this layer — every transaction must balance. The engine validates all transactions before committing them.
The state of goods that have been dispatched via the movement system but have not yet arrived. Visible to the owner. Goods in transit cannot be used or sold until they arrive. Transit state is persisted in save files (snapshot version 1+).

​
U

The Lua-based programmable services system (Primitive 9). Players write code, deploy it as services, and sell subscriptions or per-call access to other players. In solo mode, AI agents publish and subscribe to services. Phase 4+. Described as the “moat primitive” — it turns Realm from an economic sim into a platform where in-game SaaS businesses are structurally real businesses.

​
V

A first-class concept (Law 6). Every piece of world state has a “who can see this?” flag: public, owner-only, contract-revealed, survey-revealed, and so on. Visibility asymmetry creates the information cost mechanic and enables businesses like surveyors, analysts, and intelligence brokers to exist.

​
W

A single simulation instance. In solo mode: a save file (SQLite). In multiplayer: a shard (Postgres). Each world has its own economy, prices, history, and player roster.
See Tick.

​
Terms deliberately not used in Realm

The following words come up in similar games but are avoided in Realm — both to stay disciplined and because they imply mechanics that have been explicitly rejected.
TermWhy it’s avoided
QuestNo quests. The economy generates motivation; Realm does not script objectives.
LevelNo leveling. Skills exist on labor, but players have no “level.”
ClassNo classes. Players are entrepreneurs; their identity emerges from decisions.
Resource nodeUse plot + subsurface composition instead. “Node” implies a designer placed it; in Realm, world-gen produces it.
FactionNot in v1. Possible in a future phase if player governance becomes a feature.
PvPNo combat, ever. Use competition for economic rivalry.
GrindIf players say “this game has grind,” something’s wrong with the design. There should be no rote actions that aren’t decisions.
TutorialRealm has a guided first hour, not a tutorial. A tutorial teaches mechanics; the first hour introduces primitives via real play.

Development phases

The full phase-by-phase build plan with test gates for each stage.

Economic primitives

The 9 economic atoms that underpin every definition in this glossary.

Laws of the universe

The 10 engine-enforced rules referenced throughout these definitions.

User-code layer

Full reference for the Lua sandbox, service API, and block editor introduced in Phase 4.

Build docs developers (and LLMs) love

Get started for freeTalk to us