MatchboxPlugin

Matchbox Update: v0.9.5 is here!

This is a safe, behind-the-scenes update no gameplay changes, just better stability and new tools for the future!

Updating is 100% safe and recommended.

What's new in this release:

• New Matchbox API – lets other plugins connect smoothly (big step for future features!)
• New Javadocs + Public Docs – grab the JavaDocs JAR from the repo or view the live docs at https://ohacd.github.io/MatchboxPlugin/
• Better spectator chat – alive players & spectators now have separate chats
• Fixed arrow hits – decorated pots are now fully protected during games
• Improved stability – faster sessions, better error handling, and heavy testing

Full changelog in the project's repo.

Thanks for playing!

[0.9.4] - Latest Release (Ability System)

This stability release marks the end of the rapid iteration phase for the plugin. It's mostly an under-the-hood update, modularizing the project and extending the last update's Spark ability system to also fit the medic (supporting future ability additions).

There is also a new ability for the spark Delusion, which is a fake infection that stays for 30 seconds after application, that the medic can see.

Other additions mainly focus on stability and ensuring the game is fully playable with all features working as intended (The infamous buggy Steve skin override).

Lastly, there has been an update to the default config, setting the random skin toggle to false by default and setting the Steve skin toggle to true by default.

Added

• Medic Secondary Ability System: Medic now uses the same ability system as Spark
  • Healing Sight is now tracked as a secondary ability (preparing for future abilities)
  • System modeled after the Spark secondary ability system for consistency
  • Configurable via medic.secondary-ability in config.yml
  • Options: "random" (default), "healing_sight"
  • Ready for future medic abilities to be added
• Delusion Ability: New Spark secondary ability that creates fake infections
  • Spark can activate an 8-second window, then right-click a player to apply a fake infection
  • Fake infections appear identical to real infections to the medic (same particles)
  • Medic can see delusion infections using Healing Sight alongside real infections
  • Medic can cure delusion infections, wasting their cure on a non-infected player
  • Delusion infections automatically decay after 30 seconds
  • Delusion infections do not cause elimination when discussion phase starts
  • Configurable via spark.secondary-ability in config.yml
  • Options: "random" (default), "hunter_vision", "spark_swap", "delusion"

Changed

• Medic Ability System Architecture: Refactored medic abilities to match Spark's system
  • Created MedicSecondaryAbility enum for ability tracking
  • Added ability selection logic in GameManager
  • Updated InventoryManager to handle medic abilities dynamically
  • MedicSightListener now checks if ability is active before allowing use
  • System is now extensible for adding new medic abilities in the future
• Config steve skin override: Default config now comes with steve skin override as true by default
  • Random skin toggle is now set to false by default
• Debug command: Fake infected (Delusion infection) is tracked by the debug command
  • Added the fake infected param to /matchbox debug command

Fixed

• Steve Skin Override: Fixed inconsistent steve skin application
  • All players now consistently receive steve skins when enabled
  • Skins are reapplied at the start of each new round to ensure consistency
  • Fixed issue where some players would get alex or random skins instead of steve
• Invalid default seat locations: Fixed an error where default seat locations weren't loading correctly when used with the m4tchb0x map
  • Default Spawn/Seat locations are no longer linked to a world folder named world
  • Now linked to a world folder named m4tchb0x

