GAME OF CORES/ Faction API

Rust 2021 · WebAssembly · CPU RTS

Faction API

Runtime callbacks, observation fields, order payloads and SDK functions for faction programs.

Prices and limits come from the active world. Each section links to its source contract. SDK signatures are generated from the repository reference.

Logistics epochs expose world.logistics. Miners produce physical cargo and unload at local town depots. Only arrival at the receiving faction’s capital town credits CPU. The guaranteed floor remains available.

Town and dock inventories are separate. Ground carriers join them; hulls ship between owned docks. Read the active capacities and rates in world.logistics.rules. Loaded ground carriers cannot row, fly or use gates.

Unit orderBehavior
cargo: {load: {p,dock}, amount?} / cargo: {unload: {p,dock}, amount?}Standing transfer at an owned endpoint within reach. Amount is cycles; omission fills or empties the hold. Ground movement is explicit.
dock: pNavigate a hull to the owned coastal anchorage. Combine with a cargo job to transfer on arrival.
cargo: {salvage: wreckId, amount?}Recover a visible wreck after approaching. Income still requires delivery to your own capital.
cargo: {embark: shipId, port: p} / cargo: {disembark: p}Transfer a ground passenger at an owned dock. Passengers share hull capacity with cargo and aircraft.
cargo: nullCancel the job. A new movement order also cancels the previous job; it may include a replacement cargo operation.
u.rts.cargo / me.rts.logisticsOwners see exact holds, jobs, depots and visible wrecks. Spectators and visible rivals receive coarse load and active transfer states.

Energy epochs expose world.energy and me.energy. Every mined core draws power, and a province yields only the share of its draw its grid meets. Dark cores still count toward the Crown.

Plants and batteries are structure ports with a capacity. Each island of a faction’s grid balances once a second: a surplus charges batteries; a shortfall drains them to the reserve, burns boiler cargo, then darkens the shed provinces first.

Order or fieldBehavior
structures: [{…, ports: [{kind, capacity}]}]Build a plant: solar, boiler, wind, hydro, tidal, geo, reactor, fusion or battery. Each kind’s research, quote, capacity range and output are in world.energy.kinds.
grid: {shed: [p,…], reserve}Provinces to darken first in a shortfall, in order; MW·s the batteries keep back. An omitted field keeps its value.
give: {power: {mw, seconds}}Sell power in a deal: 0.1 to 100 MW. The giver needs transmission and an island bordering the taker’s.
me.energyLast second’s supply, demand, met, powered, batteries, islands, plants and deals.
world.energy / p.powerThe sun, wind fronts and tide, with their formulas; each province’s sun, wind, tide and free room for hydro, tidal, geothermal and reactors.

A faction program is one Rust 2021 source file. The server compiles it for wasm32-unknown-unknown with std and the gameofcores SDK.

Register callbacks with program!. Each invocation starts in a fresh WebAssembly instance. Persistent state belongs in game RAM.

This reference describes CPU RTS behavior. Read the active world’s rules before selecting capabilities, limits or prices.

rust
use gameofcores::*;

program!(think, miner, reflex, research, duel, look);
// Define each callback named above. Every other registered name is a unit type,
// except the reserved names challenge, build3d, live3d and work.
PropertyContract
SourceInclude a line beginning with use gameofcores. Source size is limited by limits.sourceBytes. Modules must be inline. Only the shipped libraries are available. File inclusion is unavailable.
ArgumentsUp to four View arguments. Trailing arguments may be omitted. Views remain valid for the invocation.
Return valueAny type implementing Into<Value>, including (). think returns a faction order object. Unit controllers may return orders or commit them with order().
ExecutionCode and memory are metered using rules.wasm. cycles_left() reports remaining budget. Files, network access, clocks and threads are unavailable.
PersistenceStatics, heap data and thread-local values reset on each call. Use mem, plan and RAM operations for state that survives.
Numeric valuesObservation numbers and IDs use f64. Missing keys and indices return an undefined View.
VisibilityThe engine supplies a faction-specific observation. Player source, diagnostics, plans and messages remain private to its seat.

Only registered callbacks are invoked. think is required. Unit type identity is its function name; renaming a controller creates a new type.

SignatureInput and outputInvocation
fn think(world: View, me: View) -> ValueReceives the faction observation. Returns a faction order object.Once per simulation second, subject to budget.
fn miner(units: View, world: View, me: View, why: View)Example controller name. Receives a batch of its units. Returns unit orders or calls order().According to compute.types, unit events and timers.
fn reflex(units: View, near: View) -> Vec<Value>Receives units in contact and nearby contacts keyed by unit ID. Returns {id, hit}, {id, step} or {id, hold}.While units are in contact, subject to the active cadence and budget.
fn research(puzzle: View) -> ValueReceives a research puzzle. Returns its answer.When the research target and savings permit an attempt.
fn duel(puzzle: View) -> ValueReceives a combat puzzle. Returns its answer.During a code duel, subject to budget.
fn challenge(foe: View, max: View) -> ValueReturns a puzzle secret within max, or Value::Null for an engine-selected puzzle.When the faction throws a puzzle.
fn look(budget: View, info: View) -> ValueReturns faction appearance, unit styles, names and related assets.When code goes live and when the render budget grows.
fn build3d(budget: View, info: View) -> ValueReturns the capital scene.On deployment and applicable scene or budget changes.
fn live3d(state: View, now: View) -> ValueReturns {state, set, clear} for capital animation.Once per second while the capital stands, subject to budget.

View reads input in place. Value owns data used to build output. Copy only values the program must retain or modify within the call.

OperationBehavior
view.get(key), view.at(index), view.path(path), view.key(id)Access an object member, array item, dotted path or numeric object key. Missing entries yield an undefined view.
view.num(), view.num_or(default), view.int()Read a number. num() returns NaN for a non-number; num_or returns the supplied default.
view.str(), view.bytes(), view.truthy()Read a string, byte sequence or truth value. str() returns an empty string for a non-string.
view.iter(), view.entries(), view.keys()Iterate an array or object. Use len() and is_empty() for its size.
view.exists(), view.is_nullish(), view.is_num(), view.is_arr(), view.is_obj()Check presence and type before interpreting optional data.
view.value()Copy an input into an owned Value. The copy costs instructions.
obj! { "key" => value }, arr![value, ...]Construct an object or array. Rust numbers, strings, booleans, vectors, options, points and views convert into Value.
value.set(key, value), value.entry(key), value.push(value)Build or change a result. Undefined containers become objects or arrays as needed.
value.to_json(), Value::parse(text)Serialize or parse JSON. Undefined object fields are omitted; non-finite numbers become null; bytes use {"$b":"<base64>"}.

think(world, me) receives the broad faction observation. Province geography is public. Ownership and economic data may be missing or stale under fog.

Unit controllers receive their units and a restricted observation. world.units is omitted. Capital RAM and spoils are replaced by province and spied RAM.

Controllers also omit the faction’s own public statements, archive and timers. Share controller inputs through RAM; send carried plans with units leaving friendly land.

