Skip to content

Content reference

Markdown
The field-by-field reference for the content packs: spells, talents, classes, zones, modes, bosses, sets and cosmetics, and how mods and community packages are built from them.

Short guides for the usual additions. The design is in docs/ARCHITECTURE.md. Paths are from engine/benilla/ unless they start at the repository root; packs/ is crates/survivors-content/packs/.

Every addition

  1. Write the entity into the right pack (base for classic, tbc, wotlk). A string is { en = "...", de = "..." }; both languages, always.
  2. Keep the numbers you guessed marked TUNE in a comment, and say where a number comes from (AS's table and re/NUMBERS.md section, or "ours").
  3. Regenerate the client and web copies and check the packs: cargo run -p survivors-content --bin azs-content -- gen, then -- check.
  4. Run cargo test -p survivors-content -p survivors-sim and the golden runs (cargo test --release -p survivors-sim golden).
  5. Order matters. Lists the run draws from (spell pools, jewels, cards, enemies) are drawn in file order, and some catalogs use their place as the wire id. Appending to a drawn list moves the golden runs: regenerate them in a separate commit Golden: <why> and say so in the report. A catalog whose place is its wire id or display takes new entries at the end only.
  6. A new behaviour (something the run does that no existing key does) is code: see "A behaviour" at the end.
  7. Stay modular. The run's code never names a content key or carries a content number (a talent key in a match, a display id in a constant). What an entry does is written in its TOML; what no field says yet becomes one generic field, documented here, that any entry may use. The rules in full: CLAUDE.md at the repository root.

The public data files (site/public/data/v1/*.json, documented at /guides/data-api on the site) publish only the fields the FILES table of crates/survivors-content/src/gen/data.rs names. A new field on a def stays unpublished until that table and its emitter name it; azs-content gen writes the files with the other copies, and index.json lists each file's fields.

The expansion field in pack.toml accepts classic, tbc, wotlk and cata. The standard campaign includes all four packs. staff_only = true on any pack restricts its zones to verified admins and moderators; it defaults to false. Progression still applies, and the development all-zones switch does not bypass this policy. Cooperative hosts verify each guest's role before seating or reconnecting them. Ordinary players retain the locked preview.

archives = ["archive-name"] lists required Data/packs/<archive-name>.MPQ files in mount order. Names use lowercase ASCII letters, digits, underscores and hyphens only. The client, standalone server and browser exporter mount the campaign's archives automatically. Install the staged map and navigation archives in data/3.3.5a/Data/packs (its lighting rows are in the map archive); verify the map hash against the stage's manifest.json, and the navigation hash and map binding against navigation.json. python tools/campaign-packs.py --data data/3.3.5a/Data checks that every required archive exists. The release script seals and includes these files; they are required campaign data, not optional Video downloads.

A campaign archive must not carry a copy of a table (Map, AreaTable, WorldMapArea, LoadingScreens, Light*, Spell*, SoundEntries, Creature*): a DBC is read whole from the highest archive, so the copy hides every row a patch adds after it was made. The pack builders (tools/cataclysm-pilot.py ROWS_ONLY) write only the pack's own rows, as AZS/CataRows/<Table>.dbc, into cata-pilot, the one archive of Cata's own files. The pack's last archive, cata-tables, holds each of those tables as the chain has it plus those rows: python tools/campaign-tables.py --data <Data> writes it (--check verifies it; tools/ship.ps1 rewrites it before the release data is packed), so the chain stays the one version of every base row, and a row added to the pack later lands in the same file. It is a separate small archive because a sealed archive is re-keyed by any change and downloads whole. A pack built before the builders did this still carries copies (and a cata-visibility archive); --split cata-pilot --out <file> repacks it without them, with the lighting rows folded in. A new table a builder writes goes into ROWS_ONLY and the tool's TABLES with its string columns. tools/cataclysm/lights.toml names Cata light volumes that wear another volume's weather slots (found by map and world position, because the campaign renumbers every id); the tool applies it to the Light table, so a zone's light changes by rewriting cata-tables alone, without rebuilding cata-pilot.

The minimap draws one 256x256 BLP per ADT tile, found through a row of textures\Minimap\md5translate.trs (<MapDirectory>\map<X>_<Y>.blp); a tile with no row draws nothing. cata-pilot carries neither, so the small archive cata-minimap holds the art of every ADT tile cata-pilot carries (copied from the Cataclysm source patch, data/custom-patches/cata-mop/patch-5.MPQ) and the table as the chain has it plus one row per tile, under the pack's own directory names (TolBarad, AzsCataAzeroth). python tools/campaign-minimap.py --data <Data> writes it; --check (run by tools/ship.ps1) fails once the chain's table no longer is the one it was built from or a row's tile is missing. A new zone, or a wider tile window in a rebuilt cata-pilot, needs the tool run again. The source has no art for Dragon Soul's map, so that minimap stays empty.

Cataclysm content lives in survivors-content/packs/cata; its pack owns the staff restriction. The local practice preset uses the same access policy and all four packs. Use tools/cataclysm-campaign.py to build its local pack and generated catalog. The staging and validation workflow is in docs/superpowers/plans/2026-11-11-cataclysm-integration.md.

A spell

packs/<pack>/classes/<class>/spells.toml, one [[spell]]:

[[spell]]
key = "fireball"          # stable: saves, replays and checkpoints name it
id = 133                  # 3.3.5a's spell id: the client shows its icon, name and visual
school = "fire"
shape = { strike = { targets = 1 } }   # the Shape vocabulary (survivors-content spells.rs)
hit = 51
cooldown = 1.3
range = 30.0
rider = { slow = { pct = 50, secs = 3.0 } }   # optional
name = { en = "Fireball", de = "Feuerball" }
icon = "Spell_Fire_FlameBolt"
# faction = "horde"       # optional: only heroes of a race with this `side` are dealt it
# legendary = false       # optional: no legendary amulet for it (default true)
  • The first spell of the file is the one every run of the class starts with (the class's starter names it).
  • range is how far from the hero an enemy's edge may stand for a strike, dot, execute or missile cast to go off. A nova casts by its radius and a cone by its length, never by range. The melee classes' blows (a strike, dot or execute of a warrior, rogue, paladin, druid, shaman, death knight, demon hunter or monk that hits at arm's length) all write range = 10.0, so a hero running from a pack still lands them; a farther range makes a strike a bolt for its legendary (MELEE_REACH, below).
  • A class's own meters: builds = { resource = "chi", n = 1 } gathers what a cast makes; spends = { resource = "chi", n = 2, more = 0.5 } spends that much when it is gathered and the cast is more stronger (its hit, heal, shield or buff). Nothing waits for a meter: like every class's, each spell casts on its cooldown (free casts of talents and echoes spend nothing). The meters are the class's [[resources]] (class.toml, below).
  • needs = "<talent key>": a level-up hand deals the spell only to a build that took that talent of its class (a stance's own spells); a talent's start_with still starts the run with it.
  • shape = { sphere = { share = 10, count = 3, secs = 20.0, display = 97951 } }: healing spheres dropped around the hero once someone is below 85 % health; walking over one heals share % of the walker's max health; display is a GameObjectDisplayInfo id; the optional scale (default 1, 0.1 to 10) draws the sphere bigger or smaller than its model.
  • shape = { orbit = { count = 3, radius = 5.0, reach = 2.2, period = 2.4, every = 0.7, secs = 10.0, display = 97953 } }: orbs circling the hero radius yd out, a turn every period seconds, each striking every enemy within reach of it, one enemy at most once every every seconds; display is the orb's CreatureDisplayInfo (the monk's Chi Orbit).
  • shape = { empower = { more = 20, haste = 30, secs = 11.0 } }: a timed buff on the hero's pets (any minion at their side): each blow deals more % more and the beat between blows is haste % shorter, for secs seconds. It casts as soon as a pet stands at the hero's side, enemies near or not (else its cooldown stays); a stronger buff still running holds, a weaker cast only extends it. Its strength grows with the buff and duration lines like a fury. pet = { one, many } names the pets in the text; needs keeps its card from builds without them (Demonic Empowerment needs the Imp's demonic_familiar). Test demonic_empowerment_makes_the_demons_hit_harder_and_faster.
  • shape = { bond = { haste_cap = 20 } }: a spell that is never cast (hit and cooldown stay 0) and grows the hero's pets, which have no cards of their own, with its own cards: the damage lines make each blow hit harder, the cooldown lines shorten the beat between blows (by haste_cap % at the most in all; the card stops offering the line once it is reached), the targets lines make each blow strike that many more enemies, each for the whole blow. pet = { one, many } names the pets in the text; needs keeps its card from builds without them (Demonic Knowledge needs the Imp's demonic_familiar); legendary = false. Tests demonic_knowledge_grows_the_demons and a_bond_offers_no_more_cooldown_once_capped.
  • aura = <seconds>: the hero wears the spell as an aura that long after each cast, so the client plays its visual's state kit on the hero (the monk's Spinning Crane Kick spin). While the cards or the Game Menu hold the run, the aura waits with the hero's other timers.
  • stands = <CreatureDisplayInfo> on a totem spell: the totem stands as that model (the monk's Black Ox Statue), named after the spell. A stock totem (Searing, Magma) without it stands in the hero's race's fire totem model; with it, it keeps its creature and takes that model (Magma Totem: FireLightTotem). Test a_stock_totem_can_stand_as_a_model_of_its_own.
  • Totems never stand in one another: a new totem goes down beside the hero on the first of 8 bearings (east first) that has no standing totem within 2 yd, then on the 2nd and 3rd ring out. Test totems_stand_apart.
  • no_crit = true on a spell: it never crits. Its damage-over-time ticks roll no crit however much crit chance the hero has (Run::tick_dots, the spread of a hit stays); it is read for a dot spell (Pestilence: a plague counts as damage over time). Test pestilence_ticks_never_crit_and_another_plague_still_does.
  • no_echo = true on a spell: no echo (a ring's "chance for a spell to cast twice", Run::echo) casts it a second time. Pestilence has both. Test an_echo_never_casts_pestilence_again. A damage over time that a dying enemy passes on (Wandering Plague's jump) follows a set's stacks too (PetHarvest stacks, the strongest kept), test a_jumping_pestilence_follows_the_sets_three_stacks; a dot that spreads (DotSpread) only lands on enemies without it.
  • requires_enemy = false on a totem spell lets it cast before enemies come into range. Totems otherwise wait until an enemy is nearby.
  • follows = true on a totem spell: its field rides with the hero (the warrior's Bladestorm). Nothing is set down, each beat strikes round the hero where they stand, and the hero wears the spell as an aura as long as the field lasts (its duration lines and the card stops counted), so the client plays its visual's state kit on them: Bladestorm's look keeps the stock state kit 9857, the Whirlwind animation and the whirl. With pulse_visual each beat is also a cast of that look from the hero. Not with stands or aura; the text says it surrounds the hero. Test a_following_totem_rides_with_the_hero_and_is_worn_while_it_lasts.
  • visual = <spell id>: the hero's casts of the spell are SMSG_SPELL_GO of that 3.3.5a spell instead (a worn spell skin still wins); the damage log, cooldowns and meters keep the spell's own id. For a channel (a spell whose Spell.dbc row has aura 23, periodic trigger): its own SpellVisual holds only the channel kit, so a cast of it draws nothing, and the missiles live in the spell it triggers (Arcane Missiles 5143 shows as rank 13's 42845). Icy Touch uses it for a burst sized to the target. every_cast_spell_has_a_look only asks for a SpellVisual, so a kit-only one passes it: read the row (SpellVisual.dbc HasMissile, the cast and impact kits). Test tags_visuals_and_looks_come_from_the_packs.
  • vfx = { source = <spell id>, cast = { model = "Spells/Example.m2", slot = "rhand", scale = 0.5 }, impact = { model = "Spells/Other.m2", slot = "chest", scale = 0.6 } }: builds a new composition for this spell's visual. source supplies the existing visual chain and the missile's travel speed (omit it or use 0 for this spell; a spell whose own row has speed 0 names the spell that flies the missile, as Death Coil names its damage spell 47632); cast, impact, state and area are optional accents. Each replaces one kit slot and scales a private copy of the effect model's row. Other slots, animations, beam procedures, missiles, state and area kits, and model attachments remain intact, but the slot an accent names is replaced: whatever the source kit holds there is gone. An impact kit's one effect usually sits in chest, so an accent in chest swaps the spell's own look for its model (Blood Boil lost its boiling blood that way); name a slot the source leaves empty. A cast accent that is a *_Precast_* hand model (Shadow_Precast_Low_Hand, Ice_Precast_Low_Hand) plays its whole swirl on every cast, and on a spell that casts every second it reads as coloured threads around the hero; the Death Knight's 2026-11-12 recipes did that and were removed. A spell with no vfx shows the look the client has for it, its own row's or the stock spell its visual = <spell id> names (the Death Knight's whole class does); a composed id (910001-910999) needs its recipe. Slots are head, chest, base, lhand, rhand, breath, world; scale is 0.1 through 2.0. Models must already exist in the preceding patch chain. A ranged spell whose source has no cast kit must leave cast unset: the empty kit lets the equipped weapon supply its firing animation. Use an impact accent instead; the compiler rejects a cast accent that would block this fallback. Reserve a unique visual spell ID in 910001–910999; original spell rows and combat identities stay unchanged. The compiler reserves 100000–119999 in the four visual tables. tools/class-spell-vfx.py reads these recipes during the final adminemotes patch step (Python 3.11+, override interpreter with AZS_PYTHON). Rebuild class patches before that final step; a missing source or colliding generated ID is an error, never an invisible fallback. visual applies to hero casts, owned ground areas and temporary cast auras; an equipped spell skin wins. Passive and bond spells do not get recipes because they never cast. Regression coverage: visual_recipes_are_generic_and_reject_unknown_slots, content_looks_apply_to_every_class_and_equipped_skins_win, tools/test_class_spell_vfx.py.
  • visual_every = 0.12 on a missiles spell spaces its visible launches so repeated hits on one target do not overlap. Zero keeps a simultaneous volley. The range is 0 through 1 second. Damage, target rolls and cooldowns remain immediate; the extra packets are visual only and aim at the target's last position if it has disappeared. Like animation steps, pending visual launches are transient and are not kept in handover checkpoints. Test spaced_missile_looks_do_not_delay_or_repeat_damage.
  • pulse_visual = <spell id> on a totem spell: every beat of the totem is also a cast of that 3.3.5a spell from the totem itself (SMSG_SPELL_GO, the look only; the damage is the spell's own): the Searing Totem's fireball (3606) flies from the totem to the enemy it shoots, the Magma Totem's ring of fire (19823, "Fire Nova Visual", a base effect: the stock pulse 8187 draws hand effects, which a totem lacks) bursts round it. Read the spell's cast kit before naming one. Without it the beat is silent (the monk's statue). Tests a_totems_beat_is_cast_from_the_totem, a_spell_names_only_its_class_s_meters_and_talents.
  • look_aura = <spell id> inside shape.summon gives the summoned units a visual aura for their lifetime. Use an aura with the desired state visual. Test storm_earth_and_fire_spirits_wear_the_hero_and_the_ghost_aura.
  • lays = { display = 3074 } on a ground spell: each cast also leaves that object (a GameObjectDisplayInfo id, shown only: never selected, walked over or hit) standing where the area lands, for as long as the area lasts; on any other spell, lays = { display = 3072, secs = 1.5 } stands it under the hero for secs. scale (default 1) draws it bigger or smaller. The hunter's traps use it: the client draws a trap from the object a stock server's trap spell summons (G_*Trap), not from the spell's own visual, which only throws it. Not for totems, which drop their own. Tests a_ground_trap_stands_as_long_as_its_area_and_goes_with_it, a_trap_without_an_area_stands_a_moment_under_the_hero, what_a_spell_lays_is_checked.
  • look_widen_max = 1.5 on a ground spell: the most its area's model is drawn wider than the model itself (1 to 4: the client draws no more than 4x). The cards and talents widen a ground area, and the server tells the client how much so the model covers what it hits; for a model that is mostly a dark or loud ground texture (Hurricane's black glow under its storm cloud) that covers the arena floor. Only the look is held: the radius that hits, and the shards or rain that fall over it, keep the full area. 0 (the default): the look follows the area. Tests a_ground_look_can_be_held_to_a_widening, a_ground_look_is_held_to_the_packs_widening.
  • turns_into = 856 on a proc = { kind = "sheep", ... } spell (Polymorph): the CreatureDisplayInfo an enemy it turns shows until the next hit pops it or its hold ends. A sheep proc needs it, no other spell takes it. Name every body a spell shows apart from the hero this way (stands, turns_into, an orbit's display): spells::displays hands them to the release export, which packs models only for the displays it can read, so a body the code hardcodes is missing from a release and draws as nothing (the sheep were invisible). Tests a_sheep_proc_names_what_it_turns_enemies_into, what_a_spell_shows_apart_from_the_hero_is_a_release_root, sheep_hold_still_and_pop_on_the_next_hit.
  • form = { id = 22, display = 25277, races = [[10, 1234]] } on a self buff with a duration (fury, haste, thorns, immune): the hero shows that shapeshift form (written as a talent's form) while the buff lasts, then their talents' form or none again (the demon hunter's Metamorphosis). A free cast of it shifts the hero too. A hero in any form (a talent's or a spell's) is drawn on no mount, the steed's or the hub's: a form's model is a creature rig with no Mount pose, and the client would stand it on the saddle. The ride and its speed go on, and the mount is back in the update that ends the form. Test a_hero_in_a_form_rides_nothing_and_the_steed_comes_back_with_the_body.
  • steps = { looks = [904026, 904027], every = 0.35 }: after each cast the hero plays these looks in turn, one every every seconds (each a 3.3.5a spell id, a patch's own, whose visual plays as a cast of it: its pose and effects; they deal nothing): the demon hunter's Blade Dance spins from several sides. At most 8.
  • The spell book's text is built from the fields (survivors-sim/src/spell_text.rs); check it in both languages.
  • Its look: the class colours and spell skins (spellcolors.rs, spellskins.rs); with WOW_DATA set, cargo test -p survivors-sim every_cast_spell_has_a_look.

A talent

packs/<pack>/classes/<class>/talents.toml, one [[talent]] in its tree:

[[talent]]
key = "arcane_focus"
tree = 0                  # the class's [[talent_tree]] index
row = 0
col = 1
ranks = 5
effects = []              # what AS's table gives (rewritten by re/tools/talents.js)
icon = "Spell_Holy_Devotion"
name = { en = "Arcane Focus", de = "Arkaner Fokus" }
text = { en = "Arcane spells deal {v}% more damage.", de = "..." }
menu_v = 0.05
mods = [{ school = 64 }]  # the Mod vocabulary; mods_v is {v} per rank
mods_v = 0.05
# plays = [...] / behaviors = [...] for talents that act on hooks (TALENT keys)
# form = { id = 1, display = 892, races = [[6, 8571]] }  # a shapeshift: form id (UNIT_BYTES_2
#   byte 3) and the model every client sees, per race id where it differs
  • A class has three trees of seven rows, and a talent has no x or y: its col only orders the talents of a row. The hero menu stands a row's talents by how many the row has (web.slot in SurvivorsArmory.lua): one in the middle, two a half step either side on even rows and a whole step on odd rows, three or four a step apart. So a row never leans to one side, whatever its columns, and which talent takes which place follows from the talents they require. It draws a talent as a milestone or a capstone by its English text, which then starts with Milestone. or Capstone.; the run's own capstone is a one-rank talent of row 6.
  • What lies behind the three trees is not background: a tree's background names the stock talent window's art (Interface\TalentFrame\<background>-TopLeft and its three siblings, read through TalentTab.dbc, which a class from content alone has no rows in), and the hero menu does not read it. The hero menu draws one wide painting of the class, talent_art ("A class"), else the game's own Interface\AzerothSurvivors\Talents\<token in lower case> (a texture of a client archive, patch-1.MPQ, made by tools/talent-paintings-patch.py); a class with neither shows the dark ground alone.
  • New talent builds use v1.<hub bits>.<ranked keys>, for example v1.100.2example.mod:talent,1another_talent. Keep a talent's key and its tree's index stable. Talents can move in the display without shifting old ranks. Rank changes still obey current caps, requirements and exclusivity. Removed keys contribute no ranks.
  • Old positional builds and links remain readable. The official order is frozen in engine/benilla/web/talent-layout-v0.json. Legacy mod-only classes and complete positional builds that match the active mod layout use that layout. Load an old positional mod build in its originating profile and re-export it by key before moving it. Bare digits carry no profile identifier. Use letters, numbers, underscores, hyphens, dots, or colons in portable keys. Older profiles with other key characters can still save positionally. Lua compatibility data comes from python tools/sync-talent-build.py.
  • SurvivorsTalents.lua is generated (azs-content gen); the hero menu's copy and the in-game copy must match.
  • The account talent tree is packs/base/account/tree.toml, the levels levels.toml. The dash (Shift) is the account talent with effect = "dash". The game spreads the total cost of all talent ranks evenly over the level-ups, rounding down the cumulative budget at each level. Max level always funds the whole tree.
  • Healing per kill: stat 15 heals a flat amount (Spirit Tap), stat 34 a share of the maximum health (stat = [34, 0.001]: 0.1% a rank).
  • A talent's behaviors name a behaviour key of survivors-content/src/behaviors.rs TALENT with the fields that key takes; the validator rejects a missing or an extra field. The fields: spell (a spell key), pet (narrows a demon behaviour to that pet kind), n, pct, reach (yd), share, more, secs, cap, per_armor, per_health, aura (a spell id). The warlock's demons are the example: inherits (spell), primary_target (n, reach, more), cleave_reach, nth_swing_double, execute, spread_to_dotted, consume_dot, missing_health_more, armor_health_more, damage_shield, stun_dotted, doom_streak; meteor, free_heal and gate_coil carry their numbers too. blow_cast (spell) makes each blow of the talent's demons also a free cast of the hero's spell, shown from that demon (it wears the hero's spell colours), with every upgrade the hero gave it and the cleave plays that name it (the Water Elemental: Frostbolt, Splitting Ice).
  • The shaman's shock plays (shock_echo, shock_boost) list the shocks they chain in keys.
  • exclusive rules talents out of each other: exclusive = true is its tree's pair, exclusive = "<group>" a named group of the class, across its trees (the warlock's legion: Legion Gate's lesser demons or Demonic Supremacy; the monk's stance: one stance milestone of the three trees). Of a group, the talent taken first (tree order, then file order) stands and the others take no ranks (survivors-sim/src/talents.rs hold_to_rules); a group of one talent is refused. The two capstones of a tree rule each other out without it.
  • A talent's effects are the exe's table (re/tools/talents.js rewrites them); a number we changed on purpose carries an # Ours: comment above it, and the tool would put AS's back.
  • A summon play (pets, n, lasts, spread, most) may say floor, the lowest share of its {v} seconds cooldown reduction brings it to (0.43: every 30 sec at most every 13), and lesser = true, lesser demons that Demonic Supremacy's stat stops.
  • talent_looks.toml blow = "reflect" | "kit_thorns" | "spell_thorns": the run's own blows (Eye for an Eye, the thorns) take their meter row, school and spell id from that look.
  • A talent's own damage (a crit_bleed or hit_dot bleed, a burst) goes to a damage-meter row under the talent's key: the row reads the talent's name in the player's language, and its icon is the talent_looks.toml spell of that key (no look, no icon). Give such a talent a look.
  • The ticks of a crit_bleed or hit_dot bleed roll a crit as the hero's hits do (Run::tick_bleeds: the hero's crit chance and crit damage, no spread on the sum the bleed was laid with); a crit tick shows as a crit in the damage log and the Biggest Crits list. A dot spell's ticks always did (Run::tick_dots). Test a_bleed_tick_can_crit. A set's field_burn ticks and a no_crit spell's stay without.
  • per_sec = true on a hit_dot play (default false): {v} is the share of the hit dealt every second, not the share over the whole secs: the tick is a second, so a tick is {v} of the hit and secs seconds add up to {v} times secs (Deadly Poison: 40% every second for 8 sec, 320% in all). Every other hit_dot keeps its {v} as a share over its whole time. Test a_hit_dot_per_sec_deals_its_share_every_second_and_without_it_over_the_whole_time.
  • kit = 3031 on a hit_dot or kill_burst play (a SpellVisualKit.dbc id, 0 none, the default): the stock effect the play shows on an enemy, sent as SMSG_PLAY_SPELL_VISUAL to every seat like a shop kill effect. A hit_dot shows it on an enemy that takes its damage over time afresh (not while it still carries it, not on a corpse); a kill_burst on the corpse as the burst goes off. Both go through the hero's budget of effects (Run::play_kit, the kill effect's as well; an elite or a boss always shows it). A damage log draws nothing of its own on the enemy, so a talent whose damage should be seen names a kit. Find one from a spell that has the look: its Spell.dbc row's SpellVisual, that row's impact column (3) and the kit it names (the rogue's Deadly Poison: 2818, kit 3031 Poison_Impact_Chest; Toxic Bloom: Plagued Blood Explosion, kit 8059). The release packs the kits' models from talents::play_kits (azs-host's cosmetic roots). Tests a_poison_and_a_cloud_play_their_kits, a_poison_and_a_cloud_without_a_kit_play_none, what_a_play_shows_is_a_release_root.

A set bonus

A set wakes with four armor pieces of its tier at 1+ stars (the 4-piece) and all eight at 3+ stars (the 8-piece); all eight at 5 stars empower the 8-piece by 1.5. The tiers are the rarities common uncommon rare epic legendary pvp (BASE_TIERS in survivors-content/src/set_bonuses.rs). Everything about a bonus is data (re/NUMBERS.md 14.6 has the originals, docs/PLAN-SET-BONUSES.md the design):

  • packs/base/gear/set_rules.toml (key = "rules", one entity): pieces = [4, 8], stars = [1, 3], empower_stars = 5, empower = 1.5.
  • packs/<pack>/gear/set_bonuses.toml: the 4-piece of each tier, one stat line for every class (key = "<tier>_4", pieces = 4).
  • packs/<pack>/classes/<class>/set_bonuses.toml: the class's 8-piece of each tier, one change to one of its spells (key = "<class>_<tier>_8", pieces = 8). A class without an entry for a tier has no 8-piece there, only the 4-piece.
[[set_bonus]]
key = "warlock_pvp_8"
tier = "pvp"
pieces = 8
text = { en = "Death Coil strikes {v} more enemies, deals 50% more damage, horrifies them for 3 sec and comes back 40% sooner, and you deal {v2}% more damage to enemies you stun, root, slow or fear.", de = "..." }

[[set_bonus.part]]              # scales with the set's strength; a count rounds
mods = [{ targets = ["death_coil"] }]
mods_v = 5.0
whole = true
shows = "v"                     # the text's {v}: this part's number

[[set_bonus.part]]              # written in the text: empowering does not change it
mods = [{ damage = ["death_coil"] }]
mods_v = 0.5
fixed = true

[[set_bonus.part]]
effects = [{ stat = [18, 0.6] }]
shows = "v2"
percent = true                  # shown times 100

A class bonus may define one mechanic = { kind = "...", spell = "...", ... } for a stateful effect. The spell belongs to that class. All durations, strengths, counts and ranges are positive pack values. Distances use the simulation's yards (divide metres by 0.9144). Mechanics keep their stated values when the set is empowered, but for a number that says it empowers (thaw_splash, formation_images): empowering multiplies that number, and the text's {v} shows it in percent for both strengths (no part fills {v} then). An optional marker = { entry = 990101, display = 90103, scale = 0.65 } chooses an existing creature display for a visible pickup or moving projectile. Without it the source spell supplies the ground visual. A bonus may show some of the class's spells on the action bar as another spell while a rule holds, [[set_bonus.form]] with spell (the key of a spell of the class), id (a spell ID of the reserved 911001-911999, no spell's own, one for each form), icon (a file of Interface/Icons, without its path or extension, that the client's SpellIcon.dbc knows), name (the button's tooltip name, in every language) and when. when = "fused" holds once the bonus's spell_fusion has fused (the hero has drawn every spell it fuses, spell among them). The spell stays what it is in the run (its effect, its cooldowns, its cards): only its button changes. While a form holds, Run::known_spells (the spellbook and the bar at the world entry) and send_spellbook name the form's id in the spell's place, and every SMSG_SPELL_COOLDOWN and SMSG_CLEAR_COOLDOWN of the spell is sent under the form's id (Run::send), so the button sweeps; the run sends the spellbook and the bar again the tick a form starts or stops holding (Run::sync_bar_forms). The patch builder (tools/class-spell-vfx.py) writes each form into the client's Spell.dbc: a copy of the spell's row with the form's icon and name; rebuild the patch for it to show. A new when (an "after n hits") is a new FormWhen value read in Run::bar_forms. Tests a_fused_bonus_shows_its_spells_as_forms_on_the_bar (the pack's rules), a_fused_hunters_bar_shows_the_bombs_forms_and_sweeps_their_cooldowns (the run's bar and sweeps) and test_a_set_form_is_a_spell_of_its_own (the patch builder). A bonus may rename a spell of its class while it is awake, [[set_bonus.rename]] with spell (the key) and name (the new name, in every language). The spell is the same one (its key, icon, effect and cooldowns), but the level-up cards, the action bar's tooltips and every name the interface shows for its ID read name, and the card's and the tooltip's description is the bonus's own text (the Path of Darkness 4-piece: Cloak of Shadows is Darkness). The run tells the interface the names of the spells of the hero's class that a bonus renames (AZSNAMES, sent with the tips, so a new language or a sync sends it again; the spell's own name goes back if the names were told and the bonus is gone): Run::set_rename, Run::set_rename_text, Run::set_names_line. A hero whose bonus is not awake, and whose names were never told, hears nothing of it. Nothing in the client's tables changes, so it needs no patch rebuild. Test the_pack_writes_the_balance_teams_numbers (the rogue's 4-piece). A bonus may also make looks for its missiles, [[set_bonus.look]] with visual (a spell ID of the reserved 910001-910999, unused by any spell's visual), source (the 3.3.5a spell whose look it copies) and missile_scale and/or missile_speed (the source's missile drawn that many times as big, flown that many times as fast), and/or no_missile = true (the look keeps what happens where the source lands and loses the missile that flies there) and impact_scale (what happens where it lands, drawn that many times as big; 0.1 to 4) and/or cast_scale (what the source draws where its caster stands, as an explosion the caster itself casts, that many times as big; 0.1 to 4; a source needs the kit in question: the compiler stops on one without), or in place of cast_scale a cast = { model, slot, scale } (a model of its own in the cast kit, as a spell's vfx accent writes it: a copy of the source's cast kit, or a new one, with that model in that slot at that scale, 0.1 to 2; the model must be in the client's SpellVisualEffectName). An impact = { model, slot, scale } accent instead replaces the source landing model in its impact kit at a fixed scale; gameplay area bonuses do not resize it. impact and impact_scale are alternatives. tools/class-spell-vfx.py writes them into the client's tables in the final patch step (rebuild the patch for them to show); a mechanic names one as its visual, shot or a drift blade's spin look. A look may also say alpha (0.05 to 1, 1 as the source draws it): how solid the client draws its models, for a blast that flashes the screen (Arcane Trinity's nova, 0.2). The client reads it by the look's spell ID (set_bonuses::look_alpha) for the kits the look plays on units (cast, impact, aura) and its missile, every part alike (particles, ribbons, meshes, cards, ground decals); a burst at a ground point keeps its stock alpha, and the tables carry nothing of it, so it needs no patch rebuild. A look may also give the client a hue, turn (degrees, -359 to 359: the look's colours rotated round the colour wheel as a shop spell colour does, Circle of Holy Light's shot 160 as the shop's Azure Light; a colour the hero wears for the look's school, or a class colour, replaces it) or tint (0 to 359: every colour set to that hue as a class colour does, 115 the green of Fel; it wins over what the hero wears), not both. The client reads it by the look's spell ID (set_bonuses::look_hue, in entities/spell_fx/hue.rs cast_hue) for what the caster casts or flies (the kits and the missile) and for the beam of a chain spell (entities/chain_beam, which asks cast_hue when the beam is made and hues its whole draw, texture included); an effect drawn at a ground point carries no caster to stamp, so the hue does not reach it (a persistent ground area, a DynamicObject of the hero's, does: Creeping Death's Poison Pool). The units that cast for the hero (a totem, an image) must wear the hero's colours to take a worn one: the server copies them to a ring's totems. The tables carry nothing of the hue, so it needs no patch rebuild. Test a_look_changes_something_within_the_reserved_range, a_part_alpha_is_the_share_of_its_tag, a_look_with_a_hue_gives_the_client_its_turn_or_its_tint, tools/test_class_spell_vfx.py.

  • dot_diversity { share } adds a share of tick damage for each different active periodic spell that the hero has on the enemy.
  • retaliation_splash { spell, cooldown, radius, targets } replaces a retaliation spell's base cooldown and gives its full retaliation hit to up to that many enemies near the attacker.
  • ground_root { spell, metres, radius, damage, secs } replaces a strike with a ground hit at the densest enemy group within metres of the caster. Its radius in yards scales with area bonuses. Enemies in it take the spell's damage multiplied by damage and are rooted for secs.
  • marked_death_casts { spell, charge, casts, radius, elite_only? } marks a target on a direct hit of spell. With elite_only, only elites and guardians can be marked. Each direct hit of charge on a marked target adds one cast on death. The cast picks a strike from casts and an enemy within radius yards of the death. The strikes and their riders use the caster's normal power.
  • chain_override { spell, jumps, metres, falloff } sets a chain spell's jump count, maximum jump distance in metres, and share of damage retained at each jump.
  • field_strike { spell, field, cast, targets, damage, fallback_visual, fallback_key, fallback_damage } triggers on the named spell's hit. Inside the hero's named ground field, nearby enemies within the secondary spell's range take a share of the original hit. Outside, the original target takes the fallback share if still alive. Each secondary hit is a proc.
  • chain_recast { spell } casts a chain a second time, starting on a different primary target.
  • permanent_pets { pet, count } keeps that many ordinary pets of the chosen kind at the hero's side.
  • pet_portal { config } marks enemies with a periodic spell and opens a temporary portal on their death. Its config names the spell, portal marker, active limit, seconds and pulse interval, search range, splash radius, pet kind and count, damage share, leap milliseconds and damage meter row.
  • soul_harvest { config } drops a soul on the death of an enemy marked by spell. The hero spends souls on a reaper when trigger marks a primary target; on each kill the reaper can jump to a nearby marked enemy. Its config names cast, pickup radius, mark/drop/reaper lifetimes, jump count and radius, damage share, travel milliseconds, markers and meter row.
  • hit_vortex { config } starts a vortex at every hits-th direct hit of spell, pulls ordinary enemies within radius until secs and deals damage times the spell's hit. Its marker supplies the name, entry, display and scale, and row names its damage meter line.

For each of the three config effects, a seat uses the first configured mechanic of that kind in its awake sets' order. Named markers use distinct entries in 990000-990999 and inherit the old stock query names only in retained ABI-1 profiles that use the legacy entries.

  • pulse replaces the named spell's normal cast with a learned-spell pulse. It takes radius, every and damage (base damage before the spell's normal damage scaling).
  • nova overrides a nova's base radius and cooldown and removes its base stun.
  • freeze_chance reads the named spell's school and gives direct attacks of that school a chance (at most 1) to freeze for secs. Freezes respect hold resistance.
  • form_trap leaves thorns when the form changes. It takes radius, secs, root, spreads and cooldown. Each triggered patch moves to its victim and excludes previous victims.
  • death_sprout leaves a pickup when a rooted enemy dies. It takes pet, pickup radius, mature, secs, summon duration and damage (a share of the named spell per attack). Only one of this mechanic's summons can be active.
  • thaw_splash stores a share of the first hit of the named spell (same_spell; any hit without it) on a frozen enemy, and when that enemy thaws or dies frozen, splinters of the stored damage jump to other enemies. It takes radius, targets (at most that many splinters, each enemy at most one, the thawed enemy never) and damage, the share of the hit that is stored (empowers = true: it follows the set's strength and {v} shows it, 80 and 120). Rules:
    • The first hit of a freeze is the first Deep-Freeze-like hit while the enemy is frozen, and also the hit that froze it (or froze it again), even a hit that would freeze and kills; a later freeze, whatever its source, makes the next hit the first again and its amount replaces the stored one. The whole hit counts, overkill too. Proc hits (splinters) store nothing.
    • Splinters go to bosses first, then elites, then the rest, each the nearest first. A splinter deals the stored number with the bonuses that depend on the enemy it strikes, and nothing of the hero's own (the stored blow holds those already: the set's factor, talents, gear, cards). Those are the marks and vulnerabilities on the enemy (Hunter's Mark, Arcane Trinity's and Frost Tomb's, a broken enemy's) and the stat bonuses against a kind of enemy: an elite or boss (vs_elite), one with little health left (vs_low), one under the hero's damage over time (vs_dotted), a held one, frozen, stunned, rooted, slowed or feared (vs_held, stat 18: Shatter), an exposed one; they are worked out as for any other hit (added up, then multiplied with the marks). So Shatter may act twice on one chain, once in the stored blow (the first enemy was held) and once on the enemy a splinter strikes. The armour and shield bonuses (per_armor, shielded, unbreakable) and Bloodthirst's stacks are the hero's own and are not taken again. It rolls the hero's crit chance and factor, with no spread on the damage. It freezes through the hero's stun talent for the spell's school (Frostbite) and not at all without one. Tests a_splinter_takes_the_bonuses_of_its_target_and_none_of_the_heros_own, a_splinter_deals_the_stored_number_whole_unless_it_crits.
    • boss_immune = true: bosses and guardians are never frozen by it, so they hold no frozen state and store nothing, though splinters and shots still hit them.
    • visual is the splinter missile's look (a spell ID), kit a SpellVisualKit played on the enemy as the splinters leave it (Shatter's 6452).
    • An optional orbit (with a marker) casts the named spell in turn from count emitters circling the hero at radius, one turn in period seconds, a cast every every seconds on a fixed beat that no cooldown changes (a late step catches up a round of beats at most). A cast is the whole spell on the targets the hero's own cast would pick, but ordered boss, then elite, then nearest, within the spell's range of the hero; none in reach, the cast is lost. shot is the cast's missile look (a spell ID). height is the default offset above the hero; heights overrides it by body display and scales the marker by it.
  • strike_chain adds jumps to each target of a strike. Set the jump radius, additional targets and fixed damage share per jump.
  • field_echo makes a totem cast another spell (cast) from its position every every seconds at the given damage share. The normal totem shots continue on their own timer.
  • spell_freeze replaces the named spell's rider with a chance (at most 1) to freeze a target for secs, subject to normal hold resistance (boss_immune = true: bosses and guardians are not frozen at all). Each target rolls alone.
  • nova_every replaces every every-th cast of the named nova spell (the mage's Arcane Explosion) with a bigger one: area times its radius (every radius bonus counted) and damage times its hit, which then rolls crit and spread like any cast. The replaced cast does not happen; the count starts again at 0. Every cast of the spell counts: one the hero casts, a free one (Arcane Concentration's), a double hit and an echo; the casts of formation_images never do. An echo or double hit of the big nova is a normal cast that counts as the first of the next round. Each enemy it strikes is slowed by slow percent for secs (boss_immune = true: a boss is not slowed; without it a boss and a guardian are slowed in full) and takes vulnerability more damage from every source for secs, multiplied with the other damage bonuses; struck again, both timers start over at secs and nothing stacks. Slows in general (Run::rider_on): the strongest running slow counts, one of the same strength only refreshes (the longer of what is left and its time) and a weaker one never replaces a stronger one. visual is the look (a spell ID of a [[set_bonus.look]]) the big nova is drawn with, with no skin or spell colour; without it the spell's own look is used. The cast needs an enemy in the spell's normal reach.
  • formation_images makes the named summon spell's images (the hero's Mirror Image) permanent: the first cast brings them all and no cast does anything after it. The bonus's 4-piece or 8-piece gives the spell (a part with start_with), and while it is awake the spell's card is never dealt: no banish is spent. The images stand one at each of angles (degrees from the hero's facing, counter-clockwise, so 180 is straight behind and +60 front left) radius yards from the hero and turn with them; where a wall or a drop is in the way an image stands nearer on the line to the hero and goes back out when the place is free. The client puts them there every frame from the hero's own position and facing, copies the hero's animations and mount, and draws them with alpha (1 is solid); the server sends them no movement. They take no damage and no enemy sees them. Whenever the hero casts the named cast nova, every image casts it in the same moment round itself, with the hero's radius and the hero's skin and spell colour, for damage of the hero's hit (empowers = true: it follows the set's strength and {v} shows it in percent, 60 and 90) with the hero's crit chance; this includes free casts, echoes and a nova's replacement. An image's cast never rolls a free cast or an echo itself and never counts for nova_every. What the images deal and slay is the hero's: experience, kill counts, kill effects and the leech. They vanish while the hero is down or dead and return to their places when the hero lives; without the spell cast no image stands and none casts.
  • shared_cooldown makes the cast spells in spells (the hunter's three traps) share one cooldown. Each spell the hero has drawn counts, in any order, and one alone has it too. Its base is cooldown seconds for all of them, taken through the normal cooldown rules (cards, talents, gear, haste, the floor of 20% of the base) at the strongest cut any drawn spell of the group has, so one trap's legendary cooldown line shortens all. The group casts as soon as it is ready and one of its spells has an enemy in its own reach (a ground spell: an enemy within its range and area, a nova: within its radius); then all of them cast at once, each where its own rules put it, one with no enemy of its own in reach is left out, and the shared time starts for all of them, the left out ones too. A talent that lays one of the spells (Wyvern Sting, Counterattack) is a normal cast: it does not use the shared time and lays no other spell.
  • spell_fusion fuses the spells in spells into one bomb once the hero has drawn every one of them (the order does not matter; before that only shared_cooldown counts). The spells keep their places on the bar (the bonus's [[set_bonus.form]]s are what the client shows on them) and are no longer cast one by one. The bomb takes every number from source, a nova spell (the Explosive Trap): it is laid at the hero's feet as soon as an enemy is within area times the radius of source (the radius with every card and bonus counted), goes off fuse seconds later where it lies, the hero near or not, and its cooldown is cooldown seconds through the cooldown rules at the cut of source alone (so it has cooldown over the base of source times what source has). The explosion deals damage times the hit of source (with every bonus of source) to every enemy in that radius, each rolling its own crit (empowers = true: damage follows the set's strength and {v} shows it in percent, 1000 and 1500), and slows them by slow percent for slow_secs (Run::rider_on: bosses and guardians in full, a running slow only refreshes). Burning ground then covers the same radius for the time and with the beat of the ground spell ground, drawn like it; each beat deals burn times the explosion's hit, as a crit to the enemies the explosion crit and plain to the rest (a beat never rolls itself), and the grounds of several bombs stack. The ground spell chill is laid at the spot as it is on its own (its own level and bonuses). The bomb stands in the models the spells lay (lays), all at scale times their size, until it goes off. From the fusion on only the card of source is dealt, so the others keep the level they had, and no banish is spent. visual is the look (a [[set_bonus.look]] spell ID) the explosion is drawn with: the world draws it where the bomb lies (a caster-free destination visual, so the hero may be anywhere), a look whose landing (impact kit) is the explosion, such as a stock bomb's without its missile. rocket (a look of a missile) and rocket_speed (yards a second, the speed the client flies it at: its source's Spell.dbc speed times the look's missile_speed) add a rocket that falls on the bomb from rocket_speed * fuse yards straight above and lands the moment it goes off; it is only drawn. chill_visual (a [[set_bonus.look]] spell ID) is the look the chill ground is laid and drawn with when the bomb lays it, in place of the spell's own (a recoloured copy of its look: source the spell, a tint); the spell laid on its own keeps its look. Test a_rocket_falls_on_the_bomb_and_the_world_draws_its_explosion_where_it_lies.
  • field_ring casts the named totem in count equally spaced positions at radius yards round the hero, the first straight ahead of where the hero faces at the cast (three stand at 0 and +-120 degrees). entry and display choose the creature shown at each position. Each is a whole totem: its own time, beat and hit. Where a wall or a drop is in the way a totem stands at the last free point of its line from the hero, nearer. A new cast adds its totems to the old ones, which stay until their own time is out; max is how many stand at most (default count, so a new cast replaces the old ones): at the limit a new totem takes a free place first and replaces the oldest one where there is none (of equally old ones the first set). A cast sets its own count round the hero's place and facing, on old totems if they stand there (without slots of a field_burn). The totems wear the hero's spell colours, so what they shoot is drawn in them. They stay where they were set unless a field_burn of the same spell is awake, and they vanish when the hero falls. The 4-piece that sets the ring gives the totem spell with a part (effects = [{ start_with = "lightwell" }]) when the run should start with it.
  • field_burn makes that ring turn round the hero and follow them: one turn in period seconds (clockwise = true: clockwise seen from above, else counter-clockwise; the hero's facing changes nothing but where a ring starts). The client turns the ring itself, as it stands the mage's formation_images: it is told each totem's angle, its radius and the turn (from period and clockwise, and again after a hold, a wall or every few seconds), and stands the totem on the ring every frame from where it draws the hero, so a running hero is never trailed. The run keeps its own totems on the same ring for the aim and the shots. Nothing of that is written in the TOML. slots gives the ring that many fixed places, equally spaced, which turn with it (at least the ring's max): the first cast with no totem standing takes the places slots / count apart from the first one (the ring starts where the hero faces), every further cast puts its totems one place on in the turning direction from the places of the cast before it (the next free one when taken), and a totem that replaces the oldest at max takes its place, so nothing jumps. Without slots a new cast puts its totems where the hero faces. Test the_turning_ring_has_27_places_the_first_cast_takes_0_9_18_and_each_next_one_place_on. Every hit of a totem sets the enemy burning: damage times the hit it dealt (after every bonus and a crit) in ticks ticks every seconds apart, which never crit and take only the damage-over-time talents on top (Mods::dot_factor); one burn an enemy, a new hit starts it over with its own sum; a burn runs to its end when the totem is gone. empowers = true: damage follows the set's strength and {v} shows it in percent (100 and 150). An enemy that dies of a burn tick bursts for burst times its maximum health on every enemy within radius of it, using the spell ID visual: exactly that, no bonus, no crit, no burn from it and no burst of what it slays (a kill by a hit or by anything but a burn tick never bursts). Ticks and the burst are dealt whole (Run::set_exactly). jumps, jump_radius, speed, shot, ranked make a totem's hit a shot in a chain: each beat the totem sends one shot (one more for each extra target the hero has for the spell) at an enemy within the spell's range, ranked = true choosing by rank (boss, guardian, elite, normal; the nearest of a rank first). The shot flies at speed yards a second (0: it lands at once), drawn as the look shot (a [[set_bonus.look]] spell ID; its source's own speed is the number to give), and does nothing until it lands: its enemy then takes the totem's hit with its own crit and burns, and the shot jumps on, up to jumps times, to the nearest enemy within jump_radius of the one it hit that the chain has not hit yet (by rank when ranked); with none it goes back to the enemy it came from if that lives within jump_radius, else the chain ends. An enemy that dies before the shot lands loses the shot and its chain. The amulets' jumps leave once the chain has ended, from the last enemy it hit (not before, so the hero's jump amulets add their jumps after the set's), and every enemy they hit burns for its own hit. Test a_burn_is_one_third_of_the_hit_a_tick_for_three_seconds_and_a_new_hit_starts_it_over and the other holy.rs tests of Circle of Holy Light, circle_of_holy_light_is_the_balance_teams_set.
  • return_orb leaves a homing projectile on a successful cast. It takes delay, speed (yards per second), collision radius, damage (a spell-damage share) and active cap. Each projectile strikes each enemy once. Optional per_target = true replaces the caster-origin trigger with one orb at each landed direct nova target's impact position, including lethal hits. Echoes and free casts use the same nova path; orb hits never create orbs. After delay, orbs follow the hero's current position, checking the swept collision path before arrival removal, including an immediate arrival. The existing cap overflow rule remains. Optional empowers = true scales cap (rounded) and damage together; the mechanic supplies {v} = cap and {v2} = damage percent for the tooltip. Both flags default to false for existing packs.
  • prey_chains, with config = { spell, max_prey, jumps, segment_range, damage, chains_per_tick }, marks up to max_prey elites, guardians or bosses on the owner's first regular direct spell hit. Later hits of that spell accumulate weaknesses, including generated chain hits. On death, every weakness queues a chain with distinct targets, each segment within segment_range yards; a segment without a target ends the chain. Each hit uses the spell's current damage calculation times damage. chains_per_tick bounds queue processing without dropping pending chains. Empowerment rounds and scales jumps, also shown as {v}. See survivors-content/src/set_reactions.rs.
  • chain_storm uses config = { spell, copy } for one regular-cast copy starting at another valid target in effective start range. It reuses the effective chain configuration and its own target hits, without an extra cooldown or recursive copies. Its threshold form writes hits, radius, pull, damage, row and marker: every hits landed owner hits, including the copy and jumps, fixes a storm at the highest-priority enemy in start range, falling back to the impact position. It stores damage times that chain's calculated first hit, including its crit; after pull seconds pulling normal enemies, it deals the stored amount once per enemy within radius. No second offensive scaling or crit roll applies. These fields do not empower.
  • ambush_window uses config = { spell, source, secs, opener_secs, follow_secs, damage, shadow_share, width, smoke, stealth, veil, slice, spin, image_aura, image_secs, marker, empowers }. A committed regular cast of spell opens a secs window before its hit when the opener or follow-up is ready. The opener's opener_secs timer keeps running during kill-driven follow_secs chains. Normal and elite enemies lose the hero as a target; other spells keep casting. damage adds to the named spell's damage once, including derived copies. The window records actual health removed by its hits, including extra targets and echoes. At the end an image deals shadow_share of that sum once per enemy along the start-to-current-position path (width); standing still uses its local circle. The settlement has no new crit roll or offensive multipliers. A window or image kill permits the next regular cast within follow_secs to reopen it. source names its damage row; optional localized source_name labels it in the meter; the look IDs, image_secs and optional marker control visuals. With empowers, damage and shadow_share scale; tooltips deliberately retain their base values. See set_windows.rs.
  • cast_link joins consecutive cast positions. It takes seal lifetime, path secs, half-width, tick every, damage (a spell-damage share per tick) and shield (a maximum-health share). Each ally gains the shield once per path.
  • frozen_graves leaves graves where marked enemies die; a grave is not used up and lets a ghoul go on every beat while it lies. It takes pet, marker cap and secs, the beat every (seconds: the first ghoul goes every after the grave is laid, so 15 and 2 make 7 ghouls a grave), search radius, explosion blast radius, travel speed and damage (a spell-damage share per explosion). An enemy is marked when it dies frozen (a freeze of thaw_splash or freeze_chance), or with entombed = true when it dies with a live stack of the hero's entomb (read as it dies, before its stacks end with it). A grave's ghoul aims within radius of the grave: with entombed at the nearest boss or guardian that carries every stack an entomb can, else at the thickest enemy group (blast wide). The ghoul runs there and explodes on every enemy within blast, each once; the explosion is a proc (it lays no entomb stack, is no cast, so no echo and no amulet's extra) but takes the hero's damage bonuses and the target's entomb vulnerability, and with crit = true every enemy it strikes rolls its own crit. source (a text in every language) makes the explosion a damage-meter source of its own under that name, with the icon of spell. empowers = true: damage and blast follow the set's strength; {v} shows damage in percent and {v2} shows blast in meters (the pack writes yards, METERS_PER_YARD). Tests ice_graves_come_from_entombed_deaths_and_each_lets_a_ghoul_go_every_two_seconds, a_grave_goes_for_a_boss_with_every_stack_before_the_thickest_group.
  • entomb (the death knight's Frost Tomb 4-piece): every hit the hero deals in the school of spell (a cast's, a tick's; not a proc's and not the frozen_graves explosion; a hit that kills lays none) lays one stack on the enemy it strikes, up to stacks. All stacks of an enemy end secs after the latest hit (each new hit starts the time over for all). Each stack makes the enemy take vulnerability more damage in that school from the hero (added up, then multiplied with the other bonuses; the explosion of frozen_graves takes it too) and slows it by slow percent (the stacks' sum; bosses and guardians too, the strongest running slow counts as for every slow). empowers = true: vulnerability follows the set's strength and {v} shows it in percent. The stacks are a debuff the enemy carries: a boss's or a lair guardian's shows in the target window's debuff bar (AZSDEBUFFS, under name, a text in every language, with icon, a file under Interface\Icons, else the spell's own icon), and the client is told the stacks of every enemy near the hero for the counter drawn over it (AZSTOMBS). Tests entomb_lays_a_stack_per_frost_hit_up_to_five_for_four_seconds_and_slows_five_percent_each, the_stacks_are_a_debuff_the_target_window_lists_for_a_boss_or_guardian.
  • pet_harvest (the death knight's Eternal Grave Harvest 8-piece): an enemy that dies under the hero's damage-over-time spell spell (a stack of it on the corpse, or the tick that slew it) rises as a pet for secs seconds while fewer than cap of those stand; one that the pets' own casts slew rises as well. The pet inherits inherit of the hero's maximum health and blow power, strikes targets more enemies with each blow, and each blow casts spell (the hero's level of it, rank 1 unlearnt) for damage times its hit with the hero's modifiers, as a stack of the hero's. stacks is how many stacks of spell an enemy carries at most from every source (the hero and the pets): the strongest stack has priority (a stronger one takes the weakest's place, a weaker one is lost, equals start the oldest over), the spell's time is untouched (Dot::lay_strongest; without this word a dot stacks to the cap of its shape). visual is the look (a spell ID) played where a pet rises. Only these pets count as "of the set": a talent's pets (Master of Ghouls, Army of the Dead) are not boosted. empowers = true: damage and inherit follow the set's strength and {v}, {v2} show them in percent; cap, targets, stacks and secs do not grow.
  • pet_boost (the Eternal Grave Harvest 4-piece): the pets of kind pet that the pet_harvest of the same spell raised deal damage more (1.0 is twice; their harvest spell cast too) and strike targets more with each blow, on top of the harvest's own targets. empowers = true: damage follows the set's strength and {v} shows it in percent. With beat = { secs, every } the damage-over-time spell itself is laid as a beat while the bonus is awake (the hero's cast of it, the pets' and an amulet's alike): it lasts secs (the hero's duration bonuses still stretch it), ticks every every seconds, and each tick deals the spell's whole hit, not a share of it; every stack ticks on its own. The spell's tooltip is worded for it (Cast::beat_dot) in all 12 languages. Tests the_four_piece_boosts_only_the_ghouls_the_set_raised, the_exotic_four_piece_lays_pestilence_as_a_beat_of_whole_hits.
  • drift_blades sends blades out of the hero in straight lines (the warrior's Exotic set: a blade with the 4-piece, two images of the hero with the 8-piece). Every every seconds blades of them leave, each flying range yards in secs seconds toward the nearest enemies beyond beyond yards of the hero (bosses and elites first), no two on the same side (a quarter turn apart for two; with no enemy to show the way a blade turns on a heading of its own, which moves on with every launch). A blade strikes each enemy within radius of its whole path for damage times the hit of spell, and the same enemy again once rehit seconds have passed (at secs or more it strikes each enemy once). The hero must know spell (a part with start_with gives it) and an enemy must stand within range + radius; a launch that finds none waits for the first that does. Of several bonuses that write blades the last awake one launches, so the 8-piece's replace the 4-piece's. The bonus needs a marker (a blade is a creature: its display moves, an area cannot); images = true puts the hero's own look on the blade (the marker's display is then replaced, its scale kept) as a Mirror Image wears it, and aura is a spell ID whose look aura the blade wears (Bladestorm's 46924). Two more words, each optional, make a blade turn and break up: spin = { look, every } plays the look of the spell look on the blade itself at once and then every every seconds while it flies, so a look whose cast turns its caster (Whirlwind's own, spell 1680: its cast kit plays the Whirlwind animation, which the client plays full-body even on a moving unit) spins a blade that wears the hero's look; the look is a stock spell or one of the bonus's own [[set_bonus.look]] (the warrior's 4-piece plays 910904, the Devastate axe in a cast kit, on an invisible marker, display 29885: a model with no attachment points hangs every kit model at its feet). split = { into, times, fork, damage, reach } breaks a blade whose flight has ended into into blades that start where it ended, spread fork degrees apart round the heading it flew (two with fork = 90 leave 45 degrees either side) and fly reach times as far in reach times the time, striking for damage times as much and remembering which enemies the parent struck last (so none is struck twice at once). They are images or orbs like their parent, spin like it, and break again the same way until a line of blades has broken times times; the content check refuses a launch that could end in more than 64 blades. on_hit = { spells, per, most } sends the blades out on hits instead of every every seconds (the warrior's 8-piece: Whirlwind's and Bladestorm's): the own hits of the named spells (a cast's, a totem's beat; never a proc's, a periodic one or a blade's) are counted, and a launch sends one blade for every per enemies struck, a started group counting, at least blades and at most most (most is what the 64 counts); every is then the least time between two launches, and hits before it has passed leave as soon as it has. The spells must be the class's. Tests drift_blades_may_leave_on_hits_one_for_every_few_enemies_struck, the_eight_piece_sends_one_image_for_every_few_struck_at_most_once_an_interval. A class's 4-piece replaces the tier's shared one, so a class that writes one gives the shared stats as parts again.
  • nova_echo (spell, cooldown; the demon hunter's Exotic 4-piece) sets the base cooldown of the nova spell to cooldown seconds (the normal cooldown rules, cards and the floor, still cut it) and makes each cast the hero makes of it also go off at the place of the cast before it: the same nova (its look, its radius with every bonus, its hit, its rider) at that place. The first cast of a run has no echo, and an echo is no cast (it counts for no cooldown, rift or cast bonus). Test nova_echo_cuts_the_base_cooldown_and_goes_off_at_the_cast_before.
  • nova_seam (spell, rift, travel, width, damage, empowers, fire, rift_marker, flame_marker; the Exotic 8-piece) leaves a rift of rift seconds where each cast of the nova spell stood (an echo leaves none; rift_marker is the creature drawn there). The next cast, while the rift still stands, links it to the hero's new place at any distance: a flame (flame_marker; it plays the look of the spell fire as it sets out) travels the seam in exactly travel seconds whatever its length, and the line it has crossed burns (the same creature laid every two width along it) until it arrives. The whole crossed line, width yards either side, strikes each enemy that touches it once for damage times the hit of the linking cast (a crit of its own for each), shown as Chaos Nova's damage. A linked rift is spent, the seam runs to its end although the rift would have run out, and several seams are separate (an enemy is struck once by each). The creature markers belong to the mechanic (not the bonus' marker): their entries are unique among all markers. empowers = true: rift and damage follow the set's strength and the text's {v} shows the rift's seconds and {v2} the damage in percent (8 and 130, empowered 12 and 195); a mechanic that writes both numbers fills both placeholders itself (SetMechanic::shown_values), so no part shows them. Tests a_seam_links_the_rift_to_the_next_cast_at_any_distance_within_the_rifts_time, a_seam_strikes_each_enemy_once_in_flame_or_trail_and_runs_on_when_its_rift_is_gone.
  • proc_cast (spell, cast, chance, damage, most, empowers, then; the Mythic 8-piece) gives each hit of the spell spell (its own hits only: not periodic ones, a proc's or a blade's) chance to cast the spell cast free: costs and spends nothing, starts no cooldown, and deals damage times its hit (on the targets a cast of it picks, cards counted). Of the free casts won, at most most are let through in any rolling second (a win over the limit is lost). The hero need not know cast: it then casts at rank 1 as if it had just been picked (known_or_new). The cast is made on the next tick. then = { cast, chance, damage, most } gives a critical hit of cast, the hero's own cast and the free one alike, chance to cast then.cast free the same way for damage of its hit, at most most a second: these numbers are written in the text and never change with the set. empowers = true: chance and damage follow the set's strength and {v} and {v2} show them in percent (5 and 50, empowered 7.5 and 75). A free cast of the proc's own spell can win nothing more (cast is not spell). Tests a_proc_wins_free_casts_of_its_spell_at_most_a_few_a_second_and_a_crit_wins_the_then, a_free_cast_casts_a_spell_the_hero_has_not_learned_for_its_share_and_costs_nothing.
  • darkness (automatic, spell, only_spell, secs, cooldown, immune_secs, boss_share, boss_immune_secs, and the looks smoke, stealth, veil, flicker; the rogue's Path of Darkness 4-piece) turns the immunity spell spell (Cloak of Shadows) into a state. With automatic = true, it starts as soon as it is ready during play and ignores manual input; manual controls are hidden. With automatic = false (the default), the hero starts it with a key: the keyboard's AZS_DARKNESS (default 1), the controller's LT or the touch button, each sending AZSCMD darkness (RunCmd::Darkness). The spell never casts by itself while the bonus is awake (the hero must have drawn its card; it is dealt once and never as a rank-up), and the key does nothing without it, while the hero is in the Darkness or while its cooldown runs. A press makes the hero untouchable for immune_secs, plays the look smoke (a 3.3.5a spell ID) and puts the hero in the Darkness for secs, dressed in the auras stealth and veil (spell IDs of 3.3.5a, a translucent figure and a dark veil). In it every enemy loses the hero as its target: with another hero in the run (co-op) it goes for the nearest of the others by the normal rules, with none it stands still, striking no one, walking nowhere and starting no ability, and a grey ? shows over its head (SMSG_QUESTGIVER_STATUSINCOMPLETE, which the client keeps on a hostile unit; Horde::question); what is already under way (missiles, marked ground, a lit exploder, poison, a stampede's line) goes on by the normal rules. A boss or a guardian stands still for boss_share of the time of the Darkness that starts (a restart by a kill counts its own time), its wind-up broken as a stun breaks it, then goes for the hero again although the Darkness runs on, and the Darkness cannot stop it again for boss_immune_secs (a boss that appears meanwhile is not stopped at all). The hero casts only_spell (Backstab) and nothing else: every other spell, free cast, echo and talent's attack waits for the end and then casts when it is ready (Run::darkness_blocks, the free casts' queue holds), while shift, a racial, poisons and bleeds go on. The Darkness ends when its time runs out, when only_spell is cast and goes off (unless darkness_ambush keeps it), or when the hero falls or is knocked down; the flicker look plays and the cooldown cooldown starts there (never at the press), and no card, talent, trinket or cap changes it (Run::darkness_cooldown). The hero's state goes to the interface as the AZSDARK line (has;ready;on;cd;cdmax;left;auto, sent when has, ready, on or auto changes). The bonus's text has no number: every value is fixed. Tests in class_sets/darkness.rs.
  • darkness_ambush (spell, damage, kill_secs, empowers; the Path of Darkness 8-piece) goes with a darkness of the same hero: a cast of spell (Backstab) that begins in the Darkness deals damage more on every enemy it strikes and every strike it makes, as a factor of 1 + damage (4 gives 5) multiplied with every other bonus, before the crit (Run::darkness_damage_factor); the state at the start of the cast counts, so the Backstab that ends the Darkness has it too. A kill by a blow under spell's key during that cast (its own, a talent's blow that rides it such as Mutilate's second blade or Shadow Dance's cleave, a double hit; never a poison's or a bleed's tick, never an exploder's own burst) keeps the Darkness alive and gives it at least kill_secs seconds (the longer of what is left and kill_secs; no new immunity, no cloud, no flicker; bosses and guardians that are not immune stand again for their share of kill_secs). A cast with no kill ends it as it would without the set, and a kill outside the Darkness starts nothing. The part effects = [{ start_with = "cloak_of_shadows" }] starts the run with the spell (the run does not begin in the Darkness: the hero presses the key). empowers = true: damage follows the set's strength and {v} of the text shows it in percent (400, empowered 600).
  • poison_stacks (spell, talent, stacks; the Creeping Death 4-piece) changes a talent with a hit_dot play (Deadly Poison) of the same class: it is laid only by the hits of spell (a strike: Envenom), not by every spell the play's keys name (an empty list means all), and it stacks. Every hit of spell (each enemy it strikes, a double hit and an echo each) lays a stack of its own, the talent's share of exactly that hit (v, 40% every second with per_sec, or over the play's secs without it), for the play's secs (8 for Deadly Poison), a tick a second, with the talent's bonuses; an enemy carries up to stacks stacks of one hero (a second hero's are their own and do not count), a new one beyond that takes the place of the one with the least time left, and a stack that runs out leaves alone (Run::lay_bleed_stack, talented.rs). spell aims anew while the bonus is awake: of the enemies in its reach the most stacks first, then boss, guardian, elite, normal, then the nearest (Run::poison_targets). A bleed (a crit_bleed) is no part of it. Without the bonus the talent is laid and replaced as it always was.
  • poison_carrier (spell, talent, secs, every, jumps, radius, most, pool_secs, pool_radius, pool_slow, pool_share, pool_ticks, pool_most, empowers, glow, jump_visual, pool_visual; the Creeping Death 8-piece) goes with a poison_stacks of the same spell and talent. An enemy that carries all its stacks becomes a carrier of the hero's poison for secs seconds if the hero has fewer than most carriers; at the limit a higher rank (boss, guardian, elite, normal) displaces the lowest carrier, which ends at once, and an enemy that cannot become one waits, the first to have had the stacks first. A carrier lasts until its time is out, it dies or it is displaced: each own hit of spell on it starts its secs over, a jumped copy or another hero's poison does not, and falling below the stacks does not end it; one that ends with the stacks and a free place becomes a carrier again at once. At once and then every every seconds on a fixed beat a carrier gives copies of all its stacks (their strength and time left; it keeps them) to jumps enemies within radius of it, those with the fewest stacks first, then the nearest, another carrier only when no other enemy is within reach; a copy is no hit (no damage, echo or proc) and at the limit takes the place of the stack with the least time left, and an enemy that then has the stacks becomes a carrier in its turn (Run::poison_settle). The damage the talent's ticks take off a carrier, from any hero's poison and without what a killing tick leaves over, is added up over all its carrier time. A carrier that dies (a kill, a tick's too; not a burst that is no kill) leaves a pool where it died for pool_secs seconds, pool_radius yards wide (the hero's general area bonuses widen it, a spell's own do not), at most pool_most a hero (a further one takes away the weakest of all, by what it holds, the older of two, which may be the new one). Enemies in it are slowed by pool_slow percent while they stand there (the strongest slow counts, bosses and guardians in full) and every pool_secs / pool_ticks seconds take pool_share / pool_ticks of what the dead carrier's poison took off it: damage over time with no crit and no stack, taking the hero's damage-over-time bonuses again, one tick a beat on an enemy whatever pools lie over it (the strongest counts, a second hero's too), a kill by it the hero's. empowers = true: jumps follows the set's strength and {v} of the text shows it (2, empowered 3); the pool's share does not. glow is the spell ID whose look aura a carrier wears, jump_visual and pool_visual are looks ([[set_bonus.look]]) for the bolt of a jump and the pool; carriers show as a Deadly Poison and an Overdose entry in the target window's debuff bar of a boss. Everything about it, but the damage factor of the spell, is fixed; Creeping Death gives that as a part mods = [{ damage_times = ["envenom"] }] (mods_v = 2.0, empowered = 3.0, shows = "v2"). Tests in class_sets/poison.rs.
  • strike_jump (spell, jumps, radius, damage, speed, visual; the monk's Elemental Tiger Storm 4-piece) sends a hit of a strike on: every enemy a cast of spell strikes sends up to jumps leaps from itself, one after another, each to another enemy within radius yards of the one it leaves: the highest rank first (boss, guardian, elite, normal), then the nearest; never the enemy it leaves, but one already struck is a fair target, so two enemies in reach make a chain A, B, A. A leap deals damage times the hit it leaps from, before that hit's crit roll and with every bonus of the hero's own (a spent meter's bonus included), so what depends on the enemy struck (an elite, a mark, a low or held one) counts for the enemy it lands on, and every leap rolls a crit of its own. It is a missile: it flies speed yards a second (visual is its look, a spell ID; a stock look such as Chain Lightning's 421 needs no [[set_bonus.look]], and without it the spell's own look flies) and strikes when it lands. The enemy it was sent at, slain meanwhile, takes nothing, and the rest of the chain is lost; a leap that finds no enemy in reach is not sent. The hero's own leap is an own hit of the spell (what a hit of it sets off, an amulet's jump or a talent's proc, it sets off too: amulet jumps ride the leap's hits as they ride every hit), but a leap sends no leaps: only the cast's own hits do. At most 256 leaps are in the air at once. Nothing about it empowers. Code in class_sets/jump.rs (Run::set_leaps, Run::tick_leaps); the strike's cast reads it in Run::cast_shape. Tests in class_sets/jump.rs, in survivors-content/src/set_bonuses.rs (elemental_tiger_storm_is_the_balance_teams_revision_of_the_monks_mythic_set).
  • pet_copy (spell, pets, damage, needs, empowers, optional damage_cards; the monk's Elemental Tiger Storm 8-piece) makes the pets of the kinds pets (spirit, xuen: the elemental spirits of Storm, Earth, and Fire and Xuen) fight only by casting the hero's own spell (a strike): in place of its normal blow each such pet casts, from where it stands, a copy of the hero's spell as it is now (its targets, its reach, the talents', cards' and amulet's lines, a strike_jump of the same spell), at its prey and then at the nearest enemies within the spell's reach of the pet, as many as the hero's own cast would strike. Every enemy takes damage times the hit the hero's cast would deal it, with the enemy's own bonuses and a crit rolled with the hero's chance. The copy builds and spends no meter and has no meter's bonus, and sets off nothing of the hero's: it is a proc's hit (no talent or amulet proc, no cast of another spell) and no lifesteal heals for it (Run::set_blow_bare); what slays is counted as a pet's kill as ever. Its beat is the hero's cooldown of the spell with every cut it has, never under the cooldown floor, on a clock of each pet's own, so a pet that comes (Run::spawn_pet) strikes the moment an enemy is in its reach. The mechanic acts only in a run whose hero has taken the talent needs names and knows spell; otherwise the pets fight as they always did. needs is the mechanic's own: the bonus itself (its parts, the run's start with Storm, Earth, and Fire) works with or without the talent, unlike a bonus's needs. The run keeps the talents it took in ClassSets::taken (Run::stand_sets, rebuild_seat). The spells that call the pets are unchanged. empowers = true: damage follows the set's strength and {v} of the text shows it in percent (50, empowered 75). damage_cards = [{ pet = "spirit", spell = "storm_earth_and_fire" }] maps each copied pet kind to a spell's damage cards. It multiplies the copy once by the live source Known.damage_pct factor (1 + damage_pct / 100), defaulting to 1 when no source is known; the copy's leaps inherit that amount. Newly drawn cards affect existing pets on their next attack. Entries must name unique copied pet kinds and existing spells; the default list is empty. Tests in talented.rs (a_pet_casts_tiger_palm_in_place_of_its_blow_the_moment_it_comes_and_then_on_the_heros_cooldown and the three after it) and in survivors-content/src/set_bonuses.rs.
  • heal_sparks (sources, targets, radius, share, cap, speed, id, row, visual; the priest's Holy Sparks 4-piece) sends a spark for every heal the hero casts from sources (spell or talent keys: Renew, Circle of Healing in the priest pack; a heal over time counts each tick, overhealing counts, a heal_bell wave's heal never; the heal of a cast whose hits each mend, Holy Nova's mend rider, is one heal for the whole cast while a set counts it) from the healed hero to up to targets enemies within radius yards of them (boss, guardian, elite, normal, then the nearest). A spark flies speed yards a second (drawn as the look visual, a [[set_bonus.look]]) and deals where it lands share of the heal as the difficulty had not yet cut it. Optional cap limits it to that share of the hero's maximum health; omitting cap removes the damage limit. No crit of its own, none of the hero's damage bonuses, the enemy's own; one whose enemy dies on the way is lost. Logged as the spell id under the meter row row. Nothing about it changes with the stars. Tests in class_sets/holy.rs.
  • heal_bell (sources, at_full, threshold, cooldown, radii, gap, heal, harm, knock, knock_secs, shield, shield_secs, id, row, icon, slot, empowers, optional crit; the priest's Bell of Redemption 8-piece): the hero's own heals from sources (as heal_sparks counts them, after the difficulty) charge a bell by their whole amount, overhealing too, up to threshold of the maximum health (rounded up); the next counting heal rings it instead of charging it, once cooldown seconds have passed since the last ring (the charge builds meanwhile). The ringing sends one wave for each of radii yards, gap seconds apart, round where the healed hero stood: each heals every living hero within it heal of their maximum health times H and strikes each enemy for harm times that on the priest's maximum health. crit = true uses the hero's global crit chance and multiplier without random damage spread; it defaults to false. No other hero damage bonus or difficulty healing cut applies; the enemy's own bonuses do. The waves knock normal enemies back knock yards in knock_secs. H is the ringing heal as the difficulty had not cut it, over what its spell heals with no bonus (one tick for a heal over time; 1 for a heal with no heal shape), so cards, talents and legendaries count. What a wave heals beyond a hero's missing health is their bell shield (Hero::bell_shield, a shield of its own, not shield): up to shield of their maximum health for shield_secs seconds, every wave that hits them starting the time over, taking damage before every other shield and setting nothing off when it breaks or ends; it is saved with the run (checkpoint 17) and sent in AZSRUN as bsh and bsl (seconds left) while one stands. at_full: the spells of sources that are cast whenever they are ready (a heal over time on the most wounded hero in reach, the hero when nobody is wounded; a group heal on everyone in reach, wounded or not). empowers = true: heal and shield follow the set's strength and {v} and {v2} of the text show them in percent (10 and 50, empowered 15 and 75). id, row log the waves; the charge shows as the aura icon in the aura place slot. Tests in class_sets/holy.rs.
  • needs = "<talent key>" on a [[set_bonus]] makes the whole bonus (its parts and its mechanic) work only in a run whose talents took that talent of the class: Run::take_talents and a checkpoint's rebuild fold only the bonuses that stand (sets::standing), so a loadout the run cut the talent from (too few points: the deepest rows of the smallest tree go first) has no bonus either. The generated AZS_GEN.setBonuses carries needs, and the hero menu's set rows (Armory) show the bonus asleep with the hint "Requires the talent ..." while the active loadout lacks it. The pieces still count.
  • A part is the body of a talent without a tree: effects (stats, as a talent's), mods with mods_v, plays (each with its own v). A set line has several numbers, so a bonus holds several parts. The part's number is its first stat's amount, else mods_v, else its first play's v.
  • Strength p is 1.0, or empower when all eight pieces have empower_stars. The set is then empowered as a whole: the 4-piece's mechanic that empowers grows with it too (the Eternal Grave Harvest's 100%, the Frost Tomb's 6%), while a part of a 4-piece keeps its number. A mechanic that empowers fills {v} (and, for pet_harvest and frozen_graves, {v2}) itself, so no part may show that placeholder. A part's number is number x p; whole rounds a count afterwards; fixed keeps the number (it is written in the text); empowered = <n> is the number when empowered in place of x p (the "every 5th" that becomes "every 4th"). shows = "v" | "v2" is the text placeholder the part fills, percent shows it times 100. At most one part fills each placeholder, and every language's text has a placeholder exactly when a part fills it (the check fails otherwise). A shown number is its size: a malus (mods_v = -0.6 of a damage_times, "60% less damage") shows without its sign. with_set = true on a part of a 4-piece makes it follow its tier's 8-piece: it takes its empowered number (x p, or empowered) when that 8-piece is empowered (all eight pieces at empower_stars), where a 4-piece part otherwise keeps its written number (Illidari's Pride's 4 -> 6 targets and -60% -> -35% damage). It is read where parts are folded (sets::parts). There are no values between (a star count 1 to 4 gives the normal number). The hero menus (Armory, Inspect, Proving Build) show a small bonus that follows its set with the empowered numbers (and no "Empowered" tag): the generated AZS_GEN.setBonuses marks it follows = true (SetBonusDef::follows_set: a part with with_set, or a mechanic that empowers and shows a number that changes; test a_small_bonus_follows_its_set_only_when_it_says_so). Test a_four_piece_part_that_follows_the_set_empowers_with_its_eight_piece.
  • tier is a base tier word or the key of a [[gear_tier]] (its rarity is 6 plus its place among the packs' tiers).
  • The check also refuses an unknown tier, pieces that are neither of the rules', a 4-piece in a class folder or an 8-piece outside one, a second bonus for a tier, a part that does nothing, a spell key the class lacks, and rank_targets (it counts talent ranks).
  • The window shows the 4-piece and 8-piece lines from the generated AZS_GEN.setBonuses, with {v}/{v2} computed in Rust for both strengths (SetBonusDef::shown): Lua never recomputes a number. survivors_sim::sets wakes the sets from the worn pieces and Applied::fold folds their parts into the hero's mods, plays and stats exactly as a talent's, also for a hero with no talent build.
  • Balance: the radii and delays the original's texts do not give (a recast after 0.3 s, 8 yd for a splash, a dot spread or a kill burst) are ours: TUNE.
  • The sets fold when the seat takes its talent build (take_talents): the client sends talents at world entry for every hero, the empty build - for one who spent nothing (Run.lua). A seat whose client never sends it gets its pieces' stats but no set. rebuild_seat (a restore) folds them again from the gear as it is then, so a piece dropped in the run can wake a set in the restored run's mods and plays but not in its stats.
  • follow moves the spell's strikes with the hero (tick_fields); the drawn DynamicObject stays where it was cast (the run has no packet that moves an area). A spell that follows should be one whose look can stand that, or the area needs its own move.
  • The new plays' state (pending recasts, hit_buff stacks, the time last hurt) is transient and not in a checkpoint. kill_trim, kill_cast and hit_buff fire on direct hits, not on a dot tick that kills; splash fires on every hit of a spell, so name single-target spells.

The words a set uses beyond the talents' (each works for any class that writes it, and a sim test names it):

WordMeaning ({v} is the part's number)
mods: followthe spell's ground area moves with the hero (Consecration, Volley, Blizzard)
damage_timesthe spell deals {v} more damage as a factor 1 + {v} that multiplies with every other bonus (damage adds to the talents' shares: 150% more is x2.5)
cooldown_timesthe spell's cooldown is {v} shorter as a factor 1 - {v} that multiplies with every other cut (cooldown adds to the talents' shares: 40% shorter is x0.6)
plays: recast { keys, delay }a cast is cast again delay s later for {v} of its damage
expose { keys, secs }enemies hit take {v} more damage from everything for secs s
hit_buff { keys, secs, cap }each hit gives {v} more damage for secs s, stacking cap times
kill_trim (keys)each kill takes {v} s off the hero's other cooldowns
splash { keys, share, radius, projectile? }a hit also strikes {v} more enemies within radius for share of it; projectile = true shows the spell's missile from the impact to each extra enemy (default false)
dot_spread { keys, radius }an enemy dying under the dot passes it to {v} enemies within radius
hit_rider { keys, rider }a hit has {v} chance to put a rider ({ stun = { secs = 1.0 } }, flee, ...) on its target
kill_cast { keys, spell }a kill casts spell for free, at most once every {v} s

and six stats for the 4-piece (talents.rs stat): 35 pickup range (a share), 36 gold (a share), 40 area of effect (a share), 37 targets (flat extra targets for every spell), 38 calm regeneration (a share of the maximum health a second after 3 s unhurt), 39 crowd armor (a share less damage taken while 5 or more enemies stand within 8 yd; the thresholds belong to the stat).

Spatial set patterns

projectile_pattern, field_pattern and manifest_pattern are reusable spatial mechanics. Their schemas are survivors-content/src/set_patterns/{projectiles,fields,manifestations}.rs; complete examples live in packs/cata/classes/*/set_bonuses.toml. Each writes mechanic = { kind = "...", config = { pattern = "...", ... } }. Unknown fields are rejected; spell keys must belong to the bonus's class, and counts, timings and ranges are validated. Give required spells with start_with parts; a pattern does not silently teach them.

The last active config of each family wins. Write the 4-piece before the 8-piece: the latter replaces that family's runtime config, so it must include the complete baseline and extension. upgraded (projectiles) and empowered (fields) enable their extension; the field flag does not mean five-star empowerment. Manifest variants express extensions with their own fields. All three families keep their stated damage shares fixed at five stars. A share multiplies the named spell's current hit with that hero's upgrades, rather than giving flat damage. Generated hits are proc-safe and do not count recursively as fresh triggering casts.

Distances and line half-widths use simulation yards (metres / 0.9144), speeds yards per second, times seconds, and angles radians. A width reaches that far on either side of a line. Every hero owns their markers, targets, charges and pending hits in multiplayer. Pause freezes motion and deadlines. Expiry, death, set removal and a change between configs clear owned objects and pending effects. Decorative markers do not block heroes or become enemy targets.

Moving objects (projectile_pattern). pattern is shield_flight, beast_paths, returning_blades, blood_orbit or rolling_barrels. They share a flat config; every field is required except optional charger and default-empty melee. Unused fields still satisfy validation; start from a matching shipped example.

FieldsMeaning
spell, damage_spell, finisher, charger, meleeTrigger, damage source, finishing cast, optional charging cast, and melee-wave casts.
upgraded, marker, large_marker, visualExtension flag, ordinary/large { entry, display, scale } actors, and look ID (0 uses the source look).
count, burst_count, cap, charges, overlaps, bounces, restoreOrdinary/burst counts, live cap, activation threshold, allowed overlapping path hits, group bounces, and restored spheres.
distance, width, speed, duration, suspend, orbit, interval, radiusReach, line half-width, speed, lifetime, suspension time, orbit radius, pulse interval, blast radius.
damage, return_damage, finish_damage, ignite_damageOrdinary, return, finishing, ignition spell-hit shares.
push, heal, scale, armorNormal-enemy push distance, maximum-health healing fraction, hero size multiplier, armor percentage points.

Example config (add the bonus's key, tier, pieces, localized text and spell-granting parts):

mechanic = { kind = "projectile_pattern", config = { damage_spell = "shield_slam", pattern = "shield_flight", spell = "shield_slam", finisher = "shockwave", upgraded = false, count = 1, burst_count = 1, cap = 24, charges = 3, overlaps = 1, distance = 20.0, width = 1.5, speed = 16.0, damage = 1.5, return_damage = 1.5, duration = 8.0, suspend = 2.0, orbit = 3.0, interval = 0.75, radius = 8.0, finish_damage = 2.5, push = 3.0, heal = 0.0, restore = 0, scale = 1.6, armor = 30, bounces = 3, ignite_damage = 1.5, visual = 0, melee = ["shield_slam", "mortal_strike", "cleave", "execute", "bloodthirst", "victory_rush", "whirlwind", "bladestorm"], marker = { entry = 990300, display = 90300, scale = 1.5 }, large_marker = { entry = 990301, display = 90304, scale = 2.5 } } }

Persistent fields (field_pattern). Each variant nests a common field table, with all fields required: spell creates the field, activate triggers its extension, and feed supplies heat where used. marker, image, visual, burst_visual select its actor, hero-copy rendering and looks. radius, secs, every, damage, burst set its area, lifetime, pulse interval and ordinary/extension spell-hit shares. empowered enables the 8-piece extension.

patternAdditional required fields
pillarscount caps pillars; width is link half-width and refresh proximity; active_secs is activation duration. Fewer than three pillars use circular hammer areas.
choircount, length, half_angle define emitters/strokes; speed, wave_secs control the wandering wave; picture_delay, picture_radius, picture_limit bound delayed pictures.
sunheat, feed_heat, max_heat, heat_damage, heat_radius set bounded increments and additive damage/radius growth per heat. speed, flight_secs, trail_secs, trail_step, trail_limit bound flight and trail.
trailstep, nodes bound movement samples and flame width; close is revisit distance; min_area is the minimum enclosed area in square simulation yards; cooldown is shared by that owner's eruptions. Valid closure consumes the old path.
mechanic = { kind = "field_pattern", config = { pattern = "pillars", field = { spell = "judgement", activate = "divine_storm", feed = "judgement", marker = { entry = 990350, display = 90315, scale = 0.5 }, image = false, visual = 910350, burst_visual = 910351, radius = 4.0, secs = 18.0, every = 1.0, damage = 0.35, burst = 0.5, empowered = false }, count = 3, width = 1.0, active_secs = 6.0 } }

Manifestations (manifest_pattern). These configs are flat after pattern:

patternRequired fields
forgespell, alternate; markers hammer, blade, anvil; looks lightning, magma; max_waves, range, width, half_angle, offset, share, burst_share, travel, steps, charge, fronts, chains, anvil_secs. Alternating casts charge an anvil; a later cast releases lightning and magma fronts.
celestialspell, alternate, rain; markers sun, moon, wheel, crescent; looks solar_visual, lunar_visual, rain_visual; max_waves, range, width, share, rain_share, travel, steps, phase_casts, orbit, orbit_radius, orbit_period, eclipse_secs, rain_every, rain_radius. Phase casts alternate manifestations; orbit adds a sun/moon encounter and eclipse rain.
afterimagesspell, marker image, visual, count, max_waves, range, width, share, sweep, duration, steps, lifetime. Stationary hero copies sweep beams; later casts wake retained copies together.

max_waves caps pending waves. steps divides a wave/sweep's total share across scheduled hits. travel/duration time that motion, sweep is angular span, and offset places the forge actor. All marker tables use { entry, display, scale }.

mechanic = { kind = "manifest_pattern", config = { pattern = "forge", spell = "stormstrike", alternate = "lava_lash", hammer = { entry = 990400, display = 90310, scale = 1.8 }, blade = { entry = 990401, display = 90311, scale = 0.6 }, anvil = { entry = 990402, display = 90312, scale = 1.2 }, lightning = 910400, magma = 910401, max_waves = 32, range = 14.0, width = 2.5, half_angle = 0.9, offset = 3.0, share = 0.9, burst_share = 1.8, travel = 1.2, steps = 6, charge = 3, fronts = 1, chains = 4, anvil_secs = 8.0 } }

A marker model of its own. [[set_bonus.model]] exposes an existing client model under new display/model IDs. display is the CreatureDisplayInfo ID used by a marker's display; model is its CreatureModelData ID. source is an existing creature display whose render settings and model metadata are copied, not a spell ID. path is a relative client .m2 asset path. Optional textures lists at most three skin names without paths; omit it when the model supplies its own textures. Identical shared recipes are allowed; conflicting recipes for one display/model ID are rejected.

[[set_bonus.model]]
display = 90300
model = 90300
source = 1825
path = "ITEM/ObjectComponents/Shield/Shield_2H_OutlandRaid_D_01.m2"
textures = ["Shield_2H_OutlandRaid_D_01"]

tools/class-spell-vfx.py reads these recipes when building the final patch and writes the display/model DBC rows. Referenced model and texture assets must already exist in the client; a recipe does not create mesh or texture files. Rebuild the patch for model/look changes, and regenerate content copies with azs-content gen; never hand-edit generated copies.

Gear pieces

A piece of gear adds its slot's own stats plus a class profile, scaled by its tier and its stars (re/NUMBERS.md 14.7; survivors-content/src/pieces.rs piece_bonus is the one function that computes it, the hero menu reads the same tables from AZS_GEN.pieces):

value = (slot stat x slot[tier] + profile stat x profile[tier]) x factor x (1 + star gain)

  • packs/base/gear/pieces.toml: [[piece_slot]] (the armor slots 0 to 7 and the weapons' 8 main hand, 9 off hand, 10 ranged, with profile = false for the weapons) and [[piece_profile]] (eight pairs of stats). A stat is { hp = 12.0 }: damage cooldown hp crit crit_damage speed armor regen pickup gold area; shares are fractions (0.012 is 1.2%), health and regen are flat.
  • packs/base/gear/piece_scale.toml (key = "scale"): factor, then per rarity (Common to PvP) slot, profile, star_step and star_last; each star up to steps adds star_step, the top star adds star_last on top. A rarity past the end of a list takes its last number. lore_rarity is the least rarity whose pieces tell their class's own flavor line.
  • A class's class.toml has piece_profiles = [3, 4, 5, 6, 7, 0, 1, 2]: the profile in each armor slot, head to hands. A class wears each of the eight once (the original's (class id x 3 + slot) mod 8; a new class picks its own).
  • gear/piece_lore.toml (plain_<profile>) is the flavor line Common to Rare pieces show, classes/<class>/piece_lore.toml (<class>_<profile>) the class's own for Epic and better. A class without lore shows the plain line.
  • Health rounds to a whole number once per piece; stats that come to nothing are left out. Nothing is saved: the values are computed from the piece's id and stars, so a change reaches every hero. The run sums the pieces before it rounds, and flat regeneration keeps its tenths (GearBonus::add_to), as the jewelry's does.
  • survivors_sim::gear::sources answers "DROPS FROM" (the zones whose rarity table holds the piece's rarity, their bosses whose drops list it); the hero menu asks gear sources <id>.
  • In a run the character window (Inspect.lua) shows the pieces worn, their stars and the numbers piece_bonus gives them, as the server's AZSARMOR line tells them (HeroSeat::armor_list), and wakes the sets from that line by set_rules and the set_bonus entries, as the hero menu does.

A jewel (ring or trinket), an amulet, a legend

packs/<pack>/jewelry/jewels.toml (base) or packs/<pack>/jewelry.toml:

[[jewel]]
key = "accuria"
slot = "ring"             # or "trinket"
behavior = "damage"       # survivors-content jewelry.rs `Behavior`
base = 0.17               # its worth B
growth = "a"              # the growth rule (re/NUMBERS.md 17.2)
icon = "INV_Jewelry_Ring_15"
name = { en = "Band of Accuria", de = "Band von Accuria" }
  • A cache's offer draws from this list in order: a new jewel moves the golden runs.
  • buff_spell = <3.3.5a spell id> optionally names the player-frame aura of an active jewel proc. Timed TBC behaviors use their current duration and stack count; a generic behavior = "proc" also accepts it and otherwise uses proc.spell. An omitted value gives no additional aura for legacy behaviors. Permanent bonuses and enemy debuffs do not become player buffs. The id must be positive when set.
  • upgrade_base optionally gives subsequent picks their own base strength; the first still uses base. Combine growth = "a", an explicit ceiling, offered_below = <ceiling> and max_picks to keep several useful upgrades after a high-rarity first pick.
  • proc_scaling = { cap = 0.5 } optionally caps a timed proc's effective strength. Above that raw worth, its repeat interval is divided by worth / cap, stopping at the buff duration. The same rule drives runtime and tooltips. It works for generic proc entries and the timed Dragonspine, Tsunami, Hourglass, Skull, Brooch, Greatness and Phylactery behaviors. Use it with a positive repeat interval; it does not make a stacking proc or a permanent stat repeat. The ceiling must leave useful uptime room. Other pieces keep their existing behavior.
  • A Mote of Anger piece's worth is its average motes per hitting cast: a fractional mote is a chance of one additional mote, so worth above one remains useful. Motes still arm only one additional spell and proc strikes do not generate more motes.
  • group = "sustain" (optional, on a ring or trinket) names a family of which a hero wears one piece per slot: while a ring or trinket of the group is worn, no other new piece of it is offered for that slot, only the worn one to grow, and the other slot keeps its own. The packs put their health and healing pieces (max health, regen, lifesteal, health per kill, lives) in sustain. A new family needs no code, just the name on its members; an empty name fails azs-content check. Amulets are worn one at a time already and take no group. Tests a_group_names_a_family_of_pieces (survivors-content) and a_group_allows_one_piece_per_slot (survivors-sim).
  • Amulets are [[amulet]] in amulets.toml (rarity, growth, effects = [["damage", 0.15]]), legendaries legends.toml. A piece that procs on hits or kills needs its family's code in game/procs.rs or game/{tbc,wotlk}_jewelry.rs (see "A behaviour"), unless the generic proc below says what it does.
  • A spell's legendary is found by the spell, never listed per spell. A [[legend]] with spell = "<key>" is AS's own for that spell and wins; every other spell takes the one [[legend]] with form = "<form>" that its shape gives (survivors-content jewelry.rs: legend_form, then legend_of; the sim's legend_for calls the same). A strike is a bolt (range over 10 yd, MELEE_REACH) or a melee blow; missiles, nova, ground, chain, dot, execute and cone are their shapes; a heal over time, fury, haste, thorns and empower are lasting; a shield, a sphere and a heal with secs = 0 are instant; immune; totem for totems and orbits; summon for summons and commands. A passive, a bond and a spell with legendary = false have none. Every form has exactly one generic entry (azs-content check fails otherwise), so a new spell needs no legend entry when its shape fits, and a new Shape variant must be given its form in legend_form. The amulet's id in the game is legendary:<spell key> whichever entry gives it, and a hero is offered it once they know the spell. The public legends.json (/data/v1/, written by azs-content gen) lists the result, one record per spell; test legend_records_resolve_every_spell_the_way_the_game_does. It and amulets.json also publish each piece's numbers at rank 1 (the pack's own words as JSON) and growth; LEGEND_GROWTH is survivors_content::jewelry's, the sim reads it from there.
  • The stat caps (cooldown reduction, crit, damage reduction, echo, haste) are defined once, in survivors-content/src/caps.rs: the sim's CRIT_CAP_PCT, CAP_PCT, COOLDOWN_FLOOR_PCT, ECHO_CAP and HASTE_CAP_PCT take their values from it, AZSCAPS tells them to addons and caps.json publishes them. A talent that raises one writes { stat = [id, share] }; the cap's raised_by names that stat id and caps.json lists the talents by it (red: Titan). A new cap is a new Cap in caps::ALL, and the AZSCAPS line and AZS_CAPS need it too. Test cap_records_are_the_constants_and_name_what_raises_them.
  • One limit that is not a stat lives in caps.rs too: GROUND_AREAS_PER_SPELL (48), how many ground areas of one spell a hero keeps standing at once (the sim's FIELDS_PER_SPELL, Run::retire_field in game/combat.rs). Cards multiply a ground spell's seconds and yards without end, so an endless run would lay an area with every cast and keep each of them, and each strikes everything in reach on every beat. Past the cap, laying a new area takes down the one that fades soonest (with what the spell lays, a trap) and the new area carries the hit that one still had to deal, its hit by the share of the new area's seconds it had left: the damage over the run stays the same, one strike carries what several would have, and the work stops growing. It is not in caps::ALL, so AZSCAPS and caps.json do not tell it. Tests a_ground_spell_keeps_a_bounded_number_of_areas_and_all_its_damage and the_area_that_fades_soonest_hands_on_the_damage_it_has_left. Totems and the traps of a dash are not covered: the totems take the same duration() and would need the same rule.
  • A proc of the piece's own numbers (Cataclysm's pieces) is behavior = "proc" with a proc:
    behavior = "proc"
    proc = { on = "crit", chance = 0.25, stat = "crit_damage", lasts = 10.0, every = 30.0, spell = 16166 }
    

    on is what sets it off: hit (an own spell's hit, not a tick), crit, cast (not its echoes) or itself (it uses itself every every seconds, the first at once). With chance (0.01..1, 1 when left out) it raises stat (damage, cooldown, crit, crit_damage) by the piece's worth for lasts seconds and then rests every seconds (0 when left out). With stacks above 1 each trigger adds a stack while they hold, each worth the worth. spell is shown on the hero as it sets off anew (0: none). Damage and cooldowns share the WotLK and TBC procs' caps. The card text is made from these numbers in every language; no code per piece. Its buffs fall off at a host handover. Tests: a_pack_proc_loads_and_is_checked (survivors-content), every_pack_proc_piece_is_worded_and_grows, a_procs_card_says_what_sets_it_off_and_what_it_gives, the_pack_procs_buffs_hold, a_pack_proc_raises_its_stat_while_it_holds and a_pack_proc_rests_after_it_set_off (survivors-sim).

A zone

packs/<pack>/zones/<zone>.toml:

[[zone]]
key = "elwynn"
order = 0                 # the menu's order
name = { en = "Elwynn Forest", de = "Wald von Elwynn" }
subtitle = { en = "...", de = "..." }
icon = "Achievement_Zone_ElwynnForest"
map = 0
map_name = "Azeroth"
area = 12
center = [-9530.0, 40.0]
radius = 100.0
# spawn = [-9520.0, 52.0]  # optional: where the heroes enter, inside `radius`; left out, at `center`
map_bounds = [1535.4166, -1935.4166, -7939.583, -10254.166]   # left, right, top, bottom of the rect the client reads the hero's map position against (see below)
health_factor = 0.82
late_factor = 0.0
gold_factor = 1.0   # optional: the banked gold of a run here, times it (coins and gold paid outright); later zones pay more, a win stays under a shop piece
hour = 10
water = { swim_speed_factor = 1.45, unlimited_breath = true } # optional; defaults to stock swim speeds
#                         # swim_speed_factor applies to heroes and swimming enemies alike.
#                         # unlimited_breath also says the zone is played under water: its deep water
#                         # is standing room (a lair, chest or portal may stand on the sea floor).
#                         # Any other zone sets nothing down in deep water (Terrain::deep_water).
#                         # Enemies in deep water swim after a hero who dives, to the hero's depth,
#                         # in every zone (Terrain::chase_toward); nothing is set in the zone for it.
weather = { fine = 85, rain = 15 }   # optional weights: fine, rain, snow, sand, storm; none = clear
# floor = 141.3           # optional: the arena stands on a WMO floor at this height, and cells
#                         # without a floor face are blocked (Naxxramas, Scarlet Monastery)
# gear_rarity = "uncommon" # optional: the rarity its bosses drop in place of its pair's (see
#                          # "A gear tier"); each expansion's first pair drops Uncommon, not Common
# [zone.menu_view]        # optional: the hero menu's 3D map preview of this zone, a whole
#                         # view (see "The hero menu's look"); the Menu Designer writes it

[[zone.enemy]]
entry = 600
name = { en = "Kobold Vermin", de = "Koboldungeziefer" }
type = "humanoid"
display = 26              # CreatureDisplayInfo
health = 24
damage = 3
swing = 1.6
speed = 5.0
cost = 1.0                # the wave director's budget
from = 0.0                # the minute it starts to come

[[zone.boss]]
icon = "INV_Misc_Head_Kobold_01"   # optional: its tile in the hero menu's Codex (below); left out, its rank's skull
entry = 690
name = { en = "Hogger", de = "Hogger" }
type = "humanoid"
display = 384
health = 3600
damage = 22
speed = 5.6
size = 3.0                # optional: its model's scale (an enemy's 1.0, a boss's 3.0 when left out)
body_radius = 1.5         # optional: its body's radius in yards (below); left out, half its size
minute = 3
yell = { en = "...", de = "..." }
kit = "hogger"            # its boss kit (below)

body_radius (on an enemy, an elite or a boss) is how far from its centre a hit or a swing ends: a hero's spell reaches an enemy when its distance to the enemy's centre, less this radius, is within the spell's reach, and the enemy's own swings reach the hero by the same measure. Left out it is half the scale (size), which suits a model of ordinary build; a huge model that is scaled down to fit the arena (Yogg-Saron) writes its own, so the melee heroes still reach it at the edge they see. A radius is 0.1 to 20 yards. The tests a_zone_and_its_bosss_kit_load and a_body_radius_of_a_boss_is_a_few_yards_at_most (survivors-content) name it.

role (on a normal enemy, one line in its [[zone.enemy]]) gives it a part beside walking up and swinging:

role = { ranged = { spell = 9613, range = 18.0, every = 3.5, speed = 24.0, radius = 1.6, factor = 0.8 } }
role = { exploder = { spell = 9874, burst = 7670, reach = 3.0, radius = 5.0, fuse = 1.6, factor = 4.0 } }
  • ranged: it stops range yards off a hero it sees (round a wall it walks up as a swinger does) and throws spell every every seconds instead of swinging: a missile to the spot the hero stood on (from Heroic I a little ahead of their run), marked radius round it until it lands, striking there for factor times its swing. speed is the spell's Spell.dbc missile speed (field 47): the client flies the missile at that speed, so the strike lands with it. A thrower slain before its missile lands strikes no one.
  • exploder: within reach of a hero it stops and casts spell on itself for fuse seconds (shortened as a boss's warning is), radius round it marked; then it bursts with burst for factor times its swing on every hero in the mark and falls, no one's kill (no experience, no loot). Slain before, it does not burst. Keep reach under radius, and give the role to an enemy that comes from minute 2 on, so the first waves are not all fuses.
  • An elite takes no role. Tests: an_enemy_role_and_an_elite_guardian_kit_load_and_are_checked (survivors-content), a_thrower_stands_off_and_its_marked_throw_can_be_dodged and an_exploder_lights_its_fuse_bursts_and_falls_unless_slain_first (survivors-sim).

An elite's [[zone.elite.kit]] entries (a boss kit's words and numbers, "A boss kit" below) are what it fights with once it holds a lair as its guardian: awake, and with a hero within the mode's lairs.ability_reach, it uses each on its every; with no hero near it starts its kit over when one comes back. Its hits are factor times the guardian's own swing, which already outhits a boss of the same minute (the mode's lairs.hit_factor over the elite's, lairs.health_factor for its health), so a guardian's factors run about half a boss's. A normal enemy takes no kit. Test: a_guardian_fights_with_its_elites_kit_once_awake_and_near (survivors-sim).

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

icon = "INV_Misc_Head_Gnoll_01" # as an enemy's map_bounds is not any rect that holds the arena: the minimap's pins (caches, guardians, pings, rifts, friends) are placed by the fraction of it the run sends, against the fraction the client's own GetPlayerMapPosition gives for the hero, so it has to be the WorldMapArea row the client shows there. Outdoors that is the top zone of the ground under the centre, which is not always the zone the pack is named for (Karazhan's arena stands in Darkshire, so it carries Duskwood's rect). In an instance it is the DungeonMap floor the WMO group under the arena draws on (DungeonMapChunk: Naxxramas's floor 6 for Kel'Thuzad's chamber, the Scarlet Monastery's floor 1 for the Graveyard), else the floor a WorldMapTransforms row names, else the instance's one WorldMapArea sheet. The test every_zones_map_bounds_are_the_rect_the_client_reads_its_position_against (benilla-app, needs WOW_DATA) checks every zone against the client, with the WMO group under its centre.

  • spawn (a zone, and each [[zone.arena]]) is the spot the heroes enter that arena at: a finite (x, y) no farther than the arena's radius from its center. The arena's edge, rings and waves stay round center; only the entry moves (Run::entry_point). The zone's spawn is for its own arena, a later arena names its own and without one is entered at its centre. Pick it on open ground: every_zone_stands (ignored, needs WOW_DATA) checks a zone's own spawn for standing room; a later arena's spawn is not checked yet. Tests: a_zone_with_a_spawn_seats_the_hero_there, heroes_enter_a_later_arena_at_its_spawn, and the content crate's a_zone_spawn_must_lie_inside_its_radius.
  • The ground: the server reads the arena's ground from the install's ADT tiles (terrain.rs). With WOW_DATA set, run cargo test -p survivors-sim every_zone_stands -- --ignored and every_zone_has_open -- --ignored; find_flat_ground and scout_the_ground (stages.rs) help pick a centre. A zone of several arenas lists its stages (stages.rs, passage.rs).
  • climb = 45.0 (a zone, optional, 20 to 80) is the steepest slope in degrees a hero walks up. The navmesh is baked from AzerothCore's mmaps, whose creatures walk up to 70°, while the client's hero stops at 50 (GROUND_COS in benilla-app player/state.rs), so on a mountainous zone it reaches hilltops and ledges whose only way up is a slope the hero cannot take, and a rift crystal, the rift portal, a chest, an elite or a boss could be set down there. Written, the zone's standing room (Terrain::standing_room) is the ground a walker who climbs no steeper reaches from the arena's centre (NavMesh::climbing: the steps onto a poly whose detail surface leans over the limit and climbs more than a yard are cut; a lower lip is a curb). Only where things are set down changes: the ground's heights, the walls and the way the enemies chase stay the navmesh's, so enemies still climb the hills. Left out, every place the navmesh reaches counts. Measure a zone's mesh before writing it: the stairs and thresholds of a building's arena are steeper than 50° on the mesh and a hero takes them (Gurubashi's pit would lose three quarters of its ground), while on open hills it costs a few percent of the ground and takes the unclimbable hilltops out. The client stops at 50° on any one face, but the mesh smooths rough ground, so write a few degrees under it: Terokkar Forest writes 45 (a report: a rift crystal and its portal on a hill with no way up; at 50 the highest ridge, 85 yd over the arena's floor, stayed reached, at 45 only ground up to 43 yd over it does). The mesh's numbers for a zone: py -I over data/dl/NAVMESH/AZS/Navmesh/<zone>-0.nav (the file is AZNV, navmesh.rs), flooding the polys from the centre without the steep ones. Tests: a_zone_may_limit_the_climb_and_it_is_checked (survivors-content), a_climbing_walker_stops_below_a_steep_ramp_but_steps_over_a_curb (navmesh.rs) and a_zones_climb_takes_a_hilltop_behind_a_steep_ramp_out_of_standing_room (terrain.rs).
  • An arena stands on open ground. The navmesh holds every floor there is, the one under a terrace or a platform too, and the run seats the heroes on the floor a walker reaches most of the mesh from, so a centre picked off the ADT chunks alone can land under a building and the hero sees the map from below (Shadowmoon's Ata'mal Terrace and Black Temple did). After a centre moves: find_open_ground (terrain.rs, OPEN_SCAN=<zone>,<x>,<y>,<span>,<radius>, OPEN_AREA, OPEN_FLAT) ranks the ground round a spot by the standing room with no building over it; rebake the navmeshes (builder navmesh, tools/patches.toml); and run navmesh_floors_stand_on_what_the_client_has, which fails an arena with more than a quarter of its standing spots under a building. indoors = true on a [[zone.arena]] says the arena lies inside one (Icecrown Citadel's halls) and lets it off.
  • An arena on a platform of a building high over the map's ground (the Frozen Throne, atop Icecrown Citadel's spire, 1,000 yd over the valley; Illidan's platform atop the Black Temple's facade) writes floor = <height> on its [[zone.arena]], as a zone's own floor does for Naxxramas: the arena stands on the building's faces near that height, the navmesh's walks start from the floor at the centre nearest it (the ADT ground under the spire would reach more of the mesh than the platform), and the void past the platform is blocked. The battlefield does not widen on a platform (its edge stays at the arena's radius, and the widening of the arenas before stays behind), and no Fel Reaver comes up onto it. Pick the centre and radius off the navmesh's floor at that height (the platform's polygons in data/acore/mmaps), the centre on the floor itself and the radius inside the platform's parapets or stairs; then rebake the navmeshes. A navmesh baked for another centre than the pack's is ignored, with a line in the server's log, until it is rebaked. On a floor the building's face is the ground: a navmesh floor 4 yd or more under it is the terrain under the building (Naxxramas's placeholder tiles lie under every hall), so things are seated on the face there and nothing is placed on it. A hero who drops 6 yd within a second to more than 12 yd under the floor of the arena they stand in, or goes 36 yd under it at all, fell off the platform or into a pit in it, whatever firm floor the navmesh holds down there (the temple's inner floor lies 60 yd under Illidan's platform): they are brought back to where they last stood, as for a fall through the map (Run::catch_fall, test a_hero_far_under_a_platform_floor_has_fallen_whatever_floor_lies_there).
  • A zone on a small terrain plateau writes platform = true on [[zone]]. Its starting arena keeps its original radius, and falls below its centre height use the same recovery as a raised floor. Hop arenas use their centre height too when no explicit floor is set. This does not flatten or filter the terrain (a_zones_platform_keeps_its_edge_and_recovers_falls, a_hop_recovers_a_hero_on_the_abyss_floor).
  • A hop arena (hop = true on a [[zone.arena]]) is a platform the fight moves on to: Dragon Soul's shattered platforms of the Maelstrom. It takes no from_boss, choice, floor or indoors, a radius of 15 yd or more, and stands after the zone's normal arenas in the list. No portal ever offers it: it is reached only by a boss phase with carry, one hop per carrying phase in list order. It holds no bosses of its own, the battlefield does not widen there and no Fel Reaver comes up; the old horde stays behind, a new one comes after the arrival calm, and the boss and the companions come along. A zone's hop arenas equal the carrying phases of its boss (the check fails otherwise). A zone with hop arenas takes no choice arena (a choice before a hop would never reach it; the check fails). The tests a_hop_arena_and_a_carrying_phase_load_and_are_checked, a_zones_hop_arenas_match_its_carrying_phases, a_normal_arena_still_needs_its_from_bosssurvivors-content, hop_arenas_are_no_part_of_the_portal_chain, a_choice_never_offers_a_hop_arena survivors-sim stages.rs, a_portal_never_opens_to_a_hop_arena, a_hop_does_not_widen_the_battlefield and go_on_resets_the_carried_bosses_timers survivors-sim passage.rs cover it.
  • The browser build ships only the tiles its arenas stand on (the shipped terrain tile rule, azs-host arena_tiles.rs): check ship.cmd -Web after adding a zone.
  • web/content.gen.js (the Worker's zone table) is generated; the Worker needs a deploy before the boards take runs of the new zone.
  • The web export picks the zone's models from the sources (scripts/web-zones.js).
  • order is also the zone's index for gear piece ids, Heroic tiers and talent experience (gear.rs, heroic.rs): never renumber an existing zone.

A zone's own trouble: tide, eruptions, portal, vortex

Besides the expansions' trouble the code gives Outland and Northrend (Legion portals, the Fel Reaver, the risen dead, the cold; game/worlds.rs), any zone may write two of its own. Cataclysm's zones do: Firelands' lava, Vashj'ir's current, Uldum's sandstorm, Deepholm's crystal faults.

[zone.tide]          # ground that floods in from the arena's rim
first = 100.0        # run clock (s) of the first tide's warning
every = 80.0         # seconds from one tide's end to the next one's warning
warn = 4.0           # seconds the ground it will reach is marked first (1.5..15)
rise = 12.0          # seconds from the rim to its deepest
stand = 8.0          # seconds it stands there
ebb = 6.0            # seconds back to the rim
reach = 0.45         # how deep: a share of the radius, from the rim in (0.1..0.7; the middle stays dry)
tick = 1.0           # seconds between two hits on a hero in it
hit = 0.06           # each hit's share of the hero's most health
spell = 905183       # the hit's spell (the log names it) and the visual along its front
flare = 2.0          # seconds between two visuals along the front (0: none)
color = "ff5a14"     # the ground's colour, rrggbb
say = { en = "The lava rises! Keep to the middle!", de = "..." }   # the banner as it is marked

[zone.eruptions]     # ground that bursts open near the hero
first = 45.0         # run clock (s) of the first
every = 20.0         # seconds between two
count = 3            # how many at once (1..12)
spread = 9.0         # how far round the hero (1..40 yd)
radius = 4.0
warn = 2.5           # seconds each is marked before it bursts (1.5..10)
hit = 0.08           # the burst's share of the hero's most health
spell = 905182       # the burst's visual (and the log's name for every hit)
knock = 0.0          # optional: yards the burst throws a hero off
lasts = 6.0          # optional: seconds the ground burns on after the burst (needs `burn`)
tick = 1.0           # optional, 1.0: seconds between two hits of the burning ground
burn = 0.03          # optional: each of those hits' share of the hero's most health
color = "ff5a14"
say = { en = "The ground erupts!", de = "..." }   # the banner as the first ones are marked
  • Neither begins while a boss fights (a tide that is up rises, stands and ebbs on), and both are marked on the ground in their color before they strike: a tide first shows the whole ground it will reach, from its deepest out past the edge, then floods in from the rim. Hits are shares of the hero's most health, so they scale with the run; Heroic shortens the warnings and hardens the hits as it does a boss's ground.
  • The ground belongs to no unit (the run's WORLD): its visuals play with no caster, so pick a spell whose visual is a ground impact kit (Cataclysm's 905xxx impacts, Lava Burst, ...).
  • A tide that is up is not kept through a host handover; its next one is (checkpoint 14).
  • The client draws a wide mark's projection taller (a fifth of its radius above and below its point), so a tide climbs an arena's slopes.
  • Tests: a_tide_and_eruptions_load_and_are_checked (survivors-content), a_tides_front_comes_in_stands_and_goes_back, a_tide_floods_in_from_the_rim_stands_and_ebbs and eruptions_burst_near_the_hero_and_burn_on (survivors-sim).

Three more a zone may write: the rift portal's look, a portal of its own, and a vortex.

rift_portal = { sealed = 8939, open = 8639, scale = 0.8 }   # GameObjectDisplayInfo ids; scale 1 when left out

[zone.portal]        # tears open away from the heroes and lets enemies through until destroyed
entry = 701301       # its own creature entry (and its look's object entry)
name = { en = "Flame Portal", de = "Flammenportal" }
display = 11686      # the creature struck (an Invisible Stalker under its look)
size = 1.0           # optional
look = 8639          # optional: a GameObjectDisplayInfo id drawn at its spot (a portal model no creature wears)
look_scale = 0.8     # optional, 1.0
health = 650         # an elite's, before the zone's factor
first = 70.0         # run clock of the first
every = 75.0         # seconds between two
spawns = [700190, 700191]   # this zone's enemies it lets through (one every 4 sec, 12 at most)
say = { en = "A flame portal tears open! ..." }
closed = { en = "The flame portal gutters out!" }

[zone.vortex]        # roams after the hero and grinds up heroes and horde alike
entry = 701311
name = { en = "Sand Vortex", de = "Sandwirbel" }
display = 20211      # SandVortex.mdx
size = 1.4           # optional
first = 120.0
every = 100.0        # seconds from one's end to the next
lasts = 25.0
speed = 3.5          # yards a second, under a hero's 7 (0.5..6): it can be led
radius = 6.0
tick = 0.5
hit = 0.03           # a hero's most health a tick
grind = 0.06         # a normal enemy's or elite's most health a tick; bosses and guardians are spared
spell = 905133       # the visual and the log's and meter's name of its hits
color = "e8c066"
say = { en = "A sand vortex rises! It grinds up all it touches: lead the horde into it!" }
  • The portal works as Outland's Legion portal (game/worlds.rs): it opens 26 to 34 yd from the hero while no boss fights, lets its spawns through (those whose from minute has come, else any of them), closes by itself after twelve, and destroyed pays a gold pile. Its look goes with it; a portal carried through a host handover stands on without its look.
  • The vortex forms for 2 sec with its ground marked, then steps after the hero once a second. Its grind is a proc of the hero's: what it slays gives experience and loot, and the meter has a row for it. It is new with Cataclysm: lead the horde through it.
  • Tests: a_rift_look_a_portal_and_a_vortex_load_and_are_checked (survivors-content), a_zone_portal_opens_under_its_look_lets_its_spawns_through_and_pays and a_vortex_roams_after_the_hero_and_grinds_the_horde_but_spares_bosses (survivors-sim).

A zone's sites

A zone lists spots of its arenas a dungeon run works with, one [[zone.site]] each. arena 0 is the zone's own arena, k the k-th [[zone.arena]] (never a hop one); at lies inside it.

[[zone.site]]            # a door that blocks a disc until its key is won
arena = 1
kind = "door"
at = [-9230.0, 40.0]
radius = 4.0             # the blocking disc, yards
along = 90.0             # heading, degrees
display = 12345          # GameObjectDisplayInfo id
key = "a"

[[zone.site]]            # the elite or boss that drops the key
arena = 1
kind = "key_boss"
at = [-9200.0, 60.0]
entry = 609              # an elite or boss of the zone
key = "a"

[[zone.site]]            # a chest; with a key, in the pocket that key's door gates
arena = 1
kind = "chest"
at = [-9235.0, 44.0]
key = "a"

[[zone.site]]            # a trap: strikes with `spell` when a hero steps within `radius`
arena = 1
kind = "trap"
at = [-9210.0, 30.0]
radius = 3.0
spell = 905150

[[zone.site]]            # rocks fall within `radius`
arena = 1
kind = "rockfall"
at = [-9250.0, 20.0]
radius = 8.0
FieldMeaning
radiusa door's blocking disc, a trap's trigger, a rockfall's region, in yards (0.5 to 60; default 1)
alonga door's heading in degrees: the way one walks through the doorway (the door object faces it; the jambs stand across it)
displaya door's GameObject display (needed)
entrya key boss's creature entry (needed)
spella trap's strike visual (needed)
keydoor: the key that opens it (needed); key boss: the key it drops (needed); chest: the key whose door gates its pocket, none = free-standing

Pairing, per arena: a door's key is dropped by a key boss of the same arena, and a chest's key is a door's of the same arena. A key has at most one door per arena (its chests stand in that door's pocket) but may have several key boss sites, of which a run picks one. A key is made of a-z, 0-9 and _ (it is a field of the AZSKEYS line), and along is a finite number. Tests: a_zone_site_loads_and_is_checked, a_door_and_a_key_boss_pair_by_key.

In a dungeon run a picked door stands shut from the moment the heroes come into its arena: its display as a solid GameObject turned to along (the client collides with it), and its disc (at, radius) blocks the server's ground checks: where enemies walk and are led, where anything is set down, dashes and pets. A hero inside the disc is thrown out of it along along, to the side they stand on, never into a jamb. When its key is won the object and the disc are gone. Tests: a_blocker_blocks_walkable_line_clear_and_the_chase_field, a_closed_door_blocks_enemies_and_placements, an_opened_door_removes_its_object_and_its_blocker, a_hero_inside_a_door_is_pushed_out, a_hero_off_the_axis_is_pushed_through_the_doorway_not_into_the_jamb, a_door_object_is_solid_on_the_wire_and_a_chest_still_passable.

To find the spots, run the scout over an arena's navmesh (py -I tools/dungeon-sites.py --nav <zone-arena.nav> --arena N, see its docstring): it proposes doorways, chest nooks, trap tiles and rockfall regions as paste-ready snippets. It works on the arena's own floor only, chosen as the run chooses it (of the stacked polygons under the arena's centre the one whose walk reaches the most of the mesh, then every polygon reached from it without a long way round), and prints that floor's height in its header: a mesh with stacked floors (Icecrown Citadel) no longer offers spots on a floor over or under the arena's. Pass --radius the arena's radius. The scout sees only the navmesh, so a neck it finds there (a slope, not walls) may gate nothing on the run's walk grid: the ignored test sites_stand_and_pockets_seal (needs WOW_DATA) is the judge. It checks every site has standing room, every key boss is reachable, a door's disc cuts its key's chests off, and Icecrown Citadel's arenas 1 to 3 hold at least 3 sites each.

A zone's loading screen

On the way into a zone the loading screen wears the zone's own dress: its picture, its name and subtitle in the menu's language, and a hint about the game. Nothing of it is in the zone's TOML: a zone takes part by having a picture under its key.

  • The picture. tools/loading-paintings.sh paints data/dl/LOADING-SCREENS/<key>.png (one paint line a zone: its light, said from the zone's hour and its sky, and its place alone, with no hero and no creature; the look is the script's STYLE and the same for every zone). python tools/loading-screens-patch.py cuts each to 16:9, encodes it as Interface\AzerothSurvivors\Loading\<key>.blp (2048x1024, about 1.4 MiB) and packs patch-1.MPQ; then node tools/build-patches.js files 1 gives the archive's new files entry for tools/patches.toml. A zone without a picture keeps its map's stock art under the same words. Paint with the lower quarter dark and calm: the words and the bar stand there.
  • The words. The menu hands them over at the world entry (SurvivorsLoading.lua, AZS_LoadingScreen(art, title, subtitle, tip)). The hints are that file's HINTS, general ones about the game, the English line as the key; a new hint is a line there and its translation in the eleven SurvivorsLocale_<locale>_Loading.lua (py -I tools/tests/loading-screen.py checks them, no build).
  • The bar. tools/loading-screens-patch.py puts it together and packs it over the stock client's two files (Interface\Glues\LoadingBar\Loading-BarBorder.blp, Loading-BarFill.blp), so every bar that names them wears it. It is AzeriteUI's cast bar, the run's interface (ui/AddOns/AzerothSurvivorsUI/Assets: cast_back.tga the steel case, cast_bar.tga the crystal in Colors.normal), placed as AzeriteUI's own layout places them (Layouts/Data/PlayerCastBar.lua); the pointed ends keep their shape. The client draws the frame over the fill, as it draws the stock bar: the crystal's shape is cut out of the case, and the fill is the whole crystal, squeezed to the progress. --preview <folder> writes the two pictures as PNGs and packs nothing.
  • The spark and the vignette. The loading screen draws both itself (loading_screen.rs: spark_alpha, vignette_alpha): a spark on the fill's tip, and a darkening of the picture toward its edges and under the words. output/loading-mock/ shows them with the same formulas.
  • The sound. SurvivorsLoading.lua's SOUND is the sound kit (a name of SoundEntries.dbc) an entry sounds once: the world entry's own click (gsCharacterSelectionEnterWorld) and nothing else. The stock Enter button plays that kit itself, so the file only notes it there and sounds it for the entries that go round the button (a hub's host, a replay); "" leaves the stock click alone and adds none. A loop would stutter under the load's long frames, so it is one sound that plays out.
  • The hero menu. With the 3D map preview off (azsMenuMapPreview other than "1", which is the default; the Game Menu's Background button and the Video window's 3D Map Preview box switch it) the select screen shows the same picture behind the heroes (AZS.ScreenBackdrop in SurvivorsGlue.lua), for every zone whose picture is in the archives: SetTexture answers whether the file is there, so a zone without one keeps the stock stage (py -I tools/tests/screen-backdrop.py, no build). The browser has no 3D preview and always shows the picture; it hides the stock stage in glue_booth::sync_screen_backdrop, where the desktop does it in map_preview::sync.
  • The picture's life. On the desktop the hero menu's picture moves (SurvivorsScreenLife.lua): it swells slowly in and out, and the zone's lines in that file's LIFE table (by the zone's key) put pieces over it and under the heroes: smoke from a chimney, mist drifting through a valley, a flickering light or a lit window, sunbeam rays that breathe, lightning that flashes now and then, and motes (dust, fireflies, embers, snow, ash, wisps, water glints, rain; a motes line with stretch draws long specks turned along their way). A line is { kind, x, y, field = value }: x, y (and an area's w, h) are fractions of the 16:9 picture, every size and distance is in picture heights, and a field the line leaves out is its kind's (KINDS). The lines are placed by looking at the painting, so a repainted picture needs its lines placed again; a zone without lines only swells. The pieces are five small textures, Interface\AzerothSurvivors\Life\*.blp in patch-5.MPQ, drawn by py -I tools/screen-life-art.py (never pack while the game runs; a missing piece draws nothing). py -I tools/screen-life-preview.py <key> renders the picture with its life into output/screen-life/<key>.mp4 from the same Lua file (--still 6 9 for frames, --lua <copy> for a copy being placed); py -I tools/tests/screen-life.py checks every zone's lines, the crop on three screen shapes, and that no piece jumps while it can be seen. No build.
  • The site. The campaign on azreborn.com's home page shows the same picture for the zone. python tools/site-zone-art.py writes it as site/app/assets/zone-art/<key>.webp (1600 pixels wide) and <key>-800.webp (phones), which are committed; the page finds them by file name (site/app/utils/zoneArt.ts), and a zone without one keeps its expansion's artwork there.

A user map

A user map is one file, not a pack: a [[zone]] table that says where a map lies and whose monsters it borrows, beside recipe tables that change the world there (docs/PLAN-EDITOR.md). It stays off the hero menu's zone list and the boards. In this phase the dev route is a hub mode: put AZS_MAP=<file> and AZS_MODE=<mode file> in the environment of the game (its in-process server and its client both read them). The mode file is two lines of TOML: extends = "hub" and [hub] with place = "<key>". The hero menu's HUBS window cannot open a user map: the Worker refuses a place it does not know ("Unknown place.").

The game and the Community Maps worker read the modes and scenario limits from engine/benilla/web/community-map-rules.json. Keep the shared acceptance fixtures in engine/benilla/web/test/fixtures/maps current when changing those rules.

[[zone]]
key = "my_map"          # a-z, 0-9, _; 1 to 32 characters; not a campaign zone's or a hub place's
name = "My Map"
like = "elwynn"         # the campaign zone whose enemies, elites and bosses it borrows
map = 0
map_name = "Azeroth"
area = 12
center = [-9530.0, 40.0]
radius = 100.0          # 20 to 400
map_bounds = [1535.4166, -1935.4166, -7939.583, -10254.166]   # as a zone's
hour = 10
# spawn = [-9520.0, 52.0]   # optional, inside radius

[[object.remove]]       # a placement of the world taken away: found by id + model + position
id = 4712
model = "World\\...\\Rock.m2"       # (paths shortened here)
from = [-9535.0, 44.0, 52.3]

[[object.move]]         # ... or put somewhere else
id = 4711
model = "World\\...\\Tree.m2"
from = [-9531.0, 40.0, 52.0]
position = [-9533.0, 41.0, 52.1]
rotation = [0.0, 90.0, 0.0]
scale = 1.0

[[object.add]]          # any .m2 or .wmo of the install (a .wmo is not scaled)
model = "World\\...\\Fence01.m2"
position = [-9528.0, 45.0, 52.0]
  • The limits (edits per file, file size, scale, how far from center an object may lie, the model folders refused) are data: engine/benilla/crates/benilla-recipe/src/limits.toml. A file over any of them is refused whole, with the first reason. A move or remove that finds no placement in the world (the world changed under it) is reported by the server; a stale move still puts the object at its new spot, as an add would. The client does not report.
  • The recipe edits only the map named by the zone table's map_name and only the tiles within one of its center. AZS_MAP is a dev handle: the client cannot yet tell which world the server opened, so set it only for the walk and unset it for any other run. A building (.wmo) that is moved or added may carry doodad_set and name_set (default 0).
  • Check a file: cargo run -p survivors-content --bin azs-content -- check-map <file>. It has no install, so it does not look the models up; the server does when it loads the map.
  • A user map runs on the ADT ground and its placements, without the navmesh: pick open ground.
  • The local desktop editor commands keep one live draft at a time, outside co-op. A draft starts with map new <campaign-zone> <key> or map open <key>. Object and gameplay edits are checked before they take effect and each accepted edit adds one undo step. map save writes the whole file to maps/<key>.toml beside the account save. map list lists those files. map close discards the draft and its history, so save first to keep edits. The editor opens the map as a local hub. See The map editor for the controls.

Height strokes

Each [[height]] table stores an edit in file order. center is [x, y] in world yards. radius is in yards. delta is the signed displacement at the centre of a raise or lower stroke. Smooth and flatten store samples instead. Samples are signed offsets on a square row-major grid, with X varying fastest. The grid side is ceil(2 * radius / brush_sample_step) + 1. The shared terrain path interpolates those offsets and applies a radial falloff. The same field lifts doodads and deforms client and server terrain. Buildings stay at their recorded height. The editor refuses any stroke that overlaps a building's projected bounds. Brush limits live in engine/benilla/crates/benilla-recipe/src/limits.toml.

A stroke may name its shape. falloff is the curve from centre to rim: "smooth" (the default, the first brushes' S-curve), "linear", "flat" (full strength to the rim) or "sharp" (a peak). inner is the hardness, the share of the radius held at full strength, from 0 (the default) to brush_max_inner. A file that leaves both out reads exactly as before and keeps its fingerprint. The stamps of one batch are sampled in order, each against the ground the stamps before it leave, so overlapping flatten and smooth stamps never add up past their target.

The clone brush stores samples too: each point takes the height of the point dx, dy away, raised by dz (the wire word clone=dx,dy,dz), so the relief around a source spot is stamped where the stroke goes. The editor sets the offset from the source and the stroke's first click, and dz puts the source spot at that click's height. A source point with no ground leaves its target as it is.

Surface strokes

[[paint]] stamps blend toward a layer or a named texture (texture), or swap a named layer for another (replace); like height stamps they take falloff and inner. A layer a stamp adds to a chunk carries the ground effect (grass and other clutter) that texture has in the stock ground around it, a replaced layer takes the new texture's, and every painted 8×8 cell names the layer that covers most of it, so clutter follows the paint. [[holes]] stamps open or fill the native 4×4 hole blocks. [[water]] stamps set a flat surface at height (absolute Z) or, without one, dry the cells; liquid is "water" (the default), "ocean", "magma" or "slime", the 3.3.5 LiquidType.dbc rows 1 to 4. Magma and slime draw as the stock ones do, and as there heroes walk the ground under them. crop = true fills only the cells whose edited ground dips under the surface somewhere, so the shore follows the land instead of the brush's circle.

[[block]] stamps (center, radius, blocked) wall off, or open again, each terrain chunk whose centre lies in the circle: the MCNK impassable flag the run's ground and the client's fences read. [[tint]] stamps (center, radius, color, opacity, falloff, inner) blend the ground's vertex colours toward color, a multiplier per channel from 0 to 2 where 1 leaves the ground as it is; they work on any map, and only the client draws them. A tint of 1, 1, 1 wipes earlier tints back to the stock colours.

The minimap follows the recipe: the client redraws each tile whose ground a recipe changed from the stock tile plus the difference between a shaded drawing of the stock and the edited ground (benilla_formats::minimap_patch). Untouched texels keep the bake, so moved, added or removed objects do not show on it. The map's code carries no image: every player draws the same tiles from the recipe.

The map editor

Start the desktop game with its local server. Open Game Modes and select Community. Choose a base zone and a map name, select a saved map, or paste a share code into the map code field. Once the draft is ready, use Enter editor to enter with the selected hero. The editor panel opens in the world. The editor flies with the free camera controls (mouse look, WASD, Space/C and Ctrl).

  • Click a world placement to select it. Edit its transform in the panel, press G to grab it, Q/E to turn it, ** and ** to scale a doodad, or Delete to remove it. Click to place a grabbed object and use Esc or right-click to cancel. Ctrl+Z and Ctrl+Y step through the draft.
  • The Models tab (key 3) opens the Model library, a window of its own. The side column picks Browse, Favorites or Recent and walks the archive's folders; the grid shows live 3D thumbnails and its search finds as you type (words anywhere in a path; Props and Buildings filter by kind). Click a model to see it large and turning at the right, with its size (drag to turn it, scroll to zoom). Double-click it, or press Place on map, to arm placement, then click or hold and drag to place a group of copies; right-click a tile to favorite it. Buildings can be placed from the library; their preview is not available. The library is Editor/ModelLibrary.lua, and Editor/TextureLibrary.lua is the same kind of window for terrain textures (Browse textures in the Terrain drawer: hover a swatch to look at it, click to paint with it). Both scan the archive's list a slice per frame, so a big install never stalls them.
  • Maps in the top bar lists the saved maps (and recovery snapshots) to open, recover or start a new one over a campaign zone; Community and Share maps open the catalogue and the share window. All the editor's windows are built from Editor/EditorKit.lua: flat buttons, entry boxes, a window with a head, a virtual grid, fades and timers. The mock-UI test py -I tools/tests/editor-ui.py (--shots DIR draws wireframes) runs them without a build.
  • Drag the centre, radius and spawn handles, or use the panel's marker buttons. Green and red report open ground and blocked ground after release. Right-click the spawn handle to clear it.
  • Enter a terrain brush radius and strength in yards, choose Raise, Lower, Smooth, Flatten or Clone, then hold or drag on the ground. Clone first asks for a source spot (Clone from picks another); a green ring shows where each stamp copies from. The editor applies batches while the mouse is held and flushes the remaining points on release. A whole stroke is one undo step. Smooth and flatten cap each sampled correction at the chosen strength. The bar above the tool bar sets the Curve and Hardness of height and paint brushes. Flatten levels to the ground under the stroke's first click, to a level locked with Lock level on click or typed into the box, and with Ramp and Rises toward lays a slope through that point. Raise only and Lower only keep flatten and smooth from cutting or filling. Doodads follow the terrain and the editor refuses strokes under buildings.
  • Erase paints the base texture back; Liquid in the water bar picks water, ocean, lava or slime, and Shore lets a fill follow the ground instead of the brush's circle. While placing copies, Turn, Tilt and Size vary each copy, the same way again for the same command; Spread drops each copy up to 4, 8 or 16 yards from where it was dragged, on the ground there, and Lean stands each copy along the ground's slope (copy words spread= and align=1; buildings stay upright).
  • Walls and tint in the Terrain drawer: Wall off and Open walls set whole terrain chunks impassable or open (red rings mark the walled chunks of edited tiles), Tint ground blends the ground's colour toward the Colour in the bar; Neutral wipes a tint.
  • A selected building shows its Doodad set: type another and Apply to show that set of props beside set 0 (set= on the transform; the server refuses a set the building lacks).
  • The top bar provides save, undo, redo and cursor coordinates. Use 1–7 to select tools from the bottom bar. In Gameplay, change the encounter source to use another campaign zone's enemies, elites and bosses in test runs.
  • Save writes the draft beside the account save under maps/<key>.toml. Use Maps to switch drafts. Close or switching discards undo history, so save changes first. An undo step keeps the zone part and the objects, but of the strokes only what changed: a brush stroke costs a count, not a copy of the map (survivors-content/src/draft.rs).
  • Test run starts a fight on the current draft with the campaign zone's monsters. Back to the editor restores the draft and its undo history. No test rewards, progress, or board entries are saved.
  • Share maps (or /mapshare) exports the current draft as a copyable code or imports a code into a new saved map. Host draft starts an unranked lobby on the draft. Guests need a desktop client, the same build and matching game archives. The first archive check runs in the background. Wait for it to finish before trying to host or join.
  • Community maps (or /communitymaps) browses player maps. Publish shares the current draft, Import saves a local copy, and Report sends the selected entry to moderation. Publishing and reporting use the signed-in account.

Recipe limits live in benilla-recipe/src/limits.toml. The editor currently works with one arena per map.

A race, a companion

  • A creature's icon (enemy, elite and boss alike) is its tile and its big picture in the Codex (SurvivorsCodex.lua): a bare file name of Interface\Icons\, no folder and no extension. The client has no portrait of each creature, so pick the closest of what it holds: a boss's own Achievement_Boss_* where one exists, a pet family's Ability_Hunter_Pet_* for an animal, a folk's INV_Misc_Head_* for a humanoid, a spell icon of a summoned demon, ghoul or elemental for the rest. gen puts them in AZS_GEN.creatureIcons, by entry, so a creature in two zones names one icon; a test fails a built-in creature without one. The names are not checked against the install (the packs cannot see the MPQs): look a new one up in the chain's list (benilla-extract <Data> list). A file stored with a space in its name (the client's Achievement_Boss_Archimonde .blp) cannot be named, and the check refuses a dot or a space.
  • Races are [[race]] in packs/base/account/races.toml: id (ChrRaces), male/female (CreatureDisplayInfo), faction (FactionTemplate), side (alliance or horde), and the racials. Each racial belongs to one race and opens once in account/levels.toml (start/unlock_order).
  • One people on both sides is two races (two ChrRaces rows on the same bodies, as the Pandaren 15 and 17): the second writes kin = "<first key>" and the same bonuses (the check holds them equal), may share the first's racials, and its wins count as the first's (race_wins, the "every race" achievement).
  • A new playable race needs its patch rows (tools/races-patch.js: ChrRaces, CharSections and the hair tables, displays, start outfit, the create screen's button and icons), a race-wins achievement, the classes' races, and the client's race tables (ui_unit.rs names and sides, ui_social/query.rs, the glue stages in glue_booth.rs/glue_mgr.rs/glue_create.rs, SurvivorsGlue.lua RACE_TOKENS).
  • A pet that wears the hero's look has display 0 in its PetKind look (the mage's clones, the monk's spirits): the clone flag and the hero's display go with it.
  • A pet's word in the packs (pet = "spirit_wolf", PetKind::key) is also its key on the addon line AZSPETS, and a demon's kind there (docs/ADDON-API.md): renaming a PetKind renames it for third-party addons too.
  • Companions are [[companion]] in packs/base/meta/companions.toml (key, name, display). Their place is the wire's (creature entry 9100 + place): new ones go at the end, and each needs a price in cosmetics/pets.toml.

A boss kit

packs/<pack>/bosses/<boss>.toml, named by a [[zone.boss]]'s kit:

[[boss]]
key = "hogger"

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

[[boss.kit]]
every = 14.0
ability = { adds = 5 }

Two cast abilities work for any boss, including inside a combo:

  • summon = { entry = 5300, count = 12, spell = 42650, warn = 2.0, radius = 8.0 } holds the boss for a visible cast, then spawns only the named zone enemy within radius yards. The entry must exist in a pack's zone enemies. Unlike adds, it does not choose random enemies from the current wave. A dead boss cannot finish the summon.
  • meteor = { cast = 69845, spell = 69846, burst = 69845, radius = 6.0, warn = 3.0, fall = 1.5, height = 12.0, factor = 4.0 } marks the target when casting starts, plays cast for warn seconds, then sends spell straight down from height yards above the mark. The burst and damage (factor times the boss's hit) occur after fall more seconds. Set fall = height / spell's Spell.dbc Speed; the client reads missile speed from the DBC. Heroic difficulty shortens the cast warning but never the missile flight. A combo of meteors aims each mark anew; space its steps far enough apart to leave room to dodge.

Other abilities wait while these casts wind up. Their pending casts, like ground warnings and combo steps, are transient and are dropped on host handover. The tests summoned_enemies_and_meteor_timings_are_validated_inside_combos, a_summon_cast_calls_only_its_named_creature_after_the_windup and a_meteor_falls_from_above_and_hits_only_after_its_flight cover the shared vocabulary.

A wave rolls out from where the boss stands (Illidan's Fel Wave):

  • wave = { spell = 36225, burst = 75536, count = 5, w = 5.0, warn = 2.0, gap = 0.45, factor = 2.0 } shows spell on the boss and marks count rings w yards deep at once, the first from its feet. The innermost strikes after warn seconds, each next one gap seconds after the one inside it, for factor times the boss's hit; each ring strikes once, so a hero outruns the wave or slips in behind its front. burst plays all round each ring as it strikes (about one every 10 yd), so pick a spell whose visual is a ground area kit. The boss stands while it rolls; w × count may reach at most 60 yd. Its warning counts in the Outland and Northrend kits' fairness test (at least 1.8 s). The test a_wave_rolls_out_ring_after_ring_and_spares_who_slips_behind_it covers it.

A [[boss.phase]] may also write display = <CreatureDisplayInfo id>, the look the boss takes up for the rest of the fight as the phase begins (Illidan's demon form, 21322), and spell = <id>, a visual it shows on itself then (Metamorphosis, 47241). Left out, it keeps its look and shows nothing. The test a_phase_brings_its_look_and_its_visual covers both. The web export takes a phase's display with the zone whose boss names the kit (scripts/web-zones.js).

A [[boss.phase]] may also write carry = { warn = <1.0 to 15.0 s>, spell = <id> }: the boss stands and winds up a Cataclysm (spell is its visual, the cast bar and the marked platform; warn is scaled by the difficulty like other warnings), the platform is marked and deals no damage, then the veil falls and the heroes and the boss go on to the zone's next hop arena. The Cataclysm cannot be stunned. The hops a boss owes are the carrying phases it has passed minus the hops made, so a restore or two thresholds crossed at once are safe (they hop one after the other); a boss slain in the cast hops no more, and an endless encore of the boss owes no hop and fights where the heroes stand. At most one boss of a zone carries. The tests a_carrying_phase_marks_the_platform_then_carries_heroes_and_boss_to_the_next, two_thresholds_crossed_at_once_hop_twice_one_after_the_other, a_boss_slain_in_the_cataclysm_hops_no_more, a_boss_slain_in_the_veil_hops_no_more, a_hop_owed_is_cast_again_after_a_restore_and_never_twice, a_stun_cannot_break_the_cataclysm, an_endless_encore_of_a_carrying_boss_owes_no_hop and a_zone_without_hop_arenas_owes_no_hopsurvivors-sim passage.rs, and a_boss_counts_the_carrying_phases_it_passed survivors-sim hazards.rs cover it.

A scripted ability

A mod's boss can be driven by a Lua script. Three data words name it (the script API itself is in docs/HOWTO-SCRIPTS.md):

  • ability = { script = { name = "dance", params = { gap = 1.5, rounds = 3.0 } } } as a kit entry: when it comes due (every), the script dance decides what the boss does. params (optional, at most 16, finite numbers, kept sorted by key) are numbers the script reads. A script is no step of a combo.
  • script = "dance" on a [[boss.phase]]: the script's phase hook runs as the phase begins.
  • [boss.yells.<id>], a text in all twelve languages like a phase's yell: the lines a script may have the boss say by id.

A script is a locked object of the kind script at packs/<package>/scripts/<name>.lua (the name is lower case letters, digits, _ and -), owned by the package whose folder it is in. The lookup is pack-local: a kit's script is the one of the pack that defines the kit file, never another pack's. A profile with a script requires the capability scripts-v1 (the browser build does not offer it). A script file is at most 64 KiB, a package holds at most 16, a profile at most 1 MiB; it is UTF-8 (a byte order mark is dropped) without NUL bytes, and its hash in the lock is that of the bytes as written. The tests in tests/scripts_format.rs cover the words.

The abilities are the game/bosses.rs vocabulary (cones, circles, adds, charges, combos...); a new kind of ability is code there. cargo test -p survivors-sim rift_calibration -- --ignored prints how long the bosses last.

A mode

  1. Write crates/survivors-sim/modes/<key>.toml. Start from extends = "standard" and override only what differs ([horde], [hero], [coop], ...). Give it name/name_de and a [card] (icon, colour, tag, text, rules, rewards, each with its _de) for the menu.
  2. List the packs it loads (packs = ["base", "tbc", "wotlk"]; only their classes, zones, jewelry, cards and mutators exist in its runs) and its mutators = [...]. A pack that no mode of the profile names (a mod's own pack) joins every mode that loads all of its requires, so a mod's class or zone plays without a mode of its own (mode/catalog.rs join_unnamed_packs). A pack that one of the profile's modes does name joins no other mode: its classes are missing from the others, which refuse a hero of such a class at login. The hero menu knows: the mode line of each mode carries ;xc=<class ids> when its packs lack classes of the profile (Mode::menu_lines), and the menu shuts Enter for such a hero with "Not in this game mode" (AZS.ModeLacksClass, AZS.HeroLacksClass). To play a class in a mode, name its pack in that mode's packs.
  3. Add it to BUILT_IN in crates/survivors-sim/src/mode.rs (include_str!).
  4. Test with AZS_MODE=<key>. A mode that changes the numbers keeps its runs off the leaderboards unless it is meant for them; say so in its rules.

practice = true keeps gameplay inside the current run. It skips account gold and event tokens, gear, experience, achievements, run records, reports, boards and host handover. The editor uses this mode for Test run, preserving the draft separately. The sim test the_editor_hub_and_practice_use_the_user_map_and_keep_its_undo_history covers the rule.

[encounters] changes the zone's boss schedule. Omit it for the campaign schedule.

  • kind = "survival" stays in the starting arena and scales the horde from elapsed run time. Extra elite packs come every elite_wave_seconds, starting with elite_wave_first enemies and growing by one up to elite_wave_max. The horde's normal and absolute enemy caps still apply.
  • kind = "rush" brings the first boss after first_seconds and each following boss after the preceding one falls plus break_seconds. Arena passages, arrival grace and the final boss's victory still apply. The victory pays the run's rewards without unlocking campaign progress.

Both schedules require the rift bar, hub, Proving Grounds, daily challenge and dungeon rules to be disabled. See endless.toml and bossrush.toml for examples.

[dungeon] turns a mode's runs into random dungeon runs (dungeon.toml; a mode that does not write it has none, the_standard_mode_has_no_dungeon). enabled = true switches it on. start_zone = "icc" locks an event-only dungeon to that zone (a zone key from the mode's packs, and the table must be enabled): the server starts the hero there whatever the hero menu picked and whether or not the account has opened the zone (the daily's rule), without recording it as the zone entered last; the mode's line to the hero menu carries it as zk=<key>, and the menu stands on that zone, shuts every other zone with "Fixed by the game mode" and words its Enter button for it. An empty key (the default) leaves the zone to the hero menu. A key no pack holds is refused (a_start_zone_is_checked); the_dungeon_mode_locks_its_runs_to_its_start_zone covers the lookup and the menu line, tools/tests/zone-lock.py the picker.

floor_pool enables multi-floor routes. List zone keys from the mode's packs on the same map as start_zone, which serves as the menu's anchor. Every zone contributes its entry arena and first boss, and their boss entries must be different. floor_count draws that many of these arenas without replacement and must be between two and the pool size. A defeated floor boss advances the group after the passage fade. The last boss wins the run. Room events still use the sites authored in the arena. If start_arenas lists arena numbers in start_zone, that zone occupies the first draw and its starting arena is randomly drawn from the list. Each opening arena needs its own scheduled boss and a room with a door, key boss and gated chest. The plan puts at least one gated chest behind a selected door. Set floor_pool = [], floor_count = 0 and start_arenas = [] to return to the event-only route of a parent mode.

locks, chests, traps and rockfalls are [min, max] counts per arena (locks counts door and key boss pairs; each pair rises within 0 and 32). key_seconds is how long a key boss has to fall before it leaves and its door stays shut (1 to 3600) and chest_reveal how near, in yards, a standing hero comes to a hidden chest's site before it appears and shows on the minimap (0 to 60). [dungeon.trap]: hit (share of max health, 0.01 to 0.6), warn (0.2 to 10 s), rearm (1 to 3600 s), reveal (0 to 60 yards), knock (0 to 30). A trap's blow is sized from the maximum health of the hero who sprang it and strikes every hero in its circle; a hero still untouchable (just come into the arena) springs none. reveal is checked but ignored for now: a trap shows no mark before it is sprung (a marked ground always strikes). [dungeon.rockfall] takes the [zone.eruptions] words first, every, count, radius, warn, hit, spell, knock, lasts, tick, burn and color with the same ranges, without spread and say; the site's radius is the region. An enabled table outside its ranges, or with a misspelt key, is refused (a_dungeon_table_is_checked); the_dungeon_mode_loads_and_takes_the_rest_from_standard covers the mode file.

How hard endless play gets is a mode setting too ([horde] in standard.toml): endless_health_rise and endless_damage_rise are what each endless minute multiplies an enemy's health and hit by, and past endless_ramp minutes of endless play both count endless_accel extra minutes for every minute past the ramp, squared (endless_accel = 0 keeps the rise straight). A mode file can tune it without a rebuild (AZS_MODE=<path>.toml); the sim test endless_steepens_past_its_ramp names the rule.

Crowd control fades in endless the same way: endless_hold_decay is what each endless minute multiplies the length of a hold by, a hold being a stun or root (a freeze) on an enemy, whatever the spell, talent, legendary or racial that lays it (Run::rider_on), and a Polymorph sheep (try_sheep). At 0.93 a hold keeps about half its length 10 minutes in and a twentieth at 40; 1 keeps holds whole, 0 makes every enemy immune once endless begins. Slows, fears and weakens are not holds and keep their length; a boss's own wind-up does not either. A new kind of hold takes Run::hold_factor too. The tests endless_holds_decay_with_the_minute (mode), endless_shortens_a_stun_or_root and sheep_fade_in_endless (sim) name the rule.

How many enemies stand on the field is two [horde] settings. The waves fill it up to max_enemies (120 in standard.toml); what comes on top of the waves (a boss's adds, summons and eggs and what hatches from them, the elites, a portal's demons) may go past that up to max_bodies (300, never below max_enemies; both grow for a party of more than five). On a field that full such an enemy does not come: the enemy nearest where it would have stood takes a Bolstering stack instead (+20% health and hit, 5% bigger, at most 10, never a boss), so a deep endless field that no longer thins grows stronger, not larger. A new source of enemies on top of the waves spawns through Run::spawn_or_bolster. The tests the_standard_mode_keeps_the_old_numbers (mode) and a_full_field_grows_stronger_not_larger (sim) name the rule.

A stun on a boss is an interrupt, not a lock. Bosses and guardians keep a quarter of a hold, and a stun that takes hold (Run::rider_on, whatever spell, talent, legendary, set or racial lays it) also breaks off what the boss winds up (Run::break_wind_up): its cast bar closes, interrupted; the ground it marked for a wind-up or channel it stands for (Run::hold_boss: cone, nova, stomp, line, ring, sweep, rush, wave, a summon or meteor cast) is taken back; its aimed charge and the steps of a combo or trail still to come are dropped. What it already let go (a pool, a meteor falling, a whirlwind) still lands, and while it is stunned it starts nothing new. A root only holds it in place. After a stun took hold the boss shrugs off stuns for [horde] boss_stun_immunity seconds (8 in standard.toml, 0 lets every stun land), shown on its target frame as "Stun immune". A new boss ability that makes its boss stand passes the first mark id it laid to hold_boss, so a stun can break it. The tests bosses_shrug_off_stuns_for_the_modes_immunity (mode), a_stun_breaks_off_a_boss_wind_up_and_leaves_it_immune, a_stun_interrupts_a_boss_cast_but_not_a_falling_meteor and a_stunned_boss_starts_nothing_until_the_stun_ends (sim) name the rule.

Shift's ability is a mode setting: [hero] shift = "steed" (the default: Divine Steed for every hero, game/steed.rs) or "dash" (the dodge, game/dash.rs); [hero] dash = false takes it away. The steed's numbers are [steed] in standard.toml (seconds, speed_pct, charges, recharge, rank_recharge_pct: the talent's second rank speeds the steed's recharge where the dash gets a charge); the dash's stay in game/dash.rs (BASE_CHARGES, RECHARGE, ...). The account talent dodge (account/tree.toml) learns either; its dash face is how it reads in a mode whose Shift is the dash.

A locked content profile

Preflight a local profile with azs-content profile-check --profile <directory> --json. This validates sources, ownership and the entity registry; its success does not validate typed modes. Full gameplay preparation uses survivors-server --check-profile <directory>. The directory contains profile.json, a JSON object with a lock (ProfileLock) and compatibility (Compatibility) from survivors_content::release. The lock names exact package versions, their dependencies, and each object's path, kind, and lowercase BLAKE3 hash of its raw bytes. All paths are relative to this directory and use forward slashes. The command reads the locked TOML inventory and emits JSON with an identity on success or pack, file, entry, and message for each diagnostic on failure. A diagnostic about the profile as a whole has no pack. The command exits nonzero on rejection and does not write generated output.

  • Put each gameplay pack's files under packs/<package-id>/, including its pack.toml. Mark these TOML objects as gameplay. The manifest key matches the package ID and its requires lists the same direct dependencies as the lock. The lock pins their versions. Keep the gameplay package order equal to the merge order, choosing the lowest manifest order and then the key among packs whose requirements have loaded.
  • Mark mode TOML as mode in the owning gameplay package. Legacy packages keep modes/<key>.toml; new packages use modes/<owner>/<stem>.toml, producing the logical key <owner>:<stem>. The owner comes from the lock, never the filename alone. Mode sources stay separate from the entity registry. Legacy namespace eligibility does not grant official trust.
  • A full mode replacement writes replaces = "<logical-key>" in its source and declares PackageOverride { dependency, entity: "mode:<logical-key>" } in the lock. The direct dependency must lead to the original owner, and later writers must depend on the previous writer. Unknown targets, unused declarations, duplicate writes and unrelated sibling replacements are rejected. extends is independent inheritance; replacing and extending the same effective key is a cycle.
  • Every playable profile locks exactly one effective standard mode. No inventory-order or unsigned default selector exists. External inheritance resolves only locked effective modes; embedded modes never satisfy a missing external parent.
  • An authored [card] makes a mode visible in the picker. card.order is an optional integer; authored positions sort first, then modes without an order, with logical keys breaking ties. Card and localization tables are never inherited. The six bundled cards explicitly preserve their existing Campaign, Swarm, Warband, Daily, Hub and Proving Grounds order.
  • Keep assets outside the source directories. A presentation-only package may contain only allowlisted texture and audio objects under presentation/. These packages use no gameplay pack slot. Mixed archives, models, collision, and navigation belong to gameplay identity. The source checker does not mount assets or execute UI code. Asset byte verification is part of installation.
  • Keep existing official pack and entity keys. Other package IDs use author.name, and each new entity they define uses author.name:entity. Each component begins with a lowercase ASCII letter or digit and otherwise uses lowercase ASCII letters, digits, underscores or hyphens.
  • An override of an existing entity requires a matching lock declaration with entity set to kind:key, for example spell:thunder_clap or spell:author.name:flare. Its dependency names a direct requirement that defines the entity or requires its defining pack transitively. Independent packages cannot both override the same entity, even if they touch different fields. To intentionally layer one override on another, declare the dependency between their packages and order them accordingly in the lock.

A profile can contain 64 gameplay packs. TOML preflight allows 256 KiB per file, 8 MiB and 1,024 files per package, and 64 MiB and 8,192 files per profile. It caps the parsed tree depth at 32 and the total at 2,000,000 nodes before constructing typed entity tables. Localization IDs and phrase keys can occupy up to 4 KiB each. The combined UTF-8 bytes of localization keys and text, including each input overlay, can occupy up to 8 MiB per profile. When these limits were set, the four built-in packs used 186,490 localization bytes and their longest flattened ID was 156 bytes.

Prepared gameplay modes

survivors_sim::mode::prepare_profile(&ResolvedProfile, &Registry) compiles an immutable PreparedModes catalog without global content, class/zone caches, mutable disk or user-map reads. The registry must carry the same full canonical-lock digest. The catalog retains exact source bytes, paths and effective owners, exposes shared Arc<Mode> lookups, and carries that digest. The read-only server validation command uses this same compiler on a private candidate and exits before boot selection, sockets, save locks, cloud initialization, assets or gameplay. Its version 1 JSON contains ok, lock_digest, and bounded diagnostics (one message of at most 8,192 characters). The digest includes the full canonical lock and compatibility, including presentation choices.

There are at most 128 mode sources. Inheritance starts at depth zero: eight parent edges pass, nine fail. Active paths diagnose cycles and completed parents are memoized with their depth. Each expanded mode has at most 16,384 TOML nodes and 512 KiB of UTF-8 table-key/string-value bytes; the catalog has at most 262,144 nodes and 8 MiB of those bytes. Every container and scalar counts as a node, including the root. Before cloning a parent, conservative parent-plus-child allocation is charged, including fields later replaced or discarded. Each sibling pays its own expansion cost. The exact merged tree is checked before typed construction. The baseline nine modes total 2,733 expanded nodes and 36,840 string bytes, with at most three parent edges. Adding the six explicit card positions brings the current totals to 2,739 nodes and 36,870 string bytes.

Runtime startup prepares modes before asset mounting or any save/cloud/menu work. Invalid pack views reject instead of widening to all packs; daily class/zone checks use the candidate registry. Every candidate zone passes typed registry validation; mode validation checks its pack selection and daily/hub references independently of warmup. Zone preloading iterates the selected mode's zones with the existing cap of twelve on native and one in the browser, so short catalogs are safe. Remaining terrain loads stay on demand. A mode needs at least one eligible starting zone; the optional conventional starting zone is looked up fallibly. Native developer mode files and local user-map editing remain a separate bundled/dev path.

install_prepared(catalog, selected_registry) is a one-time handoff for a future admitted candidate: the exact selected registry instance and digest must match, and an already used or installed catalog rejects replacement. It does not select a registry, rebuild typed content, mount assets, choose saves, grant admission or acknowledge readiness. External play remains gated until the asset/UI preparation and Task 7 admission adapters exist. Candidate failure is terminal; a selected external profile cannot fall back to embedded modes or mutable developer mode files.

A class is an open id from the content registry: a pack may add one on a free ChrClasses id (1..=31) from content alone (see "A class" and "Local mod profiles"). An id no loaded pack defines is refused where it enters (a save, a replay, a checkpoint, a co-op seat, a create); it is never played as a Warrior. Built-in hub locations are engine-owned places. An enabled hub validates its backing creature zone against the candidate pack view without initializing runtime objects. Hub lookup initializes only the matched hub; campaign lookup and hub-key classification do not initialize unrelated hubs. Asset/DBC preparation remains part of the activation boundary.

A mutator

packs/<pack>/mutators/<file>.toml:

[[mutator]]
key = "glass_hero"
icon = "INV_Misc_Gem_Diamond_02"
behaviors = [{ behavior = "dealt_scale", pct = 200 }, { behavior = "taken_scale", pct = 200 }]
name = { en = "Glass Hero", de = "Gläserner Held" }
text = { en = "the heroes deal and take double damage", de = "..." }

The behaviours a mutator may name are MUTATOR in survivors-content/src/behaviors.rs, each with its numbers (mutators.rs MutatorBehavior). A mode turns it on with mutators = ["..."]; Heroic affixes (affixes.toml) are mutators the tiers pick.

A cosmetic catalog entry

packs/base/cosmetics/<catalog>.toml (wings, horns, trails, mounts, titles, tabards, frames, name styles, emotes, kill effects, enchants, spell colours, spell skins, looks, wardrobe sets, weapon looks, pets, form skins):

[[wing]]
key = "angel_white"
name = "Angel Wings (White)"
price = 1500
# admin = true   worn on an admin's device alone, never sold
  • Read the file's header: in most catalogs the place is the wire id or the patch's display id, so new entries go at the end.
  • Footstep trails share a four-bit wire field, with zero reserved for no trail. The shop entries in SurvivorsWings.lua and the renderer's TRAILS table in benilla-app/src/trails.rs pair with the pack by key and wire order, respectively. Keep the renderer's existing entries in place.
  • A wardrobe set names the class whose tier set it is (class = "deathknight"); any hero may wear it, but the shop sells at least one set of every class, so a new class brings a sold set (test the_shop_sells_a_wardrobe_set_of_every_class).
  • A wardrobe set with admin = true (and price = 0) is an admin's: the shop lists it, and the gear window and the Wardrobe Keeper offer it, on an admin's device alone; it is never sold or gifted, and no other device buys, tries or wears it (gamemaster, the Gamemaster's Robe, stock items 12064 and 2586, hood and robe, repainted in black, steel and blood). The Lua shop needs a SET_LOOKS row in SurvivorsWardrobe.lua for its icons and group like any set.
  • A weapon look (weapon_looks.toml) takes the same word: admin = true (and price = 0) makes it an admin's, owned and listed on an admin's device alone, never sold, gifted or unlocked (bloodmourne, a sword of our own built by tools/bloodmourne.py: its display is a row the cosmetics patch adds and its entry an item id of ours, 980001, which the server alone answers). The Lua shop needs a WEAPON_LOOKS row in SurvivorsWeaponLooks.lua for its icon.
  • A model the client does not have yet needs its patch archive: wings and horns tools/cosmetics-patch.js, enchants tools/enchant-patch.js, the letters in tools/patches.toml (docs/PATCHES.md).
  • A wardrobe set may name fewer than eight pieces (pieces = [[2, 90901, 20]] is the chest alone, as a robe; the Darkfuse set adds plain gloves and boots: see TWEAKS and PLAIN in tools/retail-backport-source.js): it dresses those slots and leaves the others as worn. A retail item the client lacks comes in through the wow-retail-backport kit (github.com/Kirazul/wow-retail-backport; its steps up to pack), then node tools/retail-backport-source.js (the source archive data/dl/SOURCES/retail-backport.mpq) and node tools/cosmetics-patch.js (patch-W's display row from id 90901, patch-H's textures), then node tools/demonhunter-patch.js: patch-}'s copy of ItemDisplayInfo.dbc outranks patch-W's.
  • A stock robe in new colours (the Gamemaster's Robe in black, steel and blood) is an entry of REPAINTS in tools/robe-repaint.py: the stock display it copies, the name its textures take, an icon, and a colour ramp each for the stock robe's cloth, its drape and the metal trim; an inlay ramp lays the line beside the trim and the bands' lozenges in it instead of metal, and blood (a ramp, soak: how far blood soaks up each body texture column from its lower edge, spatter: drops per 128 x 64 stock pixels, a seed) bloodies it. A stock hood is an entry of HOODS there: its model texture painted in the cloth ramp, the trim rectangles (rim, hem, in stock pixels; paint the stock texture in marker colours and look at it worn to find them) in the metal ramp, with inlay and blood's spatter as for a robe. node tools/cosmetics-patch.js runs it (in the retail backport kit's venv: numpy, Pillow) and ships the rows from id 90951, the robes' then the hoods' (patch-W), and the textures (patch-H); patch-} needs the rows as for a backport.
  • aura = <spell id> on a wardrobe set: a spell whose state visual the hero wears in the world while it shows a piece of the set, in aura slot 48 (wardrobe::AURA_SLOT), wherever the wings' aura goes: its own client at the run's start, every client in a hub when the look changes, the other heroes' clients in co-op (Look::auras). The hero menu hangs the aura's state kit models on the selected hero too, as it does the ghost's (build_glue_preview). A stock cosmetic aura hidden from the client's lists suits it (42726, "Cosmetic - Immolation (Whole Body)", burns the whole body; benilla-extract <Data> spellvis <id> shows a spell's kits), or a glow of its own: an entry of GLOWS in tools/cosmetics-patch.js, a stock glow model drawn dark (tools/m2-shade.js: Alpha blend, one colour, emitters dropped) under a hidden spell of its own (the Gamemaster's set rings its hero with 90981, Flame Reflection's glow in black without its flames). Its rows go into every copy of the spell tables (patch-W, then patch-}, patch-~, packs/cata-tables.MPQ and packs/spellfx.MPQ as rebuilt from it). The release takes its visual's files as a root (azs-host zones::cosmetics). Test a_shown_sets_aura_follows_its_piece.
  • The admin page's gift catalog is generated: AZS_WRITE_CATALOG=1 cargo test -p survivors-sim catalog rewrites web/admin-catalog.js.
  • The cloud's save check prices what a save gains from that catalog, and mirrors in web/unlocks.js (UNLOCKS) the prices no generated file carries: form skins, dye styles, companion training (training.rs), gear chests by rarity (gear.rs, gear_tiers.toml) and the account tree and levels. After changing one, copy it there: node --test engine/benilla/web/test/*.test.mjs fails until they match. A shop category new to grants.rs names its save line in OWNED_AT beside them.
  • A new cosmetic table goes into the release check too (azs-host zones::cosmetics, azs-host --verify-release).
  • A Game Pass tier in packs/base/meta/pass.toml can grant a mount with { mount = "<mount key>" }. Set its shop price to zero for a pass exclusive and give the season a stand-in for its encore. Use an ownedOnly shop group in SurvivorsWings.lua to show mounts there after players unlock them.

A form skin

packs/base/cosmetics/form_skins.toml: another look for a shapeshift form, bought in the shop's Cat Forms tab and worn by every hero that takes the form (the druid's Cat Form today; Dire Bear Form or a spell's form take one the same way):

[[form_skin]]
key = "snow"
name = { en = "Snow Cat", de = "Schneekatze", ... }   # all twelve languages
price = 4000
form = 1                  # the form's id: a talent's or spell's `form.id` (1 Cat Form, 8 Dire Bear Form)
display = 29408           # CreatureDisplayInfo.dbc id of the model it shows in the form's place
races = [[6, 29409]]      # optional: a race's own model of it (the others show `display`)
  • Append new skins; nothing numbers them. The shop's tiles are in SurvivorsWings.lua (CATALOGS, command formskin), one { key, L["Name"], nil, icon } row each in a group; a new group name or note goes into the SurvivorsLocale_<loc>_FormSkins.lua files.
  • The model is picked at the account's own server from the hero's race (formskins::run_map) and rides the seat's look map (the one the spell skins use, under a key past every spell id), so a co-op guest's skin shows on the host's run too. The release packs every skin's model with the form models (talents::form_displays).
  • One skin is worn at a time per account. Regenerate the menu's Content.lua and the locale copies after a change (azs-content gen).

A gear dye, a dye pack

packs/base/cosmetics/dyes.toml: [[dye]] (key, name, hue, sat, lum, pack) is the gear palette in wire order, [[dye_pack]] (key, name, price) a pack the shop sells it in (price 0: every account owns it). A dye's place plus one is its wire index, so new dyes go at the end (at most 63); the client's table benilla_formats::dye::DYES must say the same (test the_palette_is_the_clients). Packs and dyes are generated into the menu's Content.lua.

  • glow = true on a pack: it holds no gear dye. It unlocks the glow colours (wire index 33 on, benilla_formats::dye::GLOW_DYES) that paint cosmetics, the wings today (cosmetic_colors.rs: color wings <index>, the colour row under the worn wings, color buy). At most one pack, and it is sold (price above 0); no gear dye may sit in it. Test the_glow_colours_belong_to_the_glow_pack_and_never_to_gear.
  • Regenerate the menu and the admin gift catalog after a change (azs-content gen, AZS_WRITE_CATALOG=1 cargo test -p survivors-sim catalog).

A dye style

The same dyes.toml accepts [[dye_style]]: key, translated name and description, an icon name, gold price, rendering mode, translated family and numeric family_order. The shop and wardrobe group by family order without changing wire or catalog order. Entries sharing an order must share the same family label. Modes are stable wire vocabulary: 0 selective/classic (free), 1 gentle full-surface glaze, 2 dark base with coloured highlights, 3 translucent radiant clothing, 4 moving stars, 5 drifting astral mist and stars, 6 travelling geometric rune marks, 7 travelling energy waves; 8 spectral rim, 9 ethereal shimmer, 10 phase veil, 11 lightning veins, 12 expanding rings, 13 rotating arcs, 14 comet trails, 15 crystal lattice, 16 molten veins, 17 distorted ripples, 18 shifting prism facets; 19 mirror polish, 20 brushed metal, 21 flowing quicksilver, 22 iridescent pearl sheen. Modes 19-22 (Living Metal) darken the surface to a polished base and light it with a view-dependent reflection of a sky, a horizon band and the sun (dye_view_light in wow_model.wgsl, no cube map), coloured by the dye worn with the style; modes 4-7 (Living Light) add a breathing coloured rim. The six families contain 3, 4, 4, 4, 4 and 4 styles. Modes must be unique and within 0-31; keep existing numbers stable. Prices and product names belong in TOML, never in simulation branches. The generator emits dyeStyles.

Styles and colour packs unlock independently for the account. dye buy style:<key> buys a style; purchased style tokens are saved and reported as style:<key> alongside pack tokens. Every persisted outfit validates both entitlements. Shop try-ons need neither entitlement. The per-slot appearance is an eleven-bit value carried in a u16: the low six bits select colour and the next five select mode. Existing saved values retain their exact meaning. Colour 0 preserves the original pigment while allowing a style; appearance 0 restores the original look. Gear colours 33-46 remain reserved for cosmetic glows. The internal preview-clear sentinel uses reserved colour 46, not 255, since that value can name a style/colour combination. The roster enchant word keeps the original eight appearance bits in bits 24-31; bits 23, 22 and 21 carry appearance bits 8, 9 and 10 respectively. This preserves all previous nine-bit encodings. Its low 21 bits remain the ItemVisuals id. Visible-item update fields carry the full appearance in their high half.

The body's own look is one more slot: the neck (slot 1, benilla_formats::dye::SKIN_SLOT) draws nothing, so its appearance rides the same save line, roster word and update field as a gear slot's and dresses the skin, face, facial hair, scalp, underwear, hair and extra skin (CompositePlan::with_skin). The Mog workshop's "Whole figure" paints every gear slot and the body; "Entire outfit" and a shop try-on on all slots leave the body alone. The body stays opaque under a spectral style: it takes the colour and rim, never the see-through.

Ghost clothing blends over intact skin in the body atlas; independent equipment models use alpha blending and a luminous rim. Animated styles use the existing shader time binding, not repeated CPU texture uploads. Their patterns follow the surface UVs; no independent floating particles are spawned. Body metadata reserves five bits for mode and three for effect coverage in inverse alpha; sample it without filtering so adjacent modes cannot blend into another style. Changes to the rendering vocabulary must stay in step between benilla_formats::dye, the body compositor and wow_model.wgsl. Do not start a build or large-crate test merely to regenerate a catalog; follow the task's build authorization rules.

A gear tier

packs/<pack>/gear_tiers.toml: [[gear_tier]] is a whole gear set above the six the code keeps (Common, Uncommon, Rare, Epic, Legendary and the PvP set): eight armor pieces for every class and each class's weapons, with one colour, one strength and one set of prices. Outland's exotic (packs/tbc) and Northrend's mythic (packs/wotlk) are the two there are.

  • name is the set's word, the same for every class ("Exotic Helm"; a language that joins a tail after the noun writes it as the tail, German "der Exotik"), weapon the name of its weapons. Both carry every language. The rarity word the windows show ("EXOTIC", "Exotisch") and the shop chest's name go in the hero menu's hand-written strings (rarity|<name>, chest|<name> Chest in SurvivorsLocale_<locale>_Talents.lua).
  • rank is how it ranks against the rest (Common 1, Legendary 6): the best piece a slot holds is worn and the sets run in this order. What a piece adds is slot_scale and profile_scale (what its slot's stats and its class profile's stats are multiplied by; Legendary 4.6 and 3.4, see "Gear pieces"), star_step and star_last (what each star and the top star add; Legendary 0.12 and 0.12). drop_chance, duplicate_gold, star_factor (a star's cost, Legendary 4.6), chest_price, chest_shop_cap and look_price are the tier's own numbers (TUNE).
  • chest_for_sale = false holds the tier's shop chest back: the pieces drop in the tier's zones as ever, but the shop's chest stays locked for everyone, staff included, and the server refuses to sell it ("Coming soon" in the hero menu). Unwritten it is true. Held chests can still be opened. Test the_shop_sells_a_tier_s_chest_only_when_its_pack_says_so.
  • Its sets give what its pack writes as set_bonus entries with tier = the tier's key (packs/tbc/gear/set_bonuses.toml: a 4-piece line of two stats, see "A set bonus"); a class without a tier entry has no 8-piece for it. Both pack tiers write one for every class, in the tier's own pack and whichever pack defines the class (packs/tbc/classes/<class>/set_bonuses.toml for Exotic, packs/wotlk/classes/<class>/set_bonuses.toml for Mythic).
  • Where it drops is the pack's: the tier belongs to the expansion of the pack that defines it and drops in that expansion's zones only, in the pair pair names (0 the first two zones of the twelve, 5 the last two), beside the pair's own rarity: each boss rolls the piece of every rarity its zone drops, the final boss the weapons. The shop's chests offer the tier wherever one of those zones is open.
  • A pair's own rarity is its place in its expansion (Common, Uncommon, Rare, Epic, PvP, Legendary); a zone that writes gear_rarity (a word of those six in lower case, pvp, or a tier's key) drops that one instead, beside the tiers its pair names. The first pair of Outland, Northrend and Cataclysm writes "uncommon": a hero there holds Classic's Common set already. Test a_zone_names_the_rarity_it_drops.
  • armor_icons names the eight icons of each armor kind (cloth, leather, mail, plate) in slot order (head, shoulders, chest, waist, legs, feet, wrists, hands); weapon_icons one icon per weapon of a class, by class key (a class it leaves out shows its Legendary weapon). Icons are written without their INV_, and each must be the icon of a stock item of that armor kind and slot, or of that weapon kind: the hero wears the display of such an item.
  • A piece's number holds its rarity in one digit, so the packs add four tiers at most (MAX_GEAR_TIERS). A tier's rarity is its place among all packs' tiers in load order, from 6: saves name pieces by it, so never reorder or remove a tier.
  • azs-content gen carries the tiers into the menu's Content.lua (AZS_GEN.gearTiers), which the Gear window, the shop's chests, the codex and the run's loot toast and end screen read, and into the Worker's content.gen.js (GEAR_TIERS, name and colour in rarity order), which the web armory and the site read to take a tier's piece into a profile and to name and colour it; the admin gift catalog and the web armory's lexicon list the pieces too (AZS_WRITE_CATALOG=1 cargo test -p survivors-sim catalog, cargo test -p survivors-server write_armory_lexicon -- --ignored). Tests a_gear_tier_is_checked_and_a_piece_number_holds_four (the pack check) and a_pack_tier_drops_only_in_its_expansion (the run).

A set look

packs/<pack>/classes/<class>/set_looks.toml: [[set_look]] dresses one of the class's run sets as the real set it is named after, so a "Judgement Breastplate" wears the Judgement Breastplate:

[[set_look]]
key = "paladin_epic"
rarity = 3   # Judgement Armor (ItemSet 217)
pieces = [
    [0, 45888, 1, "Helmet_74"], [1, 34258, 3, "Shoulder_37"], ...
]
  • rarity is the pieces' rarity (0 Common to 4 Legendary, 5 the PvP set, from 6 the packs' gear tiers); the class comes from the folder, and a class has one look per rarity.
  • Each piece is (gear slot 0-7: head, shoulders, chest, waist, legs, feet, wrists, hands; ItemDisplayInfo id; InventoryType, 20 for a robe in the chest slot; icon without its INV_). The hero wears that display (survivors-sim gear.rs display), and the server's lines and the Gear window (AZS_GEN.setLooks) show that icon.
  • A slot the look leaves out, and a set without a look, keep the look of the armor kind's icon (ARMOR_ICONS, a tier's armor_icons), as before. A set whose name the client has no set for (the Common sets, the monk's and the demon hunter's) writes none.
  • Take the pieces from the client's own data: ItemSet.dbc names the set's items, Item.dbc their display and InventoryType, ItemDisplayInfo.dbc the icon.
  • Regenerate the menu's Content.lua after a change (azs-content gen). Tests a_set_look_is_checked_and_dresses_one_rarity_of_its_class (the pack check) and a_named_set_wears_the_real_set_s_look (the run).

An achievement

packs/base/meta/achievements.toml, in the menu's order:

[[achievement]]
key = "kills_100"
name = { en = "First Blood", de = "Erstes Blut" }
text = { en = "Slay 100 enemies.", de = "Töte 100 Feinde." }
goal = { kills = 100 }    # survivors-content meta.rs `Goal`: kills, elites, bosses, rifts,
                          # revives, wins, zones, campaign, zone_win, flawless, tier, survive,
                          # coop_win, codex, race_wins, class_wins, classes, ...
icon = "Ability_Warrior_Rampage"
group = "Slaying"         # the codex's group (SurvivorsCodex.lua)

A new kind of goal is code: the Goal variant in meta.rs and its count in survivors-sim/src/achievements.rs (RunLog, filled at the run's end in game/ending.rs).

A daily or weekly quest, the Badge Vendor

packs/base/meta/quests.toml. A quest counts the runs that pass its filters while it is drawn and pays its reward in Badges once, as the run that finishes it ends (solo, and a co-op guest on the guest's own account); the vendor sells cosmetics for the Badges. Nothing in the code knows a quest or an item by key, so a new quest or item is an entry here and nothing else.

[[quest]]
key = "daily_win"
period = "daily"            # "daily" (a new draw every UTC day) or "weekly" (every Game Pass week,
                            # Monday 00:00 UTC)
metric = "wins"             # what it counts: runs, wins, bosses, elites, kills, rifts, revives add
count = 1                   # what each run brings; classes / zones count the different classes the
reward = 3                  # runs were played with / zones they were won in (up to `count`)
icon = "Achievement_Dungeon_ClassicDungeonMaster"
text = { en = "Win a run.", de = "Gewinne einen Lauf.", ... }   # all twelve languages
# Filters, all optional and off at their default: a run counts only when it passes every one.
min_seconds = 180           # the run lasted this long
won = true                  # the run was won (`wins` and `zones` quests count won runs alone anyway)
min_tier = 1                # won at this tier or higher (0 is Normal and no filter; a lost run has no tier)
daily = true                # played in the Daily Challenge (the day's hero is assigned)
coop = true                 # played in co-op
zone = "elwynn"             # won in this zone (a zone key)
class = 8                   # played with this class (a `ChrClasses` id)

[[badge]]                   # the currency and its vendor: the first entry is the one the game uses
key = "justice"
name = { en = "Badges of Justice", ... }
icon = "Spell_Holy_ChampionsBond"
done = { en = "Quest complete: {quest} (+{n} {badge}).", ... }  # the chat line; every language holds `{quest}`
daily_count = 3             # quests each period draws from its pool
weekly_count = 2
shop = [[{ set = "might" }, 200], [{ wings = "angel_white" }, 80]]  # (item, price in Badges)
  • Which quests run. The day (or the week) number shuffles the period's pool and the first daily_count (weekly_count) are the ones: the same for everyone, with no cloud. A pool must hold at least what is drawn (the check says so).
  • Items. The holiday shops' kinds: mount, wings, horns, trail, emote, name_style, kill_fx, spell_color, and set (a wardrobe armor set, never an admin's or the Game Pass's), weapon (a weapon look, never an admin's) and tabard. What is bought is owned as if the gold shop had sold it. A new kind is a variant of Item in meta.rs plus its owned/give arms in survivors-sim/src/events.rs.
  • Things gold cannot buy. An item the vendor lists whose gold price in its own catalog is 0 is sold by the vendor alone (a mount: price = 0 in cosmetics/mounts.toml, then [{ mount = "<key>" }, <Badges>] here). The gold shop refuses it and names the vendor (mounts.rs buy, quests::sells), the Mounts category shows it under its badge = true group with the vendor's mark (SurvivorsWings.lua), and the vendor lists it first under Only for Badges (SurvivorsQuests.lua reads the catalog's price, no key). A cosmetic with a price above 0 is sold both ways; to sell something new in both shops, add it to its catalog with a gold price and list it in shop. Mounts are the one kind that has the gold price 0 as "not sold" today: for another kind the same step needs its own buy to refuse a price of 0 and name the vendor.
  • The save. The Badges held and ever earned, and the progress, ride the QB line (quests.rsBoard); the Worker refuses a save that holds more than it ever earned (impossibleSave).
  • The hero menu. SurvivorsQuests.lua: two shop categories, Quests and Badge Vendor. The quests' texts and the currency's name reach it in the menu's language (the server answers quests with one AZSACCT quests;… line); item names come from the packs' catalogs.
  • Tests. quests.rs (the draw, the filters, the payout, the save, the vendor) and meta.rs (a_quest_or_a_vendor_item_that_does_not_hold_together_is_a_problem).

A language

Today: English, German, French, Spanish, Brazilian Portuguese, Russian, Italian, Polish, Turkish, Japanese, Simplified Chinese and Korean (Lang::ALL). Adding one (say Dutch, nl / nlNL):

  1. survivors-content/src/i18n.rs: a Lang variant at the end of the list (Lang::cache_version keeps the language's number, the index plus one, in its low byte, so the others' numbers do not move; the rest is a stamp of the build's version and packs, which makes every client drop its Cache\WDB answers once per build that changes content, so a moved display or model reaches heroes whose caches hold the old one), its place in Lang::ALL, locale() (nlNL), key() (nl), native_name(), and a field in Text and in cosmetics::Tr (nl, with #[serde(default)]; Text::exact/Tr::exact get an arm). The content crate's own test fixtures that spell a { en = .., ru = .. } table out (tests.rs, zones.rs, ...) get the field too.
  2. The packs' strings: tools/i18n-pack.py extract <dir> --lang nl writes every { en = "...", de = "..." } string that lacks nl; translate them to <dir>/nl.json ({"English": "Translation"}), then i18n-pack.py apply <dir> --lang nl writes them into the TOMLs. Add "nl" to the script's language list and to its table pattern. The loose strings: packs/*/i18n/nl.toml (every id of en.toml); validation lists the missing ones.
  3. The run's hard-wired sentences: tools/i18n-phrases.py extract lists every tr("English", "Deutsch") pair; packs/base/phrases/nl.toml maps the English wording to the translation (i18n::tr reads it for every language but English and German). apply only rewrites the languages that have a JSON in its directory.
  4. The server's branching texts (match i18n::current() { Lang::De => .., }: jewelry, rifts, vault, loot, passages, bosses, ...; the mode cards' Words and the [i18n.nl] blocks of survivors-sim/modes/*.toml) and the spell descriptions (survivors-sim/src/spell_text/<key>.rs, dispatched in spell_text.rs): an arm or a file per language; a test loops over Lang::ALL. A language with three noun forms after a count reads them from i18n::plural_ru / plural_pl, one with two from plural_one.
  5. The generator writes Generated/Content_<locale>.lua (glue and addon) and the web class names by itself; the hand-written SurvivorsLocale_<locale>_*.lua per glue file, Locale_<locale>_*.lua per addon file (same keys as the German ones, check_lua-style comparison) and SurvivorsLocale_<locale>_Talents.lua (the generator copies it into the addon) go into glue.toc and AzerothSurvivors.toc; AZS_LANGUAGES in SurvivorsLocale.lua/Locale.lua (identical copies) offers it, UI_LOCALES in benilla-ui/src/script/cvars.rs answers it from GetLocale(), and browser_language in benilla-app/src/cvars/mod.rs maps the browser's. A language whose letters Friz Quadrata lacks goes into LANGUAGE_FACES in benilla-app/src/ui_text/engine/faces.rs with the face that draws it, so the azsFont default (auto) draws it there: Russian in Prototype (Latin and Cyrillic), Japanese in Kosugi, Chinese in ZCOOL KuaiLe, Korean in Nanum Gothic (assets/fonts/README.md). A face other than Prototype is also the language's script face: a letter a text's own face lacks is looked up there first. The player can pick the face in the menu (AZS_FONTS, SurvivorsLocale.lua/Locale.lua; how to add a face: assets/fonts/README.md, "The pick list"), and the language's row in AZS_LANGUAGES names its face in file when Friz cannot draw the name.
  6. Japanese, Chinese and Korean need no plural forms: their texts after a count take one form. Japanese and Chinese are written without spaces, and the interface wraps them between their characters (ui_text/layout/wrap.rs, unspaced_break); a changelog line's topic keeps an ASCII ": " after it there too, as the window colours and cuts the topic at that colon.

A class

The death knight (packs/wotlk/classes/deathknight/) is the worked example; the monk (packs/tbc/classes/monk/) shows the meters (resources, builds/spends), stance spells (needs), spheres, a statue (stands) and an unlock; the demon hunter (packs/wotlk/classes/demonhunter/) its own bodies (bodies), a timed form (a spell's form), two weapons (swing, two [gear] weapon lists) and weapons the start outfits lack (starter_items).

  1. Pack: classes/<class>/class.toml (key, id = its ChrClasses id, health, power, starter, races, starter_weapons, the dash card, bot_name/bot_order, name, color, the class colours, piece_profiles: the gear profile of each armor slot, see "Gear pieces"), spells.toml, talents.toml with its three [[talent_tree]]s, and optionally set_bonuses.toml and piece_lore.toml (see "A set bonus", "Gear pieces").
    • damage_pct, taken_pct, pickup_pct (whole percent, may be negative, default 0): the class's own balance. damage_pct is a share more on all the damage it deals, taken_pct a share more on every blow it takes (after armour), pickup_pct a share more on the hero's own pickup radius for orbs and coins (10 yd; it counts before the gear, race and talent shares, which add to each other; the companion's radius ignores it). A class that kills from afar takes a negative pickup_pct so it walks to what it drops; a talent's pickup stat (35) gives the radius back to a build that fights close. The check keeps it between -90 and 500.
    • [[resources]] (key, max, start, every: seconds for one point to come back on its own, 0 never, name): the class's own meters, which spells builds and spends; the first fills the hero's power bar, the power line names each (chi=2;brew=1). hidden = true keeps a meter out of the player's sight while it still counts: no tooltip line, no power bar, no HUD crystals (the monk's chi and brews and the demon hunter's fury and soul fragments, for now).
    • bodies = [[4, 98951, 98952]] ([race, male, female], CreatureDisplayInfo ids): a hero of that race wears this body as one of the class instead of the race's model, dressed in their own skin, face, hair and gear (the display's model must be a Character\ model without an ExtraDisplayInfo, so the client composes it as a player). Only races the class takes.
    • swing = { beat = 1.2, dual = true }: the cosmetic auto-swing (seconds between swings; two weapons take turns, each on twice the beat), for a class the run's own table lacks.
    • [[starter_items]] (entry, name, display, inventory_type, subclass, material, sheath, hand = main/off/ranged): weapons the start outfits do not hold, with their Item.dbc row, which starter_weapons then names by entry. Missing items are skipped with a diagnostic. Set weapon_layout to main_hand, dual_wield or ranged to specify the gear slots. A [gear] block supplies one weapon list per slot, in that order. A new slot also needs its own starter item. Its weapon_icons are written without INV_ (the readers add it), and each must name an ItemDisplayInfo row's icon, or the piece has no model (the demon hunter's glaives come with patch-}). The first list is the main hand's icons, the second the off hand's, and an icon belongs to one hand: the client turns no off-hand weapon round, so tools/demonhunter-patch.js gives each row of an off-hand icon the mirrored twin of its right-hand model (<model>left, made by tools/m2-mirror.js, as 3.3.5a ships Glave_1H_DualBlade_D_02left beside its right-hand glaive). Build patch-} again after changing which icons stand in which hand.
    • [gear] off_hand_looks = true: a class whose gear holds one weapon may still show a look in its off hand, two one-hand weapons (a legendary's, e.g. Thunderfury twice) in place of its two-hand one (the monk). A two-hand weapon shown in the main hand empties the off hand again, for every class (gear.rs shows_slot, dress_looks).
    • unlock = "classic" (or "tbc", "wotlk"): the class opens once a hero of the account, of any class, has beaten that world's last zone; a locked class shows no open zones and plays no run, and no daily deals it. A mode's [unlocks] table (monk = "open", deathknight = "tbc") overrides a class's own word (modes/standard.toml). Staff can open a class for one account ahead of that, kept in the save (UC line); the hero menu's class buttons say on hover what opens a locked class. The Worker checks the daily's class against its own draw from OPEN_CLASSES in web/content.gen.js (generated: the classes with no unlock of their own); the daily mode sets no [unlocks], so the two lists agree, and survivors-sim daily.rs tests it.
    • talent_art = "presentation/talents/<name>.png": the painting the hero menu's talent window lays behind the class's three trees, the locked path of a Texture object of the profile (a PNG, at most 4096 pixels a side). It is drawn 1.52 times as wide as it is high (web.ART), so give it that shape; the first and the last 30% of its width are the outer trees' (web.SEAMS, its colour zones should meet at 30% and 70%), and a tree's part is drained of colour while the tree has no point. Without the field the window asks the game's own file Interface\AzerothSurvivors\Talents\<token in lower case>, which only a client archive holds. The path is checked (presentation/, .png); list the file in the package's required_assets to make the profile need it (the class binds it as a zone's icon binds a Texture). Native only: a profile with a Texture object plays in no browser. The generator writes it into AZS_GEN.classes as talentArt, for the classes that name one only. Test a_talent_art_names_a_locked_png_and_reaches_the_generated_row, tools/tests/talent-cards.lua.
    • spell_tone = <palette place> (1 to 15, as a [[colors]] entry's tone; 0, the default, none): every spell a hero of the class casts is drawn in that one hue until its player wears a class colour, which replaces it. It rides the padding word's class colour bits (spellcolors::field_bits, class_field), so the client draws it as it draws a worn class colour: the cast, precast and impact kits, the missiles, the chain beams, the persistent areas (DynamicObject) with their shards, and the instant ground bursts (dest_fx::spawn_ground_bursts takes the colour of the caster it carries); no other class. A worn school colour still wins for its school's spells, which a ground burst, naming no spell, cannot take. The hues are the packs' palette's (PALETTE_HUES in entities/spell_fx/hue.rs), not any hue. Test a_spell_tone_is_a_palette_place, a_class_s_own_tone_stands_until_a_class_colour_is_worn.
  2. Code: none for the class itself. A class is an open id from the content registry (no enum variant per class); everything about it comes from its entity (Class::def). An unknown class id is refused where it enters (a save, a replay, a checkpoint, a co-op seat, a create). Only class-specific behaviours that no field says (a resource, a pet) go into their families (game/talented.rs, game/hero.rs, game/companion.rs). A class has no set bonuses unless a set_bonuses.toml writes them (see "A set bonus"); code scripts none for it.
    • Id. id is a ChrClasses id in 1..=31 (the client's class masks are 1 << (id - 1)), unique among all classes. The ids 1-9 and 11-13 are the twelve shipped classes; 10 is free. By convention official classes take the free ids upward from 14 and mods take them downward from 31, so the two rarely meet; a clash fails content validation.
    • Token. The client names a class by its token: the upper-cased name part of its key (the part after the namespace: author.frostknight:frost_knight is FROST_KNIGHT, warrior is WARRIOR). Tokens are unique; a second class with the same token fails content validation.
  3. Client assets and DBC patches, only for a class with its own art:
    • azs-content gen writes Generated/Classes.tsv (the glue root) and classIcon into AZS_GEN.classes. The client adds ChrClasses, CharBaseInfo and CharStartOutfit rows from that table for every class the archives lack, so a class from content alone needs no DBC patch. Archive rows always win: a shipped class's rows never change, and a class whose id an archive already fills is reported and adds nothing. The table's last column is the class's icon (its icon, else its starter's): for a class the client adds, the create screen's crest (Interface\ForeverLogin\charactercreate\button-classicon-<token>) draws that icon, while a crest file of its own still wins;
    • the hero menu's gear window reads a class's [gear] (armor, set words, weapon names and icons), which gen writes into AZS_GEN.classes as gear. Pack gear takes precedence for every class. A set word's translations go under set|<word>, a weapon's under its name;
    • the run's damage meter takes the class's color for a class its colour table lacks;
    • the create screen's weapon preview shows only weapons with an Item.dbc row (the class's starter_items/starter_weapons); a weapon without a row is not shown;
    • the Lua side gives a class lacking one an icon (AZS_SetClassIcon: the crest file, which the client answers with the class's icon as above, else the class's own pack icon), a colour, a name and icon coordinates, an extra CharacterCreateClassButton<n> and class tabs that fit past twelve;
    • for a class with art of its own, as the monk and the demon hunter have:
      • ChrClasses.dbc row for a class the client does not know;
      • CharBaseInfo.dbc: every race paired with the class, node tools/allclasses-charbaseinfo.js (patch-R);
      • CharStartOutfit.dbc: the start outfit per race and sex;
      • races and their looks: tools/races-patch.js;
      • talent tree backgrounds (background of each tree) and icons. Put each archive's letter in tools/patches.toml. The monk's are all one archive, tools/monk-patch.js (patch-{): spell rows and visuals, icons, ChrClasses/CharBaseInfo/ CharStartOutfit rows, the create screen's eleventh class button and the class icon tiles; the in-game class colour and icon tile in !AzerothSurvivorsCompat. The demon hunter's sibling, tools/demonhunter-patch.js (patch-}, on top of {), adds its bodies' models and CreatureDisplayInfo rows and the twelfth button; rebuild } after {, then ~.
  4. Lua: the generated tables carry the class (azs-content gen); check the hand-written glue files that still list classes (SurvivorsGlue.lua, SurvivorsArmory.lua, SurvivorsSpellColors.lua, SurvivorsSpellSkins.lua, SurvivorsTitles.lua, SurvivorsPass.lua, SurvivorsWings.lua), each with its Locale_deDE_* entry.
  5. Gates: a golden file per zone for the class (game/golden.rs cases, a Golden: commit), the balance bench for the class (BAL_CLASSES=<id> cargo test --release -p survivors-sim balance_bench -- --ignored --nocapture), and the hero menu glue shots.

A behaviour

When nothing in the existing keys does it:

  1. Add the variant to game/behaviors/mod.rs Behavior (or behaviors/mutators.rs) with its key, and its arm calling the family's code.
  2. Put it in game/hooks.rs ORDER at its site, where its random draws belong; its state goes in the seat (STATE), never in the list.
  3. Add its key to the matching list in survivors-content/src/behaviors.rs (HOOKS, TALENT or MUTATOR); the test that holds the lists equal fails until both sides name it.
  4. An entry that a build only has when the packs name it leaves the golden runs alone; check.

Words added 2026-11-10 (shaman feedback)

Each works for any class or entry that writes it; a sim test names it.

WordWhereMeaning
mods = [{ bulwark = <yd> }]talentEarthen Bulwark's reduction (mods_v) holds while an enemy is within <yd> yards (the shaman 10, the monk and demon hunter 7)
passive_gaincards.toml [[rarity]]what a passive's rank card is worth at this rarity, times one step of the passive (Common 1.0); the extra is kept in the passive's Known::damage_pct, which no cast reads
jump_gain = <share>legend effecteach jump of a chain hits <share> harder than the one before, and the chain loses nothing
"crit_dotted"legend effectits hits always crit an enemy under one of the hero's damage-over-time effects
dot_reap = <share>legend effectits hits also deal <share> of what the hero's damage-over-time effects have left on the enemy; they keep ticking

The cards and the Game Menu hold a hero: Run::hold_timers moves the ends of what the hero has running (totems, ground spells, traps, summons, heals over time, buffs) by the time held, as now runs on while the run waits. A new timer on the seat that should wait too goes in that function. In co-op the arena plays on around a hero whose cards are up, so what the hero set down (ground spells, totems, traps: the seat's fields and laid) is not held: tick_seat ticks it and it fades on its own clock, and only the hero's own buffs and timers wait.

Local mod profiles

A mod is a locked content profile (see "A locked content profile" above) that a player keeps on their own machine. It needs no signature and no server approval, and none would change what it is: a local profile always plays as Modded.

  • What Modded means. Heroes and progress of its own (survivors-save.tsv.profiles/<gameplay hash>/save.tsv beside the official save, which a mod never opens), no cloud saves, no ranks, no official progress, and co-op only with players on the exact same lock. A presentation-only change of official gameplay is Modded too.
  • Authoring. Build a profile root with profile.json and its sources, check it with azs-content profile-check --profile <directory> --json, and hand the folder to players. After an edit, azs-release profile-lock <directory> hashes the locked objects again, names the files the lock does not list and runs the same source preflight; azs-release profile-pack <directory> --out <zip> writes the release zip a registry pins (profile.json, LICENSE, exactly the locked objects, the same bytes every time) and prints its size and SHA-256. The game regenerates the trusted UI itself at import; generated files in the folder are not trusted.
  • Import. The player puts the folder into UserData/mods/import/ and presses Import in the Mods window (MENU, Mods). The launcher runs the game binary once per folder with --import-profile <folder> <staging>, in a process of its own, so the running game never builds a second registry. A passing profile is kept under UserData/mods/profiles/<lock digest>/; a failing one keeps nothing and its diagnostics (dependency or override conflicts, package or resource limits) show on the tab before any run. The source folder is never changed. Importing a mod again, after an edit or as a newer version, replaces its older version: two imports are one mod when they hold the same namespaced packages (author.name), else when their folder has the same name (Entry::origin). The newer one takes over the choice; an older version the running game has open stays until the next import. A catalog install keeps every version.
  • Remove. Each row of the INSTALLED tab has a Remove that asks twice. It clears the choice when the row was chosen, deletes the entry and the kept folder (--mods remove <lock digest>, mods::remove) and leaves the saved heroes of its gameplay where they are: importing the same version again plays them again. The profile the game is playing cannot be removed.
  • The window. MENU, Mods has two tabs: INSTALLED (the kept profiles, Import, Play official content) and GET MORE (the signed catalog of "Community packages" below, Import too). The hero menu's zone list ends with a Get more page (after Lich King; staff's Cataclysm page comes before it) whose button opens the window on GET MORE (AZS.OpenMods("more")); it needs the installed game.
  • Choose and restart. Choose marks one kept profile for the next start (selected.json); Play official content clears it. A choice applies only after a restart. If the chosen profile is missing or was edited after import, the launcher turns the choice off with a message and starts the official content; the modded save stays untouched.
  • Scripts. A profile with boss scripts (docs/HOWTO-SCRIPTS.md) shows a Scripts badge on its row in the Mods window, and every Choose of it asks a second time: the first click arms the button (it reads Choose?) and shows the notice "This mod carries scripts: small programs that run on your computer while you play it. Only choose it if you trust where it came from."; the second click chooses it. The import message names how many scripts it holds (Entry.scripts). It is Modded like any mod.
  • Limits. At most 32 kept profiles and 16 folders per import. Richer content can still be rejected or need lower visual settings; a mod is not promised to run as fast as official content.
  • Classes. A mod may add a class on a free class id (1..=31; today 10 and 14..=31, mods by convention from 31 down) from content alone: a class.toml and its spells.toml in a pack of the profile, with a token (the upper-cased name part of its key) no other class has. The class passes content validation, the catalog and the import's runtime check, and plays a run like any other: its pack is named by no mode, so it joins every mode that loads the packs it requires ("A mode"). A class without a talents.toml plays with no talents; the talent windows say so. A new class on a taken id, or with a taken token, fails content validation. A spell's id gives it its client visuals and also its name on the run's cards and meter (the run's names go by id): a mod spell on an id another spell of the profile has shows that spell's name there (the fixture's Rime Strike on 49143 reads "Frost Strike" in the run), so give it an id of its own when the name matters. Temporary forms still follow the casting spell's own form definition. Existing ABI-1 profiles that omit the migrated stock swing, totem placement or scripted set fields keep their old defaults. Explicit values from the profile take priority. A mod may also give a shipped class another archetype by overriding that class and its starter, both declared as overrides in the lock ([[override]] kind = "class" and kind = "spell"): another starter shape, school and rider and a meter of its own, under the same id, key and client token. A profile cannot change a shipped class's client art, and has no set bonuses for a new class unless its pack writes them. Fixtures: survivors-content/tests/support/class_mods.rs; native_content_fixture <root> class-mods writes the three profile folders for the Mods window (frost-mage, taken-class-id, new-class-slot). A new class may also name its talent window's painting (talent_art, a Texture object of the package) and one hue for all its spells (spell_tone, a palette place), both in "A class".
  • Talents. A mod's talents are the packs' own entries, [[talent_tree]] and [[talent]] in classes/<folder>/talents.toml of its package, with its package's keys (author.name:ice_barrier):
    • A new class writes its three trees and its talents. Each entry names the class by its whole key (class = "author.name:frost_knight"): the folder name stands for a class only where it is the class's key, which a namespaced key never is. A class without a talents.toml plays with none.
    • Talents added to a shipped class go in classes/<class>/talents.toml of the mod's package (the folder is the shipped class's key, mage), in tree 0 to 2 of the trees it has; a mod adds no fourth tree. A tree is listed row by row, which the build string and the run's rules read, so while a mod's package is loaded the registry puts every tree in that order (a stable sort by row): the shipped talents keep their places and a mod's talent stands after the talents its row has. The shipped packs alone are held to the listing by the check. A req names a talent of a row above, in the same tree.
    • Reworking a talent, a tree or a class is an override: [[override]] with kind = "talent" (or "talent_tree", "class"), its key and the fields it changes, declared in the lock (entity = "talent:arcane_focus", its dependency the package that defines it). A field replaces the old one whole (a name or a text carries every language, effects, mods and plays are lists replaced as a list). A talent moved to another row (row, col) is put among that row's. A mod cannot remove a talent, only change what it does.
    • A mod has saves of its own, tied to its gameplay hash, so its talents never shift the build string of a hero of the official content. Test a_mods_talents_land_in_the_rows_of_a_shipped_tree.
  • Handed-over runs. When the host of a modded co-op run leaves, the successor's replay part records the takeover (replay revision 3, uncertified), so the run replays and watches as it was played. A player on an older build is not made heir of such a run.
  • Code. azs-update/src/content/mods.rs (store, selection, LocalModRetention), bin/launcher/mods.rs (--mods status|import|enable <id>|disable), survivors-server/src/native_boot.rs (prepare_modded), benilla-app/src/ui_script/mod_profiles.rs and the Mods window in SurvivorsMods.lua.

Typed native presentation files

The initial raw Texture adapter supports PNG UI sprites. A zone's existing icon field may name the complete locked path, for example presentation/icons/my-zone.png. Bare icon names still resolve under Interface/Icons. Matching folds ASCII case and slash direction only; there is no guessed basename, extension or presentation/ alias. Typed sprites have distinct cache keys before the legacy BLP/TGA extension stripping. Existence, layout size and render decode use the same validated pixels. This does not add a model-texture or executable-file fallback.

Raw Audio initially supports mono/stereo 16-bit PCM WAV at 8–192 kHz. The exact locked path may appear in the effective SoundEntries.dbc variation list of a signed Asset archive; the normal kit, music and ambience consumers resolve that Audio role before legacy archives. Streams reopen the retained selected root, while SFX reuse predecoded samples. Existing archive codecs remain unchanged. Other raw formats and roles fail explicitly before readiness.

Each encoded raw file is capped at 16 MiB, each decoded texture/audio at 64 MiB, and aggregate decoded media at 128 MiB. PNG dimensions are nonzero and at most 4096 per axis. Full decode, strict WAV framing/alignment and allocation checks run once during startup, never per frame. Required Texture files need an authored zone-icon or class talent_art binding; required Audio files need an authored SoundEntries binding. A required_assets entry alone is not a consumer binding. A run-only binding need not play or render in the menu; actual media acceptance separately observes the selected sprite and audio through the live consumers.

Community packages

A community package is a local mod profile or a map package ("Map packages" below) that its author releases on GitHub and the registry pins after review. A mod installs like an imported folder and plays as Modded; a map installs beside the game's content and plays as a practice map. A review or signature is distribution approval, never official trust.

  • Registry (its own public repository, apart from the addon repository; the draft is tools/azs-mods, see its README): packages/<id>.toml per package (kind = "mod" or "map", namespace = "author.name", requires, status = "active" | "deprecated" | "blocked" with a reason for the newest version, blocked = [{ version, reason }] for older ones, optional exact-byte mirrors). tools/packages.py pin writes packages.json with every kept version (up to 16, oldest first): each release zip's size, SHA-256 and profile summary. A zip holds profile.json, an optional LICENSE and exactly the locked objects, nothing else; a profile may hold the game's unqualified packs, its own namespace and exactly what some version of a required package pins. packages.json is never part of index.json.
  • Signing: azs-release packages-sign --packages packages.json --assets <dir of <sha256>.zip> --store <store> checks every object of every version against its locked BLAKE3 hash, binds each lock digest and writes packages/catalog.json, then .sig (over azs package catalog\0 and the bytes, so it is never a release's or the addon index's signature); the serial must rise, and a store whose catalog does not parse is refused.
  • Launcher: --mods refresh verifies the catalog, keeps it with its signature in one file (packages-catalog.json in the launcher state, the serial floor beside it) and writes UserData/mods/catalog.json for the Mods window: one row per package at its newest version, with the older kept version it would update. When no host answers it says it shows the kept catalog. --mods install <id> fetches the newest version's exact zip from GitHub or a mirror (<mirror><sha256>.zip), unpacks and checks it and imports it through the game's validator. The kept profile records its source digest, the lock the catalog signed (the validator's regenerated UI gives the kept lock another digest). A start turns off a chosen profile whose source digest the cached catalog blocks, however it was installed (saves kept, no network); a running game is never changed, and a new block is unknown until the next refresh. Debug builds read zips from AZS_PACKAGE_ASSETS.
  • Code: azs-update/src/packages.rs (+ packages/tests.rs), bin/launcher/mods.rs, bin/azs-release.rs (sign_packages), benilla-app/src/ui_script/mod_profiles.rs, the "Community packages" list in SurvivorsMods.lua.

Publishing a mod

The first package, Frost Mage (syiana.frostmage), went through exactly these steps; its own files are in Syiana/azs-mod-frostmage, its entry is packages/frostmage.toml in the registry Syiana/azs-mods.

  1. The folder. A profile root: profile.json and the sources it locks (see "Local mod profiles"). Your package id is author.name in lower case, and it is the folder packs/<id>/ too. Ids that start with azs. are the game's own and are refused. A mod that changes an existing entry says so in profile.json (overrides), as the example does for class:mage and spell:fireball.
  2. Every language. Each name, description and text a player reads carries all twelve languages (en de fr es pt ru it pl tr ja zh ko). A missing one is reported with its file and key and nothing is packed.
  3. Lock it. After every edit, azs-release profile-lock <folder> hashes the locked objects again, names files the lock does not list, and runs the game's own source check (the one azs-content profile-check runs):
    frostmage-src: 462 objects locked, 1 rehashed; the game's preflight passes
    
  4. Pack it. azs-release profile-pack <folder> --out frostmage-v1.zip writes the release zip (profile.json, LICENSE when present, exactly the locked objects; the same bytes on every run) and prints what the registry pins:
    frostmage-v1.zip: 1420409 bytes, sha256 29392b3b1631177a362de668734a9724fae021d172353ac15bff4655e97321c0
    

    The zip carries the official packs the profile depends on, unchanged (a profile locks every pack it uses). A license file should say which files it covers; the example's MIT covers only packs/syiana.frostmage/.
  5. Release it. A GitHub release of your repository with that zip as its asset; the asset name must fit the entry's [source] asset pattern (frostmage-*.zip, where * is the version).
  6. Register it. A pull request on Syiana/azs-mods with one new file, packages/<id>.toml:
    id = "frostmage"
    kind = "mod"
    name = "Frost Mage"
    author = "Syiana"
    repo = "Syiana/azs-mod-frostmage"
    description = "The mage as a frost caster: its starter becomes Glacial Pulse, a frost nova that roots what it hits and builds Chill."
    license = "MIT"
    namespace = "syiana.frostmage"
    requires = []
    
    [source]
    type = "release"
    asset = "frostmage-*.zip"
    

    The registry's workflow (or a maintainer, with python tools/packages.py pin) fetches the release, checks the zip against the launcher's rules and pins it by size and SHA-256 in packages.json (pinned frostmage v1 (1420409 bytes, sha256 ...)).
  7. The review. Merging that pull request is the review. A mod is data and, a boss script aside, never a program, but it can change the balance and every text a player reads, so the reviewer reads the diff between the old and the new tag: the numbers, the texts in all twelve languages, and what the profile asks of the game (compatibility). A package with scripts (docs/HOWTO-SCRIPTS.md) is reviewed as source: a script runs on the player's computer, so the reviewer reads every .lua file, not only the diff of the numbers.
  8. Signing and publishing. The maintainers' publisher (it runs on the maintainers' own machine, and the signing key stays there) sees the higher serial in packages.json, fetches every pinned zip, refuses any whose bytes are not the pinned ones, runs azs-release packages-sign (every object of every kept version is checked against its locked BLAKE3 hash and the profile's lock digest is bound):
    package catalog serial 1: 1 versions, signed into ...
      frostmage v1 Active lock c7a02402601d05f6d0a0791de55c5486677b35501d5bc769ba0feff2a6768bab
    

    and uploads packages/catalog.json.sig, then packages/catalog.json. The catalog shows in the Mods window of the clients that have it, under "Community packages".
  9. Updating and blocking. A new release is pinned beside the old ones (up to 16 are kept) and becomes the offered version; the player's update keeps the old version and its progress. To stop offering a version set status = "blocked" with a reason (or blocked = [{ version = "v1", reason = "Breaks saves." }] for an older one): the next catalog marks it, and a launcher turns a chosen profile of a blocked version off at its next start, saves kept.

Map packages

A map package is a Map Builder map as a fixed, installable version: the map file the editor saves ([[zone]] and the recipe tables, see "A user map"), a manifest that pins the game files its edited ground is built from, and a profile.json whose lock holds just that package. The same package travels through the Community (the author's in-game submission) and through the GitHub registry (kind = "map"), and installs into UserData/maps/packages/<package>/<version>/. An installed map plays as a practice map from Game Modes, Community, Installed: no restart, no change to the content profile, no official progress, as any Community map.

What a package holds

profile.json                              lock: one gameplay package `<author>.<map key>`,
                                          compatibility with `authored-map-v1`
maps/<author>.<key>/<key>.toml            the map file's exact canonical bytes (object kind `map`)
maps/<author>.<key>/<key>.json            its manifest (object kind `map`)

The manifest (survivors-content mappackage::MapManifest, exact pretty JSON):

FieldMeaning
schema1
key, map, map_namethe map file's, checked against it
recipe_sha256the map file's SHA-256: the Community's recipe hash
derivationhow the ground is built from the recipe (edited-ground-v1); a change to that is a new name
baseevery game file the edited ground reads, sorted: { path, state } with state "absent", "present" or { "exact": <BLAKE3> }
draft_revisionthe editor revision it was frozen at: provenance only
  • Identity: package id, version and the manifest's BLAKE3 (MapIdentity). The same package and version with other bytes is refused wherever it meets an installed one (two catalogs, an author re-exporting under an old number). Both installers judge an installed version by its locked packages (ids, versions, every object's hash: mappackage::same_packages), never by the whole lock digest, because the game writes its own compatibility into a Community install's profile.json; so a GitHub copy and a Community copy of one version are the same package.
  • Names: the package id names a folder and the map key a file, so neither may be a Windows device name (con, prn, aux, nul, com1-com9, lpt1-lpt9); mappackage::package, the exporter and the Worker refuse them alike. The manifest holds at most 512 KiB (the Worker's bound), checked when the package is made, so an exported package always goes along with a submission.
  • Installed folders: a version is written beside its place as a dot folder, every file flushed, then renamed; dot folders are never listed as versions. A version folder that no longer reads whole (a cut-off write, a lost file) is moved aside to .<version>.torn-* by the next install of that version, from either catalog, and its blocked/withdrawn marker goes along; one whose profile.json locks another package is refused as other bytes, not taken for torn.
  • Names across the catalogs: the Community gives a package name to the account that used it first, the GitHub registry to its namespace's owner, and nothing ties the two. A GitHub block names a package and version, so it also marks a Community copy of those names; a Community withdrawal names its manifest's SHA-256 too and marks only that revision. Two authors who pick the same name meet as "installed already with other bytes" on a player's machine.
  • Base: recorded while the exporting game checks the map against its install and builds the arena ground as a run does (benilla_formats::record_lookups around share::validate_text and Terrain::load_edited at max(radius, ROAM_MOST) + ARENA_REACH_PAST_RADIUS). ADTs, the WDT, models and WMO groups are pinned by their raw archive bytes; a file looked for and not found must stay absent; DBCs are only required to exist, because their strings differ by locale; root files (Wow.ini) stay out. Before an installed map is played every base file is checked: a map made for other game files is refused with how many differ, and nothing changes.
  • Content profiles may hold maps too: a locked profile with map objects resolves them (ResolvedProfile::map_sources) and requires authored-map-v1; a map-only package is no pack.

Exporting (Map Builder)

Open the map in the editor, type an author name (a-z, 0-9, -, _, up to 24) into the Share maps panel's box and press Export package (map share package <author>). The open map is frozen at one draft revision (usermap::freeze, refused during a brush gesture), checked, its base recorded, and written as UserData/maps/exports/<author>.<key>/<version>/ plus <author>.<key>-<version>.zip for a GitHub release. A ledger (ledger.json) numbers the versions: the same map file on the same base keeps its version, anything else is the next one; a written version is never changed, and a version folder or zip the ledger does not list (an export cut off before its ledger) keeps its number, which the next export skips. A packaged map file holds at most 256 KiB, the Community's bound.

The ledger lives on one machine. An author on another PC, or after a reinstall, types the version the Community names after the author (author 7, map share package <author> <version>): the export is then written as at least that version (1 to 999999), never below the ledger's newest.

GitHub registry

A registry entry with kind = "map" pins a release zip holding exactly the export: one package in the entry's namespace, only map objects under maps/<package>/, no edges to other packages, and authored-map-v1 (tools/packages.py; the launcher's mappackage::check_package_lock holds the same rule). The launcher installs it into UserData/maps/packages instead of keeping it as a mod profile, and marks an installed version the catalog blocks with a blocked file (the game then offers none of its maps; the marker goes when the block does). A block names a package and version, so it marks a copy the game installed from the Community too.

Code

PieceWhere
Manifest, package objects, pairing, package folder readersurvivors-content/src/mappackage.rs, profile.rs (map_sources)
Lookup recorderbenilla-formats/src/chain.rs record_lookups
Frozen draftsurvivors-sim/src/usermap.rs freeze
Export, base check, installed list, Community installsurvivors-server/src/mappackage.rs (+ mappackage/tests.rs)
Community verbs installed, play_installed, install, submit with packagesurvivors-server/src/community_maps.rs
Editor verb map share package <author>survivors-server/src/server.rs share_command, ui/AddOns/AzerothSurvivors/Editor/SurvivorsSharing.lua
Installed list, Install packageSurvivorsCommunityMaps.lua
Launcher install of kind = "map", blocksazs-update/src/packages.rs (install_map, mark_blocked_maps)
Workerweb/community-maps.js, web/migrations/0042_community_map_packages.sql
Tests without an installsurvivors-content/tests/map_packages.rs, survivors-server mappackage::tests, azs-update packages::tests, web/test/community-maps.test.mjs; tools/azs-addons/tools/test_packages.py

Not covered yet: a map's own models or textures (a package only references the game's files; a licensed-object store is a later step), a replay of a practice run (practice runs record no replay), and a run on a second device.

The hero menu's look

packs/base/meta/menu.toml (one entity, kind menu, key = "hero", survivors_content::menu) holds every number of the hero menu's look; the client reads it in benilla-app/src/portrait/menu_design.rs, the stage dressing (glue_stage.rs) and the 3D map preview (glue_booth/map_preview.rs) take it from there. Stage yards are the menu scene's yards; screen places are -1..1 with y up; each alpha is at azsMenuStage 1; over_map = true keeps a piece while a map preview shows (only the contact shadow does by default).

TableFields
clock (top level, before the tables)the time of day the land is lit at: "real" (the hour it is where the player sits, to the minute, so the land goes through the day with them) or "zone" (each zone's own hour; the default when left out). A view's own hour pins its zone under either; the Video window's Time of Day (azsTimeOfDay), once the player holds an hour there, wins over both
[map_view]every zone's preview unless it names its own [zone.menu_view] (the same fields, all of them): focus = [x, y] (optional, the world point the view centres on; left out, the zone's center), turn (quarter turns 0..3 about the focus: 0 looks north) and yaw (a further turn, any degrees), pitch (tilt, degrees), distance (behind the platform), lift (up or down on screen), scale (terrain yards to stage yards), orbit = [radius, seconds], hour (optional; pins this view's light to that hour, whatever the menu's clock says), fog_band = [low, high] (the zone's fog start held in this band, a share of the depth; both equal set it), fog_end (full haze, a share of the depth to the framed square's far edge), fog_color (optional, linear 0..1; also the sky behind the land), brightness
[vignette]alpha, height and lift (the quad's height and centre on screen; below the quad the darkening goes on at its bottom shade down to the screen's lower edge), reach (how far up the middle darkens), curve (how much higher the sides reach), over_map, behind_platform (over a map it stands at the platform's far edge: the platform and the heroes in front, only the landscape darkened)
[contact_shadow], [cast_shadow]alpha, width, length (in a hero's sizes), over_map; the cast shadow stands on the menu's own stage only
[halo]the glow behind the hero: alpha, size, rgb, over_map
[shafts], [aurora]alpha, rgb (the aurora's tints its drawn green and violet), over_map
[mist]alpha, rgb, width (the banks' width over the drawn one), speed (their drift pace over the drawn one; 0 holds them), variation (how much the banks differ in size, height and pace: 0 all alike, 1 as drawn, more wilder), over_map
[moon]alpha, size (a share of the screen's height), at = [x, y], over_map
[stage_effects]the menu stage model's own particle streams: alpha (0 takes them away), hue (optional degrees, 0 red, 120 green, 240 blue: one colour for all of them; left out, their own), over_map
[map_overlay]a colour over the map's landscape only, behind the platform and the heroes: alpha (how much of it covers the land; 0 none), rgb (black darkens the land, another colour tints it)
[platform]the stone under the heroes in front of a map: stone (texture path), stone_tile (stage yards one picture of the stone covers: smaller is finer and sharper; 0 stretches one picture over the whole platform, which blurs a tiling texture), shade = [top, side], margin (room round the outermost seats), rings (the two stone rings; without them a prop can be the floor)
[[platform.prop]]model (an .m2, or a .wmo with its first doodad set), at = [across, back] (in the platform's radii from its centre), nudge = [right, back, up] (stage yards), size, yaw (degrees), fit (optional, false: the model is the platform itself, stretched to the platform's width and depth with its top on the floor, size then scales that; it fits before it turns; pair it with rings = false), effects (its particle emitters run), hold (optional animation id whose last frame it holds), shown

The preview draws the terrain tile holding the focus and the tiles round it (three by three, those the map's WDT lists), framed on a square of one tile round the focus, so the focus stands in the middle whichever way the view turns and the land goes on past the square on every side. It draws through a camera of its own into the glue booth's target before the stage's camera, which draws the stage over it: nothing of the land stands in front of the platform. That camera's near plane is the platform's far edge, so a wall between it and the camera falls away. A zone with a floor (an instance: Naxxramas, the Scarlet Monastery) shows the buildings on its tiles standing on that floor, without the ground under or round them. The zone the preview showed last is kept in the CVar azsMenuMapZone; at the next start its land and models load before the menu opens, and the first landscape fades in from the cover. At the game's start the hero menu's first screen waits for the scene: a black frame over the whole screen (SurvivorsGlue.lua, taking over from the login's cover) stays until the land, the platform and the cover's lift have stood for 0.8 s (SceneReady, which map_preview::sync sets and the glue feed passes to AZS.SceneReady), then fades out; after 20 s it goes anyway, and with the preview off, a failed load or the browser build there is nothing to wait for. Over that wait, and the login's before it, the game plays its start animation from the window's first frame (loading_screen/start.rs, a flat Bevy UI tree above the loading screen: the logo in its halo inside two rings that turn against each other, the outer one's 24 runes lighting one after another as the start goes on (they are the progress; there is no bar), comets on the rune band, fog, light shafts and embers, all over a dark painting that covers the window and is cut, never stretched (assets/start/backdrop.jpg: tools/start-art.py bakes it, brightened and a little greyer, from the painting its BACKDROP names among those tools/start-paintings.sh makes in data/dl/START-BACKGROUND; another picture is that one word and python tools/start-art.py --backdrop --mock); each piece is placed by its UiTransform and tinted, so nothing is laid out again; its pictures are embedded, drawn by tools/start-art.py, and output/start-mock/ is the browser mock with the same numbers); it ends in a flare with the select screen up, SceneReady and every rune burning, and lets go of the window at once when a stage takes too long; until it lets go, no key or click reaches the screens under it (the loading screen's input cut, loading_screen/input.rs). Away from the menu (a run, the create screen) the landscape and the platform stay, hidden, so the menu shows them at once on the way back; with the preview switched off they go.

The Menu Designer (dev build, Ctrl+Shift+H in the hero menu) edits all of it live: a zone list (it shows any zone in place of the menu's pick), the map preview's switch, a switch that hides the menu's buttons, the zone's view (focus with one-tile steps N/S/W/E, facing, the sliders above), the look and the platform. Only the map hides the heroes, the platform, the dressing and every particle effect (not the map overlay) while the window is open; WASD then walks the focus through the land as the view shows it (Shift faster), Q and E turn it, and the mouse frames it: a drag turns and tilts it, a right drag raises or lowers it, the wheel brings it nearer or farther, Ctrl and the wheel scales the miniature. A prop's model and the platform's stone come from the asset browser, a window of its own beside the designer's: a search of the archives' file list (the map editor's index; a whole typed path is taken as well) or all of it, page by page, as a grid of pictures. Models are drawn in 3D one after another by a camera of their own (portrait/menu_preview.rs: this page, then the next; "Redraw" draws them again), textures are loaded as they are; a click on a cell takes it and the window stays open (the held one's cell is marked), so the owner can click on through the pictures; the cross closes it. A new prop's first click adds it, the next ones change its model. The platform's own Change model… picks a model that is the platform (a prop with fit; the rings go off, Back to rings undoes it) and stone size sets stone_tile. Props can be added and removed. A changed framing re-frames the standing landscape at once; a focus on another tile builds the ring round it, and after 0.6 s without a change the landscape is rebuilt so its doodads match; within a zone the new one takes the old one's place without a fade. Save writes every changed zone's [zone.menu_view] into its zone file (right after the zone's own fields) and the look into menu.toml, through survivors_content::edit (crate feature edit, toml_edit): comments, order and untouched values stay as written; a prop taken out takes its comment along, and one given another model loses the comment about the old one. It writes into AZS_CONTENT_DIR when set (a native debug build then reloads it), else this checkout's packs/; the packs are compiled in, so a save reaches the shipped game with the next build.