Phase System

Phases allow Titans to evolve during the fight, unlocking new moves, gaining stat boosts, and changing movement behavior as their health depletes.

How Phases Work

graph LR
    A[100% HP
Phase 1] -->|Drops below 66%| B[66% HP
Phase 2]
    B -->|Drops below 33%| C[33% HP
Phase 3]

    style A fill:#4a9eff
    style B fill:#e67e22
    style C fill:#e74c3c

Phases trigger at health thresholds (100%, 66%, 33%, etc.)
Each phase can have:
- Different move pools
- Stat modifiers (speed, damage, scale)
- Movement pattern changes
- Movement controller overrides (NEW!)
- On-enter/exit scripts
- Optional state machines

Phase Configuration Location

File: config/titan/phases/{phaseSet}.json

Phases are stored in separate files referenced by fight manifests:

{
  "pokemonProperties": "raichu",
  "name": "Storm Surge Titan Raichu",
  "phaseSet": "raichu"  // ← References config/titan/phases/raichu.json
}

See: Fight Configurations →

Basic Phase Structure

{
  "phases": [
    {
      "healthThreshold": 1.0,
      "moves": ["storm_call", "thunderstrike", "chain_lightning"],
      "speedModifier": 1.15,
      "damageModifier": 1.0,
      "scaleModifier": 1.1,
      "movementPattern": "KITING",
      "aggressionLevel": 1.2,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 0);",
      "onExitScript": "q.titan.remove_potion('minecraft:speed');",
      "movementOverrides": {
        "kiting": {
          "preferredDistance": 8.0,
          "circleSpeed": 1.1
        }
      }
    }
  ]
}

Core Phase Properties

`healthThreshold` (Required)

Health percentage when phase activates (1.0 = 100%, 0.5 = 50%):

// Phase 1: Full health
"healthThreshold": 1.0

// Phase 2: Below 66%
"healthThreshold": 0.66

// Phase 3: Below 33%
"healthThreshold": 0.33

// Bonus Phase: Below 10% (enrage!)
"healthThreshold": 0.1

`moves` (Required)

Array of move IDs available in this phase (references move set):

// Phase 1: Basic attacks only
"moves": ["storm_call", "thunderstrike", "chain_lightning"]

// Phase 2: Add stronger moves
"moves": ["storm_surge", "electroweb", "thunder_cage", "spark_clone"]

// Phase 3: Ultimate moves
"moves": ["thunderbolt_barrage", "volt_tackle", "gigavolt_havoc"]

Tips:

Start with 3-5 moves per phase
Add complexity in later phases
Ensure moves exist in the move set
Consider move cooldowns for variety

See: Move Sets →

`speedModifier` (Required)

Movement speed multiplier:

"speedModifier": 1.0   // Normal speed
"speedModifier": 1.25  // 25% faster
"speedModifier": 1.5   // 50% faster
"speedModifier": 0.8   // 20% slower

Raichu Progression Example:

// Phase 1
"speedModifier": 1.15   // Slightly faster

// Phase 2
"speedModifier": 1.28  // Noticeably faster

// Phase 3
"speedModifier": 1.4   // Very fast

`damageModifier` (Required)

Attack damage multiplier:

"damageModifier": 1.0   // Normal damage
"damageModifier": 1.3   // 30% more damage
"damageModifier": 1.6   // 60% more damage
"damageModifier": 2.0   // Double damage

Raichu Progression Example:

// Phase 1
"damageModifier": 1.0   // Base damage

// Phase 2
"damageModifier": 1.2   // +20% damage

// Phase 3
"damageModifier": 1.35   // +35% damage

`scaleModifier` (Required)

Visual size multiplier (doesn’t affect hitboxes):

"scaleModifier": 1.3   // 30% larger
"scaleModifier": 1.4   // 40% larger
"scaleModifier": 1.5   // 50% larger

Typical Progression:

// Phase 1
"scaleModifier": 1.1

// Phase 2
"scaleModifier": 1.15

// Phase 3
"scaleModifier": 1.2   // Imposing final form

`movementPattern` (Required)

Default movement controller for this phase:

Pattern	Controller	Best For
`STANDARD`	Ground patrol	Default fallback
`HIT_AND_RUN`	Hit-and-run	Melee strikers
`TELEPORT`	Teleport blink	Psychic/Ghost types
`KITING`	Kiting	Ranged attackers
`FLYING_BOMBER`	Flying bomber	Dive attackers
`FLYING_CIRCLER`	Flying circler	Aerial casters
`FLYING_RUSH`	Flying rush	Aggressive flyers
`BERSERKER`	Berserker	High aggression
`DEFENSIVE`	Defensive	Tanks
`ENRAGED`	Enraged	Low HP berserk
`ZIGZAG`	Zigzag	Evasive
`PERCHED`	Perched	Flying with landing
`RUSH`	Berserker	Legacy alias

