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.

A primitive is an economic atom: an entity, resource, or capability that the simulation engine understands natively. The engine does not know what a “shipping company” is. It knows about plots, vessels (which are matter combined with capital), labor, movement, and contracts. A shipping company is what emerges when a player composes those together. Your job is to understand the primitives well enough that you can compose anything you want to build from them. There are 9 primitives in v1. Every legitimate business idea in Realm must be expressible as a composition of these nine. If you find one that is not, the primitive set is incomplete.
If a business idea cannot be expressed using these 9 primitives, the primitive set is incomplete — fix the primitives, don’t add a special case.

​
The nine primitives

Definition: A bounded region of the world with physical properties. Players claim plots; plots are property; plots are tradeable.Intrinsic properties (set at world generation, never change):
  • Coordinates (x, y on the world grid)
  • Area (some plots are larger than others)
  • Terrain type: plains, forest, mountain, desert, tundra, swamp, water-shallow, or water-deep
  • Climate (temperature, rainfall, seasonality)
  • Coastal access (yes/no; harbor depth if applicable)
  • Altitude
  • Hidden subsurface composition — what materials actually lie beneath the surface, invisible until prospected
Derived properties (change over time):
  • Owner (player ID or unclaimed)
  • Improvements built on it (buildings, infrastructure, hosted code services)
  • Known surveys (what has been discovered about the subsurface)
  • Current usage (what is being produced, extracted, or operated here)
What you can do:
  • Claim an unclaimed plot, subject to availability rules per game mode
  • Sell or transfer a plot to another player
  • Lease a plot for a set duration at a negotiated price
  • Build on a plot
  • Survey a plot (costs time and money; reveals subsurface composition)
Why subsurface is hidden: Resources do not exist as designer-declared facts. World generation produces a hidden composition map. A plot might have heavy iron content, light copper content, and a small oil pocket — but until someone surveys it, nobody knows, including the owner. This makes prospecting a real economic activity and creates information markets around survey data.
Definition: Physical stuff. Has properties. Conserved. Cannot be created from nothing.Properties of every material:
  • Material ID (assigned by the world; players can name it)
  • Physical properties: mass, density, melting point, conductivity, caloric value, durability, and other attributes tracked on a fixed engine schema
  • Quantity (units exist, are owned, and can be moved)
  • Location (material is always somewhere — a plot, a vehicle, a warehouse)
v1 design decision: Realm uses approximately 25 pre-defined real-world materials with realistic properties. This is the faster-to-ship, more intuitive approach. A future expansion may move to fully generic materials where players discover what attribute combinations are useful — but that complexity is out of scope for v1.What you can do:
  • Extract material from a plot, if the subsurface contains it and you have extraction infrastructure in place
  • Transform material via production (combine materials, labor, and energy into new materials — see Primitive 6)
  • Move material between locations (takes real time — see Primitive 4)
  • Trade material with other players (see Primitive 7)
  • Store material in warehouses on your plots
  • Destroy material (rare — fire, decay; see Law 5)
The conservation rule: Material never appears or disappears outside of these defined channels. Every unit of iron in the economy came from a plot and traveled a physical path to reach its current location.
Definition: Time-bounded capacity to do work. Comes from players themselves, hired NPCs, or AI agents in solo mode.Properties of every labor unit:
  • Skill levels (extraction efficiency, production quality, negotiation, surveying, and others)
  • Loyalty / morale (affects reliability and output quality)
  • Wage (cost per unit of game-time)
  • Location (labor must physically be where the work is)
Three sources of labor:
  1. Your own time. You are a labor unit. Your hours played are the most valuable input you have — you make decisions that NPCs cannot.
  2. Hired NPC labor. Generic workers recruitable in populated areas. They cost wages, have skill levels, and can quit if mistreated.
  3. AI agent labor (solo mode only). AI agents can be employed by other AI agents or by you directly.
Labor is not infinite. Populated regions have larger labor pools. Frontier plots must import labor at real cost — which makes geography matter for workforce planning, not just logistics.What you can do:
  • Post a job, set wages, and receive applicants who accept or reject
  • Assign labor to specific tasks on your plots
  • Train labor to raise skill levels (costs time and money)
  • Fire labor (subject to employment contract terms)
  • Work for other players as paid labor yourself
Definition: Things take time. Goods take time to move. Distance is real and has economic cost.Properties:
  • World tick: the smallest unit of simulation time
  • Movement speed: depends on transport mode and cargo
  • Travel routes: paths between locations, which may have toll or permission requirements
