BuildBattle-OG

TrueOG Network's fork of Plugily-Projects/BuildBattle — a building competition minigame for Purpur 1.19.4, using MyWorlds for arena world management.

Current version: 5.1.5 (changelog).

Two game modes ship in the box. In classic mode players build on their own plot against a theme, then vote on each other's builds. In Guess The Build one player builds while everyone else races to guess the theme in chat for points.

OG fork notes

This fork makes no outside service calls. Upstream's update checker, remote translation fetching, error reporting and metrics are all stubbed out, so the bundled Default locale is always used and nothing phones home. It also adds /hub, /bbjoin, /bbforcestart and reconnect handling so players reliably get back to the main world from an arena, and integrates with the rest of the TrueOG plugin set (see Integrations).

Return locations are recorded whenever a player enters an arena world by any route — /bbjoin, /bb join, a portal, or /mw tp — and are kept on disk, so /hub, a relog, a respawn or a server restart all put the player back where they started rather than at main world spawn.

/v and /vote are claimed inside BuildBattle worlds before any other plugin sees them, so VotingPlugin cannot take the /vote label away from theme voting. BuildBattle has no map pool to vote on, so the command drives the theme poll the vote menu already owns rather than adding a second one.

Requirements

• Purpur 1.19.4
• MyWorlds (either the MyWorlds or the My_Worlds fork — both plugin names are accepted)
• BKCommonLib (MyWorlds' own dependency)

Optional, integrated when present: Utilities-OG, Chat-OG, GameModeInventories-OG, Spawn-OG, Citizens, PlaceholderAPI, ViaVersion.

Quick Setup

1. Drop the jar in plugins/ and start the server once to generate plugins/BuildBattle-OG/.
2. Create your arena worlds and register them with MyWorlds. Name them to the Chat-OG convention — BB1-map for the game world and BB1-hub for its lobby (see World naming).
3. Add your main overworld/nether/end to MyWorlds.Protected-Worlds in config.yml so arenas can never be created there.
4. Run /bba setup create <arena> and follow the setup inventory to place the lobby, start and end locations. Use /bba setup edit <arena> to reopen it later.
5. Use /bba addplot <arena> with the location wand to mark each build plot.
6. Set /bba settheme <theme>, or leave the bundled themes.yml list in place.
7. Run /bba reload, then join with /bb join <arena>.
8. Optionally place join signs in the hub so players can join without commands (see Join Signs).

Join Signs

Admins can place physical signs that players right-click to join an arena. Signs render the four lines from Signs.Lines in language.yml (title, arena name, game state, player counts) and update automatically. With Sign-Block-States: true in config.yml, the block behind the sign also changes color with the game state (white waiting, yellow starting, orange in game, gray ending, black restarting).

To set one up:

1. Make sure the arena exists (/bba setup create <arena>, see Quick Setup above).
2. Place a sign in a persistent world such as the server hub — not in the BB<n>-map/BB<n>-hub worlds, which are recreated between games.
3. Write [buildbattle] on the first line and the arena id (e.g. BB1) on the second line. Requires the buildbattle.admin.sign.create permission.
4. The sign reformats immediately; right-clicking it joins that arena.

Sign locations are saved under the arena's signs: list in arenas.yml. Breaking a registered sign requires buildbattle.admin.sign.break and removes it from the arena.

World naming

Arena worlds must be named BB<n>-<map> and their lobby worlds BB<n>-hub, for example BB1-map and BB1-hub. Chat-OG resolves a world to a multi-world game by that <letters><digits>- prefix and keys its per-game Discord channel off it, so the BB prefix must also exist under discord.games in Chat-OG's config.yml. Worlds named any other way simply stay in global chat — everything else still works.

Arena ids follow the same convention, so the arena that owns BB1-hub and BB1-map is named BB1. /bbjoin accepts the id case-insensitively and also accepts the bare number, so /bbjoin BB1, /bbjoin bb1 and /bbjoin 1 are the same command. A bare number that matches more than one arena is refused rather than guessed.

Upgrading from 5.1.4 or earlier: the bundled arenas.yml template changed from bb_lobby / bb_game_1 to BB1-hub / BB1-map, and its arena id from default to BB1. Existing arenas keep whatever names they already have; changing the template does not migrate them. To adopt the convention: stop the server, rename the world folders, then update the arena id, the three location lines and world: in arenas.yml along with your MyWorlds worlds.yml and inventories.yml entries. Until the worlds are renamed, /bbjoin <number> cannot resolve the arena and no chat formatter is registered.

Configuration

config.yml holds the fork-specific MyWorlds block:

MyWorlds:
  # BuildBattle requires My_Worlds and will enable these MyWorlds settings on startup.
  Enable-World-Inventories: true
  Enable-World-Chat: true
  # BuildBattle arenas, plots and lobby locations are blocked from these worlds.
  Protected-Worlds:
    - world
    - world_nether
    - world_the_end
  # Days to keep a player's pre-arena return location on disk (0 = keep forever).
  PreJoin-Location-Expiry-Days: 30

Arenas live in arenas.yml:

instances:
  BB1:
    lobbylocation: BB1-hub,-1.0,80.0,7.0,0.0,0.0
    startlocation: BB1-map,-1.0,80.0,7.0,0.0,0.0
    endlocation: BB1-hub,-1.0,80.0,7.0,0.0,0.0
    minimumplayers: 2
    maximumplayers: 10
    plotmembersize: 1
    mapname: mapname
    world: BB1-map
    # classic (deprecated: solo), guess_the_build
    gametype: classic
    isdone: false
    signs: {}
    plots: {}

Themes are in themes.yml, messages in language.yml, and per-player statistics use mysql.yml when Database.Enabled is on.

Placeholders

Registered through Utilities-OG as MiniPlaceholders, resolved for the viewing player, and updated the moment a game's points are awarded:

Placeholder	Value
<bb_score>	The player's POINTS_TOTAL
<bb_rank>	Colored rank name for that score: Apprentice (0), Builder (100), Bricklayer (300), Carpenter (750), Mason (1,500), Craftsman (3,000), Architect (6,000), Engineer (10,000), Sculptor (15,000), Master Builder (25,000), Forger (40,000), Dreamer (60,000), Extractor (100,000), Dom (150,000); Dreamweaver for the top player once they also reach Dom

Integrations

Plugin	Effect when installed
MyWorlds / My_Worlds	Required. Arena world management, per-world inventories and chat.
Utilities-OG	Registers the <bb_score> and <bb_rank> placeholders. language.yml values containing a MiniMessage tag or the &* rainbow code render through TrueOG's colorizer, enabling <#rrggbb> hex, <gradient:...>, named colours and decorations. Plain &-coded values are passed through byte-for-byte, so nothing shipped changes appearance. Without the plugin, all values keep their default formatting.
Chat-OG	Arena chat is scoped per world, styled by BuildBattle-OG's own formatter, and mirrored to the game's Discord channel, provided worlds follow the naming convention and discord.games.BB exists in Chat-OG's config. The formatter shows the player count in the lobby, VOTE and JUDGING during the voting phases, and the theme while building — never in Guess The Build, where the theme is the answer.
GameModeInventories-OG	Builders get a creative exemption scoped to arena worlds at runtime. Do not grant regular players gamemodeinventories.toggle or gamemodeinventories.anywhere, and keep arena worlds out of restrict_adventure_worlds — guessers are put in adventure mode.
Spawn-OG	Keep arena worlds out of its login-safety.worlds list so reconnect handling stays with BuildBattle-OG.
Citizens	Enables /bba addnpc for plot NPCs.
PlaceholderAPI	Exposes arena placeholders to other plugins.

Commands

/bb (aliases buildbattle, buildb) and /bba (aliases buildbattleadmin, buildbadmin) each print their own help listing. The tables below cover the arguments this fork defines plus the most-used ones inherited from MiniGamesBox.

Player Commands

Command	Permission	Description
/bbjoin [lobby]	—	Join a lobby by id (BB1, or just 1); no argument lists the open lobbies
/bb join <arena>	—	Join an arena
/bb randomjoin	—	Join any arena with room
/vote [#] or /v [#]	—	List the themes up for voting and cast a vote
/bb leave	—	Leave the current arena
/bb arenas	buildbattle.arenas	Open the arena selector
/bb menu	—	Open the plot options menu
/bb guess <word>	—	Submit a Guess The Build guess
/bb selectplot	buildbattle.command.selectplot	Select the plot you are standing in
/bb stats	—	Show your statistics
/bb top [statistic]	—	Show the leaderboard
/hub	—	Leave the arena or lobby and return to the main world

Admin Commands

Command	Permission	Description
/bba setup create <arena>	buildbattle.admin.setup	Create a new arena
/bba setup edit <arena>	buildbattle.admin.setup	Open the arena setup inventory
/bba delete <arena>	buildbattle.admin.delete	Delete an arena
/bba list	buildbattle.admin.list	List arenas and their states
/bba reload	buildbattle.admin.reload	Reload configuration
/bba stop	buildbattle.admin.stop	Stop the running game
/bbforcestart [time]	buildbattle.admin.forcestart	Start the game ignoring minimumplayers
/bba forcestart	buildbattle.admin.forcestart	Force the game to start
/bba forceplay <arena> <theme>	buildbattle.admin.forceplay	Force an arena to play a theme
/bba settheme <theme>	buildbattle.admin.settheme	Set the current arena's theme
/bba theme [add/remove] [gameType] [theme]	buildbattle.admin.theme	Manage the theme list
/bba addplot <arena>	buildbattle.admin.addplot	Add a build plot using the location wand
/bba removeplot <arena> <plot ID>	buildbattle.admin.removeplot	Remove a build plot
/bba addnpc	buildbattle.admin.addnpc	Place a plot NPC (requires Citizens)
/bba locwand	buildbattle.admin.locwand	Get the plot selection wand
/bba tp <arena/worldName> [location type]	buildbattle.admin.teleport	Teleport to an arena location
/bba spychat	buildbattle.admin.spychat	Toggle arena chat spying
/bba statistic <adjust/set> <statistic> <amount> [player]	buildbattle.admin.statistic	Adjust a player's statistic (buildbattle.admin.statistic.others for [player])

Permissions

Administration

buildbattle.admin.* (default OP) grants every node in the Admin Commands table above, plus:

Permission	Default	Description
buildbattle.admin	OP	Base administrative access
buildbattle.admin.sign.create	OP	Create BuildBattle join signs
buildbattle.admin.sign.break	OP	Break BuildBattle join signs
buildbattle.admin.statistic.others	OP	Adjust another player's statistics
buildbattle.admin.locale / .locales	OP	Inspect and switch locales
buildbattle.admin.kitfile	OP	Manage kit files
buildbattle.admin.placeholders	OP	Check placeholder resolution
buildbattle.admin.leaderboard.manage	OP	Manage leaderboard holograms
buildbattle.command.override	OP	Bypass in-game command blocking (Block.In-Game.Commands)
buildbattle.updatenotify	OP	Update notifications (inert in this fork)

Gameplay

Permission	Default	Description
buildbattle.command.selectplot	OP	Select the plot you are standing in
buildbattle.particles	OP	Use the particle menu
buildbattle.heads	OP	Use the player-heads menu (set per entry in heads/mainmenu.yml)
buildbattle.arenas	OP	Open the arena selector
buildbattle.fullgames	OP	Join arenas that are already full
buildbattle.join.<arena>	OP	Join a specific arena, when per-arena join permissions are enabled

Point, voting and experience multipliers are configured by permission node in permissions.yml. Biome menu entries use biomes.VIP by default, configurable in biomes.yml.

Building

git clone --recursive https://github.com/true-og/BuildBattle-OG
cd BuildBattle-OG
./gradlew build

If you cloned without --recursive, run ./bootstrap.sh first. The shaded plugin jar lands in build/libs/BuildBattle-OG-<version>.jar.

Credits

BuildBattle-OG is a fork of Plugily-Projects/BuildBattle by Tigerpanzer_02, Plajer, TomTheDeveloper and contributors, distributed under the GPLv3.

Open Source Libraries

Library	Author	License
InventoryFramework	stefvanschie	Unlicense
ScoreboardLib	TigerHix	LGPLv3
HikariCP	brettwooldridge	Apache License 2.0
Commons Box	Plajer	GPLv3

Attributions

Thanks to Code Whale for the Open Source POEditor license behind upstream's locales, and to Minecraft Heads for the head names and textures used in the heads menu.