Raichu Example:

// Phase 1: Ranged positioning
"movementPattern": "KITING"

// Phase 2: Teleport combat
"movementPattern": "TELEPORT"

// Phase 3: Aggressive rushdown
"movementPattern": "RUSH"

See: Movement Controllers →

`aggressionLevel` (Optional, default: 1.0)

How aggressively Titan pursues target:

"aggressionLevel": 1.0   // Normal
"aggressionLevel": 1.5   // More aggressive
"aggressionLevel": 2.0   // Very aggressive
"aggressionLevel": 0.5   // Defensive

Higher = closer positioning, more frequent attacks.

Raichu Progression:

// Phase 1
"aggressionLevel": 1.2

// Phase 2
"aggressionLevel": 1.5

// Phase 3
"aggressionLevel": 1.8

Movement Overrides (NEW!)

Key Feature

New in Rewrite

Per-phase movement controller configuration overrides

The movementOverrides property allows fine-tuning movement behavior per phase:

{
  "healthThreshold": 0.6,
  "movementPattern": "TELEPORT",
  "movementOverrides": {
    "teleport": {
      "minRange": 4.0,
      "maxRange": 8.0,
      "radialCandidates": 10,
      "heightVariance": 2.5,
      "cooldownMs": 12000
    }
  }
}

Available Override Types

Teleport Blink Override

"movementOverrides": {
  "teleport": {
    "minRange": 4.0,           // Minimum teleport distance
    "maxRange": 8.0,           // Maximum teleport distance
    "radialCandidates": 10,    // Number of positions to evaluate
    "heightVariance": 2.5,     // Vertical offset range (±2.5)
    "cooldownMs": 12000        // Time between teleports (ms)
  }
}

Raichu Example:

// Phase 2 (60% HP) - Moderate teleportation
{
  "healthThreshold": 0.6,
  "movementPattern": "TELEPORT",
  "movementOverrides": {
    "teleport": {
      "minRange": 4.0,
      "maxRange": 8.0,
      "cooldownMs": 12000
    }
  }
}

// Phase 3 (35% HP) - Aggressive teleportation
{
  "healthThreshold": 0.35,
  "movementPattern": "TELEPORT",
  "movementOverrides": {
    "teleport": {
      "minRange": 3.0,
      "maxRange": 6.0,
      "cooldownMs": 8000  // Faster teleports!
    }
  }
}

Hit-and-Run Override

"movementOverrides": {
  "hitAndRun": {
    "approachSpeed": 1.3,      // Speed multiplier during approach
    "retreatSpeed": 1.5,       // Speed multiplier during retreat
    "strikeRange": 3.0,        // Distance to trigger strike
    "retreatDistance": 8.0,    // How far to retreat
    "cooldownMs": 5000         // Time before next cycle
  }
}

Example Progression:

// Phase 1 - Cautious
"movementOverrides": {
  "hitAndRun": {
    "approachSpeed": 1.2,
    "retreatSpeed": 1.4,
    "cooldownMs": 5000
  }
}

// Phase 3 - Aggressive
"movementOverrides": {
  "hitAndRun": {
    "approachSpeed": 1.5,
    "retreatSpeed": 1.3,
    "cooldownMs": 2000  // Relentless attacks
  }
}

Kiting Override

"movementOverrides": {
  "kiting": {
    "preferredDistance": 8.0,  // Ideal range from target
    "minDistance": 6.0,        // Too close threshold
    "maxDistance": 12.0,       // Too far threshold
    "circleSpeed": 1.1         // Strafing speed multiplier
  }
}

Flying Bomber Override

"movementOverrides": {
  "flyingBomber": {
    "cruiseAltitude": 12.0,    // Height while circling
    "diveSpeed": 1.8,          // Speed during dive
    "ascentSpeed": 1.3,        // Speed climbing back
    "attackAltitude": 3.0      // Dive endpoint height
  }
}

Flying Circler Override

"movementOverrides": {
  "flyingCircler": {
    "altitude": 10.0,          // Fixed flight height
    "orbitRadius": 8.0,        // Circle radius
    "orbitSpeed": 1.2          // Rotation speed
  }
}

Flying Rush Override

"movementOverrides": {
  "flyingRush": {
    "rushSpeed": 2.0,          // Direct charge speed
    "minAltitude": 4.0,        // Minimum height
    "maxAltitude": 8.0         // Maximum height
  }
}

