# 🧰 Vue d’ensemble

Cette page regroupe toutes les fonctions, variables et schémas disponibles dans les scripts Lua utilisés par le moteur. Tu trouveras ici :

Les fonctions à fournir (move, bank),
Les variables globales lues automatiquement (pods, monstres, récoltes…),
Le format précis des actions,
Et toutes les fonctions Lua que tu peux appeler dans ton script.

💡 Tous les exemples sont prêts à copier-coller dans Retype et testés avec le moteur.

# 🧭 Cycle d’exécution (logique interne)

Le moteur charge le script Lua et identifie les fonctions globales (move, bank, etc.).
Il exécute move() en boucle pour avancer dans le trajet.
Si pods ≥ MAX_PODS, il :
- Supprime les objets de AUTO_DELETE (si défini),
- Puis exécute bank() (si présente).
Si gather est présent → récolte selon ELEMENTS_TO_GATHER.
Si fight est présent → combat selon les règles (MIN_MONSTERS, MAX_MONSTERS, etc.).
Si custom est défini → la fonction est appelée avant le déplacement.

🧠 Le moteur est intelligent : si la valeur passée à path ou changeMap correspond à un ID de carte ou à une zone éloignée, il prendra automatiquement le Zaap le plus proche pour s’y rendre.

# ✅ Fonctions obligatoires

# 🔀 `move()`

Fonction principale exécutée en boucle. Elle doit retourner un tableau d’actions.

function move()
  return {
    { map = "5,7", gather = true, path = "bottom" },
    { map = "5,8", fight = true, path = "right" },
  }
end

# 🏦 `bank()`

Appelée automatiquement quand les pods dépassent la limite (MAX_PODS).

function bank()
  return {
    { map = "4,7", path = "left" },
    { map = "4,6", npcBank = true },
  }
end

⚠️ Si bank() n’est pas défini, le bot stoppe lorsque les pods sont pleins.

# 🌐 Variables globales

Les variables globales configurent ton comportement par défaut. Place-les en haut de ton script.

-- Récolte
ELEMENTS_TO_GATHER = { 45, 46, 47 }

-- Pods
MAX_PODS = 88
AUTO_DELETE = { 1234, 5678 }

-- Combat
MIN_MONSTERS = 1
MAX_MONSTERS = 4
FORBIDDEN_MONSTERS = { 666, 999 }
FORCE_MONSTERS = {}

-- Verrous de combat
FIGHT_LOCK_SPEC = true
FIGHT_LOCK_JOIN = false
FIGHT_LOCK_PARTY = true

# 🧱 Structure d’une action

Chaque action est une table contenant une ou plusieurs clés parmi celles ci-dessous :

Clé	Type	Description
`map`	`string` ou `int`	Carte ciblée par l’action (`"x,y"` ou `mapId`).
`gather`	`bool`	Récolte les éléments interactifs présents (utilise `ELEMENTS_TO_GATHER`).
`fight`	`bool`	Tente un combat si un groupe correspond aux règles (`MIN_MONSTERS`, `MAX_MONSTERS`, `FORBIDDEN_MONSTERS`, `FORCE_MONSTERS`).
`custom`	`string` ou référence de fonction	Nom d’une fonction sans arguments appelée avant le déplacement (`path`/`changeMap`).
`path` / `changeMap`	`string`/`int`	Déplacement : `"top"`, `"bottom"`, `"left"`, `"right"` ou `"zaap(12345)"` ou un `mapId` distant.
`cell`	`int`	Se place sur la cellule. Si c’est une sortie, change de map.
`door`	`string`	Réservé (présent mais non utilisé/implémenté côté moteur).
`npcBank`	`bool`	Ouvre la banque PNJ, dépose tout puis ferme.
`chestGuild`	`bool`	Ouvre le coffre de guilde et dépose l’inventaire.
`chestGuildNumber`	`int`	Numéro de coffre de guilde à utiliser (défaut : `1`).
`lockedHouse`	`string`	Format `"NomDuPersonnage \| CodeMaison"` (`-1` si proprio).
`lockedStorage`	`string`	Format `"Cellule \| CodeCoffre"` (`-1` si pas de code requis).
`crafting`	`bool`	Enchaîne une séquence de craft après la banque PNJ.
`craftItemGid`	`int`	GID de l’item à crafter.
`craftBankMapId`	`int`	MapId de la banque pour le craft.
`craftWorkshopMapId`	`int`	MapId de l’atelier de craft.
`craftSpecialWorkshop`	`bool`	Utilise un atelier spécial.
`craftReturnBank`	`bool`	Retourne à la banque après le craft.

