Skip to content

Adding Boss To Boss Rush Event

Jump to bottom
Tien edited this page Aug 16, 2024 · 8 revisions

Adding Boss to Boss Rush Event

This page will show you how to add a boss to the Boss Rush Event powered by the Boss Rush API.

Introduction

It's important to know how the Boss Rush System Queue works first. The system has a Queue<BossData> private field that is used to spawn the bosses in a certain order. Boss Rush System exposes a public method that will be the main interface for adding bosses into the queue.

As an additional note, if there is a need to read the queue into your mod, it is advised to store it into a separate data structure as the bosses are stored. This is to prevent any issues that may arise from direct manipulation of the queue.

Adding a Boss into the Queue

void BossRushSystem.AddBoss(float position, Types.BossData data)

The above method is exposed by the Boss Rush System. It is the only way to add a boss into the queue. The method requires two parameters: the float position of the boss in the queue and the BossData struct that contains all the necessary information to spawn the boss properly.

Do note that each call of AddBoss represents a Boss Rush Stage. You will only call this once for each stage. If you want two bosses to spawn at the same time in a stage, then you must call AddBoss once; the BossData struct parameter containing the necessary information about the two bosses to spawn.

The float position parameter indicates the queue position of the stage. The ordering of the stages will be in ascending order; lowest number will be the first. Adding stages with equal positions is supported. Those with equal postitions will be randomized within those slots.

using BossRushAPI.Types;
using Terraria.ID;
using BRS = BossRushAPI.BossRushSystem;

// ...

AddBoss(5, new([NPCID.Retinazer, NPCID.Spazmatism]))
AddBoss(5, new([NPCID.TheDestroyer]))
AddBoss(6, new([NPCID.SkeletronPrime]))
AddBoss(1, new([NPCID.KingSlime]))

Consider the code above. Using this code, when the Boss Rush Event is toggled on, King Slime will spawn first as the first stage. Next, either the Twins or the Destroyer will spawn. For example, let's say the Twins spawned first. After defeating the Twins, Destroyer will spawn next. If Destroyer was spawned first instead of Twins, then the Twins will spawn next after the defeat of Destroyer. If they have the same position number, the system will randomize them in any order of spawning until all bosses registered in that position are exhausted, only then will the system proceed to the next position number.

Another thing to note is that this only works when the Boss Rush Event is inactive. Dynamically adding bosses during the Boss Rush Event is not possible. This is to prevent any issues that may arise from direct manipulation of the queue.

BossData Struct

The BossData struct contains all the necessary information to spawn the boss properly. Within it are more structs. This section will describe them one by one. You only need to pay attention to the constructors.

public BossData(
    List<int> types,
    List<int> subTypes = null,
    Rectangle? spawnOffset = null,
    ModifiedAttributes? modifiedAttributes = null,
    SpawnAttributes? spawnAttributes = null,
    TimeContext? timeContext = null,
    PlaceContext? placeContext = null,
    Message? startMessage = null,
    Message? defeatMessage = null
)

List<int> types

This is a required parameter. It is a list of NPC IDs that will be the basis of spawning the bosses at the start of the Boss Rush Stage.

Modded content is also supported so long as the type given to this parameter is correct. One may use tModLoader's ModContent.NPCType<ModNPC>() to get the NPC ID of a modded NPC.

For example, [NPCID.Spazmatism, NPCID.Retinazer] will spawn the Twins. [NPCID.King] will spawn King Slime.

For modded content, tModLoader has a comprehensive guide on how to get the NPC ID of a modded NPC.

The bosses here are required to be defeated by players to progress to the next Boss Rush Stage.

List<int> subTypes = null

Optional parameter that also represent a list of NPC IDs. These are NPCs that are tracked through a boss rush stage. These NPCs are also required to be defeated to progress to the next Boss Rush Stage. The key differences from the required types parameter are as follows.

  1. They will not be spawned by the Boss Rush System at the start of the Boss Rush Stage.
  2. They will be tracked by the Boss Rush System if they are spawned through boss logic or other phases of the stage.

