Kepler. Documentation · Scripts 508 fonctions disponibles actuellement English

Scripts Kepler

Kepler exécute des scripts .ank : de petits programmes que vous écrivez et qui pilotent votre compte comme vous le feriez à la main, mais sans vous.

Un script sert quand les workers ne suffisent pas. Le Brain construit, le Pillage farm les inactifs, les Expéditions partent, mais si vous voulez « rappeler ma flotte quand un joueur précis se connecte », « envoyer un message Discord dès que mes débris dépassent un million », ou « balayer trois galaxies et noter ce que j'y trouve », c'est un script qu'il vous faut.

Cette référence décrit 508 fonctions et 296 valeurs, telles que le moteur les expose réellement. Elle est vérifiée contre le programme, pas contre une intention : chaque signature qui suit est celle que votre script rencontrera.

Où l'on écrit, où ça tourne

Ouvrez votre robot, page Scripts. Le bouton + Nouveau crée un fichier, la console en dessous montre ce qu'il écrit, et les boutons Démarrer, Pause, Reprendre et Arrêter en gouvernent la vie.

Un script tourne dans son propre fil, avec son propre environnement. Il ne peut pas faire tomber le robot : une erreur l'arrête, lui, et la raison s'affiche dans la console. Cochez run at startup pour qu'il reparte tout seul au démarrage.

Pendant que vous jouez vous-même dans le navigateur intégré, en mode manuel, vos scripts n'envoient plus rien au jeu. Chacun s'arrête sur sa première requête : une fonction qui demande une page au jeu, une méthode d'un céleste comme p.GetShips(), une action, TriggerFleetSave, et même PauseBot ou LogOut, qui fermeraient votre session. La console le dit une fois, et le script repart de la même ligne quand le mode s'éteint, avec ses variables. Tous les scripts attendent, ceux que vous lancez à la main depuis l'éditeur compris : un script qui parle au jeu pendant que vous jouez peut changer la planète sous vos doigts, d'où qu'il soit parti.

Ce qui ne va pas au jeu continue : Print, le stockage, les calculs, les lectures de ce que le robot a déjà en mémoire (GetCachedPlanets, Distance, IsLoggedIn...), les tâches CronExec ou IntervalExec qui ne font que cela, et HttpRequest ou FetchURL vers un autre site que le jeu, un webhook par exemple. Vers le serveur du jeu ou un site de Gameforge, ces deux-là attendent comme le reste. Les réglages du robot passent aussi, puisqu'ils ne demandent rien au jeu : StartWorker, StopWorker, ClearAllConstructionQueues ou AbortAllFarmingSessions. Les workers, suspendus pendant le mode, en tiennent compte à la reprise. Deux nuances encore : le temps de vol (FlightTime) interroge le jeu sur la cible, il attend donc ; et un calcul de fret, de vitesse ou de prix attend lui aussi tant que le robot n'a pas en mémoire vos recherches, vos bonus de formes de vie ou votre classe d'alliance. Il les lit d'ordinaire dès ses premiers tours ; la classe d'alliance, seulement quand il en a besoin.

Les attentes comptent le temps de la partie : un SleepUntil("03:00:00") se réveille bien à trois heures, et si la ligne suivante parle au jeu, c'est elle qui attend la fin du mode. Une tâche retenue sur une requête part une fois à la reprise, pas autant de fois qu'elle a été manquée. Les appels retenus d'un même script repartent un par un, à une seconde d'écart environ ; deux scripts différents repartent chacun de leur côté.

Arrêter coupe l'attente sur-le-champ, et l'appel retenu ne part pas. L'attente est celle du script qui fait l'appel, et c'est sa console qui la dit, que l'appel soit écrit dans le script, dans une de ses tâches, dans une fonction de !global.ank ou sur un céleste qu'un autre script a gardé dans une variable partagée. Un go appartient au script qui l'a lancé, qu'il parte du script lui-même, d'une de ses tâches, d'une fonction de !global.ank ou d'un autre go, et aussi longtemps qu'il dure, quoi que fassent les autres scripts et les autres comptes entre-temps. Une tâche posée par une fonction de !global.ank (ExecIn, IntervalExec, CronExec...) appartient de même au script qui appelle la fonction, depuis un go compris : elle s'arrête avec lui, et sa pause comme ses échecs s'écrivent dans sa console.

