Quick Start Guide

Install the plugin and start your first match in 3 easy steps.

1. Requirements

• Server: Paper 1.21.1+ (or Purpur).
• Java: Java 21 LTS.
• Optional: PlaceholderAPI if using scoreboards.

2. Installation

1. Drop FindTheBlock-1.0.0.jar into your server's plugins/ folder.
2. Restart your server.
3. Done! The plugin creates its files in plugins/FindTheBlock/ automatically.

3. Play a Match

1. Join the server. You will spawn on the safe bedrock platform in the void lobby.
2. Give yourself admin rights with /op <your_name>.
3. Start a match:
   Chat Copy

   /start normal

4. The 10-second countdown begins, the roulette picks an item, and you are scattered into the world.
5. Forgot how to craft the target item? Type /recipe to see the crafting table recipe.
6. Collect or craft the item to win!

World Gen & Nether

How fresh Overworld and Nether worlds are generated with zero server lag.

Background World Factory Pipeline

Traditional minigames freeze the server when creating a new world. FindTheBlock prevents lag using a background generation pipeline:

• Standby Queue: It keeps a pre-generated world pair ready before the match starts.
• Paced Chunk Gen: New chunks are generated asynchronously at 30 chunks per second, keeping server TPS at a locked 20.0.
• Automatic Cleanup: When a match concludes, the temporary worlds are unloaded and wiped from disk completely.

Nether & The End Dimensions

• Nether: An Overworld and Nether world pair is generated with the exact same seed. Nether portals link with 1:8 coordinate scaling.
• The End: Supported on-demand. An End dimension (ftb_<id>_the_end) is only loaded if a player enters an End portal. If no one goes to the End, it is never loaded to save server resources.
• Automatic Cleanup: When the match finishes, all match dimensions (Overworld, Nether, and End) are automatically unloaded and deleted from disk.

Match Flow

How a match progresses from lobby to victory.

The 4 Match States

State	Duration	What Happens
LOBBY	Unlimited	Players wait on the lobby platform. PvP, hunger, and damage are disabled.
STARTING	10 seconds	Countdown plays on screen with sounds. Item roulette spins to pick the target block.
IN_GAME	Until win	Players scatter into fresh survival Overworld and Nether worlds. First pickup wins.
ENDING	10 seconds	Winner celebration with fireworks. Players teleport back to lobby; match worlds delete.

Player Death & Respawn

• Players keep inventory on death inside match worlds.
• Respawn sends players back to their bed or match world spawn point.

Party Matchmaking & 20s Ready Check

• Party Match Initiation: When a party leader starts a match with /start or via the Match Selector, an interactive ready-check menu opens for all party members.
• 20-Second Window: Players click [ Accept & Join ] or [ Decline ]. If a player does not respond within 20 seconds, they are considered declined.
• Automatic Start: Once all players respond (or 20s expires), racers who confirmed enter the 10-second countdown and roulette, while declining players stay safely in the lobby.

Stopping a Match

• Admins can stop an active match anytime with /ftb stop.
• All players return to the lobby immediately with cleared inventories, and temporary worlds are deleted.

Crash Reconnect

How player disconnects and mid-game joiners are handled.

60-Second Crash Grace Window

• If a player crashes or disconnects during a match, their spot, inventory, and coordinates are held for 60 seconds.
• If they reconnect within 60 seconds, they return directly to where they were in the match.
• If they do not reconnect within 60 seconds, their saved session expires and they are treated as a Late Joiner (spawning in the lobby with options to join or spectate).

Late Joiners

When a player connects while a match is already running, they receive clickable chat options:

• Join: Run /join to scatter into the match immediately (if enabled in config).
• Spectate: Run /spectate to fly around as a spectator.
• Stay in Lobby: Wait on the lobby platform until the next match starts.

20-Minute Milestone Buffs

Permanent speed and regeneration buffs to help close out long matches.

The Buffs

When a match reaches the 20-minute mark, all remaining players receive permanent potion buffs to speed up pacing until the match ends:

• Speed II: Increased movement and sprinting speed.
• Regeneration I: Steady passive health recovery.

Both buffs stay active until the match ends.

Void Lobby

The default pre-game waiting area included with FindTheBlock.

Platform Specs

• World name: ftb_lobby (created automatically if missing).
• Size: 100 × 100 bedrock platform centered around (0, 0).
• Elevation: Y = 100.
• Spawn point: X = 0.5, Y = 101.0, Z = 0.5.

