Content reference
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
- Write the entity into the right pack (
basefor classic,tbc,wotlk). A string is{ en = "...", de = "..." }; both languages, always. - Keep the numbers you guessed marked
TUNEin a comment, and say where a number comes from (AS's table andre/NUMBERS.mdsection, or "ours"). - Regenerate the client and web copies and check the packs:
cargo run -p survivors-content --bin azs-content -- gen, then-- check. - Run
cargo test -p survivors-content -p survivors-simand the golden runs (cargo test --release -p survivors-sim golden). - 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. - A new behaviour (something the run does that no existing key does) is code: see "A behaviour" at the end.
- 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.mdat 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
starternames it). rangeis 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 itsradiusand a cone by itslength, never byrange. 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 writerange = 10.0, so a hero running from a pack still lands them; a fartherrangemakes 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 ismorestronger (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'sstart_withstill 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 healsshare% of the walker's max health;displayis aGameObjectDisplayInfoid; the optionalscale(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 heroradiusyd out, a turn everyperiodseconds, each striking every enemy withinreachof it, one enemy at most once everyeveryseconds;displayis the orb'sCreatureDisplayInfo(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 dealsmore% more and the beat between blows ishaste% shorter, forsecsseconds. 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;needskeeps its card from builds without them (Demonic Empowerment needs the Imp'sdemonic_familiar). Testdemonic_empowerment_makes_the_demons_hit_harder_and_faster.shape = { bond = { haste_cap = 20 } }: a spell that is never cast (hitandcooldownstay 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 (byhaste_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;needskeeps its card from builds without them (Demonic Knowledge needs the Imp'sdemonic_familiar);legendary = false. Testsdemonic_knowledge_grows_the_demonsanda_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). Testa_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 = trueon 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 adotspell (Pestilence: a plague counts as damage over time). Testpestilence_ticks_never_crit_and_another_plague_still_does.no_echo = trueon a spell: no echo (a ring's "chance for a spell to cast twice",Run::echo) casts it a second time. Pestilence has both. Testan_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 (PetHarveststacks, the strongest kept), testa_jumping_pestilence_follows_the_sets_three_stacks; a dot that spreads (DotSpread) only lands on enemies without it.requires_enemy = falseon a totem spell lets it cast before enemies come into range. Totems otherwise wait until an enemy is nearby.follows = trueon 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. Withpulse_visualeach beat is also a cast of that look from the hero. Not withstandsoraura; the text says it surrounds the hero. Testa_following_totem_rides_with_the_hero_and_is_worn_while_it_lasts.visual = <spell id>: the hero's casts of the spell areSMSG_SPELL_GOof 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 whoseSpell.dbcrow 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_lookonly asks for a SpellVisual, so a kit-only one passes it: read the row (SpellVisual.dbcHasMissile, the cast and impact kits). Testtags_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'svisual.sourcesupplies 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,stateandareaare 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 inchest, so an accent inchestswaps the spell's own look for its model (Blood Boil lost its boiling blood that way); name a slot the source leaves empty. Acastaccent 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 novfxshows the look the client has for it, its own row's or the stock spell itsvisual = <spell id>names (the Death Knight's whole class does); a composed id (910001-910999) needs its recipe. Slots arehead,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 leavecastunset: the empty kit lets the equipped weapon supply its firing animation. Use animpactaccent 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.pyreads these recipes during the finaladminemotespatch step (Python 3.11+, override interpreter withAZS_PYTHON). Rebuild class patches before that final step; a missing source or colliding generated ID is an error, never an invisible fallback.visualapplies 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.12on amissilesspell 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. Testspaced_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). Testsa_totems_beat_is_cast_from_the_totem,a_spell_names_only_its_class_s_meters_and_talents.look_aura = <spell id>insideshape.summongives the summoned units a visual aura for their lifetime. Use an aura with the desired state visual. Teststorm_earth_and_fire_spirits_wear_the_hero_and_the_ghost_aura.lays = { display = 3074 }on agroundspell: each cast also leaves that object (aGameObjectDisplayInfoid, 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 forsecs.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. Testsa_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.5on agroundspell: 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. Testsa_ground_look_can_be_held_to_a_widening,a_ground_look_is_held_to_the_packs_widening.turns_into = 856on aproc = { kind = "sheep", ... }spell (Polymorph): theCreatureDisplayInfoan 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'sdisplay):spells::displayshands 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). Testsa_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'sform) 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. Testa_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 everyeveryseconds (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); withWOW_DATAset,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
colonly orders the talents of a row. The hero menu stands a row's talents by how many the row has (web.slotinSurvivorsArmory.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 Englishtext, which then starts withMilestone.orCapstone.; the run's own capstone is a one-rank talent of row 6. - What lies behind the three trees is not
background: a tree'sbackgroundnames the stock talent window's art (Interface\TalentFrame\<background>-TopLeftand its three siblings, read throughTalentTab.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 ownInterface\AzerothSurvivors\Talents\<token in lower case>(a texture of a client archive,patch-1.MPQ, made bytools/talent-paintings-patch.py); a class with neither shows the dark ground alone. - New talent builds use
v1.<hub bits>.<ranked keys>, for examplev1.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 frompython tools/sync-talent-build.py. SurvivorsTalents.luais 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 levelslevels.toml. The dash (Shift) is the account talent witheffect = "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
behaviorsname a behaviour key ofsurvivors-content/src/behaviors.rsTALENTwith 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_healandgate_coilcarry their numbers too.blow_cast(spell) makes each blow of the talent's demons also a free cast of the hero'sspell, shown from that demon (it wears the hero's spell colours), with every upgrade the hero gave it and thecleaveplays that name it (the Water Elemental: Frostbolt, Splitting Ice). - The shaman's shock plays (
shock_echo,shock_boost) list the shocks they chain inkeys. exclusiverules talents out of each other:exclusive = trueis its tree's pair,exclusive = "<group>"a named group of the class, across its trees (the warlock'slegion: Legion Gate's lesser demons or Demonic Supremacy; the monk'sstance: 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.rshold_to_rules); a group of one talent is refused. The two capstones of a tree rule each other out without it.- A talent's
effectsare the exe's table (re/tools/talents.jsrewrites them); a number we changed on purpose carries an# Ours:comment above it, and the tool would put AS's back. - A
summonplay (pets,n,lasts,spread,most) may sayfloor, the lowest share of its{v}seconds cooldown reduction brings it to (0.43: every 30 sec at most every 13), andlesser = true, lesser demons that Demonic Supremacy's stat stops. talent_looks.tomlblow = "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_bleedorhit_dotbleed, a burst) goes to a damage-meter row under the talent's key: the row reads the talent'snamein the player's language, and its icon is thetalent_looks.tomlspell of that key (no look, no icon). Give such a talent a look. - The ticks of a
crit_bleedorhit_dotbleed 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. Adotspell's ticks always did (Run::tick_dots). Testa_bleed_tick_can_crit. A set'sfield_burnticks and ano_critspell's stay without. per_sec = trueon ahit_dotplay (default false):{v}is the share of the hit dealt every second, not the share over the wholesecs: the tick is a second, so a tick is{v}of the hit andsecsseconds add up to{v}timessecs(Deadly Poison: 40% every second for 8 sec, 320% in all). Every otherhit_dotkeeps its{v}as a share over its whole time. Testa_hit_dot_per_sec_deals_its_share_every_second_and_without_it_over_the_whole_time.kit = 3031on ahit_dotorkill_burstplay (aSpellVisualKit.dbcid, 0 none, the default): the stock effect the play shows on an enemy, sent asSMSG_PLAY_SPELL_VISUALto every seat like a shop kill effect. Ahit_dotshows it on an enemy that takes its damage over time afresh (not while it still carries it, not on a corpse); akill_burston 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: itsSpell.dbcrow'sSpellVisual, 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 fromtalents::play_kits(azs-host's cosmetic roots). Testsa_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 withinmetresof the caster. Its radius in yards scales with area bonuses. Enemies in it take the spell's damage multiplied bydamageand are rooted forsecs.marked_death_casts { spell, charge, casts, radius, elite_only? }marks a target on a direct hit ofspell. Withelite_only, only elites and guardians can be marked. Each direct hit ofchargeon a marked target adds one cast on death. The cast picks a strike fromcastsand an enemy withinradiusyards 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 byspell. The hero spendssoulson a reaper whentriggermarks a primary target; on each kill the reaper can jump to a nearby marked enemy. Its config namescast, 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 everyhits-th direct hit ofspell, pulls ordinary enemies withinradiusuntilsecsand dealsdamagetimes the spell's hit. Itsmarkersupplies the name, entry, display and scale, andrownames 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.
pulsereplaces the named spell's normal cast with a learned-spell pulse. It takesradius,everyanddamage(base damage before the spell's normal damage scaling).novaoverrides a nova's baseradiusandcooldownand removes its base stun.freeze_chancereads the named spell's school and gives direct attacks of that school achance(at most 1) to freeze forsecs. Freezes respect hold resistance.form_trapleaves thorns when the form changes. It takesradius,secs,root,spreadsandcooldown. Each triggered patch moves to its victim and excludes previous victims.death_sproutleaves a pickup when a rooted enemy dies. It takespet, pickupradius,mature,secs, summondurationanddamage(a share of the named spell per attack). Only one of this mechanic's summons can be active.thaw_splashstores 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 takesradius,targets(at most that many splinters, each enemy at most one, the thawed enemy never) anddamage, 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. Testsa_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.visualis the splinter missile's look (a spell ID),kita 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 fromcountemitters circling the hero atradius, one turn inperiodseconds, a cast everyeveryseconds 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.shotis the cast's missile look (a spell ID).heightis the default offset above the hero;heightsoverrides it by body display and scales the marker by it.
strike_chainadds jumps to each target of a strike. Set the jumpradius, additionaltargetsand fixeddamageshare per jump.field_echomakes a totem cast another spell (cast) from its position everyeveryseconds at the givendamageshare. The normal totem shots continue on their own timer.spell_freezereplaces the named spell's rider with achance(at most 1) to freeze a target forsecs, subject to normal hold resistance (boss_immune = true: bosses and guardians are not frozen at all). Each target rolls alone.nova_everyreplaces everyevery-th cast of the named nova spell (the mage's Arcane Explosion) with a bigger one:areatimes its radius (every radius bonus counted) anddamagetimes 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 offormation_imagesnever 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 byslowpercent forsecs(boss_immune = true: a boss is not slowed; without it a boss and a guardian are slowed in full) and takesvulnerabilitymore damage from every source forsecs, multiplied with the other damage bonuses; struck again, both timers start over atsecsand 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.visualis 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_imagesmakes 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 withstart_with), and while it is awake the spell's card is never dealt: no banish is spent. The images stand one at each ofangles(degrees from the hero's facing, counter-clockwise, so 180 is straight behind and +60 front left)radiusyards 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 withalpha(1 is solid); the server sends them no movement. They take no damage and no enemy sees them. Whenever the hero casts the namedcastnova, every image casts it in the same moment round itself, with the hero's radius and the hero's skin and spell colour, fordamageof 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 fornova_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_cooldownmakes the cast spells inspells(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 iscooldownseconds 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_fusionfuses the spells inspellsinto one bomb once the hero has drawn every one of them (the order does not matter; before that onlyshared_cooldowncounts). 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 fromsource, a nova spell (the Explosive Trap): it is laid at the hero's feet as soon as an enemy is withinareatimes the radius ofsource(the radius with every card and bonus counted), goes offfuseseconds later where it lies, the hero near or not, and its cooldown iscooldownseconds through the cooldown rules at the cut ofsourcealone (so it hascooldownover the base ofsourcetimes whatsourcehas). The explosion dealsdamagetimes the hit ofsource(with every bonus ofsource) to every enemy in that radius, each rolling its own crit (empowers = true:damagefollows the set's strength and{v}shows it in percent, 1000 and 1500), and slows them byslowpercent forslow_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 spellground, drawn like it; each beat dealsburntimes 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 spellchillis laid at the spot as it is on its own (its own level and bonuses). The bomb stands in the models thespellslay (lays), all atscaletimes their size, until it goes off. From the fusion on only the card ofsourceis dealt, so the others keep the level they had, and no banish is spent.visualis 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) androcket_speed(yards a second, the speed the client flies it at: its source's Spell.dbc speed times the look'smissile_speed) add a rocket that falls on the bomb fromrocket_speed * fuseyards straight above and lands the moment it goes off; it is only drawn.chill_visual(a[[set_bonus.look]]spell ID) is the look thechillground is laid and drawn with when the bomb lays it, in place of the spell's own (a recoloured copy of its look:sourcethe spell, atint); the spell laid on its own keeps its look. Testa_rocket_falls_on_the_bomb_and_the_world_draws_its_explosion_where_it_lies.field_ringcasts the named totem incountequally spaced positions atradiusyards round the hero, the first straight ahead of where the hero faces at the cast (three stand at 0 and +-120 degrees).entryanddisplaychoose 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;maxis how many stand at most (defaultcount, 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 owncountround the hero's place and facing, on old totems if they stand there (withoutslotsof afield_burn). The totems wear the hero's spell colours, so what they shoot is drawn in them. They stay where they were set unless afield_burnof 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_burnmakes that ring turn round the hero and follow them: one turn inperiodseconds (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'sformation_images: it is told each totem's angle, its radius and the turn (fromperiodandclockwise, 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.slotsgives the ring that many fixed places, equally spaced, which turn with it (at least the ring'smax): the first cast with no totem standing takes the placesslots / countapart 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 atmaxtakes its place, so nothing jumps. Withoutslotsa new cast puts its totems where the hero faces. Testthe_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:damagetimes the hit it dealt (after every bonus and a crit) intickstickseveryseconds 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:damagefollows the set's strength and{v}shows it in percent (100 and 150). An enemy that dies of a burn tick bursts forbursttimes its maximum health on every enemy withinradiusof it, using the spell IDvisual: 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,rankedmake 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'srange,ranked = truechoosing by rank (boss, guardian, elite, normal; the nearest of a rank first). The shot flies atspeedyards a second (0: it lands at once), drawn as the lookshot(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 tojumpstimes, to the nearest enemy withinjump_radiusof the one it hit that the chain has not hit yet (by rank whenranked); with none it goes back to the enemy it came from if that lives withinjump_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. Testa_burn_is_one_third_of_the_hit_a_tick_for_three_seconds_and_a_new_hit_starts_it_overand the otherholy.rstests of Circle of Holy Light,circle_of_holy_light_is_the_balance_teams_set.return_orbleaves a homing projectile on a successful cast. It takesdelay,speed(yards per second), collisionradius,damage(a spell-damage share) and activecap. Each projectile strikes each enemy once. Optionalper_target = truereplaces 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. Afterdelay, 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. Optionalempowers = truescalescap(rounded) anddamagetogether; the mechanic supplies{v}= cap and{v2}= damage percent for the tooltip. Both flags default to false for existing packs.prey_chains, withconfig = { spell, max_prey, jumps, segment_range, damage, chains_per_tick }, marks up tomax_preyelites, guardians or bosses on the owner's first regular directspellhit. Later hits of that spell accumulate weaknesses, including generated chain hits. On death, every weakness queues a chain with distinct targets, each segment withinsegment_rangeyards; a segment without a target ends the chain. Each hit uses the spell's current damage calculation timesdamage.chains_per_tickbounds queue processing without dropping pending chains. Empowerment rounds and scalesjumps, also shown as{v}. Seesurvivors-content/src/set_reactions.rs.chain_stormusesconfig = { 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 writeshits,radius,pull,damage,rowandmarker: everyhitslanded 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 storesdamagetimes that chain's calculated first hit, including its crit; afterpullseconds pulling normal enemies, it deals the stored amount once per enemy withinradius. No second offensive scaling or crit roll applies. These fields do not empower.ambush_windowusesconfig = { 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 ofspellopens asecswindow before its hit when the opener or follow-up is ready. The opener'sopener_secstimer keeps running during kill-drivenfollow_secschains. Normal and elite enemies lose the hero as a target; other spells keep casting.damageadds 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 dealsshadow_shareof 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 withinfollow_secsto reopen it.sourcenames its damage row; optional localizedsource_namelabels it in the meter; the look IDs,image_secsand optionalmarkercontrol visuals. Withempowers,damageandshadow_sharescale; tooltips deliberately retain their base values. Seeset_windows.rs.cast_linkjoins consecutive cast positions. It takesseallifetime, pathsecs, half-width, tickevery,damage(a spell-damage share per tick) andshield(a maximum-health share). Each ally gains the shield once per path.frozen_gravesleaves graves where marked enemies die; a grave is not used up and lets a ghoul go on every beat while it lies. It takespet, markercapandsecs, the beatevery(seconds: the first ghoul goeseveryafter the grave is laid, so 15 and 2 make 7 ghouls a grave), searchradius, explosionblastradius, travelspeedanddamage(a spell-damage share per explosion). An enemy is marked when it dies frozen (a freeze ofthaw_splashorfreeze_chance), or withentombed = truewhen it dies with a live stack of the hero'sentomb(read as it dies, before its stacks end with it). A grave's ghoul aims withinradiusof the grave: withentombedat the nearest boss or guardian that carries every stack anentombcan, else at the thickest enemy group (blastwide). The ghoul runs there and explodes on every enemy withinblast, 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 withcrit = trueevery 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 ofspell.empowers = true:damageandblastfollow the set's strength;{v}showsdamagein percent and{v2}showsblastin meters (the pack writes yards,METERS_PER_YARD). Testsice_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 ofspell(a cast's, a tick's; not a proc's and not thefrozen_gravesexplosion; a hit that kills lays none) lays one stack on the enemy it strikes, up tostacks. All stacks of an enemy endsecsafter the latest hit (each new hit starts the time over for all). Each stack makes the enemy takevulnerabilitymore damage in that school from the hero (added up, then multiplied with the other bonuses; the explosion offrozen_gravestakes it too) and slows it byslowpercent (the stacks' sum; bosses and guardians too, the strongest running slow counts as for every slow).empowers = true:vulnerabilityfollows 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, undername, a text in every language, withicon, a file underInterface\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). Testsentomb_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 spellspell(a stack of it on the corpse, or the tick that slew it) rises as apetforsecsseconds while fewer thancapof those stand; one that the pets' own casts slew rises as well. The pet inheritsinheritof the hero's maximum health and blow power, strikestargetsmore enemies with each blow, and each blow castsspell(the hero's level of it, rank 1 unlearnt) fordamagetimes its hit with the hero's modifiers, as a stack of the hero's.stacksis how many stacks ofspellan 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 thecapof its shape).visualis 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:damageandinheritfollow the set's strength and{v},{v2}show them in percent;cap,targets,stacksandsecsdo not grow.pet_boost(the Eternal Grave Harvest 4-piece): the pets of kindpetthat thepet_harvestof the samespellraised dealdamagemore (1.0is twice; their harvest spell cast too) and striketargetsmore with each blow, on top of the harvest's owntargets.empowers = true:damagefollows the set's strength and{v}shows it in percent. Withbeat = { 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 lastssecs(the hero's duration bonuses still stretch it), ticks everyeveryseconds, 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. Teststhe_four_piece_boosts_only_the_ghouls_the_set_raised,the_exotic_four_piece_lays_pestilence_as_a_beat_of_whole_hits.drift_bladessends 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). Everyeverysecondsbladesof them leave, each flyingrangeyards insecsseconds toward the nearest enemies beyondbeyondyards 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 withinradiusof its whole path fordamagetimes the hit ofspell, and the same enemy again oncerehitseconds have passed (atsecsor more it strikes each enemy once). The hero must knowspell(a part withstart_withgives it) and an enemy must stand withinrange+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 amarker(a blade is a creature: its display moves, an area cannot);images = trueputs the hero's own look on the blade (the marker's display is then replaced, itsscalekept) as a Mirror Image wears it, andaurais 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 spelllookon the blade itself at once and then everyeveryseconds 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 intointoblades that start where it ended, spreadforkdegrees apart round the heading it flew (two withfork = 90leave 45 degrees either side) and flyreachtimes as far inreachtimes the time, striking fordamagetimes 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 brokentimestimes; 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 everyeveryseconds (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 everyperenemies struck, a started group counting, at leastbladesand at mostmost(mostis what the 64 counts);everyis 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. Testsdrift_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 novaspelltocooldownseconds (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). Testnova_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 ofriftseconds where each cast of the novaspellstood (an echo leaves none;rift_markeris 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 spellfireas it sets out) travels the seam in exactlytravelseconds whatever its length, and the line it has crossed burns (the same creature laid every twowidthalong it) until it arrives. The whole crossed line,widthyards either side, strikes each enemy that touches it once fordamagetimes 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:riftanddamagefollow 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. Testsa_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 spellspell(its own hits only: not periodic ones, a proc's or a blade's)chanceto cast the spellcastfree: costs and spends nothing, starts no cooldown, and dealsdamagetimes its hit (on the targets a cast of it picks, cards counted). Of the free casts won, at mostmostare let through in any rolling second (a win over the limit is lost). The hero need not knowcast: 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 ofcast, the hero's own cast and the free one alike,chanceto castthen.castfree the same way fordamageof its hit, at mostmosta second: these numbers are written in the text and never change with the set.empowers = true:chanceanddamagefollow 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 (castis notspell). Testsa_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 lookssmoke,stealth,veil,flicker; the rogue's Path of Darkness 4-piece) turns the immunity spellspell(Cloak of Shadows) into a state. Withautomatic = true, it starts as soon as it is ready during play and ignores manual input; manual controls are hidden. Withautomatic = false(the default), the hero starts it with a key: the keyboard'sAZS_DARKNESS(default 1), the controller's LT or the touch button, each sendingAZSCMD 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 forimmune_secs, plays the looksmoke(a 3.3.5a spell ID) and puts the hero in the Darkness forsecs, dressed in the aurasstealthandveil(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 forboss_shareof 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 forboss_immune_secs(a boss that appears meanwhile is not stopped at all). The hero castsonly_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, whenonly_spellis cast and goes off (unlessdarkness_ambushkeeps it), or when the hero falls or is knocked down; theflickerlook plays and the cooldowncooldownstarts 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 theAZSDARKline (has;ready;on;cd;cdmax;left;auto, sent whenhas,ready,onorautochanges). The bonus'stexthas no number: every value is fixed. Tests inclass_sets/darkness.rs.darkness_ambush(spell,damage,kill_secs,empowers; the Path of Darkness 8-piece) goes with adarknessof the same hero: a cast ofspell(Backstab) that begins in the Darkness dealsdamagemore on every enemy it strikes and every strike it makes, as a factor of1 + 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 underspell'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 leastkill_secsseconds (the longer of what is left andkill_secs; no new immunity, no cloud, no flicker; bosses and guardians that are not immune stand again for their share ofkill_secs). A cast with no kill ends it as it would without the set, and a kill outside the Darkness starts nothing. The parteffects = [{ 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:damagefollows 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 ahit_dotplay (Deadly Poison) of the same class: it is laid only by the hits ofspell(a strike: Envenom), not by every spell the play'skeysname (an empty list means all), and it stacks. Every hit ofspell(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 withper_sec, or over the play'ssecswithout it), for the play'ssecs(8 for Deadly Poison), a tick a second, with the talent's bonuses; an enemy carries up tostacksstacks 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).spellaims 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 (acrit_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 apoison_stacksof the samespellandtalent. An enemy that carries all itsstacksbecomes a carrier of the hero's poison forsecsseconds if the hero has fewer thanmostcarriers; 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 ofspellon it starts itssecsover, 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 everyeveryseconds on a fixed beat a carrier gives copies of all its stacks (their strength and time left; it keeps them) tojumpsenemies withinradiusof 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 forpool_secsseconds,pool_radiusyards wide (the hero's general area bonuses widen it, a spell's own do not), at mostpool_mosta 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 bypool_slowpercent while they stand there (the strongest slow counts, bosses and guardians in full) and everypool_secs / pool_ticksseconds takepool_share / pool_ticksof 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:jumpsfollows the set's strength and{v}of the text shows it (2, empowered 3); the pool's share does not.glowis the spell ID whose look aura a carrier wears,jump_visualandpool_visualare looks ([[set_bonus.look]]) for the bolt of a jump and the pool; carriers show as aDeadly Poisonand anOverdoseentry 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 partmods = [{ damage_times = ["envenom"] }](mods_v = 2.0,empowered = 3.0,shows = "v2"). Tests inclass_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 ofspellstrikes sends up tojumpsleaps from itself, one after another, each to another enemy withinradiusyards 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 dealsdamagetimes 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 fliesspeedyards a second (visualis 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 inclass_sets/jump.rs(Run::set_leaps,Run::tick_leaps); the strike's cast reads it inRun::cast_shape. Tests inclass_sets/jump.rs, insurvivors-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, optionaldamage_cards; the monk's Elemental Tiger Storm 8-piece) makes the pets of the kindspets(spirit,xuen: the elemental spirits of Storm, Earth, and Fire and Xuen) fight only by casting the hero's ownspell(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, astrike_jumpof 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 takesdamagetimes 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 talentneedsnames and knowsspell; otherwise the pets fight as they always did.needsis 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'sneeds. The run keeps the talents it took inClassSets::taken(Run::stand_sets,rebuild_seat). The spells that call the pets are unchanged.empowers = true:damagefollows 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 sourceKnown.damage_pctfactor (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 intalented.rs(a_pet_casts_tiger_palm_in_place_of_its_blow_the_moment_it_comes_and_then_on_the_heros_cooldownand the three after it) and insurvivors-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 fromsources(spell or talent keys: Renew, Circle of Healing in the priest pack; a heal over time counts each tick, overhealing counts, aheal_bellwave's heal never; the heal of a cast whose hits each mend, Holy Nova'smendrider, is one heal for the whole cast while a set counts it) from the healed hero to up totargetsenemies withinradiusyards of them (boss, guardian, elite, normal, then the nearest). A spark fliesspeedyards a second (drawn as the lookvisual, a[[set_bonus.look]]) and deals where it landsshareof the heal as the difficulty had not yet cut it. Optionalcaplimits it to that share of the hero's maximum health; omittingcapremoves 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 spellidunder the meter rowrow. Nothing about it changes with the stars. Tests inclass_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, optionalcrit; the priest's Bell of Redemption 8-piece): the hero's own heals fromsources(asheal_sparkscounts them, after the difficulty) charge a bell by their whole amount, overhealing too, up tothresholdof the maximum health (rounded up); the next counting heal rings it instead of charging it, oncecooldownseconds have passed since the last ring (the charge builds meanwhile). The ringing sends one wave for each ofradiiyards,gapseconds apart, round where the healed hero stood: each heals every living hero within ithealof their maximum health times H and strikes each enemy forharmtimes that on the priest's maximum health.crit = trueuses 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 backknockyards inknock_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 nohealshape), 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, notshield): up toshieldof their maximum health forshield_secsseconds, 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 inAZSRUNasbshandbsl(seconds left) while one stands.at_full: the spells ofsourcesthat 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:healandshieldfollow the set's strength and{v}and{v2}of the text show them in percent (10 and 50, empowered 15 and 75).id,rowlog the waves; the charge shows as the auraiconin the aura placeslot. Tests inclass_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_talentsand 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 generatedAZS_GEN.setBonusescarriesneeds, 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),modswithmods_v,plays(each with its ownv). A set line has several numbers, so a bonus holds several parts. The part's number is its first stat's amount, elsemods_v, else its first play'sv. - Strength
pis 1.0, orempowerwhen all eight pieces haveempower_stars. The set is then empowered as a whole: the 4-piece's mechanic thatempowersgrows 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 thatempowersfills{v}(and, forpet_harvestandfrozen_graves,{v2}) itself, so no part may show that placeholder. A part's number isnumber x p;wholerounds a count afterwards;fixedkeeps the number (it is written in the text);empowered = <n>is the number when empowered in place ofx p(the "every 5th" that becomes "every 4th").shows = "v" | "v2"is the text placeholder the part fills,percentshows 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.6of adamage_times, "60% less damage") shows without its sign.with_set = trueon a part of a 4-piece makes it follow its tier's 8-piece: it takes its empowered number (x p, orempowered) when that 8-piece is empowered (all eight pieces atempower_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 generatedAZS_GEN.setBonusesmarks itfollows = true(SetBonusDef::follows_set: a part withwith_set, or a mechanic thatempowersand shows a number that changes; testa_small_bonus_follows_its_set_only_when_it_says_so). Testa_four_piece_part_that_follows_the_set_empowers_with_its_eight_piece. tieris 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,piecesthat 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, andrank_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::setswakes the sets from the worn pieces andApplied::foldfolds 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 sendstalentsat 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. followmoves the spell's strikes with the hero (tick_fields); the drawnDynamicObjectstays 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_buffstacks, the time last hurt) is transient and not in a checkpoint.kill_trim,kill_castandhit_bufffire on direct hits, not on a dot tick that kills;splashfires 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):
| Word | Meaning ({v} is the part's number) |
|---|---|
mods: follow | the spell's ground area moves with the hero (Consecration, Volley, Blizzard) |
damage_times | the 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_times | the 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.
| Fields | Meaning |
|---|---|
spell, damage_spell, finisher, charger, melee | Trigger, damage source, finishing cast, optional charging cast, and melee-wave casts. |
upgraded, marker, large_marker, visual | Extension flag, ordinary/large { entry, display, scale } actors, and look ID (0 uses the source look). |
count, burst_count, cap, charges, overlaps, bounces, restore | Ordinary/burst counts, live cap, activation threshold, allowed overlapping path hits, group bounces, and restored spheres. |
distance, width, speed, duration, suspend, orbit, interval, radius | Reach, line half-width, speed, lifetime, suspension time, orbit radius, pulse interval, blast radius. |
damage, return_damage, finish_damage, ignite_damage | Ordinary, return, finishing, ignition spell-hit shares. |
push, heal, scale, armor | Normal-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.
pattern | Additional required fields |
|---|---|
pillars | count caps pillars; width is link half-width and refresh proximity; active_secs is activation duration. Fewer than three pillars use circular hammer areas. |
choir | count, length, half_angle define emitters/strokes; speed, wave_secs control the wandering wave; picture_delay, picture_radius, picture_limit bound delayed pictures. |
sun | heat, 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. |
trail | step, 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:
pattern | Required fields |
|---|---|
forge | spell, 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. |
celestial | spell, 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. |
afterimages | spell, 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, withprofile = falsefor 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_stepandstar_last; each star up tostepsaddsstar_step, thetopstar addsstar_laston top. A rarity past the end of a list takes its last number.lore_rarityis the least rarity whose pieces tell their class's own flavor line.- A class's
class.tomlhaspiece_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::sourcesanswers "DROPS FROM" (the zones whose rarity table holds the piece's rarity, their bosses whose drops list it); the hero menu asksgear sources <id>.- In a run the character window (
Inspect.lua) shows the pieces worn, their stars and the numberspiece_bonusgives them, as the server'sAZSARMORline tells them (HeroSeat::armor_list), and wakes the sets from that line byset_rulesand theset_bonusentries, 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 genericbehavior = "proc"also accepts it and otherwise usesproc.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_baseoptionally gives subsequent picks their own base strength; the first still usesbase. Combinegrowth = "a", an explicitceiling,offered_below = <ceiling>andmax_picksto 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 byworth / cap, stopping at the buff duration. The same rule drives runtime and tooltips. It works for genericprocentries 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) insustain. A new family needs no code, just the name on its members; an empty name failsazs-content check. Amulets are worn one at a time already and take no group. Testsa_group_names_a_family_of_pieces(survivors-content) anda_group_allows_one_piece_per_slot(survivors-sim).- Amulets are
[[amulet]]inamulets.toml(rarity,growth,effects = [["damage", 0.15]]), legendarieslegends.toml. A piece that procs on hits or kills needs its family's code ingame/procs.rsorgame/{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]]withspell = "<key>"is AS's own for that spell and wins; every other spell takes the one[[legend]]withform = "<form>"that its shape gives (survivors-contentjewelry.rs:legend_form, thenlegend_of; the sim'slegend_forcalls the same). A strike is abolt(range over 10 yd,MELEE_REACH) or ameleeblow;missiles,nova,ground,chain,dot,executeandconeare their shapes; a heal over time, fury, haste, thorns and empower arelasting; a shield, a sphere and a heal withsecs = 0areinstant;immune;totemfor totems and orbits;summonfor summons and commands. A passive, a bond and a spell withlegendary = falsehave none. Every form has exactly one generic entry (azs-content checkfails otherwise), so a new spell needs no legend entry when its shape fits, and a newShapevariant must be given its form inlegend_form. The amulet's id in the game islegendary:<spell key>whichever entry gives it, and a hero is offered it once they know the spell. The publiclegends.json(/data/v1/, written byazs-content gen) lists the result, one record per spell; testlegend_records_resolve_every_spell_the_way_the_game_does. It andamulets.jsonalso publish each piece's numbers at rank 1 (the pack's own words as JSON) andgrowth;LEGEND_GROWTHissurvivors_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'sCRIT_CAP_PCT,CAP_PCT,COOLDOWN_FLOOR_PCT,ECHO_CAPandHASTE_CAP_PCTtake their values from it,AZSCAPStells them to addons andcaps.jsonpublishes them. A talent that raises one writes{ stat = [id, share] }; the cap'sraised_bynames that stat id andcaps.jsonlists the talents by it (red: Titan). A new cap is a newCapincaps::ALL, and theAZSCAPSline andAZS_CAPSneed it too. Testcap_records_are_the_constants_and_name_what_raises_them. - One limit that is not a stat lives in
caps.rstoo:GROUND_AREAS_PER_SPELL(48), how many ground areas of one spell a hero keeps standing at once (the sim'sFIELDS_PER_SPELL,Run::retire_fieldingame/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 spelllays, 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 incaps::ALL, soAZSCAPSandcaps.jsondo not tell it. Testsa_ground_spell_keeps_a_bounded_number_of_areas_and_all_its_damageandthe_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 sameduration()and would need the same rule. - A proc of the piece's own numbers (Cataclysm's pieces) is
behavior = "proc"with aproc:behavior = "proc" proc = { on = "crit", chance = 0.25, stat = "crit_damage", lasts = 10.0, every = 30.0, spell = 16166 }onis what sets it off:hit(an own spell's hit, not a tick),crit,cast(not its echoes) oritself(it uses itself everyeveryseconds, the first at once). Withchance(0.01..1, 1 when left out) it raisesstat(damage,cooldown,crit,crit_damage) by the piece's worth forlastsseconds and then restseveryseconds (0 when left out). Withstacksabove 1 each trigger adds a stack while they hold, each worth the worth.spellis 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_holdsanda_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 stopsrangeyards off a hero it sees (round a wall it walks up as a swinger does) and throwsspelleveryeveryseconds instead of swinging: a missile to the spot the hero stood on (from Heroic I a little ahead of their run), markedradiusround it until it lands, striking there forfactortimes its swing.speedis the spell'sSpell.dbcmissile 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: withinreachof a hero it stops and castsspellon itself forfuseseconds (shortened as a boss's warning is),radiusround it marked; then it bursts withburstforfactortimes its swing on every hero in the mark and falls, no one's kill (no experience, no loot). Slain before, it does not burst. Keepreachunderradius, 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_dodgedandan_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'sradiusfrom itscenter. The arena's edge, rings and waves stay roundcenter; only the entry moves (Run::entry_point). The zone'sspawnis 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, needsWOW_DATA) checks a zone's ownspawnfor standing room; a later arena'sspawnis 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'sa_zone_spawn_must_lie_inside_its_radius.- The ground: the server reads the arena's ground from the install's ADT tiles (
terrain.rs). WithWOW_DATAset, runcargo test -p survivors-sim every_zone_stands -- --ignoredandevery_zone_has_open -- --ignored;find_flat_groundandscout_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'smmaps, whose creatures walk up to 70°, while the client's hero stops at 50 (GROUND_COSinbenilla-appplayer/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 -Ioverdata/dl/NAVMESH/AZS/Navmesh/<zone>-0.nav(the file isAZNV,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) anda_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 (buildernavmesh,tools/patches.toml); and runnavmesh_floors_stand_on_what_the_client_has, which fails an arena with more than a quarter of its standing spots under a building.indoors = trueon 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 ownfloordoes 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'sradius, 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 indata/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 afloorthe 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 thefloorof 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, testa_hero_far_under_a_platform_floor_has_fallen_whatever_floor_lies_there). - A zone on a small terrain plateau writes
platform = trueon[[zone]]. Its starting arena keeps its original radius, and falls below its centre height use the same recovery as a raisedfloor. 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 = trueon a[[zone.arena]]) is a platform the fight moves on to: Dragon Soul's shattered platforms of the Maelstrom. It takes nofrom_boss,choice,floororindoors, aradiusof 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 withcarry, 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 nochoicearena (a choice before a hop would never reach it; the check fails). The testsa_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_arenasurvivors-simstages.rs,a_portal_never_opens_to_a_hop_arena,a_hop_does_not_widen_the_battlefieldandgo_on_resets_the_carried_bosses_timerssurvivors-simpassage.rscover it. - The browser build ships only the tiles its arenas stand on (the shipped terrain tile rule,
azs-hostarena_tiles.rs): checkship.cmd -Webafter 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). orderis 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
colorbefore 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's905xxximpacts,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_ebbsanderuptions_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 itsspawnsthrough (those whosefromminute 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_paysanda_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
| Field | Meaning |
|---|---|
radius | a door's blocking disc, a trap's trigger, a rockfall's region, in yards (0.5 to 60; default 1) |
along | a door's heading in degrees: the way one walks through the doorway (the door object faces it; the jambs stand across it) |
display | a door's GameObject display (needed) |
entry | a key boss's creature entry (needed) |
spell | a trap's strike visual (needed) |
key | door: 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.shpaintsdata/dl/LOADING-SCREENS/<key>.png(onepaintline a zone: its light, said from the zone'shourand its sky, and its place alone, with no hero and no creature; the look is the script'sSTYLEand the same for every zone).python tools/loading-screens-patch.pycuts each to 16:9, encodes it asInterface\AzerothSurvivors\Loading\<key>.blp(2048x1024, about 1.4 MiB) and packspatch-1.MPQ; thennode tools/build-patches.js files 1gives the archive's newfilesentry fortools/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'sHINTS, general ones about the game, the English line as the key; a new hint is a line there and its translation in the elevenSurvivorsLocale_<locale>_Loading.lua(py -I tools/tests/loading-screen.pychecks them, no build). - The bar.
tools/loading-screens-patch.pyputs 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.tgathe steel case,cast_bar.tgathe crystal inColors.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'sSOUNDis the sound kit (a name ofSoundEntries.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 (
azsMenuMapPreviewother 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.ScreenBackdropinSurvivorsGlue.lua), for every zone whose picture is in the archives:SetTextureanswers 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 inglue_booth::sync_screen_backdrop, where the desktop does it inmap_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'sLIFEtable (by the zone's key) put pieces over it and under the heroes:smokefrom a chimney,mistdrifting through a valley, a flickeringlightor a litwindow, sunbeamraysthat breathe, lightning thatflashes now and then, and motes (dust,fireflies,embers,snow,ash,wisps, waterglints,rain; a motes line withstretchdraws long specks turned along their way). A line is{ kind, x, y, field = value }: x, y (and an area'sw,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\*.blpinpatch-5.MPQ, drawn bypy -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 intooutput/screen-life/<key>.mp4from the same Lua file (--still 6 9for frames,--lua <copy>for a copy being placed);py -I tools/tests/screen-life.pychecks 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.pywrites it assite/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
centeran 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. Amoveorremovethat finds no placement in the world (the world changed under it) is reported by the server; a stalemovestill puts the object at its new spot, as anaddwould. The client does not report. - The recipe edits only the map named by the zone table's
map_nameand only the tiles within one of itscenter.AZS_MAPis 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 carrydoodad_setandname_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>ormap open <key>. Object and gameplay edits are checked before they take effect and each accepted edit adds one undo step.map savewrites the whole file tomaps/<key>.tomlbeside the account save.map listlists those files.map closediscards 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, andEditor/TextureLibrary.luais 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 testpy -I tools/tests/editor-ui.py(--shots DIRdraws 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=andalign=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 ofInterface\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 ownAchievement_Boss_*where one exists, a pet family'sAbility_Hunter_Pet_*for an animal, a folk'sINV_Misc_Head_*for a humanoid, a spell icon of a summoned demon, ghoul or elemental for the rest.genputs them inAZS_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'sAchievement_Boss_Archimonde .blp) cannot be named, and the check refuses a dot or a space. - Races are
[[race]]inpacks/base/account/races.toml:id(ChrRaces),male/female(CreatureDisplayInfo),faction(FactionTemplate),side(allianceorhorde), and the racials. Each racial belongs to one race and opens once inaccount/levels.toml(start/unlock_order). - One people on both sides is two races (two
ChrRacesrows on the same bodies, as the Pandaren 15 and 17): the second writeskin = "<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.rsnames and sides,ui_social/query.rs, the glue stages inglue_booth.rs/glue_mgr.rs/glue_create.rs,SurvivorsGlue.luaRACE_TOKENS). - A pet that wears the hero's look has display 0 in its
PetKindlook (the mage's clones, the monk'sspirits): 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 itskeyon the addon lineAZSPETS, and a demon'skindthere (docs/ADDON-API.md): renaming aPetKindrenames it for third-party addons too. - Companions are
[[companion]]inpacks/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 incosmetics/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 withinradiusyards. The entry must exist in a pack's zone enemies. Unlikeadds, 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, playscastforwarnseconds, then sendsspellstraight down fromheightyards above the mark. Theburstand damage (factortimes the boss's hit) occur afterfallmore seconds. Setfall = 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 }showsspellon the boss and markscountringswyards deep at once, the first from its feet. The innermost strikes afterwarnseconds, each next onegapseconds after the one inside it, forfactortimes the boss's hit; each ring strikes once, so a hero outruns the wave or slips in behind its front.burstplays 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 × countmay reach at most 60 yd. Its warning counts in the Outland and Northrend kits' fairness test (at least 1.8 s). The testa_wave_rolls_out_ring_after_ring_and_spares_who_slips_behind_itcovers 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 scriptdancedecides 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'sphasehook runs as the phase begins.[boss.yells.<id>], a text in all twelve languages like a phase'syell: 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
- Write
crates/survivors-sim/modes/<key>.toml. Start fromextends = "standard"and override only what differs ([horde],[hero],[coop], ...). Give itname/name_deand a[card](icon, colour, tag, text, rules, rewards, each with its_de) for the menu. - List the packs it loads (
packs = ["base", "tbc", "wotlk"]; only their classes, zones, jewelry, cards and mutators exist in its runs) and itsmutators = [...]. A pack that no mode of the profile names (a mod's own pack) joins every mode that loads all of itsrequires, so a mod's class or zone plays without a mode of its own (mode/catalog.rsjoin_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: themodeline 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'spacks. - Add it to
BUILT_INincrates/survivors-sim/src/mode.rs(include_str!). - 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 everyelite_wave_seconds, starting withelite_wave_firstenemies and growing by one up toelite_wave_max. The horde's normal and absolute enemy caps still apply.kind = "rush"brings the first boss afterfirst_secondsand each following boss after the preceding one falls plusbreak_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 itspack.toml. Mark these TOML objects asgameplay. The manifest key matches the package ID and itsrequireslists 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 manifestorderand then the key among packs whose requirements have loaded. - Mark mode TOML as
modein the owning gameplay package. Legacy packages keepmodes/<key>.toml; new packages usemodes/<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 declaresPackageOverride { 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.extendsis independent inheritance; replacing and extending the same effective key is a cycle. - Every playable profile locks exactly one effective
standardmode. 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.orderis 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 usesauthor.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
entityset tokind:key, for examplespell:thunder_claporspell:author.name:flare. Itsdependencynames 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.luaand the renderer'sTRAILStable inbenilla-app/src/trails.rspair 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 (testthe_shop_sells_a_wardrobe_set_of_every_class). - A wardrobe set with
admin = true(andprice = 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 aSET_LOOKSrow inSurvivorsWardrobe.luafor its icons and group like any set. - A weapon look (
weapon_looks.toml) takes the same word:admin = true(andprice = 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 bytools/bloodmourne.py: itsdisplayis a row the cosmetics patch adds and itsentryan item id of ours, 980001, which the server alone answers). The Lua shop needs aWEAPON_LOOKSrow inSurvivorsWeaponLooks.luafor its icon. - A model the client does not have yet needs its patch archive: wings and horns
tools/cosmetics-patch.js, enchantstools/enchant-patch.js, the letters intools/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: seeTWEAKSandPLAINintools/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 topack), thennode tools/retail-backport-source.js(the source archivedata/dl/SOURCES/retail-backport.mpq) andnode tools/cosmetics-patch.js(patch-W's display row from id 90901, patch-H's textures), thennode tools/demonhunter-patch.js: patch-}'s copy ofItemDisplayInfo.dbcoutranks patch-W's. - A stock robe in new colours (the Gamemaster's Robe in black, steel and blood) is an entry of
REPAINTSintools/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; aninlayramp lays the line beside the trim and the bands' lozenges in it instead of metal, andblood(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 ofHOODSthere: 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, withinlayandblood's spatter as for a robe.node tools/cosmetics-patch.jsruns 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 ofGLOWSintools/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.MPQandpacks/spellfx.MPQas rebuilt from it). The release takes its visual's files as a root (azs-hostzones::cosmetics). Testa_shown_sets_aura_follows_its_piece.- The admin page's gift catalog is generated:
AZS_WRITE_CATALOG=1 cargo test -p survivors-sim catalogrewritesweb/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.mjsfails until they match. A shop category new togrants.rsnames its save line inOWNED_ATbeside them. - A new cosmetic table goes into the release check too (
azs-hostzones::cosmetics,azs-host --verify-release). - A Game Pass tier in
packs/base/meta/pass.tomlcan 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 anownedOnlyshop group inSurvivorsWings.luato 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, commandformskin), one{ key, L["Name"], nil, icon }row each in a group; a new group name or note goes into theSurvivorsLocale_<loc>_FormSkins.luafiles. - 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.luaand 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 = trueon 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. Testthe_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.
nameis 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"),weaponthe 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> ChestinSurvivorsLocale_<locale>_Talents.lua).rankis 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 isslot_scaleandprofile_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_stepandstar_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_capandlook_priceare the tier's own numbers (TUNE).chest_for_sale = falseholds 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 istrue. Held chests can still be opened. Testthe_shop_sells_a_tier_s_chest_only_when_its_pack_says_so.- Its sets give what its pack writes as
set_bonusentries withtier= the tier's key (packs/tbc/gear/set_bonuses.toml: a 4-piece line of two stats, see "A set bonus"); a class without atierentry 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.tomlfor Exotic,packs/wotlk/classes/<class>/set_bonuses.tomlfor 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
pairnames (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. Testa_zone_names_the_rarity_it_drops. armor_iconsnames the eight icons of each armor kind (cloth,leather,mail,plate) in slot order (head, shoulders, chest, waist, legs, feet, wrists, hands);weapon_iconsone icon per weapon of a class, by class key (a class it leaves out shows its Legendary weapon). Icons are written without theirINV_, 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 gencarries the tiers into the menu'sContent.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'scontent.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). Testsa_gear_tier_is_checked_and_a_piece_number_holds_four(the pack check) anda_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"], ...
]
rarityis 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;
ItemDisplayInfoid;InventoryType, 20 for a robe in the chest slot; icon without itsINV_). The hero wears that display (survivors-simgear.rsdisplay), 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'sarmor_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.dbcnames the set's items,Item.dbctheir display andInventoryType,ItemDisplayInfo.dbcthe icon. - Regenerate the menu's
Content.luaafter a change (azs-content gen). Testsa_set_look_is_checked_and_dresses_one_rarity_of_its_class(the pack check) anda_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, andset(a wardrobe armor set, never an admin's or the Game Pass's),weapon(a weapon look, never an admin's) andtabard. What is bought is owned as if the gold shop had sold it. A new kind is a variant ofIteminmeta.rsplus itsowned/givearms insurvivors-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 = 0incosmetics/mounts.toml, then[{ mount = "<key>" }, <Badges>]here). The gold shop refuses it and names the vendor (mounts.rsbuy,quests::sells), the Mounts category shows it under itsbadge = truegroup with the vendor's mark (SurvivorsWings.lua), and the vendor lists it first under Only for Badges (SurvivorsQuests.luareads 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 inshop. Mounts are the one kind that has the gold price 0 as "not sold" today: for another kind the same step needs its ownbuyto refuse a price of 0 and name the vendor. - The save. The Badges held and ever earned, and the progress, ride the
QBline (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 answersquestswith oneAZSACCT quests;…line); item names come from the packs' catalogs. - Tests.
quests.rs(the draw, the filters, the payout, the save, the vendor) andmeta.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):
survivors-content/src/i18n.rs: aLangvariant at the end of the list (Lang::cache_versionkeeps 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 itsCache\WDBanswers once per build that changes content, so a moved display or model reaches heroes whose caches hold the old one), its place inLang::ALL,locale()(nlNL),key()(nl),native_name(), and a field inTextand incosmetics::Tr(nl, with#[serde(default)];Text::exact/Tr::exactget an arm). The content crate's own test fixtures that spell a{ en = .., ru = .. }table out (tests.rs,zones.rs, ...) get the field too.- The packs' strings:
tools/i18n-pack.py extract <dir> --lang nlwrites every{ en = "...", de = "..." }string that lacksnl; translate them to<dir>/nl.json({"English": "Translation"}), theni18n-pack.py apply <dir> --lang nlwrites 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 ofen.toml); validation lists the missing ones. - The run's hard-wired sentences:
tools/i18n-phrases.py extractlists everytr("English", "Deutsch")pair;packs/base/phrases/nl.tomlmaps the English wording to the translation (i18n::trreads it for every language but English and German).applyonly rewrites the languages that have a JSON in its directory. - The server's branching texts (
match i18n::current() { Lang::De => .., }: jewelry, rifts, vault, loot, passages, bosses, ...; the mode cards'Wordsand the[i18n.nl]blocks ofsurvivors-sim/modes/*.toml) and the spell descriptions (survivors-sim/src/spell_text/<key>.rs, dispatched inspell_text.rs): an arm or a file per language; a test loops overLang::ALL. A language with three noun forms after a count reads them fromi18n::plural_ru/plural_pl, one with two fromplural_one. - The generator writes
Generated/Content_<locale>.lua(glue and addon) and the web class names by itself; the hand-writtenSurvivorsLocale_<locale>_*.luaper glue file,Locale_<locale>_*.luaper addon file (same keys as the German ones,check_lua-style comparison) andSurvivorsLocale_<locale>_Talents.lua(the generator copies it into the addon) go intoglue.tocandAzerothSurvivors.toc;AZS_LANGUAGESinSurvivorsLocale.lua/Locale.lua(identical copies) offers it,UI_LOCALESinbenilla-ui/src/script/cvars.rsanswers it fromGetLocale(), andbrowser_languageinbenilla-app/src/cvars/mod.rsmaps the browser's. A language whose letters Friz Quadrata lacks goes intoLANGUAGE_FACESinbenilla-app/src/ui_text/engine/faces.rswith the face that draws it, so theazsFontdefault (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 inAZS_LANGUAGESnames its face infilewhen Friz cannot draw the name. - 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).
- Pack:
classes/<class>/class.toml(key,id= itsChrClassesid,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.tomlwith its three[[talent_tree]]s, and optionallyset_bonuses.tomlandpiece_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_pctis a share more on all the damage it deals,taken_pcta share more on every blow it takes (after armour),pickup_pcta 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 negativepickup_pctso it walks to what it drops; a talent'spickupstat (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 spellsbuildsandspends; the first fills the hero's power bar, the power line names each (chi=2;brew=1).hidden = truekeeps 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],CreatureDisplayInfoids): 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 aCharacter\model without anExtraDisplayInfo, 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 theirItem.dbcrow, whichstarter_weaponsthen names by entry. Missing items are skipped with a diagnostic. Setweapon_layouttomain_hand,dual_wieldorrangedto 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. Itsweapon_iconsare written withoutINV_(the readers add it), and each must name anItemDisplayInforow'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, sotools/demonhunter-patch.jsgives each row of an off-hand icon the mirrored twin of its right-hand model (<model>left, made bytools/m2-mirror.js, as 3.3.5a shipsGlave_1H_DualBlade_D_02leftbeside 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.rsshows_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 (UCline); 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 fromOPEN_CLASSESinweb/content.gen.js(generated: the classes with nounlockof their own); the daily mode sets no[unlocks], so the two lists agree, and survivors-simdaily.rstests 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 fileInterface\AzerothSurvivors\Talents\<token in lower case>, which only a client archive holds. The path is checked (presentation/,.png); list the file in the package'srequired_assetsto make the profile need it (the class binds it as a zone'siconbinds a Texture). Native only: a profile with a Texture object plays in no browser. The generator writes it intoAZS_GEN.classesastalentArt, for the classes that name one only. Testa_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'stone; 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_burststakes 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_HUESinentities/spell_fx/hue.rs), not any hue. Testa_spell_tone_is_a_palette_place,a_class_s_own_tone_stands_until_a_class_colour_is_worn.
- 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 aset_bonuses.tomlwrites them (see "A set bonus"); code scripts none for it.- Id.
idis aChrClassesid in 1..=31 (the client's class masks are1 << (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_knightisFROST_KNIGHT,warriorisWARRIOR). Tokens are unique; a second class with the same token fails content validation.
- Id.
- Client assets and DBC patches, only for a class with its own art:
azs-content genwritesGenerated/Classes.tsv(the glue root) andclassIconintoAZS_GEN.classes. The client addsChrClasses,CharBaseInfoandCharStartOutfitrows 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 (itsicon, 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 intoAZS_GEN.classesasgear. Pack gear takes precedence for every class. A set word's translations go underset|<word>, a weapon's under its name; - the run's damage meter takes the class's
colorfor a class its colour table lacks; - the create screen's weapon preview shows only weapons with an
Item.dbcrow (the class'sstarter_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 extraCharacterCreateClassButton<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.dbcrow 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 (
backgroundof each tree) and icons. Put each archive's letter intools/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 andCreatureDisplayInforows and the twelfth button; rebuild}after{, then~.
- 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 itsLocale_deDE_*entry. - Gates: a golden file per zone for the class (
game/golden.rscases, aGolden: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:
- Add the variant to
game/behaviors/mod.rsBehavior(orbehaviors/mutators.rs) with itskey, and its arm calling the family's code. - Put it in
game/hooks.rsORDERat its site, where its random draws belong; its state goes in the seat (STATE), never in the list. - Add its key to the matching list in
survivors-content/src/behaviors.rs(HOOKS,TALENTorMUTATOR); the test that holds the lists equal fails until both sides name it. - 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.
| Word | Where | Meaning |
|---|---|---|
mods = [{ bulwark = <yd> }] | talent | Earthen Bulwark's reduction (mods_v) holds while an enemy is within <yd> yards (the shaman 10, the monk and demon hunter 7) |
passive_gain | cards.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 effect | each jump of a chain hits <share> harder than the one before, and the chain loses nothing |
"crit_dotted" | legend effect | its hits always crit an enemy under one of the hero's damage-over-time effects |
dot_reap = <share> | legend effect | its 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.tsvbeside 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.jsonand its sources, check it withazs-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 underUserData/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 readsChoose?) 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.tomland itsspells.tomlin 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 atalents.tomlplays 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'sidgives 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"andkind = "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-modswrites 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]]inclasses/<folder>/talents.tomlof 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 atalents.tomlplays with none. - Talents added to a shipped class go in
classes/<class>/talents.tomlof the mod's package (the folder is the shipped class's key,mage), intree0 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 byrow): 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. Areqnames a talent of a row above, in the same tree. - Reworking a talent, a tree or a class is an override:
[[override]]withkind = "talent"(or"talent_tree","class"), itskeyand the fields it changes, declared in the lock (entity = "talent:arcane_focus", itsdependencythe package that defines it). A field replaces the old one whole (anameor atextcarries every language,effects,modsandplaysare 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.
- A new class writes its three trees and its talents. Each entry names the class by its whole
key (
- 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.rsand the Mods window inSurvivorsMods.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>.tomlper package (kind = "mod"or"map",namespace = "author.name",requires,status = "active" | "deprecated" | "blocked"with areasonfor the newest version,blocked = [{ version, reason }]for older ones, optional exact-bytemirrors).tools/packages.py pinwritespackages.jsonwith every kept version (up to 16, oldest first): each release zip's size, SHA-256 and profile summary. A zip holdsprofile.json, an optionalLICENSEand 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.jsonis never part ofindex.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 writespackages/catalog.json, then.sig(overazs package catalog\0and 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 refreshverifies the catalog, keeps it with its signature in one file (packages-catalog.jsonin the launcher state, the serial floor beside it) and writesUserData/mods/catalog.jsonfor 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 fromAZS_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 inSurvivorsMods.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.
- The folder. A profile root:
profile.jsonand the sources it locks (see "Local mod profiles"). Your package id isauthor.namein lower case, and it is the folderpacks/<id>/too. Ids that start withazs.are the game's own and are refused. A mod that changes an existing entry says so inprofile.json(overrides), as the example does forclass:mageandspell:fireball. - 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. - 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 oneazs-content profile-checkruns):frostmage-src: 462 objects locked, 1 rehashed; the game's preflight passes - Pack it.
azs-release profile-pack <folder> --out frostmage-v1.zipwrites the release zip (profile.json,LICENSEwhen 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 onlypacks/syiana.frostmage/. - Release it. A GitHub release of your repository with that zip as its asset; the asset name must fit the entry's
[source] assetpattern (frostmage-*.zip, where*is the version). - Register it. A pull request on
Syiana/azs-modswith 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, withpython tools/packages.py pin) fetches the release, checks the zip against the launcher's rules and pins it by size and SHA-256 inpackages.json(pinned frostmage v1 (1420409 bytes, sha256 ...)). - 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.luafile, not only the diff of the numbers. - 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, runsazs-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 uploadspackages/catalog.json.sig, thenpackages/catalog.json. The catalog shows in the Mods window of the clients that have it, under "Community packages". - 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 areason(orblocked = [{ 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):
| Field | Meaning |
|---|---|
schema | 1 |
key, map, map_name | the map file's, checked against it |
recipe_sha256 | the map file's SHA-256: the Community's recipe hash |
derivation | how the ground is built from the recipe (edited-ground-v1); a change to that is a new name |
base | every game file the edited ground reads, sorted: { path, state } with state "absent", "present" or { "exact": <BLAKE3> } |
draft_revision | the 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'sprofile.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 itsblocked/withdrawnmarker goes along; one whoseprofile.jsonlocks 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_lookupsaroundshare::validate_textandTerrain::load_editedatmax(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
mapobjects resolves them (ResolvedProfile::map_sources) and requiresauthored-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
| Piece | Where |
|---|---|
| Manifest, package objects, pairing, package folder reader | survivors-content/src/mappackage.rs, profile.rs (map_sources) |
| Lookup recorder | benilla-formats/src/chain.rs record_lookups |
| Frozen draft | survivors-sim/src/usermap.rs freeze |
| Export, base check, installed list, Community install | survivors-server/src/mappackage.rs (+ mappackage/tests.rs) |
Community verbs installed, play_installed, install, submit with package | survivors-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 package | SurvivorsCommunityMaps.lua |
Launcher install of kind = "map", blocks | azs-update/src/packages.rs (install_map, mark_blocked_maps) |
| Worker | web/community-maps.js, web/migrations/0042_community_map_packages.sql |
| Tests without an install | survivors-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).
| Table | Fields |
|---|---|
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.
