Add-ons
More actions
Add-ons
An add-on is a player-created extension for Shroud of the Avatar, written in the Lua programming language. Add-ons can turn information the game already shows into custom windows, heads-up displays, trackers, alerts, and other interface tools. They are deliberately read-mostly: an add-on may observe supported game state and draw its own interface, but it cannot move a character, cast a skill, choose a target, loot an item, or complete a trade.[1]
Lua extensions existed before Release 154, but R154 made them a much more complete, supported system. The release added a sandbox and watchdog, opt-in loading, saved settings, native game windows, a broad documented API, and the in-game Community Addons catalog for reviewed packages.[2] In other words, add-ons graduated from loose scripts in a folder to respectable citizens of New Britannia—though they still need permission before coming through the door.
This system is unrelated to the Add-On Store, the former name of the game's real-money shop. Community Addons contains player-created software installed through the game client; the Add-On Store page covers website purchases.
Community add-on documentation
The Community Addons public catalog is the authoritative list of packages currently available through the game. SotAwiki's pages provide longer help, configuration notes, dependency explanations, and troubleshooting that add-on authors and users can maintain together.
| Add-on | Type | Author | Summary |
|---|---|---|---|
| Toolbox | Interface and tracking | shawn butts (shawn) | Configurable combat HUDs, crafting plans, experience and activity tracking, combat statistics, map tools, notifications, and optional market values. |
| Buff Monitor System (BMS) | Status and combat HUD | Garritt Grandberg (Tirrag) | Configurable player and pet buff displays, plus alerts for short combat opportunities. Requires SES. |
| Aggro Meter | Combat and threat HUD | Garritt Grandberg (Tirrag) | Displays the selected creature's threat list and can announce when the player or named pet gains aggro. |
| Crafters Ledger | Crafting and inventory planning | Kronic | Builds recipe shopping lists and helps locate materials across supported account storage. |
| FXStop | Visual-effects control | Garritt Grandberg (Tirrag) | Locally hides selected spell effects without changing combat or what other players see. Requires SES. |
| OCX Tools | Tracking and utilities | Feldon Grimshaw | Combat, crafting, gathering, loot, kill, experience, timer, and daily-total windows. |
| PawPad | Pet status and command-key HUD | Kronic | Shows pet health, buffs, stance, and reminders for the player's configured pet-command keys. |
| Player Quest System Engine (PQS) | Player-quest engine | Garritt Grandberg (Tirrag) | Runs quests supplied by separate community quest-library packages. Requires SES. |
| Point of Interest System (POIS) | Navigation and mapping | Garritt Grandberg (Tirrag) | Records, labels, tracks, imports, exports, and displays points on scene maps. Requires SES. |
| Rabbit Locations in Castle Atos | Point library | Garritt Grandberg (Tirrag) | Supplies the Castle Atos fox and rabbit daily-task locations to POIS. Requires POIS and SES. |
| SotA Event System (SES) | Developer event library | Garritt Grandberg (Tirrag) | Shared event infrastructure used by several add-ons; generally installed as a dependency. |
| SotaLore Skills | Skill-planner export | Darren Boyd (Gravidy) | Copies trained skill levels into SotaLore's skill planner or exports them to a local JSON file. |
| TotA Meter | Combat and build analysis | Tools of the Avatar | Measures personal and pet combat, runs a timed build test, and exports selected build data. |
Previously cataloged add-ons
- loctest — a location and map-beacon test display, retained as historical documentation after it left the catalog.
Add-on authors are welcome to expand their documentation beneath Add-ons/<name>. The add-on documentation guide provides a copyable overview-page skeleton, suggested subpages, version and safety conventions, and a publishing checklist. Toolbox and POIS show how a larger add-on can keep an inviting overview while moving detailed help into maintainable subpages. The catalog remains the place to install or update packages.
Finding help
Use the Community Addons catalog or the in-game /addons window to install and update packages. Use an add-on's SotAwiki overview and documentation subpages for walkthroughs, commands, configuration, and troubleshooting. When wiki instructions and a newer installed version differ, the installed add-on's help and the current catalog listing take precedence.
For a bug, feature request, or behavior that the documentation does not explain, follow the Support link in the add-on's infobox or catalog listing. Not every package supplies one. Add-on authors can consult the official Lua documentation for API behavior and use the wiki documentation guide when adding or updating player help here.
What add-ons can do
The supported API exposes bounded, player-visible information rather than unrestricted access to the client. Its exact surface grows with game updates, but the main uses include:[3]
| Area | Examples of available information or tools |
|---|---|
| Character and combat | Health, focus, gold, Vigor, targets, buffs and debuffs, combat events, damage and healing details |
| Activities | Experience gains, inventory changes, loot, known skills, quests, recipes, crafting, salvaging, and gathering results |
| World and community | Scene and compass information, weather and moon phase, map beacons, party state, friends, guild membership, and chat events |
| Interface | Native themed windows, compact panels, HUD strips, labels, images, bars, buttons, text fields, toggles, sliders, lists, grids, and tooltips |
| Player controls | Add-on chat commands, key bindings, window toggles, saved settings, notifications, sounds, and free-text emotes |
Add-on windows use the game's frame, visual theme, opacity, dragging, resizing, and remembered position. They carry a visible Add-on tag, sit below the game's own windows, and can all be hidden at once. An add-on may also replace the stock buff bar or the health and focus bars on the player frame; the originals return when that add-on is disabled.[1]
The API does not grant a second pair of adventuring hands. It has no supported calls for movement, combat actions, targeting, looting, or trading. Information is also limited to what the player is allowed to know: hidden creature statistics remain hidden, another player's private details are not opened up, and world effects are reported only within documented visibility limits.[1]
Finding and installing add-ons
The easiest route is the Community Addons window. Enter /addons in chat, or open the add-on manager and select Get Addons. The catalog lists approved packages with their author, description, install count, update date, required dependencies, and support link when one is supplied. Install, Update, and Remove manage the package in its own folder.[1]
Every newly installed add-on starts disabled. Read its description and requested permissions, then switch on Run in Community Addons or enable it in the add-on manager. Removing a catalog package deletes its installed files but keeps its saved variables, so reinstalling it later restores its settings.[1]
Add-ons can also be installed by hand. A traditional single-file add-on is a *.lua file placed in the game's Lua/ folder; a packaged add-on occupies one Lua/<slug>/ subfolder with a manifest and its supporting files. The add-on manager's Open Folder button or /lua path opens the correct location. Hand-installed files also start disabled.[1]
Useful commands
| Command | Purpose |
|---|---|
/addons
|
Open Community Addons |
/lua path
|
Open the local Lua folder |
/lua reload
|
Reload installed add-ons after files change |
/lua unload
|
Unload all add-ons |
/lua check
|
Report package problems that prevent loading or submission |
/lua hideui
|
Hide all add-on windows at once |
Safety and permissions
Add-ons run in a client sandbox. File operations are confined to the game's Lua/ folder, and calls that execute programs, exit the client, or read environment variables are disabled. A watchdog aborts a callback that runs too long, while an add-on that repeatedly errors in a short period is automatically disabled. Its errors and chat output are labelled with the add-on's name, which keeps a script from convincingly impersonating the game, a GM, or a private message.[1]
Internet access is a separate, opt-in permission. Only a packaged add-on may request it, and the package must list the exact hosts it intends to contact. The player then has to enable Internet for that add-on. Requests are limited to HTTPS GET operations, declared hosts, small text responses, and a modest request rate; redirects are checked again. A changed host list requires fresh approval. Loose *.lua files never receive network access.[1]
Packages in Community Addons pass an automated scan and human approval before they appear to other players. That review is an additional check, not a replacement for the sandbox or for reading what an add-on says it does.[1]
Creating an add-on
The official authoring guide covers installation, callbacks, interface construction, saved variables, feature detection, packages, and submission. The API reference is the function-by-function source of truth, while the examples provide complete add-ons that can be read, downloaded, and adapted.[3]
A simple add-on is one Lua file. It normally declares identifying metadata and whichever ShroudOn* callbacks it needs. ShroudOnStart() runs when the enabled add-on starts, event callbacks react to changes, and ShroudOnUpdate() handles work that genuinely belongs on each frame. New interface work should use Shroud.UI, which produces native themed windows and controls; two older drawing systems remain available for compatibility.[1]
Larger projects use a package folder and manifest.json. The manifest gives the package its stable slug, version, author, description, ordered Lua file list, minimum API version, dependencies, and any permissions. Packages may also include a small set of documented image, sound, data, icon, and README files. /lua check is the useful pre-flight inspection before sharing one.[1]
Creators submit from Community Addons with Submit to Community. The game packages a single-file add-on automatically, while multi-file projects should first be converted with Make Package or /lua package. New versions need increasing version numbers and are scanned and reviewed before approval. Submission status and reviewer messages appear under My Submissions.[1]
Because the API is versioned and updated alongside the game, creators should check ShroudLuaApiVersion, declare an honest minimum version, and consult the current reference rather than assuming a function exists on every client. The R154 work log recorded the API's rapid expansion from basic script hooks to native UI, detailed combat events, inventory and activity reports, packages, dependencies, media files, and permissions in the weeks before launch.[4]
References
- ↑ 1.00 1.01 1.02 1.03 1.04 1.05 1.06 1.07 1.08 1.09 1.10 1.11 Catnip Games: Lua add-on authoring guide, retrieved October 4, 2026.
- ↑ Catnip Games: What's New in Shroud of the Avatar, snapshot dated September 28, 2026.
- ↑ 3.0 3.1 Catnip Games: SotA Lua Addons documentation, retrieved October 13, 2026; documentation for API version 36.
- ↑ Catnip Games Work Log: September 21–27, 2026.