Il ne reste qu'une exception, voulue : ce que lance le premier niveau de !global.ank lui appartient, même quand c'est un script qui le recharge (voir plus bas).

L'arrêt du compte aussi relâche l'appel sans le laisser partir. Un script arrêté pendant le mode ne touche plus au jeu, même depuis OnExit : ces appels-là rendent une erreur, et la console le dit. Le reste d'OnExit tourne normalement. Seul le compte dont vous tenez le navigateur est concerné.

Une chose n'attend pas : le chargement de !global.ank. Quand vous l'enregistrez, quand vous le démarrez depuis la liste des scripts, quand un script le recharge par StartScript("!global.ank") ou quand le compte démarre, son premier niveau s'exécute tout de suite, appels au jeu compris, même pendant le mode manuel. Ce qu'il lance à ce niveau, tâches et go, appartient à !global.ank, même quand c'est un script qui l'a rechargé : pendant le mode, cela attend pour !global.ank, et l'arrêt de ce script n'y touche pas. Les fonctions qu'il définit, elles, attendent comme le reste quand un script les appelle.

Trois noms sont spéciaux :

FichierQuand il tourne
!global.ankAu démarrage, dans l'environnement parent. Ce qu'il définit est visible par tous les autres scripts.
!sleep.ankAu coucher, pendant que la session est encore ouverte. C'est le moment de rentrer une flotte.
!wake.ankAu réveil, une fois la session rouverte.

Un nom du moteur passe devant un nom de !global.ank. Si ce fichier définit une fonction ou une variable qui porte le nom d'une fonction du moteur, vos scripts reçoivent celle du moteur ; seul le code de !global.ank voit la sienne. Une mise à jour qui ajoute des fonctions peut donc masquer une des vôtres : le script s'arrête alors sur une erreur comme function wants 1 arguments but received 2, ou lit autre chose que ce que vous aviez rangé. Renommez la vôtre.

Le langage

Les scripts sont écrits en anko, un langage dont la syntaxe ressemble beaucoup à Go, en plus souple : pas de déclaration de type, pas de compilation, et une boucle s'écrit comme on l'attend.

for i = 0; i < 5; i++ {
	Print("passe " + i)
	SleepSec(2)
}

Une ligne ne se coupe pas n'importe où

Un appel long se coupe après une virgule, jamais après la parenthèse ouvrante :

secs, fuel = FlightTime(origine,
	cible, HUNDRED_PERCENT, flotte, ATTACK)     // ✓
secs, fuel = FlightTime(
	origine, cible, HUNDRED_PERCENT, flotte, ATTACK)     ✗ syntax error

C'est la mise en page la plus naturelle en Go, et anko la refuse. Son message à lui ne dit que « syntax error » ; le robot y ajoute la ligne, la colonne et le texte fautif :