💡 Le moteur peut automatiquement utiliser un Zaap s’il détecte que la destination (path ou changeMap) est trop éloignée ou correspond directement à un ID de carte.

# ⚙️ Fonction `custom`

Permet d’insérer une logique personnalisée dans le trajet.

function move()
  return {
    { map = "-31,-56", custom = "checkClass", path = "bottom" },
  }
end

function checkClass()
  local classId = getClass()
  if classId == 1 then
    printMessage("Je suis un Iop !", 'green')
  elseif classId == 2 then
    printMessage("Je suis un Cra !", 'blue')
  else
    printMessage("Classe inconnue : " .. tostring(classId), 'yellow')
  end
end

🔸 Le path est exécuté après la fonction custom.

Permet d’insérer une logique personnalisée dans le trajet.

function move()
  return {
    { map = "-31,-56", custom = "checkClass", path = "bottom" },
  }
end

function checkClass()
  local classId = getClass()
  if classId == 1 then
    printMessage("Je suis un Iop !", 'green')
  elseif classId == 2 then
    printMessage("Je suis un Cra !", 'blue')
  else
    printMessage("Classe inconnue : " .. tostring(classId), 'yellow')
  end
end

🔸 Le path est exécuté après la fonction custom.

# 📚 Référence détaillée des fonctions Lua

Ci‑dessous, toutes les fonctions exposées au Lua par le moteur, avec description, paramètres, valeur de retour et un mini‑exemple.

# 🖨 Logs & contrôle du script

printMessage(message: string, color: string) Affiche un message dans la console front. Couleurs usuelles : green, yellow, red, blue, orange, info.
```
printMessage("Lancement du trajet", "green")
```
delay(ms: int) Pause bloquante (millisecondes).
```
delay(500) -- 0,5s
```

stopScript() Arrête proprement le script courant.

if getPods() > getPodsMax() then stopScript() end

# 🗺 Carte & personnage

getCurrentPos(): string Renvoie la position courante au format "x,y".
```
local pos = getCurrentPos() -- ex: "-2,0"
```
getMapId(): int ID numérique de la carte actuelle.
```
local id = getMapId()
```

getPodsMax(): int, getPods(): int Pods max et pods actuels.

if getPods() * 100 / getPodsMax() > 90 then printMessage("Plein", 'yellow') end

getJobLevel(jobId: int): int Niveau d’un métier.
```
local peche = getJobLevel(36)
```
getCharacterLevel(): int Niveau du personnage.
getClass(): int Breed ID (classe).

getTeam(): array Tableau de membres { breedId, name, level }.

for _,m in ipairs(getTeam()) do printMessage(m.name .. ": " .. m.level, 'info') end

# 🎒 Inventaire & équipement

getInventoryItemCount(gid: int): int Quantité en inventaire pour un GID donné.
```
if getInventoryItemCount(7964) > 0 then useInventoryItem(7964, 1) end
```
getInventoryItemByGid(gid: int): table|nil Retourne { uid, gid, quantity } ou nil.
getEquippedItemAtPosition(position: int): table|nil Item équipé à une position (table ou nil).
useInventoryItem(gid: int, quantity: int): bool Utilise quantity de l’item gid.
equipItem(uid: int, position: int): bool Équipe l’item uid à la position.
unequipItem(uid: int): bool Retire l’item uid (retourne à l’inventaire).
DropItem(gid: int, quantity: int): bool Jette au sol.
deleteItem(gid: int): bool Supprime tout l’item (toute la quantité) s’il est présent.
```
deleteItem(313) -- supprime toutes les graines id 313
```

# Transferts (banque/coffre) — nécessite un dialogue ouvert

putAllItems(), putExistingItems() Dépose tout / dépose ce qui existe déjà côté conteneur.
getAllItems(), getExistingItems() Récupère tout / récupère uniquement les doublons.

# 🏠 Maison / Coffres / Stockage

