Skip to content
TAURION
A1About & Open Questions

About & Open Questions

How these docs were produced, and the open design questions.

Authoritative, source-cited documentation of Taurion, a fully on-chain RTS/ sandbox MMO on the Xaya platform (Polygon). Written for game designers and client developers building a new AAA UX. Start with the overview, then dive into the per-subsystem docs.

Ground truth. The Game State Processor (GSP) source (this repository) is the single source of truth for all game rules — the on-chain engine replays every move through this exact code. Every nontrivial rule, constant, fee and edge case in these docs is cited as file:line into the GSP source tree. The official web client supplies human display names and shows which APIs the UI consumes; the display names are the ones shown in the game UI, while codes are normative on-chain. Where the test files (*_tests.cpp) contain real move/state JSON examples, the docs quote them.

Index#

Doc What it covers
Game Overview Start here. End-to-end game explanation: core fantasy, the spawn→prospect→mine→haul→refine→build→craft→fight→trade loop, the faction system, a systems map, the full display-name↔code glossary (ores/materials/vehicles/buildings/fitments), and the player-actions master list.
Moves Reference The complete on-chain move protocol: every move type (vc/a/nc/c/b/s/x), processing order, validation, costs, plus god-mode admin commands. Exact JSON for each.
RPC & REST API The GSP JSON-RPC API: every read/long-poll/stateless method, the state envelope, error codes, and what the official web client actually calls. (There is no "submit move" RPC — moves go on-chain.)
Game State Schema The game-state JSON every getter returns: every entity (account, character, building, ground loot, ongoing, region, trade, money supply, prizes), every field, type, units, presence rules, with examples.
Items & Materials Complete item catalog: 9 ores, 9 materials, 4 artefacts, blueprints, the full 104-fitment catalog (codes, complexity, slot/size/faction locks, recipes, effects), prizes, refining/reveng/copy/construct rules, cargo space, costs/fees/burning.
Vehicles Complete vehicle catalog (36 vehicles): per-vehicle stats (cargo/speed/HP/regen/slots/mining/prospecting/complexity/target size), slot rules, how to obtain each, vehicle-swap and fitment moves.
Buildings Every building type and mechanic: data model, placement/founding, foundation→finished construction, the six services, the Rocket Turret, ancients/obelisks/common buildings, destruction & loot, enter/exit, owner config/transfer, spawn geography.
Prospecting & Mining The resource economy: regions, prospecting (entry, duration, resource detection, the 88-area distribution map, artefact drops, the finite prize lottery) and mining (rates, cargo limits, depletion, re-prospecting).
Combat The combat system: per-block aim/fire cycle, target selection, damage/hit-miss, shield vs armour, AoE, syphon/self-destruct, effects, mentecon, factions, stat modifiers, safe zones, death & loot, fame, HP regen, and the weapon/fitment combat catalog.
Services & Crafting The five building services & crafting ops (ref/fix/rve/cp/bld) + mobile refining: cost model (base burn + owner fee), move/RPC schemas, formulas, ongoing-op lifecycle, destruction-while-crafting risk.
Trading & the DEX The per-building order-book DEX: bids/asks/cancel/transfer, price units, escrow, matching engine (price-time priority, maker-price settlement), fees, trade history, destruction cleanup, and how clients query it.
Economy & Accounts The economy & account system: WCHI vs vCHI, accounts/identity, faction init, the burnsale (stages, rates, minting), vCHI sinks/flows, dev payments & character creation, fame, the GameStart fork, prizes, money-supply accounting.
Movement & the World Movement & the world map: hex coordinate system, map size/shape, static obstacles & edge weights, safe zones, dynamic obstacles, speed computation, waypoint encoding, per-block movement processing, blocked-step retries, building footprints/enter/exit.
Block Lifecycle The per-block game loop (UpdateState order) and the ongoing-operation system (prospecting, repair, copy, construct, building construction, config update), interruption on death, and the pending-state JSON for optimistic UI.
Building & Running a GSP Ops guide: how to build and run tauriond against live Polygon (XayaX bridge, ports, storage, RPC).

Note: Game Overview and this About & Open Questions page are the new "front door" docs. The numbered subsystem docs are the exhaustive references.

Open questions (consolidated)#

These are genuine ambiguities surfaced by reading the GSP source — points a designer or ops owner must resolve rather than guess. Collected from the "Open questions" section of every detail doc; the source doc is noted for each.

