Account, galaxy, players and messages

Knowing who you are, looking at what sits in a system, recognising the other players, reading the highscore, and writing to someone.

The account

Rank is your place in the highscore, Total the number of ranked players.

A record from memory, not a reading. GetCachedPlayer asks the game for nothing, and therein lies its value as well as its limit: it returns what the bot retained from the last overview page it opened, and from no other. The nickname and the ID do not move, the points and the rank may be several minutes old.

Zero means "the reading failed". GetSlots queries the game, but returns only one value: it has no way of signalling a failure to you. With no session, or if the game answers oddly, it returns a struct that is entirely zero and writes the reason to the bot's log. The same holds for GetCachedPlayer. Zero free slots out of zero reads as "full" to any test, IsAllSlotsInUse included, so that no script will go and launch a fleet on that. It is deliberate.

Reading a system

The reading now goes through the version 13 door, in the same shape as before. The game closed the page the library was querying: it answered "error in retrieve galaxy infos", and GalaxyInfos was the last of the bot's readings left behind. It now borrows the same reading as the workers, then translates it back into the original shape, field for field. Not a line of your existing scripts has to change, except that the fields version 13 no longer serves come back empty rather than as an error: see the pitfalls below.

What a position holds

The pitfalls of the reading

nil means "nothing at all", not "no planet". A position holding nothing but a debris field returns a perfectly real record, with empty player fields. Test p.Player.ID == 0 for "nobody", p == nil for "deserted position". One edge case: a field that would hold deuterium alone, with neither metal nor crystal, is set aside and its position comes back nil.

A destroyed planet keeps a name, and .Destroyed does not say so. The game attaches it to a system account instead of removing it. Kepler wipes the player, the rank, the alliance and every state, but .Player.Name may still carry the game's replacement name. As for .Destroyed, it exists in the returned shape and is never filled: it is false on a destroyed planet just as on the others. A player ID of zero is the only test that does not mislead.

An activity of zero is not an absence of activity. It is an absence of display, and the game displays nothing past an hour. A player gone for three days and a player gone for sixty-one minutes return the same zero.

The alliance has nothing left but its tag. Version 13 no longer gives the name, the rank or the member count on this page. .Alliance.Name, .Alliance.ID, .Alliance.Rank and .Alliance.Member therefore still exist, and return the empty string or zero instead of an error, which is the lesser of two evils.

Long inactivity is not carried over. The game's reading tells the inactive player from the long-inactive one, but the shape returned to your script carries only an .Inactive, copied from the short flag alone. To tell the two apart, read the Status that PlayersData returns and look there for the capital I.

The reading exposes only three things: Position(i), Galaxy() and System(). The other members of the original shape are out of reach: sys.ExpeditionDebris stops on no member named 'ExpeditionDebris' for struct, and sys.Events and sys.Relocations do the same. It is a clean error, at run time, naming the field. Expedition debris, which sits on position 16, is not in the reading anyway.

A reading queues behind the workers. It goes through the account's queue, at ordinary priority, but not through the bot's rate pacer: it is up to your script to space its calls out if it sweeps a hundred systems.

Standing on a celestial, and why it matters

The celestial does not change what the reading says: a system holds the same planets seen from anywhere. It matters as soon as you want to act from that reading.

The game ties the action to the current planet, and the token it hands out with the reading is valid for that one. Reading from one and sending from another ends in a refusal — which nothing in the reading announces.

A single position

GetPlanetInfo reads the whole system and hands you one position: it therefore costs exactly one request, the same as GalaxyInfos. If you want several in the same system, call GalaxyInfos once and walk its result.

An empty position returns an error, not a zeroed record. That is deliberate: an empty record would read as a nameless planet belonging to player number zero, and a script comparing names or ranks would see a real target.

Going through several systems

These three functions ask the game for nothing: they compute. The galaxy wraps around, so a radius that overflows comes back from the other side, GetSystemsInRange(3, 3) starts at 499. The number of systems is your universe's; with no session, the computation falls back on 499 without saying so.

