A Lua addon system for the client. An addon is a folder of Lua files the client loads at start and runs in a sandbox. Everything it may touch arrives through one hafen.* API. Read the game state and react to events. Draw your own UI. Add hotkeys and console commands. Restyle the client. With the user’s permission, drive the character.
-- addons/myaddon/main.lua
hafen.event():on("SessionEnteredWorld", function(session)
hafen.log():write("hello from " .. (session:character() or "?"))
end)
hafen.timer():every(5, function()
local session = hafen.session():current()
if session then hafen.log():write("trees nearby: " .. session:world():gob():count("terobjs/tree")) end
end)
That is a whole addon beside a manifest.json naming it. Nothing above needs a permission, a build step or a restart: drop the folder into addons/, type :reload, and it runs.
| Page | Read it when |
|---|---|
| Getting started | You have not written one yet: from an empty folder to a window with a hotkey that remembers its state. |
| The guides | You know the shape and want to do a thing: read the world, schedule work, draw UI, save data, add hotkeys, act, theme, translate, debug. |
| The API reference | You want a name: every namespace, verb, argument, return and error. |
| The manifest | What names an addon: the folder, the manifest field by field, the API version it declares. |
| The runtime | When your code runs, the sandbox, the CPU budgets, the console commands. |
| The AddOns manager | The Installed tab that enables, updates and removes an addon, and the Browse tab that searches the hub. |
| Macros | Your own Lua snippets, kept by the client on the Macros page of the game menu and run as a :lua line runs. |
| Dev tools | Three addons to point at your own while you write it, from the addons repository. |
One page per namespace, and a directory where a namespace is large. The reference index lists every page.
| Area | Namespaces |
|---|---|
| World | world · Gob · Position · map |
| Character | player · time · char · study · party · buff · meter |
| Subsystems | kin · speed · craft · quest · wound · fight · actionbar · chat |
| Acting | menugrid · flowermenu, and the protected verbs on player, world and items |
| UI | ui · the stylesheet · font · client |
| Your own content | asset · resource · virtual · entries in the action menu |
| Data and network | json · http · websocket · voice · steam |
| Infrastructure | event · timer · store · locale · console · log · sound |
| Page every other page assumes | Covers |
|---|---|
| Conventions | How the API is spelled and what a read gives back. |
| Threading | Where your handler runs and what it may reach. |
| References | Every kind of thing a verb takes. |
| Shapes | What a plain table of numbers looks like. |
| Data types | Every snapshot shape. |
| Events | The catalogue of what the client tells you about. |
[!WARNING] This documentation has been entirely generated using artificial intelligence. While efforts have been made to provide accurate and useful information, it may contain inaccuracies, omissions, or outdated information.
If you notice anything that is incorrect, unclear, or missing, please feel free to open an issue or submit a pull request with a correction.
Community contributions and corrections are always welcome!