Berserker Override

"movementOverrides": {
  "berserker": {
    "chargeSpeed": 1.6,        // Forward charge speed
    "ignoreHealth": false      // Charge regardless of HP
  }
}

Defensive Override

"movementOverrides": {
  "defensive": {
    "safeDistance": 10.0,      // Preferred distance
    "retreatThreshold": 0.5    // HP % to start retreating
  }
}

Enraged Override

"movementOverrides": {
  "enraged": {
    "speed": 2.0,              // Movement speed multiplier
    "healthThreshold": 0.2     // HP % to activate
  }
}

Zigzag Override

"movementOverrides": {
  "zigzag": {
    "zigSpeed": 1.4,           // Movement speed
    "zigInterval": 1000,       // Time between direction changes (ms)
    "zigAngle": 45             // Angle of lateral movement
  }
}

Perched Override

"movementOverrides": {
  "perched": {
    "perchDuration": 5000,     // Time on ground (ms)
    "flyDuration": 8000        // Time in air (ms)
  }
}

Movement Override Matching

The override key must match the controller type. If movementPattern is "TELEPORT", use "teleport" as the override key (lowercase).

Pattern → Override Key:

TELEPORT → teleport
HIT_AND_RUN → hitAndRun
KITING → kiting
FLYING_BOMBER → flyingBomber
etc.

Phase Scripts

`onEnterScript` (Optional)

MoLang executed when entering phase:

// Simple particle effect
"onEnterScript": "q.particle_effect('cobblemon:thunder_actorcloud', q.position(0), 180, 3.5);"

// Multiple effects with sound
"onEnterScript": "q.particle_effect('minecraft:electric_spark', q.position(0), 180, 3.5); q.play_sound('minecraft:entity.lightning_bolt.thunder', 0.7, 1.3);"

// Apply buffs
"onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 0); q.titan.apply_potion('minecraft:haste', 999999, 0);"

// Complex phase transition (Raichu Phase 3)
"onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 2); q.titan.apply_potion('minecraft:strength', 999999, 1); q.titan.apply_potion('minecraft:resistance', 999999, 1); q.invoke_move('overcharge'); q.play_sound('minecraft:entity.lightning_bolt.thunder', 1.1, 0.9);"

Common Patterns:

Particle burst
Buff application
Sound effect
Invoke move (special attack)
Heal to threshold

`onExitScript` (Optional)

MoLang executed when leaving phase:

"onExitScript": "q.titan.remove_potion('minecraft:speed'); q.titan.remove_potion('minecraft:haste');"

Used to clean up phase-specific effects.

Complete Phase Examples

Raichu Three-Phase Progression

Full config from phases/raichu.json:

{
  "phases": [
    {
      "healthThreshold": 1.0,
      "moves": [
        "storm_call",
        "thunderstrike",
        "chain_lightning",
        "discharge_nova",
        "lightning_dash"
      ],
      "speedModifier": 1.15,
      "damageModifier": 1.0,
      "scaleModifier": 1.1,
      "movementPattern": "KITING",
      "aggressionLevel": 1.2,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 0); q.titan.apply_potion('minecraft:haste', 999999, 0); q.particle_effect('minecraft:electric_spark', q.position(0), 180, 3.5); q.play_sound('minecraft:entity.lightning_bolt.thunder', 0.7, 1.3);",
      "onExitScript": "q.titan.remove_potion('minecraft:speed'); q.titan.remove_potion('minecraft:haste');"
    },
    {
      "healthThreshold": 0.6,
      "moves": [
        "storm_surge",
        "electroweb",
        "thunder_cage",
        "spark_clone",
        "magnetic_flux",
        "lightning_dash",
        "lightning_rod"
      ],
      "speedModifier": 1.28,
      "damageModifier": 1.2,
      "scaleModifier": 1.15,
      "movementPattern": "TELEPORT",
      "aggressionLevel": 1.5,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 1); q.titan.apply_potion('minecraft:strength', 999999, 0); q.invoke_move('spark_clone'); q.play_sound('minecraft:block.beacon.activate', 0.9, 1.6);",
      "onExitScript": "q.titan.remove_potion('minecraft:speed'); q.titan.remove_potion('minecraft:strength');",
      "movementOverrides": {
        "teleport": {
          "minRange": 4.0,
          "maxRange": 8.0,
          "radialCandidates": 10,
          "heightVariance": 2.5,
          "cooldownMs": 12000
        }
      }
    },
    {
      "healthThreshold": 0.35,
      "moves": [
        "thunderbolt_barrage",
        "volt_tackle",
        "gigavolt_havoc",
        "overcharge",
        "storm_surge",
        "lightning_rod"
      ],
      "speedModifier": 1.4,
      "damageModifier": 1.35,
      "scaleModifier": 1.2,
      "movementPattern": "RUSH",
      "aggressionLevel": 1.8,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 2); q.titan.apply_potion('minecraft:strength', 999999, 1); q.titan.apply_potion('minecraft:resistance', 999999, 1); q.invoke_move('overcharge'); q.play_sound('minecraft:entity.lightning_bolt.thunder', 1.1, 0.9);",
      "onExitScript": "q.titan.remove_potion('minecraft:speed'); q.titan.remove_potion('minecraft:strength'); q.titan.remove_potion('minecraft:resistance');"
    }
  ]
}