PathShape / meaning
world.tick, world.secondsSimulation tick and elapsed simulation seconds.
world.provinces[]{id, name, adj, routes, x, y, terrain, height, map, visible, ...}. IDs identify provinces; route entries describe researched crossings.
world.provinces[].owner, .seenAgoLast observed owner and age of the observation in seconds. Owner -1 means free land; undefined means never observed.
world.provinces[].mines, .shared, .leasedMine slot yields, joint owners and leases. Check the current worker rights before issuing gather orders.
world.provinces[].units, .siegeVisible faction counts and siege state. Own provinces additionally expose loyalty, policy and mining staff.
world.provinces[].garrison, .townGarrisonPresent on visible provinces. garrison counts the owner’s units across the province. townGarrison counts individually visible, grounded, non-stealth owner units in the capture ring. Hidden units and other factions are excluded. Use current combat observations when planning a siege.
world.units[]Own units in full plus visible allied and rival units with restricted fields. Available to think; omitted from controllers.
world.techs{id: {name, tier, need, requires, does, ...}}. Use these IDs for research and capability checks.
world.factions[], world.pacts[], world.crownFaction summaries, signed pacts and the current win condition. Read thresholds from this observation.
world.computeWorld CPU budget, core yield, bank rules and price level. Present in CPU RTS.
me.id, .capital, .provinces, .bank, .techsFaction identity, holdings, currency balance and unlocked techs. me.bank is ◆; me.rts.cpu.bank is CPU.
me.unitsRoster totals, type counts, standing jobs, spawn queue, allowance, current maximum and upkeep rate.
me.acceptLocalsPrivate standing recruitment choice. Present as false when automatic locals are declined; omitted when enabled.
me.rts.cpu, me.rts.costsPrivate CPU balances, policy and spending; prices scaled for this world.
me.ramCapitalCapital RAM visible to think. Persistent planning state is stored here.
me.ramProvince, me.ramSpied, u.ramUnitController memory sources: province pages, spied pages and carried unit pages.
me.inbox, me.contracts, me.research, me.refusedPrivate messages, contracts, research state and recently refused orders. Refusals contain {t, why}.
why, u.whyController reason: tick, event or timer. Event units report reasons such as idle, attacked or revealed.
u.localReflex-only {p,x,y} in the current province frame, shared by near offsets, hazards and shell aims.
u.terrain[]Ground reflex directions {x,y,walk,cover} sampled half a cell and one cell ahead. Zero walk means blocked; cover multiplies ranged damage. Air and sea units omit this array.
u.coverOwn units only: {by, secondsLeft} while protected on a host’s land. Omitted without active cover. Lease, hire, passage and toll protection can grant cover. Avoid attacks on the named host while it lasts.
u.rts.driveScalePrivate ground body multiplier on drive charges. Speed 2 pays 1×, speed 3 pays 1.5625×, speed 4 pays 2.25×.
near[id][].reachVisible contact’s attack reach, in cells, including naval reach modifiers. Present in reflex observations.
u.rts.readyIn, .windupIn, .windupTargetCPU RTS private weapon state: seconds until ready, seconds until release, and pending target ID or null. Preserve that target through the windup.

think returns an object with optional fields. The engine validates each order and reports refusals in the private console and me.refused.

FieldPayload / effect
spawn[{type, name?, build?, modules?}]. Fabricate units for registered controllers. Body limits, research, capacity, currency and CPU checks apply.
acceptLocalsBoolean, default true. Persistently enable or decline automatic local recruitment in either ruleset. false prevents conquest militia and uncontrolled units joining with territory. Land still transfers; explicit spawns, hires and deliberate persuasion retain their usual checks. Non-booleans are refused.
disband[unitId, ...]. Retire owned units. Hired units cannot be disbanded.
ramRAM operations on capital pages. Use mem::put or plan::share to construct them.
compute.cpu{limits?, reserve?, upkeepOrder?, upkeepUnits?}. Replace the CPU policy atomically. See CPU policy below.
compute.typesController allocation and cadence by registered type. Entries can specify share, cycles and every.
researchA tech ID from world.techs, or null to pause. Requires its prerequisites and a registered solver to complete puzzles.
rent◆ per second allocated to rented cycles, within the current rules.
policy, provincesFaction policy and per-province overrides. Policy fields include extraction, autonomy, integrate and invest.
send[{to, body?, give?, ask?, pact?}]. Send private messages, trade offers or pact invitations.
accept, reject, leave, cancelLists of message, pact or contract IDs for the corresponding operation.
inboxRequested inbox capacity in pages, within the current limits.
toll, payTollsStanding tolls [{province, coin}] and a boolean controlling payment of others’ tolls.
bribe, propaganda, faith, preachPolitical actions subject to reach, capability and cost. SDK helpers are listed under sway.
wake{at, note?, type?} or a list of timers. at is a simulation second. {cancel: note} removes a named timer.
cosmetics◆ moved into the appearance budget. The transfer is one-way.
memoPublic faction text, within the current length limit. It is visible to spectators.

Controllers issue orders for their own units. An unchanged or absent order preserves the standing job. think does not directly move units.

json
{"id":17,"do":"gather","target":4,"slot":0,"via":[2,4]}
rust
// Inside a registered controller; the shared plan must contain open mines.
for u in units.iter() {
    order(orders::gather(u, world, me));
}
Field / resultContract
idThe unit receiving the order.
dogather, fight, capture, persuade, raid, study, move or idle. Each verb has body, target and capability restrictions.
target, slot, viaTarget province, optional mine slot and explicit province route. Each route hop must be legal. Without a route, the target must be one step away.
at{x, y} or a list of local waypoints. Coordinates use cells east and north of the target province’s town.
focus, alertPersistent weapon target ID and the distance that triggers contact handling. Visibility and reach still apply.
ramRAM operations for the unit or its current province. {id, ram} can write memory without changing its job.
powerCPU RTS drive, armor and weapon allocations. Limits, modules and recurring charges apply.
ability, aim, radius, amount, repairTargetParameters for paid abilities such as artillery shells and repair. Check current capability, geometry, budget and cooldown.
cloak, pierce, guard, deploy, landCPU RTS controls for cloak, armor penetration, directional armor, artillery setup and landing.
{id, hit}Reflex result: select a visible target for the next strike. Combine with step to fire while moving. Reach and visibility are checked again at release.
{id, step: {x, y}}Reflex result: step in a local direction until the next reflex invocation.
{id, hold: true}Reflex result: remain still until the next invocation.
  • order() commits immediately. Returned orders are lost if the call fails before returning. An over-budget final memory-page fee can invalidate even committed orders.
  • Winged bodies cannot gather, capture, persuade or study. Landing preserves their wings. Hulls retain water movement across controller changes.

CPU RTS uses one bank per faction. Code execution and priced actions debit that bank. Code lanes also share a per-second burst cap.

Read me.rts.cpu for current balances and policy. Read me.rts.costs for prices at the current world’s price level.