ligne 3, colonne 25 : syntax error
    secs, fuel = FlightTime(

Les erreurs d'exécution le disent aussi. Un champ mal orthographié, un argument de trop, une valeur qui n'est pas du type qu'on croyait : aucune ne se voit à la lecture, et toutes sont désignées à la ligne près.

ligne 3, colonne 5 : no member named 'ComputerTechnology' for struct
    ordi = techs.ComputerTechnology

Seul un arrêt demandé n'est pas décoré : il n'y a pas de défaut à chercher.

Ces paquets sont importables : bytes, encoding/json, errors, fmt, io/ioutil, math, math/rand, net/http, net/url, regexp, sort, strconv, strings, sync, time.

strings = import("strings")
if strings.Contains(nom, "Xylo") { Print("le voilà") }

Les deux pièges qu'il faut connaître avant d'écrire une ligne

Ils viennent tous deux de la même règle d'anko, et ils ne provoquent aucune erreur. Un script qui tombe dedans ne plante pas : il fait autre chose que ce qu'il dit. C'est de loin la première cause de scripts qui « ne marchent pas ».

1. Une fonction qui rend plusieurs valeurs les rend dans une tranche

En Go, GetCelestials() rend deux choses : la liste et une erreur. Anko ne connaît pas cette notion : il vous les remet empaquetées ensemble.

c = GetCelestials()        // ✗ c vaut [<liste> <nil>], pas la liste
Print(len(c))              //   affiche 2, toujours

c, err = GetCelestials()   // ✓ c vaut la liste, err vaut nil
Print(len(c))              //   affiche 24

Le symptôme classique : index must be a number, ou une valeur qui vaut obstinément 2. Chaque fonction de cette référence indique combien de valeurs elle rend ; prenez-en exactement autant.

2. Prendre trop de cibles ne provoque rien, et c'est pire

// ConstructionsBeingBuilt rend QUATRE valeurs, pas cinq.
bid, bsec, rid, rsec, err = ConstructionsBeingBuilt(id)   // ✗
if err != nil { ... }   // « undefined symbol 'err' »… ou pire

Anko ne signale pas la cible en trop : la variable reste simplement non définie. Et si un bloc précédent avait laissé un err traîner, votre test porte sur l'erreur d'un autre appel, ce qui est indétectable à la lecture.

La règle est donc simple : comptez les valeurs de retour, ni plus, ni moins.

L'implémentation est en cours, et voici où elle en est

Compléter cette API est notre priorité, et il ne reste plus grand-chose.

Cette page dit l'état exact du jour, parce qu'une référence qui promettrait ce qui n'existe pas encore vous ferait perdre des heures sur des symboles introuvables. Ce qui suit est mesuré sur le programme, pas annoncé.

Ce qui est couvert est tout le cœur du métier : lire le compte, les célestes, les ressources, les technologies ; envoyer, suivre et rappeler des flottes ; relever la galaxie, une position, le classement ; construire, démolir, annuler ; piloter les workers et composer leur travail ; chercher où envoyer sa flotte pour la nuit ; ranger des valeurs entre deux passes ; attendre, s'ordonnancer, être réveillé par une attaque, un message, une flotte ou une cible qui bouge ; écrire au journal, prévenir sur Discord ou Telegram.

Ce qui manque, et pourquoi :

Ce qui n'existe pasPourquoi
Le marché entre joueursIl n'existe plus. Gameforge l'a retiré du jeu, et la bibliothèque elle-même ne l'a plus suivi au-delà de la v7. OfferSellMarketplace, OfferBuyMarketplace, BuyMarketplace et CollectAllMarketplaceMessages ont donc été retirées : elles auraient rendu « réussite » sans rien faire, ce qui est pire que de ne pas les livrer.
Les claviers TelegramLes réponses interactives et OnTelegramMessageReceivedCh demandent que le robot écoute Telegram en continu, ce qu'il ne fait pas : il y écrit. SendTelegram fonctionne.
OnRepatriateCompletedChLe robot sait dire qu'une flotte est partie, pas qu'elle est arrivée. Un canal nommé « completed » qui se déclencherait au départ mentirait. OnFleetCh dit ce qu'il sait, et le dit sous son vrai nom.
SendMailLe robot n'a pas de réglages SMTP : lui en donner est une fonctionnalité à part entière, pas une ligne d'API. Discord et Telegram couvrent le besoin.
UnsafePhalanxElle scanne sans vérifier la portée, et la doc de référence prévient elle-même : une coordonnée hors de portée fait bannir le compte automatiquement, dix minutes la première fois. Phalanx vérifie, et c'est tout ce qui les sépare. Nous ne livrons pas la version qui ne vérifie pas.
Les fichiersTempFile, ListTempFiles et leurs jumelles écrivent sur le disque. Les scripts d'un client hébergé tournent sur nos machines : leur ouvrir le système de fichiers est une décision d'architecture, pas une ligne d'API. Put/Get couvrent la persistance dont un script a besoin.
SkipSuspiciousLoginWaitSon équivalent existe : le bouton « Passer l'attente de connexion » de l'Aperçu du robot. Il reste à la main : il dit que la cause d'un refus de Gameforge a disparu, ce qu'un script ne sait pas, et insister prolonge le blocage. Voir Ce qui reste à la main, exprès.
Les robots d'une autre installationUn script de Kepler voit et pilote les robots de SON installation, et eux seuls : OwnBots, GetBotByID, StartRemoteScript sans adresse (voir Piloter les autres robots de l'installation). Un autre Kepler, le vôtre sur une autre machine ou celui d'un autre client sur le Cloud, reste hors de portée : StartRemoteScript refuse une adresse. Pour lancer un script de l'extérieur, une adresse existe, sous une clé à elle (voir Lancer un script de l'extérieur).
CalcFastCargoPF et IdealExpeditionCargoShipsDeux calculs dont la règle exacte ne se lit pas dans la doc de référence, seulement dans ses exemples. CalcPreferredCargo couvre le premier besoin en disant, elle, ce qu'elle fait.
La base de NinjaDBGetShips, DBGetDefenses, DBGetFacilities, DBGetResearches, DBGetResourceBuildings, DBGetResourceSettings lisent la base de leur outil. Kepler n'en tient pas de semblable : GetShips, GetFacilities, GetTechs2 et GetResearch lisent le compte.
Les réglages propres à NinjaEnableNJA, DisableNJA, IsNJAEnabled. Elles pilotent des mécanismes de leur outil, qui n'ont pas d'équivalent chez nous : les nommer ne ferait pas exister ce qu'elles commandent.
Les réglages de leurs workersGetBrainBatchUpdateSettings, BrainBatchUpdate, SendSavedFleet manient des structures propres à leur outil. Les nôtres se pilotent par StartWorker et par les couples de réglages, dont GetExpeditionsConfigs et SetExpeditionsConfigs sous les noms de Ninja : voir Réglages des workers.
Le prix de la matière noireGetDarkMatterPrices : ces prix ne sont pas dans le jeu mais chez son prestataire de paiement, derrière une session de paiement ouverte pour le compte. Kepler n'y va pas.
Pas encoreNewACS (l'attaque groupée), SendMessageAlliance, PlaySound, ClearOut, et les canaux OnFleetDispatch, OnSystemInfos, OnPhalanxReport, OnFarmSessionStart, OnFarmSessionAllSpySent, OnFarmSessionBeforeAttack, OnFarmSessionAttacksSent, OnFarmSessionDone. OnFleetCh dit déjà quelles flottes partent.
ExecInCh et compagnieRien : elles existent toutes désormais.

Ce que ça implique pour vous. Un script recopié qui touche l'une de ces familles s'arrête sur undefined symbol 'X'. C'est une erreur franche, à l'exécution, qui nomme le symbole manquant : vous saurez immédiatement lequel. Elle ne casse rien d'autre, et le reste du script n'aura pas tourné.

Dites-nous ce qui vous manque. Cette liste se vide, et l'ordre dans lequel elle se vide dépend de vous : une fonction réclamée passe devant les autres.

Cette page est mise à jour à chaque version. L'index alphabétique, dans la colonne de gauche, est le seul endroit qui ne peut pas se tromper : il est fabriqué à partir du programme lui-même, et un test refuse la publication s'il s'en écarte.

Ce qui reste à la main, exprès

La règle de Kepler est que tout ce qui se fait dans le robot se fasse aussi par script. Deux familles de gestes y échappent, et ce n'est pas un retard : elles ne s'ouvriront pas aux scripts.

Les secrets et l'installation : jamais

Aucune fonction ne touche, et aucune ne touchera :

  • l'import et l'export des robots, qui portent les mots de passe en clair ;
  • la clé de licence (« Ressaisir ma clé ») et les écrans Licence, Mon compte et Connexion ;
  • la mise à jour de Kepler, qui arrête tous les robots ;
  • le mot de passe OGame et la double authentification ;
  • les proxys avec leurs identifiants (SetProxy et AddOwnProxy chez Ninja) ;
  • la création et la suppression d'un robot ;
  • le remplacement de l'adresse de sortie, qui redémarre Kepler.

Pourquoi. Un script se recopie d'un forum, d'un ami ou d'une IA, et il tourne sans personne devant l'écran. Ce qu'il peut lire, il peut l'envoyer ailleurs, par HttpRequest ou SendDiscord, et un mot de passe ou une clé, une fois sortis, ne se rattrapent pas. Ces gestes touchent aussi toute l'installation, tous les robots à la fois, alors qu'un script ne voit que son compte. Aucune case ne les ouvre. Pour la même raison, LICENSE_UUID, LICENSE_USERNAME et LICENSE_EMAIL restent vides : votre adresse e-mail sert d'identifiant, et elle ne s'imprime jamais (voir l'offre et la licence).

Les gestes humains : à la main, le script prévenu

Ceux-là demandent un jugement qu'un script n'a pas. Ils se font dans l'interface :

  • Répondre au défi de Gameforge (le captcha de la connexion). C'est une image à lire, et une mauvaise réponse aggrave le blocage. Le script en est prévenu par OnCaptchaCh : voir Savoir que Gameforge demande un défi.
  • Passer l'attente de connexion après un refus de Gameforge, le SkipSuspiciousLoginWait de Ninja : c'est dire que la cause a disparu, et insister prolonge le blocage.
  • Autoriser un script à mettre le compte en vacances. SetVacationMode existe, mais il ne part qu'une fois la case cochée par vous dans les paramètres du robot : deux jours de jeu gelés, sans recours, ne se décident pas dans une boucle.
  • Tirer une nouvelle empreinte ou reprendre celle de cet ordinateur : le jeu recevrait une machine neuve à chaque démarrage d'un script rejoué. La bibliothèque d'empreintes, elle, se pilote (NewFingerprint, ApplyFingerprint…).
  • Suivre un compte après la fusion des univers : l'identifiant du robot change, et le script qui le demanderait serait arrêté en route.

Ce qui distingue Kepler de Ninja

L'API suit celle de Ninja, pour que vos scripts existants tournent sans modification. Trois écarts assumés :

  • SleepRandMin compte des minutes, comme son nom le dit. Si vous venez d'un script qui lui passait des millisecondes, utilisez SleepRandMs.
  • Les valeurs propres à l'offre de Ninja (LICENSE_*, IS_CLOUD, VERSION) disent les nôtres : VERSION porte le numéro de Kepler, pas celui de Ninja, LICENSE_BOTS_ALLOWED le plafond de votre licence, et LICENSE_UUID, LICENSE_USERNAME et LICENSE_EMAIL restent vides, pour ne jamais tendre votre adresse à un script.
  • Simulator rend la forme de Ninja, mais pas tous ses chiffres : les survivants du défenseur valent zéro, TacticalRetreat et Logs restent vides. Tout le reste est calculé, voir Simuler un combat.

Écrire vos scripts avec une IA

Un assistant de code (Claude, ChatGPT, Cursor, Copilot...) peut lire cette référence à la source, fonction par fonction, par notre serveur MCP. Comment le brancher : MCP (script avec IA).

La référence, par famille

FamilleCe qu'on y trouve
Sortie, journal et stockagePrint, les niveaux de journal, Put/Get, Discord et Telegram
Temps et attentela famille Sleep, les horaires, les durées
OrdonnancementExecIn, ExecAt, ExecInCh, ExecAtCh, IntervalExec, CronExec, RangeCronExec, RemoveCron
Célestes et ressourcesplanètes, lunes, mines, bâtiments, technologies
Flottes, vols et combatenvois, durées, fret, puissance de combat, simulateur de combat
Piloter les workersStartBrain, StopFarmingBot, IsWorkerRunning, ListWorkers, AddHunterTarget
Réglages des workersGetExpeditionsConfigs, SetSleepModeConfigs, SetFleetSaveConfigs, SetRewardsConfigs, SetMaxSlotsFor, GetSlot
Orion, sa valeur, ses combatsStartOrion, GetOrion, OrionScan, OrionClaim, sur un univers d'Orion
Compte, galaxie, joueurs et messagesrelevés de systèmes, classement, courrier
Boîte à outilsmaths, chaînes, JSON, base64, identifiants
Constantes et valeursles tableaux d'identifiants, la licence, le serveur
Dix scripts qui marchentdes scripts entiers, à coller tels quels