Progression Analysis:

Phase 1 (100%): KITING, ranged combat, Speed I
Phase 2 (60%): TELEPORT with tuned parameters, Speed II + Strength I
Phase 3 (35%): RUSH (berserker), Speed III + Strength II + Resistance I

Simple Two-Phase Boss

{
  "phases": [
    {
      "healthThreshold": 1.0,
      "moves": ["basic_attack", "special_attack"],
      "speedModifier": 1.0,
      "damageModifier": 1.0,
      "scaleModifier": 1.3,
      "movementPattern": "STANDARD",
      "aggressionLevel": 1.0
    },
    {
      "healthThreshold": 0.5,
      "moves": ["special_attack", "ultimate"],
      "speedModifier": 1.3,
      "damageModifier": 1.5,
      "scaleModifier": 1.4,
      "movementPattern": "BERSERKER",
      "aggressionLevel": 1.6,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 1); q.particle_effect('minecraft:explosion', q.position(0), 50, 3.0);"
    }
  ]
}

Four-Phase Enrage Boss

{
  "phases": [
    {
      "healthThreshold": 1.0,
      "moves": ["basic_attack"],
      "speedModifier": 1.0,
      "damageModifier": 1.0,
      "scaleModifier": 1.3,
      "movementPattern": "STANDARD",
      "aggressionLevel": 1.0
    },
    {
      "healthThreshold": 0.66,
      "moves": ["basic_attack", "special_attack"],
      "speedModifier": 1.2,
      "damageModifier": 1.2,
      "scaleModifier": 1.35,
      "movementPattern": "HIT_AND_RUN",
      "aggressionLevel": 1.3,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 0);",
      "movementOverrides": {
        "hitAndRun": {
          "approachSpeed": 1.2,
          "retreatSpeed": 1.3,
          "cooldownMs": 5000
        }
      }
    },
    {
      "healthThreshold": 0.33,
      "moves": ["special_attack", "ultimate"],
      "speedModifier": 1.4,
      "damageModifier": 1.5,
      "scaleModifier": 1.4,
      "movementPattern": "HIT_AND_RUN",
      "aggressionLevel": 1.6,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 1); q.titan.apply_potion('minecraft:strength', 999999, 0);",
      "movementOverrides": {
        "hitAndRun": {
          "approachSpeed": 1.4,
          "retreatSpeed": 1.4,
          "cooldownMs": 3000
        }
      }
    },
    {
      "healthThreshold": 0.1,
      "moves": ["ultimate"],
      "speedModifier": 1.8,
      "damageModifier": 2.0,
      "scaleModifier": 1.5,
      "movementPattern": "ENRAGED",
      "aggressionLevel": 2.5,
      "onEnterScript": "q.titan.apply_potion('minecraft:speed', 999999, 2); q.titan.apply_potion('minecraft:strength', 999999, 2); q.titan.apply_potion('minecraft:resistance', 999999, 1); q.particle_effect('minecraft:explosion_emitter', q.position(0), 20, 4.0); q.play_sound('minecraft:entity.wither.spawn', 1.0, 0.8);",
      "movementOverrides": {
        "enraged": {
          "speed": 2.0,
          "healthThreshold": 0.1
        }
      }
    }
  ]
}

Balancing Phases

Difficulty Curve

Phase	Speed Modifier	Damage Modifier	Aggression	Movement
1	1.0-1.15	1.0	1.0-1.2	KITING/STANDARD
2	1.2-1.3	1.2-1.3	1.3-1.5	TELEPORT/HIT_AND_RUN
3	1.4-1.5	1.3-1.6	1.6-2.0	RUSH/BERSERKER
Enrage	1.7-2.0	1.8-2.5	2.0-3.0	ENRAGED

Move Pool Progression

Phase 1: Foundation

3-5 basic moves
Low-medium cooldowns
Simple patterns
Easy to learn

Phase 2: Complexity

