Trick or Treat & Haunted Mobs

Overview

This page documents every feature of the plugin, its commands, permissions, placeholders, and configuration keys. Each feature section lists what it does and the exact config options that control it.

The plugin ships with three main config files and manages several data files automatically. Everything is designed to work out of the box — install it, restart, and the default Halloween experience is live.

Feature list at a glance

• Candy Currency — a server-wide currency earned across the plugin and spent in GUIs.
• GUI Hub Menu — one clean menu (SmartInvs) linking to shop, costumes, and leaderboard.
• Spooky Shop — buy items/perks with candy through a configurable GUI.
• Costume Wardrobe — equip disguises, optionally per-rank or for a candy price.
• Pumpkin Hunt — multi-level pumpkin-breaking progression with rewards.
• Leaderboard — GUI & placeholder ranking of top pumpkin hunters.
• Headless Horseman Boss — boss bar, minion waves, weighted loot, auto-spawn.
• Blood Moon Event — timed server-wide event with a candy multiplier.
• Haunted Loot Chests — ambush-and-reward chests.
• Jump Scares — random ghost apparitions with sound & disguise.
• Spooky Mobs — themed heads, sounds, and disguises on natural spawns.
• Villager Trick-or-Treat — right-click villagers for treats or tricks.
• Login Disguises — disguise players automatically on join.

Compatibility

Installation

1. Drop TrickOrTreatPlugin-4.4-SNAPSHOT.jar into your server's plugins/ folder.
2. (Optional) Install LibsDisguises, LuckPerms, and PlaceholderAPI for the optional integrations.
3. Start the server once to generate the config files, then edit them and run /tt reload.

Config Files

Data files (candy.yml, pumpkinprogress.yml, pumpkinblocks.yml, hauntedchests.yml) are created and maintained automatically — see Data & Persistence.

Commands

Base command: /tt (alias /trickortreat). Running /tt with no arguments opens the GUI hub for players.

Permissions

Placeholders PlaceholderAPI

Register these anywhere PlaceholderAPI is supported (scoreboards, holograms, GUIs, chat).

Candy Currency

Candy is the single currency that ties the plugin together. Players earn it from many sources and spend it in the shop and wardrobe. Balances are saved to candy.yml asynchronously (no main-thread lag) and flushed on shutdown.

Earning candy

• Breaking a counted pumpkin → candy.per-pumpkin
• A villager "treat" → candy.per-treat
• Being credited with a boss kill → candy.per-boss-kill
• Opening a haunted chest → hauntedchest.candy

All earnings are multiplied during a Blood Moon by bloodmoon.candy-multiplier.

config.yml

candy:
  per-pumpkin: 1
  per-treat: 2
  per-boss-kill: 25

Check balances with /tt candy or %trickortreat_candy%.

GUI Hub Menu SmartInvs

Running /tt (or /tt menu) opens a central menu with buttons for the Shop, Costumes, and Leaderboard, plus a live stats panel showing the player's candy, pumpkin progress, rank, and Blood Moon status.

config.yml

menu:
  title: "&6Trick or Treat"
  leaderboard-title: "&ePumpkin Leaderboard"

Spooky Shop GUI

Open with /tt shop. Each item is defined in config with an icon, name, lore, slot, candy cost, and a list of console commands run on purchase. Purchases are refused if the player can't afford them.

config.yml

shop:
  title: "&1Spooky Shop"
  rows: 3
  items:
    golden_apple:
      slot: 10                # 0-based inventory slot
      icon: GOLDEN_APPLE
      name: "&6Golden Apple"
      cost: 10
      lore: ["&7A tasty pick-me-up."]
      commands:
        - "give %player% golden_apple 1"

Costume Wardrobe GUI LibsDisguises

Open with /tt costume. Players click a costume to disguise as that mob; a barrier button removes the costume. Requires LibsDisguises — if it's absent the command explains that costumes are unavailable.

Selling / locking costumes