These are compatible with bosses with transforming types, or boss minions. For example, if we use [NPCID.KingSlime] for types and [NPCID.BlueSlime] for subTypes, then the system will track all blue slimes that is spawned from King Slime, and King Slime and all blue slimes must be defeated in order to progress to the next stage.

If the parameter is null, then the system will not track any subtypes.

Rectangle? spawnOffset = null

This is an optional parameter that represents the offset of the boss from the target player. It is a rectangle because the spawn offset is randomized. It selects a random point within the rectangle to use as a spawn position.

The target player will always be the one with the highest aggro stat. If there are multiple players with the highest aggro stat, then the target will be randomly selected among the players with the highest aggro stat.

The basis of the offset is the target player's Center. If we have a new Rectangle(0, 0, 100, 100), then it will look like the the image below:

Spawn Offset Visual

ModifiedAttributes? modifiedAttributes = null

The ModifiedAttributes struct stores the buffs in stats. It contains boosts (or nerfs) for damage, defense and life only. The struct contains several parameters that have their own fields. They are listed below:

  1. float lifeMultiplier = 1f - Multiplier for the life of the bosses and their minions.
  2. float damageMultiplier = 1f - Multiplier for the damage of the bosses and their minions.
  3. float defenseMultiplier = 1f - Multiplier for the defense of the bosses and their minions.
  4. int lifeFlatIncrease = 0 - Flat increase for the life of the bosses and their minions.
  5. int damageFlatIncrease = 0 - Flat increase for the damage of the bosses and their minions.
  6. int defenseFlatIncrease = 0 - Flat increase for the defense of the bosses and their minions.
  7. bool projectilesAffected = false - If true, the damage of the projectiles of the bosses and their minions will be affected by the damage modifiers.

The formula for the modifying the NPC stats is as follows:

npc.stat = (npc.stat + statFlatIncrease) * statMultiplier;
// where stat is either life, damage or defense

The recommended way to use the constructor is this:

new ModifiedAttributes(defenseFlatIncrease: 10, lifeMultiplier: 1.5f, damageMultiplier: 1.5f, projectilesAffected: true)

Those parameters that are left out will use the default values listed above. The BossData struct can accept a null value for ModifiedAttributes? modifiedAttributes as well, and it will use the default values.

SpawnAttributes? spawnAttributes = null

The SpawnAttributes struct stores the spawn values for those not related to the bosses and their minions. In Terraria, random NPCs still spawn as enemies even when a boss is present. BossData struct contains SpawnAttributes information to control that. The SpawnAttributes struct contains the following parameters:

  1. float maxMultiplier = 1f - Multiplier for the maximum number of enemies that can spawn.
  2. int maxFlatIncrease = 0 - Flat increase for the maximum number of enemies that can spawn.
  3. float rateMultiplier = 1f - Multiplier for the spawn rate of the enemies.

There are existing static properties that are already pre-configured:

  1. SpawnAttributes.Default - Default values for the spawn attributes.
  2. SpawnAttributes.NoSpawns - No random mob spawns will occur.
  3. SpawnAttributes.DoubleSpawns - Double the spawn rate and allowable maximum number of enemies.

However, if there is a need to customize the values, the constructor can be used like this:

new SpawnAttributes(rateMultiplier: 1.5f, maxFlatIncrease: 1000)

Parameters left out will use the default values. The BossData struct can accept a null value for SpawnAttributes? spawnAttributes as well, and it will use the default values as a result.

TimeContext? timeContext = null

The TimeContext struct stores the required time setting for the boss rush stage. Terraria is known for having time constraints when fighting bosses. This will be used to control the time of the boss rush stage. The TimeContext struct contains the following parameters:

  1. double time - Required parameter that signifies the actual time in-game in in-game units.
  2. bool dayTime - Required parameter which determines if world is day or night.

Terraria uses its own units when dealing with time. An internal counter is updated every tick. The time parameter will directly set this internal counter to set the time. It is up to the implementation of the modder to use the correct time values. For more information, refer to the facts presented:

  1. At the start of morning, time is 0.0 and dayTime is true.
  2. At the start of night, time is 0.0 and dayTime is false.
  3. At 12:00 PM, time is 27000.0 and dayTime is true.

