# Canal JASS

> Les 1291 fonctions JASS dont disposent les créateurs de cartes s’appellent désormais par leur nom depuis l’extérieur du jeu : créer des unités, modifier des attributs, effets, panneaux, boîtes de dialogue, sons, caméra, brouillard… Quatre usages : console Farsight, ligne de commande, HTTP, Python.

Source: https://war3ai.com/fr/docs/jass/

Les **1291 natives JASS** que les créateurs de cartes peuvent utiliser dans leurs scripts s’appellent désormais toutes par leur nom depuis l’extérieur du jeu : créer des unités, modifier des attributs, afficher des effets, ouvrir des panneaux et des boîtes de dialogue, jouer des sons, déplacer la caméra, modifier le brouillard… De quoi personnaliser le jeu plus avant — assistance pour RPG, [compagnon IA](https://war3ai.com/fr/docs/companion/), mini-jeux maison, outils de débogage.

| Usage | Idéal pour | Point d’entrée |
|---|---|---|
| **Page « Console JASS » de Farsight** | Essayer à la main, modifier en voyant le résultat | Barre latérale « Système → Console JASS » : écrivez un script et cliquez sur Exécuter ; à droite, parcourez les fonctions par catégorie, un clic en insère une dans le script |
| **Ligne de commande** | Essayer à la main, ou en faire un fichier de script à relancer | `python -m openwar3 jass --inst 20` (interactif), `-e "code"`, `my_script.j`, `--list mot-clé` |
| **HTTP** | Programmes externes, dans n’importe quel langage | `POST /api/instances/{n}/jass`, etc. (voir plus bas) ; le serveur de Farsight n’écoute qu’en local |
| **Python** | Écrire des schémas, des compagnons, des outils | `g.jass.NomDeFonction(...)` ; les effets visuels et interactions courants sont regroupés dans `openwar3.visual` |

> **Attention**
>
> Trois limites, toutes dictées par le mécanisme :
> 
> - Seules les **parties solo** (contre l’ordinateur, sur votre machine) peuvent modifier le monde. Créer des objets ou modifier des unités unilatéralement depuis votre machine désynchroniserait les autres joueurs d’une partie multijoueur — en multijoueur, seules les fonctions en lecture seule sont autorisées (`Get*`, `Is*`, `Count*`…).
> - Réservé aux outils locaux : les appels passés via une connexion en tant que joueur (`Game(player=N)`) ou en mode équitable sont rejetés.
> - Uniquement pour les parties en solo ou hébergées vous-même en réseau local.
> 
> Pour ajouter des éléments à l’écran en multijoueur, utilisez le [canevas](https://war3ai.com/fr/docs/canvas/) : c’est le runtime qui le dessine lui-même, sans modifier l’état du jeu.

## Écrire un script

La console, la ligne de commande et HTTP utilisent le même format de script. Une instruction par ligne ; **vous pouvez coller du JASS tel quel** (`call` / `set` / `local`, `true` / `false` / `null`, codes à quatre caractères `'Hpal'`, commentaires `//`), ou écrire à la manière de Python :

```text
set h = hero()                                   // intégré : héros principal de notre camp
local texttag t = CreateTextTag()
call SetTextTagText(t, "|cffffcc00+128 critique !|r", 0.024)
call SetTextTagPosUnit(t, h, 60)
call SetTextTagVelocity(t, 0, 0.03)
call SetTextTagPermanent(t, false)
call SetTextTagLifespan(t, 4)
call SetTextTagVisibility(t, true)
call PingMinimapEx(h.x, h.y + 300, 3, 255, 0, 0, false)
set u = CreateUnit(Player(0), 'hfoo', h.x + 200, h.y, 270)
print("créé", u, "niveau du héros", GetHeroLevel(h))
```

- **Les variables sont mémorisées** : pour une même instance et une même partie, les variables définies par `set` dans un bloc restent utilisables dans le suivant ; elles sont effacées automatiquement à chaque nouvelle partie, et peuvent aussi l’être à la main.
- **Fonctions intégrées** : `hero()` héros principal de notre camp, `me()` joueur local, `unit('hfoo')` trouve une unité, `unit_at(x, y)`, `wait(secondes)`, `print(...)`. Sur une unité, on peut lire `.x`, `.y`, `.hp`, `.hp_max`, `.mana`, `.type`, `.owner`, `.level` ; les quatre opérations arithmétiques et les comparaisons sont prises en charge.
- **Pas de** `if`, `loop` ni `function` — pour écrire de la logique, utilisez `g.jass` en Python (ce sont de simples appels de fonction), ou écrivez un [schéma](https://war3ai.com/fr/docs/schemes/).
- En cas d’erreur, vous saurez à quelle ligne et pourquoi (fonction inexistante, mauvais nombre d’arguments, variable non définie…) ; les instructions qui précèdent l’erreur ont déjà pris effet.

Arguments et valeurs de retour :

| Dans la signature | Quoi passer | Remarques |
|---|---|---|
| Entier | Un nombre ; les codes à quatre caractères `'Hpal'` sont convertis automatiquement | |
| Réel | Un nombre | Le runtime le convertit au format attendu par le moteur |
| Booléen | `true` / `false` | |
| Chaîne | `"..."` | Le chinois et les codes couleur du jeu sont pris en charge ; les chaînes que le jeu conserve (texte flottant, panneaux, boutons, commandes de chat) sont copiées sur le moment : aucun risque |
| Handle | Un handle stocké dans une variable, ou une unité (ce que renvoie `hero()` est converti automatiquement en handle) | |
| Fonction (code) | Uniquement `null` | Impossible de fournir une fonction JASS depuis l’extérieur ; `TimerStart(t, 60, false, null)` fonctionne |
| Retour de type chaîne | — | Le moteur renvoie un index dans la table des chaînes : le texte ne peut pas être relu. Pour les noms d’unités, utilisez `g.map_data.name_of` |

## Catégories

Les fonctions sont classées d’après leur nom ; la partie droite de la console et `--list` suivent ce classement :

| Catégorie | Nombre | Exemples |
|---|---|---|
| Effets visuels | 80 | Texte flottant, éclairs reliant deux points, effets spéciaux, images au sol, marques au sol, couleur / taille / animation des unités |
| Panneaux d’interface | 146 | Panneaux multilignes, classements, fenêtres de compte à rebours, boîtes de dialogue, quêtes, texte à l’écran, signaux sur la mini-carte, dialogue avec portrait, filtres plein écran |
| Caméra | 44 | Champs de caméra, panoramique, tremblement de caméra |
| Sons et musique | 50 | Créer et jouer des sons, lancer une musique |
| Brouillard et vision | 25 | Zones visibles, activer / désactiver le brouillard |
| Objets / héros / unités | 63 / 32 / 161 | Créer des objets, définir le niveau d’un héros, changer de propriétaire, ajouter des compétences |
| Joueurs / alliances / ressources | 71 | Définir les alliances, modifier l’or et le bois |
| Déclencheurs / événements / minuteries | 62 | Créer des déclencheurs, enregistrer des événements, minuteries |
| Terrain / météo / destructibles | 45 | Effets météo, modifier le terrain, créer des destructibles |
| Déroulement de la partie | 57 | Vitesse de jeu, pause, heure du jour |
| Autres | … | Groupes d’unités et régions, stockage, scripts d’IA de l’ordinateur, conversions de types et maths, réponses aux événements… |

Le 2026-09-24, **94 d’entre elles** ont été appelées une par une en partie réelle, avec vérification visuelle de l’effet ; les autres passent par le même chemin, simplement sans vérification individuelle de leur effet.

> **Remarque**
>
> Les fonctions de la catégorie « réponses aux événements » (`GetTriggerUnit`, `GetClickedButton`…) n’ont de valeur qu’à l’instant où un déclencheur s’exécute ; appelées depuis l’extérieur, elles renvoient 0 ou une valeur vide. Pour savoir « si c’est arrivé », utilisez les compteurs d’événements décrits plus bas.

## HTTP

Serveur de Farsight (`127.0.0.1:8866` par défaut, écoute uniquement en local) :

```http
GET  /api/jass/natives?q=TextTag&cat=visual
POST /api/instances/20/jass        {"code": "set h = hero()\ncall PingMinimapEx(h.x, h.y, 3, 255, 0, 0, false)"}
     -> {"ok": true, "rows": [...], "printed": [...], "vars": {...}}
     -> en cas d'erreur : {"ok": false, "error": "第 2 行：...", "line": 2}
POST /api/instances/20/jass/call   {"name": "SetUnitScale", "args": [{"unit": 599669636}, 1.4, 1.4, 1.4]}
POST /api/instances/20/jass/reset  efface les variables mémorisées
```

Un argument unité s’écrit `{"unit": adresse}`, l’adresse étant le `addr` de l’unité dans l’instantané. Mesuré : 60 à 90 ms par requête.

## Python : g.jass et openwar3.visual

```python
j = g.jass
t = j.CreateTextTag()
j.SetTextTagText(t, "Bonjour", 0.024)  # mêmes règles d'arguments que dans les scripts ; les unités et objets de l'instantané se passent directement
j.signature("CreateImage")             # consulter la signature
```

`openwar3.visual.Visual(g)` regroupe les effets visuels courants déjà testés, une ligne par effet (appelez `v.tick()` à chaque tick : ce qui a expiré est supprimé, les liens et cercles qui suivent des unités sont déplacés ; `v.clear()` supprime tout) :

| Méthode | Effet |
|---|---|
| `float_text(texte, unité ou point, ...)` | Texte flottant : chiffres de dégâts, indications au-dessus de la tête, chinois et couleurs acceptés |
| `link(a, b, kind)` | Un lien entre deux unités, qui les suit : traction / lien spirituel / drain de vie / vague de soins |
| `effect(modèle, unité ou point, ...)` | Modèle d’effet spécial : au-dessus de la tête, sous les pieds, ou joué une seule fois (explosion, colonne de lumière) |
| `ring(unité ou point, rayon, color)` | Cercle au sol : portée d’un sort, zone dangereuse, point de ralliement ; peut suivre une unité |
| `ping(point, color)` | Signal sur la mini-carte |
| `board(titre, lignes...)` | Panneau multiligne en haut à droite (avec icônes), modifiable case par case |
| `countdown(titre, secondes)` | Fenêtre de compte à rebours en haut à droite, décomptée par le jeu lui-même |
| `scene(nom, texte, portrait)` | Dialogue avec portrait : le portrait du bas devient une unité qui parle, et un sous-titre « nom : texte » s’affiche à l’écran |
| `screen_tint(color, alpha)` | Filtre plein écran (par défaut, bords rougis : alerte de vie basse) |
| `sound(chemin)` / `reveal(point, rayon, secondes)` / `look(unité, ...)` | Jouer un son / dissiper le brouillard sur une zone / changer la couleur d’une unité, l’agrandir, lui faire jouer une animation, la faire clignoter |

## Interactions : savoir ce que fait le joueur sans écrire de fonction JASS

En JASS, réagir aux actions du joueur exige d’écrire une fonction de déclencheur, et on ne peut pas fournir de fonction depuis l’extérieur. La solution : **créer un déclencheur vide, sans condition ni action, y enregistrer seulement l’événement, puis compter combien de fois il s’exécute.** En test, un déclencheur vide compte bel et bien.

| Méthode | Usage |
|---|---|
| `chat_commands(["-follow", "-stay"])` → `.poll()` | Commandes tapées par le joueur dans le chat (correspondance exacte, ou sur le début) |
| `menu(titre, [boutons...])` → `.clicked()` | Menu de boutons au centre de l’écran : lequel a été cliqué |
| `hotkeys(("left", "right", "up", "down", "esc"))` → `.poll()` | Nombre d’appuis sur les flèches et sur Échap |
| `on("TriggerRegister...Event", arguments...)` → `.poll()` | Nombre d’occurrences de n’importe quel événement JASS : mort d’une unité, entrée dans une région, dégâts subis, minuterie… |

La limite : on sait seulement « combien de fois », pas « qui, ni quel texte ». Pour distinguer les auteurs, créez un compteur par objet. C’est ainsi que sont branchées les commandes de chat du [compagnon IA](https://war3ai.com/fr/docs/companion/).

## Précautions

- **Supprimez vous-même ce que vous créez** : textes flottants, liens, images, panneaux, déclencheurs… sinon ils restent indéfiniment (`Visual.clear()` supprime ce qu’il a lui-même créé). Le jeu affiche au maximum environ 100 textes flottants simultanés.
- **Les fonctions BJ ne sont pas des natives** : `CreateTextTagUnitBJ` et consorts sont assemblées à partir de natives dans le script de la carte, et ne sont pas disponibles ici — reproduisez leur implémentation avec des natives.
- **Certaines constantes doivent d’abord être converties** : par exemple `ConvertPlayerColor(1)`, `ConvertFogState(4)` (valeurs possibles dans common.j).
- Environ 13 ms par appel (conversion des handles comprise) ; au niveau du protocole, ce sont les opcodes W3P 70 à 72, voir [Protocole W3P](https://war3ai.com/fr/docs/protocol/).