Stopwatch Module v2

[ItsNature]

Overview

Description:

Overhauls the Stopwatch module to support multiple stopwatches and timers with configurable options such as text color, display format, HUD positioning.

Full Docs: Stopwatch Module

Changes:

• Deprecated StopwatchModule#startStopwatch, StopwatchModule#stopStopwatch, StopwatchModule#resetStopwatch
• Added StopwatchModule#addStopwatch, StopwatchModule#removeStopwatch, StopwatchModule#startStopwatch(id), StopwatchModule#stopStopwatch(id), StopwatchModule#resetStopwatch(id), StopwatchModule#resetStopwatches
• Added StopwatchModule#addTimer, StopwatchModule#removeTimer, StopwatchModule#startTimer, StopwatchModule#stopTimer, StopwatchModule#resetTimer, StopwatchModule#resetTimers
• Added HudPosition: common data class for positioning HUD elements
  • float x: horizontal offset
  • float y: vertical offset
• Added Stopwatch: configurable stopwatch displayed on the client HUD
  • String id: unique server-assigned id
  • String name: HUD display name
  • boolean resetOnStart: reset elapsed time on each start
  • boolean preventModification: lock client-side options
  • boolean hideWhenStopped: hide from HUD when stopped
  • String customFormat: display format (e.g. "mm:ss")
  • Color textColor: text color
  • HudPosition hudPosition: screen position
• Added Timer: configurable countdown timer displayed on the client HUD
  • String id: unique server-assigned id
  • String name: HUD display name
  • Duration duration: countdown duration
  • boolean loop: restart when finished
  • boolean preventModification: lock client-side options
  • boolean hideWhenStopped: hide from HUD when stopped
  • String customFormat: display format
  • Component titleText: on-screen title when finished
  • boolean ingameNotification: popup when finished
  • Color textColor: text color
  • HudPosition hudPosition: screen position
• Added corresponding NetworkTypes helpers for HudPosition protobuf conversion

Code Example:

  public void addStopwatchExample(Player viewer) {
      Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());

      apolloPlayerOpt.ifPresent(apolloPlayer -> {
          this.stopwatchModule.addStopwatch(apolloPlayer, Stopwatch.builder()
              .id("parkour-stopwatch")
              .name("Parkour")
              .resetOnStart(true)
              .preventModification(true)
              .hideWhenStopped(false)
              .customFormat("mm:ss")
              .textColor(ApolloColors.DARK_AQUA)
              .hudPosition(HudPosition.builder()
                  .x(-30)
                  .y(30)
                  .build()
              )
              .build());
      });
  }

  public void startStopwatchExample(Player viewer) {
      Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
      apolloPlayerOpt.ifPresent(apolloPlayer -> this.stopwatchModule.startStopwatch(apolloPlayer, "parkour-stopwatch"));
  }

  public void addTimerExample(Player viewer) {
      Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());

      apolloPlayerOpt.ifPresent(apolloPlayer -> {
          this.stopwatchModule.addTimer(apolloPlayer, Timer.builder()
              .id("game-timer")
              .name("Countdown")
              .duration(Duration.ofSeconds(45))
              .loop(false)
              .preventModification(true)
              .hideWhenStopped(false)
              .customFormat("mm:ss")
              .titleText(Component.text("Time's up!", NamedTextColor.RED))
              .ingameNotification(true)
              .textColor(ApolloColors.LIGHT_PURPLE)
              .hudPosition(HudPosition.builder()
                  .x(-10)
                  .y(30)
                  .build()
              )
              .build());
      });
  }

  public void startTimerExample(Player viewer) {
      Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
      apolloPlayerOpt.ifPresent(apolloPlayer -> this.stopwatchModule.startTimer(apolloPlayer, "game-timer"));
  }

---

Review Request Checklist

• Your code follows the style guidelines of this project.
• I have performed a self-review of my code.
• I have tested this change myself. (If applicable)
• I have made corresponding changes to the documentation. (If applicable)
• The branch name follows the projects naming conventions. (e.g. feature/add-module & bugfix/fix-issue)

---