Package dev.itsharshxd.zentrix.api.phase

Class PhaseBuilder

java.lang.Object
dev.itsharshxd.zentrix.api.phase.PhaseBuilder
public class PhaseBuilder extends Object
Fluent builder for creating custom game phases dynamically.

This builder allows addon developers to create phases that integrate with the Zentrix phase system, including border configuration and on-start actions.

Example Usage


 PhaseBuilder bloodMoon = new PhaseBuilder()
     .name("blood_moon")
     .displayName("&#990000&l BLOOD MOON")
     .duration(90)
     .border(border -> border
         .shrinkTo(75)
         .shrinkDuration(90)
         .damagePerBlock(2.0))
     .onStart(actions -> actions
         .announce("&#990000The Blood Moon rises!")
         .title("&#990000&lBLOOD MOON", "&#FF6666Damage doubled!")
         .sound(Sound.ENTITY_WITHER_SPAWN, 0.8f, 0.5f)
         .giveEffect(PotionEffectType.STRENGTH, 1800, 0))
     .addonId(getAddonId());

 phaseService.registerPhaseAt(bloodMoon, 2);
Since:
1.1.0
See Also:

  • Constructor Details

    • PhaseBuilder

      public PhaseBuilder()
      Creates a new PhaseBuilder instance.

  • Method Details

    • name

      @NotNull public @NotNull PhaseBuilder name(@NotNull @NotNull String name)
      Sets the internal name of the phase.

      This is the unique identifier used in configuration and queries. Must only contain lowercase letters, numbers, and underscores.

      Parameters:
      name - The phase name (e.g., "blood_moon", "final_shrink")
      Returns:
      This builder for chaining
      Throws:
      IllegalArgumentException - if the name is null, empty, or contains invalid characters

    • displayName

      @NotNull public @NotNull PhaseBuilder displayName(@NotNull @NotNull String displayName)
      Sets the display name of the phase.

      This is the formatted name shown to players, with color code support (both legacy &c and hex &#RRGGBB formats).

      Parameters:
      displayName - The display name (e.g., "invalid input: '&#990000'invalid input: '&l' BLOOD MOON")
      Returns:
      This builder for chaining

    • duration

      @NotNull public @NotNull PhaseBuilder duration(int seconds)
      Sets the duration of the phase in seconds.
      Parameters:
      seconds - The duration in seconds (must be positive)
      Returns:
      This builder for chaining
      Throws:
      IllegalArgumentException - if duration is not positive

    • border

      @NotNull public @NotNull PhaseBuilder border(@NotNull @NotNull Consumer<PhaseBuilder.BorderConfigBuilder> config)
      Configures the border behavior for this phase using a fluent consumer pattern. 
      
 builder.border(border -> border
     .shrinkTo(75)
     .shrinkDuration(90)
     .damagePerBlock(2.0)
     .warningTime(10));
      Parameters:
      config - A consumer to configure border settings
      Returns:
      This builder for chaining

    • noBorderShrink

      @NotNull public @NotNull PhaseBuilder noBorderShrink()
      Disables border shrinkage for this phase.

      Creates a border config with doShrinkage = false.

      Returns:
      This builder for chaining

    • onStart

      @NotNull public @NotNull PhaseBuilder onStart(@NotNull @NotNull Consumer<PhaseBuilder.PhaseActionsBuilder> config)
      Configures the on-start actions for this phase using a fluent consumer pattern. 
      
 builder.onStart(actions -> actions
     .announce("Phase has started!")
     .title("Phase!", "Get ready")
     .sound(Sound.ENTITY_ENDER_DRAGON_GROWL, 1.0f, 1.0f)
     .togglePvP(true));
      Parameters:
      config - A consumer to configure on-start actions
      Returns:
      This builder for chaining

    • addAnnounce

      @NotNull public @NotNull PhaseBuilder addAnnounce(@NotNull @NotNull String message)
      Adds an announcement message action to be sent when the phase starts.
      Parameters:
      message - The message to announce (supports color codes)
      Returns:
      This builder for chaining

    • addTitle

      @NotNull public @NotNull PhaseBuilder addTitle(@NotNull @NotNull String main, @Nullable @Nullable String subtitle)
      Adds a title action to be displayed when the phase starts.
      Parameters:
      main - The main title text
      subtitle - The subtitle text
      Returns:
      This builder for chaining

    • addSound

      @NotNull public @NotNull PhaseBuilder addSound(@NotNull @NotNull org.bukkit.Sound sound, float volume, float pitch)
      Adds a sound action to be played when the phase starts.
      Parameters:
      sound - The sound to play
      volume - The volume (0.0-1.0)
      pitch - The pitch (0.5-2.0)
      Returns:
      This builder for chaining

    • addTogglePvP

      @NotNull public @NotNull PhaseBuilder addTogglePvP(boolean enable)
      Adds a PvP toggle action when the phase starts.
      Parameters:
      enable - true to enable PvP, false to disable
      Returns:
      This builder for chaining

    • addGiveEffect

      @NotNull public @NotNull PhaseBuilder addGiveEffect(@NotNull @NotNull org.bukkit.potion.PotionEffectType type, int duration, int amplifier)
      Adds a potion effect to be given to all players when the phase starts.
      Parameters:
      type - The potion effect type
      duration - The duration in ticks (20 ticks = 1 second)
      amplifier - The effect amplifier (0 = level 1)
      Returns:
      This builder for chaining

    • addCommand

      @NotNull public @NotNull PhaseBuilder addCommand(@NotNull @NotNull String command)
      Adds a command to be executed when the phase starts.

      Commands are executed as the console. Use placeholders like %player% if supported.

      Parameters:
      command - The command to execute (without leading slash)
      Returns:
      This builder for chaining

    • addStartDeathmatch

      @NotNull public @NotNull PhaseBuilder addStartDeathmatch()
      Adds a deathmatch start action when the phase starts.
      Returns:
      This builder for chaining

    • addGiveItem

      @NotNull public @NotNull PhaseBuilder addGiveItem(@NotNull @NotNull String itemId)
      Adds an item to be given to all players when the phase starts.
      Parameters:
      itemId - The item identifier (supports custom:, itemsadder:, nexo:, or vanilla)
      Returns:
      This builder for chaining

    • addonId

      @NotNull public @NotNull PhaseBuilder addonId(@NotNull @NotNull String addonId)
      Sets the addon ID that owns this phase.

      This is used for tracking which addon registered the phase and for querying phases by addon.

      Parameters:
      addonId - The addon identifier
      Returns:
      This builder for chaining

    • customField

      @NotNull public @NotNull PhaseBuilder customField(@NotNull @NotNull String key, @Nullable @Nullable Object value)
      Adds a custom metadata field to this phase.
      Parameters:
      key - The field key
      value - The field value (should be serializable)
      Returns:
      This builder for chaining

    • getName

      @Nullable public @Nullable String getName()
      Gets the phase name.
      Returns:
      The phase name, or null if not set

    • getDisplayName

      @Nullable public @Nullable String getDisplayName()
      Gets the display name.
      Returns:
      The display name, or null if not set

    • getDuration

      public int getDuration()
      Gets the duration in seconds.
      Returns:
      The duration

    • getBorderConfig

      @Nullable public @Nullable PhaseBuilder.BorderConfigBuilder getBorderConfig()
      Gets the border configuration.
      Returns:
      The border config builder, or null if not set

    • getOnStartActions

      @NotNull public @NotNull List<PhaseBuilder.PhaseAction> getOnStartActions()
      Gets the on-start actions.
      Returns:
      An unmodifiable list of actions

    • getAddonId

      @Nullable public @Nullable String getAddonId()
      Gets the addon ID.
      Returns:
      The addon ID, or null if not set

    • getCustomFields

      @NotNull public @NotNull Map<String,Object> getCustomFields()
      Gets all custom fields.
      Returns:
      A copy of the custom fields map

    • validate

      public void validate() throws IllegalStateException
      Validates that this builder has all required fields set correctly.
      Throws:
      IllegalStateException - if the builder is not valid

    • isValid

      public boolean isValid()
      Checks if this builder is valid without throwing an exception.
      Returns:
      true if the builder has all required fields

    • copy

      @NotNull public @NotNull PhaseBuilder copy()
      Creates a copy of this builder.
      Returns:
      A new PhaseBuilder with the same configuration

    • toString

      public String toString()
      Overrides:
      toString in class Object