Commander tool contract¶
Generated by connecting an MCP client to the actual Commander server and reading tools/list. No game request is made. Tool names, input schemas, required fields, and descriptions below are the executable English protocol contract. See Commander for setup and integration workflows for examples. Download the JSON contract.
Tools with all tiers enabled: 63.
abandon_planet¶
Tier: commit.
Permanently give up one planet and its moon. Always preview_abandon_planet first, show consequences, and obtain explicit player approval naming this planet. Never infer consent from cleanup, optimization, poor field count or a general empire-management request. Cannot abandon the last planet; homeworld moves to the oldest remaining colony. Own flights and building construction block it. Other queues are lost without refunds; foreign flights continue to the attackable ruins. Requires confirm=true and the preview token/code. No password should be requested or passed through chat.
{
"additionalProperties": false,
"properties": {
"confirm": {
"description": "true only after explicit player approval of this irreversible abandonment and its moon/asset losses",
"type": "boolean"
},
"confirmation_code": {
"description": "exact planet code from the preview",
"type": "string"
},
"confirmation_token": {
"description": "unexpired token from preview_abandon_planet",
"type": "string"
},
"planet_id": {
"description": "the exact planet ID approved by the player",
"type": "integer"
}
},
"required": [
"planet_id",
"confirmation_code",
"confirmation_token",
"confirm"
],
"type": "object"
}
accept_trade¶
Tier: commit.
Take an offer. Your payment leaves the planet now, and the seller's cargo ships launch now: they fly travel_seconds to you, unload, and carry the payment home. Nothing here can be recalled by either side. Only one buyer wins an offer, so a race that is lost is reported as the offer being gone rather than as an error. Read the row in trade_offers to the player, with the arrival time, before accepting.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "the offer id, from the trade_offers tool",
"type": "integer"
},
"planet_id": {
"description": "the planet that pays and receives; omit for your first",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
acs_groups¶
Tier: read.
Read your ACS invitations and active joint attacks. Optional group_id shows participants, ships and synchronized arrival; other commanders' cargo stays private.
{
"additionalProperties": false,
"properties": {
"group_id": {
"description": "ACS group id; omit to list invitations and your attacks",
"type": "integer"
}
},
"type": "object"
}
alliance_chat¶
Tier: read.
The private channel shared by your current alliance, oldest first. Reading through Commander does not clear the terminal's unread badge. New members cannot read lines from before they joined.
alliance_detail¶
Tier: commit.
One alliance in full: who owns it, what it says about itself, how many are in it.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "the alliance id, from the alliances tool",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
alliance_standing¶
Tier: read.
Your alliance membership, roster and role, plus pending applications and invitations.
alliances¶
Tier: commit.
Every alliance on the server.
allied_defenses¶
Tier: read.
Read allied fleets traveling to or holding at your planets and moons. Shows their owners, full ships and hold end; cargo stays private. These are reinforcements, not hostile incoming attacks.
boost_production¶
Tier: spend.
Raise one planet's mine output by 25 percent for 24 hours, for 100 dark matter. One boost per planet at a time; a running one cannot be extended or stacked.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to boost; omit for your first",
"type": "integer"
}
},
"type": "object"
}
build_defense¶
Tier: spend.
Queue defences on a planet. They never leave it, so unlike ships they cannot be lost anywhere but at home. Same shipyard line as ships: five batches, beside construction, paused while the shipyard or nanite factory is raised.
{
"additionalProperties": false,
"properties": {
"count": {
"description": "how many to build",
"type": "integer"
},
"key": {
"description": "the ship or defence key, for example small_cargo or rocket_launcher",
"type": "string"
},
"planet_id": {
"description": "the planet whose shipyard builds them; omit for your first",
"type": "integer"
}
},
"required": [
"key",
"count"
],
"type": "object"
}
build_queue¶
Tier: read.
What is being built on a planet and when each item lands. Two lines are listed together, ordered by finish: queue_type building is the construction line, ship and defense the shipyard line; they run at the same time and each holds five. Research rows are the account's own slot.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to read; omit for your first planet",
"type": "integer"
}
},
"type": "object"
}
build_ships¶
Tier: spend.
Queue ships in a planet's shipyard. Needs a shipyard, and the ship's own prerequisites; the codex tool prices one before you commit to several. The shipyard is its own line, five batches deep, running beside construction: a batch starts now even while a mine is upgrading, but nothing is built while the shipyard or nanite factory itself is being raised. Units are handed over one by one as they finish.
{
"additionalProperties": false,
"properties": {
"count": {
"description": "how many to build",
"type": "integer"
},
"key": {
"description": "the ship or defence key, for example small_cargo or rocket_launcher",
"type": "string"
},
"planet_id": {
"description": "the planet whose shipyard builds them; omit for your first",
"type": "integer"
}
},
"required": [
"key",
"count"
],
"type": "object"
}
cancel_build¶
Tier: spend.
Take a queued build, batch or research back. Its cost returns to the planet: all of it for a level, and for a batch the share of the units not yet built, while the units already finished stay. Everything queued behind it moves up in its own line (construction or shipyard) and the next one starts now. A building level cannot be cancelled while a higher level of the same building is queued behind it; cancel that one first. Cancelling is what makes room when a line is at its limit of five.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet whose queue it is in; omit to mean any of yours",
"type": "integer"
},
"queue_id": {
"description": "the queue entry's id, from build_queue or from the response that queued it",
"type": "integer"
}
},
"required": [
"queue_id"
],
"type": "object"
}
cancel_trade¶
Tier: commit.
Withdraw one of your own open offers. The escrowed resources and the reserved large cargo go back to the planet they left. An offer somebody has already accepted is in the air and cannot be called back.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "your own offer's id, from trade_offers with mine",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
changelog¶
Tier: read.
Published game changes from the server. Filter by version or limit; defaults to the five newest releases.
{
"additionalProperties": false,
"properties": {
"limit": {
"description": "maximum releases when version is omitted; defaults to 5",
"type": "integer"
},
"version": {
"description": "release tag such as v0.11.13; omit for recent releases",
"type": "string"
}
},
"type": "object"
}
codex¶
Tier: read.
Everything the rules say about one thing, or about many at once. Give keys instead of key for a build order in a single call: the planet and your research are read once and every entry is quoted against them. Give a key and you get the price at the level you would build next, what that level produces or draws, how long it takes, what it needs first and what it unlocks. Figures are for your own planet at your own tech, so the numbers are the ones you will actually get. Ask this before deciding, not after building.
{
"additionalProperties": false,
"properties": {
"key": {
"description": "a building, technology, ship or defence key such as metal_mine",
"type": "string"
},
"keys": {
"description": "answer for several keys at once instead of one; the planet is read once for all of them",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"level": {
"description": "the level to answer for; defaults to the next one you would build",
"type": "integer"
},
"planet_id": {
"description": "answer for this planet; omit for your first",
"type": "integer"
}
},
"type": "object"
}
combat_rules¶
Tier: read.
Read the live server combat rules, rapid-fire matrix, unit stats, moon percentage units and compatibility limits. Use these instead of guessing OGame values from memory.
conversation¶
Tier: commit.
Everything said between you and one player, oldest first. Marks what they sent as read. Read this before answering somebody, so the reply follows what was actually said.
{
"additionalProperties": false,
"properties": {
"username": {
"description": "the other player's username",
"type": "string"
}
},
"required": [
"username"
],
"type": "object"
}
conversations¶
Tier: commit.
Who you are talking to, newest first, with the last thing said in each.
create_acs¶
Tier: commit.
Turn your outbound attack into a joint attack. Then invite commanders by name; no alliance membership is required for attack invitations.
{
"additionalProperties": false,
"properties": {
"fleet_id": {
"description": "your outbound attack fleet to turn into an ACS group",
"type": "integer"
}
},
"required": [
"fleet_id"
],
"type": "object"
}
create_alliance¶
Tier: commit.
Found an alliance with yourself as owner. The tag is public and permanent enough that other players will know you by it, so ask before inventing one.
{
"additionalProperties": false,
"properties": {
"description": {
"description": "what it is for",
"type": "string"
},
"name": {
"description": "the alliance's full name",
"type": "string"
},
"tag": {
"description": "the short tag shown beside members' names",
"type": "string"
}
},
"required": [
"tag",
"name"
],
"type": "object"
}
dark_matter¶
Tier: read.
The balance, the rate, and whether it is running. Dark matter is earned while the account has an open session, subject to a 12-hour cap per unbroken session. Read rate_per_hour and prices from the response; multiple connections do not multiply earnings. There is nothing to deploy.
defence_summary¶
Tier: read.
What is standing on a planet, totalled: weapon, shield and hull across every turret and every ship parked there. Read this before answering an attack. Incoming ships are hidden on fleets; an in-range phalanx_scan from a moon is the exception that can reveal composition.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to read; omit for your first planet",
"type": "integer"
}
},
"type": "object"
}
delete_message¶
Tier: commit.
Delete one message permanently. There is no undo and no trash.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "the message id, from the messages tool",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
demolish_building¶
Tier: commit.
Tear the top level of a building down, freeing the field it occupied. This is how a planet or moon that is out of fields gets room back. It costs what that level cost to build (codex shows it under demolish), takes as long as building it, takes one of the five construction slots, and the field comes back when it finishes. Refused for the terraformer and lunar base (they are the fields), for satellites and crawlers, while that building has any other row in the construction line, under the same shipyard and laboratory locks as upgrade_building, and for a missile silo whose missiles would not fit the smaller silo. cancel_build takes it back for a full refund until it finishes. The level is gone once it does: tear down only when the player asked for it or approved it, and say the cost and time first.
{
"additionalProperties": false,
"properties": {
"building": {
"description": "the building key to take one level off, for example robotics_factory",
"type": "string"
},
"planet_id": {
"description": "the planet or moon it stands on; omit for your first planet",
"type": "integer"
}
},
"required": [
"building"
],
"type": "object"
}
dispatch_fleet¶
Tier: commit.
Send a fleet. The ships leave the planet now and the flight takes real time in both directions, so say the arrival time and the fuel before you send it. Check the galaxy tool for the cost first. A slot can hold a planet and a moon; target_moon aims at the moon.
{
"additionalProperties": false,
"properties": {
"cargo": {
"additionalProperties": {
"type": "integer"
},
"description": "metal, crystal or deuterium to load",
"type": "object"
},
"confirm_ally": {
"description": "attack only: send it even though the target is in your own alliance. Without this the server refuses and names them; ask the commander before setting it",
"type": "boolean"
},
"hold_hours": {
"description": "defend only: 0-32 hours at the target; fuel is prepaid and not refunded on recall",
"type": "integer"
},
"mission": {
"description": "attack, transport, deploy, colonize, espionage, recycle or defend (hold at an alliance member's planet/moon)",
"type": "string"
},
"origin_planet_id": {
"description": "the planet to launch from; omit for your first",
"type": "integer"
},
"ships": {
"additionalProperties": {
"type": "integer"
},
"description": "ship key to count, for example {\"small_cargo\": 2}",
"type": "object"
},
"speed_percent": {
"description": "throttle 10-100; lower is slower and cheaper",
"type": "integer"
},
"target_galaxy": {
"description": "galaxy number",
"type": "integer"
},
"target_moon": {
"description": "aim at the moon orbiting that slot rather than the planet on it",
"type": "boolean"
},
"target_position": {
"description": "position 1-15",
"type": "integer"
},
"target_system": {
"description": "system number",
"type": "integer"
}
},
"required": [
"mission",
"target_galaxy",
"target_system",
"target_position",
"ships"
],
"type": "object"
}
empire_overview¶
Tier: read.
The whole situation in one call: who you are, every planet with its stocks, and under planet_detail every one of them with its own production report and build queue, plus the quest board and every fleet in the air. Start here; it is one call instead of four or five per planet.
fleets¶
Tier: read.
Every fleet of yours in the air, and every fleet heading at you.
galaxy¶
Tier: spend.
One solar system's fifteen slots, with what it costs to get there from one of your planets: distance, flight time and fuel for a single small cargo. A slot with wreckage in orbit carries a debris field with the metal and crystal in it and how many recyclers it takes; dispatch_fleet with mission recycle collects it. A slot with a moon carries it under the planet with its name and fields. Viewing a system other than your own costs 10 deuterium per jump; your own system, and refreshing the one you just paid for, are free. A slot with simulated true belongs to the simulated population: nobody reads a message sent there, and it defends and rebuilds on a script.
{
"additionalProperties": false,
"properties": {
"galaxy": {
"description": "galaxy number",
"type": "integer"
},
"planet_id": {
"description": "measure distance from this planet; omit for your first",
"type": "integer"
},
"system": {
"description": "system number",
"type": "integer"
}
},
"required": [
"galaxy",
"system"
],
"type": "object"
}
invite_acs¶
Tier: commit.
Invite a commander to your ACS attack. Sends an in-game invitation; max 5 commanders including you.
{
"additionalProperties": false,
"properties": {
"group_id": {
"type": "integer"
},
"username": {
"type": "string"
}
},
"required": [
"group_id",
"username"
],
"type": "object"
}
join_acs¶
Tier: commit.
Send your own ships to an invited ACS attack. Target is read from the group. Up to 16 fleets and 5 commanders; a join may delay the remaining flight by at most 30%. Existing protection and attack limits apply. Each fleet keeps its own technologies, losses, cargo and return route.
{
"additionalProperties": false,
"properties": {
"cargo": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"confirm_ally": {
"description": "join even though the group's target is in your own alliance; without it the server refuses and names them",
"type": "boolean"
},
"group_id": {
"type": "integer"
},
"origin_planet_id": {
"type": "integer"
},
"ships": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"speed_percent": {
"type": "integer"
}
},
"required": [
"group_id",
"ships"
],
"type": "object"
}
join_alliance¶
Tier: commit.
Join an alliance.
{
"additionalProperties": false,
"properties": {
"alliance_id": {
"description": "the alliance id, from the alliances tool",
"type": "integer"
}
},
"required": [
"alliance_id"
],
"type": "object"
}
jump_gate¶
Tier: commit.
Move ships between two of your own moons instantly, with no flight and no fuel. Resources cannot go through, and both gates are out of action for an hour afterwards.
{
"additionalProperties": false,
"properties": {
"from_moon_id": {
"description": "the moon to send from",
"type": "integer"
},
"ships": {
"additionalProperties": {
"type": "integer"
},
"description": "ship key to count",
"type": "object"
},
"to_moon_id": {
"description": "the moon to send to",
"type": "integer"
}
},
"required": [
"from_moon_id",
"to_moon_id",
"ships"
],
"type": "object"
}
launch_missiles¶
Tier: commit.
Fire interplanetary missiles at another planet's defences. A missile ignores every shield, cannot be met by ships, takes no fleet slot and cannot be recalled, and what it destroys never rebuilds. The defender's anti-ballistic missiles each destroy exactly one of yours before any of it lands. Range is five systems per level of Impulse Drive, less one, inside your own galaxy only.
{
"additionalProperties": false,
"properties": {
"count": {
"description": "how many missiles to fire",
"type": "integer"
},
"order": {
"description": "which emplacements to hit first, by key; omit for dearest first",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"origin_planet_id": {
"description": "the planet whose silo fires; omit for your first",
"type": "integer"
},
"target_galaxy": {
"description": "target galaxy",
"type": "integer"
},
"target_moon": {
"description": "aim at the moon rather than the planet",
"type": "boolean"
},
"target_position": {
"description": "target position",
"type": "integer"
},
"target_system": {
"description": "target system",
"type": "integer"
}
},
"required": [
"target_galaxy",
"target_system",
"target_position",
"count"
],
"type": "object"
}
leaderboard¶
Tier: read.
The ranking, a page at a time. limit is how many rows (up to 500, default 100) and offset is where to start, so the whole ladder is readable in pages. Ranks are absolute: the first row of the second page is rank 101, not 1. For your own place and the players either side of you, standing is one call instead of hunting for yourself here. Rows with simulated true are the simulated population rather than people.
{
"additionalProperties": false,
"properties": {
"limit": {
"description": "how many rows to return; defaults to 100, capped at 500",
"type": "integer"
},
"offset": {
"description": "how many rows to skip; 100 starts the second page",
"type": "integer"
}
},
"type": "object"
}
leave_alliance¶
Tier: commit.
Leave an alliance. Rejoining is not automatic and may not be offered.
{
"additionalProperties": false,
"properties": {
"alliance_id": {
"description": "the alliance id, from the alliances tool",
"type": "integer"
}
},
"required": [
"alliance_id"
],
"type": "object"
}
mark_notices_read¶
Tier: commit.
Mark server notices as read, optionally only the given IDs. Does not mark player messages.
{
"additionalProperties": false,
"properties": {
"ids": {
"description": "server notice IDs to mark read; omit to acknowledge all server notices",
"items": {
"type": "integer"
},
"type": [
"null",
"array"
]
}
},
"type": "object"
}
messages¶
Tier: read.
The inbox, newest first. Narrow it: since_hours for a window, unread_only for what you have not seen, limit for how many. Bodies are included, so there is nothing else to fetch. Anything with no sender is the server: a quest paid, a fleet home, an attack, a moon formed, a missile strike.
{
"additionalProperties": false,
"properties": {
"limit": {
"description": "how many at most; omit for all of them",
"type": "integer"
},
"since_hours": {
"description": "only what arrived in the last N hours",
"type": "integer"
},
"unread_only": {
"description": "only what you have not read",
"type": "boolean"
}
},
"type": "object"
}
moon_status¶
Tier: read.
Inspect owned moons without spending: free fields, lunar base, phalanx level/range and 5000-deuterium scan affordability, jump gate readiness/cooldown and owned destination gates. Use phalanx_scan or jump_gate only for an authorized action. No mines, cargo teleportation or moon destruction mechanic.
{
"additionalProperties": false,
"properties": {
"moon_id": {
"description": "owned moon ID; omit to inspect every owned moon",
"type": "integer"
}
},
"type": "object"
}
next_event¶
Tier: read.
Wait for the server to say something happened, instead of asking again. Returns at once if anything is already queued, otherwise blocks up to timeout_seconds (default 30, up to 3600) and returns an empty list if nothing came. Pass kinds to sleep through everything else: with kinds=[queue.completed] a passing fleet no longer wakes you, though it is still returned when you do wake. An hour-long wait is meant for sleeping through a build; keep it under your client's own request timeout. Use it to sleep through a build or until traffic changes: queue.completed, fleet.incoming, fleet.returned, fleet.combat, planet.attacked and the rest arrive here. A fleet.incoming event is an early warning, but its payload is deliberately brief; read fleets for the attacker, route, arrival and the ship intelligence your Espionage Technology can resolve.
{
"additionalProperties": false,
"properties": {
"kinds": {
"description": "only wake for these event names, such as queue.completed; anything else that arrives is still returned",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"timeout_seconds": {
"description": "how long to wait; defaults to 30, capped at 3600",
"type": "integer"
}
},
"type": "object"
}
offer_trade¶
Tier: commit.
List resources for sale. The offered resource and enough large cargo to carry the larger leg leave the planet the moment the offer is listed, and stay out of play until somebody accepts it or you cancel. The two sides may differ by at most a 1:3 ratio. When a buyer accepts, the flight leaves immediately, burns your deuterium as fuel, takes one of your fleet slots and cannot be recalled, so max_hours is the real commitment here: it is the furthest delivery you are agreeing to fly. Say what is being locked away, and for how long a flight, before listing anything.
{
"additionalProperties": false,
"properties": {
"alliance_only": {
"description": "show it only to your own alliance",
"type": "boolean"
},
"max_hours": {
"description": "1-720: how long a delivery flight you will accept. A buyer further away than this cannot take the offer",
"type": "integer"
},
"offer_amount": {
"description": "how much of it to hand over",
"type": "integer"
},
"offer_resource": {
"description": "what you are giving: metal, crystal or deuterium",
"type": "string"
},
"planet_id": {
"description": "the planet the cargo leaves from; omit for your first",
"type": "integer"
},
"request_amount": {
"description": "how much of it you want",
"type": "integer"
},
"request_resource": {
"description": "what you want back; it has to be a different resource",
"type": "string"
}
},
"required": [
"offer_resource",
"offer_amount",
"request_resource",
"request_amount",
"max_hours"
],
"type": "object"
}
phalanx_scan¶
Tier: commit.
Read the fleets moving to and from one planet, from a moon with a sensor phalanx. Unlike ordinary incoming-fleet intelligence, it gives the exact composition regardless of Espionage Technology. It costs five thousand deuterium from that moon whether or not it finds anything, reaches level squared less one systems inside your own galaxy, and cannot read a moon.
{
"additionalProperties": false,
"properties": {
"galaxy": {
"description": "galaxy to scan",
"type": "integer"
},
"moon_id": {
"description": "the moon whose sensor phalanx is used",
"type": "integer"
},
"position": {
"description": "position to scan",
"type": "integer"
},
"system": {
"description": "system to scan",
"type": "integer"
}
},
"required": [
"moon_id",
"galaxy",
"system",
"position"
],
"type": "object"
}
planet_detail¶
Tier: read.
One planet in full: stocks, buildings, facilities, ships, defences and what is in its build queue. Every building row carries next_cost.energy (what the upgrade draws), energy_after and production_factor_after (what it leaves), and costs_production when it would slow every mine on the planet. Nothing refuses a mine for want of energy, so affordable means resources alone: read costs_production before spending. A moon comes back the same way with is_moon set: it mines nothing, started with one field, and only the lunar base, the sensor phalanx, the jump gate, robotics, the shipyard and the storages stand on it.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to read; omit for your first planet",
"type": "integer"
}
},
"type": "object"
}
preview_abandon_planet¶
Tier: read.
Inspect irreversible planet abandonment: the planet and its moon, lost assets and queues, blockers, replacement homeworld and the 24-48h coordinate cleanup deadline. Gives a five-minute confirmation token. This does not abandon anything. Show these consequences and obtain explicit approval for this named planet before abandon_planet.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "explicit owned planet ID, never a moon; no default",
"type": "integer"
}
},
"required": [
"planet_id"
],
"type": "object"
}
production_report¶
Tier: read.
Energy and resource production for a planet, including the production factor. A factor below 1 means the energy budget is short and every mine on the planet is running slow; that is the usual reason an empire has stopped growing.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to read; omit for your first planet",
"type": "integer"
}
},
"type": "object"
}
quests¶
Tier: read.
The quest ladder: every rung, how far along it you are, what it pays, and what it has already paid. Reading it is also what settles it: a finished rung is paid into the homeworld here, and the player is sent a note saying so, so call it after anything lands.
queue_research¶
Tier: spend.
Start a technology. Needs a research laboratory, and the tree says what is blocking anything that will not start. One research at a time per account, and not from a planet whose laboratory is being upgraded.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet whose laboratory runs it; omit for your first",
"type": "integer"
},
"tech": {
"description": "the technology key, for example energy or combustion_drive",
"type": "string"
}
},
"required": [
"tech"
],
"type": "object"
}
read_message¶
Tier: commit.
Open one message and mark it read. The inbox already carries every body, so reach for this only when you actually want it marked.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "the message id, from the messages tool",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
recall_fleet¶
Tier: commit.
Turn a fleet around. It still has to fly home, so a recall halfway out costs the same time again.
{
"additionalProperties": false,
"properties": {
"fleet_id": {
"description": "the fleet to turn around, from the fleets tool",
"type": "integer"
}
},
"required": [
"fleet_id"
],
"type": "object"
}
rename_planet¶
Tier: commit.
Give a planet a new name. Free, and each world can be renamed once a day. The name is shown to every other commander who looks at that system.
{
"additionalProperties": false,
"properties": {
"name": {
"description": "the new name, 3 to 24 characters",
"type": "string"
},
"planet_id": {
"description": "the planet to rename; omit for your first",
"type": "integer"
}
},
"required": [
"name"
],
"type": "object"
}
report_detail¶
Tier: read.
One combat, espionage or missile report with its full payload, by report ID.
{
"additionalProperties": false,
"properties": {
"id": {
"description": "report ID from reports",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
}
reports¶
Tier: read.
Battle, espionage and missile reports, newest first, each with its full payload. Narrow it: kind is combat, espionage or missile, since_hours for a window, limit for how many. Unfiltered this is every battle you have ever been in. A combat payload carries the rounds, both sides before and after, what stood back up, the loot and the debris; an espionage payload carries what the probes saw at their info level; a missile payload carries what was fired, intercepted, landed and destroyed.
{
"additionalProperties": false,
"properties": {
"kind": {
"description": "combat, espionage or missile; omit for all",
"type": "string"
},
"limit": {
"description": "how many at most; omit for all of them",
"type": "integer"
},
"since_hours": {
"description": "only what arrived in the last N hours",
"type": "integer"
}
},
"type": "object"
}
research_levels¶
Tier: read.
The commander's researched levels, flat. Cheaper than the tree when all you need is a number.
research_tree¶
Tier: read.
Every technology: its level, whether it is unlocked, and what is blocking it. in_progress lists what is being researched anywhere in the empire and when it finishes; research is account-wide, so it is the same list from every planet.
{
"additionalProperties": false,
"properties": {
"planet_id": {
"description": "the planet to read; omit for your first planet",
"type": "integer"
}
},
"type": "object"
}
rush_build¶
Tier: spend.
Finish the next thing in a build queue now, for 1 dark matter per minute of remaining time, with a minimum charge of 5. Only the first item of a line (construction, shipyard or research) can be rushed; everything behind it in that line moves up by the same amount. Omitting queue_id rushes whatever finishes soonest on your first planet.
{
"additionalProperties": false,
"properties": {
"queue_id": {
"description": "the queue item to finish; omit for the next thing on your first planet",
"type": "integer"
}
},
"type": "object"
}
send_alliance_message¶
Tier: commit.
Write to every current member of your alliance. A group of people reads this, and it cannot be taken back. Show the player the text before sending it.
{
"additionalProperties": false,
"properties": {
"body": {
"description": "what to say to the alliance",
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
}
send_message¶
Tier: commit.
Write to another commander. A person reads this, and it cannot be taken back. Show the player the text before sending it.
{
"additionalProperties": false,
"properties": {
"body": {
"description": "what to say",
"type": "string"
},
"to": {
"description": "the commander's name",
"type": "string"
}
},
"required": [
"to",
"body"
],
"type": "object"
}
server_stats¶
Tier: read.
Server-wide counters: universes, accounts, planets, fleets in the air.
simulate_combat¶
Tier: read.
Preview a battle using the live server resolver. Supply known ships, defenses and each ACS force's weapons/shielding/armour levels. No fleets are sent, no resources are spent, and no hidden target information is fetched. 1-20 runs, at most 20000 units, units times runs <= 200000. The result is a distribution, not a guarantee; stale or incomplete spy reports can change outcomes.
{
"additionalProperties": false,
"properties": {
"attackers": {
"items": {
"additionalProperties": false,
"properties": {
"armour": {
"type": "integer"
},
"defenses": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"shielding": {
"type": "integer"
},
"ships": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"weapons": {
"type": "integer"
}
},
"required": [
"ships",
"weapons",
"shielding",
"armour"
],
"type": "object"
},
"type": [
"null",
"array"
]
},
"defenders": {
"items": {
"additionalProperties": false,
"properties": {
"armour": {
"type": "integer"
},
"defenses": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"shielding": {
"type": "integer"
},
"ships": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"weapons": {
"type": "integer"
}
},
"required": [
"ships",
"weapons",
"shielding",
"armour"
],
"type": "object"
},
"type": [
"null",
"array"
]
},
"runs": {
"type": "integer"
},
"seed": {
"type": "integer"
}
},
"required": [
"attackers",
"defenders"
],
"type": "object"
}
standing¶
Tier: read.
Your own rank and score, with the players just above and just below you. This is what to read to know whether you are gaining, not the leaderboard.
{
"additionalProperties": false,
"properties": {
"span": {
"description": "how many players to show either side of you; defaults to 5",
"type": "integer"
}
},
"type": "object"
}
trade_offers¶
Tier: read.
The open market, nearest first. Every row carries travel_seconds, which is how long the seller's cargo would take to reach the planet you named and is the number that decides whether an offer is worth taking. Offers too far for the seller's own travel limit are already left out. Alliance-only offers appear once you are in the alliance that listed them. The market is per universe, so it is the same market from every planet you hold; only the distances move.
{
"additionalProperties": false,
"properties": {
"max_hours": {
"description": "only offers whose cargo would reach you within this many hours",
"type": "integer"
},
"mine": {
"description": "list your own open offers instead of other players'",
"type": "boolean"
},
"offered": {
"description": "only offers selling this resource: metal, crystal or deuterium. Omit for any",
"type": "string"
},
"planet_id": {
"description": "the planet that would trade; distances are measured from it. Omit for your first",
"type": "integer"
},
"scope": {
"description": "public or alliance; omit for both",
"type": "string"
},
"wanted": {
"description": "only offers asking for this resource: metal, crystal or deuterium. Omit for any",
"type": "string"
}
},
"type": "object"
}
units¶
Tier: read.
What is parked on a planet: kind=ships for the shipyard, kind=defense for the ground.
{
"additionalProperties": false,
"properties": {
"kind": {
"description": "ships or defense",
"type": "string"
},
"planet_id": {
"description": "the planet; omit for your first",
"type": "integer"
}
},
"required": [
"kind"
],
"type": "object"
}
upgrade_building¶
Tier: spend.
Queue the next level of a building, or several with count. Costs resources now and finishes later; check production_report first if the energy budget is short, because a new mine on a starved planet produces almost nothing. The construction line holds five levels and each is charged as it is queued; the shipyard is a separate line and does not count against it. The shipyard and nanite factory are refused while a ship or defence batch is queued, and the research laboratory while a research started from this planet runs.
{
"additionalProperties": false,
"properties": {
"building": {
"description": "the building key, for example metal_mine or solar_plant",
"type": "string"
},
"count": {
"description": "how many levels to queue; defaults to one",
"type": "integer"
},
"planet_id": {
"description": "the planet to build on; omit for your first",
"type": "integer"
}
},
"required": [
"building"
],
"type": "object"
}