goToAndEnterHouse(doorMapId: int, nickname: string, code: string): bool Se rend à la map, interagit avec la porte portant le nickname, entre (code -1 si proprio).
```
goToAndEnterHouse(123456789, "NomDuPerso", "CodeMaison")
```
goAndOpenChest(chestMapId: int, chestCellId: int, code: string): bool Se rend à la map, ouvre le coffre et charge TempStorage (code -1 si pas requis).

# 🗺 Déplacements & interactions

goToCellId(cellId: int): bool Se place sur une cellule de la carte.
changeMapByCellId(cellId: int): bool Équipe : va à la cellule et change de map.
teamGoToCellId(cellId: int): bool Équipe : va à la cellule (sans changer de map).
goToMapId(mapId: int): bool Prend automatiquement le Zaap le plus proche puis se déplace jusqu’à mapId.
```
goToMapId(212862721)
```
goUseInteractive(cellId: int): bool Se déplace et utilise un interactif à la cellule.

# 🧑‍🤝‍🧑 Équipe

teamUseInventoryItem(gid: int, quantity: int): bool Tous les membres utilisent l’item.
```
teamUseInventoryItem(16554, 1) -- tout le monde mange du pain
```
upgradeCharacterStatsBatch(agi:int, str:int, vit:int, cha:int, int:int, wis:int): bool Monte plusieurs stats pour le personnage courant.
upgradeCharacterStatsBatchByName(name:string, agi:int, str:int, vit:int, cha:int, int:int, wis:int): bool Monte les stats pour un membre nommé.

# 💬 PNJ & dialogues

talkNpc(npcActorId: int): bool Équipe : ouvre un dialogue PNJ (action générique).
replyNpc(index: int): bool Équipe : choisit une réponse de dialogue par index.
replyNpcAndChangeMap(index: int): bool Équipe : répond puis attend explicitement l’événement de changement de map.
leaveDialog(): bool Équipe : ferme le dialogue courant.

# 🛒 Hôtel de vente (HDV)

openSellerHdv(cellId: int): bool Équipe : ouvre l’HDV vendeur (le cellId est ignoré par le backend).
sellAllItems(): bool Équipe : vend l’inventaire actuel.
closeSellerHdv(): bool Équipe : ferme le dialogue.

# 🔨 Craft

craftItem(itemGid: int, bankMapId: int, workshopMapId: int, special: bool, returnBank: bool): bool Démarre un craft pour itemGid, enchaîne banque/atelier, atelier spécial si special, retour banque si returnBank.
```
craftItem(324, 12345, 67890, false, true)
```

# 📦 Banque (TempStorage) — gestion fine par GID

getMaxQuantitesByGid(gid: int): bool Pendant un coffre/banque ouverts, retire du coffre la quantité max possible d’un GID (selon pods restants).
```
-- Depuis un coffre ouvert : prend le max de 16504 sans dépasser les pods
getMaxQuantitesByGid(16504)
```

# 🚀 Exemples complets

# 🔁 Récolte + Combat + Banque

ELEMENTS_TO_GATHER = { 45, 46 }
MAX_PODS = 90

function move()
  return {
    { map = "1,1", gather = true, path = "bottom" },
    { map = "1,2", fight = true, path = "right" },
    { map = "2,2", path = "top" },
  }
end

function bank()
  return {
    { map = "2,1", path = "left" },
    { map = "1,1", npcBank = true },
  }
end

# 🏠 Retour maison + coffre personnel

function bank()
  return {
    { map = "212862721", lockedHouse = "NomDuPersonnage|CodeMaison" },
    { map = "212340752", cell = "158" },
    { map = "212341776", cell = "242" },
    { map = "212342800", lockedStorage = "430|CodeCoffre" },
  }
end

🏡 Le bot entre automatiquement dans la maison, avance jusqu’au coffre et y dépose les ressources.

# 🏦 Retour banque PNJ

function bank()
  return {
    { map = "212862721", npcBank = true },
  }
end

💰 Le bot interagit avec le PNJ de la banque et dépose tous les objets.

# 🛡️ Retour coffre de guilde

function bank()
  return {
    { map = "212862721", chestGuild = true, chestGuildNumber = 1 },
  }
end

🏰 Le bot ouvre le coffre de guilde spécifié et y dépose automatiquement le contenu de son inventaire.