Deployment / consensus config#

  1. God-mode enabled in the checked-in mainnet config. params.pb.text:31 sets god_mode: true (commit 25e5ce1 "enable god mode"), so as-built the admin teleport/build/gift/sethp commands run on mainnet/Polygon, testnet and regtest. But GodModeDisabledTests asserts god mode is off on Chain::MAIN — so that test would fail against the current config. Whether the released mainnet binary disables god mode (e.g. via a build/CI override) is not determinable from source. Confirm with ops before relying on its absence. (01 Q1; 06 §12; 11 Q3; 13 Q3.)
  2. Provenance/authorisation of admin commands. The GSP gates god-mode by params.god_mode but does not itself restrict who may submit admin commands — that is the surrounding Xaya/GSP daemon's privileged channel. Document the admin command authorisation from the daemon layer. (01 Q3.)
  3. GameStart fork height on Polygon. Non-coin moves are gated on the GameStart fork (mainnet height stated as 80,528,098, src/forks.cpp:71). The activation parameters live in src/forks.* and deployment config; cross-check the precise live value. (01 Q4; 11 §7.)

Economy / currency#

  1. vCHI unit vs satoshi cap mismatch. MAX_COIN_AMOUNT (per-move cap, called "the total cap on vCHI") is 100,000,000,000 satoshi = 1,000 vCHI, but the burnsale sells 50,000,000,000 units added directly to balance — implying burnsale units are counted in the same satoshi denomination as balance (so the realised cap is 50e9 sat = 500 vCHI). The "total cap" comment appears stale. Confirm the intended human denomination (is 1 displayed "vCHI" = 1 satoshi-unit, or = 1 COIN?). (02 Q4 [Cubit unit scale]; 11 Q1.)
  2. TEST-ONLY vCHI airdrop on character creation. VCHI_AIRDROP = 1000 sat per new character is flagged FIXME: For the full game, remove this (src/moveprocessor.cpp:57,1366). Confirm whether it stays in the AAA relaunch economy or must be removed. (01 Q2; 11 Q2.)
  3. Airdrop/gift persistence at the full-game reset. Code comments say only burnsale_balance (minted) is "carried over to the full game"; the reset/ migration policy for non-burnsale balance (airdrops, gifts, the johnv5/etc. starter-inventory hack at src/logic.cpp:177-202) is unspecified. (11 Q2.)
  4. Where burnt vCHI is accounted. DEX base fee and service base costs are removed from the payer with no recipient (true sinks), but there is no "burnt" money-supply counter analogous to burnsale/gifted, so net circulating supply is not directly queryable via getmoneysupply. Also: the in-game burn is not routed to the on-chain burn_addr (that is for WCHI). Confirm whether the in-game burn should be tracked in moneysupply stats. (10 Q1; 11 Q5.)
  5. The cash prize tier. prizes: {name:"cash" number:10 probability:350000} sits inside the params{} block, has no display-name mapping in the official client, and is awarded only as a "cash prize" inventory item — its in-game effect/redemption (does it award vCHI?) is not implemented in the prospecting code. (07 Q4; 11 Q4.)

Items / crafting#

  1. Mobile Refinery blueprint origin. vhf refinery is with_blueprint: true (so a vhf refinery bpo can be constructed/copied) but is not in any artefact's reverse-engineering output list. How is the first vhf refinery bpo obtained on mainnet (prize, seeding, special distribution)? Not determinable from config. (04 Q2.)
  2. 42 non-reverse-engineerable fitment blueprints. Twelve fitment families (beam, gun, syphon, syphonaoe, allyreplenish, rangered, hitext, hitred, dmgred, armourregen — all tiers — plus vhf mentecon and vhf refinery) are blueprintable but never appear in any artefact's reveng list. Their bpo acquisition path (drop? prize? seeding?) is a design decision not encoded in the GSP. (04 Q3.)
  3. bp_copy_blocks / bp_copy_cost appear unused for copy timing. Blueprint- copy duration uses construction_blocks × complexity (GetBpCopyBlocks, services.cpp:739-751), not the dedicated bp_copy_blocks param. Confirm whether bp_copy_blocks/bp_copy_cost are live tuning knobs or dead config. (09 Q1; 13 Q1.)
  4. Original-blueprint dispersal timing for multi-item builds. Building from an original debits the bpo by 1 and the ongoing handler re-credits it on completion; the net "originals are reusable" is confirmed by design intent, but the exact block-by-block inventory timing for serial multi-item original builds was traced via comments, not the full ongoings.cpp path in the vehicle doc. (05 Q1.)
  5. raw f display/icon name mismatch. The official client shows the display name "Voltar" for raw f but uses an icon asset named for "Voltan". Which spelling is canonical for new UI? (04 Q1.)
  6. Refining yield "loss" intent. Refining 10,000 ore yields far fewer total material units (intentional mass-loss / sink). The intended sink rate per ore is a design parameter worth confirming against the economy model. (04 Q5.)
  7. Mobile-refinery cargo-overflow invariant. The "refining never overflows cargo" guarantee relies on every refined output being strictly smaller in total space than its input — an implicit config invariant, not a runtime check. Flag if new ores/materials are added. (09 Q3.)
  8. Cargo-space display scaling. Vehicle cargo_space values are raw proto integers (e.g. 3,600,000) and ores/materials cost space: 1/unit; the intended display scaling of the large numbers is a client choice not fixed by the GSP. (03 Q3; 04 Q4.)