4-7 moves
Add movement mechanics (teleport, hit-and-run)
Mix of simple and complex
Test player skill

Phase 3: Ultimate

3-6 moves
At least one ultimate (300+ cooldown)
High damage, high risk
Vulnerability windows critical

Movement Progression Strategies

Strategy 1: Escalating Mobility

Phase 1: STANDARD (predictable)
Phase 2: HIT_AND_RUN (tactical)
Phase 3: TELEPORT (chaotic)

Strategy 2: Range Shift

Phase 1: KITING (maintain distance)
Phase 2: TELEPORT (close gaps)
Phase 3: RUSH (aggressive pursuit)

Strategy 3: Aerial Assault

Phase 1: FLYING_CIRCLER (safe circling)
Phase 2: FLYING_BOMBER (dive attacks)
Phase 3: FLYING_RUSH (relentless charges)

Duration Targets

Phase 1: 40-50% of fight time (learning phase)
Phase 2: 30-40% of fight time (mechanics test)
Phase 3: 20-30% of fight time (ultimate challenge)

Balance with move damage, cooldowns, and HP pool.

Troubleshooting

Phase Not Triggering

Symptoms: Titan stays in Phase 1

Fixes:

✅ Check healthThreshold order (must be descending: 1.0, 0.66, 0.33)
✅ Verify Titan health drops below threshold
✅ Check logs for phase transition messages
✅ Ensure config is reloaded (/titan reload)
✅ Verify phaseSet ID exists in config/titan/phases/

Phase Skipping

Symptoms: Titan goes from Phase 1 → Phase 3 directly

Causes:

Health dropped too fast (high player DPS)
Multiple phases with same threshold

Fixes:

Add onEnterScript heal to threshold: q.heal_to_percent(0.66);
Reduce player damage output
Increase Titan max HP
Add immunity period on phase enter

Movement Overrides Not Working

Symptoms: Titan uses default movement parameters

Fixes:

✅ Check override key matches pattern (TELEPORT → "teleport")
✅ Verify movementPattern is set correctly
✅ Ensure all required properties in override are present
✅ Check logs for override parsing errors
✅ Verify phase config is valid JSON

Stat Modifiers Not Applying

Symptoms: Titan doesn’t get faster/stronger

Fixes:

✅ Buffs last 999999 ticks (~13 hours real-time)
✅ Check potion effect IDs are correct (minecraft:speed)
✅ Amplifier: 0 = Level I, 1 = Level II, etc.
✅ Verify onEnterScript syntax (semicolons, quotes)
✅ Check MoLang errors in logs

Scripts Not Executing

Symptoms: No particles/sounds on phase enter

Fixes:

✅ Use new MoLang syntax: q.titan.apply_potion (not q.apply_potion)
✅ Check semicolons at end of each statement
✅ Verify string quotes (single ' for MoLang strings)
✅ Check function names (see Server MoLang reference)

See: Server MoLang →

Next Steps

Move Sets

Define which moves appear in each phase

Move Sets →

Movement Controllers

Configure AI movement patterns

Movement Controllers →

Server MoLang

Script phase transitions and effects

Server MoLang →

Fight Config Builder

Visual phase editor

Fight Config Builder →

Master phases and movement overrides to create dynamic, evolving boss encounters!

Phase System

Phase System

How Phases Work

Phase Configuration Location

Basic Phase Structure

Core Phase Properties

healthThreshold (Required)

moves (Required)

speedModifier (Required)

damageModifier (Required)

scaleModifier (Required)

movementPattern (Required)

aggressionLevel (Optional, default: 1.0)

Movement Overrides (NEW!)

Available Override Types

Teleport Blink Override

Hit-and-Run Override

Kiting Override

Flying Bomber Override

Flying Circler Override

Flying Rush Override

Berserker Override

Defensive Override

Enraged Override

Zigzag Override

Perched Override

Movement Override Matching

Phase Scripts

onEnterScript (Optional)

onExitScript (Optional)

Complete Phase Examples

Raichu Three-Phase Progression

Simple Two-Phase Boss

Four-Phase Enrage Boss

Balancing Phases

Difficulty Curve

Move Pool Progression

Movement Progression Strategies

Duration Targets

Troubleshooting

Phase Not Triggering

Phase Skipping

Movement Overrides Not Working

Stat Modifiers Not Applying

Scripts Not Executing

Next Steps

`healthThreshold` (Required)

`moves` (Required)

`speedModifier` (Required)

`damageModifier` (Required)

`scaleModifier` (Required)

`movementPattern` (Required)

`aggressionLevel` (Optional, default: 1.0)

`onEnterScript` (Optional)

`onExitScript` (Optional)