Kepler. Documentation · Scripts 508 functions available right now Français

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

FunctionReturns
GetCachedPlayer()1: your own recordPlayerID, PlayerName, Points, Rank, Total, HonourPoints.
GetSlots()1: your fleet slotsInUse, Total, ExpInUse, ExpTotal.
ServerURL()2: an address and an errorYour server's address, with no trailing slash. A Kepler addition.
me = GetCachedPlayer()           // ONE target: this is a struct
Print(me.PlayerName, me.Points, "points, rank", me.Rank, "of", me.Total)

slots = GetSlots()               // ONE target as well
if slots.InUse >= slots.Total { Print("not one free slot left") }
if slots.IsAllSlotsInUse(EXPEDITION) { Print("expeditions all in use") }

addr, err = ServerURL()          // TWO targets
Print(addr)                      // https://s123-fr.ogame.gameforge.com

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.

Redeeming a Gameforge code

FunctionReturns
RedeemCode(code)1: an errorRedeems a code in the Gameforge lobby for the bot's account, a gift or a sitting code for instance: the « Redeem a Gameforge code » field of the Settings. A Kepler addition.
err = RedeemCode("XXXX-XXXX-XXXX")
if err != nil {
	LogWarn("redeeming the code:", err)
}

All of it goes through the bot's proxy, signing in to the lobby included when a session has to be opened, even with « Login only » ticked. The other requests of a script then go out directly; this one does not. A refusal from Gameforge comes back in the error, said plainly the way the official lobby says it, then as Gameforge returned it, in brackets: redeem refused: Gameforge does not recognise this code (400 Bad Request : ...): check ... for instance. If Gameforge first wants age verification on the account, the error says so too. Nothing is retried over another connection. The type Gameforge recognises in the code goes to the bot's log.

The bot's session first. The redeem presents the session the bot holds, without opening another one. It only opens one if Gameforge refuses that session and no bot of this Gameforge account is started, even asleep or waiting to reconnect: a fresh session could cut it off. Otherwise the error says so, and stopping those bots before trying again is enough. If a bot starts while the session opens, that session is set aside and the code is not submitted: the error says that too.

The button's brake holds for scripts. Three refused sign-ins in ten minutes for this Gameforge account, from the Settings button, a script or the « New bot » form, and RedeemCode returns for a quarter of an hour an error that says so, without sending anything. One redeem at a time per Gameforge account: one started during another is refused.

A lost answer is not a refusal. If the request went out but Gameforge's answer does not come back (timeout, gateway down), the error says Gameforge may have taken the code: check in the lobby before trying again.

The browser fingerprint

FunctionReturns
GetFingerprintNames()1: a list of namesThe entries of the fingerprint library that this bot's fingerprint setting describes. Empty when none matches.

It is the line of the Browser fingerprint panel, in the bot's settings, "General" tab, above the table: "This table matches the library fingerprint …". It names the entry that the bot's fingerprint setting describes, the one in the table, and the list marks it "(this bot)". An entry is copied into the bot when you apply it, and nothing keeps track of where it came from. The link is the machine: same system, same browser, same agent, same screen, same memory, same cores, same time zone, same languages, same colour depth, same navigator.vendor and same graphics card. It is also what the Bots column of the Fingerprints page counts.

A list, because two entries can describe the same machine. The bot then carries both, and the screen names them together. It is empty for a fingerprint drawn at random, read from this computer or made by hand, and for an entry edited since, even on its graphics card alone: the bot keeps its copy, which is no longer the same machine.

The setting, not the file. The game receives the bot's fingerprint file as long as it exists, and GetFingerprintNames does not read it: it compares the setting, like the line above the table. The orange line under the table ("The game still receives the fingerprint kept in this bot's file…") only compares part of the file with the setting: the memory, the cores, the time zone, the graphics card and the agent, each only when the setting fills it in. With no difference on those five, the grey line shows, even if the file differs on the system, the browser, the screen, the languages, the colour depth or the navigator.vendor. The file can differ from the setting in two cases. It can be older than the setting: "Apply" then deletes it, and the next sign-in rebuilds it from the chosen fingerprint. It can also be shared by two bots with the same e-mail and universe in two languages. It is then the one built by whichever of the two signed in first, from the setting it had at the time, and "Apply" does not delete it on either bot: the game keeps receiving it for both. Two bots can also carry one imported name: "Apply" then leaves the file to the other bot and moves this one to its account's name.

