Constants and values
What the engine places in your script before its first line. These are not functions: you read them, you do not call them, and none of them returns an error.
Some are real and useful. Others exist only so that a script coming from Ninja does not stop on an unknown symbol, and are worth nothing. The last section says which ones, because mixing them up is expensive.
The id arrays
| Value | Holds | |
|---|---|---|
ShipsArr | 16 ids | The ships, from the small cargo to the pathfinder. |
DefencesArr | 10 ids | The defences, both missiles included. |
TechnologiesArr | 16 ids | The researches, in the order of the game's tree. |
BuildingsArr | 23 ids | The buildings, planet and moon alike. |
PlanetBuildingsArr | 20 ids | The buildings of a planet. |
MoonBuildingsArr | 9 ids | The buildings of a moon, solar satellite included. |
OrionBuildingsArr | 8 ids | The Orion buildings: the anomaly scanner, then the seven of the Control Centre. Kept apart, so that a loop over BuildingsArr does not meet them on a universe that does not have them. |
LfBuildingsHumansArr LfBuildingsRocktalArr LfBuildingsMechasArr LfBuildingsKaeleshArr | 12 ids each | A race's lifeform buildings. |
LfTechnologiesHumansArr LfTechnologiesRocktalArr LfTechnologiesMechasArr LfTechnologiesKaeleshArr | 18 ids each | A race's lifeform research. |
LfTechnologiesArr | 72 ids | The research of all four races, in this order: Humans, Rock'tal, Mechas, Kaelesh. |
The order is guaranteed and does not change from one start to the next. So you can index into them, build a parallel array, or print a report always in the same order.
for id in ShipsArr {
Print(id) // prints "SmallCargo", not 202
}
An id prints as its name, and that name is in English whatever the language of your universe: it is hard-coded into the game library, not read from your pages. ID2Str(id) does the same thing explicitly, and returns Invalid(99999) for a number it does not know, rather than nothing at all.
SOLARSATELLITE is in BuildingsArr, not in ShipsArr. It is built at the shipyard, but the game counts it among the buildings, so a loop reading a planet's levels has to expect to find it there.
Each script gets its own copy of the four arrays. Sorting ShipsArr therefore disturbs no other script on the account. That said, you really are sorting your ShipsArr, for the whole life of your script.
sort = import("sort")
arr = ShipsArr // arr refers to the same array, not a copy
sort.Slice(arr, func(i, j) { return arr[i] < arr[j] })
// ShipsArr is sorted too, until this script ends.
The lifeform and celestial arrays follow Ninja's documentation, same names and same order, and every script gets its own copy of them too.
The id names
Every id in the four arrays has its named constant, and the other way round. They are written in upper case.
// Ships
SMALLCARGO LARGECARGO LIGHTFIGHTER HEAVYFIGHTER CRUISER
BATTLESHIP COLONYSHIP RECYCLER ESPIONAGEPROBE BOMBER
DESTROYER DEATHSTAR BATTLECRUISER CRAWLER REAPER
PATHFINDER
// Defences
ROCKETLAUNCHER LIGHTLASER HEAVYLASER GAUSSCANNON
IONCANNON PLASMATURRET SMALLSHIELDDOME LARGESHIELDDOME
ANTIBALLISTICMISSILES INTERPLANETARYMISSILES
// Technologies
ESPIONAGETECHNOLOGY COMPUTERTECHNOLOGY WEAPONSTECHNOLOGY
SHIELDINGTECHNOLOGY ARMOURTECHNOLOGY ENERGYTECHNOLOGY
HYPERSPACETECHNOLOGY COMBUSTIONDRIVE IMPULSEDRIVE
HYPERSPACEDRIVE LASERTECHNOLOGY IONTECHNOLOGY
PLASMATECHNOLOGY INTERGALACTICRESEARCHNETWORK
ASTROPHYSICS GRAVITONTECHNOLOGY
// Buildings
METALMINE CRYSTALMINE DEUTERIUMSYNTHESIZER SOLARPLANT
FUSIONREACTOR SOLARSATELLITE METALSTORAGE CRYSTALSTORAGE
DEUTERIUMTANK SHIELDEDMETALDEN UNDERGROUNDCRYSTALDEN SEABEDDEUTERIUMDEN
ALLIANCEDEPOT ROBOTICSFACTORY SHIPYARD RESEARCHLAB
MISSILESILO NANITEFACTORY TERRAFORMER SPACEDOCK
LUNARBASE SENSORPHALANX JUMPGATE
// Orion buildings
INTERSTELLARANOMALYSCANNER INTERGALACTICRECOVERYCENTRE
LITHIUMELECTROLYSISLAB METALRECYCLINGUNIT
CRYSTALFINISHINGSTATION ANOMALYANALYSISCENTRE
HIGHPRESSUREDEUTERIUMTANKS CATALYTICCONVERTOR
Lifeform buildings and research have their constant too, under the name Ninja gives them. BuildBuilding(c, RESIDENTIALSECTOR) and BuildTechnology(c, INTERGALACTICENVOYS) are therefore written as there.
// Humans : buildings
RESIDENTIALSECTOR BIOSPHEREFARM RESEARCHCENTRE
ACADEMYOFSCIENCES NEUROCALIBRATIONCENTRE HIGHENERGYSMELTING
FOODSILO FUSIONPOWEREDPRODUCTION SKYSCRAPER
BIOTECHLAB METROPOLIS PLANETARYSHIELD
// Humans : research
INTERGALACTICENVOYS HIGHPERFORMANCEEXTRACTORS FUSIONDRIVES
STEALTHFIELDGENERATOR ORBITALDEN RESEARCHAI
HIGHPERFORMANCETERRAFORMER ENHANCEDPRODUCTIONTECHNOLOGIES LIGHTFIGHTERMKII
CRUISERMKII IMPROVEDLABTECHNOLOGY PLASMATERRAFORMER
LOWTEMPERATUREDRIVES BOMBERMKII DESTROYERMKII
BATTLECRUISERMKII ROBOTASSISTANTS SUPERCOMPUTER
// Rock'tal : buildings
MEDITATIONENCLAVE CRYSTALFARM RUNETECHNOLOGIUM
RUNEFORGE ORIKTORIUM MAGMAFORGE
DISRUPTIONCHAMBER MEGALITH CRYSTALREFINERY
DEUTERIUMSYNTHESISER MINERALRESEARCHCENTRE ADVANCEDRECYCLINGPLANT
// Rock'tal : research
VOLCANICBATTERIES ACOUSTICSCANNING HIGHENERGYPUMPSYSTEMS
CARGOHOLDEXPANSIONCIVILIANSHIPS MAGMAPOWEREDPRODUCTION GEOTHERMALPOWERPLANTS
DEPTHSOUNDING IONCRYSTALENHANCEMENTHEAVYFIGHTER IMPROVEDSTELLARATOR
HARDENEDDIAMONDDRILLHEADS SEISMICMININGTECHNOLOGY MAGMAPOWEREDPUMPSYSTEMS
IONCRYSTALMODULES OPTIMISEDSILOCONSTRUCTIONMETHOD DIAMONDENERGYTRANSMITTER
OBSIDIANSHIELDREINFORCEMENT RUNESHIELDS ROCKTALCOLLECTORENHANCEMENT
// Mechas : buildings
ASSEMBLYLINE FUSIONCELLFACTORY ROBOTICSRESEARCHCENTRE
UPDATENETWORK QUANTUMCOMPUTERCENTRE AUTOMATISEDASSEMBLYCENTRE
HIGHPERFORMANCETRANSFORMER MICROCHIPASSEMBLYLINE PRODUCTIONASSEMBLYHALL
HIGHPERFORMANCESYNTHESISER CHIPMASSPRODUCTION NANOREPAIRBOTS
// Mechas : research
CATALYSERTECHNOLOGY PLASMADRIVE EFFICIENCYMODULE
DEPOTAI GENERALOVERHAULLIGHTFIGHTER AUTOMATEDTRANSPORTLINES
IMPROVEDDRONEAI EXPERIMENTALRECYCLINGTECHNOLOGY GENERALOVERHAULCRUISER
SLINGSHOTAUTOPILOT HIGHTEMPERATURESUPERCONDUCTORS GENERALOVERHAULBATTLESHIP
ARTIFICIALSWARMINTELLIGENCE GENERALOVERHAULBATTLECRUISER GENERALOVERHAULBOMBER
GENERALOVERHAULDESTROYER EXPERIMENTALWEAPONSTECHNOLOGY MECHANGENERALENHANCEMENT
// Kaelesh : buildings
SANCTUARY ANTIMATTERCONDENSER VORTEXCHAMBER
HALLSOFREALISATION FORUMOFTRANSCENDENCE ANTIMATTERCONVECTOR
CLONINGLABORATORY CHRYSALISACCELERATOR BIOMODIFIER
PSIONICMODULATOR SHIPMANUFACTURINGHALL SUPRAREFRACTOR
// Kaelesh : research
HEATRECOVERY SULPHIDEPROCESS PSIONICNETWORK
TELEKINETICTRACTORBEAM ENHANCEDSENSORTECHNOLOGY NEUROMODALCOMPRESSOR
NEUROINTERFACE INTERPLANETARYANALYSISNETWORK OVERCLOCKINGHEAVYFIGHTER
TELEKINETICDRIVE SIXTHSENSE PSYCHOHARMONISER
EFFICIENTSWARMINTELLIGENCE OVERCLOCKINGLARGECARGO GRAVITATIONSENSORS
OVERCLOCKINGBATTLESHIP PSIONICSHIELDMATRIX KAELESHDISCOVERERENHANCEMENT
Anywhere a function expects an id, the raw number works too: ID2Str(204) and ID2Str(LIGHTFIGHTER) give the same result.
Missions
| Constant | Value | |
|---|---|---|
ATTACK | 1 | |
GROUPEDATTACK | 2 | |
TRANSPORT | 3 | |
PARK | 4 | Park on a position of your own. |
PARKINTHATALLY | 5 | Park at an ally's. |
SPY | 6 | |
COLONIZE | 7 | |
RECYCLEDEBRISFIELD | 8 | |
DESTROY | 9 | Moon destruction. |
MISSILEATTACK | 10 | |
ANOMALYENCOUNTER | 14 | To an Orion anomaly: a destination of type ANOMALY_TYPE, the holding time in hours with SetDuration. On a universe without Orion, the game refuses. |
EXPEDITION | 15 | |
SEARCHFORLIFEFORMS | 18 | Displays as "SearchForLifeform", singular. |
Like the ids, a mission prints as its name: Print(EXPEDITION) prints "Expedition", not 15.
Speeds
Twenty steps in all. The ten whole ones run from TEN_PERCENT (value 1) to HUNDRED_PERCENT (value 10). The ten half steps slot in between: FIVE_PERCENT is 0.5, FIFTEEN_PERCENT is 1.5, and so on up to NINETY_FIVE_PERCENT, which is 9.5.
TEN_PERCENT TWENTY_PERCENT THIRTY_PERCENT FORTY_PERCENT FIFTY_PERCENT
SIXTY_PERCENT SEVENTY_PERCENT EIGHTY_PERCENT NINETY_PERCENT HUNDRED_PERCENT
FIVE_PERCENT FIFTEEN_PERCENT TWENTY_FIVE_PERCENT THIRTY_FIVE_PERCENT
FORTY_FIVE_PERCENT FIFTY_FIVE_PERCENT SIXTY_FIVE_PERCENT
SEVENTY_FIVE_PERCENT EIGHTY_FIVE_PERCENT NINETY_FIVE_PERCENT
The half steps are only offered in game to the General class. Kepler exposes them to everyone so that a script written for another account does not stop on them. A General account sends them as they are; an account of another class flies at the whole step below, and never under 10 % (FIFTY_FIVE_PERCENT flies at 50 %, FIVE_PERCENT at 10 %). FlightTime, GetDepartureTime and LowestSpeed compute that step, and SetSpeed on a NewFleet() keeps it: the calculation and the flight agree.
They are decimal numbers, and that is exactly what the speed parameter of FlightTime expects.
Celestial types, lifeforms, classes
| Constant | Value | |
|---|---|---|
PLANET_TYPE | 1 | |
DEBRIS_TYPE | 2 | The debris field of a position. |
MOON_TYPE | 3 | |
ANOMALY_TYPE | 4 | An Orion anomaly, written "[A:4:165:9]". |
NONE_LF_TYPE HUMANS ROCKTAL MECHAS KAELESH | 0 to 4 | Lifeforms. |
NO_CLASS COLLECTOR GENERAL DISCOVERER | 0 to 3 | Player class. |
NO_ALLIANCE_CLASS WARRIOR TRADER RESEARCHER | 0 to 3 | Alliance class. |
The celestial types are genuinely useful: NewCoordinate(4, 128, 6, MOON_TYPE) and GetEmpire(PLANET_TYPE) expect them.
The lifeforms and the classes are not. No function returns these values yet: nothing gives you a planet's lifeform, nor your player class, nor your alliance's, and the lifeform functions are missing (see the table of gaps in the introduction). So today these thirteen constants only serve to keep a script that names them from failing.
The dimensions of the universe
| Value | Holds | |
|---|---|---|
GALAXIES | an integer | The number of galaxies in your universe. |
SYSTEMS | an integer | The number of systems per galaxy. |
These two values are read from your universe's record, but only if the session is open at the moment the script starts. With no session, they are 9 and 499, which are the usual dimensions and not yours.
They are frozen when the script starts. A script launched before login will keep 9 and 499 for its whole life, even once the account is logged in. No function returns these two numbers on the fly: the only cure is to restart the script once logged in.
// Sweep a whole galaxy without hard-coding 499.
for sys = 1; sys <= SYSTEMS; sys++ {
infos, err = GalaxyInfos(4, sys)
if err != nil { LogWarn(err); continue }
SleepRandMs(400, 900)
}
The file, the server, the version
| Value | Holds | |
|---|---|---|
FILE __FILE__ | a string | The name of the current script, extension included: ma-ronde.ank. |
OGAME_SERVER | a record | The server: .Name, .Number, .Language, and .Settings. Fields empty with no session. |
VERSION __VERSION__ | a string | The Kepler version that is running, 1.82.606 for example. See below. |
OGAME_SERVER is not a string, it is a record, as in Ninja. The name of the universe reads OGAME_SERVER.Name.
Printf("%s (s%d-%s)", OGAME_SERVER.Name, OGAME_SERVER.Number, OGAME_SERVER.Language)
Print("economy speed:", OGAME_SERVER.Settings.EconomySpeed)
The available fields are Name, Number, Language, PlayerCount, PlayersOnline, Opened, StartDate, ServerClosed, Prefered, SignupClosed, and Settings. That last one carries the universe settings: EconomySpeed, FleetSpeedWar, FleetSpeedPeaceful, FleetSpeedHolding, UniverseSize, PlanetFields, DebrisFieldFactorShips, DebrisFieldFactorDefence, ResearchDurationDivisor, EspionageProbeRaids, WreckField, AKS, ServerLabel, ServerCategory, PremiumValidationGift.
EconomySpeed is not always a number. Depending on the universe, the game puts 8 or "x8" in it. Test before you count with it.
FILE is not there to separate your storage keys. Each script already has its own memory: two scripts storing the key last.system do not tread on each other, and prefixing protects nothing. FILE is there to name yourself, in an alert or a log line.
SendDiscord(MY_WEBHOOK, FILE + ": debris at " + coord)
In !global.ank, FILE is always !global.ank. A function defined over there reads the symbols of the environment where it was written, not of the one calling it: it will name itself !global.ank even when called from ma-ronde.ank.
OGAME_SERVER holds neither the address, nor the number, nor the language of the server, only the name of the universe. It is frozen when the script starts, like GALAXIES and SYSTEMS: a script launched before login will see it empty forever. To get the up-to-date value at the moment you need it, call the functions. GetUniverseName(), GetServerNumber() and GetLang() return a single value, empty or zero with no session. ServerURL() returns two: the address and an error.
VERSION is your bot's number, the one the interface shows and every update moves forward. A development build carries dev- followed by its commit there. Compare it against a Kepler number:
if VersionCompare(VERSION, "1.82.600") == -1 {
Print("this script needs Kepler 1.82.600 or newer")
Exit()
}
It is Kepler's number, not Ninja's. The guard many Ninja scripts put at the top, VersionCompare(VERSION, "0.91.8") == -1, passes here, since 1.82 comes after 0.91, but it says nothing about what the script really expects: the two numberings have nothing in common. Replace Ninja's number with the Kepler version that brings what the script needs.
Waiting for the stop: OnQuitCh
| Value | Holds | |
|---|---|---|
OnQuitCh | a channel | Closes when the script stops. |
Its normal use is to keep a script running after it has scheduled its tasks. Without it, the script reaches the end of its text and finishes: the screen shows it stopped, without the count of its tasks, and its OnExit runs at once. Its ExecAt and its CronExec do not stop for all that: they carry on without it, until they end, until the Stop button, until the script is started again or until the account stops. Once its last task is done, it lets go of its event channels. With <-OnQuitCh, the screen says the script is running, its channels stay open, and OnExit waits for the real end.
CronExec("0 3 * * *", func() { Print("it is three in the morning") })
<-OnQuitCh // blocks until the script stops
It closes on Exit(), on Terminate(), on the Stop button, and when the bot shuts down. Ninja only fires it on Exit; here, every stop closes it.
Two precautions:
- The lines that follow
<-OnQuitChdo not run. The channel only releases once the stop is under way, and the engine then refuses the next instruction. Write your farewell line before it, or in anOnExitfunction, which the bot calls afterwards, with its own grace period. - Never use it in
!global.ank. That file defines the shared environment, its channel never closes, and the wait would block the loading of the shared definitions for all your other scripts.
The offering and the licence
These values carry the names Ninja gives them, and they tell your install: where the bot runs, and how many bots your licence covers. Nothing more: what names you, yourself, stays empty (see below).
Six of them carry two names. Ninja writes them wrapped in double underscores, __IS_CLOUD__ rather than IS_CLOUD, and that is the form scripts from there use to read them. Both forms work here and give the same value.
| Value | Holds | What that implies |
|---|---|---|
IS_CLOUD __IS_CLOUD__ | a boolean | True on an instance we host, false on your computer. |
IS_SELF_HOST __IS_SELF_HOST__ | a boolean | The reverse: true when Kepler runs at your place. |
LICENSE_BOTS_ALLOWED __LICENSE_BOTS_ALLOWED__ | an integer | The number of bots the licence covers right now. Zero when it has expired or been refused. |
LICENSE_UUID __LICENSE_UUID__ | the empty string | Always empty, even with a licence installed. |
LICENSE_USERNAME __LICENSE_USERNAME__ | the empty string | Always empty: the licence holder is your account name on the shop, often your email address. |
LICENSE_EMAIL __LICENSE_EMAIL__ | the empty string | Always empty. |
CookieDomain | the empty string | In Ninja, a cloud instance carries its subdomain there. Kepler has no use for it. |
LICENSE_UUID, LICENSE_USERNAME and LICENSE_EMAIL stay empty, on purpose. Your email address serves as your login, on the shop as in the bot, and it must never be printed. A script gets copied from a forum, a friend or an AI, it runs with nobody in front of the screen, and it can send anything elsewhere through HttpRequest or SendDiscord: it is not handed what names you. The names still exist, as the empty string, so that a script coming from Ninja that prints them keeps running instead of stopping on undefined symbol.
They are read when the script starts. A licence extended or reduced while it runs changes nothing to what it reads: restart it to read again. On a development build, which asks for no licence, LICENSE_BOTS_ALLOWED is zero, with nothing capped.
if IS_CLOUD {
Print("hosted instance")
}
Printf("%d bot(s) covered by the licence", LICENSE_BOTS_ALLOWED)
DISCORD_WEBHOOK and TELEGRAM_CHAT_ID likewise carry what you filled in on the Notifications page, and SendDiscord(DISCORD_WEBHOOK, msg) goes out as is, with nothing more to configure. See notifications.
| Value | Holds | What that implies |
|---|---|---|
DISCORD_WEBHOOK | the Discord webhook from the Notifications page | Empty if none is set: SendDiscord then returns an error. |
TELEGRAM_CHAT_ID | the Telegram chat from the Notifications page | Zero if none is set. |