> For the complete documentation index, see [llms.txt](https://darkstarworks.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://darkstarworks.gitbook.io/plugins/mc/mt-documentation/tiers-yml.md). # tiers.yml Controls the difficulty curve, the anti-cheese guardrails, per-mob tuning, and how parties are resolved. Edit it, then `/tcpmt reload` — changes apply live, no restart needed. ## How the curve works Difficulty is authored as a list of **bands**. Each band covers a range of tiers and carries a flat set of knobs that applies to every tier in that range. You'll usually have 3–5 bands — early game, mid game, end game, and one or two Mythic bands for prestige. ```yaml bands: - tiers: "1-5" # tier range: "1-5", "13-20", "M1-M5", or single "20" / "M3" health-mult: 1.3 melee-mult: 1.25 # ... more knobs - tiers: "6-12" health-mult: 2.0 # ... ``` Tier ranges: * **`1` – `20`** — Standard tiers (write the bound as a plain number). * **`M1` – `M5`** — Mythic tiers (write the bound with an `M` prefix). * Mix them however you like — `tiers: "M1-M2"` is a band for the first two Mythic levels. A tier whose rank isn't covered by any band behaves like vanilla (no scaling), so you never have to define them all. ## Design intent: Standard vs Mythic The shipped defaults follow this philosophy — useful to know when tuning: * **Standard 1–20** is balanced against the **vanilla ceiling**: a top player in netherite + Protection IV, Smite V, a Density/Breach mace, totems, and golden apples. T20 should be hard but fair for that loadout. * **Mythic M1–M5** is **custom-gear headroom** — for servers where the best players run stronger-than-vanilla gear. The defaults are tuned at roughly ×1.5 (M1) up to ×2.5 (M5) of the T20 values. **They are not balanced for vanilla gear.** If your server is vanilla-only, lower these. ## The knobs Every knob is optional; omitted = the no-scaling default in brackets. ### Stat scaling (per-mob attributes) | Knob | Default | Effect | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `health-mult` | `1.0` | Multiplies max health. | | `melee-mult` | `1.0` | Multiplies outgoing melee damage. | | `spell-mult` | `1.0` | Multiplies outgoing projectile / fang / potion / area-effect damage. | | `speed-mult` | `1.0` | Multiplies movement speed. Hard-capped by `speed-max-multiplier`. | | `resistance-pct` | `0.0` | Incoming damage reduction, in percent. Capped by `resistance-max-pct`. The most reliable lever — a flat multiplier that survives crits, Smite, and Breach. | | `armor-add` | `0.0` | Flat `generic.armor` points added on top of the mob's base. | | `armor-toughness-add` | `0.0` | Flat `generic.armor_toughness` added. **Toughness is what keeps armor relevant against burst damage** — pair it with `armor-add`, don't add armor alone. | | `knockback-resistance` | `0.0` | Absolute 0–1 target (1.0 = full knockback immunity). Replaces the base rather than scaling it. | | `follow-range-mult` | `1.0` | Multiplies `generic.follow_range` — how far the mob aggros from. | | `scale-mult` | `1.0` | Multiplies `generic.scale`. Physically enlarges the mob *and* its hitbox / melee reach. Doubles as a visual tier telegraph. Capped by `scale-max-multiplier`. | | `attack-knockback-add` | `0.0` | Flat `generic.attack_knockback` — extra knockback the mob **deals**. The lever that lets high-tier mobs shove players into chamber hazards (lava pits, ledges). | | `absorption-add` | `0.0` | Flat absorption "shield" hearts granted at spawn. Sits above the health pool, sidesteps the vanilla 1024 max-health ceiling, reads as yellow hearts. Capped by `absorption-max`. | ### Equipment Dresses a scaled mob in a random gear set at spawn, no drops. Skipped on ranged mobs holding a bow/crossbow (replacing their weapon would break their attack AI). ```yaml equipment: apply-to-providers: ["vanilla"] # "*" to also dress custom-provider mobs chance: 0.7 # 0..1; roll per spawn sets: - helmet: { type: DIAMOND_HELMET, enchants: { protection: 2 } } chestplate: { type: DIAMOND_CHESTPLATE, enchants: { thorns: 2, protection: 2 } } leggings: { type: DIAMOND_LEGGINGS, enchants: { protection: 2 } } boots: { type: DIAMOND_BOOTS, enchants: { protection: 2 } } ``` * Slots: `main-hand`, `off-hand`, `helmet`, `chestplate`, `leggings`, `boots`. * `enchants:` accepts both modern names (`protection`, `sharpness`) and legacy ones (`protection_environmental`, `damage_all`). Over-levelling works (`protection: 9` etc.). ### Permanent spawn effects Status effects applied once when the mob spawns. Use for permanent buffs like Speed II or Regeneration. ```yaml effects: - { type: speed, amplifier: 1, permanent: true } - { type: regeneration, amplifier: 0, permanent: true } ``` Avoid `resistance` here — incoming-damage reduction is already handled by `resistance-pct` above; stacking would double-dip. ### On-hit punishment What a player suffers when this band's mobs land a hit. ```yaml on-hit: effects: - { type: wither, duration: 60, amplifier: 1, chance: 0.35 } - { type: blindness, duration: 40, amplifier: 0, chance: 0.35 } true-damage-fraction: 0.25 true-damage-type: armor_piercing # or "unblockable" anti-heal-ticks: 60 ``` * **`effects`** — status effects rolled per hit (`chance` is per-effect). * **`true-damage-fraction`** — a portion of the hit (0–1) dealt as a *separate* damage event that bypasses armor points. Counts against the one-shot cap, not on top of it. * **`true-damage-type`** — * `armor_piercing` = MAGIC damage. Ignores armor points, but Protection and Resistance still reduce it. Respects totems. The right counter to stacked Prot-IV netherite. * `unblockable` = bypasses armor, Protection, Resistance, and totems. The nuclear option — the one-shot cap still prevents a full-HP instakill, but otherwise nothing mitigates it. Reserve for Mythic. * **`anti-heal-ticks`** — how many ticks the victim cannot regain health after being hit. 20 = 1 second. Attacks the gapple-sustain meta. ### Spawn dynamics Tunes the trial spawner's behaviour for the chamber's effective tier. ```yaml spawn: simultaneous-bonus: 3 # extra mobs allowed alive at once (0 = unchanged) cooldown-mult: 0.7 # multiplier on the inter-wave cooldown (<1 = faster waves) horde-intensity: 7 # 1-10 wave-pacing dial (5 = vanilla) ``` A swarm beats single-target burst — mace and Smite hit one mob, so raising `simultaneous-bonus` is often more effective than raising HP. **`horde-intensity`** controls how "all at once" a wave arrives, on a 1–10 dial where **5 is vanilla** (the spawner is left untouched): * **Below 5** stretches the gap between individual mob spawns — a slow trickle (1 = almost glacial). * **Above 5** compresses that gap toward a single burst, and at **8+** it also raises a floor on how many mobs may be alive at once so a whole wave can be on the field together. **10 = full horde-fest** (the wave dumps near-instantly). It drives the spawner's `ticks_between_spawn` and `simultaneous_mobs` directly; the vanilla baselines are restored automatically on every chamber reset, so it never compounds across cycles. Set a **server-wide default** with the root-level `horde-intensity:` key (also 1–10, default 5). Any band that doesn't set its own `spawn.horde-intensity` inherits it: ```yaml # top of tiers.yml, alongside party-resolution horde-intensity: 5 # default for every band that omits its own ``` ## Per-mob overrides Bands scale every mob identically. `mob-overrides` lets specific entity types scale differently, so casters don't become unkillable and weak-by- design mobs stay relevant. ```yaml mob-overrides: evoker: health: 0.6 # ignore 40% of the band's health bonus spell: 0.4 cave_spider: health: 0.5 resistance: 0.4 armor: 0.4 bogged: health: 1.3 # buff a weak-by-design mob melee: 1.25 witch: spell: 0.5 vex: health: 0.5 ``` Each factor is a multiplier on that stat's band contribution: `1.0` = unchanged, `0.0` = mob ignores the tier's boost for that stat, `>1` = amplified. For the multiplier stats (`health`, `melee`, `spell`, `speed`, `follow-range`) the factor scales the *bonus*; for the rest (`resistance`, `armor`, `armor-toughness`, `knockback-resistance`) it scales the magnitude. Available factors: `health`, `melee`, `spell`, `speed`, `resistance`, `armor`, `armor-toughness`, `knockback-resistance`, `follow-range`. {% hint style="info" %} **Smite reality.** Most chamber mobs are undead (zombies, husks, skeletons, strays, bogged), so a player with Smite V deletes raw HP. Don't fight this by inflating band HP for everyone — it'll over-tune the non-undead (spiders, breezes). Bump undead mob-overrides instead. {% endhint %} ## Guardrails Anti-cheese clamps applied **after** the per-band values. They make it safe to push numbers high without breaking fairness. ```yaml guardrails: resistance-max-pct: 65 # mobs are never immune speed-max-multiplier: 1.5 # mobs stay catchable on foot damage-cap-fraction: 0.75 # one hit ≤ 75% of a player's max health scale-max-multiplier: 3.0 # absolute cap on generic.scale absorption-max: 40 # cap on absorption hearts per mob ``` * **`resistance-max-pct`** — incoming damage reduction is clamped here no matter how high a band sets `resistance-pct`. Range 0–99. * **`speed-max-multiplier`** — absolute ceiling on movement speed. Range ≥1.0. * **`damage-cap-fraction`** — the headline anti-one-shot rule. A single mob hit (including the true-damage portion) can never remove more than this fraction of the victim's maximum health. At 0.75, a full-health player always survives at least one hit from anything, at any tier, including unblockable true damage at M5. Range 0.1–1.0. * **`scale-max-multiplier`** — absolute cap on `scale-mult`. Vanilla allows up to 16; the default of 3.0 keeps mobs from clipping inside low-ceiling rooms. * **`absorption-max`** — cap on the absorption hearts a single mob can be granted at spawn (vanilla allows up to 2048). ## Party resolution When several players are inside a chamber together, whose tier do the mobs scale to? ```yaml party-resolution: lowest # lowest | highest | host | average ``` | Strategy | Behaviour | | -------------------- | ------------------------------------------------------------------------------------------ | | `lowest` *(default)* | Match the least-progressed player. Fair to newcomers; lets veterans help friends. | | `highest` | Match the most-progressed player. Aspirational — the group rides the veteran's difficulty. | | `host` | A designated leader's tier. Falls back to `lowest` if no leader is set. | | `average` | The party's average rank, rounded down. | ## Tuning tips * **Don't pour budget into `armor-add` alone.** Vanilla's damage formula decays armor against burst, and the **Breach** enchantment erases up to 60% of it. Always pair `armor-add` with `armor-toughness-add`, or shift that budget into `resistance-pct` (which Breach can't touch). * **Resistance is your most reliable lever.** A flat multiplier that survives crits, Smite V, Breach, and armor-piercing true damage. If a band feels too easy against geared players, raise this before anything else. * **Use true damage to bite the Prot-IV netherite meta.** The shipped 13–20 band lands \~12% armor-piercing true damage for exactly this reason. If your top players still trivialise it, raise the fraction or switch to `unblockable` for that band. * **Swarm beats burst.** Mace and Smite hit one mob. Raising `spawn.simultaneous-bonus` is often more effective than raising HP. * **Reach for `horde-intensity` when you want pressure, not just numbers.** Pushing it to 8–10 makes a wave arrive all at once instead of trickling — a very different feel from the same mobs spread over time. Set it once at the root for a server-wide vibe, then bump individual high-tier bands. * **Speed and scale are subtle by default.** A `speed-mult` of 1.1 is barely noticeable; `scale-mult` of 1.1 is a 10% bigger silhouette. Use them as flavour, not as the main difficulty driver. *** Next: [**chambers.yml →**](/plugins/mc/mt-documentation/chambers-yml.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://darkstarworks.gitbook.io/plugins/mc/mt-documentation/tiers-yml.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.