Read this in Español.
Scoreboards for areas of ANY shape, not just boxes. Outline your dig zone, perimeter or build area with a line of marker blocks in the sky, run one command, and ShapeBoard tracks every block broken and placed inside that exact shape. When someone walks in, a leaderboard sidebar appears just for them. When they walk out, it goes away.
100% server-side. Players do not install anything.
Full quality video with sound: shapeboard-demo.mp4
Tools like buildevents can only track rectangular boxes. Real projects are not rectangles: perimeters have round corners, rivers you want to skip, weird bulges. If you track a box around a round perimeter, people mining outside the actual project still climb your leaderboard. ShapeBoard follows the exact outline you drew, so the count is fair.
The sidebar is also per-player for real. It is sent with targeted scoreboard packets, so only the people standing inside the shape see it. No teams are touched, no team colors are changed, and two players who happen to share a team color do not leak the board to each other. Whatever your server uses teams and colors for stays intact.
- Fabric server with Fabric API, on any Minecraft from 1.21 to 26.2.
- Drop the jar for your Minecraft version into
mods/(the table below says which one). - Restart. Done: there is no config file to edit.
Every version gets its own jar, compiled against that version. The name always ends in the Minecraft version it is for.
| Minecraft | Jar | Java |
|---|---|---|
| 1.21, 1.21.1 | shapeboard-x.y.z+1.21.jar |
21 |
| 1.21.2 | shapeboard-x.y.z+1.21.2.jar |
21 |
| 1.21.3 | shapeboard-x.y.z+1.21.3.jar |
21 |
| 1.21.4 | shapeboard-x.y.z+1.21.4.jar |
21 |
| 1.21.5 | shapeboard-x.y.z+1.21.5.jar |
21 |
| 1.21.6 | shapeboard-x.y.z+1.21.6.jar |
21 |
| 1.21.7 | shapeboard-x.y.z+1.21.7.jar |
21 |
| 1.21.8 | shapeboard-x.y.z+1.21.8.jar |
21 |
| 1.21.9 | shapeboard-x.y.z+1.21.9.jar |
21 |
| 1.21.10 | shapeboard-x.y.z+1.21.10.jar |
21 |
| 1.21.11 | shapeboard-x.y.z+1.21.11.jar |
21 |
| 26.1, 26.1.1, 26.1.2 | shapeboard-x.y.z+26.1.2.jar |
25 |
| 26.2 | shapeboard-x.y.z+26.2.jar |
25 |
Minecraft 26.1 and up need Java 25: that is the game's requirement, not the mod's. The jar for a version will refuse to load on a different one rather than half work.
Say TVTvirus is admin and wants to track his server's perimeter dig:
-
Draw the outline. Fly to a Y above the build (for example y150) and draw one continuous line of a marker block (for example black concrete) tracing the shape of the project, until it closes on itself. Any shape works: circles, blobs, donut holes, cut corners. Small gaps up to 6 blocks are bridged automatically; bigger gaps make the scan fail and it tells you the exact coordinates of the open ends so you can go patch them.
-
Create the shape. Stand anywhere within 64 blocks of the line (or pass explicit coordinates from the console) and run:
/shapeboard create bigculo minecraft:black_concrete 150ShapeBoard walks the whole line, closes the shape, and reports the area:
[ShapeBoard] Shape 'bigculo' created in 45 ms: 797,680 columns inside, outline of 4,350 blocks. Objectives: bigculo_break / bigculo_place.Just want a rectangle? Skip the drawing entirely: give it two opposite corners and the ceiling Y instead:
/shapeboard createbox spawnzone 30640 4768 31631 6079 150 -
Give it a pretty name. This is what players see on the sidebar:
/shapeboard rename bigculo Big Culo -
Pick what the leaderboard ranks by. This is the step people miss: the sidebar ranks by blocks broken unless you say otherwise. Both breaks and placements are always counted, but only one of them drives the board.
/shapeboard metric bigculo break # digs (default) /shapeboard metric bigculo place # builds and decoration /shapeboard metric bigculo both # the sumBuilding a project rather than digging one? Run the
placeline, or the board will sit at zero while everyone works.Digging a place first and building it later? Leave
metriconbreakfor the dig phase, flip it toplaceon the day the building starts. Both counters ran all along, so nothing is lost, and anyone can watch the other one at any time with/shapeboard view(see Two boards, one zone). -
That is it. From now on, everything mined or placed inside the shape and below the marker line counts into the vanilla scoreboard objectives
bigculo_breakandbigculo_place. Anyone who walks in gets:[ShapeBoard] You entered Big Culo. Blocks you mine or place here count toward the leaderboard. [ShapeBoard] Run /shapeboard hide to hide the sidebar, /shapeboard quiet to mute these messages.Those two lines are shown once, not on every crossing: the same zone stays quiet for 15 minutes afterwards, and
/shapeboard quietmutes them for good.with a live top 15 sidebar. If they are not in the top 15 but have a score, their own line is shown in the last slot so they always see where they stand.
| Command | Who | What |
|---|---|---|
/shapeboard create <id> <block> <y> [x z] |
OP | Scan the marker line and create a shape. x z optional start point (required from console) |
/shapeboard createbox <id> <x1> <z1> <x2> <z2> <y> |
OP | Rectangular zone with no drawing at all: two opposite corners + the ceiling Y (only blocks below it count) |
/shapeboard rename <id> <name...> |
OP | Set the display name shown on the sidebar |
/shapeboard metric <id> <break|place|both> |
OP | What the leaderboard ranks by: blocks broken (default), placed, or the sum. Perfect for build/decoration zones |
/shapeboard total <id> <on|off> |
OP | Show a Total line at the top of the sidebar with everyone's combined count (on by default) |
/shapeboard delete <id> |
OP | Delete the shape (scoreboard objectives are kept) |
/shapeboard list |
all | List shapes with area and marker info |
/shapeboard info <id> |
all | Details of one shape |
/shapeboard top [id] |
all | Top 10 + totals in chat |
/shapeboard hide / show |
all | Per-player sidebar toggle, remembered across sessions |
/shapeboard view <break|place|both|reset> |
all | What your sidebar ranks by, whatever the zone is set to. reset follows the zone again |
/shapeboard quiet [on|off] |
all | Mute the entered/left chat lines. The sidebar keeps working. No argument toggles it |
/shapeboard suffix <id> <word|auto|off> |
OP | Word after the display name on the sidebar title. auto turns into Dig / Build / Both, following what is being ranked |
/shapeboard prefix <id> <word|off> |
OP | Word before the display name |
/shapeboard contains <id> <x> <z> |
OP | Debug: is this column inside the shape? |
/shapeboard scan <id> |
OP | Count the blocks still standing inside the shape (see Dig progress) |
/shapeboard progress [id] |
all | Progress bar and remaining block count from the last scan |
/shapeboard layer [y] [id] |
all | One Y layer, measured against what that layer started with |
/shapeboard down <y> [id] |
all | Everything still standing from the top of the scan down to that Y: how much is left before the shape is clear to y |
/shapeboard blocks [id] |
all | Every block type still standing, best first (what you will be hauling out) |
/shapeboard range <id> <ymin> <ymax> |
OP | Y slice the scan covers (default: above the bedrock floor, up to the marker Y) |
/shapeboard baseline <id> <blocks>|fromscan |
OP | How many blocks were there before digging started. fromscan freezes the last scan, 0 = use the raw volume |
/shapeboard untracked <id> <name> |
OP | Hold the digs nobody was credited for (pre-shape digs, explosions, world edits) under a fake name, resynced after every scan. off removes it |
A zone that gets dug out first and built up later needs two leaderboards in the
same place. It already has them: breaks and placements are always counted into
two separate objectives, <id>_break and <id>_place. The metric only picks
which one the sidebar shows, so nothing has to be duplicated and there is no
second shape to create (overlapping shapes would not work anyway: a column
belongs to the first shape that contains it).
/shapeboard metric virusia break # dig phase, everyone sees the digs
/shapeboard metric virusia place # building day, one command, same zone
/shapeboard view place # any player, any time, just for them
/shapeboard view reset # back to whatever the zone shows
view is per player and remembered across sessions, so a builder can watch the
placements while the diggers keep their own board. To make it obvious which one
you are looking at, give the shape an auto suffix:
/shapeboard rename virusia Virusia
/shapeboard suffix virusia auto
The sidebar title then reads Virusia Dig, Virusia Build or Virusia
Both, following whatever that viewer is ranking by. A fixed word works too
(/shapeboard suffix virusia Build), and /shapeboard prefix puts one in front.
Break counters answer "who dug the most". They cannot answer "how much is left",
because TNT and world edits are not credited to anyone. /shapeboard scan answers
that directly: it counts the blocks still standing inside the shape.
/shapeboard scan bigculo
/shapeboard progress bigculo
— Big Culo progress —
████████░░░░░░░░░░░░ 41.74%
Progress: 280,374 / 671,744 blocks cleared, 391,370 remaining
Left to dig: deepslate 202,334, stone 115,216, tuff 15,297, diorite 12,677
A block counts as "still to dig" when it is solid, collidable and breakable. Air, water, lava, leaves, grass and other decoration, and bedrock are all skipped, so the bar reaches 100% when the hole is actually finished.
The denominator. By default it is the raw volume of the Y slice (columns x height). That is exact and needs no setup, but natural caves and the air above the terrain count as "already dug", so the bar starts above zero. For a true reading, measure how many blocks were there before you started and set it:
/shapeboard baseline bigculo 148300000
You can get that number by scanning the same area on a copy of the world from before the dig, or on a freshly generated world with the same seed.
Making the board add up. The per-player counters only see what players are credited for. Blocks dug before the shape existed, explosions and world edits are invisible to them, so the leaderboard total can sit well below what the scan measured. Point a fake name at the difference and it stops getting lost:
/shapeboard untracked bigculo Untracked
It is recalculated after every scan, so the board always adds up to the real
hole. /shapeboard untracked <id> off removes it.
Digging to a target Y. Layer by layer is /shapeboard layer, and everything
above a target depth at once is /shapeboard down. It adds up every block still
standing from the top of the scan down to that Y, which is the question crews
actually ask ("how much before we are clear to y-20?"):
/shapeboard down -20 bigculo
— Big Culo · down to y-20 —
███████░░░░░░░░░░░░░ 38.60%
Down to y-20: 210,455 / 545,180 blocks cleared, 334,725 remaining
Layers: 43 of 96 cleared from y99 down to y-20, highest one left is y41.
Both read from the last scan, so they answer instantly and cost nothing.
Cost. The scan runs on a worker thread and reads chunk data straight from
storage, so the server keeps ticking. A 4,096 column zone takes ~50 ms; a
800,000 column perimeter takes a few seconds. It saves the world first, so
freshly dug chunks are always included. Run it from a cron job (hourly or daily)
and /shapeboard progress answers instantly from the stored snapshot.
- Scan: starting from a seed block, ShapeBoard walks the connected line of marker blocks at that exact Y (loading only the chunks the line passes through), auto-bridges gaps up to 6 blocks, then runs a flood fill from outside. Everything the flood cannot reach is inside. A diagonal line blocks the fill correctly, so outlines with 45 degree corners are fine.
- Mask: the result is stored as z-intervals per x column in
world/shapeboard/shapes.json. A lookup is a couple of integer comparisons, so tracking costs nothing even with dozens of players digging. - Counting: block breaks are counted through Fabric's break event, block placements through a tiny mixin. Only columns inside the shape and below the marker Y count. Scores go to plain vanilla scoreboard objectives, so everything else on your server (commands, datapacks, other mods) can read them.
- Sidebar: each viewer gets a client-only fake objective through targeted packets (
shapeboard_view), refreshed only when the numbers change. Leaving the area removes it and restores whatever sidebar objective the server had displayed. Player names on the board keep their team colors.
Does it need anything on the client? No. Vanilla players see everything.
What about TNT? Blocks broken by explosions are not credited to anyone (the game does not attribute them to a player). Hand mining and tools count normally.
Do carpet bots count? Their breaks and placements count under the bot's own name, so a bot-heavy dig still shows who ran what. Bots never receive sidebars or chat messages.
Multiple shapes? Yes, create as many as you want. A player standing inside one sees that shape's board.
What if my outline has a hole in it? The scan fails and prints the coordinates of the open line ends. Patch them (or leave up to 6 blocks, which bridge automatically) and rerun create.
Can I track a build or decoration area that has no outline? Yes, two ways. If a rectangle is enough, /shapeboard createbox <id> <x1> <z1> <x2> <z2> <y> needs no blocks at all. For a custom shape, the marker line is only needed during the scan: draw a temporary outline with any cheap block at a Y above the build, run create, then remove the blocks; the shape keeps working forever (the mask is stored in world/shapeboard/). Either way, set /shapeboard metric <id> place so the leaderboard ranks by blocks placed instead of dug (or both for the sum).
Can I track an area that already had digging? Objectives start at zero when the shape is created. If you have previous numbers in another objective, copy them in with /scoreboard players operation.
Does the scan lag the server? It loads only the chunks the outline itself touches, once, at create time. A 4,000 block outline takes well under a second on a loaded world.
./gradlew build
The jar lands in build/libs/. Java 21+, Gradle downloads everything else. That builds for 1.21, which is the version the source tree is written against.
For every other Minecraft version:
python3 tools/multiversion.py # all of them, into build/multiversion/
python3 tools/multiversion.py 26.2 # just one
python3 tools/multiversion.py 26.2 --errors # compile only, list every error
One source tree, no branch per version: the differences between Minecraft releases are renames, and they live in a substitution table at the top of tools/multiversion.py. The 26 series also needs its own toolchain, since Minecraft stopped shipping obfuscated in 26.1 and there are no mappings to ask for any more, and that build script is derived from this one rather than kept beside it. Building the 26 jars locally needs a JDK 25 as well as the 21.
MIT