Si vous voulez programmer votre propre version du jeu, les API vous permettent d'interagir avec le serveur du jeu, dans les deux sens : récupérer les données mais aussi exécuter des actions (déplacer un citoyen dans l'outre-monde...).
Si vous avez des difficultés, n'hésitez pas à demander de l'aide sur le Discord ou sur le bug tracker Github.
Pages liées :
⚠️ Remarque : si vous obtenez une « erreur CORS » ou « 403/forbidden » en tentant d'appeler une API : voir Corriger une erreur CORS.
| Obtenir les zones de la carte |
Utilité : construire votre carte du désert. Données fournies : nombre de zombies, objets dans la zone, présence d'une ville... ► Pour obtenir toutes les zones de la carte : Important : la coordonnée X augmente de 2 en 2 (et non de 1 en 1 comme sur une grille classique). Explications et exemples. La liste des objets est de la forme 'id_de_l'objet' => 'quantité'. ► Pour n'obtenir que les zones modifiées depuis une certaine date, ajoutez le paramètre &newerthan : api/maps?action=get&map_id=1&newerthan=1602429478 Ce paramètre est utile pour alléger les requêtes (ne pas recharger la totalité de la carte alors que seules quelques zones ont été modifiées). La date indiquée dans &newerthan doit être un timestamp Unix, par exemple « 1602429478 ». ► Pour ne récupérer que certaines zones, listez leurs coordonées dans le paramètre &zones : api/maps?action=get&map_id=1&zones=0_8,1_1,1_2 Utile pour alléger la requête si vous n'avez besoin que des zones autour du joueur et pas du reste la carte.
► Pour obtenir, en plus des informations générales, des informations de zone liées à un joueur précis, ajoutez son jeton d'authentification avec le paramètre &token : api/maps?action=get&map_id=1&token=... Cela ajoute le champ user_specific
dans les valeurs retournées par l'API : |
| Obtenir les caractéristiques des citoyens |
Utilité : placer les citoyens sur la carte, récupérer leurs états de santé... Données fournies : son pseudo, ses points d'action, ses coordonnées sur la carte... ► Pour obtenir tous les citoyens de la carte : Depuis le 24 avril 2020, l'API citizens ne retourne plus les pictos des joueurs (trop gourmand et inutile pour placer les citoyens sur la carte). La clé "pictos" est désormais systématiquement vide, elle n'est conservée que pour assurer la rétrocompatibilité. Pour récupérer les pictos, utilisez l'API dédiée pictos (documentée plus bas dans la page). ► Pour obtenir un citoyen précis : Si vous avez besoin des données de plusieurs citoyens, évitez la seconde possibilité car multiplier les requêtes nuit aux performances. Utilisez plutôt la première possibilité pour récupérer en une seule fois les données de tous citoyens, puis n'affichez que les données qui vous intéressent. ► Pour ne récupérer que les citoyens présents dans certaines zones,
listez leurs coordonées dans le paramètre &zones : Utile pour alléger la requête si vous n'avez besoin que des zones autour du joueur et pas du reste la carte.
► Pour n'obtenir que les citoyens modifiés depuis une certaine date,
ajoutez le paramètre &newerthan : Ce paramètre est utile pour alléger les requêtes (ne pas récupérer les citoyens non modifiés). La date indiquée dans &newerthan doit être un timestamp Unix, par exemple « 1602429478 ». |
| Obtenir l'intérieur d'une ville |
Utilité : construire votre interface pour l'intérieur de la ville. Données fournies : objets en banque, liste des chantiers, état du puits... > Une ville précise : > Toutes les villes d'une carte : Récupérer toutes les villes d'une carte n'est pas recommandé car la requête est plus lourde et vous n'aurez généralement besoin que d'une ville à la fois. Préférez appeler une ville précise. Si vous voulez juste afficher la carte, n'appelez pas cette API : utilisez l'API /maps (voir plus haut, « Obtenir la carte »). |
| Obtenir les objets stockés dans les bâtiments |
Utilité : récupérer les objets stockés à l'intérieur
des bâtiments d'une ville. Ne pas confondre avec les objets stockés
dans la banque globale de la ville, qui sont récupérés via l'API
cities?action=get (voir ci-dessus).
► Pour récupérer les objets stockés dans les bâtiments :
• L'API retourne les objets regroupés par l'ID de la construction
qui les contient. Les sous-entrées sont les paires
"ID de l'objet" => "Quantité de cet objet" |
| Connecter le joueur à son compte |
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
► Exemple de formulaire HTML sur le Github Une fois l'utilisateur connecté : L'API vous retournera une clé token. Enregistrez ce token dans un cookie chez le joueur, car vous en aurez besoin plus tard pour appeler les API qui nécessitent que le joueur soit identifié (ex : déplacer le joueur sur la carte). |
| Déconnecter le joueur |
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
|
| Créer un citoyen |
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
|
| Contrôler un citoyen-bot |
Utilité : permettre au joueur de prendre temporairement
le contrôle d'un citoyen-bot, à la place de son citoyen normal.
Les citoyens-bots sont disponibles dans les parties où les joueurs réels
sont peu nombreux, notamment pour permettre les expéditions dans le désert.
1°) Appelez l'API de prise de contrôle : api/me?action=switch_citizen&target_id=2488&token=...
2°) L'API vous retournera une clé token. Enregistrez ce token dans un cookie chez le joueur, en remplacement de son cookie d'authentification initial. La requête échouera si vous tentez de prendre le contrôle du citoyen d'un vrai joueur au lieu d'un citoyen-bot. Contrôlez le message d'erreur retourné par l'API pour vous assurer que la requête a été acceptée. 3°) Une fois que le joueur a pris le contrôle du citoyen-bot, il peut lui faire accomplir toutes les actions d'un citoyen normal, via les API classiques (se déplacer, fouiller...). |
| Créer un compte utilisateur | Pour des raisons de sécurité, l'API ne permet pas de créer des comptes pour le moment. Les personnes doivent s'incrire en passant par le site principal. |
| Obtenir les caractéristiques du joueur connecté |
api/me?action=get&token=...
Le &token est le jeton d'autentification qui est créé lorsque le joueur se connecte. Pour le récupérer, voir Authentifier le joueur. Notez que si vous récupérez déjà les données des citoyens de la carte avec l'API citizens (voir ci-dessus), les données du joueur connecté s'y trouvent également. |
| Choisir sa spécialité |
api/me?action=specialize&type=explorer&token=...
3 valeurs sont possibles pour le paramètre type : |
| Déplacer le joueur |
► Déplacer le joueur d'une zone : api/zone?action=move&to=southeast&token=...Indiquez dans le paramètre to la direction dans laquelle
déplacer le joueur :
► Téléporter le joueur vers une ville : api/zone?action=teleport&to=city&target_id=170&token=...La téléportation permet de déplacer le joueur entre
les habitations d'une ville sans besoin de connaître leurs coordonnées.
Elle ne requiert ni points d'action ni contrôle de la zone,
contrairement au déplacement classique move. |
| Fouiller la zone | api/zone?action=dig&token=... |
| Explorer un bâtiment | api/city?action=explore&token=... |
| Attaquer un zombie |
• Attaquer à mains nues : api/zone?action=fight&token=... • Attaquer avec une arme : api/zone?action=fight&item_id=401&token=... Indiquez dans le paramètre item_id l'id de l'objet à utiliser comme arme (ex : item_id=401 si le couteau est l'objet n°401). Consultez l'API configs pour connaître l'id de chaque objet. • Chasser un zombie de la zone vers une zone voisine :api/zone?action=repel&token=... La zone de destination est choisie aléatoirement. |
| Agresser un citoyen |
api/me?action=attack&target_id=120&token=...
Indiquez dans le paramètre target_id l'id du citoyen à agresser. |
| Soigner un citoyen blessé |
• Me soigner moi-même : Indiquez dans le paramètre item_id l'id de l'objet de soin à utiliser (ex : item_id=23 si le bandage est l'objet n°23). Consultez l'API configs pour connaître l'id de chaque objet. • Soigner un autre citoyen : Indiquez dans le paramètre target_id l'id du citoyen à soigner. |
| Planter sa tente dans la zone |
api/city?action=build&city_type_id=13&token=...
Le paramètre city_type_id=13 indique que l'on construit une tente individuelle et non une ville accueillant plusieurs joueurs. |
| Fonder une ville dans la zone |
api/city?action=build&city_type_id=12&city_size=5&token=...
Le paramètre city_type_id=12 indique
que l'on construit une ville et non une simple tente individuelle. |
| Connecter son habitation à une ville | api/city?action=connect&token=... |
| Détruire une tente dans la zone | api/city?action=attack&token=... |
| Modifier le terrain dans le désert |
api/edit&stuff=water&coord_x=6&coord_y=2&radius=0&token=...
|
| Faire entrer ou sortir le joueur de la ville |
api/city?action=go_inout&token=...
La zone où se trouve le citoyen doit comporter une ville ou une tente. |
| Actionner la porte de la ville |
Ouvrir la porte : api/city?action=open_door&token=... Fermer la porte : api/city?action=close_door&token=... Ces deux actions sont séparées afin que la porte ne soit pas rouverte involontairement lorsque deux joueurs tentent de la fermer en même temps. Et réciproquement, pour ne pas risquer de refermer la porte en croyant l'ouvrir. |
| Construire un chantier |
api/buildings?action=build&building_id=101&token=...
Le paramètre building_id dans l'URL est le numéro du chantier dans lequel le citoyen veut investir un point d'action. |
| Prendre de l'eau au puits |
api/items?action=pickup&construction_id=254&item_id=9&token=...
• Le paramètre &item_id est l'ID de l'objet à ramasser
(voir l'API configs pour la liste des ID). Cette méthode fonctionne pour les objets stockés à l'intérieur d'un bâtiment. Pour ramasser un objet placé directement au sol, utilisez l'API zone (voir "Ramasser un objet" plus haut dans la page) |
| Ajouter de l'eau dans le puits |
api/items?action=drop&construction_id=254&item_id=9&token=...
• Le paramètre &item_id est l'ID de l'objet à déposer
(voir l'API configs pour la liste des ID). Cette méthode fonctionne déposer un objet à l'intérieur d'un bâtiment. Pour déposer un objet directement au sol, utilisez l'API zone (voir "Ramasser un objet" plus haut dans la page) |
| Déposer un objet au sol | api/zone?action=drop&item_id=3&token=.. |
| Ramasser un objet au sol | api/zone?action=pickup&item_id=3&token=... |
| Consommer un objet |
api/items?action=eat&item_id=10&token=...
Indiquez dans le paramètre item_id l'id de l'objet à consommer. Ex : item_id=10 pour manger un hamburger (item #10). Consultez l'API configs pour connaître l'id de chaque objet. |
| Assembler un objet |
api/items?action=craft&item_id=201&token=...
Le paramètre item_id dans l'URL est le numéro de l'objet à obtenir par assemblage (dans cet exemple, l'objet n° 201, c'est-à-dire la plaque de bois). La liste des objets nécessaires à la fabrication ne figure pas dans l'URL, elle est calculée par le serveur du jeu. |
| Ajouter une crypte sur la carte |
api/zone?action=add&stuff=vault&token=...
L'API retourne les coordonnées de la case où la crypte a été générée. |
| Ajouter des zombies sur la carte |
api/zone?action=add&stuff=zombies&token=...
Cette action n'est normalement possible que si le joueur se trouve dans une crypte.
Pour ajouter des zombies sans besoin de crypte (utile dans le cadre des tests du jeu),
ajouter le paramaètre &conditions : |
| Dévoiler 7 zones aléatoires de la carte |
api/zone?action=reveal&stuff=random7&token=...
7 cases seront dévoilées comme si elles avaient été visitées par un joueur. En outre, l'API vous indique les coordonnées de ces cases pour permettre, par exemple, de les mettre en valeur sur votre carte. |
| Obtenir la liste des discussions |
Obtenir la liste des discussions
Résultats renvoyés par l'APIChaque clé retournée par l'API contient les informations relatives un fil de discussion :
|
| Obtenir les messages d'une discussion |
Récupérer les messages d'une discussionapi/discuss/threads?action=get&topic_id=3
Résultats renvoyés par l'API
|
| Créer une nouvelle discussion |
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
|
| Répondre dans une discussion |
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
|
| Déclencher l'attaque zombie quotidienne |
api/events?action=endcycle&token=.... Le joueur doit être dans une ville pour déclencher l'attaque. |
| Historique des attaques zombies |
> Historique des attaques de toutes les villes : > Pour obtenir l'historique d'une ville précise, indiquer l'ID de la ville souhaitée grâce au paramètre &city_id :
Vous pouvez choisir l'ordre chronologique en ajoutant le paramètre &sort : |
| Historique des actions des joueurs |
api/events?action=get&type=map Chaque événénement est décrit par les clés suivantes :
|
| Lancer une partie |
Utilité : commencer une partie sur une « vraie » carte.
La carte par défaut lors de la création du compte n'est qu'une démo. |
| Gagner la partie |
Utilité : s'enfuir dans la voiture pour remporter
la partie (si les conditions sont remplies). |
| Valider sa mort |
Utilité : commencer une nouvelle partie après avoir été tué. |
| Obtenir le top 10 des survivants | Utilité : classement des citoyens actuellement en vie ayant survécu le plus longtemps. |
| Obtenir les pictos des joueurs |
Pictos d'un citoyen :
api/pictos?action=get&citizen_id=56
Pictos des citoyens d'une carte : api/pictos?action=get&map_id=1 |
| Obtenir les paramètres du jeu |
api/configs?action=get&map_id=...
Si le paramètre &map_id n'est pas précisé, une configuration par défaut sera affichée. Cette API renvoie toutes les données statiques du jeu :
|
| Créer un objet |
Utilité : Les joueurs peuvent créer et paramétrer eux-mêmes
de nouveaux objets qui seront disponibles dans le jeu (leur nom, leurs effets...).
Ces données doivent être envoyées par la méthode HTTP POST.
Cela signifie que, contrairement aux autres API, vous ne devez pas
les placer directement dans l'url. Vous devez les envoyer
via un formulaire HTML (<form>) (ou, de façon plus avancée, en javascript).
|
| Statistiques de découverte d'objets |
Utilité : simule un grand nombre de fouilles dans le désert afin d'obtenir les probabilités réelles de découverte de chaque objet. Cela vous permet de vérifier si les taux de découverte que vous avez définis sont réalistes. Par exemple, un objet avec des probabilités de découverte très faibles ne pourra, en pratique, jamais être trouvé par les joueurs. api/configs?action=stats&map_id=...Valeurs renvoyées :
|
Cette liste s'enrichira au fur et à mesure des développements.
Si vous obtenez une « erreur CORS » ou « 403/forbidden » en tentant d'appeler une API :
Une erreur CORS signifie que votre appel à une API d'InvaZion a été bloquée. Vous pouvez la voir en ouvrant la console web de Firefox (Ctrl+Maj+k) ou de Chrome (Ctrl+Maj+i) :
(Le « traceur potentiel » que croit voir l'extension n'en est évidemment pas un, la requête inter-sites est le principe d'une API.)
Si vous avez des difficultés, n'hésitez pas à demander de l'aide sur le Discord ou sur le bug tracker Github.
// In this example, the generated map will be 15 cells high and 10 wide
$nbr_rows = 15;
$nbr_cols = 10;
$map = '';
## 1. Generates the lines of the map (each loop = 1 new line)
for ($row=0; $row<$nbr_rows; $row++) {
## 2. Generates the cells inside the line (each loop = 1 new cell)
$zones = '';
for ($i=0; $i<$nbr_cols; $i++) {
// You will put the content of the cell inside this div
$zones .= '<div class="zone">...</div>';
}
## 3. We shift 1 line out of 2 to the right, in order to nest the hexagons
$align = '';
if ($row%2 === 1) {
$align = 'padding-left:1.25em';
}
## 4. Saves the generated line for later display
$map .= '<div class="row" style="'.$align.'">'
.$zones.
'</div>';
}
// Displays the generated map
echo $map;Le code présenté ici est en PHP, mais vous pouvez adapter cette structure au langage que vous souhaitez (javascript...), la logique reste la même.
Pour la démonstration le code est présenté en un seul bloc, mais en situation réelle il est préférable de le découper en fonctions ou en classes.
Si vous avez besoin de davantage d'explications, n'hésitez pas à les demander sur le Discord.
Chaque case de la carte du jeu est identifiée par une coordonnée [X:Y], où X représente la colonne et Y représente la ligne. Par exemple, la case [8:3] se trouve sur la 8e colonne de la 3e ligne de la carte.
Précision importante : en raison de la forme hexagonale des cases, la coordonnée X augmente de 2 en 2 (et non de 1 en 1 comme sur une carte carrée). La valeur du Y, elle, augmente de 1 en 1 comme sur une grille classique. Exemple :
Ce système de « coordonnées doublées » simplifie grandement la programmation par la suite, en empêchant que les règles de déplacement ne varient d'une case à l'autre. Imaginons que l'on numérote simplement les cases de 1 en 1 comme sur une grille carrée, en se contentant de décaler visuellement les lignes afin d'imbriquer les hexagones :
Ce résultat, qui semble visuellement identique, génèrerait des comportements incohérents. Mettons qu'un joueur situé en 0:0 se déplace en diagonale vers le coin bas+droite, et regardons comment évoluerait la coordonnée X :
On constate que la cordonnée X augmente ou n'augmente pas... alors qu'il s'agit du même déplacement. Le système classique imposerait ainsi de réaliser des vérifications contextuelles en fonction de la case de départ (si Y est impair, augmenter X de 1 ; si Y est pair, laisser X identique...). C'est contre-intuitif et complexifie le codage de tout ce qui concerne les coordonnées : déplacements, calcul de distances, etc.
Alors qu'avec le système des coordonnées doublées, le X évolue toujours de la même façon quelle que soit la case de départ. Reprenons l'exemple du joueur se déplaçant vers le bas+droite en partant de 0:0, mais cette fois sur la carte à coordonnées doublées :
Le joueur va passer par ces cases :
On voit qu'avec ce système, X augmente de la même façon tant qu'on se déplace dans la même direction, ce qui est logique et épargne de nombreux tests conditionnels inutiles.
Merci à Scaalp pour sa lumière sur la sujet, et à Redblobgames pour ses explications complètes.
Les dates retournées par les API d'InvaZion sont au format standard international ISO 8601, par exemple :
2019-02-18T14:51:41+01:00
Tous les langages proposent des fonctions pour convertir les dates ISO, n'utilisez pas d'expressions régulières pour les parser.
$iso_date = "2019-02-18T14:51:41+01:00";
// Converts the ISO date to a timestamp ("1550497901000")
$timestamp = strtotime($iso_date);
// Converts the timestamp to the human-readable format "dd/mm/yyyy"
$formatted_date = date("d/m/Y", $timestamp);
// Will prompt "18/02/2019" in the browser page
echo $formatted_date;
var iso_date = "2019-02-18T14:51:41+01:00";
// Converts the ISO date to the human-readable format "dd/mm/yyyy"
var formatted_date = new Date(iso_date).toLocaleDateString();
// Will prompt "18/02/2019" in the console of your browser
console.log(formatted_date);
Le format ISO évite toute ambiguïté dans les dates échangées par les API :
Par principe, vous pouvez exploiter les API d'Invazion sans restrictions ni autorisation préalable. Certaines limites sont toutefois posées :