Movement cost (approximate):
cost = base_rate × distance × (1 + load_factor) × terrain_modifier
time = distance / speed × terrain_modifier
Speed depends on the transport asset. A coastal vessel is fast over water but cannot operate inland. A truck is slower but flexible across terrain types.Goods in transit exist in a distinct state: visible to the owner, but unusable and unsellable until they arrive at their destination.What you can do:
  • Move goods, labor, and money between locations
  • Build or purchase transport assets (vessels, vehicles)
  • Sell transport services to other players — this is the core of a shipping company
  • Plan routes and optimize for cost versus speed
Time is the universal currency. Energy and labor convert into time saved or time required. The strategic depth in Realm comes almost entirely from time being a real, irrecoverable cost.
Definition: A medium of exchange, tracked on accounts. Can be earned, spent, loaned, and lost — but not created outside designed channels.v1 design: A single in-game currency, issued by the simulation as a starting grant per player and via scheduled NPC seed transactions. No player can print currency. No code path can create money outside designed mechanisms.v2+ design: Player-issued currencies — a player declares “I issue Avi-Coin, redeemable for X” and other players choose whether to accept it. A foreign exchange market emerges. This is intentionally deferred from v1 because it makes the simulation significantly harder to keep tractable.Properties of every account:
  • Owner (player ID or business ID)
  • Balance
  • Transaction history (visible to the owner; partially visible to the public for registered businesses)
What you can do:
  • Send money to another account
  • Receive money from any source
  • Take loans (via Primitive 8 — Contracts)
  • Issue stock or bonds in later phases (via Contracts and the financial layer)
  • Hold capital in different forms: cash, on-deposit, invested in inventory, or invested in plots
The single most important rule: Money cannot be created or destroyed except through designed channels. This must be enforced at the data layer, not at the application layer. See Law 1 for the engine-level enforcement detail.
Definition: A process that consumes inputs — matter, labor, energy, money — at a location over time, and produces outputs in the form of matter or services.Properties of a production process:
  • Recipe: what inputs produce what outputs at what rate. You define your own recipes by configuring buildings and equipment, within physical-law constraints. The engine validates mass balance and energy balance — inputs must account for all outputs, including waste.
  • Throughput: the rate at which the process runs
  • Efficiency: affected by labor skill levels, equipment quality, and plot conditions
v1 simplification: The engine ships a library of pre-built recipe templates for common production processes. You unlock these templates by building the right equipment. The library is generative rather than curated: anything that satisfies mass balance and energy balance is a valid recipe. The hand-authored templates simply give you a starting point.What you can do:
  • Operate production on any plot you own or lease
  • Configure recipes within physical-law constraints
  • Scale throughput by adding more equipment
  • Optimize efficiency by training or hiring higher-skilled labor
Why production is a primitive and not a sub-category of matter: Production is the engine’s core transformation layer. Without it, matter can only be extracted and traded — it cannot be refined, manufactured, or combined. Production is what creates value chains.
Definition: Mechanisms by which players exchange goods, services, and capital. Two distinct layers exist.7a. Direct P2P exchange: Two players agree on a transfer. “I give you 100 iron for $500.” The transaction is atomic, mutual, and one-shot. No intermediary. No order book.7b. Order books / exchanges: Where there is enough volume in a good or asset, an open order book emerges. Buy and sell orders are public. Any player can place an order. The exchange engine matches them automatically.v1 design: Both 7a and 7b exist from day one. An order book opens automatically for any commodity that hits a volume threshold — for example, five distinct sellers active in the past 30 game-days. Below that threshold, you use direct P2P trades.Properties of an order book:
  • Asset being traded (a material, a service, an equity share)
  • Current bids and asks, each with price, quantity, and delivery location
  • Last trade price
  • Volume and depth
What you can do:
  • Post limit orders (bids to buy, asks to sell)
  • Take existing orders at market price
  • View the public order book (with an optional information-cost delay if that setting is enabled)
  • Trade privately via P2P off-book, with non-standard negotiated terms
  • Build market-making businesses that provide liquidity and earn the spread
Definition: Multi-step, multi-condition agreements between parties, enforced by the engine itself.This is the most important non-obvious primitive. Real economies do not run on instant spot trades — they run on long-term commitments. Without first-class contracts, players would reinvent them poorly using informal promises and reputation alone.A contract has:
  • Parties: who is involved — players, businesses, or the engine acting as counterparty
  • Triggers: when each clause activates — on a time schedule, on an event, or when a threshold is crossed
  • Obligations: what must happen — pay, deliver, perform a service
  • Penalties: what happens on breach — forfeit collateral, lose access, pay damages
  • Duration and termination conditions
