BIngo

a paper plugin where teams race to collect the items on a shared, seeded bingo card. first team to complete a line wins.

gameplay

every game runs off a single card that every team can see. a card is a square grid of cells (3x3 up to 6x6), and each cell is either a specific item or a group like "any planks". the card is rolled from a seed, so the same seed always produces the same card.

when the game starts, players are healed, cleared, spread out around spawn, and a countdown runs. on GO, you claim a cell for your team the moment you pick up, craft, or move the matching item into your inventory. a background inventory sweep every half second is the backstop, so nothing gets missed. claimed cells stay claimed (except in lockout mode, where they lock for everyone).

a live action bar shows your team's count and the current leader. an optional sidebar scoreboard and boss bar track standings for the whole lobby. when a team gets within one cell of winning, a "one away" message is broadcast.

modes

• standard - first full row, column, or diagonal
• blackout - first team to claim every cell
• lockout - a cell locks globally the instant any team claims it; first to a line of their own cells wins. competitive, no shared cells
• count - first team to a target number of cells; lines are ignored

extras

• solo - every online player becomes their own team
• spectator mode - /bingo spectate drops you out of play; your card view then shows which team holds each cell
• hardcore - dying puts you in spectator for the rest of the game
• time limit - optional; when it runs out the team with the most cells wins, a tie is a draw
• stats - wins and games played are persisted per player, with a leaderboard

how to use

1. install: drop the jar in your server's plugins/ folder and restart
2. players join teams with /bingo join <team>, or leave auto-assign on to have everyone split onto teams automatically at start. /bingo lobby opens a chest menu - click a wool to join that team, or the barrier to spectate
3. an admin runs /bingo start [mode] [size] [seed] (all optional, defaults come from the config)
4. each player is handed a bingo card item - right-click it to open the card as a chest gui. glowing means your team has that cell, a barrier means another team locked it
5. play until a team hits the win condition. /bingo stop ends a game early

commands

all under /bingo (alias /bg):

command	does
start [mode] [size] [seed]	begin a game
solo [mode] [size]	begin a game where every online player is their own team
stop	end the game
lobby	open the team-select chest ui
join <team> / leave	pick or drop a team
team <create|remove|clear>	manage runtime teams before a game
spectate	go spectator
card	open the card gui
teams	list teams and members
status	mode, size, seed, per-team cell counts
reveal	print the current card to yourself
top	win/games leaderboard
stats [player]	wins and games for a player
reroll	roll a new card before the game starts
reload	re-read the config and item pool

permissions

• bingo.admin - start, stop, reroll, reload, team management (defaults to op)
• bingo.exempt - player is skipped by auto-assign

configuration

everything lives in config.yml:

• default-mode / default-size - used by a bare /bingo start
• count-target - cells needed to win in count mode
• start-countdown - seconds before GO
• time-limit - seconds; 0 disables it
• auto-assign - round-robin every online player onto teams at start
• on-start.* - toggles for clear inventory, heal, spread, set time to day
• spread-radius - blocks from world spawn to scatter players
• hardcore - death spectates the player for the rest of the game
• scoreboard - show the live sidebar during a game
• teams - map of id: { display, color }, color is a minimessage color name
• item-pool - roughly 130 items plus 9 groups: distribution tier weights, named groups ("any of these" sets), and easy / medium / hard material lists that can reference groups with #name

card generation fills every cell by rolling a tier (weighted by distribution), then a random entry from that tier, seeded by the game seed. a cell is either an exact item or a group - holding any member of a #planks group claims "any planks".

technical details

• platform: paper 26.2 (bukkit api)
• language: kotlin, jdk 25
• package: com.mohammadfaizan.bingo
• card sizes: 3 to 6
• dependencies: none

restart persistence

a running game is written to game.yml on shutdown - card, seed, mode, per-team members and claimed cells, lockout locks, and time remaining. it resumes automatically on the next server start: tasks, boss bar, scoreboard, and card items are all recreated. the file is deleted on a clean stop, win, or draw. games still in the pre-game countdown are not saved.

claim detection

claims are event-driven - pickup, craft, and inventory-move events claim a cell immediately. a 0.5 second full-inventory scan per player runs as a backstop for anything the events miss. standings, action bar, scoreboard, and the "one away" broadcast update on each claim.