Skip to content

Making mods

Markdown
A step-by-step tutorial for Azeroth Survivors Reborn mods: the starter mod, your first change, the test loop, recipes for spells, talents, enemies, bosses, zones, modes and new classes, locking and publishing, the checker's messages and their fixes.

This guide takes you from nothing to a published mod. Read Mods first if you have never played one: it explains what a mod is, what it can do and what playing Modded means.

Every example on this page was checked with the game's own checker on a copy of the starter mod. Where something could only be checked by the game itself, the page says so.

What you will build, and what you need

You will make a mod: a folder that holds the game's content, your own package of changes and additions, and a lock that fingerprints every file. You test it in your own game, then share it as a folder or publish it in the game's community list.

You need:

  • The desktop game, installed. Mods do not play in the browser.
  • A text editor. Everything you write is plain text: TOML for content, JSON for the lock. An editor with TOML colouring catches typing errors early. Save as UTF-8.
  • The template kit in the azs-mods repository, folder templates/: a complete starter mod, one small example per task, and the registry entry for publishing. Download the repository as a zip from GitHub (Code, Download ZIP) or clone it.
  • The author tools, below.
  • The references: the content reference lists every field of every entry; the script guide is the boss script API.

If you have written WoW addons or private-server content before: there is no Lua in a mod (boss scripts aside) and no database. Content is TOML, the game reads it at start, and the ids you know from the 3.3.5 client (spell ids, CreatureDisplayInfo display ids, icon names) are how a mod names what the client shows.

Getting the tools

Two command-line tools check and lock a mod: azs-content (the checker) and azs-release (lock and pack). A third, azs-script, belongs to boss scripts. They are not in the game download. They come from the game's own source repository, which is not public. To get them, ask in the community Discord.

On this page they are written as azs-content and azs-release; on Windows they are azs-content.exe and azs-release.exe, run from a terminal in the folder that holds your mod folder.

How a mod is put together

The folder

This is the starter mod, templates/starter-mod/ in the kit:

starter-mod/
  profile.json                  the lock: every package, its version, every file's fingerprint
  LICENSE                       your licence (replace the placeholder)
  modes/standard.toml ...       the game's modes, as the kit carries them
  packs/base/...                the game's content: classic classes, zones, everything else builds on
  packs/tbc/...                 The Burning Crusade's zones and classes
  packs/wotlk/...               Wrath of the Lich King's zones and the Death Knight
  packs/yourname.example/       YOUR package
    pack.toml                   key = "yourname.example", requires = ["base"], order = 10
    overrides.toml              your changes and additions

You write only in your own package folder (and in profile.json, where the lock lists your files). The game's packs stay as they are: the lock names their exact bytes.

The words

  • Profile: the whole folder. The game imports a profile and plays it as one mod.
  • Lock: profile.json. It lists every package with its version and dependencies, the overrides each package makes, and every file with its kind and its BLAKE3 hash.
  • Package: one folder under packs/. The game's own are base, tbc and wotlk. Yours is named author.name.
  • Namespace: your package's name, author.name, in lower-case letters, digits, _ and -, for example yourname.example. Names that start with azs. belong to the game: the community list refuses them, so never use one.
  • Entry: one thing the game plays: a spell, a talent, a class, a zone, a boss kit, a mode. Each has a kind and a key.
  • New entry: one your package adds. Its key starts with your namespace: yourname.example:frost_focus. Two authors never take the same key that way.
  • Override: a change to an entry that already exists, written as [[override]] with the entry's kind, its key and only the fields you change. A field you write replaces the old one whole; fields you leave out stay as they were.

The rule for overrides

Every override is also declared in the lock, in your package's overrides list in profile.json: the entry you change (spell:fireball) and the package it comes from (base), which your package must require. An override the lock does not declare is refused, and so is a declaration your files never make. Two mods that do not depend on each other cannot change the same entry, even different fields of it. To build one mod on top of another, require it.

Your first change in ten minutes

