Lua scripting for Dofus Retro is the gateway to truly custom automation. Visual configuration covers the vast majority of what most players need, but a Lua script lets you describe exactly what your character should do, in what order and under which conditions. With MoonBot you get a full engine, a browser-based editor and public documentation, so you can go from zero to a first working script in a single session.
This tutorial is aimed at beginners. No prior programming experience is required: we start from the basics, explain how the engine is organized, then build a gather → bank → marketplace loop and a small combat routine together. Every example uses the engine's real syntax, taken from the official documentation: keep it open for the details of each function.
Why Lua on Dofus Retro
Lua is a lightweight, readable language built to be embedded inside applications. That makes it an ideal choice for driving a bot: the syntax is minimal, you learn the essentials in an hour, and there is nothing to install because everything runs in the cloud at MoonBot. You write, you run, you watch the live logs from your browser, even from a phone.
Why write Lua scripting for Dofus Retro instead of doing everything with the mouse in the interface? Because some sequences are too specific for a configuration panel: go harvest one particular resource, check your pods, return to the bank only past a threshold, sell a priority list on the HDV, then start over. A script expresses that logic in a few lines and repeats it flawlessly, day and night.
There is also a learning payoff. Once you understand how a few namespaces fit together, you stop thinking in terms of single clicks and start thinking in terms of routines. You can chain a gathering run into a crafting session, route the crafted items to the marketplace, then reroute the character to a new spot once a profession level is reached. That kind of conditional, stateful behavior is exactly where Lua shines, and it is far more robust than trying to stitch the same flow together with static settings alone.
Lua complements the interface, it does not replace it. You can reuse a combat or marketplace configuration you already built visually inside a script, and write only the glue that orchestrates everything.
The MoonBot Lua engine
MoonBot exposes 395 functions across 20 namespaces. A namespace is simply a thematic grouping: you reach a function with the namespace.function(...) notation. This structure makes the engine easy to explore: if you want to do something with the inventory you look at the inventory namespace; for the map, map; for the marketplace, hdv.
Here are the main namespace families to know as a beginner:
- structure — the anatomy of a script: the
move(),bank()andphoenix()functions and the step types. - fight — combat: turns, spells, targeting, placement.
- map — current map, map changes, movement, zaaps.
- inventory and character — bag, pods, equipment, level, kamas.
- hdv — listing items, buying and floor prices on the marketplace.
- craft and job — batch crafting, recipes, profession levels.
- config — script settings: resources to gather, bank threshold, accepted monsters.
- group — leader and mules, coordinated movement and fights.
- global, npc, exchange, quest, mount, pets, chat, merchant, fm, bot, controller — for everything else.
Each function is described in the public documentation with its parameters and return value. Keep that tab open while you code: it is your best ally.
Steps, scripts and loops
Before writing, you need to understand how a behavior runs. A step is a Lua table that names a map and what to do there: gather, fight, sell, deposit at the bank, then exit in a given direction. A MoonBot script returns these steps from three functions, and the engine chains them in a loop.
Here is the skeleton of a script, as presented in the documentation:
-- Gathering route: wheat around Astrub
function move()
return {
{ map = "5,-24", path = "right", gather = true },
{ map = "6,-24", path = "right", gather = true },
{ map = "7,-24", path = "bottom", gather = true },
}
end
-- Called when pods are full
function bank()
return {
{ map = "5,-17", sale = true }, -- Marketplace
{ map = "4,-17", npcBank = true }, -- Bank
}
end
-- Called if the character dies
function phoenix()
return { { map = "10,-5", phoenix = true } }
end
This skeleton shows three key ideas: move() describes the route, map by map; bank() takes over when the bag is full; phoenix() takes the character to the phoenix statue if it dies. You do not write a loop: once the route is done, the engine starts over. Note the -- that introduces a comment: use it generously.
Lua has only a handful of keywords, and you will meet most of the ones you use daily in this tutorial: function, return, end, local, if and then. Indentation is not required by the language, but it makes nested blocks far easier to read, so keep it consistent. When a condition gets complex, you can combine tests with and, or and not, for instance if pods >= 90 and level < 60 then. That is genuinely most of the grammar you need to be productive.
The built-in script editor
No external IDE, no local setup. From the MoonBot dashboard, open the script editor right in the browser. You write your Lua, save it and assign it to a bot. Logs stream in real time: you see every move, every harvest and every error the moment it happens.