It asks the game for nothing and is read again on every call: a fingerprint applied from the screen shows on the next call. The game only receives it at the next sign-in, and only if no other bot already holds the file under this account's name.

names = GetFingerprintNames()
if len(names) == 0 {
	LogWarn("this bot carries no fingerprint from the library")
} else {
	Print("library fingerprint:", names[0])
}

Creating, applying and removing a fingerprint

FunctionReturns
NewFingerprint(name, system, region)2: the fingerprint and an error"+ New fingerprint" on the Fingerprints page: a machine drawn at random, then saved in the library.
GetFingerprint(name)1: the fingerprint, nil when there is noneThe sheet of a library entry, to read or to edit.
SaveFingerprint(fingerprint)1: an error"Save" on the sheet of an entry you have edited.
ApplyFingerprint(name)1: an error"Apply" in the Browser fingerprint panel: this bot will present that entry to the game.
DeleteFingerprint(name)1: an error✕ in the library: the entry of that name is removed from it, unless a bot carries it.

NewFingerprint does what the sheet does on the Fingerprints page, "+ New fingerprint" button: "Draw at random", then "Save the fingerprint". The sheet's three choices are its three arguments.

  • name is the entry's name. Empty, it is the first free "Machine N", as in the sheet.
  • system is "Windows", "Mac OS X", "Linux", "Android" or "iOS", in any case. Empty, it is drawn by its real share among the three computer systems: a phone only comes out when you ask for one. Any other name is refused.
  • region is a code from the sheet's "Region" list ("FR", "DE", "RS"…). It sets the time zone and the languages. Empty, it is the region of the bot's exit address on the Cloud, and elsewhere that of its universe's language: the sheet takes the panel's language, a script has a bot. An unknown code is refused.

The machine drawn is consistent from end to end, as in the sheet: the agent, the screen, the memory, the cores and, for a phone, the graphics card go together, and it differs from every library entry and every bot. The browser is Chrome, at a recent stable version, and Safari on an iPhone. The version comes from Chrome's release calendar, with a delay of one to fourteen days drawn for the machine: on 10/11/2026, 157 or 156.

A bot's Chrome updates itself, like a real browser, each on its own date. Every bot has its own delay behind the latest stable version, one to fourteen days, drawn once. It changes version at its first sign-in after its date, never during a session, and never in the same hour as another bot of the installation. Its log gives the planned date ("browser version change planned"), then the change ("the fingerprint's browser changes version", before and after). The library entries it carries follow it. A fingerprint taken from this computer does not climb on its own: it follows the player's Chrome when the panel reads it again, at the bot's next sign-in. None of this goes through a script.

A name already taken is never overwritten. NewFingerprint then returns the entry in place, unchanged, with an error that says so: a script run at every start does not draw a new machine each time. The fingerprint returned is never nil, even on failure.

Editing is GetFingerprint then SaveFingerprint, like "Edit" on the Fingerprints page. The fingerprint carries the sheet's fields.

Field
NameThe entry's name. It does not change: SaveFingerprint rewrites the entry of that name, and refuses a name the library does not have.
System, Browser, UserAgentThe system, the browser and the agent.
Memory, CoresThe memory in GB, that of navigator.deviceMemory, and the cores.
Width, Height, ColorDepthThe usable screen size and its colour depth.
Timezone, LanguagesThe time zone and the languages ("fr-FR,fr,en-US,en").
Vendor, Webglnavigator.vendor and the graphics card. Empty, the library works them out from the system.

SaveFingerprint saves what the browser would expose. The memory of a Safari, a Firefox or an iPhone is zero, since they have no navigator.deviceMemory; a Safari's cores are 4 or 8; a memory that the Chrome version does not report becomes the nearest one it does. The fingerprint you pass is read back as saved. A setting the sign-in could not build, an unknown time zone or a badly formed language, is refused with the error the sign-in would have given. The bots that already carry the entry keep their copy: editing it only counts for the bots you apply it to afterwards.