You will make Fireball cast once a second, see the checker catch the change, lock it, and play it.

  1. Copy the starter. Copy templates/starter-mod/ out of the kit to a working folder, for example C:\mods\starter-mod\.
  2. Check it once, unchanged. In a terminal in C:\mods\:
    azs-content profile-check --profile starter-mod --json
    

    It prints one line of JSON. "ok":true and an empty "diagnostics":[] mean the folder passes. It also prints the mod's gameplay_hash.
  3. Make the change. Open starter-mod\packs\yourname.example\overrides.toml. It already overrides Fireball, and profile.json already declares that override. Change the cooldown:
    [[override]]
    kind = "spell"
    key = "fireball"
    hit = 60
    cooldown = 1.0
    
  4. See the lock catch it. Run the check again. It now fails, because the file's bytes no longer match the lock:
    {"diagnostics":[{"entry":"","file":"packs/yourname.example/overrides.toml","message":"TOML source hash differs from the profile lock","pack":"yourname.example"}],"ok":false}
    
  5. Lock it again.
    azs-release profile-lock starter-mod
    

    It hashes every locked file again, rewrites profile.json where a hash changed, and runs the same check:
    rehashed packs/yourname.example/overrides.toml
    starter-mod: 388 objects locked, 1 rehashed; the game's preflight passes
    

    (The number of objects depends on the kit's version.)
  6. Import it. Copy the starter-mod folder into UserData\mods\import\ in your game's install folder. Start the game, open MENU, Mods, and press Import. The window says starter-mod: imported as <a short code>.
  7. Choose it and restart. Press Choose on its row, restart the game, and the row says Playing now. Your runs are Modded from now on: a fresh save, heroes of its own.
  8. See it. Play a mage. Fireball now casts once a second.

To go back to the official game: MENU, Mods, Play official content, restart.

Make it yours

Before you build more, give the package your own name, in three places that must agree:

  1. Rename the folder packs/yourname.example/ to packs/<you>.<mod>/, for example packs/ayla.frostfire/.
  2. In its pack.toml, set key = "ayla.frostfire".
  3. In profile.json, in your package's entry: its "id", and the start of the "path" of each of its objects (packs/ayla.frostfire/...). Set the lock's "name" (at the top of "lock") to your mod's name too, in lower-case letters, digits, ., _ and - (ayla-frostfire); a name with spaces or capitals stops the lock with invalid profile name "Ayla Frostfire".

Then run azs-release profile-lock and the check. The renamed mod is a new mod to the game (two imports are one mod when they hold the same namespaced packages), so remove the old starter from the Mods window. Every new key you write from then on starts with ayla.frostfire:. The rest of this guide keeps yourname.example.

The test loop

Every change goes through the same five steps:

  1. Edit a file of your package.
  2. Lock: azs-release profile-lock <folder>. It prints rehashed <file> for each changed file and ends with the game's preflight passes, or it lists the problems and stops.
  3. Check (optional, the lock ran it already): azs-content profile-check --profile <folder> --json, the same check as JSON with the package, file and entry of each problem.
  4. Import again: replace your folder in UserData\mods\import\ with the new one and press Import. From version 0.7.2 the game replaces the older version of the same mod (imported as <code>; replaced the older version <code>), and a choice you made for the older version moves to the new one. A folder that did not change says already imported. The game does not watch the folder: import after every change.
  5. Restart the game. A choice applies only after a restart.

Adding a file

profile-lock hashes only the files the lock lists. A new file of your package needs an entry in your package's "objects" in profile.json first, with its path, its kind and any hash:

{ "path": "packs/yourname.example/zones/glade.toml", "hash": "0000000000000000000000000000000000000000000000000000000000000000", "kind": "gameplay" }

profile-lock then writes the real hash. A file in the folder that the lock does not list stops the lock:

not locked: packs/yourname.example/extra.toml
Error: 1 file(s) of the folder are not in profile.json's lock: remove them or list them there

The kinds you need: gameplay for every TOML file of your package, mode for a mode file, texture for a PNG, script for a boss script. The game decides nothing from a file's name alone.

Reading the Mods window

  • Playing now: the mod this game started with.
  • Chosen: the mod the next start will play.
  • Modded: the badge every mod carries.
  • Restart the game to apply.: a choice waits for a restart.
  • The import's messages stand under Import: what was imported, replaced, or not imported and why.

Saves, and starting clean

A mod's heroes live in a save of their own, in a folder named after the mod's gameplay hash beside the official save: the official save is UserData\survivors-save.tsv in your install folder, a mod's is UserData\survivors-save.tsv.profiles\<gameplay hash>\save.tsv. Every change to your content gives the mod a new gameplay hash, so each new version of your mod starts with an empty save. The heroes of the older version stay on disk, under the older hash, and come back if you import that exact version again. Your official save is never opened by a mod.

To start clean, close the game and delete that version's folder UserData\survivors-save.tsv.profiles\<gameplay hash>\ (the hash is the gameplay_hash that profile-check --json prints for it), or change any byte of your content and lock again: a new gameplay hash starts an empty save. Remove alone keeps the heroes: importing the same version again plays them again.

Recipes

Each recipe shows a file of your package and what it goes with. They were checked together in one copy of the kit's starter mod (the game's base, tbc and wotlk packs and one package, yourname.example) with azs-release profile-lock and azs-content profile-check, which passed; the rebuilt mage, which changes Fireball too, was checked in a copy of its own. The kit's templates/snippets/ folder holds one more example per task, each with a comment that says which file it goes in.

The texts below carry the English words in all twelve languages: that passes the check, but players then read English. See Languages.

Change a spell

Any .toml file of your package; an [[override]] is read wherever it stands in it. Here overrides.toml:

# Fireball casts faster.
[[override]]
kind = "spell"
key = "fireball"
cooldown = 1.0

Lock: { "dependency": "base", "entity": "spell:fireball" } in your package's overrides.

What you may write on a spell: school, shape, hit, cooldown, range, rider, builds, spends, name, icon and more; the content reference ("A spell") lists them all. The checker names the fields it knows when you misspell one. Find a spell's key in packs/<pack>/classes/<class>/spells.toml.

Add a talent to one of the twelve classes

A talent can stand on any row of a class's three trees (version 0.7.2; before, only on the last row). Put it in classes/<class key>/talents.toml of your package, here packs/yourname.example/classes/mage/talents.toml:

[[talent]]
key = "yourname.example:frost_focus"
tree = 2
row = 2
col = 3
ranks = 3
effects = []
icon = "Spell_Frost_FrostBolt02"
name = { en = "Frost Focus", de = "Frost Focus", fr = "Frost Focus", es = "Frost Focus", pt = "Frost Focus", ru = "Frost Focus", it = "Frost Focus", pl = "Frost Focus", tr = "Frost Focus", ja = "Frost Focus", zh = "Frost Focus", ko = "Frost Focus" }
text = { en = "Frost spells deal {v}% more damage.", de = "Frost spells deal {v}% more damage.", fr = "Frost spells deal {v}% more damage.", es = "Frost spells deal {v}% more damage.", pt = "Frost spells deal {v}% more damage.", ru = "Frost spells deal {v}% more damage.", it = "Frost spells deal {v}% more damage.", pl = "Frost spells deal {v}% more damage.", tr = "Frost spells deal {v}% more damage.", ja = "Frost spells deal {v}% more damage.", zh = "Frost spells deal {v}% more damage.", ko = "Frost spells deal {v}% more damage." }
menu_v = 0.04
mods = [{ school = 16 }]
mods_v = 0.04
  • The folder name is the class's key (mage, warrior, deathknight, ...). A new talent is no override and needs no lock declaration.
  • tree is 0, 1 or 2: the class's three trees. There is no fourth.
  • row is 0 to 6. The game's talents keep their places; yours stands after the talents of its row.
  • col is no coordinate: it only orders the talents of a row. The talent window stands a row's talents by how many it has, so a row never leans to one side.
  • req (optional) names a talent of a row above, in the same tree, that must be taken first.
  • {v} in the text is the talent's value per rank (menu_v); mods with mods_v is what it does in a run (here: more damage for frost spells, school 16).
  • A text that starts with Milestone. or Capstone. in English draws the talent as a milestone or capstone.

Rework or move a talent

An override of the talent, in any file of your package:

# Arcane Focus: three ranks instead of five, and on the second row.
[[override]]
kind = "talent"
key = "arcane_focus"
ranks = 3
row = 1

Lock: { "dependency": "base", "entity": "talent:arcane_focus" }. A talent moved to another row (row, col, version 0.7.2) stands among that row's. A name or text you write carries all twelve languages; effects, mods and plays are replaced as whole lists. A mod cannot remove a talent: change what it does instead.

A mod has its own saves, so its talents never shift the talent builds of the official game's heroes.

An enemy, an elite and a zone

A zone is one file, packs/yourname.example/zones/glade.toml, with its enemies, its elites and its bosses inside. Add it to the lock's objects as a gameplay file.

[[zone]]
key = "yourname.example:glade"
order = 50
name = { en = "Whispering Glade", de = "Whispering Glade", fr = "Whispering Glade", es = "Whispering Glade", pt = "Whispering Glade", ru = "Whispering Glade", it = "Whispering Glade", pl = "Whispering Glade", tr = "Whispering Glade", ja = "Whispering Glade", zh = "Whispering Glade", ko = "Whispering Glade" }
subtitle = { en = "The kobolds' last stand", de = "The kobolds' last stand", fr = "The kobolds' last stand", es = "The kobolds' last stand", pt = "The kobolds' last stand", ru = "The kobolds' last stand", it = "The kobolds' last stand", pl = "The kobolds' last stand", tr = "The kobolds' last stand", ja = "The kobolds' last stand", zh = "The kobolds' last stand", ko = "The kobolds' last stand" }
icon = "Achievement_Zone_ElwynnForest"
map = 0
map_name = "Azeroth"
area = 12
center = [-9530.0, 40.0]
radius = 100.0
map_bounds = [1535.4166, -1935.4166, -7939.583, -10254.166]
health_factor = 0.9
late_factor = 0.0
hour = 12
weather = { fine = 70, rain = 30 }

[[zone.enemy]]
entry = 970001
name = { en = "Glade Kobold", de = "Glade Kobold", fr = "Glade Kobold", es = "Glade Kobold", pt = "Glade Kobold", ru = "Glade Kobold", it = "Glade Kobold", pl = "Glade Kobold", tr = "Glade Kobold", ja = "Glade Kobold", zh = "Glade Kobold", ko = "Glade Kobold" }
type = "humanoid"
display = 26
icon = "INV_Misc_Head_Kobold_01"
health = 30
damage = 4
swing = 1.6
speed = 5.0
cost = 1.0
from = 0.0

[[zone.enemy]]
entry = 970002
name = { en = "Glade Wolf", de = "Glade Wolf", fr = "Glade Wolf", es = "Glade Wolf", pt = "Glade Wolf", ru = "Glade Wolf", it = "Glade Wolf", pl = "Glade Wolf", tr = "Glade Wolf", ja = "Glade Wolf", zh = "Glade Wolf", ko = "Glade Wolf" }
type = "beast"
display = 165
icon = "Ability_Hunter_Pet_Wolf"
health = 22
damage = 3
swing = 1.3
speed = 7.4
cost = 1.0
from = 1.0

[[zone.elite]]
entry = 970005
name = { en = "Glade Taskmaster", de = "Glade Taskmaster", fr = "Glade Taskmaster", es = "Glade Taskmaster", pt = "Glade Taskmaster", ru = "Glade Taskmaster", it = "Glade Taskmaster", pl = "Glade Taskmaster", tr = "Glade Taskmaster", ja = "Glade Taskmaster", zh = "Glade Taskmaster", ko = "Glade Taskmaster" }
type = "humanoid"
display = 163
icon = "INV_Misc_Head_Kobold_01"
health = 600
damage = 18
swing = 2.0
speed = 5.4
cost = 12.0
from = 3.5
size = 2.0

[[zone.elite.kit]]
every = 8.0
ability = { cone = { spell = 15284, range = 8.0, arc = 90.0, warn = 1.3, factor = 1.2 } }

