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 325 fonctions et 147 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 :
| Fichier | Quand il tourne |
|---|---|
!global.ank | Au démarrage, dans l'environnement parent. Ce qu'il définit est visible par tous les autres scripts. |
!sleep.ank | Au coucher, pendant que la session est encore ouverte. C'est le moment de rentrer une flotte. |
!wake.ank | Au réveil, une fois la session rouverte. |
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 errorC'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.ComputerTechnologySeul 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 24Le 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 pireAnko 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 pas | Pourquoi |
|---|---|
| Le marché entre joueurs | Il 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 Telegram | Les réponses interactives et OnTelegramMessageReceivedCh demandent que le robot écoute Telegram en continu, ce qu'il ne fait pas : il y écrit. SendTelegram fonctionne. |
OnRepatriateCompletedCh | Le 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. |
SendMail | Le 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. |
UnsafePhalanx | Elle 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 fichiers | TempFile, NewSheet, 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. |
| Les autres robots | AllBots, OwnBots, BotsCount, GetBotByID, StartRemoteScript, StopRemoteScript. Un script de Kepler voit son compte, et lui seul. Ouvrir un compte aux scripts d'un autre est une question de cloisonnement avant d'être une question d'API : deux clients partagent nos machines. |
| Les réglages propres à Ninja | EnableNJA, DisableNJA, IsNJAEnabled, SkipSuspiciousLoginWait, GetSlot, NewSheet. 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. |
CalcFastCargoPF et IdealExpeditionCargoShips | Deux 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. |
ExecInCh et compagnie | Rien : 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 distingue Kepler de Ninja
L'API suit celle de Ninja, pour que vos scripts existants tournent sans modification. Trois écarts assumés :
SleepRandMincompte des minutes, comme son nom le dit. Si vous venez d'un script qui lui passait des millisecondes, utilisezSleepRandMs.GetHighscorene fonctionne plus en version 13 du jeu : la page qu'elle lisait a changé. UtilisezHighscoreData, qui interroge l'API du jeu, rend le classement entier d'un coup et ne se cassera pas à la prochaine version.- Les fonctions propres à l'offre de Ninja (
LICENSE_*,IS_CLOUD,VERSION) existent avec nos valeurs, pour qu'un script qui les lit ne s'arrête pas.
É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
| Famille | Ce qu'on y trouve |
|---|---|
| Sortie, journal et stockage | Print, les niveaux de journal, Put/Get, Discord et Telegram |
| Temps et attente | la famille Sleep, les horaires, les durées |
| Ordonnancement | ExecIn, ExecAt, ExecInCh, ExecAtCh, IntervalExec, CronExec, RangeCronExec, RemoveCron |
| Célestes et ressources | planètes, lunes, mines, bâtiments, technologies |
| Flottes, vols et combat | envois, durées, fret, puissance de combat |
| Piloter les workers | StartBrain, StopFarmingBot, IsWorkerRunning, ListWorkers, AddHunterTarget |
| Compte, galaxie, joueurs et messages | relevés de systèmes, classement, courrier |
| Boîte à outils | maths, chaînes, JSON, base64, identifiants |
| Constantes et valeurs | les tableaux d'identifiants, la licence, le serveur |
| Dix scripts qui marchent | des scripts entiers, à coller tels quels |