ApplyFingerprint is the "Apply" button, on the script's bot and on it alone. The setting changes at once, and GetFingerprintNames sees it on the next call. The game receives the new fingerprint at the next sign-in: the current session is not cut. The bot's fingerprint file is deleted so that it is rebuilt from the entry, unless it is also another bot's file. On the Cloud, an entry whose time zone is not that of the bot's exit address is redone at the next start, as if it had been applied from the screen.

What the screen asks for with a confirmation, ApplyFingerprint holds with two guards.

  • An entry the bot already carries does nothing, when its file presents it too or does not exist yet. The button rebuilds the file on every click; a script replayed at every start would give the game a new machine at every sign-in. The log only says "fingerprint applied by a script" when the fingerprint has changed.
  • This account's file is another bot's, the same account in two languages: refused, with an error that says so. The game would receive that file, not the entry asked for; the screen says it in its confirmation.

DeleteFingerprint is the library's ✕, the one on the Fingerprints page and in the Browser fingerprint panel. The entry of that name leaves the library; no fingerprint file is deleted. A name the library does not have is refused.

An entry a bot carries is refused, whichever bot it is, with an error that names them: they are the ones the Bots column of the Fingerprints page counts. The screen removes it after a confirmation, the bots keeping their copy; a script has nobody to confirm, and a clean-up script replayed at every start would empty the library of the machines you share between bots. To remove it anyway, use the screen.

"Draw a new fingerprint" and "Take this computer's fingerprint", in the Browser fingerprint panel, have no function: replayed by a script, they would give the game a new machine at every start.

None of these functions touches another bot's fingerprint: ApplyFingerprint takes no account, and never deletes another bot's file. Changing the fingerprint of an account already set up gets noticed, from a script as from the screen: do it at creation, or when it collides with another bot.

// A phone for this bot, once and for all: replayed, nothing changes
f, err = NewFingerprint("Living room phone", "Android", "FR")
if err != nil { LogWarn("fingerprint:", err) }
Print(f.Name, f.UserAgent, f.Memory, f.Width, f.Height)
err = ApplyFingerprint(f.Name)
if err != nil { LogError("apply:", err) }
// Clean-up: remove the entries no bot carries
for name in ["Machine 1", "Machine 2", "Machine 3"] {
	err = DeleteFingerprint(name)
	if err != nil { Print(name, ":", err) }
}
// Edit the screen of a library entry
f = GetFingerprint("Living room")
if f == nil {
	LogWarn("no \"Living room\" fingerprint in the library")
} else {
	f.Width = 1920
	f.Height = 1032
	err = SaveFingerprint(f)
	if err != nil { LogError("Living room:", err) }
}

Reading a system

FunctionReturns
GalaxyInfos(galaxy, system)2: the reading and an errorThe fifteen positions of a system.
GalaxyInfosUsing(galaxy, system, celestial)2: the reading and an errorThe same, standing on a celestial.
GetPlanetInfo(coordinate)2: the position and an errorA single position.
GetPlanetInfoUsing(coordinate, celestial)2: the position and an errorThe same, standing on a celestial.
CoordinatesAvailableForDiscoveryFleet(origin, galaxy, system)2: the list and an errorThe positions a lifeform expedition can be sent to, empty ones included. Empty list when there is none.
sys, err = GalaxyInfos(1, 224)         // TWO targets
if err != nil { LogError(err); return }

for i = 1; i <= 15; i++ {
	p = sys.Position(i)
	if p == nil { continue }           // position entirely empty
	if p.Player.ID == 0 {
		// nobody: a lone debris field, or a destroyed planet
		Print(i, "unowned", p.Debris.Metal)
		continue
	}
	Print(p.Coordinate, p.Name, p.Player.Name, p.Activity)
}
// [P:1:224:8] Colony III Xylo 15

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

