> ## Documentation Index
> Fetch the complete documentation index at: https://vctdocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Usage Examples

> Practical examples of using VCT events in your plugin.

<Info>
  These are only basic examples — you can mix and match events to create complex logic such as countdown-based minigames, reward systems, or event triggers.
</Info>

## Broadcast when a timer starts

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      if (event.getType() == VCTEventType.CREATE) {
          String timerId = event.getTimerId();
          String timeInitial = event.getInitialTime();

          Bukkit.broadcastMessage("A new timer has started: " + timerId + " (" + timeInitial + ")");
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_create_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timerId%;getTimerId()'
      - '%timeInitial%;getInitialTime()'
    conditions:
    - '%eventType% == CREATE'
    actions:
      default:
      - 'to_all: actionbar: A new timer has started: %timerId% (%timeInitial%);100'
  ```
</CodeGroup>

* Useful for announcing timers to all players.
* Gives context when a new timer begins.

## Send bossbar updates every second

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      if (event.getType() == VCTEventType.CHANGE) {
          String timeLeft = event.getTimeLeft();

          Bukkit.getOnlinePlayers().forEach(player -> {
              player.sendActionBar("Time left: " + timeLeft);
          });
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_change_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timeLeft%;getTimeLeft()'
    conditions:
    - '%eventType% == CHANGE'
    actions:
      default:
      - 'to_all: actionbar: Time left: %timeLeft%;100'
  ```
</CodeGroup>

* Runs every second.
* Good for syncing custom UI or scoreboards with the timer.

## Grant rewards when timer finishes

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      if (event.getType() == VCTEventType.FINISH && event.getTimerId().equals("xp_challenge")) {
          Bukkit.broadcastMessage("The XP Challenge has ended!");

          // Reward all players
          for (Player player : Bukkit.getOnlinePlayers()) {
              player.giveExpLevels(5);
          }
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_finish_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timerId%;getTimerId()'
    conditions:
    - '%eventType% == FINISH'
    - '%timerId% == xp_challenge'
    actions:
      default:
      - 'to_all: message: The XP Challenge has ended!'
      - 'console_command: xp add @a 5 levels' # Reward all players
  ```
</CodeGroup>

* Perfect for minigames or challenges (`xp_challenge`) that end with rewards.
* Trigger extra logic when the timer reaches 00:00:00.

## Pause/resume feedback

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      switch (event.getType()) {
          case PAUSE:
              if (event.getTimerId().equals("game_round")) {
                  Bukkit.broadcastMessage("The round has been paused");
              }
              break;
          case RESUME:
              if (event.getTimerId().equals("game_round")) {
                  Bukkit.broadcastMessage("The round has resumed!");
              }
              break;
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_pause_resume_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timerId%;getTimerId()'
    conditions:
    - '%timerId% == game_round'
    - '%eventType% == PAUSE execute paused'
    - '%eventType% == RESUME execute resumed'
    actions:
      paused:
      - 'to_all: message: The round has been paused'
      resumed:
      - 'to_all: message: The round has resumed!'
  ```
</CodeGroup>

* Keeps players informed about game-round timers only.

## Log when a timer is stopped manually

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      if (event.getType() == VCTEventType.STOP) {
          Bukkit.getLogger().info("[MyPlugin] Timer stopped: " + event.getTimerId());
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_stop_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timerId%;getTimerId()'
    conditions:
    - '%timerId% == game_round'
    - '%eventType% == STOP'
    actions:
      default:
      - 'to_all: actionbar: Timer stopped %timerId%;100'
  ```
</CodeGroup>

* Useful for debugging or auditing timer interruptions.
* Logs any timer being stopped.

## Announce time modifications

<CodeGroup>
  ```java Java Example theme={null}
  @EventHandler
  public void onVCTEvent(VCTEvent event) {
      if (event.getType() == VCTEventType.MODIFY && event.getTimerId().equals("pvp_event")) {
          String modifier = event.getModifier();
          String modification = event.getModification();

          if (modifier.equals("ADD")) {
              Bukkit.broadcastMessage("The PVP event has been extended by " + modification + "!");
          } else if (modifier.equals("TAKE")) {
              Bukkit.broadcastMessage("The PVP event has been reduced by " + modification);
          } else if (modifier.equals("BOSSBAR_STYLE")) {
              Bukkit.broadcastMessage("The segments of the boss bar in the PVP event have changed to " + modification);
          }
      }
  }
  ```

  ```yaml CE Example theme={null}
  vct_modify_example:
    type: custom
    custom_event_data:
      event: voiidstudios.vct.api.VCTEvent
      variables_to_capture:
      - '%eventType%;getType()'
      - '%timerId%;getTimerId()'
      - '%modifier%;getModifier()'
      - '%modification%;getModification()'
    conditions:
    - '%timerId% == pvp_event'
    - '%eventType% == MODIFY'
    - '%modifier% == ADD execute added'
    - '%modifier% == TAKE execute taked'
    - '%modifier% == BOSSBAR_STYLE execute segments'
    actions:
      add:
      - 'to_all: message: The PVP event has been extended by %modification%!'
      take:
      - 'to_all: message: The PVP event has been reduced by %modification%'
      style:
      - 'to_all: actionbar: The segments of the boss bar in the PVP event have changed to %modification%;100'
  ```
</CodeGroup>

* Lets everyone know when the timer is adjusted or modified.
* Great for competitive scenarios (adding bonus time, penalties, etc.).