Configuration reference

This is the config.yml AfkGuard writes on first start, comments included. Every key you see here is the key the plugin reads; there are no hidden ones. Change a value, reload, and it applies.
Top-level sections: language, afk, reasons, auto-kick.
# ============================================================
#  AfkGuard v1.0.0  ·  Configuration
# ------------------------------------------------------------
#  Part of the TTS-Studio plugin suite.
#  Hot-reload with /afk reload after any change.
# ============================================================

# Active language. ISO-639-1 two-letter code (lowercase).
# Bundled out of the box: es (Spanish), en (English).
# Missing keys fall back to en automatically. Operators can drop extra
# lang/<code>.yml files in plugins/AfkGuard/lang/.
language: en

afk:
  # Seconds of inactivity before a player is auto-marked AFK.
  default-timeout-seconds: 300

  # Per-permission overrides (granted permission = longer leash).
  # Highest matched value wins.
  per-permission-timeouts:
    "afkguard.timeout.vip": 600
    "afkguard.timeout.premium": 1200

  detection:
    # Require an actual block change before resetting the AFK timer —
    # tiny mouse jitter or sub-block packets won't count as activity.
    require-block-change: true
    # Minimum yaw/pitch delta (degrees) to count as a rotation.
    require-rotation-degrees: 5.0
    # Anti-macro: detect repeating movement loops (piston AFK pools etc.)
    cyclic-pattern-detection: true
    history-size: 20
    max-cycle-length: 10

  visual:
    # Nametag prefix shown above an AFK player (MiniMessage).
    name-tag: "<gray>[AFK] <player_name>"
    use-team-prefix: true

  zone:
    # When enabled, AFK players are teleported to a safe spot,
    # fed, and made invulnerable until they return.
    enabled: false
    location:
      world: "world"
      x: 0.0
      y: 80.0
      z: 0.0
      yaw: 0.0
      pitch: 0.0
    teleport-back-on-activity: true
    auto-feed: true
    invulnerable: true

  mob-cap-exclusion:
    # Cancel natural mob spawns near AFK-only players so the cap
    # doesn't fill up with mobs that nobody is fighting.
    enabled: true

# ============================================================
#  AFK STATUS REASONS  (v1.1.0)
# ------------------------------------------------------------
#  Lets players announce why they are going AFK.
#  Example: /afk dinner  ->  "Steve is now AFK (dinner)"
#
#  - reasons.enabled = false  -> /afk ignores any reason argument.
#  - reasons.free-text = true -> any word is accepted
#    (can invite spam or inappropriate text — off by default).
# ============================================================
reasons:
  enabled: true
  free-text: false
  allowed:
    - dinner
    - gaming
    - brb
    - working
    - sleeping

# ============================================================
#  AUTO-KICK  (v1.2.0)
# ------------------------------------------------------------
#  Kick players who stay AFK too long. Warnings are sent at
#  configurable intervals before the kick.
#
#  - enabled: false → feature is completely off (default, non-breaking).
#  - threshold-seconds: how long a player must be AFK before kick.
#  - warn-at: seconds before kick at which to send a warning message.
#    Example: [60, 30, 10] sends warnings at 9m, 9m30s, 9m50s for a
#    10-minute threshold.
#  - per-permission-thresholds: override threshold for specific groups.
#    Use -1 to prevent a group from ever being kicked.
#  Bypass permission: afkguard.bypass.kick (default false).
# ============================================================
auto-kick:
  enabled: false
  threshold-seconds: 600
  warn-at:
    - 60
    - 30
    - 10
  # Each entry overrides the threshold for players with that permission.
  # The highest matching threshold wins (most generous). Use -1 to exempt a group entirely.
  per-permission-thresholds:
    "afkguard.kick.vip": 1200
    "afkguard.kick.premium": -1