Combat / state representation#

  1. combat sub-field coverage in state JSON. The serializer exposes only range/area/friendlies/damage.{min,max} for attacks and omits proto fields (armour_percent, shield_percent, weapon_size, effects, gain_hp, low_hp_boosts, self_destructs, received_damage_modifier, hit_chance_modifier, target_size). Whether a new AAA UX needs these surfaced is a design decision. (03 Q2.)
  2. target_size/weapon_size derivation. Combat math fully consumes these integers, but the mapping from VehicleSize/fitment tier to the numeric target_size/weapon_size lives in src/fitments.cpp, not the combat code. Designers should consult the fitments/vehicles derivation for concrete per-class numbers. (08 Q1.)
  3. Fame-split divisor counts all killers (incl. out-of-range). fame.cpp divides fameLost by the count of all distinct killer accounts but only credits in-range ones, so out-of-range participants dilute the reward. The code is unambiguous; whether this is the intended design is a balance question. (08 Q2.)
  4. getserviceinfo output for non-deterministic ops. Reverse-engineering and prize outcomes are random at execution; the preview's output semantics (expected vs max) for reveng were not exhaustively traced. (02 Q1.)

World / map#

  1. Exact mainnet region count & region geometry. The region count and per- region tile footprints are embedded in regiondata.dat (logged at generation, procmap.cpp:598), not source constants — "hundreds of thousands" of regions, but the precise figure and shape need the map-generation tooling run against the shipped blob. (07 Q1, Q2; 03 Q1 [region.id width].)
  2. Exact map silhouette (minX[]/maxX[] per row) and obstacle bitmap. Only the bounding box (Y∈[-4096,4095], X∈[-4096,4095] at the centre row) is verifiable from source; the full per-row bounds live in the compiled obstacledata.dat blob. (12 Q1.)
  3. Per-building production-service mapping for c1–c11. Each common ancient- city building offers armour_repair + one production service, but the exact pairing per index/faction is per-file; a full UI needs each <faction>_c<N>.pb.text read directly. (06 appendix §13; 09 Q2.)
  4. ancient1/2/3 and ss (City) types defined but never placed. They have full all-service configs and large footprints but appear in neither initialbuildings.pb.text nor any GSP code path — likely dead/legacy config or intended for admin placement. (06 Q1; 09 references same types.)
  5. Client-only building model codes (sf/ep/et). These map to GLB models in the client but have no GSP building type, so they render nothing in the live game — presumably future/cut content. (06 Q3.)
  6. Real block time → wall-clock conversion. All durations are in blocks; the wall-clock mapping depends on Polygon block cadence and GSP confirmation depth, outside the reviewed rule source. (07 Q3.)
  7. No-combat (partner) zone movement semantics. Confirmed from code that no-combat zones affect combat and building placement but not movement edge weight (only faction starter zones do) — flagged only because the name "safe zone" might wrongly suggest a movement effect. (12 Q3.)
  8. Any speed-affecting item beyond turbo/retarder. A scan found only the turbo line (positive base-speed modifier) and retarder/longretard (negative combat-effect speed); no other speed items were found but this was not exhaustively cross-checked against every fungible item. (12 Q4.)

Client integration (not GSP ambiguities, but flagged for client devs)#

  1. Client dex wrapper vs GSP x move key. The official client builds a data: { dex: [...] } wrapper (marked as a stub), but the on-chain DEX move key is "x". The translation from the client wrapper to the emitted "x" move was not located; client devs should confirm the final move uses "x". (10 Q2.)
  2. Incomplete client surfaces. The market UI is a placeholder and several RPCs are stubbed client-side (getMoneySupply, getPrizeStats, getTradeHistory, setPathData) — the GSP fully implements them server-side; a new client should wire them up. (02 §6.3; 10 Q3.)
  3. Order ID stability. Orders share the global entity-ID counter and IDs are never reused after deletion (monotonic); trade-history rows use a separate log-ID counter. Safe to use as stable references. (10 Q4.)

UX-direction notes pending: a separate write-up of the owner's UX direction was referenced but is not yet part of these docs at the time of writing. If/when those notes are added, fold their direction into the overview and link them here.