There are existing static properties that are already pre-configured that mirror said facts above:

  1. TimeContext.Day - 4:30 AM.
  2. TimeContext.Night - 7:30 PM.
  3. TimeContext.Noon - 12:00 PM.

However, if there is a need to customize the values, the constructor can be used like this:

new TimeContext(120.0, true)

The BossData struct can accept a null value for TimeContext? timeContext as well. When timeContext is null, the system will not change the time.

PlaceContext? placeContext = null

The PlaceContext struct stores the required place setting for the boss rush stage. Terraria is also known for having biome requirements when fighting bosses. This will be used to control the place of the boss rush stage. When the Boss Rush Stage comes into play, all players will be teleported to the specified PlaceContext data. The PlaceContext struct has two constructors. The first one is as follows:

  1. Vector2 initialPosition - Required parameter that signifies world coordinates.
  2. int width - Required parameter that signifies the horizontal diameter from initialPosition, where initialPosition is the center.
  3. int height - Required parameter that signifies the vertical diameter from initialPosition, where initialPosition is the center.

What the constructor does is use initialPosition as the center of a rectangle with the given width and height. The players will be teleported to a random point within the rectangle. Given these, the second constructor is as follows:

  1. int x - Required parameter that signifies the x-coordinate of the center of the rectangle.
  2. int y - Required parameter that signifies the y-coordinate of the center of the rectangle.
  3. int width - Required parameter that signifies the horizontal diameter from the center.
  4. int height - Required parameter that signifies the vertical diameter from the center.

This form of the constructor just uses the first one with the initialPosition parameter set to new Vector2(x, y).

There are existing static properties that are already pre-configured:

  1. PlaceContext.LeftUnderworld - Left side of the underworld.
  2. PlaceContext.RightUnderworld - Right side of the underworld.
  3. PlaceContext.LeftOcean - Left side of the ocean.
  4. PlaceContext.RightOcean - Right side of the ocean.

Below is an example of how to use the constructor:

new PlaceContext(new(3000, 12000), 30, 30)

The BossData struct can accept a null value for PlaceContext? placeContext as well. When placeContext is null, the system will not teleport the players. It is also worth noting that Boss Rush Stages with a PlaceContext will always teleport players back to spawn area after the stage is completed.

Message? startMessage = null and Message? defeatMessage = null

The Message struct stores the message that will be displayed when the boss rush stage starts (startMessage) and/or when the boss is defeated (defeatMessage). In a Boss Rush Stage, the message that the boss has awoken is removed. Instead, the startMessage will replace it. The vanilla boss defeat message, however, will still be displayed. defeatMessage will be displayed alongside the vanilla boss defeat message; it does not replace the vanilla message. The Message struct has the following parameters:

  1. string text - Required parameter which is the message to be displayed.
  2. bool literal - Required parameter which determines if the message is a string literal (true) or a localization key (false).
  3. Color? color - Optional parameter which determines the color of the message. If null, the color will be white.

If you know a way to remove the vanilla boss defeat message, please open a pull request.

Below is an example of how to use the constructor:

new Message("Ho ho ho, you are doing... fantastic.", false, Color.Red);
new Message("Mods.MyMod.MyModdedBossDefeatedInBossRush", true, Color.Green);

The BossData struct can accept a null value for Message? startMessage and Message? defeatMessage. If a null value is assigned to Message, then the system will not display any messages.

When to add the Bosses

It is best to ad the code which uses BossRushSystem.AddBoss before the BossRushSystem.ToggleBossRush method is called. This is to ensure that the bosses are always added to the queue before the event starts.

Do not add bosses to the queue during initialization of your mod. The Boss Rush System will recognize the bosses you added at first, but if the Boss Rush Event is commenced again, the bosses will not spawn. This is due to the Boss Rush System cleaning all the related data structures when the event is toggled off. This will make the support for multiple boss rush mods that uses the same API compatible with each other.

Clone this wiki locally