FieldHolds
.ID, .NameThe planet. Empty on a position that holds nothing but a debris field.
.CoordinateWritten [P:1:224:8]. The type is always P, even when the position holds a moon.
.Activity0: nothing to report. 15: active right now. 16 to 59: the minutes elapsed, copied exactly as the game counts them.
.Player.ID, .Player.Name, .Player.RankThe owner and his place in the highscore.
.Inactive, .Vacation, .Banned, .Newbie, .StrongPlayer, .HonorableTarget, .AdministratorThe player's states.
.Player.IsBandit, .Player.IsStarlordThe two ends of the honour rank.
.Debris.Metal, .Debris.Crystal, .Debris.Deuterium, .Debris.RecyclersNeededThe debris field, with the number of recyclers the game announces.
.Moonnil, or .ID, .Diameter, .Activity. .Moon.Name exists and stays empty.
.Alliancenil, or .Tag.
.DestroyedExists, and is always false. See below.

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

c = GetCachedCelestial("1:2:3")
sys, err = GalaxyInfosUsing(4, 116, c.GetID())

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

p, err = GetPlanetInfo("4:116:6")
if err != nil {
	Print("nobody there:", err)      // no planet at [P:4:116:6]
} else {
	Print(p.Name, p.Player.Name, p.Activity)
}

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

FunctionReturns
GetSystemsInRange(origin, radius)1: a list of systemsIn order of number.
GetSystemsInRangeAsc(origin, radius)1: a list of systemsNearest to farthest.
GetSystemsInRangeDesc(origin, radius)1: a list of systemsFarthest to nearest.
Print(GetSystemsInRange(3, 2))       // [1 2 3 4 5]
Print(GetSystemsInRangeAsc(3, 2))    // [3 2 4 1 5]
Print(GetSystemsInRangeDesc(3, 2))   // [5 1 4 2 3]

for s in GetSystemsInRangeAsc(224, 15) {
	sys, err = GalaxyInfos(1, s)
	if err != nil { LogWarn(s, err); continue }
	SleepRandMs(500, 1200)           // space them out, nothing will do it for you
}

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

FunctionReturns
PlayersData()2: the list and an errorEvery player in the universe.
PlayerDataByID(id)2: a player and an errorClean error if the ID is unknown.
PlayerDataByName(name)2: a player and an errorWhole nickname, case is ignored.

What a player holds

FieldHolds
ID, NameThe ID and the nickname, as the game publishes them.
StatusThe game's string of letters. It is the only complete source.
AllianceThe ID of his alliance, 0 when he has none.
IsInactive()True if the status carries an i or an I: short inactivity as well as long.
IsVacation()True if the status carries a v.
IsBanned()True if the status carries a b.
DefensivePoints()His defence points, which the game does not publish. Rich record only.
OffensivePoints()His fleet, that is military minus defence. Rich record only.
players, err = PlayersData()          // TWO targets
if err != nil { LogError(err); return }

n = 0
for p in players {
	if p.IsInactive() { n++ }         // the parentheses matter, see below
}
Print(n, "inactive out of", len(players))

target, err = PlayerDataByName("Xylo")
if err != nil { Print("no such player") } else { Print(target.ID) }

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.

if p.IsInactive  { ... }   // ✗ never true, never reported
if p.IsInactive() { ... }  // ✓

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.

p, err = PlayerDataByID(id)
Print(p.DefensivePoints())        // his defence points
Print(p.OffensivePoints())        // his fleet, so what can actually fly

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

FunctionReturns
HighscoreData(category, typ)2: the whole highscore and an errorThrough the game's API. IDs, not names.
GetHighscore(category, typ, page)2: a page and an errorThe game's highscore page, a hundred players, with their home planet.

The two complete each other. HighscoreData returns the whole highscore in one call, through the game's API, but only IDs. GetHighscore reads the highscore page as the game shows it: each entry of Players carries Position, ID, Name, Score and Homeworld, the home planet that the player's name opens in the galaxy. It is the only reliable source for the home planet.

NbPage is the next page as long as the page read is full, and the page read when it is the last one: the "while page < NbPage" loop of scripts coming from Ninja therefore stops at the right place. AllianceID, HonourPoints and Ships are not filled in.

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.

