Skip to content

warning-stages.md

Latest commit

 

History

History
239 lines (181 loc) · 7.18 KB

warning-stages.md

File metadata and controls

239 lines (181 loc) · 7.18 KB

Warning Stages & Actions

AntiAFKPlus uses a staged warning system. Each stage triggers at a specific number of seconds of inactivity and can execute one or more actions. Stages are processed sequentially — once a player's idle time reaches a stage's trigger value, the do actions are executed.

How It Works

  1. A player stops all activity
  2. The plugin checks their inactivity every check-interval seconds
  3. When a stage's trigger time is reached, its actions fire
  4. If the player performs any detected activity, their timer resets to zero

Configuration Format

actions:
  - trigger: <seconds>
    do:
      - <action-type>:
          <parameters>

The last stage in the list defines the effective AFK kick timeout (unless overridden by per-group or per-world settings).

Available Actions

actionbar

Displays a message in the action bar above the player's hotbar.

- actionbar:
    text: "&eYou seem to be AFK"

title

Shows a full-screen title and optional subtitle.

- title:
    title: "&cAFK Warning"
    subtitle: "&7Move to avoid being kicked"
    fade-in: 10      # Ticks (20 ticks = 1 second)
    stay: 70
    fade-out: 20

bossbar

Displays a boss bar with a countdown timer. The bar automatically removes itself after the duration.

- bossbar:
    text: "&cYou will be kicked in %countdown%"
    color: RED
    style: SOLID
    duration: 30      # Seconds the boss bar stays visible
Parameter Values Default
color PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE RED
style SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20 SOLID
duration Seconds 30

The %countdown% placeholder shows the remaining time of the boss bar's own duration timer with a "s" suffix (e.g., if duration: 30, it counts down from 30s to 0s). Since the suffix is included, write your text as %countdown% not %countdown%s.

sound

Plays a sound for the player.

- sound:
    sound: BLOCK_NOTE_BLOCK_PLING
    volume: 1.0
    pitch: 1.0

Sound names use the Bukkit Sound enum. A full list can be found in the Spigot Javadocs.

message

Sends a plain chat message to the player.

- message:
    text: "&cYou will be kicked soon if you don't move!"

kick

Kicks the player from the server.

- kick:
    message: "&cYou were kicked for being AFK\n&7Please rejoin when you're back!"

Use \n for line breaks in the kick message.

command

Executes a command from the console. Useful for custom punishments, logging, or integration with other plugins.

- command:
    command: "broadcast &e%player% &7was kicked for being AFK"

The %player% placeholder is replaced with the player's name.

bungee-send

Sends the player to another server on your BungeeCord / Velocity network instead of kicking them.

- bungee-send:
    server: "hub"

fee

Charges the player a fee using Vault economy. Requires Vault and an economy plugin.

- fee:
    amount: 100
    message: "&c$%amount% has been deducted from your balance"

The message parameter is optional. If provided, the %amount% placeholder is replaced with the charged amount (formatted to 2 decimal places). The fee is only charged if the player's balance would remain above the economy.fee-on-kick.min-balance threshold.

webhook

Sends a notification to a Discord webhook.

- webhook:
    url: "https://discord.com/api/webhooks/..."
    message: "**%player%** was warned for being AFK"

The url parameter is required — without it, the action is silently skipped.

{% hint style="info" %} Note: If you only want Discord notifications on kicks, you don't need a webhook action at all. The kick action automatically sends a webhook when notifications.discord.enabled and notifications.discord.on-kick are both true in config.yml. The standalone webhook action is for sending notifications at non-kick stages (e.g., warnings). {% endhint %}

teleport

Teleports the player to a specified location. Useful for moving AFK players to an AFK area. If on-return.teleport-back is enabled in config.yml, the player's original location is saved and restored when they return from AFK.

- teleport:
    world: "world"
    x: 0.5
    y: 65.0
    z: 0.5
    yaw: 0.0
    pitch: 0.0

All parameters are optional — any omitted value defaults to the player's current position. Uses async teleportation on Folia/Paper for cross-region compatibility.

Example: Custom 3-Stage Setup

actions:
  # Warning at 3 minutes
  - trigger: 180
    do:
      - actionbar:
          text: "&eYou have been idle for 3 minutes"
      - sound:
          sound: ENTITY_EXPERIENCE_ORB_PICKUP
          volume: 0.5
          pitch: 2.0

  # Serious warning at 5 minutes with boss bar countdown
  - trigger: 300
    do:
      - title:
          title: "&c&lAFK WARNING"
          subtitle: "&7You will be kicked in 2 minutes!"
          fade-in: 10
          stay: 60
          fade-out: 20
      - bossbar:
          text: "&c&lAFK &7— Kick in %countdown%"
          color: RED
          style: SEGMENTED_20
          duration: 120
      - sound:
          sound: BLOCK_NOTE_BLOCK_PLING
          volume: 1.0
          pitch: 0.5

  # Kick at 7 minutes, charge fee, notify Discord
  - trigger: 420
    do:
      - fee:
          amount: 50
      - kick:
          message: "&c&lKicked for AFK\n\n&7You were idle for 7 minutes.\n&7A fee of &c$50 &7has been charged."
      - webhook:
          url: "https://discord.com/api/webhooks/your-webhook-url"
          message: "**%player%** was kicked for being AFK (7 minutes idle)"

Multiple Actions Per Stage

Each stage can have multiple actions that all execute when the trigger time is reached:

- trigger: 240
  do:
    - title:
        title: "&cLast Warning"
        subtitle: "&7Move now!"
    - sound:
        sound: BLOCK_ANVIL_LAND
        volume: 1.0
        pitch: 1.0
    - command:
        command: "tell %player% You are about to be kicked for AFK"

Placeholders in Actions

Placeholder Description Available In
%player% Player's name All actions
%uuid% Player's UUID All actions
%world% Player's current world All actions
%time% Formatted inactive time (e.g. "4m 30s") All actions
%time_seconds% Inactive time in raw seconds All actions
%warnings% Number of warnings the player has received All actions
%stage% Current warning stage number All actions
%countdown% Remaining seconds of the boss bar duration bossbar only