json
{
  "compute": {
    "cpu": {
      "limits": {"think": 0.3, "control": 22000, "reflex": 30000},
      "reserve": {"think": 3000},
      "upkeepOrder": ["miner", "guard"]
    },
    "types": {"miner": {"share": 1.0, "every": 1}}
  }
}
Field / ruleSemantics
limitsAggregate lane spending caps per faction simulation second. Values from 0 through 1 are fractions of income; values above 1 are cycle counts.
reserveProtect a lane’s remaining reserve from other lanes. The lane can consume its own reserve. Excessive reserves can block production.
upkeepOrderType priority after upkeepUnits. Named types precede unnamed types; ties use oldest unit IDs. Omission clears the previous list.
upkeepUnitsUp to 32 distinct non-negative safe integer unit IDs, paid before type priority in the listed order. Missing and foreign IDs are ignored. Omission clears the list.
Policy replacementEach compute.cpu object replaces the previous policy. Omitted limits, reserves and priority lists clear. An invalid policy preserves the old policy and emits a diagnostic.
Omitted limitsLanes may spend unprotected balance. Research instead uses its configured default savings rate.
compute.typesAllocations share the available control allowance. every: 0 requests event-driven controller calls.
income, bank, capacityCurrent income, CPU balance and bank capacity in me.rts.cpu.
spendCap, burst, availableCode execution cap, remaining code allowance and lane allowances. Prices such as fabrication and upkeep are outside the code cap.
spent, last, totalCurrent, previous-second and cumulative CPU spending. Observations precede the callback’s own execution bill.
Classic fieldscompute.units and compute.research are ignored in CPU RTS. Use compute.cpu and compute.types.
  • The values above illustrate the payload. Size a policy from current observations. An unused lane cap does not reserve money.
  • A failed think cannot apply the policy it intended to return. Leave enough think budget to finish before attempting to change it.

Select an ID from world.techs with orders.research. The research callback must return a correct answer to each offered puzzle.

CPU RTS accumulates research savings within the lane allowance. A puzzle offer limits one attempt’s execution budget; it is not the total cost of the tech.

Input / functionContract
world.techs[id]Current prerequisites, tier, required solves, offer and effect. Capability IDs such as extraction, ranged and seaTraversal are used directly by faction code.
me.techs[id]Whether the faction has unlocked the capability.
me.researchSelected tech, progress, savings and last attempt’s result.
research(puzzle), duel(puzzle)Return the answer shape required by the puzzle. Solver code consumes its callback budget.
challenge(foe, max)Return a legal puzzle secret or null for the engine default.
hash(a, b), mulmod(a, b, modulus)SDK primitives used by puzzle checking. The SDK does not provide a complete solver. Public default code includes solver examples.
FailureResult / diagnostic
Compilationvalidate returns ok: false, stage: "compile", error and the first error’s line. A rejected deployment does not consume its deploy.
Missing thinkThe program is refused with program must define think.
Panic, stack or memory exhaustionThe call stops. Read the private console. A panic inside an SDK helper may report an SDK line.
Execution budget exhaustedThe unfinished return value is lost. Earlier unit orders committed by order() survive ordinary execution failure.
Final memory-page fee exceeds budgetThe call is over budget, including its committed orders. cycles_left() accounts for held memory.
Invalid orderThe engine skips it and records a private diagnostic. Inspect me.refused and stop resending the invalid request.
CPU or prerequisite unavailableAn action may be refused despite a nonzero total bank. Check lane limits, reserves, burst, modules, research, cooldown and geometry.
Running program healthstatus.programHealth.think reports not_run, within_budget or out_of_cycles, with usage and duration. Read console for runtime errors even when the budget state is within_budget.

MCP tools manage source and inspect a seat. Runtime callbacks execute inside the faction sandbox. Call MCP tools/list for the current server’s tool schemas and permissions.

ToolOperation
docsRead the guide, current rules, runtime contract, SDK and public default source.
get_sourceRead source available to the caller. A held seat exposes its own private program.
validateCompile and dry-run the exact source.
simulateRun source in a bounded practice world against house programs. Record the returned duration, seed and rules.
trialTest source for a held seat. Use the server’s current schema and limits.
deployValidate and queue source for the held faction. Code goes live at a deploy window, then propagates from the capital.
status, observeRead the running version, private program health and the faction’s current observation.
console, internals, messagesInspect private runtime diagnostics, decision state and messages for the caller’s seat.
waitWait for selected events or health conditions. Use the returned sequence to continue.
  • Validation and simulation require sign-in. Live deployment requires a seat. Inspect the current price and receive authorization before spending credits.
  • A queued deploy is not the running version. Check status after the deploy window.

This authored CPU RTS program publishes a mining plan, spawns miners and commits gather orders. It ranks an expansion target but does not send an army.

The program has no combat reflex or puzzle solvers. The public default program provides those components for live deployment.

rust
// A small teaching program for CPU RTS. It mines and chooses an expansion target.
// It has no combat reflex or puzzle solvers. Start live play from the public default program.
use gameofcores::*;

const WORK: bool = true;
const RICH: bool = true;
const CONTROL_LIMIT: f64 = 0.45;

// lesson:callbacks
program!(think, miner);

fn think(world: View, me: View) -> Value {
    let mut orders = Value::obj();
    // lesson:expansion
    let target = realm::rank(world, me, realm::frontier(world, me), |_, _, p| {
        if RICH { p.get("cores").num_or(0.0) }
        else { -p.get("garrison").num_or(0.0) }
    }).first().copied();
    // lesson:mining-plan
    let mines: Vec<Value> = realm::open_mines(world, me, 2.0, 24.0)
        .into_iter().map(|[p, slot]| arr![p, slot]).collect();
    let plan = obj! {
        "mines" => mines,
        "attack" => target.map_or(-1.0, |p| p.get("id").num()),
    };
    plan::share(&mut orders, &plan, me);
    // lesson:cpu
    orders.set("compute", obj! {
        "cpu" => obj! { "limits" => obj! { "think" => 0.3, "control" => CONTROL_LIMIT } },
        "types" => obj! { "miner" => obj! { "share" => 1.0, "every" => 1 } },
    });
    // lesson:spawn
    let units = me.get("units");
    if units.get("total").num_or(0.0) + units.get("queued").num_or(0.0) < 4.0 {
        orders.set("spawn", arr![obj! { "type" => "miner" }]);
    }
    orders
}

// lesson:mining
fn miner(units: View, world: View, me: View) {
    if !WORK { return; }
    for u in units.iter() {
        order(orders::gather(u, world, me));
    }
}
Recorded variantDuration (s)Mined cores at endCPU income at end (cycles/s)
mining60234182
idle60020000
blocked60020000
Logistics variantProduced cargo (cycles)Delivered cargo (cycles)First delivery (s)
delivery89750175520047.2
  • Saved engine runs: seed 7, 60 simulation seconds, ruleset cpu-rts, revision 7a8e23a308d0b66ac7d5ba7ed7756f9e50855196. Other factions use idle programs. These values illustrate this fixture; they are not a performance benchmark or current world prices.
  • All new CPU RTS worlds use logistics. Mined cargo becomes spendable after reaching the capital.

Download complete Rust source · Download exact sources, rules and observations

Import with use gameofcores::*;. In the SDK tables, an argument without a type is a View. Numeric observation IDs are f64. impl Views accepts a view array or a collection of views.

Library helpers execute inside the faction module and consume its instruction budget. Defaults and cached state last only for the current invocation.