ranks, err = HighscoreData(1, 0)      // players, general highscore
if err != nil { LogError(err); return }

players, err = PlayersData()
if err != nil { LogError(err); return }

names = {}
for p in players { names[p.ID] = p.Name }

for r in ranks {
	if r.Position <= 10 { Print(r.Position, names[r.ID], r.Score) }
}

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.

FunctionReturns
PageContent(query)2: the text and an errorA game page, through the account's session.
FetchURL(url)2: the text and an errorAny address, through the same session.
HttpRequest(method, url, headers, body)3: the text, the code and an errorA full request, through the same session.
html, err = PageContent("page=ingame&component=overview")
if err != nil { LogError(err); return }
Print(len(html), "bytes")

regexp = import("regexp")
r = regexp.MustCompile(`var site = (\d+)`)
Print(r.FindStringSubmatch(html))

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.

headers = {}
headers["Authorization"] = "Bearer " + token
headers["Content-Type"] = "application/json"

payload, err = JsonEncode({"celestial": 33628068})
if err != nil { LogError(err); return }

body, code, err = HttpRequest("POST", "https://example.net/api", headers, payload)
if err != nil { LogError(err); return }       // ← THREE targets

if code == 429 {
    Sleep(60)                                 // too fast: we will retry
    return
}
if code == 401 {
    LogError("token refused")                 // no point retrying
    return
}
Print(code, len(body))

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

FunctionReturns
SendMessage(playerID, message)1: an errorA private message, through the game's chat.
target, err = PlayerDataByName("Xylo")
if err != nil { LogError(err); return }

err = SendMessage(target.ID, "Hello, I come in peace.")
if err != nil { LogError("message refused:", err) }

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.

FunctionReturns
GetEspionageReportMessages()2: the list and an errorThe summary of each report on the first page.
GetEspionageReportMessagesPages(pages)2: the list and an errorThe same, across several pages.
GetEspionageReport(msgID)2: the report and an errorThe detailed report of a message.
GetEspionageReportFor(coordinate)2: the report and an errorThe latest report on that position.
GetCombatReportSummaryFor(coordinate)2: the summary and an errorThe latest fight at that position.
DeleteMessage(msgID)1: an errorDeletes one message for good, trash included.
DeleteAllMessagesFromTab(tab)1: an errorMoves a whole tab to the trash.
summaries, err = GetEspionageReportMessages()
if err != nil { LogError("box:", err) }
for m in summaries {
  Print(m.ID, m.Target, "loot", m.LootPercentage)
}

report, err = GetEspionageReportFor("1:2:3")
if err == nil {
  Print(report.Username, "inactive:", report.IsInactive)
  Print("metal:", report.Metal, "crystal:", report.Crystal)
}

detail, err = GetEspionageReport(summaries[0].ID)
Print(detail.Username, err)

fight, err = GetCombatReportSummaryFor("1:2:3")
if err == nil { Print("loot:", fight.Loot, fight.AttackerName) }

older, err = GetEspionageReportMessagesPages(3)
Print("over three pages:", len(older))

DeleteMessage(summaries[0].ID)
DeleteAllMessagesFromTab(20)

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.

DeleteMessage never puts a message back in the inbox. The game's "delete" button is a toggle: on a message already in the trash, it puts it back in the inbox. So DeleteMessage first looks for where the message is, in the inbox then in the trash of those five tabs. In the inbox, it deletes it and then clears it from the trash; already in the trash, it only removes it from there. That is what the trash button of the Reports page does.

A message that is in none of the five tabs is not touched, and the error says so. The search costs reads of the messages: a single one for a recent espionage report, more for a message filed far back.

DeleteAllMessagesFromTab, for its part, moves the tab's inbox to the trash without emptying it: purging the whole trash would also take away the "you have been spied on" notices and whatever you put there yourself.

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

FunctionReturns
CountColonies()2: the count and the maximumWhat you have, what you may have.
count, possible = CountColonies()
Print(count, "colonies out of", possible)

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.