[[zone.boss]]
entry = 970010
name = { en = "Old Greymane", de = "Old Greymane", fr = "Old Greymane", es = "Old Greymane", pt = "Old Greymane", ru = "Old Greymane", it = "Old Greymane", pl = "Old Greymane", tr = "Old Greymane", ja = "Old Greymane", zh = "Old Greymane", ko = "Old Greymane" }
type = "beast"
display = 165
icon = "Ability_Hunter_Pet_Wolf"
health = 4000
damage = 24
speed = 5.6
size = 3.0
minute = 3
yell = { en = "The glade is mine!", de = "The glade is mine!", fr = "The glade is mine!", es = "The glade is mine!", pt = "The glade is mine!", ru = "The glade is mine!", it = "The glade is mine!", pl = "The glade is mine!", tr = "The glade is mine!", ja = "The glade is mine!", zh = "The glade is mine!", ko = "The glade is mine!" }
final = true
kit = "yourname.example:greymane"
  • Where it stands. map, area, center, radius and map_bounds place the arena on the WoW maps. This example stands where Elwynn Forest's arena stands, with Elwynn's numbers. map_bounds must be the map rectangle the client shows there, or the minimap's pins sit in the wrong place; the content reference ("A zone") explains how to find it. The checker cannot see your client, so it does not test these numbers.
  • A zone needs normal enemies, elites, and exactly one boss with final = true. Without them the check says a zone needs normal enemies and elites or a zone needs exactly one final boss.
  • entry is the creature's number, unique in its zone (a number no other zone uses avoids confusion). display is a CreatureDisplayInfo id of the 3.3.5 client: any creature model it has. icon is a file name of the client's Interface\Icons\ (no folder, no extension), shown in the Codex.
  • cost is what the creature costs the wave director, from the minute it starts to come; a boss comes at its minute.
  • health_factor scales every enemy's health in the zone; hour is the time of day, weather the weights of fine, rain, snow, sand and storm.

A new zone joins every mode whose packs include all the packages yours requires. No mode names it, so it needs no mode of its own.

A boss kit

The abilities a boss uses and how often, packs/yourname.example/bosses/greymane.toml, named by the boss's kit:

[[boss]]
key = "yourname.example:greymane"

[[boss.kit]]
every = 9.0
ability = { cone = { spell = 15284, range = 8.0, arc = 90.0, warn = 1.4, factor = 1.0 } }

[[boss.kit]]
every = 15.0
ability = { summon = { entry = 970002, count = 6, spell = 42650, warn = 2.0, radius = 8.0 } }
  • every is the seconds between two uses; warn the seconds a hero sees the warning; factor the hit, times the boss's own.
  • spell is a 3.3.5 spell id: the look of the ability in the client, never its numbers.
  • summon calls the zone enemy with that entry, which must exist in the zone (kit 1: summon entry 970099 is not a zone enemy otherwise).
  • Other words: nova, ring, rain, charge, leap, adds, meteor, wave, stomp, combo and more (a misspelt word gets the whole list: unknown variant `circle`, expected one of `cone`, `nova`, ...), and phases with their own look ([[boss.phase]]). See "A boss kit" in the content reference.
  • A kit no boss fights with is refused: 0 zone bosses fight with this kit, where one should.

To change a boss of the game, override its kit: kind = "boss" and the kit's key (the key at the top of its file in packs/<pack>/bosses/), with the whole kit list you want, declared in the lock as boss:<key>. This one passes the check:

# Hogger charges every 6 seconds and calls more adds.
[[override]]
kind = "boss"
key = "hogger"
kit = [
  { every = 6.0, ability = { combo = [["charge", { cone = { spell = 15284, range = 8.0, arc = 90.0, warn = 1.4, factor = 1.0 } }], 1.6] } },
  { every = 12.0, ability = { adds = 8 } },
]

A game mode

A mode of your package is the file modes/yourname.example/<name>.toml at the top of the profile (not in packs/), listed in your package's objects with the kind mode. Its key is yourname.example:<name>. Here modes/yourname.example/frenzy.toml:

name = "Frenzy"
extends = "standard"

[card]
icon = "Ability_Druid_Berserk"
color = [0.8, 0.3, 0.1]
tag = "SOLO · CO-OP"
text = "The campaign, but the horde comes twice as fast."
rules = ["Enemies spawn twice as fast", "Runs stay off the leaderboards"]
rewards = [["INV_Misc_Coin_01", "Gold"]]

[horde]
spawn_rate = 2.0
  • extends = "standard" takes everything from the standard mode; you write only what differs. The [card] makes it show in the Game Modes window.
  • The other languages go into [i18n.de], [i18n.fr] and so on, each with name, tag, text, rules and rewards, as the game's own modes/swarm.toml shows. A language you leave out shows the English.
  • A mode that names its packs plays only the classes and zones of those packs. If a mode of the profile names your package, your package joins no other mode: your class is then missing there, and the hero menu says Not in this game mode.

Checked only in part: the checker (profile-check) passes this file, but it does not check modes themselves (its output says "runtime_modes_validated":false). The game checks the mode when it imports the mod; that step was not run for this guide.

A new class

A class of your own, on a free class id, in packs/yourname.example/classes/blood_knight/ with three files. class.toml:

key = "yourname.example:blood_knight"
id = 31
health = 250
power = "mana"
starter = "yourname.example:blood_strike"
races = [1, 10]
name = { en = "Blood Knight", de = "Blood Knight", fr = "Blood Knight", es = "Blood Knight", pt = "Blood Knight", ru = "Blood Knight", it = "Blood Knight", pl = "Blood Knight", tr = "Blood Knight", ja = "Blood Knight", zh = "Blood Knight", ko = "Blood Knight" }
color = [0.8, 0.1, 0.15]
piece_profiles = [0, 1, 2, 3, 4, 5, 6, 7]
starter_weapons = [35]
bot_name = "Botblood"
bot_order = 31
swing = { beat = 2.0 }
icon = "Spell_Deathknight_BloodPresence"
spell_tone = 1
talent_art = "presentation/talents/blood_knight.png"

spells.toml, with the starting spell first:

[[spell]]
key = "yourname.example:blood_strike"
class = "yourname.example:blood_knight"
id = 45902
school = "physical"
shape = { strike = { targets = 1 } }
hit = 30
cooldown = 1.5
range = 5.0
name = { en = "Blood Strike", de = "Blood Strike", fr = "Blood Strike", es = "Blood Strike", pt = "Blood Strike", ru = "Blood Strike", it = "Blood Strike", pl = "Blood Strike", tr = "Blood Strike", ja = "Blood Strike", zh = "Blood Strike", ko = "Blood Strike" }
icon = "Spell_Deathknight_DeathStrike"

talents.toml, three trees and the talents (one here):

[[talent_tree]]
key = "yourname.example:blood_knight_blood"
class = "yourname.example:blood_knight"
index = 0
icon = "Spell_Deathknight_BloodPresence"
background = "DeathKnightBlood"
name = { en = "Blood", de = "Blood", fr = "Blood", es = "Blood", pt = "Blood", ru = "Blood", it = "Blood", pl = "Blood", tr = "Blood", ja = "Blood", zh = "Blood", ko = "Blood" }

[[talent_tree]]
key = "yourname.example:blood_knight_fury"
class = "yourname.example:blood_knight"
index = 1
icon = "Spell_Deathknight_BloodPresence"
background = "DeathKnightBlood"
name = { en = "Fury", de = "Fury", fr = "Fury", es = "Fury", pt = "Fury", ru = "Fury", it = "Fury", pl = "Fury", tr = "Fury", ja = "Fury", zh = "Fury", ko = "Fury" }

[[talent_tree]]
key = "yourname.example:blood_knight_ward"
class = "yourname.example:blood_knight"
index = 2
icon = "Spell_Deathknight_BloodPresence"
background = "DeathKnightBlood"
name = { en = "Ward", de = "Ward", fr = "Ward", es = "Ward", pt = "Ward", ru = "Ward", it = "Ward", pl = "Ward", tr = "Ward", ja = "Ward", zh = "Ward", ko = "Ward" }

[[talent]]
key = "yourname.example:thick_blood"
class = "yourname.example:blood_knight"
tree = 0
row = 0
col = 1
ranks = 5
effects = [{ stat = [12, 0.08] }]
icon = "Spell_Deathknight_BloodPresence"
name = { en = "Thick Blood", de = "Thick Blood", fr = "Thick Blood", es = "Thick Blood", pt = "Thick Blood", ru = "Thick Blood", it = "Thick Blood", pl = "Thick Blood", tr = "Thick Blood", ja = "Thick Blood", zh = "Thick Blood", ko = "Thick Blood" }
text = { en = "Increases your luck by {v}%.", de = "Increases your luck by {v}%.", fr = "Increases your luck by {v}%.", es = "Increases your luck by {v}%.", pt = "Increases your luck by {v}%.", ru = "Increases your luck by {v}%.", it = "Increases your luck by {v}%.", pl = "Increases your luck by {v}%.", tr = "Increases your luck by {v}%.", ja = "Increases your luck by {v}%.", zh = "Increases your luck by {v}%.", ko = "Increases your luck by {v}%." }
menu_v = 0.08

