Movement Controllers

Movement controllers define how Titans navigate and position themselves during combat. Titan includes 11 specialized controllers with configurable behavior and per-phase overrides.

Overview

Controllers are selected via weighted random based on distance, health, and aggression. Each controller has unique selection criteria and configurable parameters.

Ground Controllers

7 Controllers

Hit-and-Run
Kiting
Berserker
Defensive
Enraged
Zigzag
Standard (fallback)

Flying Controllers

3 Controllers

Flying Bomber
Flying Circler
Flying Rush

Special Controllers

2 Controllers

Teleport Blink
Perched

Controller Reference

Hit-and-Run Controller

Best For: Melee strikers (Lucario, Scizor, Weavile)

Three-phase combat pattern: APPROACH → STRIKE → RETREAT.

Configuration

{
  "movementOverrides": {
    "hitAndRun": {
      "approachSpeed": 1.3,
      "retreatSpeed": 1.5,
      "strikeRange": 3.0,
      "retreatDistance": 8.0,
      "cooldownMs": 5000
    }
  }
}

Properties

Property	Default	Description
`approachSpeed`	1.2	Speed multiplier during approach
`retreatSpeed`	1.4	Speed multiplier during retreat
`strikeRange`	2.5	Distance to trigger strike phase
`retreatDistance`	7.0	How far to retreat after strike
`cooldownMs`	4000	Time before next cycle

Selection Weight

High weight at medium range (4-10 blocks), low weight at very close or far range. Increased by aggression multiplier.

Optimal Range: 4-10 blocks Aggression Scaling: ×0.8 to ×1.5

Teleport Blink Controller

Best For: Psychic/Ghost types (Gengar, Alakazam, Mimikyu, Raichu)

Instant teleportation to tactical positions with safety checks.

Configuration

{
  "movementOverrides": {
    "teleport": {
      "minRange": 4.0,
      "maxRange": 8.0,
      "radialCandidates": 12,
      "heightVariance": 2.5,
      "cooldownMs": 10000
    }
  }
}

Properties

Property	Default	Description
`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
`cooldownMs`	12000	Time between teleports

Safety Features

Spawn Chunk Check - Ensures chunk is loaded
Water Avoidance - Filters out fluid blocks
EntityBounds Enforcement - Post-teleport collision correction

Selection Weight

High weight at medium-long range (6-15 blocks), low weight when very close. Increased when stuck or obstructed.

Optimal Range: 6-15 blocks

Kiting Controller

Best For: Ranged attackers (Arcanine, Sceptile, Flygon)

Maintains distance while circling target.

Configuration

{
  "movementOverrides": {
    "kiting": {
      "preferredDistance": 8.0,
      "minDistance": 6.0,
      "maxDistance": 12.0,
      "circleSpeed": 1.1
    }
  }
}

Properties

Property	Default	Description
`preferredDistance`	8.0	Ideal range from target
`minDistance`	6.0	Too close threshold (retreat)
`maxDistance`	12.0	Too far threshold (advance)
`circleSpeed`	1.1	Strafing speed multiplier

Optimal Range: 7-11 blocks

Flying Bomber Controller

Best For: Aerial strikers (Rayquaza, Salamence, Dragonite)

Flies above target, dives to attack, ascends to repeat.

Configuration

{
  "movementOverrides": {
    "flyingBomber": {
      "cruiseAltitude": 12.0,
      "diveSpeed": 1.8,
      "ascentSpeed": 1.3,
      "attackAltitude": 3.0
    }
  }
}

Properties

Property	Default	Description
`cruiseAltitude`	12.0	Height while circling
`diveSpeed`	1.8	Speed during dive attack
`ascentSpeed`	1.3	Speed climbing back up
`attackAltitude`	3.0	Dive endpoint height

Flying Circler Controller

Best For: Aerial casters (Togekiss, Articuno)

Maintains constant altitude while circling target.

Configuration

{
  "movementOverrides": {
    "flyingCircler": {
      "altitude": 10.0,
      "orbitRadius": 8.0,
      "orbitSpeed": 1.2
    }
  }
}

Properties

Property	Default	Description
`altitude`	10.0	Fixed flight height
`orbitRadius`	8.0	Circle radius
`orbitSpeed`	1.2	Rotation speed

Flying Rush Controller

Best For: Aggressive flyers (Dragonite enraged phase)

Direct aerial charges at target.

Configuration

{
  "movementOverrides": {
    "flyingRush": {
      "rushSpeed": 2.0,
      "minAltitude": 4.0,
      "maxAltitude": 8.0
    }
  }
}

Berserker Controller

Best For: High-aggression melee (Gyarados, Heracross)

Relentless forward aggression with no retreat.

Configuration

{
  "movementOverrides": {
    "berserker": {
      "chargeSpeed": 1.6,
      "ignoreHealth": false
    }
  }
}

Selection Weight: Increases as health decreases (enrage mechanic).

Defensive Controller

Best For: Tank Titans (Aggron, Lapras)

Maintains safe distance, retreats when threatened.

Configuration

{
  "movementOverrides": {
    "defensive": {
      "safeDistance": 10.0,
      "retreatThreshold": 0.5
    }
  }
}

Enraged Controller

Best For: Final phase berserk mode

Activated when health < 20%, ignores normal behavior.

Configuration

{
  "movementOverrides": {
    "enraged": {
      "speed": 2.0,
      "healthThreshold": 0.2
    }
  }
}

Zigzag Controller

Best For: Evasive strikers (Weavile, Toxicroak)

Unpredictable lateral movement while advancing.

Configuration

{
  "movementOverrides": {
    "zigzag": {
      "zigSpeed": 1.4,
      "zigInterval": 1000,
      "zigAngle": 45
    }
  }
}

Perched Controller

Best For: Flying types that land periodically

Alternates between perched (ground) and flying states.

Configuration

{
  "movementOverrides": {
    "perched": {
      "perchDuration": 5000,
      "flyDuration": 8000
    }
  }
}

Phase-Specific Movement Overrides

You can change movement behavior per phase in phase configs.

Example: Raichu Phase Progression

Phase 1 (100% HP): KITING pattern

{
  "healthThreshold": 1.0,
  "movementPattern": "KITING",
  "aggressionLevel": 1.2
}

Phase 2 (60% HP): TELEPORT with faster cooldown

{
  "healthThreshold": 0.6,
  "movementPattern": "TELEPORT",
  "aggressionLevel": 1.5,
  "movementOverrides": {
    "teleport": {
      "minRange": 4.0,
      "maxRange": 8.0,
      "cooldownMs": 12000
    }
  }
}

Phase 3 (35% HP): RUSH (berserker mode)

{
  "healthThreshold": 0.35,
  "movementPattern": "RUSH",
  "aggressionLevel": 1.8
}

Movement Pattern Names

Use these strings in phase configs:

Pattern Name	Controller	Best For
`STANDARD`	Ground patrol	Default/fallback
`HIT_AND_RUN`	Hit-and-run	Melee strikers
`TELEPORT`	Teleport blink	Psychic/Ghost
`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 health berserk
`ZIGZAG`	Zigzag	Evasive
`PERCHED`	Perched	Flying with landing

