Kepler. Documentation · Scripts 508 fonctions disponibles actuellement English

Constantes et valeurs

Ce que le moteur pose dans votre script avant sa première ligne. Ce ne sont pas des fonctions : on les lit, on ne les appelle pas, et aucune ne rend d'erreur.

Certaines sont vraies et utiles. D'autres existent uniquement pour qu'un script venu de Ninja ne s'arrête pas sur un symbole inconnu, et ne valent rien. La dernière section dit lesquelles, parce que les confondre coûte cher.

Les tableaux d'identifiants

ValeurContient
ShipsArr16 identifiantsLes vaisseaux, du petit transporteur à l'éclaireur.
DefencesArr10 identifiantsLes défenses, les deux missiles compris.
TechnologiesArr16 identifiantsLes recherches, dans l'ordre de l'arbre du jeu.
BuildingsArr23 identifiantsLes bâtiments, planète et lune confondues.
PlanetBuildingsArr20 identifiantsLes bâtiments d'une planète.
MoonBuildingsArr9 identifiantsLes bâtiments d'une lune, satellite solaire compris.
OrionBuildingsArr8 identifiantsLes bâtiments d'Orion : le scanner d'anomalies, puis les sept du Centre de contrôle. À part, pour qu'une boucle sur BuildingsArr ne les voie pas passer sur un univers qui ne les a pas.
LfBuildingsHumansArr LfBuildingsRocktalArr LfBuildingsMechasArr LfBuildingsKaeleshArr12 identifiants chacunLes bâtiments de forme de vie d'une race.
LfTechnologiesHumansArr LfTechnologiesRocktalArr LfTechnologiesMechasArr LfTechnologiesKaeleshArr18 identifiants chacunLes recherches de forme de vie d'une race.
LfTechnologiesArr72 identifiantsLes recherches des quatre races, dans cet ordre : humains, Rock'tal, Mechas, Kaelesh.

L'ordre est garanti et ne change pas d'un démarrage à l'autre. Vous pouvez donc indexer, construire un tableau parallèle, ou afficher un rapport toujours dans le même ordre.

for id in ShipsArr {
	Print(id)          // écrit « SmallCargo », pas 202
}

Un identifiant s'affiche sous son nom, et ce nom est en anglais quelle que soit la langue de votre univers : il est écrit en dur dans la bibliothèque de jeu, pas lu sur vos pages. ID2Str(id) fait la même chose explicitement, et rend Invalid(99999) pour un numéro qu'elle ne connaît pas, plutôt que du vide.

SOLARSATELLITE est dans BuildingsArr, pas dans ShipsArr. Il se construit au chantier spatial, mais le jeu le compte parmi les bâtiments, et une boucle qui relève les niveaux d'une planète doit donc le voir passer là.

Chaque script reçoit sa propre copie des quatre tableaux. Trier ShipsArr ne dérange donc aucun autre script du compte. En revanche vous triez bien votre ShipsArr, pour toute la durée de votre script.

sort = import("sort")
arr = ShipsArr                 // arr désigne le même tableau, pas une copie
sort.Slice(arr, func(i, j) { return arr[i] < arr[j] })
// ShipsArr est trié lui aussi, jusqu'à la fin de ce script.

Les tableaux des formes de vie et des célestes suivent la doc de Ninja, mêmes noms et même ordre, et chaque script en reçoit aussi sa copie.

Les noms d'identifiants

Chaque identifiant des quatre tableaux a sa constante nommée, et réciproquement. Elles s'écrivent en majuscules.

// Vaisseaux
SMALLCARGO   LARGECARGO   LIGHTFIGHTER   HEAVYFIGHTER   CRUISER
BATTLESHIP   COLONYSHIP   RECYCLER       ESPIONAGEPROBE BOMBER
DESTROYER    DEATHSTAR    BATTLECRUISER  CRAWLER        REAPER
PATHFINDER

// Défenses
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

// Bâtiments
METALMINE        CRYSTALMINE       DEUTERIUMSYNTHESIZER  SOLARPLANT
FUSIONREACTOR    SOLARSATELLITE    METALSTORAGE          CRYSTALSTORAGE
DEUTERIUMTANK    SHIELDEDMETALDEN  UNDERGROUNDCRYSTALDEN SEABEDDEUTERIUMDEN
ALLIANCEDEPOT    ROBOTICSFACTORY   SHIPYARD              RESEARCHLAB
MISSILESILO      NANITEFACTORY     TERRAFORMER           SPACEDOCK
LUNARBASE        SENSORPHALANX     JUMPGATE