[0.9.3] - Latest Release (It's the little quirks in life)

Added

• Spark Secondary Ability System: Spark now rolls a secondary ability each round
  • Hunter Vision or Spark Swap, alongside Swipe
  • Spark Swap occupies the Hunter Vision slot (slot 28) when selected
  • Spark Swap teleports with preloaded chunks, preserved velocity, and preserved look direction (designed to be invisible)
• Dynamic Voting Threshold System: Voting thresholds now scale dynamically based on alive player count
  • Logarithmic scaling between key points: 20 players (20%), 7 players (30%), 3 players and below (50%)
  • Works for 2-20 players with smooth threshold transitions
  • Threshold display shown during voting phase: "Threshold: X/Y" (required votes / alive players) (Dantizzle)
• Voting Penalty System: Penalty applied when voting phases end without elimination
  • Each phase without elimination reduces the threshold by ~3.33% (configurable)
  • Maximum penalty of 10% after 3 consecutive no-elimination phases
  • Penalty resets when a successful elimination occurs
• Enhanced Tie Handling: Ties are now checked against the dynamic threshold
  • If tie vote count doesn't meet threshold: no elimination occurs
  • If tie vote count meets threshold: random player from tie is eliminated
• Voting Configuration: All voting threshold values are now configurable in config.yml
  • voting.threshold.at-20-players - Threshold percentage at 20 players (default: 0.20)
  • voting.threshold.at-7-players - Threshold percentage at 7 players (default: 0.30)
  • voting.threshold.at-3-players - Threshold percentage at 3 players and below (default: 0.50)
  • voting.penalty.per-phase - Penalty percentage per phase without elimination (default: 0.0333)
  • voting.penalty.max-phases - Maximum phases that accumulate penalty (default: 3)
  • voting.penalty.max-reduction - Maximum penalty reduction percentage (default: 0.10)
• Spark Ability Configuration: Spark secondary ability selection is now configurable
  • spark.secondary-ability - Choose Spark ability: "random" (default), "hunter_vision", or "spark_swap"
  • When set to "random", ability is randomly selected each round (default behavior)
  • When set to a specific ability, that ability is always used

Changed

• Ability System Routing: Ability system routing remains unified; Spark inventories are rebuilt each swipe phase with the chosen secondary
• Voting Phase Display: Actionbar now shows both countdown timer and threshold requirement
  • Format: "Voting: Xs | Threshold: Y/Z" (timer and required votes / alive players)
  • Updates every second alongside the countdown timer
• Voting Phase Instructions: Improved voting phase start messages
  • Removed counter-intuitive "right-click player while holding paper" instruction
  • Added information that players can choose to not vote
  • Added threshold requirement display in title subtitle
  • Added explanation that no elimination occurs if threshold isn't met
• Phase Visuals: Skins are no longer reset to original during discussion/voting, and nametags remain hidden in those phases
  • Players keep their assigned game skins across phases until swipe starts again
  • Nametags stay hidden during discussion and voting (revealed only on elimination)
• Vote Resolution: Voting now requires meeting the dynamic threshold instead of simple majority
  • Players see clear feedback when threshold isn't met
  • System tracks consecutive no-elimination phases for penalty calculation

Fixed

• Steve skin override: cosmetics.use-steve-skins now correctly applies Steve skins to players (Dantizzle)

[0.9.2] - Latest Release (It's all about the base)

This is a small patch that focuses on cleanup/QOL features and insuring everything works as intended. Due to how Skins are currently handled, the steve skin override falls back to using Alex/Steve skins depending on the player model, this will hopefully be handled better next update.

Added

• Cleaner version handling/project status handling: Project status and versioning are now handled dynamically
  • The player will get notified if a newer version is available for the plugin
  • Under the hood cleanup for dynamic project status display and project versioning/version checking
• Pre-discussion elimination notice: Eliminations are now announced as titles 10 seconds before teleporting to discussion
  • Uses the MessageUtils title pipeline, matching other UI
  • Applies blindness and heavy slowness during the 10s hold, cleared on teleport
  • Works alongside seat teleports and discussion timers
• Nickname support: Voting papers, elimination titles, and hologram reveals now use display names with UUID-backed targeting to remain compatible with nick plugins (Dantizzle)
• Debug force start: /matchbox debugstart <session> lets admins start a game with fewer than the configured minimum players (still enforces spawn/seat validity)

Fixed

• Steve skin override: cosmetics.use-steve-skins now reapplies Steve skins for gameplay while restoring players’ original skins during discussion (no more partial overrides), currently falls back to Alex skin; will be fixed in the next update (Dantizzle)
• Location listing clarity: /matchbox listspawns and /matchbox listseatspawns now display all configured entries and mark any with missing/not-loaded worlds instead of reporting none exist

[0.9.1] - Latest Release (Config and QOL update)

Added

• Config File Support: Full configuration system with config.yml
  • Configurable phase durations (swipe, discussion, voting)
  • Configurable player limits (min/max players per session)
  • Configurable seat spawn numbers for discussion phase
  • Random skins toggle (enable/disable)
• Seat Location System: Discussion phase seat spawns
  • Set seat locations via /matchbox setseat <number> command (saves to config)
  • List seat locations via /matchbox listseatspawns command
  • Remove set seat locations via /matchbox removeseat <number> command
  • Configure seat coordinates in config file
  • Players automatically teleported to seats during discussion
• Spawn Location Configuration: Game spawn locations in config
  • Set spawn locations via /matchbox setspawn command (saves to config)
  • List spawn locations via /matchbox listspawns
  • Remove set spawn locations via /matchbox removespawn <index>
  • Configure spawn coordinates in config file
  • Automatic loading from config when sessions don't have locations
• Skin Restoration System: Enhanced skin management
  • Player skins return to normal during discussion phase
  • Assigned skins restored after discussion ends
• Damage Protection: Players are invulnerable during active games
  • All damage sources blocked (hits, lava, fall damage, etc.)
  • Arrows hit players (for nametag revelation) but deal no damage
  • Death prevention during games
  • Hunger loss prevention
• Block Interaction Protection: Block interactions disabled during games
  • Right-click and left-click on blocks blocked
  • Item interactions still work (abilities, voting)
• Config Validation: Added bound checks to all config values
  • Phase durations: Swipe (30-600s), Discussion (5-300s), Voting (5-120s)
  • Player limits: Min (2-7), Max (2-20) with cross-validation
  • Min spawn locations: (1-50)
• Clear Commands: Added commands to clear all spawn/seat locations with confirmation
  • /matchbox clearspawns - Clear all spawn locations (requires confirmation)
  • /matchbox clearseats - Clear all seat locations (requires confirmation)
  • Both commands require typing the command again with confirm to execute
• Config Usage Notification: Players are notified when a game starts using config defaults
  • Shows how many spawn and seat locations were loaded from config
  • Helps players understand when config is being used vs session-specific settings
• Default Configuration: Plugin ships with complete default config for M4tchbox map
  • 11 pre-configured spawn locations
  • 8 pre-configured seat locations
  • Optimized phase durations and player limits
  • Ready to play immediately without setup
• Welcome Message System: Players receive a welcome message when joining the server
  • Title animation welcoming players to Matchbox
  • Information about the game, current version, and status
  • Discord link for bug reports and suggestions (https://discord.gg/BTDP3APfq8)
• Steve Skins Option: Config option to use default Steve skins for all players
  • cosmetics.use-steve-skins in config.yml
  • When enabled, all players get Steve skin regardless of random-skins-enabled setting
  • Works alongside existing random skins system
• Gamemode Management: Players automatically set to Adventure mode during games
  • Players set to Adventure mode when game starts
  • Original gamemode restored when game ends
  • Prevents block breaking and other survival interactions during gameplay
• Session Creation Broadcast: Upon new session creation via /matchbox start <name>, a broadcast message is sent to all players
  • Informs players about the new session and how to join
  • Encourages player participation and awareness of new games

Changed

• Location Management: Locations can be set via commands or config file
  • Commands automatically save to config (config-first approach)
  • Config locations used as defaults for new sessions
  • Session-specific locations can still be set via setdiscussion command
• setspawn Command: No longer requires session name - saves directly to config
  • Usage: /matchbox setspawn (was: /matchbox setspawn <session>)
• setseat Command: No longer requires session name - saves directly to config
  • Usage: /matchbox setseat <number> (was: /matchbox setseat <session> <number>)
• Phase Durations: All phase durations configurable via config file
  • Default: Swipe (180s), Discussion (30s), Voting (15s)
• Player Limits: Min/max players configurable via config file
  • Default: Min 2, Max 7 players

Fixed

• Spawn Location Loading: Fixed issue where config spawn locations weren't checked before requiring manual spawn setup
  • Config spawns are now loaded first before checking if spawns are sufficient
  • Players are notified when starting from config defaults
• Arrow Damage: Fixed arrows passing through players due to invincibility
  • Arrows now properly hit players (for nametag revelation) but deal no damage
  • Other damage sources remain blocked during active games
• Skin Manager: Improved offline mode compatibility
  • Better error handling for players without valid skin data
  • Graceful fallback when skin properties are missing
• Spawn Distribution: Ensured all config spawn locations are properly loaded and used
  • Fixed issue where only 1 spawn location was used even when multiple were in config
  • Fixed players spawning at same position when multiple players share one spawn location
• Session system cleanup and state management
• Deprecated method usage in leave command
• Discussion/seat location teleportation logic
• Player state restoration on game end
• All commands have been added to tab with proper permission checks
• Flower Pot Duplication Bug: Fixed exploit where players could duplicate flowers from flower pots
  • All flower pot interactions (right-click) are now blocked during active games
  • Prevents players from extracting and stacking flowers from flower pots