InvaZion

Le projet de Hordes-like collaboratif

Liste des API du jeu

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.

Créer votre interface de carte
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 :

api/maps?action=get&map_id=1

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é'.
Elle vaut "null" s'il n'y a aucun objet sur la case.

► 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 :
is_visited_today : vaut "1" si le joueur a déjà visité la zone aujourd'hui.

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 :
api/citizens?action=get&map_id=1

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 :
api/citizens?action=get&citizen_id=53

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 :
api/citizens?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 n'obtenir que les citoyens modifiés depuis une certaine date, ajoutez le paramètre &newerthan :
api/citizens?action=get&map_id=1&newerthan=1602429478

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 ».

Créer votre interface de ville
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 :
api/cities?action=get&city_id=27

> Toutes les villes d'une carte :
api/cities?action=get&map_id=1

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 »).

Authentifier le joueur
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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page :
    https://invazion.nadazone.fr/api/user
  • Champs à prévoir dans votre formulaire HTML :
    • action = connect (valeur invariable)
    • email = l'email saisi par l'utilisateur (ex : myemail@provider.com)
    • password = le mot de passe saisi par l'utilisateur (ex : VMeg6257_42)

► 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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page :
    https://invazion.nadazone.fr/api/user
  • Champs à prévoir dans votre formulaire HTML :
    • action = disconnect (valeur invariable)
    • token = le jeton d'authentification du joueur (créé lors de sa connexion)
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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page :
    https://invazion.nadazone.fr/api/user
  • Champs à prévoir dans votre formulaire HTML :
    • action = create_citizen (valeur invariable)
    • pseudo = le pseudo saisi par le joueur (ex : SuperDupont)
    • token = le jeton d'authentification du joueur (créé lors de sa connexion)
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é
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.

Faire agir le joueur dans le désert
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 :
- west (gauche)
- east (droite)
- northwest (haut+gauche)
- northeast (haut+droite)
- southwest (bas+gauche)
- southeast (bas+droite)

► 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.

Indiquez dans le paramètre target_id l'ID de la ville vers laquelle le joueur doit être déplacé.

Fouiller la zone api/zone?action=dig&token=...
Explorer un bâtiment api/city?action=explore&token=...
Déposer un objet au sol api/zone?action=drop&item_id=3&token=..
Ramasser un objet api/zone?action=pickup&item_id=3&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 :
api/me?action=heal&item_id=23&token=...

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 :
api/me?action=heal&item_id=23&target_id=120&token=...

Indiquez dans le paramètre target_id l'id du citoyen à soigner.

Choisir sa spécialité api/me?action=specialize&type=explorer&token=...