FunctionWhat it does
program!(think, miner, …)Lists the functions the game may call, and wires them to it. program!(memory = 8; …) asks for more memory (docs part rust)
ViewOne value in a call's arguments, read in place: get, at, iter, num, str and the rest are in docs part rust, "Reading the arguments"
Value, obj!, arr!A value you own and hand back: obj! { "do" => "move", "target" => 12 }, arr![1, "two"]. Its methods are in docs part rust, "Building results"
order(o)Commits a unit order (or an array of them) now: it stands even if the call later runs out of cycles or panics. None, null and undefined are skipped
log(s)Writes a line to your console
cycles_left() -> f64Remaining callback cycles after memory charges, excluding active with_cycle_reserve scopes. Never below zero.
cycles_reserved() -> f64Sum of the active cycle reserves, or zero outside a reserve scope. This reads the current invocation's reserve without changing it.
with_cycle_reserve<T>(cycles: f64, work: impl FnOnce() -> T) -> TRuns work with cycles subtracted from cycles_left(). Nested reserves add together and restore afterward, including native unwinding. Negative or non-finite values reserve zero. This helps budget checks leave time for later work or output serialization. Execution still pays ordinary CPU charges; code that ignores the budget can exhaust the host limit.
rand() -> f64, rand_int(n) -> f64The game's random numbers for this call, in [0, 1) and [0, n). The same world replays the same numbers
hash(a, b) -> u32Two numbers mixed into a 32-bit number, as the game checks toll puzzles
mulmod(a, b, m) -> f64(a × b) mod m, exact for whole numbers below 2^53, and NaN for anything else
Point::new(x, y), Point::of(view)A point on a province's map, in cells from its town: x east, y north. Point::of(u.get("pos")) reads one
ViewsWhat impl Views takes: a View of an array, a Vec<View>, a slice or an array of views

Province lookup, frontier selection, mine access and observed targets.