Void Boundary Protection

• If a player falls or jumps off the platform, they are caught at Y = 90.
• The player is instantly teleported back to the center spawn.
• No fall damage is dealt, and no death screen is triggered.

Lobby Features & Controls

• Match Selector Compass: Given automatically in Slot 4. Right-click to browse active matches, join/spectate mid-game, or access the Party Finder.
• In-World Leaderboard: Admins can spawn floating text leaderboards with /ftb leaderboard spawn [wins|time] anywhere on the platform.
• Clean Inventories: Returning to the lobby clears survival gear so players never carry tools or ores into the lobby.

Lobby Rules

• PvP is disabled.
• Hunger does not drain.
• Weather is locked to clear daylight.
• Blocks cannot be broken or placed.

Change Lobby World

How to use your own custom spawn, hub build, or multi-world lobby instead of the auto-generated void platform.

Configuration

Open plugins/FindTheBlock/config.yml and set your world name and disable the platform under the lobby section:

lobby:
  world-name: "hub"        # Exact name of your custom world folder
  platform:
    auto-generate: false   # Disable the auto-generated bedrock platform

  # Automatic void protection
  void-teleport: true
  void-teleport-blocks-above-damage: 2.0

Setup Steps

1. Make sure your custom world folder is placed in your server directory and loaded.
2. Open config.yml and set lobby.world-name to your world's exact name.
3. Set lobby.platform.auto-generate: false so the 100x100 bedrock box is not built inside your world.
4. Join the server, go to your custom lobby world, stand where you want players to spawn, and run /setworldspawn.
5. Restart the server.

Automatic Lobby Features

When using a custom lobby world, FindTheBlock automatically manages the following protections:

• World Spawn Integration: Players joining the lobby or returning from matches spawn at the world spawn point set by /setworldspawn.
• Keep Inventory: keepInventory is automatically enforced on the lobby world. If a player dies, their items and XP are preserved with zero ground drops.
• Void Fall Protection: If players slip off your lobby build into the void, they are caught 2 blocks before void damage starts and teleported back to the world spawn with fall distance reset to zero.

Difficulty & Recipes

Configure item tiers and display in-game crafting recipes.

Difficulty Tiers

Difficulty	Target Items	Focus & Style
EASY (1 pt)	Diamond Ore, Amethyst Block, Calcite, Dripstone, Moss, Glow Lichen, Packed Ice, Magma, Dead Corals, Red Sand, Terracotta, Podzol	Surface & biome exploration, basic underground resources
NORMAL (3 pts)	Ancient Debris, Crying Obsidian, Sea Lantern, Prismarine, Shroomlight, Nylium, Resin Blocks, Sculk Sensors, Slime Block, Emerald Ore, Deepslate Diamond Ore, Sponge	Deep mining, Nether travel, ocean monuments, Trial Chamber exploration
HARD (5 pts)	Mob Heads, Heavy Core, Shulker Boxes, Netherite Block, Beacon, Ender Chest, Lodestone, Purpur Block, Chorus Flower, End Stone Bricks, Mycelium	The End exploration, boss encounters, mushroom islands, endgame crafting

Starting with a Difficulty

Pass the difficulty as an argument, or choose it visually in the in-game Mode Selection GUI:

• /start easy (Party leader ready-check)
• /start normal
• /start hard
• /ftb startall [tier] (Admin match for all lobby players)

If omitted, the default tier defined in config.yml is used.

Recipe Viewer GUI

Players can check how to craft the target item at any time:

• Run /recipe in chat.
• A 3 × 3 crafting table GUI opens displaying the exact pattern and ingredients.
• Works for all standard shaped and shapeless vanilla recipes.

Configuration Reference

Complete default configuration file located at plugins/FindTheBlock/config.yml.

Default config.yml

# =====================================================================
#             FindTheBlock Configuration
# =====================================================================

lobby:
  world-name: "lobby"
  # Automatic void world & 100x100 bedrock platform generation
  platform:
    auto-generate: true
    size: 100
    y-level: 100
    material: "BEDROCK"
  spawn:
    x: 0.5
    y: 101.0
    z: 0.5
    yaw: 0.0
    pitch: 0.0
  # Lobby Protections
  protect-blocks: true
  disable-hunger: true
  disable-pvp: true
  disable-fall-damage: true
  disable-mob-spawning: true
  disable-item-drops: true
  disable-weather: true
  daylight-fixed: true
  # Teleport players back to world spawn before taking void damage
  void-teleport: true
  # Blocks above the void damage boundary (minHeight - 64) where teleport triggers
  void-teleport-blocks-above-damage: 2.0
  # If a player slips off the platform, teleport them back to spawn at this Y level


