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.

Use it to define border settings and actions that run when a phase starts.

Example


 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.

      The name 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.

      The formatted name shown to players supports both legacy &c and hex &#RRGGBB color formats.

      Parameters:
      displayName - The display name (for example, &#990000&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

    • addSound

      @NotNull public @NotNull PhaseBuilder addSound(@NotNull @NotNull org.bukkit.Sound sound, float volume, float pitch, int delaySeconds)

    • 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

    • addToggleNether

      @NotNull public @NotNull PhaseBuilder addToggleNether(@NotNull @NotNull NetherToggleRequest request)

    • addToggleEnd

      @NotNull public @NotNull PhaseBuilder addToggleEnd(@NotNull @NotNull EndToggleRequest request)

    • addonId

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

      Zentrix uses it to track and query 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()
      Copies this builder.
      Returns:
      A new PhaseBuilder with the same configuration

    • toString

      public String toString()
      Overrides:
      toString in class Object