Selection Weight System

Movement controllers use dynamic weighting based on:

Distance to Target - Each controller has optimal range
Current Health - Berserker/Enraged increase when low HP
Aggression Multiplier - From phase aggressionLevel
Obstruction State - Teleport weight increases if stuck

Weight Calculation Example:

fun getSelectionWeight(
    distance: Double,
    health: Double,
    aggression: Double
): Double {
    var weight = baseWeight
    weight *= distanceModifier(distance)  // 0.3-1.5x
    weight *= healthModifier(health)      // 0.5-2.0x
    weight *= aggression                  // Phase modifier
    return weight.coerceIn(0.0, 10.0)
}

Movement System

Movement controllers are invoked through the task system which manages cooldowns, handles controller selection, and integrates with Cobblemon’s AI goal system.

Best Practices

Start Simple - Use STANDARD or HIT_AND_RUN for first phase
Escalate Complexity - Add TELEPORT or FLYING in later phases
Test Range Values - Adjust min/maxRange based on arena size
Balance Cooldowns - Shorter cooldowns = more chaotic, harder to predict
Match Lore - Psychic types → TELEPORT, Dragons → FLYING, Ghosts → HIT_AND_RUN

Example: Complete Movement Progression

Ceruledge (melee ghost type):

{
  "phases": [
    {
      "healthThreshold": 1.0,
      "movementPattern": "HIT_AND_RUN",
      "movementOverrides": {
        "hitAndRun": {
          "approachSpeed": 1.2,
          "retreatSpeed": 1.3,
          "cooldownMs": 5000
        }
      }
    },
    {
      "healthThreshold": 0.5,
      "movementPattern": "TELEPORT",
      "movementOverrides": {
        "teleport": {
          "minRange": 3.0,
          "maxRange": 6.0,
          "cooldownMs": 8000
        }
      }
    },
    {
      "healthThreshold": 0.25,
      "movementPattern": "BERSERKER",
      "movementOverrides": {
        "berserker": {
          "chargeSpeed": 1.8
        }
      }
    }
  ]
}

Next Steps

Phases → - Configure phase progression
State Machines → - Advanced AI behavior
Fight Config Builder → - Visual editor

Master movement controllers to create dynamic, engaging boss encounters!