What to know:

  • A free id. A class id is a number from 1 to 31. The game's twelve classes hold 1 to 9 and 11 to 13; today 10 and 14 to 31 are free. Mods take them from 31 downward by convention, so a mod and a game update rarely meet. A taken id is refused: shares the id 8 with `mage`: an id holds one class; a mod changes an existing class with `[[override]] kind = "class"`, it cannot add a second one on its id.
  • A token of its own. The game names a class by its token, the upper-cased part of its key after the namespace: yourname.example:blood_knight is BLOOD_KNIGHT. A second class with the same token is refused (token MAGE is also mage's).
  • The whole key. Every spell, tree and talent of a new class names it by its whole key, class = "yourname.example:blood_knight". The folder name does not stand for a namespaced class.
  • Talents are optional. A class without a talents.toml plays with no talents, and the talent windows say so. A tree's background must be written, but the hero menu does not draw it: the painting behind the trees is talent_art.
  • Spell ids. A spell's id (a 3.3.5 spell id) gives it its look in the client and its name on the run's cards and damage meter. Give each spell an id that no other spell of the profile uses, or it shows that spell's name there. Search the packs for id = <number> before you take one.
  • Races. races lists the ChrRaces ids a hero of the class may be. The class uses the races' own models.
  • More fields (meters, gear words, weapons, balance shares): "A class" in the content reference.

The talent painting: talent_art (version 0.7.2)

talent_art names a PNG of your package under presentation/, here presentation/talents/blood_knight.png at the top of the profile. List it in your package's objects with the kind texture, and in your package's required_assets:

"required_assets": ["presentation/talents/blood_knight.png"],
  • The window draws it 1.52 times as wide as it is high, so give it that shape (for example 1520 by 1000 pixels). At most 4096 pixels a side.
  • The first and the last 30% of its width lie behind the outer trees, the middle 40% behind the middle tree: let your colour zones meet at 30% and 70%. A tree's part is drained of colour while the tree has no point.
  • Any other path or format is refused: `talent_art` names a locked PNG under `presentation/` (`presentation/talents/<name>.png`).
  • A profile with a PNG plays in the desktop game only.

One colour for all its spells: spell_tone (version 0.7.2)

spell_tone is a place of the class colour palette, 1 to 15 (0, the default, is none). Every spell a hero of your class casts is drawn in that hue: casts, missiles, chain beams, ground areas and ground bursts. When the player wears a class colour of their own, that replaces it. A worn school colour still wins for its school's spells.

PlaceColourHuePlaceColourHue
1Blood Red09Azure225
2Ember2510Arcane262
3Gold4811Void285
4Venom8512Rose320
5Fel11513Crimson345
6Emerald14514Pumpkin Hex28, two-tone
7Teal17515Witchfire100, two-tone
8Frost200

A hue outside the palette, or one hue for a single spell, is not possible. A place past 15 is refused: `spell_tone` = 16 is outside 0..=15.

Rebuild one of the twelve classes

An override of the class and of its starting spell keeps the class's id, key and look and gives it another style of play. The Frost Mage package does this with the mage:

[[override]]
kind = "class"
key = "mage"
health = 260
resources = [{ key = "chill", max = 3, name = { en = "Chill", de = "Chill", fr = "Chill", es = "Chill", pt = "Chill", ru = "Chill", it = "Chill", pl = "Chill", tr = "Chill", ja = "Chill", zh = "Chill", ko = "Chill" } }]

[[override]]
kind = "spell"
key = "fireball"
school = "frost"
shape = { nova = { radius = 8.0 } }
hit = 18
cooldown = 2.0
range = 8.0
rider = { root = { secs = 2.0 } }
builds = { resource = "chill", n = 1 }
name = { en = "Glacial Pulse", de = "Glacial Pulse", fr = "Glacial Pulse", es = "Glacial Pulse", pt = "Glacial Pulse", ru = "Glacial Pulse", it = "Glacial Pulse", pl = "Glacial Pulse", tr = "Glacial Pulse", ja = "Glacial Pulse", zh = "Glacial Pulse", ko = "Glacial Pulse" }
icon = "Spell_Frost_FrostNova"

Lock: class:mage and spell:fireball, both with the dependency base. A mod cannot change a shipped class's client art.

Pictures

A zone's icon can name a PNG of your package by its whole path, for example icon = "presentation/icons/glade.png": list the file as a texture object and in required_assets, as for talent_art. A bare name such as Achievement_Zone_ElwynnForest is an icon of the client. Checked with profile-check.

Pictures are PNG, at most 4096 pixels a side and 16 MiB a file. A profile with pictures plays in the desktop game only.

Sounds: the game can play 16-bit WAV files, but only through a game archive's sound table, which a mod cannot carry (see Rights and rules). A content-only mod brings no sounds today.

A boss script (version 0.7.2)

A boss kit entry can hand the choice of ability to a Lua script: ability = { script = { name = "slam", params = { reach = 4.0 } } }, with the script at packs/yourname.example/scripts/slam.lua (kind script). A mod with scripts shows a Scripts badge, asks twice before it is chosen, and is reviewed as source. Everything else, the hooks, the commands, the limits and the azs-script tool, is in the script guide. The kit's templates/snippets/script-boss/ is a worked example.

Languages

The game speaks twelve languages: en de fr es pt ru it pl tr ja zh ko (English, German, French, Spanish, Portuguese, Russian, Italian, Polish, Turkish, Japanese, Chinese, Korean). Every name, subtitle, text and yell of a content entry carries all twelve:

name = { en = "Frost Focus", de = "Frostfokus", fr = "...", es = "...", pt = "...", ru = "...", it = "...", pl = "...", tr = "...", ja = "...", zh = "...", ko = "..." }

A missing language stops the lock and the check, with the file, the entry and the language:

Error: 1 content problem(s):
  yourname.example/classes/mage/talents.toml: talent yourname.example:frost_focus: `name` has no `ko` string

A mode is the exception: its [i18n.<language>] tables are optional, and a missing one shows the English.

Translating sensibly:

  • Start in English, copy it into all twelve to pass the check while you build, and translate before you publish. A reviewer reads your texts in every language.
  • Use the game's own words. The game's packs hold every class, school and spell name in all twelve languages; take "Frost", "Fireball" or "Chill" from there so your texts match the game's.
  • Keep {v} and other markers as they are in every language: the game fills in the number.
  • Machine translation is better than English in a German menu, but say in your release notes that the texts are machine-translated and invite players to correct them.

Lock, pack, release

The lock

azs-release profile-lock <folder> after every edit. It hashes the locked files again, rewrites profile.json when a hash changed, names files the lock does not list, and runs the game's source check. It writes nothing else.

Size limits: up to 64 gameplay packages in one mod, 256 KiB per TOML file, 8 MiB and 1,024 files per package, 64 MiB and 8,192 files in all. The community list takes at most 5,000 files a zip.

The release zip

azs-release profile-pack <folder> --out example-v1.zip

It writes the zip a registry pins: profile.json, the LICENSE file if your folder has one, and exactly the files the lock names, the same bytes on every run. It prints the two numbers the registry pins it by:

example-v1.zip: 1274327 bytes, sha256 df2be363b75f04d8b7be595c822660ff2861efd53d21554c0100cb3b90b6a76e

(The numbers are those of this guide's test profile; yours differ.) The zip carries the game's packs your mod locks, unchanged, as every mod does.

Sharing with friends

Zip the mod folder (or send the release zip, unpacked) and hand it over. Your friends unpack it into UserData\mods\import\, press Import, Choose and restart. To play co-op together, everyone needs exactly the same version: one changed byte makes another lock.

Publishing in the community list

  1. A GitHub repository for your mod, with your own files and your licence.
  2. A release of it whose asset is your release zip. The release's tag is the version players see. Drafts and pre-releases are ignored. The asset's name must fit your entry's asset pattern (example-*.zip), and only one asset of a release may fit it.
  3. A pull request on Syiana/azs-mods with one new file, packages/<id>.toml. The kit's templates/registry-entry.toml is the same file with every field explained:
id = "example"
kind = "mod"
name = "Whispering Glade"
author = "yourname"
repo = "yourname/azs-mod-example"
description = "A new zone, the Whispering Glade, with its own boss, and a faster Fireball."
license = "MIT"
namespace = "yourname.example"
requires = []

[source]
type = "release"
asset = "example-*.zip"
FieldWhat it holds
idthe entry's id: lower-case letters, digits and -. The file is named after it. It never changes.
kindmod, or map for a Map Builder map package
namethe name in the Mods window, at most 80 characters
authoryour name as players should see it, at most 80 characters
repoowner/name of the GitHub repository whose releases hold the zip
descriptionone or two sentences, at most 400 characters
licenseyour licence, at most 40 characters, for example MIT or CC-BY-4.0
namespaceyour package's name, the id in your lock (author.name, never azs.)
requiresthe ids of other community packages yours builds on; empty when it builds only on the game
[source]type = "release", and asset: the zip's name, * standing for the version
statusoptional: active (the default), deprecated or blocked
reasonwhy a package is deprecated or blocked, at most 400 characters
blockedoptional: older versions to withdraw, [{ version = "v1", reason = "Breaks saves." }]
mirrorsoptional: up to four https:// folders that serve the same zip as <sha256>.zip

The entry and the release zip of this guide's example passed the registry's own entry and zip checks (tools/packages.py in the repository).

The review

There are two pull requests. A maintainer reads your entry's pull request (who you are, what the package is, its namespace and licence) and merges it. The registry's pin workflow then fetches your release, checks the zip against the launcher's rules and opens its own pull request, "Pin: packages serial N", that pins the zip by size and SHA-256. Merging that one is the review. A reviewer reads:

  • what your mod changes: the numbers, every override and every new entry;
  • your texts, in all twelve languages;
  • what the profile asks of the game (compatibility in profile.json);
  • for a mod with scripts, every .lua file, in full: a script runs on the player's computer.

The repository's CONTRIBUTING.md and docs/REVIEW.md say what a pull request needs and what a reviewer checks. After that merge, we sign the catalog, and a player's GET MORE tab shows the version at its next refresh (the first time the tab opens in a session). A review checks that a package is what it claims to be; it is no promise of fun or fairness, and your mod always plays as Modded.

Updates

A new release with a new tag becomes an update: it is pinned beside the older versions (up to 16 are kept) and offered to players, whose update keeps the older version on disk. The new version has a new gameplay hash, so it plays with a save of its own.

The pinned zip is fixed. If you replace the file of a release on GitHub, players' games refuse the new bytes. A change is always a new release.

Withdrawing a version

Open a pull request on your entry: status = "blocked" with a reason for the newest version, or blocked = [{ version = "v1", reason = "..." }] for an older one. A player's game turns a chosen mod of a blocked version off at its first start after it has read a catalog that names the block (opening GET MORE reads it), and keeps its saves; a game that never reads the catalog again does not learn of the block. A blocked newest version stays pinned, so status = "blocked" cannot carry a fix: to replace a version with a fix, list its tag under blocked, keep status = "active" and publish the fix as a new release. status = "deprecated" with a reason retires a package without blocking it.

Troubleshooting

The checker's messages below were produced by breaking copies of this guide's test profile one way each and running profile-check (the JSON's message) or profile-lock (its error lines).

MessageCauseFix
TOML source hash differs from the profile locka file changed after the last lockrun azs-release profile-lock
not locked: <path> and file(s) of the folder are not in profile.json's lock: remove them or list them therea file in the folder that the lock does not list (only profile-lock reports it)list it in your package's objects, or delete it
the lock must declare this overridean [[override]] without its line in the lockadd { "dependency": "base", "entity": "<kind>:<key>" } to your package's overrides
locked override has no matching pack overridethe lock declares an override your files never makeremove the declaration, or write the override
invalid or duplicate override PackageOverride { dependency: "base", ... }the override's dependency is not among your package's dependencies, or a declaration is written twiceadd the package to dependencies (and to requires in pack.toml), or delete the second declaration
overrides pack `wotlk`, which `yourname.example` does not requirean override of an entry of a pack your package does not require (here a Death Knight spell)add the pack to requires in pack.toml and to dependencies in the lock, and declare the override with that dependency
`name` has no `ko` stringa text lacks a languagewrite all twelve
entity key must use its package namespace `yourname.example:` a new entry's key without your namespacewrite yourname.example:<key>
unknown field `cooldwn`, expected one of ...a misspelt fielduse one of the fields listed in the message. A broken override can also make the entry unknown, so other entries that name it fail too: fix the first message first
TOML parse error at line <n>, column <m>a TOML syntax error, for example an unclosed quote (the line and column of the mistake follow)fix the line the message names
invalid profile name "Ayla Frostfire"the lock's "name" holds spaces or capitalslower-case letters, digits, ., _ and - only (ayla-frostfire)
missing field `background` a field that must be writtenadd it
a zone needs normal enemies and elitesa zone without [[zone.enemy]] or without [[zone.elite]]add both
a zone needs exactly one final bossno boss, or more than one, with final = truemark one boss final = true
`boss 970010 kit` names the unknown boss `yourname.example:greymain`a boss's kit names no boss kitmatch the kit file's key
0 zone bosses fight with this kit, where one shoulda boss kit no boss usesname it in a boss's kit, or remove it
kit 1: summon entry 970099 is not a zone enemya summon names a creature the zones lackuse an entry of a [[zone.enemy]]
sits in tree 0 of `yourname.example:blood_knight`, which no `talent_tree` definesa talent's tree is missing (or failed to load: read the messages above it)write the class's three [[talent_tree]]s
shares the id 8 with `mage`: an id holds one class; ...a new class on a taken idtake a free id, from 31 downward
token MAGE is also mage'sa new class whose key ends like another class'sgive it another name after the namespace
`spell_tone` = 16 is outside 0..=15a palette place past 151 to 15, or 0 for none
`talent_art` names a locked PNG under `presentation/` (`presentation/talents/<name>.png`)not a .png, not under presentation/, or not lockedlock a PNG under presentation/
does nothing: no `effects`, `mods` or `plays` a talent that neither has effects nor mods nor playsgive it at least one

Problems in the game

What you seeCauseFix
Nothing to import: put a mod profile folder into UserData/mods/import.the import folder holds no folderput the folder that holds profile.json directly into import
<folder>: not imported: <reason>the game's own check refused the mod, or the folder holds your mod folder one level too deepread the reason; run profile-lock and the check, fix, import again
<folder>: already importedthe same version is kept alreadylock your change, then import again
The change does not showthe game plays what it imported at the last startimport again, Choose, restart
The selected mod profile is unavailable and was turned offthe chosen mod's kept files are gone or changedimport it again and choose it
Not in this game mode on Enterthe chosen mode does not load your hero's classpick another mode, or name your package in that mode's packs
A question mark as a class iconthe class's icon is not among the client's filespick an icon name the client has
Your mod's heroes are gonea new version of your mod has a new saveimport the older version to see its heroes again
This lobby uses different content.the lobby runs another mod or another versioneveryone plays exactly the same version
Remove is greyed out on one modit is the mod the game is playing nowPlay official content, restart, then remove it
Remove? or Choose? turns backthe second press must come within 4 secondspress twice, quickly

Questions modders ask

Can I change a boss's health? Yes. A boss stands in its zone's file, so it is an override of the zone (kind = "zone", lock zone:<key>). A field replaces the old one whole, so you write the zone's whole boss list again, with your change: copy it from the zone's file. To make every enemy of a zone tougher, override only its health_factor, which passes the check (health_factor = 1.64 on elwynn).

Can I add a pet? A spell can summon pets of a kind the game already has: shape = { summon = { pet = "wolf", count = 2, secs = 20.0 } }. The kinds are the game's own (wolf, raptor, imp, felhunter, voidwalker, succubus, felguard, infernal, doomguard, dreadlord, ghoul, mirror image, spirit wolf, gargoyle, water elemental, treant, spirit, xuen and a few more). A new kind of pet, with a behaviour of its own, needs a game update. This summon was not run through the checker for this guide.

Why does my talent not show? Check, in this order: the file is classes/<class key>/talents.toml of your package; tree is 0 to 2 and row 0 to 6; a req names a talent of a row above in the same tree; you ran profile-lock, imported again, chose the mod and restarted. A talent of a new class names the class by its whole key.

Why is my class missing in a mode? A mode plays only the packs it loads. A package that no mode names joins every mode whose packs include all the packages it requires. If a mode of your profile names your package, it joins no other mode. The hero menu says Not in this game mode.

How do I share a mod with friends? As a folder or a zip they unpack into UserData\mods\import\. See Sharing with friends.

Can I start without the starter mod? There is no command that makes a mod folder. Start from the kit's starter mod, or from the folder of a released mod such as Frost Mage, and edit profile.json by hand.

Can I sell a mod? The game takes no money for mods and the community list has no prices: every listed package installs free. Your licence is your choice. This guide is not legal advice; mind the rules below.

Does my mod work in the browser? No. The browser plays no mods.

Do I need to know Lua? Only for boss scripts. Everything else is TOML.

Glossary

WordMeaning
Profilea mod folder: profile.json and every file it locks
Lockprofile.json: packages, versions, dependencies, overrides and every file's BLAKE3 hash
Packageone folder under packs/ with its pack.toml
Namespaceyour package's name, author.name; the start of every key you add
Entryone thing the game plays, with a kind and a key
Override[[override]]: a change to an entry that exists, declared in the lock
Objectone locked file, with its path, kind and hash
Gameplay hashthe fingerprint of what a mod plays; its save is named after it
Moddedhow every mod plays: own heroes and progress, no cloud saves, no ranks
Boss kitthe abilities a boss uses and how often
Registrythe azs-mods repository: one entry per community package
Catalogthe signed list of reviewed packages that the Mods window shows
Pinthe size and SHA-256 by which the registry holds one release zip
Kitthe templates/ folder of the azs-mods repository

Rights and rules

Azeroth Survivors Reborn is a fan project. It is not affiliated with or endorsed by Blizzard Entertainment. "World of Warcraft", "Warcraft" and "Azeroth" are trademarks of Blizzard Entertainment.

  • No Blizzard files in a package. A package must not contain Blizzard's game files or anything extracted from them: no archives, models, textures, sounds or DBC tables. Only text and files you made yourself or may share.
  • Naming is fine. A package may name files of the player's own client by id or by path: a spell id, a display id, an icon name. The player's game reads them from the player's own install.
  • Packages that break these rules are refused in review, or blocked later.
  • License your work. Put a LICENSE file into your mod folder; profile-pack carries it into the zip. Say which files it covers: your own package folder, not the game's packs, which are copies of the game's content and not yours to license.
  • Rights holders reach us through azreborn.com/contact.

The registry's docs/LEGAL.md and CONTRIBUTING.md hold the same rules for pull requests. None of this is legal advice.