// Bâtiments d'Orion
INTERSTELLARANOMALYSCANNER  INTERGALACTICRECOVERYCENTRE
LITHIUMELECTROLYSISLAB      METALRECYCLINGUNIT
CRYSTALFINISHINGSTATION     ANOMALYANALYSISCENTRE
HIGHPRESSUREDEUTERIUMTANKS  CATALYTICCONVERTOR

Les bâtiments et recherches des formes de vie ont aussi leur constante, sous le nom que leur donne Ninja. BuildBuilding(c, RESIDENTIALSECTOR) et BuildTechnology(c, INTERGALACTICENVOYS) s'écrivent donc comme chez eux.

// Humains : bâtiments
RESIDENTIALSECTOR       BIOSPHEREFARM           RESEARCHCENTRE
ACADEMYOFSCIENCES       NEUROCALIBRATIONCENTRE  HIGHENERGYSMELTING
FOODSILO                FUSIONPOWEREDPRODUCTION SKYSCRAPER
BIOTECHLAB              METROPOLIS              PLANETARYSHIELD

// Humains : recherches
INTERGALACTICENVOYS            HIGHPERFORMANCEEXTRACTORS      FUSIONDRIVES
STEALTHFIELDGENERATOR          ORBITALDEN                     RESEARCHAI
HIGHPERFORMANCETERRAFORMER     ENHANCEDPRODUCTIONTECHNOLOGIES LIGHTFIGHTERMKII
CRUISERMKII                    IMPROVEDLABTECHNOLOGY          PLASMATERRAFORMER
LOWTEMPERATUREDRIVES           BOMBERMKII                     DESTROYERMKII
BATTLECRUISERMKII              ROBOTASSISTANTS                SUPERCOMPUTER

// Rock'tal : bâtiments
MEDITATIONENCLAVE      CRYSTALFARM            RUNETECHNOLOGIUM
RUNEFORGE              ORIKTORIUM             MAGMAFORGE
DISRUPTIONCHAMBER      MEGALITH               CRYSTALREFINERY
DEUTERIUMSYNTHESISER   MINERALRESEARCHCENTRE  ADVANCEDRECYCLINGPLANT

// Rock'tal : recherches
VOLCANICBATTERIES                 ACOUSTICSCANNING                  HIGHENERGYPUMPSYSTEMS
CARGOHOLDEXPANSIONCIVILIANSHIPS   MAGMAPOWEREDPRODUCTION            GEOTHERMALPOWERPLANTS
DEPTHSOUNDING                     IONCRYSTALENHANCEMENTHEAVYFIGHTER IMPROVEDSTELLARATOR
HARDENEDDIAMONDDRILLHEADS         SEISMICMININGTECHNOLOGY           MAGMAPOWEREDPUMPSYSTEMS
IONCRYSTALMODULES                 OPTIMISEDSILOCONSTRUCTIONMETHOD   DIAMONDENERGYTRANSMITTER
OBSIDIANSHIELDREINFORCEMENT       RUNESHIELDS                       ROCKTALCOLLECTORENHANCEMENT

// Mechas : bâtiments
ASSEMBLYLINE               FUSIONCELLFACTORY          ROBOTICSRESEARCHCENTRE
UPDATENETWORK              QUANTUMCOMPUTERCENTRE      AUTOMATISEDASSEMBLYCENTRE
HIGHPERFORMANCETRANSFORMER MICROCHIPASSEMBLYLINE      PRODUCTIONASSEMBLYHALL
HIGHPERFORMANCESYNTHESISER CHIPMASSPRODUCTION         NANOREPAIRBOTS

// Mechas : recherches
CATALYSERTECHNOLOGY             PLASMADRIVE                     EFFICIENCYMODULE
DEPOTAI                         GENERALOVERHAULLIGHTFIGHTER     AUTOMATEDTRANSPORTLINES
IMPROVEDDRONEAI                 EXPERIMENTALRECYCLINGTECHNOLOGY GENERALOVERHAULCRUISER
SLINGSHOTAUTOPILOT              HIGHTEMPERATURESUPERCONDUCTORS  GENERALOVERHAULBATTLESHIP
ARTIFICIALSWARMINTELLIGENCE     GENERALOVERHAULBATTLECRUISER    GENERALOVERHAULBOMBER
GENERALOVERHAULDESTROYER        EXPERIMENTALWEAPONSTECHNOLOGY   MECHANGENERALENHANCEMENT