# ⚔️ Combat Donjon : Mastodonte

MAX_PODS = 93
FIGHT_LOCK_SPEC = true
FIGHT_LOCK_JOIN = true

function MastodonteEntree()
    talkNpc(-20000)
    replyNpc(0)
    replyNpcAndChangeMap(0)
end

function MastodonteEntreePDA()
    talkNpc(-20000)
    replyNpcAndChangeMap(0)
end

function MastodonteSortie()
    talkNpc(-20001)
    replyNpcAndChangeMap(0)
end

function move()
    return {
        { map = "173280513", custom = MastodonteEntree },
        { map = "174326272", fight = true }, -- salle 1
        { map = "174327296", fight = true }, -- salle 2
        { map = "174328320", fight = true }, -- salle 3
        { map = "174329344", fight = true }, -- salle 4
        { map = "174330368", fight = true }, -- salle 5
        { map = "174331392", custom = MastodonteSortie },
    }
end

function bank()
    return {
        { map = "212862721", chestGuild = true, chestGuildNumber = 1 },
    }
end

# 🧩 Explication

MAX_PODS = 93 → le bot dépose les ressources quand il atteint 93% de pods.
FIGHT_LOCK_SPEC et FIGHT_LOCK_JOIN → empêchent les autres joueurs de rejoindre ou de regarder les combats.
MastodonteEntree() → parle au PNJ d’entrée du donjon et téléporte le joueur à la salle 1.
MastodonteEntreePDA() → version alternative via pierre d’âme (PDA).
MastodonteSortie() → parle au PNJ de sortie pour quitter le donjon.
Chaque map représente une salle du donjon, avec un combat (fight = true).
À la fin, le bot sort automatiquement puis, si les pods sont pleins, dépose les ressources dans le coffre de guilde.

🧭 Astuce : combine ces fonctions pour créer des routes modulaires (ex: goToBank(), goToWorkshop(), checkAndOpenBag()). Chaque fonction peut retourner un tableau d’actions et être appelée depuis custom pour construire des trajets dynamiques.

# 🌌 Farm Incarnam + retour maison Astrub (placeholders)

MAX_PODS = 90
ELEMENTS_TO_GATHER = {}
IGNORE_ZAAP = true                 -- (flag perso) non lu par le moteur, utile si tu veux t’en servir dans tes customs
FIGHT_LOCK_PARTY = true
FIGHT_LOCK_JOIN  = true
FIGHT_LOCK_SPEC  = true
FORCE_MONSTERS   = { 4107, 982, 3270, 3271, 3272, 3273, 4105, 4106 }
AUTO_DELETE      = { 16515, 16523, 2473, 2474, 2475, 2476, 2477, 2478, 16518, 16504 }
MIN_MONSTERS     = 1
MAX_MONSTERS     = 8

-- Flag global
incarnam = true

-- === Utils Logs ===
local function b2s(v) return v and "true" or "false" end
local function logInfo(msg)  printMessage("[INFO] "  .. msg, "green")  end
local function logWarn(msg)  printMessage("[WARN] "  .. msg, "orange") end
local function logError(msg) printMessage("[ERROR] " .. msg, "red")    end

-- Normalise la position courante en "x,y"
local function normalizePos(pos)
    if type(pos) == "string" then return pos end
    if type(pos) == "table" and pos.x and pos.y then
        return tostring(pos.x) .. "," .. tostring(pos.y)
    end
    return tostring(pos)
end

-- Route Incarnam (boucle de farm)
local ROUTE_INCARNAM = {
    { map = "154010883", path = "153878787", gather = false, fight = true },
    { map = "153878787",  path = "153879299", gather = false, fight = true },
    { map = "153879299",  path = "153879298", gather = false, fight = true },
    { map = "153879298",  path = "153879297", gather = false, fight = true },
    { map = "153879297",  path = "153879040", gather = false, fight = true },
    { map = "153879040",  path = "153879552", gather = false, fight = true },
    { map = "153879552",  path = "153879809", gather = false, fight = true },
    { map = "153879809",  path = "153880321", gather = false, fight = true },
    { map = "153880321",  path = "153880322", gather = false, fight = true },
    { map = "153880322",  path = "153879810", gather = false, fight = true },
    { map = "153879810",  path = "153879811", gather = false, fight = true },
    { map = "153879811",  path = "153880323", gather = false, fight = true },
    { map = "153880323",  path = "153880835", gather = false, fight = true },
    { map = "153880835",  path = "154010883", gather = false, fight = true },
}

