Boss Hunt

The Boss Hunt system spawns a single active boss at a time, rotates it on a long schedule, and provides a questline with a tracker item.

Core Concepts

• Boss config — Each boss is defined in config/bosshunt/*.json with spawn points, rotation settings, and quest integration
• Active boss — Only one boss is active at any time across the server. It rotates on a configurable schedule.
• Anchors/points — Predefined spawn coordinates where the boss can appear and relocate to

Configuration

Each boss hunt entry is a JSON file in config/bosshunt/:

{
  "bossKey": "dragon",
  "questId": "yourmod:bosshunt-dragon",
  "points": [
    { "x": 1000, "y": 80, "z": -500 },
    { "x": 2000, "y": 90, "z": 1000 },
    { "x": -500, "y": 75, "z": 2000 }
  ],
  "rotationDays": 7,
  "relocateIntervalHours": 12,
  "respawnInGameHours": 24,
  "noRelocateAfterDamageMinutes": 30,
  "activationRange": 64,
  "playerLockRange": 96
}

Rotation Flow

graph TD
    A["Server starts"] --> B{"activeBossKey set?"}
    B -->|No| C["Pick first boss in config list"]
    B -->|Yes| D["Resume with saved boss"]
    C --> E["Set activeBossKey"]
    D --> E
    E --> F["Pick random point from points[]"]
    F --> G["Wait for player in activationRange"]
    G --> H["Spawn boss"]
    H --> I{"Boss killed?"}
    I -->|Yes| J["Set respawn timer
now + respawnInGameHours"]
    I -->|No| K["Every relocateIntervalHours
pick new random point"]
    J --> L{"Respawn timer reached?"}
    L -->|Yes| G
    K --> M{"Damage taken
in last N minutes?"}
    M -->|Yes| H
    M -->|No| N["Relocate to new point"]
    N --> H
    O["rotationDays reached"] --> P["Despawn current boss"]
    P --> Q["Next boss in list"]
    Q --> E

Rotation Logic

• activeBossKey — Stored in world save data, determines which boss is currently active
• nextBossRotationTotalHours — The total in-game hours at which the next rotation occurs
• Deterministic rotation — Bosses rotate in the order they are defined in config files

When rotation triggers, the current boss is despawned and the next boss in the list becomes active. The rotation wraps around to the first boss after the last.

Spawn & Relocation

• The boss spawns at a random point from its points array when a player enters activationRange
• Every relocateIntervalHours, the boss moves to a different random point
• After respawnInGameHours following a kill, the boss becomes available again
• The boss will not relocate for noRelocateAfterDamageMinutes after taking damage

Death Handling

When a boss hunt boss dies:

• Loot drops — Standard entity death drops apply (configured in the entity's drops)
• Quest auto-complete — The associated quest (questId) is force-completed for all players who damaged the boss
• Respawn timer — respawnInGameHours is added to current total hours; boss won't spawn until then
• Database sync — If database sync is enabled, a boss kill is recorded for each participating player
• Rotation unaffected — Death does not trigger rotation; rotation only happens on schedule

Tracker Item

Players can use the trackboss action item to locate the active boss:

• Uses the trackboss action when activated
• 5 minute cooldown between uses
• 2 HP cost per use
• Shows distance and direction to the active boss

Action item config in itemconfig.json:

{
  "id": "boss-tracker",
  "itemCode": "alegacyvsquest:actionitem",
  "name": "yourmod:boss-tracker",
  "actions": ["trackboss"],
  "durability": 100,
  "cooldownMs": 300000,
  "useCostHp": 2
}

Quest Giver Integration

Quest givers can be configured to only offer quests when a specific boss is active:

{
  "bosshuntactiveonly": true
}

When bosshuntactiveonly is set to true, the quest giver will only display quests for the currently active boss hunt target.

Complete Example

File layout

config/bosshunt/
  yourmod_ossuarywarden.json
  yourmod_frostwyrm.json
  yourmod_shadowreaper.json

Config: config/bosshunt/yourmod_ossuarywarden.json

{
  "bossKey": "yourmod:ossuarywarden",
  "questId": "yourmod:bosshunt-ossuary",
  "points": [
    { "x": 1500, "y": 85, "z": -800 },
    { "x": 2500, "y": 90, "z": 1200 },
    { "x": -300, "y": 70, "z": 2200 }
  ],
  "rotationDays": 7,
  "relocateIntervalHours": 12,
  "respawnInGameHours": 48,
  "noRelocateAfterDamageMinutes": 45,
  "activationRange": 64,
  "playerLockRange": 96
}

Quest: quests/yourmod/bosshunt-ossuary.json

{
  "id": "yourmod:bosshunt-ossuary",
  "title": "yourmod:bosshunt-ossuary-title",
  "description": "yourmod:bosshunt-ossuary-desc",
  "predecessor": "yourmod:bosshunt-unlocked",
  "stages": [
    {
      "name": "Find the Ossuary Warden",
      "objectives": [
        { "id": "killactiontarget", "args": ["yourmod:ossuarywarden", "1", "false", "true"] }
      ]
    }
  ],
  "onComplete": [
    { "id": "giveitem", "args": ["game:gear-temporalsteel", "3"] },
    { "id": "addreputation", "args": ["npc", "yourmod:bosshunter", "200"] }
  ]
}

Quest Giver

{
  "code": "questgiver",
  "quests": ["yourmod:bosshunt-ossuary"],
  "bosshuntactiveonly": true,
  "reputationnpc": "yourmod:bosshunter"
}

Commands

Global Config

The BossHunt section in alegacy-vsquest-config.json controls global boss hunt behavior:

{
  "BossHunt": {
    "Enabled": true,
    "AnchorSearchRadius": 512
  }
}

Tips

• Place points in distinct biomes so the boss "roams" the world
• Use noRelocateAfterDamageMinutes to prevent players from chasing a teleporting boss
• Pair with bosshuntcombatmarker behavior on the boss entity for proper attacker tracking
• The tracker item is optional — players can also find bosses by exploring the points