// Kaelesh : bâtiments
SANCTUARY             ANTIMATTERCONDENSER   VORTEXCHAMBER
HALLSOFREALISATION    FORUMOFTRANSCENDENCE  ANTIMATTERCONVECTOR
CLONINGLABORATORY     CHRYSALISACCELERATOR  BIOMODIFIER
PSIONICMODULATOR      SHIPMANUFACTURINGHALL SUPRAREFRACTOR

// Kaelesh : recherches
HEATRECOVERY                  SULPHIDEPROCESS               PSIONICNETWORK
TELEKINETICTRACTORBEAM        ENHANCEDSENSORTECHNOLOGY      NEUROMODALCOMPRESSOR
NEUROINTERFACE                INTERPLANETARYANALYSISNETWORK OVERCLOCKINGHEAVYFIGHTER
TELEKINETICDRIVE              SIXTHSENSE                    PSYCHOHARMONISER
EFFICIENTSWARMINTELLIGENCE    OVERCLOCKINGLARGECARGO        GRAVITATIONSENSORS
OVERCLOCKINGBATTLESHIP        PSIONICSHIELDMATRIX           KAELESHDISCOVERERENHANCEMENT

Partout où une fonction attend un identifiant, le numéro brut passe aussi : ID2Str(204) et ID2Str(LIGHTFIGHTER) donnent le même résultat.

Missions

ConstanteValeur
ATTACK1
GROUPEDATTACK2
TRANSPORT3
PARK4Stationner sur une position à soi.
PARKINTHATALLY5Stationner chez un allié.
SPY6
COLONIZE7
RECYCLEDEBRISFIELD8
DESTROY9Destruction de lune.
MISSILEATTACK10
ANOMALYENCOUNTER14Vers une anomalie d'Orion : une destination de type ANOMALY_TYPE, le maintien en heures par SetDuration. Sur un univers sans Orion, le jeu refuse.
EXPEDITION15
SEARCHFORLIFEFORMS18S'affiche « SearchForLifeform », au singulier.

Comme les identifiants, une mission s'affiche sous son nom : Print(EXPEDITION) écrit « Expedition », pas 15.

Vitesses

Vingt paliers en tout. Les dix entiers vont de TEN_PERCENT (valeur 1) à HUNDRED_PERCENT (valeur 10). Les dix demi-points s'intercalent : FIVE_PERCENT vaut 0,5, FIFTEEN_PERCENT 1,5, et ainsi jusqu'à NINETY_FIVE_PERCENT, qui vaut 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

Les demi-points ne sont proposés en jeu qu'à la classe Général. Kepler les expose à tout le monde pour qu'un script écrit pour un autre compte ne s'arrête pas dessus. Un compte Général les envoie tels quels ; un compte d'une autre classe part au cran entier inférieur, et jamais sous 10 % (FIFTY_FIVE_PERCENT part à 50 %, FIVE_PERCENT à 10 %). FlightTime, GetDepartureTime et LowestSpeed chiffrent ce cran-là, et SetSpeed sur un NewFleet() le retient : le calcul et le vol tombent d'accord.

Ce sont des nombres décimaux, et c'est exactement ce qu'attend le paramètre de vitesse de FlightTime.

Types de céleste, formes de vie, classes

ConstanteValeur
PLANET_TYPE1
DEBRIS_TYPE2Le champ de débris d'une position.
MOON_TYPE3
ANOMALY_TYPE4Une anomalie d'Orion, qui s'écrit "[A:4:165:9]".
NONE_LF_TYPE HUMANS ROCKTAL MECHAS KAELESH0 à 4Formes de vie.
NO_CLASS COLLECTOR GENERAL DISCOVERER0 à 3Classe de jeu.
NO_ALLIANCE_CLASS WARRIOR TRADER RESEARCHER0 à 3Classe d'alliance.

Les types de céleste servent vraiment : NewCoordinate(4, 128, 6, MOON_TYPE) et GetEmpire(PLANET_TYPE) les attendent.

Les formes de vie et les classes, non. Aucune fonction ne rend encore ces valeurs : rien ne donne la forme de vie d'une planète, ni votre classe de jeu, ni celle de votre alliance, et les fonctions de formes de vie sont absentes (voir le tableau des manques dans l'introduction). Ces treize constantes ne servent donc aujourd'hui qu'à ne pas faire échouer un script qui les nomme.

Les dimensions de l'univers

ValeurContient
GALAXIESun entierLe nombre de galaxies de votre univers.
SYSTEMSun entierLe nombre de systèmes par galaxie.