Five built-in contract templates:
  • Supply contract: “Party A delivers 100 iron to Party B’s plot every 7 game-days for 12 weeks. Party B pays Xperdelivery.Penaltyfornon−delivery:X per delivery. Penalty for non-delivery: Y. Penalty for non-payment: lose access to the next delivery.”
  • Loan contract: “Party A receives 1,000fromPartyB.PartyApays1,000 from Party B. Party A pays 50 in interest every 30 game-days for 12 months, then returns principal. Penalty for default: forfeit collateral plot to Party B.”
  • Employment contract: “Worker performs labor at the hiring party’s plot for $W per game-day for 90 days. Either side may terminate with 7 days’ notice.”
  • Equity contract: “Investor pays $X for Y% ownership of the business. Investor receives Y% of declared profits.”
  • Service subscription: “Customer pays $S per month. The provider’s code service runs on the customer’s account.”
Key design rule: Contracts are templates plus parameters, not free-form code. The engine ships the templates; you parameterize them. Building new templates is initially a designer-only activity; later phases will expose template creation to advanced players.What you can do:
  • Propose a contract to any counterparty
  • Accept, reject, or counter-propose terms
  • Monitor all of your active contracts
  • Breach a contract (triggering the penalty clauses) or honor it
  • View the public contract history of any counterparty as part of their reputation surface
Definition: Player-written logic that runs on the engine, can be invoked by other players or by other code, and can be sold as a service.This is the moat primitive. No other game in this genre has it, and it is the most complex to build correctly.v1 design:
  • A sandboxed scripting environment in Lua, with a visual block-based interface for players who prefer not to write code (which compiles to Lua under the hood)
  • Code can read public game state: prices, plot data, public contract terms
  • Code can read private state that belongs to the player who deployed it: their inventory, their accounts
  • Code cannot read another player’s private state, ever
  • Code can take actions on behalf of the deploying player: place orders, propose contracts, send messages
  • Code consumes computational resources (a CPU and memory budget per tick) — you pay for this in in-game currency
Services that can emerge:
  • Auto-restock: “When my inventory of iron drops below X, automatically place a buy order at market price.”
  • Trading bot: “Watch this commodity. Buy when the 7-day moving average crosses the 30-day moving average. Sell on the opposite cross.”
  • Logistics optimizer: “Given a list of deliveries, compute the cheapest route.” Sold as a SaaS to shipping companies.
  • Market data aggregator: “A public dashboard of all commodity prices across all exchanges. Subscription fee for premium analytics.”
  • Credit scorer: “Given a counterparty ID, return a credit score based on their public contract history.” Lenders pay per query.
  • Game inside the game: A player-built betting market on event outcomes.
What you can do:
  • Write code in the in-game IDE
  • Deploy code so it becomes a live service running on your account
  • Set pricing: subscription, per-call, or free
  • Subscribe to or call other players’ services
  • View usage metrics for your own services
  • Update, version, or retire your services
Constraints:
  • Code must be deterministic given its inputs (no true randomness — randomness comes from a tick-stamped seed for reproducibility)
  • Code has a CPU budget per tick; exceeding it throttles the service or triggers premium charges
  • Code cannot create money, materials, or labor from nothing
  • Code cannot read other players’ private state
  • Code cannot impersonate other players

​
Composing primitives into businesses

The test of whether the primitive set is complete is whether you can compose any legitimate business from these nine. Here are three worked examples.
A shipping company needs physical infrastructure, transport capacity, labor, and ongoing agreements with customers.
PrimitiveRole
PlotsCoastal warehouses and dock facilities
CapitalInitial funds to purchase vessels
MatterThe vessels themselves — physical assets with high transport speed
LaborCaptains, dockworkers, dispatchers
MovementThe core service being sold — moving other players’ goods across the map
ContractsSupply agreements with shippers; employment contracts with crew
Code (optional)Route optimization, automated dispatching, customer billing
Revenue comes from per-shipment fees or long-term supply contracts with cargo owners. As the business grows, you invest in more vessels, better-skilled captains, and code that reduces manual dispatch overhead.
If all three of these compose cleanly from the 9 primitives — and they do — the primitive set is working. If you ever find a business idea that cannot be expressed this way, that is a signal that a primitive is missing, not a signal to add a game-mode-specific special case.

Design pillars

The 7 non-negotiable principles behind every design decision.

Laws of the universe

The 10 engine-enforced rules that keep the economy honest.

Build docs developers (and LLMs) love

Get started for freeTalk to us