Wikis / MythicRPG / Archetypes / Swap Rules

Swap Rules

Swap Rules control what happens when a player switches archetypes inside a group: what happens to their level/xp, whether they have to wait between swaps, whether the swap costs currency, and whether they need a permission node to do it at all.

Rules can be set as a server-wide default and overridden per-group, so CLASS swaps can behave completely differently from PROFESSION swaps.

Where to configure

Swap Rules live in config-archetypes.yml. The server-wide default sits under Configuration.DefaultSwapRule, and per-group overrides go inside each entry under Configuration.ArchetypeGroups, alongside that group's Display and LevelUpMessage:

Configuration:
  DefaultSwapRule:
    LevelMode: PER_CLASS
    Cooldown: 0
    Cost: 0
    Permission: ''

  ArchetypeGroups:
    - Group: CLASS
      Display: 'Class'
      LevelUpMessage: '<green>Your {group} leveled up to <gold>{level}<green>!'
      SwapRule:
        LevelMode: PER_CLASS
        Cooldown: 0
        Cost: 0
        Permission: ''

DefaultSwapRule applies to every archetype group that doesn't define its own SwapRule: block. When a group does define a SwapRule: block, it is merged over DefaultSwapRule per field: any of LevelMode, Cooldown, Cost, or Permission the group omits inherits that field's value from DefaultSwapRule.

Level-up message

LevelUpMessage is an optional per-group message sent to the player whenever an archetype in that group gains a level. Leave it empty (or omit it) to send nothing. It supports these placeholder tokens:

Token Replaced with
{group} The group's Display name
{group_id} The group's internal id
{archetype} The leveled archetype's display name
{archetype_id} The leveled archetype's internal name
{previous_level} The level before the level-up
{level} The new level
{max_level} The archetype's MaxLevel
{experience} The archetype's current experience
{next_experience} Experience needed for the next level, or MAX at cap

The four rules

Rule Type Default Description
LevelMode enum PER_CLASS How level + xp are handled when a player swaps archetypes within the group.
Cooldown seconds 0 Minimum time the player must wait between two swaps in the same group. 0 disables the cooldown.
Cost number 0 Amount of Vault currency deducted on a successful swap. 0 makes it free.
Permission string '' Permission node the player must have to swap within this group. Empty = no permission required.

LevelMode

Value Behavior
PER_CLASS Each archetype keeps its own level and xp independently. Swapping back to a previous archetype restores its level and xp exactly as you left it. The classic D&D-multiclass feel.
MIRRORED Every archetype the player has unlocked in the group shares the same level. When the active archetype levels up, every other unlocked archetype in the group is bumped to the same level. XP stays per-archetype. The "player level" feel.
RESET The previous archetype's level and xp are wiped on swap. Players start the new archetype fresh, and there's no going back to where they were. The "commit to your choice" feel.

MIRRORED notes

  • Mirroring kicks in on level-up, not on swap. Already-unlocked archetypes have their level bumped to match the actively-leveled one.
  • Mirroring does not re-fire per-level rewards (point grants, SpellUnlocks) for the inactive archetypes. Only the actively-leveled archetype receives its rewards. This prevents one xp gain from multiplying rewards across every archetype in the group.
  • Mirroring respects each archetype's MaxLevel (an archetype with MaxLevel: 30 won't be pushed past 30 even if another archetype in the group hits 50).
  • An archetype that's already at a higher level than the leveled one is left alone (mirroring never demotes).

Cooldown

After a successful swap, the player can't swap again in that group until the cooldown elapses. The cooldown is per-group, so a CLASS cooldown does not block PROFESSION swaps and vice versa.

The remaining time is shown to the player in the "You must wait Xs before switching … again" error. The cooldown timestamp is persisted with the profile, so cooldowns survive logouts and server restarts.

Cost

Requires Vault (or VaultUnlocked) installed with a registered economy provider. If Vault isn't present and Cost > 0, the swap is blocked with a clear error message.

The full cost is checked before the swap and deducted atomically. If the swap is cancelled (by a plugin listening to MythicArchetypeChangeEvent) or fails internally, the cost is automatically refunded.

Permission

Standard Bukkit permission node. If set, the player must have the permission to swap in this group. Useful for gating premium classes behind a rank, restricting RACE swaps to admins, etc.

Enforcement

Swap Rules are enforced on the player-facing swap paths:

  • /archetype choose <group> <archetype> (the player command)
  • The archetype_choose skill command function
  • The choose_archetype menu function

Admin commands and the setArchetype skill mechanic bypass cooldown, cost, and permission checks: they call Profile#setArchetype directly, so admins and quest scripts can always force a swap regardless of what the player could do themselves. The LevelMode is honored on every swap path, including admin-forced swaps. Forcing a swap in a RESET-mode group will still wipe the prior archetype's progress.

The default-archetype assignment for new players (Configuration.DefaultArchetypes) also bypasses the rules.

Backward compatibility

Older configs use a single boolean (Configuration.Profiles.SaveArchetypeDataOnSwitch in config-rpg.yml) instead of the structured SwapRule blocks. That option is now deprecated but still honored as a fallback when DefaultSwapRule.LevelMode is unset:

Legacy value Equivalent LevelMode
SaveArchetypeDataOnSwitch: true PER_CLASS
SaveArchetypeDataOnSwitch: false RESET

Existing servers upgrading don't need to touch their config. The legacy boolean keeps working exactly as before. Migrate to the new blocks when you want per-group overrides, mirroring, cooldowns, costs, or permission gates.

Examples

Classic multiclass: per-class level, free swaps

Configuration:
  DefaultSwapRule:
    LevelMode: PER_CLASS
    Cooldown: 0
    Cost: 0
    Permission: ''

Players can swap freely. Each class keeps its own progression. Switching back is lossless.

Player-level RPG: single shared level across classes in a group

Configuration:
  DefaultSwapRule:
    LevelMode: MIRRORED

Every unlocked archetype in a given group shares its level with every other unlocked archetype in that group. XP is still earned per-archetype, so each can be progressed independently in terms of activities; only level is mirrored.

Punishing class commitment

Configuration:
  DefaultSwapRule:
    LevelMode: RESET
    Cooldown: 86400
    Cost: 5000
    Permission: 'mythicrpg.swap.class'

Switching wipes your progress, costs 5000 currency, can only happen once per day, and requires a permission node. Use this when you want class identity to feel weighty and permanent.

Different rules per group

Configuration:
  DefaultSwapRule:
    LevelMode: PER_CLASS

  ArchetypeGroups:
    - Group: CLASS
      Display: 'Class'
      SwapRule:
        LevelMode: MIRRORED
        Cooldown: 600
        Cost: 100

    - Group: PROFESSION
      Display: 'Profession'
      SwapRule:
        LevelMode: PER_CLASS
        Cooldown: 0
        Cost: 0

    - Group: RACE
      Display: 'Race'
      SwapRule:
        LevelMode: RESET
        Permission: 'mythicrpg.swap.race'
  • Combat classes share level within the CLASS group and have a 10-minute cooldown + small currency cost.
  • Professions are completely free to swap between, each with its own progression.
  • Races are a permission-gated, progress-wiping commitment.

See also

Updated Aug 19, 2026