A customizable Minecraft Hide and Seek minigame plugin, with custom items, loadouts, cosmetics, multiple game modes, a perk system, and extensive stats tracking.

Table of Contents

• Overview
• Screenshots
• Game Modes
• Features
• Requirements
• Installation
• Configuration
• Map Setup
• Loadout System
• Perk System
• Items Reference
• Commands & Permissions
• NMS Features
• Project Structure
• Building from Source

Overview

HideAndSeek is a Minecraft minigame plugin in which one team hides while the other seeks. Hiders can disguise themselves as blocks, shrink to a tiny size, wear custom skins, or simply rely on good hiding spots, while seekers use a diverse arsenal of utility items to track, reveal, and eliminate them. The plugin is built on top of MinigameFramework (also developed by me), which handles phase management, team assignment, item registration, and player data persistence.

The plugin supports custom maps with per-map setting overrides, a lobby voting system for maps and game modes, a persistent loadout and cosmetic skin system, a round-based perk shop, detailed per-player statistics, and an extensive in-game settings GUI provided by MinigameFramework.

Screenshots

https://github.com/user-attachments/assets/5b4c1312-afd0-4cdd-96a1-fd94ada127a8

Block mode: hiders disguise as blocks and blend into the environment.

The loadout screen. Hiders and seekers have separate item pools and token budgets.

https://github.com/user-attachments/assets/d648ddb3-64c7-426b-a90d-e6340d015343

Block Selector GUI for choosing and customizing your block disguise.

https://github.com/user-attachments/assets/4ef363c3-2379-4074-812d-bf023cd184ff

https://github.com/user-attachments/assets/5cc24e07-a249-480d-83b5-f1e79d4e51a4

https://github.com/user-attachments/assets/ebb8a135-0015-4d5d-8daa-06d11a6f2318

The Proximity Sensor, Camera System, and Cage Trap in action.

Game Modes

Game modes can be changed via the in-game settings GUI or voted on by players in the lobby.

Features

Core Gameplay

• Four distinct game modes: Normal, Block, Small, Skin
• Lobby with player readiness checks and map/gamemode/role-preference voting
• Configurable hiding and seeking phase durations
• World border support with per-map border configurations
• Automatic map cleanup and lobby return after each round
• Points and scoring system with round-end coin rewards
• Boss bar showing remaining hiders and seekers during the seeking phase
• Anti-cheat visibility filtering: seekers only see hiders within a configured range and line of sight
• Hider camping detection and punishment system
• Environmental damage capping (drowning, fire, lava, suffocation, freezing, contact, hot floor) to prevent hiders escaping through hazards
• Adrenaline Rush comeback mechanic: buffs trigger when the last hider(s) survive or time runs low

Map System

• Multiple maps with per-map configuration (allowed blocks, skins, timings, seeker count, setting overrides, vending machine locations)
• Random map selection or player lobby voting
• Automatic world copying and deletion per round
• Per-map world borders, spawn points, and block lists
• Map info title shown at round start (configurable display mode)

Loadout System

• Players customize their item selection in the lobby before each round
• Token budget system with five rarity tiers: Common, Uncommon, Rare, Epic, Legendary
• Separate hider and seeker loadout slots and token pools
• Slot preferences: assign item types to specific inventory slots with configurable fallbacks
• Admin loadout manager GUI: filter items per role (blacklist/whitelist), lock individual player loadouts, define admin role presets, force a preset on all players
• Loadout data persisted across sessions via database or YAML

Perk System