A difference with Ninja. Our Desc reverses the whole list, theirs reverses only the distances. Both return the same systems, farthest to nearest, but at equal distance the order of the two neighbours is swapped: we return [5 1 4 2 3] where their documentation announces [1 5 2 4 3]. Of no consequence for a sweep, awkward if you compare two logs.

The players

What a player holds

The parentheses trap, and it is a silent one. IsInactive, IsVacation and IsBanned are functions here, checkboxes in Ninja. Written without parentheses, if p.IsInactive { ... } raises no error at all: the condition is simply always false, and your script finds zero inactive players in a universe that holds two thousand.

The other field names differ too. Their short record carries IsAdmin, IsLongInactive, Vacation and AllianceID; ours carries Status and Alliance. A script copied over therefore stops on no member named 'Vacation' for struct, which at least shows up straight away. IsInactive is the only name common to both, and it is precisely the one that says nothing when written their way.

The full record, and what it costs. PlayerDataByID and PlayerDataByName return the rich record, with Ninja's names: PointsTotal, PointsEconomy, PointsResearch, PointsMilitary, PointsMilitaryBuilt, PointsMilitaryDestroyed, PointsMilitaryLost, PointsHonor, PointsLifeform, the nine matching Position..., MilitaryShips, Celestials and Alliance. PlayersData keeps the short record.

Alliance is nil when the player has none, and otherwise carries ID, Name and Tag. This is the only place in the bot that joins an alliance id to its tag: the version 13 galaxy reading only gives the tag.

Celestials carries the player's planets and their moons, each moon right after its own planet, with ID, Name and Coordinate. It is the only way to learn where someone lives without sweeping whole systems.

These two functions cost one request per player, kept for an hour, where PlayersData costs none. A script walking two thousand players should therefore start from PlayersData and ask for the full record only for the ones it keeps.

DefensivePoints() and OffensivePoints() split defence from fleet, which the game publishes nowhere: its military score mixes the two.

The calculation rests on one identity: defence is the only thing the game counts in full in both economy and military. The categories therefore overshoot the total by exactly the defence.

defence = economy + research + military + lifeform - total fleet = military - defence

Neither method exists in 1.82.239 or earlier: a bot that does not know them stops the script on the call.

The formula came from a client on 2026-09-22; Ninja's reference declares both functions and never gave the calculation. Checked on two accounts independently: on his, and here by pricing every single defence unit across the twenty celestials of an account. 168,476 points announced, 168,476 counted, to the unit.

Anti-ballistic missiles do count as defence, which was not obvious: they defend against no fleet, only against other missiles. The game's accounting puts them there anyway. Measured on a second account carrying 490 of them:

without the missiles: 2,695,268 -> off by 4,900 with the missiles: 2,700,168 -> exact

which is precisely their cost. Interplanetary missiles could not be measured: no account at hand has a single one. They sit on the same page and in the same silo, so they probably count too - but probably is not measured.

One caveat remains: a player whose file is a few hours old gives the figures of that moment, not of now. The game only regenerates it once a day.

DefensivePoints() never goes below zero: the integer score files round, and the subtraction can land at -1. The player file itself is fractional and does not trigger that case.

The military points are not in the order Ninja declares. Its list gives Built, Destroyed, Lost; the game orders types 4, 5 and 6 as lost, built, destroyed. Measured on forty players on 21/09/2026, through an identity that depends on no documentation: what a player has built equals what they still have plus what they have lost. The names are Ninja's, the values come from the right types.

The file is big, so it is kept for six hours. The game only regenerates it once a day. The first call downloads several hundred kilobytes, the following ones cost nothing, and every script on the account shares the same copy. A player who changes nickname can therefore stay known under the old one for six hours. PlayerDataByID and PlayerDataByName read that same copy; the second compares the whole nickname, not a fragment.

These readings go through the account's connection (so through its proxy), but not through its queue: they hold no worker back.

The highscore

Use HighscoreData. GetHighscore read the highscore page, and version 13 rewrote it: it now stops on failed to find site. It stays defined so that a script coming from elsewhere does not hit an unknown symbol, but it will return an error on every call.