3 valeurs sont possibles pour le paramètre type :
- digger : fouineur (points d'action : 2, fouilles auto : 30 mn)
- explorer : explorateur (points d'action : 6, fouilles auto : 2 h)
- builder : bâtisseur (points d'action : 10, fouilles auto : 6 h)

Faire agir le joueur dans les villes
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.
Le paramètre city_size indique le nombre maximal de citoyens que la ville peut accueillir.

Connecter son habitation à une ville api/city?action=connect&token=...
Détruire une tente dans la zone api/city?action=attack&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.
C'est la même action qui sert à entrer et sortir :
> Si le citoyen n'est pas en ville, l'action l'y fera entrer.
> Si le citoyen est déjà dans la ville, l'action l'en fera sortir.

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.

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.

Construire un chantier api/buildings?action=build&construction_id=101&token=...

Le paramètre construction_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/well?action=pickup&token=...
Ajouter de l'eau dans le puits api/well?action=add&token=...
Actions liées aux cryptes
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 :
api/zone?action=add&stuff=zombies&conditions=noconditions&token=...

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.

Espace de discussion
Obtenir la liste des discussions

Obtenir la liste des discussions

  • Méthode par défaut :
    api/discuss/threads?action=get
    => Tri : les discussions sont listées selon leur ordre de création, de la plus ancienne à la plus récente. Le marquage « discussion épinglée » n'a pas d'effet sur le tri (v. &pinnedfirst ci-dessous).
    => Index : les clés d'indexation sont les ID des discussions.
  • Pour trier les sujets par ordre de dernière réponse, ajoutez le paramètre &sort :
    api/discuss/threads?action=get&sort=last_message_date
    => Tri : Les discussions sont triées selon la date de la dernière réponse qu'ils ont reçue, de la plus récente à la plus ancienne. Le marquage « discussion épinglée » n'a pas d'effet sur le tri (v. &pinnedfirst ci-dessous).
    => Index : ici les clés d'indexation ne sont plus les ID des discussions mais une numérotation continue (0, 1, 2, 3...) afin de préserver l'ordre du tri.
  • Pour forcer les discussions épinglées à s'afficher systématiquement en haut de la liste, ajoutez le paramètre &pinnedfirst :
    api/discuss/threads?action=get&sort=last_message_date&pinnedfirst=1
    => Les discussions sont marquées « épinglées » lorsque l'on veut les forcer à s'afficher en premier en raison de leur importance particulière. Ce statut est visible dans les résultats de l'API grâce à l'attribut is_pinned (voir ci-dessous).
    => pinnedfirst n'a d'effet que si un tri a été précisé avec &sort.
  • Pour récupérer le contenu complet des messages plutôt qu'un extrait, ajoutez le paramètre &fullmsg :
    api/discuss/threads?action=get&fullmsg=1
    Si ce paramètre n'est pas précisé ou a une autre valeur, seul un extrait du message sera retourné : v. plus bas, la clé first_message>message.

Résultats renvoyés par l'API

Chaque clé retournée par l'API contient les informations relatives un fil de discussion :

  • topic_id : l'ID du fil de discussion (unique).
  • title : le titre du fil de discussion. L'API le sécurise en convertissant les caractères spéciaux en entités HTML afin d'éviter les injections de code. Vous pouvez cependant faire vos propres validations pour renforcer la sécurité.
  • nbr_messages : le nombre de messages dans le fil de discussion, en comptant celui qui a ouvert la discussion. Si vous voulez afficher le nombre de réponses au sujet, enlevez 1 à ce nombre.
  • states : marqueurs des états du sujet (cumulables) :
    • is_pinned : le fil est épinglé en haut de la liste
    • is_locked : le fil est verrouillé
    • is_solved : le fil est marqué « résolu »
    • is_read : le fil a été lu. L'utilisateur doit être identifié.
  • first_message : informations relatives au premier message qui a ouvert le fil de discussion.
    • message_id : L'ID du premier message. Utile si vous voulez amener l'utilisateur directement au message grâce à une ancre HTML, au lieu de l'envoyer simplement en haut de la page du fil de discussion.
      Exemple d'url amenant au message :
      http://invazion.nadazone.fr/discuss/topic?topic=9#msg136
      => Amène au message n°136 (#msg136) du fil de discussion n°9 (topic=9)
      Notez que l'ID de message est unique dans tout l'espace de discussion, ce n'est pas une numérotation 1,2,3... à l'intérieur du fil. Par conséquent :
      - le premier message d'une discussion n'est pas "1" (sauf pour le message qui a lancé la toute première discussion du jeu) ;
      - les messages à l'intérieur d'un fil de discussion ne portent forcément des ID qui se suivent (si d'autres messages ont été postés entretemps dans d'autres discussions).
    • datetime_utc : la date à laquelle le message a été posté, au format ISO.
    • author_id : l'id de la personne qui a posté le message.
      > si elle était connectée au moment de poster : son id de membre ;
      > si elle n'était pas connectée : vaut "null".
    • author_pseudo : le nom de la personne qui a posté le message.
      > si elle était connectée au moment de poster : son pseudo de membre ;
      > si elle n'était pas connectée : le nom qu'elle a saisi librement au moment de poster.
    • message : un extrait du contenu du message, tronqué aux 150 premiers caractères. Si vous préférez récupérer le message entier, ajoutez le paramètre &fullmsg=1 dans l'url d'appel à l'API (v. plus haut).
  • last_message : informations relatives au dernier message posté dans le fil de discussion. La structure est la même que celle de first_message.
Obtenir les messages d'une discussion

Récupérer les messages d'une discussion

api/discuss/threads?action=get&topic_id=3

Indiquez dans paramètre &topic_id l'id du sujet à récupérer (dans cet exemple, nous récupérons le sujet n° 3).

Résultats renvoyés par l'API

  • topic_id : l'ID du fil de discussion (unique).
  • title : le titre du fil de discussion. L'API le sécurise en convertissant les caractères spéciaux en entités HTML afin d'éviter les injections de code. Vous pouvez cependant faire vos propres validations pour renforcer la sécurité.
  • nbr_messages : le nombre de messages dans le fil de discussion, en comptant celui qui a ouvert la discussion. Si vous voulez afficher le nombre de réponses au sujet, enlevez 1 à ce nombre.
  • states : marqueurs des états du sujet (cumulables) :
    • is_pinned : le fil est épinglé en haut de la liste
    • is_locked : le fil est verrouillé
    • is_solved : le fil est marqué « résolu »
    • is_read : le fil a été lu. L'utilisateur doit être identifié.
  • messages : contient la liste des messages de la discussion (voir ci-dessous). Chaque message est indexé par son id de message (à ne pas confondre avec l'id de la discussion topic_id).
Structure de chaque sous-clé dans messages :
  • message_id : L'ID du premier message. Utile si vous voulez amener l'utilisateur directement au message grâce à une ancre HTML, au lieu de l'envoyer simplement en haut de la page du fil de discussion.
    Exemple d'url amenant au message :
    http://invazion.nadazone.fr/discuss/topic?topic=9#msg136
    => Amène au message n°136 (#msg136) du fil de discussion n°9 (topic=9)
    Notez que l'ID de message est unique dans tout l'espace de discussion, ce n'est pas une numérotation 1,2,3... à l'intérieur du fil. Par conséquent :
    - le premier message d'une discussion n'est pas "1" (sauf pour le message qui a lancé la toute première discussion du jeu) ;
    - les ID de messages qui se suivent dans un fil de discussion ne sont pas forcément consécutifs (si d'autres messages ont été postés entretemps dans d'autres discussions).
  • datetime_utc : la date à laquelle le message a été posté, au format ISO.
  • author_id : l'id de la personne qui a posté le message.
    > si elle était connectée au moment de poster : son id de membre ;
    > si elle n'était pas connectée : vaut "null".
  • author_pseudo : le nom de la personne qui a posté le message.
    > si elle était connectée au moment de poster : son pseudo de membre ;
    > si elle n'était pas connectée : le nom qu'elle a saisi librement au moment de poster.
  • message : Le contenu du message.
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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page :
    https://invazion.nadazone.fr/api/discuss/threads
  • Champs à prévoir dans votre formulaire HTML :
    • action = create (valeur invariable)
    • title = le titre de la disussion à créer
    • message = le texte du message
    • token = le jeton d'authentification du joueur (s'il est connecté à son compte)
    • guest_pseudo = le pseudo saisi par l'auteur du message (inutile si l'auteur est déjà connecté)
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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page :
    https://invazion.nadazone.fr/api/discuss/threads
  • Champs à prévoir dans votre formulaire HTML :
    • action = reply (valeur invariable)
    • topic_id = l'ID du fil de discussion auquel le joueur répond
    • message = le texte du message
    • token = le jeton d'authentification du joueur (s'il est connecté à son compte)
    • guest_pseudo = le pseudo saisi par l'auteur du message (inutile si l'auteur est déjà connecté)
L'attaque zombie quotidienne
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 :
api/events?action=get&type=cyclicattack

> Pour obtenir l'historique d'une ville précise, indiquer l'ID de la ville souhaitée grâce au paramètre &city_id :
api/events?action=get&type=cyclicattack&city_id=141

Vous pouvez choisir l'ordre chronologique en ajoutant le paramètre &sort :
- &sort=desc pour lister les entrées de la plus récente à la plus ancienne
- &sort=asc pour lister les entrées de la plus ancienne à la plus récente
- Si le paramètre &sort n'est pas fourni ou contient une autre valeur, le tri &sort=asc sera appliqué par défaut.

Historique des actions des joueurs

api/events?action=get&type=map

Chaque événénement est décrit par les clés suivantes :
  • event_type : indique le type d'événement :
    - "attack_citizen" = un citoyen en a agressé un autre
    - "heal_citizen" = un citoyen a soigné la blessure d'un autre
  • is_success : vaut "1" si l'action a réussi, "0" si elle a échoué.
  • author : contient l'id et le pseudo du citoyen qui a réalisé l'action
  • target : contient l'id et le pseudo du citoyen ciblé par l'action (ex : le citoyen visé par une agression)
Début et fin de partie
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.

api/events?action=startgame&token=....

Gagner la partie Utilité : s'enfuir dans la voiture pour remporter la partie (si les conditions sont remplies).

api/events?action=wingame&token=....

Valider sa mort Utilité : commencer une nouvelle partie après avoir été tué.

api/me?action=validate_death&token=....

Récompenses et classements
Obtenir le top 10 des survivants Utilité : classement des citoyens actuellement en vie ayant survécu le plus longtemps.

api/citizens?action=get&map_id=1&top=survival

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
Configuration du jeu
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 :

  • map : caractéristiques générales de la partie (taille de la carte, nombre de points d'action pour se déplacer...)
  • specialities : caractéristiques des spécialités des citoyens
  • items : caractéristiques des objets (nom, description...)
  • constructions : caractéristiques des chantiers (ressources nécessaires, défenses apportées...)
  • pictos : caractéristiques des pictos (nom, description...)
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).
Si vous rencontrez des difficultés, de l'aide est disponible sur le Discord.

  • Votre formulaire HTML doit envoyer les données à cette page : api/configs
  • Champs à prévoir dans votre formulaire HTML :
    • action = create (valeur invariable)
    • type = item (valeur invariable)
    • token = le jeton d'authentification du joueur connecté (voir connecter le joueur à son compte)
    • item_characs = cette clé du formulaire contient, dans des sous-clés, les caractéristiques de l'objet à créer.
      Exemple : champ HTML permettant de saisir le nombre de points d'action que donnera l'objet au joueur :
      <input name="item_characs[ap_gain]"> Pour connaître les noms des caractéristiques disponibles (dans cet exemple : ap_gain), consultez les objets existants dans la clé items de l'API de configuration.
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 :

  • item_name : le nom de l'objet.
  • simulated_loot_rate : la probabilité de découverte de l'objet, sur 100.

Cette liste s'enrichira au fur et à mesure des développements.


Corriger une « erreur CORS »

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) :

Image erreur CORS

Si vous appelez une API d'InvaZion avec javascript, le blocage vient probablement d'une extension de votre navigateur . Notamment, l'extension PrivacyBadger de Firefox est connue pour bloquer les requêtes. Réglez l'extension afin qu'elle autorise les requêtes vers le serveur d'InvaZion. Par exemple, dans PrivacyBadger :

Image Privacy Badger

(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.


Générer la carte en HTML : exemple de code

Cet exemple de code simplifié vous aidera à comprendre comment la carte est générée en HTML. La démarche est la suivante :
  1. Une boucle va générer chaque ligne de la carte ;
  2. A l'intérieur de cette boucle, une seconde boucle va générer les cases composant la ligne ;
  3. En complément, comme nous générons une case hexagonale et non carrée, on décale 1 ligne sur 2 vers la droite (afin que les hexagones s'affichent imbriqués et non pas pointe contre pointe).
// 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.


Les coordonnées de la carte

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 :

[0:0][2:0][4:0]
[1:1][3:1]
[0:2][2:2][4:2]
[1:3][3:3]

Pourquoi ce système ?

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 :

[0:0][1:0][2:0]
[0:1][1:1]
[0:2][1:2][2:2]
[0:3][1:3]

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 :

[0:0][2:0][4:0]
[1:1][3:1]
[0:2][2:2][4:2]
[1:3][3:3]

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.


Format des dates ISO

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.

Pourquoi utiliser les dates ISO ?

Le format ISO évite toute ambiguïté dans les dates échangées par les API :

Conditions d'utilisation des API

Par principe, vous pouvez exploiter les API d'Invazion sans restrictions ni autorisation préalable. Certaines limites sont toutefois posées :