• Per-round perk shop: a random selection of perks is offered each round
• Two shop modes: inventory row (items placed directly in the player's hotbar) or vending machine (droppers placed at configured map locations)
• Hider perks: Adaptive Speed, Seeker Warning, Extra Life, Shadow Step, Camouflage, Double Jump, Trap Sense
• Seeker perks: Death Zone, Random Swap, Map Teleport, Relocate, Elytra Rush, Proximity Meter, Scent Trail, Auto Aim, Hit Display, Sword Bounce
• Finite perks: only one player per team can buy certain perks per round
• Seeker rebuyable perks: can be purchased multiple times with a configurable cooldown
• All perk costs, cooldowns, thresholds, and behaviours are configurable per-setting

Cosmetic System

• Item skins (variants) purchasable with coins earned from round points
• Each item has multiple skins with unique visual appearances
• Kill effects: custom effects played when a seeker eliminates a hider
• Win skins: special effects played for the winning team at round end
• Death messages: custom kill/environmental death message formatting
• Coin shop with configurable rarity-based prices
• Cosmetic data persisted across sessions

Statistics System

• Per-player stats tracked across all rounds: wins, losses, kills, deaths, damage dealt, survival time, playtime, taunts, last-hider-standing rounds, points and coins earned
• Per-item usage tracking (times equipped, times used)
• Per-map and per-game-mode play count tracking
• Perk usage tracking
• Block mode: hidden vs exposed time tracking
• Five-tab stats GUI: Overview, Combat, Items, Maps, Perks
• Admin /mg stats command to view any player's stats

Hider Items

Firecracker, Big Firecracker, Firework Rocket, Cat Sound, Speed Boost, Knockback Stick, Tracker Crossbow, Block Swap, Random Block, Smoke Bomb, Slowness Ball, Invisibility Cloak, Medkit, Totem of Undying, Ghost Essence (NMS only, falls back to limited behaviour without NMS), Remote Gateway

Seeker Items

Seeker's Blade (chargeable + throwable), Grappling Hook, Ink Splash, Lightning Freeze, Glowing Compass, Curse Spell, Block Randomizer, Chain Pull, Proximity Sensor, Cage Trap, Phantom Viewer, Camera System (NMS only, disabled without it), Seeker's Assistant (NMS only, disabled without it)

Requirements

MinigameFramework

[!IMPORTANT] HideAndSeek depends on MinigameFramework, a companion library also developed by me. It is not currently publicly available, neither the JAR nor the source code.

[!NOTE] MinigameFramework will be released publicly in the future. This section will be updated when that happens.

Installation

1. Ensure your server runs Paper 1.21.10/11 with Java 21 or newer.
2. Wait until MinigameFramework.jar is released and place it in your plugins/ folder.
3. Place HideAndSeek-1.0-SNAPSHOT.jar in your plugins/ folder.
4. Start the server once to generate config files.
5. Set up at least two scoreboard teams via MinigameFramework's team configuration.
6. Add at least one map (see Map Setup).
7. Restart the server.

Quick Checklist

• Java 21+ on the server
• Paper 1.21.10/11 server jar
• MinigameFramework.jar in plugins/
• HideAndSeek-1.0-SNAPSHOT.jar in plugins/
• Two teams configured in MinigameFramework
• At least one map entry in plugins/HideAndSeek/maps.yml
• Server restarted after first run

Configuration

The plugin generates config.yml and maps.yml in plugins/HideAndSeek/ on first run.

How settings work

All gameplay settings are managed through the in-game settings GUI, provided by MinigameFramework. The config.yml file only serves to override the default value of a setting. If a setting is not present in config.yml, the plugin's built-in default is used instead. Changes made in the GUI take effect immediately but do NOT persist across restarts.

Top-level config keys

# Hide & Seek Plugin Configuration

# List of available map world names
# These must match the world names in maps.yml
maps:
  - "map1"
  - "map2"

# NOTE: Map-specific configuration (spawn-points, allowed-blocks, world-borders, preferred-modes)
# is saved in maps.yml. See that file for per-map settings.

nms:
   # Master switch: attempt to load NMS adapter. If true, plugin will try to enable NMS features
   # on startup. If adapter missing or fails, behavior depends on fallbacks.
  enabled: true

persistence:
  save-skin-data: true
  save-loadout-data: true

inject-datapack: true

tab:
   enable-header: true
   enable-footer: true
   server-ip: "yourserver.com"

   # Header configuration
   header:
      # Color gradient settings for animated text
      title-colors:
         - "#FF0000" # Red
         - "#FFFF00" # Yellow
      title-speed: 0.5

      ip-colors:
         - "#00FF00" # Green
         - "#00FFFF" # Aqua
         - "#0088FF" # Light Blue
      ip-speed: 0.3

      # Header elements
      elements:
         - text: "Hello "
           enabled: true
           color: "#808080" # Gray
           animated: false
         - text: "{player}"
           enabled: true
           color: "#FFFF00" # Yellow
           animated: false
         - text: "!"
           enabled: true
           color: "#808080" # Gray
           animated: false
         - text: "\nYou are playing "
           enabled: true
           color: "#808080" # Gray
           animated: false
         - text: "HideAndSeek"
           enabled: true
           color-list: "title-colors" # Use color gradient
           speed: "title-speed"
           animated: true
         - text: " on "
           enabled: true
           color: "#808080" # Gray
           animated: false
         - text: "{server-ip}"
           enabled: true
           color-list: "ip-colors" # Use color gradient
           speed: "ip-speed"
           animated: true
         - text: "\n\n"
           enabled: true
           color: "#FFFFFF" # White
           animated: false

   # Footer configuration
   footer:
      # Footer elements
      elements:
         - text: "\nRole: "
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "{role}"
           enabled: true
           color: "{role-color}"
         - text: " | "
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "{mode}"
           enabled: true
           color: "#008000" # Green
         - text: "\nPlayers: "
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "{players-total}"
           enabled: true
           color: "#FFFFFF" # White
         - text: " ("
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "{players-hiders}"
           enabled: true
           color: "#00AA00" # Green
         - text: "|"
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "{players-seekers}"
           enabled: true
           color: "#FF0000" # Red
         - text: ")"
           enabled: true
           color: "#A9A9A9" # Dark Gray
         - text: "\nPoints: "
           enabled: true
           color: "#FFD700" # Gold
         - text: "{points}"
           enabled: true
           color: "#FFD700" # Gold
         - text: "\nCoins: "
           enabled: true
           color: "#FFFF00" # Yellow
         - text: "{coins}"
           enabled: true
           color: "#FFFF00" # Yellow
         - text: "\n"
           enabled: true
           color: "#FFFFFF" # White

scoreboard:
   enabled: true
   title:
      text: "HideAndSeek"
      small-caps: true
      underline: true
      colors:
         gradient:
            - "#FF0000" # Red
            - "#FFFF00" # Yellow

   animation:
      enabled: true
      speed: 0.15

   formatting:
      small-caps: true
      padding: true
      padding-amount: 3

   lines:
      - text: "Role:"
        enabled: true
        color: "#A9A9A9" # Dark Gray
      - text: "{role}"
        enabled: true
        color: "#0000FF" # Blue
      - text: "Mode:"
        enabled: true
        color: "#A9A9A9" # Dark Gray
      - text: "{mode}"
        enabled: true
        color: "#008000" # Green
      - text: "Players: {players-total} ({players-hiders}|{players-seekers})"
        enabled: true
        color: "#A9A9A9,#FFFFFF,#00FF00,#FF0000"
      - text: "Points: {points}"
        enabled: true
        color: "#FFD700" # Gold
      - text: "Coins: {coins}"
        enabled: true
        color: "#FFFF00" # Yellow

settings:
   # Global disallowed blockstate properties for the appearance GUI
  disallowed-blockstates:
    - "waterlogged"
    - "conditional"

  seeker-break-blocks:
    - "SHORT_GRASS"
    - "TALL_GRASS"
    - "SEAGRASS"
    - "TALL_SEAGRASS"

  block-interaction-exceptions:
    - "*_DOOR"
    - "*_FENCE_GATE"
    - "*_TRAPDOOR"
    - "*_BUTTON"
    - "*_LEVER"

  block-physics-exceptions:
    - "*_DOOR"
    - "*_FENCE_GATE"
    - "*_TRAPDOOR"
    - "*_BUTTON"
    - "*_LEVER"

Overriding setting defaults

Any setting shown in the in-game GUI can have its default value overridden in config.yml under the settings: key. For example:

settings:
  game.mode: BLOCK
  game.hiding-time: 90
  game.seeking-time: 240
  game.hiders.health: 10
  anticheat.seeking.visibility-range: 16.0
  loadout.hider-max-items: 4
  loadout.hider-max-tokens: 14
  hider-items.speed-boost.cooldown: 15
  seeker-items.glowing-compass.cooldown: 30
  points.hider.survival.amount: 10
  perks.enabled: true
  perks.perks-per-round: 3

A full list of available setting keys can be found in SettingRegistrar.java.

Map Setup

Maps are defined in plugins/HideAndSeek/maps.yml. Each key is the internal map name and must match the name of a world folder present on the server.

map1:
  pretty-name: "Starter Valley"
  description: "Default map"
  author: "Server Admin"
  size: "MEDIUM"
  icon: "GRASS_BLOCK"
  spawn-points:
    - "0,65,0,0,0"       # Format: x,y,z,yaw,pitch
  world-borders: []       # Format: centerX,centerZ,size  OR  centerX,centerZ,r:radius
  preferred-modes:
    - "BLOCK"
  seeker-break-blocks:
    - "SHORT_GRASS"
    - "TALL_GRASS"
  block-interaction-exceptions:
    - "*_DOOR"
    - "*_FENCE_GATE"
    - "*_TRAPDOOR"
    - "*_BUTTON"
    - "*_LEVER"
  block-physics-exceptions:
    - "*_DOOR"
    - "*_FENCE_GATE"
    - "*_TRAPDOOR"
    - "*_BUTTON"
    - "*_LEVER"
  setting-overrides:
    hider-items:
      firework-rocket:
        target-y: 64
  players:
    min: 4
    recommended: 8
    max: 16
  seekers:
    min: 1
    per-players: 8
    max: 4
  timings:
    hiding-time: 60
    seeking-time: 300
  vending-machine-locations:    # Dropper blocks placed during seeking for the perk vending machine shop mode
    - "12,64,-8"
    - "-40,71,22"
  allowed-blocks:               # Used in BLOCK mode
    - "STONE"
    - "OAK_LOG[*]"
    - "*CANDLE{RED_CANDLE}"
    - "OAK_TRAPDOOR[half,open,facing]"
  allowed-skins:                # Used in SKIN mode; references keys defined in skins.yml
    - "oak_log"
    - "stone"

World Border Format

If spawn-point count equals world-border count, each spawn is matched to its corresponding border by index. Otherwise, all spawns use the first border.

Block Pattern Syntax

The allowed-blocks list accepts a pattern DSL for flexible block selection:

Skin Setup

Custom skins for SKIN mode are defined in plugins/HideAndSeek/skins.yml:

oak_log:
  name: "Oak Log"
  icon: "minecraft:oak_log"
  value: "<base64 skin texture value>"
  signature: "<base64 skin texture signature>"

Skin textures can be generated using services such as Mineskin. Each skin entry must have a valid signed value/signature pair.

Loadout System

Players configure their loadout in the lobby before each round. Each item has a rarity that determines its token cost.

By default, hiders have 12 tokens and up to 3 item slots. Seekers have 12 tokens and up to 4 item slots. All values are configurable via the in-game settings GUI or under settings.loadout.* in config.yml.

Slot Preferences

Players can configure which item types (e.g. Mobility, Offense, Trap) are placed in which inventory slots, with a fallback type per slot. This is accessible from the loadout GUI via the Slot Preferences button.

Admin Preset System

Admins can define up to 5 role presets per role (hider/seeker) in the Admin Loadout Manager GUI (/mg loadout admin). Presets can be:

• Enabled/disabled per slot
• Forced: locks all players of that role to the specified preset
• Restricted: players may only choose from enabled admin presets rather than building their own loadout

Perk System

At the start of each seeking phase, a random pool of perks is selected (configurable count). Players spend their accumulated round points in the perk shop to purchase perks.

Shop Modes

• Inventory: perk items are placed directly in the player's second hotbar row during the seeking phase.
• Vending Machine: dropper blocks are placed at positions defined in maps.yml under vending-machine-locations. Players interact with the dropper to open the shop.

Hider Perks

Seeker Perks

All perk costs, cooldowns, radii, durations, and other parameters are configurable via the settings GUI under the perks.* sections.

Items Reference

Hider Items

Seeker Items

Commands & Permissions

Note: Full permission nodes and additional admin commands will be documented once MinigameFramework's command API is finalized.

Role Permissions

The following permissions are assigned automatically during a round and can be used for other plugins or command guards:

NMS Features

The NMS implementation currently targets Paper 1.21.10 (nms-v1_21_10) and Paper 1.21.11 (nms-v1_21_11). Adding support for another version requires a new Gradle module implementing the NmsAdapter interface and providing an NmsAdapterMeta that declares which Minecraft versions it supports.