The typical workflow is simple: write a small chunk of code, run it on a test account, read the logs, fix, repeat. Because everything is cloud-based, you can launch the script and then close your PC; the bot keeps going. That is one of the big advantages of a 100% cloud solution with no VPS.
Your first Lua script
Let's start with the simplest possible thing: print a message to the logs and read the character state. This confirms the editor works and gets you familiar with the syntax.
-- My very first script
function move()
global.printMessage("Script started")
local pods = inventory.podsP() -- pods as a percentage
local carte = map.currentMap() -- "x,y" coordinates
global.printMessage("Pods: " .. pods .. "%")
global.printMessage("Map: " .. carte)
global.printMessage("Kamas: " .. character.kamas())
return {} -- no movement for this test
end
Three Lua notions appear here. local declares a variable (always prefer local to avoid globals). The .. operator concatenates strings and numbers to build a message. Finally, each function returns a value: a number for inventory.podsP(), a string in "x,y" format for map.currentMap(). Run this script: if the values show up in the logs, you are ready for the next step.
Every function used here is described in the official documentation, with its parameters and return value. If in doubt, check the exact name there before copying a call.
Gather, bank and marketplace loop
Now the script that actually pays off: an automated gathering loop that empties at the bank then lists items on the marketplace. This is the classic scenario to farm kamas automatically, and it combines several namespaces.
-- Gather -> marketplace -> bank, in a loop
function move()
config.setGatherList({ "Blé" }) -- resources to gather
config.setHarvestMode("whitelist") -- only those on the list
config.setBankThreshold(90) -- bank() once pods reach 90%
config.setAntiAggro(true) -- avoids aggressive monsters
return {
{ map = "5,-24", path = "right", gather = true },
{ map = "6,-24", path = "right", gather = true },
{ map = "7,-24", path = "bottom", gather = true },
}
end
function bank()
return {
{ map = "5,-17", sale = true }, -- selling follows the Marketplace tab
{ map = "4,-17", npcBank = true }, -- deposit follows the Bank tab
}
end
Let's break down the logic. The engine walks the move() route and gathers on each map; once it reaches the end, it starts over. As soon as pods exceed the threshold, it runs bank(): a stop at the marketplace, where selling follows the Marketplace tab rules (one kama below the lowest price, lots, floor price), then a deposit at the bank, before resuming the route. MoonBot's world pathfinding handles movement between steps, zaaps and doors included.
For clean gathering, the resource list (whitelist or blacklist) and avoiding aggressive monsters take one line each, as shown above, or can be set from the interface. On a contested spot, replace gather with forcegather: the bot stays on the map and harvests each time the resource respawns. The gathering bot guide details the whole visual configuration side.
One detail worth internalizing early: a script should never assume an action succeeded. Maybe a resource got harvested by another player a split second before your bot arrived, or the bank was momentarily out of reach. Wrapping risky steps in a check, then logging the outcome, keeps the loop from silently spinning on a failed assumption. As your routines grow, this defensive style is what separates a script that runs for ten minutes from one that runs unattended for hours.
A small combat routine
Combat is richer, but the logic stays approachable. With the “Script” tactic selected in the Combat tab, the engine calls your fightManagement() function every time it is your turn. The idea: target the weakest enemy, check that the spell can reach it, cast it, then pass the turn.
-- Custom combat turn (“Script” tactic)
local SORT = 3 -- ID of the spell to cast (adjust as needed)
function fightManagement()
local cible = fight.getWeakestEnemy() -- living enemy with the fewest HP
if cible and fight.canCastSpellOnCell(SORT, cible.cellId) == "ok" then
fight.castSpell(SORT, cible.cellId)
end
fight.passTurn()
end
We see our building blocks again: conditions and namespaced calls. fight.canCastSpellOnCell() returns "ok" or the reason the cast is refused (range, line of sight, not enough AP…), which keeps you from casting a spell that is bound to fail. For a full combat system (configurable AI, strategic placement, challenges, summons, auto-boost), the visual configuration is still the fastest route; the script orchestrates edge cases. Our combat and leveling bot guide explains how to level up efficiently.
Botting breaks the Dofus terms of service and always carries a risk of sanction that no setting removes. Test on a mule and keep reasonable daily time ranges.
Best practices and debugging
A few habits make your scripts reliable and easy to fix:
- Break it into small steps. Test each block on its own before assembling everything.
- Log a lot. A
global.printMessage(...)at each key step shows you exactly where the script stops. - Use constants. Put your thresholds (pods, levels) in
localvariables at the top of the file. - Handle empty cases. Always check that a target or a resource exists before acting (
if x ~= nil then). - Start small. One area, one resource, then expand once it works.
For debugging, read the live logs in the editor. If a call fails, first check the name and parameters in the documentation. Most beginner errors come from an approximate function name or a missing parameter. The MoonBot Discord community also shares many ready-to-adapt examples.
Where to go next
You now have the foundations of Lua scripting for Dofus Retro: the engine philosophy, the 20 namespaces, the role of steps, the built-in editor and three scripts covering gathering, bank, marketplace and combat. The logical next step is to explore the documentation namespace by namespace and enrich your loops with your own conditions.
To compare MoonBot with other solutions and understand why its Lua engine stands out, read our best Dofus Retro bots 2026 comparison. And to get hands-on, create an account on the dashboard: the free tier (up to 5 bots, 1 bot for every 5 validated Discord invites) is plenty to write and test your first scripts. Check the pricing when you want to scale up, and join the Discord to talk with other scripters.
Want full examples? The GitHub repository moonbot-dofus-retro-scripts-lua collects open-source Lua scripts (MIT) ready to adapt: combat, farming, gathering and travel.