Each costume may set its own permission and/or cost. This is how you sell costumes per rank: give a costume a permission node and grant it via your rank/donor package. Locked costumes show a configurable "locked" lore (or are hidden entirely), and the permission is re-checked server-side on click so it can't be bypassed.

config.yml

costumes:
  title: "&5Costume Wardrobe"
  rows: 6
  cost: 0                        # default candy price (0 = free)
  hide-no-permission: false      # true = hide costumes the player can't use
  locked-text: "&cLocked — buy this costume!"     # lore on a locked costume
  locked-message: "&cYou don't own this costume." # chat msg on locked click
  list:
    - icon: ZOMBIE_HEAD
      name: "&2Zombie"
      disguise: ZOMBIE
    - icon: TOTEM_OF_UNDYING
      name: "&5Evoker"
      disguise: EVOKER
      permission: "trickortreat.costume.evoker"   # donor-only
      cost: 50                                      # overrides default cost

The default wardrobe ships with 16 costumes: Zombie, Creeper, Skeleton, Wither Skeleton, Witch, Spider, Enderman, Slime, Phantom, Blaze, Ghast, Drowned, Husk, Stray, Pillager, Evoker.

Pumpkin Hunt

Players break pumpkins to progress. Every break can grant a small random reward, and crossing level thresholds grants bigger rewards. Progress is per-player and saved across restarts. The plugin tracks how each pumpkin originated so you can decide which ones count.

Source rules

Pumpkins are classified as natural, grown (from a stem), or placed (by a player). Enable/disable each independently to prevent farming exploits.

Levels

With levels.enabled: true, define a number of levels and a target for each. Players earn a per-level-win reward each time they cross a threshold, and a one-time big-win after completing them all. With levels disabled, a single total-pumpkins goal and win-event reward are used.

pumpkinhunt.yml

total-pumpkins: 10          # used when levels.enabled = false

rules:
  count-player-placed: false
  count-grown: true
  count-natural: true

pumpkin-rewards:            # random reward per break
  - command: "give %player% minecraft:cookie 5"
    message: "&aYou found a hidden pumpkin!"
    event:
      sound: minecraft:entity.player.levelup
      firework: true

levels:
  enabled: true
  count: 5
  targets: [10, 10, 10, 10, 30]
  per-level-win:
    command: "say %player% completed a pumpkin level!"
    message: "&6Level complete!"
  big-win:
    command: "say %player% completed ALL pumpkin levels!"
    message: "&6&lAll levels complete!"

Players view progress with /tt pumpkins or the pumpkin placeholders.

Leaderboard

/tt top opens a GUI ranking the top pumpkin hunters (player heads with totals); the console gets a text list. Player names are cached for display. Ranks are also available via placeholders (%trickortreat_pumpkins_rank%, %trickortreat_pumpkins_top_<n>_name%, %trickortreat_pumpkins_top_<n>_amount%).

Headless Horseman Boss

A named skeleton riding a skeleton horse, wielding an enchanted netherite axe. Spawn it manually with /tt horseman or let the auto-spawner handle it. Remove it with /tt horseman despawn.

Features

• Boss health bar shown to nearby players (configurable colour, style, and range).
• Minion waves spawn periodically during the fight.
• Weighted loot table — control how likely each reward is (falls back to random-commands if no loot list is set).
• Smart kill attribution — credits the correct player even for projectile, pet, or TNT kills; the boss and its mount both count toward attribution.
• Fireproof — never burns away in daylight; the mount is always cleaned up on death.
• Auto-spawn at a fixed location, on an interval, within a world-time window, optionally requiring nearby players and/or force-loading the chunk.
• Single-instance guard and a post-death cooldown.

hauntedmobs.yml

