Making mods
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-modsrepository, foldertemplates/: 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 arebase,tbcandwotlk. Yours is namedauthor.name. - Namespace: your package's name,
author.name, in lower-case letters, digits,_and-, for exampleyourname.example. Names that start withazs.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
kindand akey. - 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'skind, itskeyand 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.
- Copy the starter. Copy
templates/starter-mod/out of the kit to a working folder, for exampleC:\mods\starter-mod\. - 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":trueand an empty"diagnostics":[]mean the folder passes. It also prints the mod'sgameplay_hash. - Make the change. Open
starter-mod\packs\yourname.example\overrides.toml. It already overrides Fireball, andprofile.jsonalready declares that override. Change the cooldown:[[override]] kind = "spell" key = "fireball" hit = 60 cooldown = 1.0 - 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} - Lock it again.
azs-release profile-lock starter-mod
It hashes every locked file again, rewritesprofile.jsonwhere 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.) - Import it. Copy the
starter-modfolder intoUserData\mods\import\in your game's install folder. Start the game, open MENU, Mods, and press Import. The window saysstarter-mod: imported as <a short code>. - 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.
- 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:
- Rename the folder
packs/yourname.example/topacks/<you>.<mod>/, for examplepacks/ayla.frostfire/. - In its
pack.toml, setkey = "ayla.frostfire". - 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 withinvalid 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:
- Edit a file of your package.
- Lock:
azs-release profile-lock <folder>. It printsrehashed <file>for each changed file and ends withthe game's preflight passes, or it lists the problems and stops. - 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. - 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 saysalready imported. The game does not watch the folder: import after every change. - 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. treeis 0, 1 or 2: the class's three trees. There is no fourth.rowis 0 to 6. The game's talents keep their places; yours stands after the talents of its row.colis 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);modswithmods_vis what it does in a run (here: more damage for frost spells, school 16).- A text that starts with
Milestone.orCapstone.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,radiusandmap_boundsplace the arena on the WoW maps. This example stands where Elwynn Forest's arena stands, with Elwynn's numbers.map_boundsmust 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 saysa zone needs normal enemies and elitesora zone needs exactly one final boss. entryis the creature's number, unique in its zone (a number no other zone uses avoids confusion).displayis aCreatureDisplayInfoid of the 3.3.5 client: any creature model it has.iconis a file name of the client'sInterface\Icons\(no folder, no extension), shown in the Codex.costis what the creature costs the wave director,fromthe minute it starts to come; a boss comes at itsminute.health_factorscales every enemy's health in the zone;houris the time of day,weatherthe 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 } }
everyis the seconds between two uses;warnthe seconds a hero sees the warning;factorthe hit, times the boss's own.spellis a 3.3.5 spell id: the look of the ability in the client, never its numbers.summoncalls the zone enemy with thatentry, which must exist in the zone (kit 1: summon entry 970099 is not a zone enemyotherwise).- Other words:
nova,ring,rain,charge,leap,adds,meteor,wave,stomp,comboand 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 withname,tag,text,rulesandrewards, as the game's ownmodes/swarm.tomlshows. A language you leave out shows the English. - A mode that names its
packsplays 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_knightisBLOOD_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.tomlplays with no talents, and the talent windows say so. A tree'sbackgroundmust be written, but the hero menu does not draw it: the painting behind the trees istalent_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 forid = <number>before you take one. - Races.
raceslists theChrRacesids 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.
| Place | Colour | Hue | Place | Colour | Hue | |
|---|---|---|---|---|---|---|
| 1 | Blood Red | 0 | 9 | Azure | 225 | |
| 2 | Ember | 25 | 10 | Arcane | 262 | |
| 3 | Gold | 48 | 11 | Void | 285 | |
| 4 | Venom | 85 | 12 | Rose | 320 | |
| 5 | Fel | 115 | 13 | Crimson | 345 | |
| 6 | Emerald | 145 | 14 | Pumpkin Hex | 28, two-tone | |
| 7 | Teal | 175 | 15 | Witchfire | 100, two-tone | |
| 8 | Frost | 200 |
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
- A GitHub repository for your mod, with your own files and your licence.
- 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
assetpattern (example-*.zip), and only one asset of a release may fit it. - A pull request on
Syiana/azs-modswith one new file,packages/<id>.toml. The kit'stemplates/registry-entry.tomlis 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"
| Field | What it holds |
|---|---|
id | the entry's id: lower-case letters, digits and -. The file is named after it. It never changes. |
kind | mod, or map for a Map Builder map package |
name | the name in the Mods window, at most 80 characters |
author | your name as players should see it, at most 80 characters |
repo | owner/name of the GitHub repository whose releases hold the zip |
description | one or two sentences, at most 400 characters |
license | your licence, at most 40 characters, for example MIT or CC-BY-4.0 |
namespace | your package's name, the id in your lock (author.name, never azs.) |
requires | the 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 |
status | optional: active (the default), deprecated or blocked |
reason | why a package is deprecated or blocked, at most 400 characters |
blocked | optional: older versions to withdraw, [{ version = "v1", reason = "Breaks saves." }] |
mirrors | optional: 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 (
compatibilityinprofile.json); - for a mod with scripts, every
.luafile, 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).
| Message | Cause | Fix |
|---|---|---|
TOML source hash differs from the profile lock | a file changed after the last lock | run 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 there | a 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 override | an [[override]] without its line in the lock | add { "dependency": "base", "entity": "<kind>:<key>" } to your package's overrides |
locked override has no matching pack override | the lock declares an override your files never make | remove 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 twice | add the package to dependencies (and to requires in pack.toml), or delete the second declaration |
overrides pack `wotlk`, which `yourname.example` does not require | an 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` string | a text lacks a language | write all twelve |
entity key must use its package namespace `yourname.example:` | a new entry's key without your namespace | write yourname.example:<key> |
unknown field `cooldwn`, expected one of ... | a misspelt field | use 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 capitals | lower-case letters, digits, ., _ and - only (ayla-frostfire) |
missing field `background` | a field that must be written | add it |
a zone needs normal enemies and elites | a zone without [[zone.enemy]] or without [[zone.elite]] | add both |
a zone needs exactly one final boss | no boss, or more than one, with final = true | mark one boss final = true |
`boss 970010 kit` names the unknown boss `yourname.example:greymain` | a boss's kit names no boss kit | match the kit file's key |
0 zone bosses fight with this kit, where one should | a boss kit no boss uses | name it in a boss's kit, or remove it |
kit 1: summon entry 970099 is not a zone enemy | a summon names a creature the zones lack | use an entry of a [[zone.enemy]] |
sits in tree 0 of `yourname.example:blood_knight`, which no `talent_tree` defines | a 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 id | take a free id, from 31 downward |
token MAGE is also mage's | a new class whose key ends like another class's | give it another name after the namespace |
`spell_tone` = 16 is outside 0..=15 | a palette place past 15 | 1 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 locked | lock a PNG under presentation/ |
does nothing: no `effects`, `mods` or `plays` | a talent that neither has effects nor mods nor plays | give it at least one |
Problems in the game
| What you see | Cause | Fix |
|---|---|---|
Nothing to import: put a mod profile folder into UserData/mods/import. | the import folder holds no folder | put 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 deep | read the reason; run profile-lock and the check, fix, import again |
<folder>: already imported | the same version is kept already | lock your change, then import again |
| The change does not show | the game plays what it imported at the last start | import again, Choose, restart |
The selected mod profile is unavailable and was turned off | the chosen mod's kept files are gone or changed | import it again and choose it |
| Not in this game mode on Enter | the chosen mode does not load your hero's class | pick another mode, or name your package in that mode's packs |
| A question mark as a class icon | the class's icon is not among the client's files | pick an icon name the client has |
| Your mod's heroes are gone | a new version of your mod has a new save | import the older version to see its heroes again |
This lobby uses different content. | the lobby runs another mod or another version | everyone plays exactly the same version |
| Remove is greyed out on one mod | it is the mod the game is playing now | Play official content, restart, then remove it |
| Remove? or Choose? turns back | the second press must come within 4 seconds | press 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
| Word | Meaning |
|---|---|
| Profile | a mod folder: profile.json and every file it locks |
| Lock | profile.json: packages, versions, dependencies, overrides and every file's BLAKE3 hash |
| Package | one folder under packs/ with its pack.toml |
| Namespace | your package's name, author.name; the start of every key you add |
| Entry | one thing the game plays, with a kind and a key |
| Override | [[override]]: a change to an entry that exists, declared in the lock |
| Object | one locked file, with its path, kind and hash |
| Gameplay hash | the fingerprint of what a mod plays; its save is named after it |
| Modded | how every mod plays: own heroes and progress, no cloud saves, no ranks |
| Boss kit | the abilities a boss uses and how often |
| Registry | the azs-mods repository: one entry per community package |
| Catalog | the signed list of reviewed packages that the Mods window shows |
| Pin | the size and SHA-256 by which the registry holds one release zip |
| Kit | the 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
displayid, 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
LICENSEfile into your mod folder;profile-packcarries 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.