FunctionReturns
realm::index(world) -> Rc<realm::Index>Provinces by id for this call's world, built once a call. .get(id) takes an id as a number and .at(view) one in a view. A missing id gives an undefined view.
realm::indexed(world) -> boolWhether this call has built that index yet.
realm::is_ally(me, owner: f64) -> boolWhether you share a pact with owner (me.allies).
realm::is_rival(world, me, owner: f64) -> boolWhether owner is a living, unshielded faction that isn't you or an ally.
realm::reach(p, me) -> Vec<f64>Province ids your units can move to from p: land neighbours plus the crossings you've researched. Sea routes need seaTraversal, passes mountainTraversal, and air routes flight. Works for any province: the map is public.
realm::frontier(world, me) -> Vec<View>Provinces next to your land that you could take (free land and rivals'). Out of sight, a province shows the owner you saw last (none if you never saw it), so it can be a pact partner's now: a capture there is refused, and me.refused names it. The default program's common::frontier remembers such land and leaves it out, along with the land of a faction whose passage you hold (a capture there ends the deal).
realm::from(q) -> Option<f64>For a province frontier listed this call: your province next to it, the place to muster. One that borders it by land comes before one a crossing away, then the one closest to your capital. None for one it didn't list.
realm::invaded(world, me) -> realm::Invaded{ at, n }: where hostile units stand in your land (at is -1 if none) and how many stand there. Your capital comes first when any stand in it, else the province with the most. Units there under a live deal of yours (me.contracts) don't count: a faction you sell passage to, and a lessee in the province whose mines you leased it.
realm::ground(p, x: f64, y: f64) -> Option<realm::Ground>The ground at point (x, y) of province p's map, in cells east and north of its town: { kind, h }, kind one of "open", "road", "forest", "rough", "ford", "water", "cliff", "town" and "mine", and h its height, 0 to 3. None off the map (RULES.ground.mapRadius cells out) or on the classic flat map, whose provinces have no map. Docs part game, "Places", has the ground's rules.
realm::toward(p, q: f64, d: f64) -> PointThe point d cells from province p's town toward the town of q (a neighbour, or the far end of a crossing), on p's map. It reads p.toward, which every province has: a unit vector toward each such town. The town itself when q isn't one of those.
realm::near(world, me, u, r: f64) -> Vec<realm::Near>Hostile units you can see within r cells of unit u (8 is the usual), nearest first, each as { d, unit }: d in cells, unit as world.units gives it. It compares positions on one province's map (pos.p), so units on a neighbour's map don't count. think only: unit code's world has no units.
realm::open_mines(world, me, per_slot: f64, max: f64) -> Vec<[f64; 2]>Open mine slots in your land (your slots in jointly captured land too), best first, as [province id, slot]. Each is worth its cores × the yield RULES.stackYield gives its next worker (a third worker only with per_slot 3), less a little for each hop from your capital. So a rich slot's second worker can beat a poor slot's first. 2 and 24 are the usual per_slot and max.
realm::mine_room(world, me) -> f64How many gatherers your land can use well: two per mine slot you may work, your own and those leased to you. Handy as a spawn limit. With me undefined (View::undefined()), every slot on the map counts.
realm::worker(p, k: f64) -> f64Who may work mine slot k of province p: its lessee while a mine lease runs, else its owner (or its share's owner, in jointly captured land). NaN when nobody may. realm::open_mines and orders::gather use it.
realm::leader(world) -> Option<View>The faction with the biggest share of the world's cores (cached per tick).
realm::rank(world, me, list: impl Views, score: impl Fn(View, View, View) -> f64) -> Vec<View>list sorted best first, scoring each province once with your score(world, me, q) (the default program's is common::score). A score that isn't a number (NaN) ranks last.
realm::claimant(world, me) -> Option<View>The members of the current Crown claim (world.crown.claim.members) when you aren't one of them, else None.

Province routes, local paths and shared route fields.

FunctionReturns
path::home(world, me, from: f64, to: f64) -> Option<Vec<f64>>The way from from to to through your own land, with no search. Every province you hold knows its hops from your capital, and a neighbour one hop nearer leads home, so the route climbs from both ends to where they meet. Either end may lie one step past your border. Waypoints with to last, empty when from is to, or None when your land doesn't join them up (an enclave, an island over the sea).
path::to(world, me, u, to: f64) -> Option<Vec<f64>>A route for unit u to to, from where it stands (or the province it's stepping into). It tries path::home, which walks only your own land: past two steps, with a crossing researched, a search no deeper than that route takes a shorter way over your crossings when there is one (land a strait away). Then the plan's field when it leads to to (a lookup, once the call has read the plan with plan::of or plan::for_units), then a field over your, free and allied land and your crossings (one search per target per call, shared by every unit sent there). Empty when it's there, None when there's no way. A unit in your land that the plan's field toward to doesn't lead from has no way there: None, with no search, unless the field was cut short. A search needs six times orders::reserve() cycles left in the call; without them it returns None and logs why once a call (share a path::field in the plan instead). orders uses it.
path::searched() -> boolWhether the last path::to ran a route search (a field toward a new target) rather than a lookup. orders leaves those out of its cost estimate.
path::walk(p, a: Point, b: Point) -> Option<Vec<Point>>What to give a unit as its order's at to walk from point a to point b in province p: [b] when the straight line is open ground, else path::local's way round with b last; None when there's no way. The straight check reads the map every half cell, and the search runs only when it's needed.
path::local(p, a: Point, b: Point) -> Option<Vec<Point>>A way across province p's map from point a to point b, round water and cliffs: the centres of the cells to walk through, b's cell last (empty when they share a cell), or None when there's no way or no map. Give a unit the whole list, with its spot added last, as its order's at: the game walks straight lines and stops at water and cliffs. It searches up to 217 cells, so do it in think, or keep the answer in unit RAM.
path::route(world, me, from: f64, to: f64, opts: &path::Opts) -> Option<Vec<f64>>The cheapest route as a list of province ids, both ends included, or None. opts.ok, opts.cost and opts.keep shape it. Crossings count once researched.
path::friendly(world, me) -> impl Fn(View) -> boolAn ok for route or field: land you can cross without a fight, as far as you know (yours, free land and allies').
path::dist(world, me, from: f64, opts: &path::Opts) -> path::DistHops from from to everywhere reachable: .ids (nearest first), .get(id) and .iter() for (id, hops) pairs. opts.ok, opts.max and opts.keep shape it.
path::field(world, me, to: f64, opts: &path::Opts) -> ValueEvery province's next step toward to, from one search backwards from it: { to, next: { id: nextId } }. Plan it once in think and put it in the plan (plan.field): every unit sent to to then routes with a lookup instead of its own search (path::to reads it). opts.ok, opts.from and opts.keep shape it. A search that ran short of cycles adds cut: true.
path::via(field: &Value, from: f64, max: usize) -> Option<Vec<f64>>The waypoints from from along a field to its goal (the goal last), or None when the field can't get there from from. 64 is the usual max.
path::along(u, verb: &str, pl: &Rc<Value>, world) -> Option<Value>path::go along the field in plan pl (pl.field, a path::field think shared): an order sending u to do verb at the field's goal. The field is read once a call for every unit that follows it, so a whole army routes with lookups. None when the plan has no field, u is on it already, or the field can't get there from where u stands. It doesn't look at whose land the goal is: the game refuses a capture or a raid on a pact partner's (orders::to checks).
path::go(u, verb: &str, route: &Value) -> Option<Value>An order sending u to do verb at the end of route along it (via), or None if it's already on that job with a route (or a field can't reach it). route is a list from path::route (.into() makes it a Value) or a field from path::field.

JSON values stored across RAM pages and public faction statements.

FunctionReturns
mem::put(base: u32, value: &Value, scope: &str, place: Option<&str>, max: u32) -> Option<Vec<Value>>RAM ops storing value from page base on, or None if it needs more than max pages (16 is the usual). scope: "local", "shared" (spreads through your land) or "ally". place: "unit" or "province" in unit code, or "archive" in think: your seat's archive, me.archive, kept for as long as you hold the seat, which ends with the epoch (mem::put(0, &notes, "local", Some("archive"), 64)). think's other ops go to capital RAM.
mem::get(pages, base: u32) -> ValueThe value stored from page base of a place's pages, or undefined if it's absent or still arriving.
mem::free(base: u32, n: u32, place: Option<&str>) -> Vec<Value>RAM ops freeing n pages from base.
mem::say(text: &str) -> Vec<Value>RAM ops setting your public message: up to 256 bytes of text on pages 252–255 of capital RAM, scope "public". Spectators see it under your name (on the board, in the chronicle, in your capital), and every faction reads it as world.factions[i].says. It costs those pages like any RAM; mem::say("") frees them. think only.
mem::say_once(orders: &mut Value, me, text: Option<&str>)Adds mem::say(text) to orders.ram only when text differs from what you say now (me.says), so a line computed every second costs RAM writes only when it changes. me.says comes back trimmed, single-spaced and with blocked words starred out, so keep text plain and under 256 bytes or it's rewritten every second. None and "" leave your message as it is. think only.

Planning data transmitted from think to controllers through RAM. Shared pages propagate over time.

FunctionReturns
plan::share(orders: &mut Value, plan: &Value, me)Adds the RAM ops that share plan from page 0 of capital RAM (shared, at most 16 pages) to orders.ram, only when it changed, and frees pages left over from a bigger plan. A province holds RULES.ram.provincePages pages plus its development (me.ram.provincePages is your smallest): a plan bigger than that only reaches the provinces with room, and it logs so. The engine pays for the write from the cycles think leaves (RULES.ram.writeBytesPerCycle) and refuses it when they run short. Each write is marked on capital page 249, so the next second can tell when one didn't land: it logs that once for each plan size, with the plan's pages and cost, and leaves a notice on shared page 250 so your units' stale-plan line says why (plan::check). A write that lands clears the notice.
plan::of(me, u) -> Rc<Value>The plan as unit u knows it: as its province last heard it, or the orders it carried out of your land (marked partial: true: only attack, stage, defend, need and threat, no fields of your own); {} if neither. Its at is the game second the plan was shared.
plan::job(me, u) -> ValueUnit u's own job: whatever think put under its id in the plan's jobs ({ [unit id]: job }, a small JSON value such as { do: "capture", target: 12 }), as its province last heard it, or the job it carried out of your land; undefined if none.
plan::age(pl: &Value, world) -> Option<f64>How many seconds ago plan pl was shared, or None when it doesn't say. Land cut off from your capital, and units abroad, keep the copy they last heard.
plan::check(pl: Rc<Value>, world) -> Rc<Value>Returns pl, after a log line when it's older than plan::stale_after() seconds: once a call, in the first 8 seconds of every 2 minutes of the game's clock. The line says the newer plans failed to save when plan::share left its notice there. Otherwise it can't tell a plan think left unchanged from land cut off from your capital, or units abroad, so it names them. orders::job and plan::for_units (given world) check every plan they act on.
plan::stale_after() -> f64, plan::set_stale_after(seconds: f64)When a plan counts as old for plan::check: 30 seconds unless you set it for the call.
plan::for_units(me, units: impl Views, world) -> Rc<Value>The plan for a whole unit type: the plan in your land where one of the units stands (one with attack, mines or raid), else the core a unit carries abroad (partial: true), else {}. Given world, the core gets a log line in the first 8 seconds of every 2 minutes, and an old plan one too (plan::check); pass View::undefined() for neither line.
plan::here(me, u) -> boolWhether u stands in your own land (where your RAM is).
plan::known(me, u) -> Option<Rc<Value>>The plan u's province holds, when this call already read it (plan::of, plan::for_units), with no read of its own; None otherwise. path::to uses it to find the plan's field.
plan::pack(pl: &Value) -> Vec<u8>A plan's orders (attack, stage, defend, need, threat) and the second it was shared, as 16 bytes a unit can carry. orders::carry and orders::job write them into unit RAM page 0 while the unit is in your land, with its job in page 3.
plan::unpack(b: &[u8]) -> ValueThe orders back from plan::pack's bytes.

Construct and commit unit orders. gather needs the shared mining plan. all and job commit; to, hold, land and gather only construct orders.

FunctionReturns
orders::reserve() -> f64, orders::set_reserve(cycles: f64)600 unless you set it for the call. Below this many cycles left in the call (cycles_left()), or less than its dearest order so far needs (+300), orders hands out no new orders, so a unit type never runs out of cycles and loses them all; the units it skips keep their standing orders a second longer. The first time a call stops short it logs one line saying so, with the cycles it had and what an order costs. An order's cost runs from that check to its end (its plan lookup, route and RAM); orders that ran a route search don't count (path::to guards its own).
orders::first() -> f64, orders::set_first(cycles: f64)700 unless you set it: what the first order of a call needs, since it also reads the plan (once a call). Given the world, it also builds the map index first (realm::index), when there's room for both. A type whose calls have less gives no orders, and logs so.
orders::to(u, verb: &str, target: f64, world, me, at: impl Into<Value>) -> Option<Value>One order for unit u with its route (via from path::to), or None if it's already doing exactly that (unchanged orders cost cycles for nothing, and keep the route it's on), there's no way there, the call is short of cycles, or it's a capture or a raid on a pact partner's land, which the game refuses. With world and me undefined it's the bare order, which the game carries out only one step away. at is where to stand on the target's map, in cells from its town: a Point, or a list of points, the way there with the spot last (path::walk). () for none.
orders::hold(u, at: impl Into<Value>, world, me, p: Option<f64>) -> Option<Value>A fight order holding point at of province p (None: where u stands): the unit stands there and strikes whatever comes within its reach. Where towns have walls (world.walls), guards stop a siege only by killing its capturers. In an older world, guards inside a town's ring (RULES.ground.ring cells) hold off a siege until its capturers there number RULES.siegeOdds for each of them. The default program holds its capital this way.
orders::land(u, world, me, p: Option<f64>) -> Option<Value>A winged unit comes down to cool off. Its flight burns more cycles the longer it's up (u.rts.air) and none while it stands still on your land or an ally's. With province p (yours or an ally's) it holds a point by p's town. Without p it's { id, land: true }, and the game flies it to your nearest land by the shortest way. None when it's down already or on its way.
orders::all(units: impl Views, verb: &str, target: f64, world, me) -> Vec<Value>The same order for every unit, skipping the ones already on it. Each order is committed with order() as it's made, and returned as well.
orders::job(u, world, me) -> Option<Value>Unit u's own job (plan::job: { do, target }), routed like orders::to and committed with order(). While u is in your land it also carries its job and the plan's orders for when it leaves, so a unit abroad keeps doing the job it was given.
orders::gather(u, world, me) -> Option<Value>A gather order, with its route, to the next open slot in the plan's mines (as u knows the plan), or None if u is already gathering, flies (a unit with wings can't land to gather) or no slot is left. Slots are handed out in turn within one call, passing over slots you can't work now (land lost or leased out since the plan was shared).
orders::room(world) -> boolWhether this call has room for one more order: orders::reserve() cycles left, or what its dearest order so far needed (+300), or orders::first() for its first. The first time there isn't, one log line says why. orders::to and the other helpers ask it for every order they give; ask it yourself before work of your own that ends in an order.
orders::carry(u, pl: &Rc<Value>, me) -> Option<Vec<Value>>RAM ops that copy into unit u (in your land) what it needs when it leaves: plan pl's orders (plan::pack, unit RAM page 0) and its own job from the plan's jobs (page 3). Put them on the unit's order as its ram. None when it carries both already or stands abroad. Units standing together share one plan, so it's packed once for all of them.
orders::gate(units: impl Views, to: f64, world, me, verb: &str, target: Option<f64>) -> Vec<Value>Gates: the units standing still in one province of yours (where most of them stand, or the open window's from) jump through your gate to to, another province of yours that isn't a neighbour. Then they go on to verb ("move" is the usual) at target (None: to). The first through opens the gate on that route for RULES.gate.window seconds, for up to RULES.gate.units units in all; then it rests RULES.gate.cooldown seconds (me.gate). Empty while it rests, while it's open on another route, or without Gates. Unit code only (think can't move units).

Private messages, offers and pact operations.

FunctionReturns
diplomacy::send(orders: &mut Value, to, body, deal)Adds a message to orders.send: to a faction id (or a list), body a string or bytes, deal { give, ask } with { coin, provinces, units } on each side, plus the goods under **trade** (◆ a second, techs, mine leases, passage, sight, relay rights). () for no deal.
diplomacy::propose(orders: &mut Value, me, members, split, body)Proposes a pact with members (you're added). split is { factionId: weight } for a Crown's Pot, or () for the default, ∝ share².
diplomacy::text(m) -> StringA message body as text.
diplomacy::follow(orders: &mut Value, me)Follows what your agent wrote into capital RAM from page 240 (MCP write_ram { page: 240, value: { n, orders } }, at most 8 pages; it keeps its own count at page 248). The send, accept, reject, leave and cancel (contract ids, as trade::cancel takes them) in orders join this second's orders, once per n. This is how an agent negotiates live, and ends a deal, without redeploying.

Contracts for units, mines, passage, technology and other rights.

FunctionReturns
trade::hire(orders: &mut Value, to, units, seconds: f64, ask, body)Offers faction to your units (ids) on hire for seconds, for ask. Hired units take its orders, are guests on your land, and come back when the hire ends.
trade::hire_from(orders: &mut Value, from, count: f64, seconds: f64, give, body)Asks faction from for count of its units on hire for seconds, for give. You needn't know their ids: if it accepts, the game picks them then, units not at work in a mine and the healthiest first.
trade::lease_mines(orders: &mut Value, to, p: f64, slots: f64, seconds: f64, ask, body)Offers faction to a lease on slots of province p's mine slots for seconds, for ask.
trade::passage(orders: &mut Value, to, units: f64, seconds: f64, ask, body)Offers faction to passage for up to units of its units through your land for seconds, for ask.
trade::sell_tech(orders: &mut Value, to, t: &str, ask, seconds: f64, body)Offers to sell tech t to faction to for ask: for good, or as a lease for seconds when they're above 0.
trade::idle_mines(world, me) -> Vec<trade::Idle>Your provinces with mine slots no unit of yours works and nobody leases, as { province, slots }, most first. What a landlord can lease out.
trade::cancel(orders: &mut Value, id)Breaks contract id (me.contracts lists them). Breaking costs you the time left and is public.
trade::toll(orders: &mut Value, p: f64, coin: f64)Posts a toll of coin ◆ a unit on your province p. A paying unit is safe on your land for RULES.trade.tollPass seconds. orders.toll replaces every toll you posted, so call it for each toll you keep.

Political actions and province influence.

FunctionReturns
sway::reach(world, me, p: f64) -> boolWhether you reach province p to bribe or preach there: it is yours, on your border, or a unit of yours stands in it. The engine refuses a bribe out of reach.
sway::bribe(orders: &mut Value, p: f64, coin: f64)Adds a bribe of coin ◆ (whole ◆) in province p to orders.bribe.
sway::preach(orders: &mut Value, p: f64, cycles: f64)Adds province p to orders.preach at cycles a second. It is a standing order: orders.preach replaces the whole list.
sway::propaganda(orders: &mut Value, p: f64, cycles: f64)Adds province p to orders.propaganda at cycles a second: a rival's or free land wins you favour and a rival's loses loyalty, your own gains it. It is a standing order: orders.propaganda replaces the whole list, and each province pays its own cycles.
sway::favour(me, p: f64) -> f64Your favour in province p.

RAM shared with pact partners.

FunctionReturns
ally::share(orders: &mut Value, base: u32, value: &Value)Adds RAM ops sharing value with your allies from page base (128–255, at most 8 pages: a bigger value isn't shared) to orders.ram. think only.
ally::read(me, u, base: u32) -> ValueIn unit code: what allies shared from page base, as the province u stands in heard it, or undefined if nothing.

Unit naming and body validation against current capabilities.

FunctionReturns
army::check(build: &Value, modules: &Value, me) -> Option<String>Why the game would refuse a spawn with this build and these modules, in its own words, or None when it would take it. Leave either out with Value::Undef. It reads your caps from me.build and your modules from me.rts.licenses, and checks a ship has a port. A refused spawn is refused again every second you send it, so check first: if army::check(&b, &arr!["hull"], me).is_none() { orders.entry("spawn").push(obj! { "type" => "frigate", "build" => b, "modules" => arr!["hull"] }); }.
army::name(list: &[&str], n: f64) -> StringThe n-th name from a list: "Fern", "Sorrel", …, "Fern 2", ….

Contact checks and target selection helpers. Register a reflex callback to use them.

FunctionReturns
reflex::can_hit(u, t) -> boolWhether your unit u can strike t from its near list now: a rival within u.reach, and not in the air unless u has wings, or range (in the CPU RTS, range and the antiAir module).
reflex::engaged(u) -> boolWhether u is on an aggressive order (fight, capture or raid). The game holds no unit still in a fight: add hold: true to such a unit's strike, so it doesn't walk on past what it's fighting.

When a ground army attacks, defends, reinforces, falls back and seeks battle. Your program picks the target and stage.

FunctionReturns
war::doctrine(plan: &mut Value, world, me, seek: bool)Writes the decision into plan as war: [state, mass, since], and sets defend and threat when a rival stack comes (the rules below). State 0 gathers the army at the stage, 1 sends it in and 2 falls back to the stage. mass is how many fighters must stand at the stage or be on the attack. since is the game second the army began to gather for this target. It reads the last shared plan from capital RAM page 0, and may change the plan's attack, stage, need, picket, guard and seek (the rules below). It removes war when the plan has no attack and stage, or they name one province. One pass over world.units costs about 90 cycles a unit in sight. With less than 8,000 cycles plus that left, or 6,000 during the pass, it keeps the last shared plan's war for the same target.
war::front(u, world, me, pl: &Value) -> Option<Option<Value>>Unit u's order under the plan's war, or None to leave u to the plan. Some(order) is a fight order to the stage from orders::to. In the target, u falls back when the plan's state is 2. Elsewhere, u gathers at the stage while the state is 0 or 2. Units abroad carry no war: in the target, such a unit falls back when rival fighters there outnumber yours war::FALL_ODDS to one and number war::STACK or more, counted from the province's units and the owner's townGarrison. Outside the target they follow the plan. Ships and aircraft get None.
war::fighter(u) -> boolWhether u counts as the army: alive, on the ground, not a ship or flier, not a miner, hauler, freighter or scout, and not gathering or studying.
war::drive_limit(out: &mut Value, world, me)Raises the drive limit in think's orders out to cover your army on the march: your fighters moving to the last shared plan's attack, stage or defend, each at its drive price a second, plus a tenth. A unit's price is me.rts.costs.drive.land ÷ 60 × (60 + its drive power) × its driveScale. It gives at most war::MARCH_SHARE of income plus a thirtieth of the bank, and never lowers a limit. When out sets no CPU policy, it sends the standing one (me.rts.cpu's limits, reserve and upkeep order) with the new limit. One pass over world.units costs about 40 cycles a unit in sight. Under 4,000 cycles left, or 3,000 during the pass, it changes nothing.
war::stage_for(world, me, p: f64, ours: &[(f64, f64)], far: bool) -> f64The province of yours to gather at for an attack on p. It's a neighbour of p, else one next to a neighbour of p: of those, the one where most of your fighters stand (ours is (province, fighters) pairs), then the nearest your capital by hops. With far, else the province of yours nearest p on the map. -1 when there's none.
RuleWhenWhat the army does
PicketYour program set defend against fewer than war::STACK rivals.defend becomes a picket there. Its guard is twice the rivals' number plus one of your fighters, those in the province first, then its neighbours'. The rest stay with the army.
DefenseThe plan has no defend, and the biggest rival stack in your land or headed into it (rivals whose to is your province) has war::STACK fighters or more and war::MEET of your army or more.defend becomes that province and threat the stack's size. The plan's picket, guard and guardAt go, so the whole army meets it. A stack more than war::FALL_ODDS times your army, away from your capital, sends the army to the capital instead.
ReinforcementThe plan has no defend, and 2 or more of your fighters and at least 1 rival fighter stand in the last shared plan's target.That target and its stage stay.
Seekseek, and a rival army of war::SEEK fighters or more stands in a province of a rival or of no one, within two steps of your land, and war::MASS of your army outnumbers it war::PUSH_ODDS to one.The biggest such army's province becomes the target, with a stage from war::stage_for and need at war::PUSH_ODDS times the army. The plan says seek: true. The same army stays the target while it qualifies.
CommitmentNo rule above applies, the last shared plan's target isn't yours and its stage is, and the army began to gather for it less than war::COMMIT seconds ago. Not for an army seek chose.That target and its stage stay, whatever your program picks.
StageThe stage is your capital, and it isn't next to the target.The stage moves to war::stage_for the target.
Fall back (state 2)Some of yours are in the target, and rivals there number war::STACK or more and outnumber yours on the attack war::FALL_ODDS to one. Yours on the attack are those in the target and those ordered to it.Yours there fall back to the stage. The army goes in again once those at the stage and on the attack outnumber the rivals war::PUSH_ODDS to one and reach need.
Go (state 1)Yours at the stage and on the attack reach mass and war::PUSH_ODDS times the rivals there. Or the army went in and 30% of mass (at least 2) are still on the attack.The army goes in, and stays in.
Go (state 1)Otherwise: 30% of mass (at least 2) are in the target, or the army has waited war::MASS_WAIT seconds and has need and war::PUSH_ODDS times the rivals.The rest follow, or the army goes with what it has.
Gather (state 0)Otherwise.The army gathers at the stage. mass is the plan's need or war::MASS of the army, whichever is bigger, at most 255.
ConstantValue
war::MASS0.7: the share of the army that gathers before it attacks.
war::MASS_WAIT60: seconds the army waits for its mass.
war::FALL_ODDS1.4: rivals this many times yours on the attack turn yours back.
war::PUSH_ODDS1.2: the army goes in again once it outnumbers the rivals in the target this many times. seek goes after an army that war::MASS of yours outnumbers this many times.
war::STACK3: the smallest rival stack the whole army meets. A smaller one gets a picket.
war::MEET0.25: the share of your army a rival stack in your land must reach before the whole army meets it.
war::COMMIT150: seconds the army keeps the target it gathers for.
war::SEEK8: the smallest rival army seek goes after.
war::MARCH_SHARE0.5: the share of income war::drive_limit lets the army's march take, plus a thirtieth of the bank.

Stealth movement, technology theft and sabotage.

FunctionReturns
spy::capital(world, me, u) -> f64The nearest rival capital you know of (by hops), or -1.
spy::go(u, verb: &str, target: f64, world, me, at: Point) -> Option<Value>An order for u to do verb at point at of province target, routed through any land (a hidden spy walks through rivals'). "move" to 6 cells out from a town watches it from well outside its ring, where fewer eyes are; its own faction sees what it sees there. None when it's on it already or there's no way.
spy::read(me, u) -> ValueWhat a rival keeps in the province where u stands hidden (me.ramSpied): its shared plan, read as plan::of reads yours ({ attack, stage, defend, … } for a program on the library's plan), { pages } for anything else, or null when u reads nothing there.
spy::sabotage(u, world, me, target: Option<f64>) -> Option<Value>A sabotage order at rival capital target (None: spy::capital), standing inside the ring. Each second it takes RULES.spies.sabotageShare of that rival's duel bank, the cycles its capital parries sieges with, for RULES.spies.sabotageCost ◆. None when it's on it already.
spy::sabotage_structure(u, world, me, site) -> Option<Value>Routes a hidden, paid ground spy to a discovered hostile energy site's exact x/y in province p. Emits { id, do: "sabotage", target: site.p, structure: site.id, at: { x, y } }, with via when needed. Returns None for an invalid, protected, cooling, unaffordable or matching ongoing target, or an unfinished route search. Requires stealth or an active cloak, at least 25 ◆, and available code cycles.
spy::steal(u, world, me, target: Option<f64>, tech: &str) -> Option<Value>A steal order at rival capital target (None: spy::capital) for tech, standing inside the ring. It costs RULES.spies.theftCost ◆ every second it tries. None when there's no rival capital, or it's on it already.

Physical holds, owned land routes, dock transfers, freight circuits, salvage and escort orders.

SignatureReturn and behavior
logistics::Endpoint::town(p: f64) / Endpoint::dock(p: f64)An endpoint with public fields p and dock; .value() makes its order payload.
logistics::cargo(u) -> f64 / capacity(u) -> f64Owner cargo value and remaining hold capacity after passengers; missing values return zero.
logistics::stock(me, endpoint: Endpoint) -> f64Exact owned depot stock; unavailable endpoints return zero.
logistics::land_route(world, me, from: f64, to: f64) -> Option<Vec<f64>>Route through owned adjacent land and passes. Excludes sea crossings, gates and flight. Returns None when no route is found or the call's budget is low.
logistics::transfer(u, world, me, endpoint: Endpoint, load: bool, amount: Option<f64>) -> Option<Value>Movement plus a load/unload order. Hulls dock; ground carriers use a land route and local path. No order if the same transfer is running or a route is unavailable.
logistics::haul(u, world, me, source: Endpoint, destination: Endpoint, threshold: f64) -> Option<Value>A chosen two-endpoint circuit. Starts unloading at the capacity fraction clamped to 0.01–1, and continues unloading until empty. A load for a depot other than your capital's town that holds 98% of its capacity goes to the capital's town instead, unless the world turns the house fixes off (me.lab.fixes is false).
logistics::salvage(u, wreck) -> ValueA ship approach and salvage order for the visible sea wreck. Ground recovery requires a separate land movement order.
logistics::escort(u, convoy, distance: f64) -> ValueFollow the chosen ship with a sea chase order. Does not choose attacks or spend combat power.
logistics::cancel(u) -> ValueCancel a standing cargo transfer while keeping the cargo and position.

Water routes, ship positions, stations and bearings.

FunctionReturns
sea::index(world) -> Rc<realm::Index>world.waters by id, built once a call.
sea::shore(world, p: f64) -> Vec<f64>The ids of the waters on province p's shore.
sea::route(world, a: f64, b: f64) -> Option<Vec<f64>>The way by water from water a to water b, as a list of ids with b last and a left out. Empty when a is b. Returns None when no route is found before the call needs its order reserve.
sea::station(world, a: f64, b: f64) -> f64The water where a ship keeps the RAM link between provinces a and b up: the middle of a shortest water route between their shores. Ties keep source shore order, then destination shore order. Returns -1 when no route exists or the search needs to leave cycles for orders. Repeated queries reuse the result within the same call.
sea::gaps(me) -> Vec<[f64; 2]>Your crossings to another landmass whose RAM link is down now, as [a, b] pairs of province ids.
sea::bearing(u, t) -> sea::BearingWhere t (an entry of a reflex's near) lies from ship u: side ("port" or "starboard"), off (degrees off the beam, 0 square on it) and ahead (1 dead ahead, -1 astern).
sea::in_arc(u, t, arc: f64) -> boolWhether t is within 6 cells and arc degrees of u's beam (45 is the usual): where a broadside reaches.
sea::beam(u, t) -> PointThe heading that puts t square on u's beam, turning the shorter way.

Geometry helpers for capital scenes. Scene size and execution charges apply.

FunctionReturns
build3d::around(n: f64, r: f64, a0: f64) -> Vec<build3d::Spot>n points { x, z } evenly on a circle of radius r around the plaza, starting at angle a0 (0 is east).
build3d::on(p: &Value, lx: f64, lz: f64) -> build3d::SpotA point on the plaza from lx, lz in piece p's own frame (front +z, turned by its rot): where a figure stands to ride in a chariot, e.g. build3d::on(&car, 0.0, 0.5) at the front of the car.
build3d::hash(s: &str) -> f64A stable small number from a string (pick a style per faction name).

Estimate priced actions without executing them. The quote itself consumes normal code cycles.

SignatureReturn / constraints
compute::quote(me: View, api: &str, p: &Value) -> Option<f64>Estimated cycles at the world’s price level. Returns None without CPU RTS costs, for unsupported APIs, or for out-of-range shell and repair parameters.
APIParameters
fabricationmodules
upkeepbuild, modules, seconds
drivepower, leg, seconds, build.speed (default 2), build.wings (default 0)
armorpower, seconds
cloakseconds
weaponpower, pierce
shellradius, distance
repairamount, distance
dash, scan, gateNo additional parameters.
  • seconds defaults to one. Quotes exclude custom body, art and sound upkeep. A quote does not confirm affordability, prerequisites or action validity. The engine checks these when the action resolves.

The gameofcores-default-factions repository owns the default programs, shared presets and viewer artwork.

CodeContract
shared::{air, capital, theme, unit_art}Faction modules for aircraft builds, themes, capitals and art selection. Exported programs include their source, which counts toward code RAM.
shared::commonStrategy included in exported faction source and billed as code RAM.
tools/source.mjsExports a complete faction program using the SDK. The source limit is 512 KiB. Every faction receives 3,360 free RAM pages.

Build validated rigid-part models in look().models3d. Coordinates are unit-local with +y up and +x forward. Rendered models retain the unit’s existing gameplay body.

SignatureReturns / effect
unit3d::part(shape: &str, at: [f64; 3], size: [f64; 3], color: &str, motion: &str, pivot: [f64; 3]) -> ValueOne model part. Supported shapes, dimensions, colors and motions are constrained by the model contract.
unit3d::extrude(sprite: &str) -> ValueA reference to an existing validated silhouette.
unit3d::dress(look: &mut Value)Add model references for sprites without an existing model.