boss-mobs:
  headless-horseman:
    display-name: "&cHeadless Horseman"
    message-on-spawn: "&aThe Headless Horseman rides again!"
    spawn-chance: 1.0
    health: 150.0
    sound: "entity_lightning_bolt_thunder"

    bossbar:
      enabled: true
      color: "PURPLE"          # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
      style: "SEGMENTED_10"    # SOLID, SEGMENTED_6/10/12/20
      range: 64

    reward:
      loot:                    # weighted; one entry is chosen
        - command: "give %player% nether_star 1"
          weight: 1
        - command: "give %player% diamond 3"
          weight: 5
      random-commands:         # legacy equal-chance fallback
        - "give %player% diamond 3"
      message: "&6The Headless Horseman has been defeated!"
      sound: "entity_wither_death"

    define-spawn-location: true
    spawn-location: "world,0.5,66,-17.0"
    cooldown-of-spawn-after-death: 3600

    auto:
      enabled: true
      interval-seconds: 120
      region-radius: 96
      require-player-nearby: true
      force-load-chunk: false
      world-time:
        from: 13000
        to: 23000

    minions:
      enabled: true
      interval-ticks: 200
      count-per-wave: 3
      max-alive: 10
      target-radius: 24.0
      despawn-on-boss-death: true
      types: [BABY_ZOMBIE, SILVERFISH, CAVE_SPIDER]

Blood Moon Event

A server-wide timed event started with /tt bloodmoon start and ended with stop (or automatically after its duration). While active, a red countdown boss bar is shown to every online player and all candy earnings are multiplied.

config.yml

bloodmoon:
  duration-seconds: 300
  candy-multiplier: 2
  bar-title: "&4Blood Moon"
  announce: "&4&lThe Blood Moon rises... candy is worth double!"
  end-announce: "&5The Blood Moon fades."

Track the state with %trickortreat_bloodmoon%.

Haunted Loot Chests