HighscoreData queries the API the game publishes to be read. It returns the whole highscore in a single call, where the page gave a hundred, and will not break at the next version. In exchange, it gives nothing but IDs: the name is taken from PlayersData. Like PlayersData, it borrows the account's connection without going through its queue.

Each entry carries ID, Position, Score and Ships, the last of these being filled only by the military highscores.

category is 1 for players and 2 for alliances. typ picks the highscore: 0 the total, 1 the economy, 2 research, 3 military, then 4, 5 and 6 for losses, constructions and destructions. Beyond that, Ninja's documentation contradicts itself: its list names 9 "economy" when its own example gives that name to 1. Kepler does not interpret them, it copies them as they are into the API address: a test call settles it in a second, a bet is paid for in hours.

An alliance highscore will return alliance IDs, which PlayersData cannot name: it knows players only.

Each category/type pair is kept for an hour, separately from the others, because the game only recomputes the ranks once an hour. Comparing the economy with the military therefore does not make one re-download the other.

Reading a game page as it comes

Two additions Ninja does not have. They are there to show what the game really sends, when a parsing error does not say how the page has changed.

PageContent takes a string of parameters, not an address: what follows the ? in index.php. The request leaves through the account's session, so through its proxy, its cookies and its fingerprint, and through its queue.

An inexact page name holds the account up for several minutes. The game answers "An error has occured!", which the library takes for a disconnection: it reconnects and retries, ten times, doubling the wait up to a minute, and during that time neither the workers nor the screen get a turn. One spelling is corrected for you automatically, resourceSettings having become resourcesettings in version 13, and the correction can be read in the log. The others are yours.

FetchURL downloads a full address. ServerURL() gives you the root. FetchURL is capped at 4 MB, which is plenty for an interface file. Two things to know: it does not look at the response code, so that a server error page comes back to you as ordinary text, with no error; and a long read is interrupted if you stop the script.

HttpRequest is the same thing with the three pieces FetchURL lacks: the method, the headers and the response code.

The code is what you were missing for a backoff ladder. A 429 is retried after a pause, a 401 will never succeed on a retry, and without the code the two look alike: FetchURL would hand you the error page as ordinary text.

Headers are written as an ordinary table, nil if you have none. An empty body is not sent. The method is free - GET, POST, PUT, DELETE, PATCH - and an empty method means GET.

The response code is never an error: a 500 comes back with err at nil and code at 500. err is only filled when the request could not leave or could not come back. Test both.

Like FetchURL, it goes through the account's session - same proxy, same cookies, same fingerprint - which lets it post to the game's own endpoints, which a bare GET cannot reach. Talking to a third-party service carries none of your session: the cookie jar only serves the domain being addressed. The response is capped at 4 MB, like FetchURL.

Writing to a player

It takes an ID, not a nickname: go through PlayerDataByName or through the .Player.ID of a galaxy reading.

Sending goes through the version 13 form, the very one the bot uses for its own alerts. The chat token is kept from one message to the next, and found again on its own if it is refused: a campaign of three hundred messages does not reload three hundred pages. The errors, for their part, are clean: they say in what shape the token was read, and the start of what the game answered.

SendMessageAlliance does not exist yet.

Reports and the message box

This is the raw material of a hand-written farming script: without it, a script sees targets through the galaxy but never what they carry.

The summary carries ID, Target, Type, From and LootPercentage — not the resources: those are in the detailed report, which GetEspionageReport and GetEspionageReportFor return. That one also carries Username, IsInactive, LastActivity, and building levels when you sent enough probes to see them.

The tab numbers are the game's own: 20 espionage, 21 combat reports, 22 expeditions, 23 transport and unions, 24 the rest. Any other number is refused here rather than passed to the game, which would answer with its overview page, that is to say with nothing.

One page by default. GetEspionageReportMessages reads what a player sees when opening the box. Going through the whole history would cost one request per page without the script asking for it: that is what the variant taking a page count is for.

Counting your colonies

No error is returned: the count is read from the bot's memory, it costs no request. With no session open, two zeros and a line in the log.