Matchbox - Minecraft Social Deduction Game

A social deduction game for Minecraft (2-20 players) with recording-proof mechanics.

Installation

1. Download Matchbox.jar and ProtocolLib-5.4.0.jar and place them in your server's plugins/ folder
2. Downlod the Map from https://www.planetminecraft.com/project/m4tchb0x-maps/ and place it in your server folder
3. Restart your server
4. The plugin comes with a default configuration pre-configured for the M4tchbox map
   • All spawn locations and seat positions are already set up
   • You can start playing immediately or customize locations as needed

Requirements: Paper 1.21.10, Java 21+, 2-20 players per game

Commands

Player Commands

• /matchbox join <session> - Join a game session
• /matchbox leave - Leave your current session
• /matchbox list - List all active sessions

Aliases: /mb or /mbox

Admin Commands

• /matchbox start <session> - Create a new game session
• /matchbox setspawn - Add a spawn location to config
• /matchbox setseat <number> - Set a seat location to config
• /matchbox setdiscussion <session> - Set discussion area location (session-specific)
• /matchbox listspawns - List all spawn locations in config
• /matchbox listseatspawns - List all seat locations in config
• /matchbox removespawn <index> - Remove a spawn location from config
• /matchbox removeseat <number> - Remove a seat location from config
• /matchbox clearspawns - Clear all spawn locations (requires confirmation)
• /matchbox clearseats - Clear all seat locations (requires confirmation)
• /matchbox begin <session> - Start the game
• /matchbox debugstart <session> - Force-start a game with debug override (allows starting with fewer than the configured minimum players; still enforces spawn/seat validity)
• /matchbox stop <session> - Stop and remove a session
• /matchbox skip - Skip current phase
• /matchbox debug - Show debug info

Configuration

All settings in plugins/Matchbox/config.yml (auto-created on first run).

Default Configuration

The plugin ships with a complete default configuration for the M4tchbox map:

• 11 pre-configured spawn locations
• 8 pre-configured seat locations for discussion phase
• Optimized phase durations (Swipe: 180s, Discussion: 30s, Voting: 15s)
• Player limits set (Min: 2, Max: 7, supports up to 20 players)
• Random skins enabled by default

You can start playing immediately without any setup! The default config works out-of-the-box with the M4tchbox map.

Customizing Locations

In-Game (Recommended)

• Stand at location → /matchbox setspawn
• Stand at seat → /matchbox setseat <number>
• Locations automatically saved to config and persist across sessions
• Use /matchbox listspawns or /matchbox listseatspawns to view configured locations
  • These commands also flag entries whose worlds are missing or not loaded so you can fix them quickly
• Use /matchbox clearspawns or /matchbox clearseats to reset (requires confirmation)

Config File

session:
  spawn-locations:
    - world: world
      x: 0.5
      y: 64.0
      z: 0.5

discussion:
  seat-locations:
    1:
      world: world
      x: 10.5
      y: 64.0
      z: 10.5

Configurable Settings

• Phase durations (swipe, discussion, voting)
• Player limits (min/max)
• Seat spawn numbers
• Random skins toggle (cosmetics.random-skins-enabled)
• Steve skins option (cosmetics.use-steve-skins) - Use default Steve skin for all players
• Spark Ability Selection:
  • spark.secondary-ability - Choose Spark secondary ability: "random" (default), "hunter_vision", "spark_swap", or "delusion"
  • "random" - Randomly selects ability each round (default behavior)
  • "hunter_vision" - Always uses Hunter Vision ability
  • "spark_swap" - Always uses Spark Swap ability
  • "delusion" - Always uses Delusion ability
• Dynamic Voting Thresholds:
  • voting.threshold.at-20-players - Threshold at 20 players (default: 0.20 = 20%)
  • voting.threshold.at-7-players - Threshold at 7 players (default: 0.30 = 30%)
  • voting.threshold.at-3-players - Threshold at 3 players and below (default: 0.50 = 50%)
• Voting Penalty System:
  • voting.penalty.per-phase - Penalty per phase without elimination (default: 0.0333 = ~3.33%)
  • voting.penalty.max-phases - Max phases that accumulate penalty (default: 3)
  • voting.penalty.max-reduction - Maximum penalty reduction (default: 0.10 = 10%)

How to Play

Game Phases

1. Swipe Phase (3 min)

• Explore and interact
• Spark: Infect players
• Medic: Cure infected players
• Use abilities (Hunter Vision, Healing Sight)
• Chat appears as holograms

2. Discussion Phase (30s)

• Teleported to discussion seats
• Infected players die (if not cured)
• Discuss and share observations
• Game skins stay applied; nametags remain hidden

3. Voting Phase (15s)

• Right-click or left-click voting papers in your inventory to vote
• You can choose to not vote (abstain)
• Dynamic threshold system: Required votes scale based on alive player count
  • Threshold shown in actionbar: "Threshold: X/Y" (required votes / alive players)
  • Threshold shown in title subtitle at phase start
  • Threshold ranges from 20% (20 players) to 50% (3 players and below)
  • Penalty system: Threshold decreases if voting phases end without elimination
• Votes must meet threshold for elimination
• If threshold isn't met, no elimination occurs
• Ties are resolved by checking if tie vote count meets threshold
• Game continues to next round

Roles

Spark (Impostor)

• Eliminate all players without being caught
• Infect one player per round
• Each round, you roll one secondary ability:
  • Hunter Vision: See all players with particles for 15 seconds
  • Spark Swap: Invisible teleport swap with a random player (preserves velocity and look direction)
  • Delusion: Apply a fake infection to a player that medic can see but doesn't cause elimination (decays after 1 minute)

Medic

• Identify Spark and save infected players
• Cure one infected player per round
• Use Healing Sight once per round

Innocent

• Survive and identify the Spark
• Work together to vote out suspicious players

Features

• Parallel sessions (multiple games simultaneously)
• Recording-proof design (identical inventories/abilities)
• Full configuration support
• Automatic location loading from config
• Damage protection during games
• Block interaction protection during games
• Skin system with phase-based restoration
• Nickname-friendly UI (titles, voting papers, holograms use player display names)
• Welcome message system for new players
• Dynamic voting system with logarithmic threshold scaling and penalty mechanics

Support & Bug Reports

Found a bug or have suggestions? Join our Discord server: https://discord.gg/BTDP3APfq8

Players will also see a welcome message when joining the server with information about the plugin and Discord link.

Version: 0.9.4
Minecraft API: 1.21.10
License: MIT
Developer: OhACD