-- Set pour lookup O(1)
local ROUTE_SET = {}
for _, step in ipairs(ROUTE_INCARNAM) do
    ROUTE_SET[step.map] = true
end

local function isOnIncarnamRoute(mapId)
    return ROUTE_SET[mapId] == true
end

-- ==== CUSTOM HELPERS (sans arguments !) ====
function interactWithPortalToIncarnam()
    local ok, err = pcall(function() interactWithPortal(true) end)
    if not ok then logError("interactWithPortalToIncarnam: " .. tostring(err)) end
end

function interactWithPortalToAstrub()
    local ok, err = pcall(function() interactWithPortal(false) end)
    if not ok then logError("interactWithPortalToAstrub: " .. tostring(err)) end
end
-- ==========================================

function gotoIncarnam()
    logWarn("Hors route Incarnam : retour vers Incarnam (via portail)…")
    return {
        -- IMPORTANT : fonction globale SANS ARGUMENTS
        { map = "192416776", custom = interactWithPortalToIncarnam }
        -- Si ton moteur exige un STRING au lieu d’une référence de fonction :
        -- { map = "192416776", custom = "interactWithPortalToIncarnam" }
    }
end

function move()
    local currentId  = tostring(getMapId())  -- mapId numérique
    local currentPos = normalizePos(getCurrentPos())
    local onRoute    = isOnIncarnamRoute(currentId)
    incarnam = onRoute

    logInfo(string.format("Position: %s (mapId=%s) | onRoute=%s | incarnam=%s", currentPos, currentId, b2s(onRoute), b2s(incarnam)))

    if not onRoute then
        logWarn("Je ne suis pas sur la boucle Incarnam → redirection…")
        return gotoIncarnam()
    end

    local first = ROUTE_INCARNAM[1]
    local last  = ROUTE_INCARNAM[#ROUTE_INCARNAM]
    logInfo(string.format("Boucle Incarnam (%d étapes) : %s → … → %s", #ROUTE_INCARNAM, first and first.map or "?", last and last.map or "?"))

    return ROUTE_INCARNAM
end

function bank()
    logInfo("Banque : retour maison (Astrub)")
    return {
        { map = "153880835", custom = interactWithPortalToAstrub }, -- portail vers Astrub
        { map = "192416776", path = "68552192" },                  -- déplacement vers quartier
        { map = "68552192",  lockedHouse = "NomDuPersonnage|CodeMaison" }, -- PLACEHOLDER maison Astrub
        { map = "95160837",  cell = "330" },                       -- navigation intérieure
        { map = "95161861",  lockedStorage = "347|CodeCoffre" },   -- PLACEHOLDER coffre maison (cellId|code)
    }
end

function interactWithPortal(state)
    if state then
        printMessage("Je vais vers Incarnam", "info")
        goUseInteractive(455)
    else
        printMessage("Je vais vers Astrub", "info")
        talkNpc(-20001)
        replyNpcAndChangeMap(0)
    end

    incarnam = state
    logInfo("Portail utilisé. incarnam=" .. b2s(incarnam))
end

Ce que fait le script

Farm en boucle une route d’Incarnam (listée via ROUTE_INCARNAM) en enchaînant les cartes avec fight = true.
Si le bot sort de la route, gotoIncarnam() le ramène automatiquement via le portail.
MAX_PODS = 90 et AUTO_DELETE permettent d’alléger l’inventaire ; en cas de pods pleins, bank() :
- passe par le portail vers Astrub,
- va jusqu’à une maison à Astrub (lockedHouse = "NomDuPersonnage|CodeMaison"),
- se déplace jusqu’au coffre (lockedStorage = "CellId|CodeCoffre") et dépose.
Les verrous FIGHT_LOCK_* sécurisent les combats (pas de spectateurs, pas d’intrus, réservé à l’équipe).

🔎 Note : IGNORE_ZAAP est un flag d’exemple non interprété par le moteur tel quel (libre à toi de l’utiliser dans tes customs). Le moteur, lui, sait automatiquement prendre un Zaap si un path/changeMap pointe vers une mapId lointaine.