Ces deux valeurs sont lues sur la fiche de votre univers, mais seulement si la session est ouverte au moment où le script démarre. Sans session, elles valent 9 et 499, qui sont les dimensions habituelles et non les vôtres.

Elles sont figées au démarrage du script. Un script lancé avant la connexion gardera 9 et 499 pour toute sa vie, même une fois le compte connecté. Aucune fonction ne rend ces deux nombres à la volée : le seul remède est de relancer le script une fois connecté.

// Balayer une galaxie entière sans coder 499 en dur.
for sys = 1; sys <= SYSTEMS; sys++ {
	infos, err = GalaxyInfos(4, sys)
	if err != nil { LogWarn(err); continue }
	SleepRandMs(400, 900)
}

Le fichier, le serveur, la version

ValeurContient
FILE __FILE__une chaîneLe nom du script courant, extension comprise : ma-ronde.ank.
OGAME_SERVERune ficheLe serveur : .Name, .Number, .Language, et .Settings. Champs vides sans session.
VERSION __VERSION__une chaîneLa version de Kepler qui tourne, 1.82.606 par exemple. Voir plus bas.

OGAME_SERVER n'est pas une chaîne, c'est une fiche, comme chez Ninja. Le nom de l'univers s'y lit OGAME_SERVER.Name.

Printf("%s (s%d-%s)", OGAME_SERVER.Name, OGAME_SERVER.Number, OGAME_SERVER.Language)
Print("vitesse d'économie :", OGAME_SERVER.Settings.EconomySpeed)

Les champs disponibles sont Name, Number, Language, PlayerCount, PlayersOnline, Opened, StartDate, ServerClosed, Prefered, SignupClosed, et Settings. Ce dernier porte les réglages de l'univers : EconomySpeed, FleetSpeedWar, FleetSpeedPeaceful, FleetSpeedHolding, UniverseSize, PlanetFields, DebrisFieldFactorShips, DebrisFieldFactorDefence, ResearchDurationDivisor, EspionageProbeRaids, WreckField, AKS, ServerLabel, ServerCategory, PremiumValidationGift.

EconomySpeed n'est pas toujours un nombre. Selon l'univers, le jeu y met 8 ou "x8". Testez avant de compter avec.

FILE ne sert pas à séparer vos clés de stockage. Chaque script a déjà sa propre mémoire : deux scripts qui rangent la clé dernier.systeme ne se marchent pas dessus, et préfixer ne protège de rien. FILE sert à se nommer, dans une alerte ou une ligne de journal.

SendDiscord(MON_WEBHOOK, FILE + " : débris à " + coord)

Dans !global.ank, FILE vaut toujours !global.ank. Une fonction définie là-bas lit les symboles de l'environnement où elle a été écrite, pas de celui qui l'appelle : elle se nommera !global.ank même appelée depuis ma-ronde.ank.

OGAME_SERVER ne contient ni l'adresse, ni le numéro, ni la langue du serveur, seulement le nom de l'univers. Il est figé au démarrage du script, comme GALAXIES et SYSTEMS : un script lancé avant la connexion le verra vide pour toujours. Pour obtenir la valeur à jour au moment où vous en avez besoin, appelez les fonctions. GetUniverseName(), GetServerNumber() et GetLang() rendent une valeur seule, vide ou nulle sans session. ServerURL() en rend deux : l'adresse et une erreur.

VERSION est le numéro de votre robot, celui que l'interface affiche et que chaque mise à jour fait avancer. Un binaire de développement y porte dev- suivi de son commit. Comparez-le à un numéro de Kepler :

if VersionCompare(VERSION, "1.82.600") == -1 {
	Print("ce script veut Kepler 1.82.600 ou plus récent")
	Exit()
}

C'est le numéro de Kepler, pas celui de Ninja. La garde que beaucoup de scripts Ninja posent en tête, VersionCompare(VERSION, "0.91.8") == -1, passe chez nous, puisque 1.82 vient après 0.91, mais elle ne dit rien de ce que le script attend vraiment : les deux numérotations n'ont rien de commun. Remplacez le numéro de Ninja par celui de la version de Kepler qui apporte ce dont le script a besoin.

Attendre l'arrêt : OnQuitCh

ValeurContient
OnQuitChun canalSe ferme quand le script s'arrête.