Place a chest with /tt hauntedchest (targets the block you're looking at). When a player right-clicks it, the chest bursts: it rewards candy and loot commands, then ambushes the player with mobs and vanishes. Chest locations persist across restarts in hauntedchests.yml.

config.yml

hauntedchest:
  candy: 10
  message: "&5A haunted chest bursts open — something stirs!"
  loot-commands:
    - "give %player% diamond 1"
  ambush-count: 3
  ambush-types: [ZOMBIE, SKELETON, SPIDER]

Jump Scares

On mob spawns there is a configurable chance to trigger a jump scare: an eerie sound and, if LibsDisguises is installed, a brief disguise. Boss and minion entities are excluded so the boss fight is never affected.

hauntedmobs.yml

jump-scares:
  ghost-mob:
    spawn-chance: 0.15
    sound: "entity_phantom_swoop"
    disguise-as: "PHANTOM"
    disguise-duration-seconds: 3

Spooky Mobs

Naturally spawning zombies and skeletons have a configurable chance to spawn "spooky": wearing a themed head, playing a custom sound, and optionally disguised via LibsDisguises. Boss/minion entities are never affected.

hauntedmobs.yml

spooky-mobs:
  zombie:
    spawn-chance: 0.3
    head: "CARVED_PUMPKIN"
    sound: "entity_zombie_ambient"
    disguise-as: "HUSK"
    disguise-chance: 0.25
    disguise-duration-seconds: 30
  skeleton:
    spawn-chance: 0.25
    head: "SKELETON_SKULL"
    sound: "entity_skeleton_ambient"
    disguise-as: "STRAY"
    disguise-chance: 0.20
    disguise-duration-seconds: 30

logging:
  spooky-mobs: false
  jump-scares: false

Villager Trick-or-Treat

Right-clicking a villager rolls a treat or a trick. Rewards are configured per LuckPerms group (with a default fallback) and gated by per-group cooldowns. Treats grant candy; tricks can apply effects or a brief disguise. You can optionally restrict interaction to a specifically named villager or require an empty hand.

config.yml

villager-interaction:
  cancel-trade: true
  only-named: ""              # restrict to a villager with this name (blank = any)
  require-empty-hand: false
  treat-chance: 0.5           # chance of treat vs trick
  messages:
    cooldown: "&cYou are on cooldown. Please wait %seconds% seconds."
    no-reward: "&cNo rewards configured."
    require-empty-hand: "&cEmpty your hand to trick-or-treat!"

reward-per-luckpermsgroups: true
default-cooldown: 60
custom-cooldowns:
  default: 60
  vip: 30
  elite: 10

rewards:
  default:
    tricks:
      command: "effect give %player% slowness 10 1"
      message: "&cTRICK! Slowness for you..."
      event: { firework: false, sound: "ENTITY_WITCH_CELEBRATE" }
    treats:
      command: "give %player% cookie 5"
      message: "&aTREAT! Enjoy cookies!"
      event: { firework: true, sound: "ENTITY_PLAYER_LEVELUP" }

Login Disguises LibsDisguises

Automatically disguise players when they join. Four modes are supported: a single default mob, a random pick from a pool, a per-LuckPerms-group mapping, or a per-permission mapping. Disguises can be persistent or timed, and optionally removed on quit.

config.yml

libdisguise:
  enabled: true
  login:
    enabled: true
    delay-ticks: 5
    persistent: true            # false = timed (uses duration-seconds)
    duration-seconds: 600
    undisguise-on-quit: true
    mode: "default"             # default | random | group | permission
    default-mob: "ZOMBIE"
    random-pool: ["ZOMBIE","SKELETON","CREEPER","WITCH","HUSK","STRAY"]
    groups:
      vip: "WITHER_SKELETON"
      elite: "WITCH"
      default: "ZOMBIE"
    permissions:
      - node: "trickortreat.disguise.CREEPER"
        mob: "CREEPER"

LibsDisguises Integration

Optional. Enables the Costume Wardrobe, login disguises, and the disguise effects on spooky mobs, jump scares, and villager tricks. Toggle globally with libdisguise.enabled in config.yml. If LibsDisguises is not installed, all disguise features degrade gracefully (they are skipped, and the costume command explains it is unavailable).

LuckPerms Integration

Optional. Used to resolve a player's primary group for per-group villager rewards (reward-per-luckpermsgroups), per-group cooldowns (custom-cooldowns), and group-based login disguises. Without LuckPerms, the plugin falls back to the default group entries.

PlaceholderAPI Integration

Optional. When present, the plugin registers the %trickortreat_*% placeholders listed in the Placeholders section. Without it, those placeholders simply aren't available; all other features work normally.

SmartInvs (bundled)

The GUI menus (hub, shop, costumes, leaderboard) are built on the SmartInvs inventory framework, which is bundled and relocated inside the plugin jar. You do not need to install it, and the relocation means it won't conflict with other plugins that ship their own copy.

Data & Persistence

Player data (candy balances and pumpkin progress) uses a pluggable storage backend selected in config.yml. All writes happen off the main thread on a 10-second flush and again on shutdown/reload — no lag on busy servers.

config.yml

storage:
  type: sqlite       # sqlite | yaml

Other data files (always YAML)

Changelog

v4.4

• Added the Candy currency, Spooky Shop, Costume Wardrobe (with per-costume permissions & pricing), Blood Moon event, Haunted Loot Chests, and a SmartInvs GUI hub + leaderboard.
• Migrated the build to Paper 1.21.8 / Java 21 with api-version: 1.21; one jar targets Minecraft 1.21.8 → 26.3.
• Hardened all sound playback against the ongoing Sound registry migration.

v4.3

• Boss health bar, minion waves, weighted loot, and smart kill attribution.
• Pumpkin leaderboard + rank placeholders; admin reset command.
• Async/debounced pumpkin persistence; unified cooldown-bypass permission.

v4.2 and earlier

• Pumpkin hunt, jump scares, spooky mobs, Headless Horseman boss, villager trick-or-treat, login disguises, and PlaceholderAPI/LuckPerms/LibsDisguises integrations.