# =====================================================================
#                 Background World Factory Pipeline
# =====================================================================
world-factory:
  # Standby warm world pairs (Overworld + Nether) kept ready in queue
  buffer-size: 1
  # Radius in chunks around spawn to pre-generate asynchronously (6 = 13x13 chunks)
  chunk-radius: 6
  # Max chunks generated per second to guarantee ZERO server tick drops
  chunks-per-second: 30
  # Maximum world border
  match-border-size: 59999968.0

# =====================================================================
#                          Match Settings
# =====================================================================
match:
  # Maximum podium winners (1st, 2nd, 3rd) scaling dynamically with player count
  max-winners: 3
  # Duration in seconds of victory celebration before returning to lobby
  celebration-seconds: 10
  # 20-minute survival reward: Speed II & Regeneration I (Infinite)
  twenty-minute-buffs: true
  # Match timeout in hours before automatic cancellation
  timeout-hours: 3

  starter-kit:
    iron-tools: true
    silk-touch-pickaxe: true

  # Mid-game connection handling
  mid-game:
    allow-late-entry: true
    allow-spectate: true
    reconnect-grace-seconds: 60

  roulette:
    roll-seconds: 3
    preview-seconds: 4

  party:
    leader-inactivity-minutes: 10

# =====================================================================
#                      Objective Difficulty Tiers
# =====================================================================
targets:
  default-tier: "NORMAL"

  EASY:
    - "DIAMOND_ORE"
    - "AMETHYST_BLOCK"
    - "CALCITE"
    - "DRIPSTONE_BLOCK"
    - "POINTED_DRIPSTONE"
    - "MOSS_BLOCK"
    - "GLOW_LICHEN"
    - "PACKED_ICE"
    - "MAGMA_BLOCK"
    - "NETHER_GOLD_ORE"
    - "NETHER_QUARTZ_ORE"
    - "DEAD_TUBE_CORAL_BLOCK"
    - "DEAD_BRAIN_CORAL_BLOCK"
    - "DEAD_BUBBLE_CORAL_BLOCK"
    - "DEAD_FIRE_CORAL_BLOCK"
    - "DEAD_HORN_CORAL_BLOCK"
    - "RED_SAND"
    - "TERRACOTTA"
    - "PODZOL"

  NORMAL:
    - "ANCIENT_DEBRIS"
    - "CRYING_OBSIDIAN"
    - "GILDED_BLACKSTONE"
    - "BLUE_ICE"
    - "SEA_LANTERN"
    - "PRISMARINE"
    - "PRISMARINE_BRICKS"
    - "DARK_PRISMARINE"
    - "TUBE_CORAL_BLOCK"
    - "BRAIN_CORAL_BLOCK"
    - "BUBBLE_CORAL_BLOCK"
    - "FIRE_CORAL_BLOCK"
    - "HORN_CORAL_BLOCK"
    - "SHROOMLIGHT"
    - "NETHER_WART_BLOCK"
    - "WARPED_WART_BLOCK"
    - "CRIMSON_NYLIUM"
    - "WARPED_NYLIUM"
    - "RESIN_BLOCK"
    - "RESIN_BRICKS"
    - "SCULK_SENSOR"
    - "CALIBRATED_SCULK_SENSOR"
    - "SCULK_SHRIEKER"
    - "SCULK_CATALYST"
    - "NETHER_BRICKS"
    - "BLACKSTONE"
    - "BASALT"
    - "POLISHED_BASALT"
    - "SLIME_BLOCK"
    - "EMERALD_ORE"
    - "DEEPSLATE_EMERALD_ORE"
    - "DEEPSLATE_DIAMOND_ORE"
    - "SPONGE"

  HARD:
    - "DRAGON_HEAD"
    - "WITHER_SKELETON_SKULL"
    - "CREEPER_HEAD"
    - "SKELETON_SKULL"
    - "ZOMBIE_HEAD"
    - "PIGLIN_HEAD"
    - "HEAVY_CORE"
    - "SHULKER_BOX"
    - "NETHERITE_BLOCK"
    - "BEACON"
    - "ENDER_CHEST"
    - "RESPAWN_ANCHOR"
    - "LODESTONE"
    - "PURPUR_BLOCK"
    - "CHORUS_FLOWER"
    - "END_STONE_BRICKS"
    - "MYCELIUM"