Son emploi normal est de garder un script en marche après qu'il a planifié ses tâches. Sans lui, le script arrive au bout de son texte et se termine : l'écran le montre arrêté, sans le compte de ses tâches, et son OnExit s'exécute tout de suite. Ses ExecAt et ses CronExec ne s'arrêtent pas pour autant : ils continuent sans lui, jusqu'à leur fin, au bouton Arrêter, à une relance du script ou à l'arrêt du compte. Sa dernière tâche finie, il lâche ses canaux d'événements. Avec <-OnQuitCh, l'écran dit que le script tourne, ses canaux restent ouverts, et OnExit attend la vraie fin.

CronExec("0 3 * * *", func() { Print("il est trois heures") })
<-OnQuitCh                       // bloque jusqu'à l'arrêt du script

Il se ferme sur Exit(), sur Terminate(), sur le bouton Arrêter, et à l'extinction du robot. Ninja ne le déclenche que sur Exit ; chez nous, tous les arrêts le ferment.

Deux précautions :

  • Les lignes qui suivent <-OnQuitCh ne s'exécutent pas. Le canal ne se libère qu'une fois l'arrêt engagé, et le moteur refuse alors l'instruction suivante. Écrivez votre ligne d'adieu avant, ou dans une fonction OnExit, que le robot appelle après coup, avec son propre délai.
  • Ne l'employez jamais dans !global.ank. Ce fichier définit l'environnement commun, son canal ne se ferme jamais, et l'attente bloquerait le chargement des définitions partagées pour tous vos autres scripts.

L'offre et la licence

Ces valeurs portent les noms que Ninja leur donne, et elles disent votre installation : où tourne le robot, et combien de robots votre licence couvre. Rien de plus : ce qui vous nomme, vous, reste vide (voir plus bas).

Six d'entre elles portent deux noms. Ninja les écrit entourées de doubles tirets bas, __IS_CLOUD__ plutôt que IS_CLOUD, et c'est sous cette forme que les scripts venus de chez lui les lisent. Les deux écritures marchent ici et donnent la même valeur.

ValeurContientCe que ça implique
IS_CLOUD __IS_CLOUD__un booléenVrai sur une instance que nous hébergeons, faux sur votre ordinateur.
IS_SELF_HOST __IS_SELF_HOST__un booléenL'inverse : vrai quand Kepler tourne chez vous.
LICENSE_BOTS_ALLOWED __LICENSE_BOTS_ALLOWED__un entierLe nombre de robots que la licence couvre en ce moment. Zéro quand elle est échue ou refusée.
LICENSE_UUID __LICENSE_UUID__la chaîne videToujours vide, même avec une licence installée.
LICENSE_USERNAME __LICENSE_USERNAME__la chaîne videToujours vide : le titulaire de la licence est le nom de votre compte sur la boutique, souvent votre adresse e-mail.
LICENSE_EMAIL __LICENSE_EMAIL__la chaîne videToujours vide.
CookieDomainla chaîne videChez Ninja, une instance cloud y porte son sous-domaine. Kepler n'en a pas l'usage.

LICENSE_UUID, LICENSE_USERNAME et LICENSE_EMAIL restent vides, et c'est voulu. Votre adresse e-mail sert d'identifiant, sur la boutique comme dans le robot, et elle ne doit jamais s'imprimer. Un script se recopie d'un forum, d'un ami ou d'une IA, il tourne sans personne devant l'écran, et il peut tout envoyer ailleurs par HttpRequest ou SendDiscord : on ne lui tend pas ce qui vous nomme. Les noms existent quand même, à la chaîne vide, pour qu'un script venu de Ninja qui les imprime continue de tourner au lieu de s'arrêter sur undefined symbol.

Elles sont lues au démarrage du script. Une licence prolongée ou réduite pendant qu'il tourne ne change rien à ce qu'il lit : relancez-le pour relire. Sur un binaire de développement, qui ne demande pas de licence, LICENSE_BOTS_ALLOWED vaut zéro, sans que rien ne soit plafonné.

if IS_CLOUD {
	Print("instance hébergée")
}
Printf("%d robot(s) couverts par la licence", LICENSE_BOTS_ALLOWED)

DISCORD_WEBHOOK et TELEGRAM_CHAT_ID portent de même ce que vous avez rempli sur la page Notifications, et SendDiscord(DISCORD_WEBHOOK, msg) part tel quel, sans rien à régler de plus. Voir les notifications.

ValeurVautCe que ça implique
DISCORD_WEBHOOKle webhook Discord de la page NotificationsVide si aucun n'est réglé : SendDiscord rend alors une erreur.
TELEGRAM_CHAT_IDle salon Telegram de la page NotificationsZéro si aucun n'est réglé.