# =====================================================================
#                        Update Checker
# =====================================================================
update-checker:
  enabled: true
  notify-ops: true

Commands & Permissions

Command reference and permission nodes for FindTheBlock.

Admin Commands

Command	Description	Permission
/ftb startall [tier]	Starts a match for all players currently in the lobby world.	findtheblock.admin
/ftb stop / /ftb stopall	Immediately cancels all active matches and returns players to lobby.	findtheblock.admin
/ftb leaderboard spawn [wins|time]	Spawns a floating in-world text leaderboard at your location.	findtheblock.admin
/ftb leaderboard remove	Removes the nearest floating leaderboard within 10 blocks.	findtheblock.admin
/ftb reload	Reloads the configuration file and updates floating leaderboards.	findtheblock.admin

Player & Party Commands

Command	Description	Permission
/party, /p	Opens Party Management if in a party, or Party Finder if solo.	findtheblock.use
/party finder	Opens the public Party Finder GUI to discover and join parties.	findtheblock.use
/party create [public|private]	Creates a new party (public by default).	findtheblock.use
/party invite <player>	Invites a player to join your party.	findtheblock.use
/party accept / /party deny	Accepts or declines a pending party invitation.	findtheblock.use
/party leave / /party disband	Leaves or disbands your current party.	findtheblock.use
/party public / /party private	Toggles party listing visibility in the Party Finder.	findtheblock.use
/party start [tier]	Starts the 20-second ready check for your party members.	findtheblock.use
/start [tier]	Starts a 20-second party match ready check (or admin match if OP).	findtheblock.use
/join	Joins an ongoing match in progress as a late racer (if enabled).	findtheblock.use
/spectate, /spec	Enters match world as a spectator with compass player teleportation.	findtheblock.use
/leave	Leaves your active match or party and returns you to the lobby.	findtheblock.use
/recipe	Opens crafting table recipe / guide GUI for the active target block.	findtheblock.use
/menu, /selector	Opens the Match Selector and Party Hub GUI (or right-click lobby compass).	findtheblock.use
/top	Opens the interactive leaderboard menu.	findtheblock.use

Permissions Reference

• findtheblock.admin: Grants full administrative control (default op).
• findtheblock.play: Grants standard player gameplay commands (default all players).
• findtheblock.bypass: Grants bypass of void lobby block protections (default op).

PlaceholderAPI Reference

Supported placeholders for tablists, scoreboards, and holograms.

Global Match Placeholders

Placeholder	Description	Example
%findtheblock_state%	Current match state enum.	IN_GAME, LOBBY
%findtheblock_state_display%	Formatted state with color code.	In Game, Lobby
%findtheblock_target%	Name of the target block or item.	IRON_INGOT
%findtheblock_time%	Elapsed match time in MM:SS format.	04:23
%findtheblock_contestants%	Count of alive participants in the match.	8

Personal Player Stats

Placeholder	Description	Example
%findtheblock_wins%	Total number of 1st-place victories.	14
%findtheblock_played%	Total matches entered.	32
%findtheblock_best_time%	Fastest win time achieved.	01:45

Top Leaderboards (Rank 1 to 10)

Placeholder	Description
%findtheblock_top_1_name%	Username of rank #1 player.
%findtheblock_top_1_wins%	Win count of rank #1 player.
%findtheblock_top_1_time%	Fastest win time of rank #1 player.

Frequently Asked Questions

Quick answers to common questions about FindTheBlock.

Can players enter the Nether?

Yes. The Overworld and Nether are paired with the identical seed. Players can build and light nether portals to gather Nether items like Blaze Rods and Nether Bricks.

Can players enter the End?

Yes. The End dimension is loaded on-demand per match only if a player enters an End portal. If no one enters the End, it is not loaded. When the match ends, all dimensions (Overworld, Nether, and End) are deleted.

What happens if a player disconnects?

Players have a 60-second window to reconnect and resume where they left off. If they do not reconnect within 60 seconds, their spot is forfeited and they are treated as a late joiner.

Can players join an active match?

Yes. When a player logs in during an active round, they can use /join to join as a runner or /spectate to watch in spectator mode.

How do I reset all leaderboard stats?

Stop your server, delete plugins/FindTheBlock/stats.json, and start the server again.

Why are placeholders displaying raw text?

Make sure you have PlaceholderAPI installed on your Paper server and run /papi reload.