Statistic-Books-MC

A Datapack that tracks all statistics in scores and allows to display highscores in books.

Development of this datapack happens in this github repository. You can find versions earlier than 1.4 (for MC 1.20) on there.

Run /trigger sb.help to get a setting-sensitive in-game overview of how it works for players. Admins/OPs and more informed players should read on.

Table of contents

• What it does
  • Limitations
  • How to get a book
    • How to know the scoreboard name
  • Secret Mode
• Settings
  • autoOptIn
  • allowSecret
  • refreshType
• Other modifications
  • Text
  • Combining Scoreboards
  • Administrative work

What it does

This datapack allows you to track any and all statistics or other scoreboard objectives in a book in a lectern. It sorts it by highest and thus shows whoever has the best score.

NOTE: All statistics are tracked through scoreboards. Because of this they cannot start tracking before they are created. So remember to create your scoreboards early. This pack comes with a built-in function that sets up all possible objectives for you, see How to know the scoreboard name.

Limitations

Because under the hood it has to use scoreboard objectives, and scoreboard objectives only start tracking numbers when they are created and don't retroactively include the already happened things, the pack only starts tracking the statistics from the point they is added, not the point of world creation. It is thus recommended to add the pack and its scoreboards at world creation or immediately afterwards.
If you want to add it later to a world, you can use my stats to scoreboards tool to bring the new scoreboard objectives up to sync with your existing stats.

Because the way scoreboards work, only online players can be queried for their scores. To be able to also include offline players, this pack caches all players tracked scores every 5 minutes. This has various implications:

• Scores aren't updated live, but at max every 5 minutes.
• Players who aren't online for at least 5 minutes might not have their scores recorded.
• Only players who were online (for 5+ minutes) after a books creation can be included in the book.

Only books placed in lecterns will be updated!

How to get a book

To get a book that works in the system, you take a writable book, put the name of the objective you want to track as the only text in the book on the first page (no spaces or newlines), sign the book and name it "MCStats". The book gets converted automatically when first put into a lectern. You know it worked when the books content is replaced by the statistics (or empty at first, it takes up to 5 minutes to fill).

For the book to actually receive updates about the tracked statistics, it needs to be placed inside a lectern and, depending on the settings, be loaded when a refresh occurs.

How to know the scoreboard name

You can track any scoreboard objective, not just the built-in ones but ones you create yourself as well. The pack comes with a function that creates all statistic type scoreboards the game has to offer - just shy of 8000 of them. If you want to add that, run /function sb:setup_objectives right after loading the datapack!

To find out what statistics are available, consult the wiki: https://minecraft.wiki/w/Statistics

Resource locations in the game are named in the form A.B:C.D. Since A and C are both always minecraft for vanilla things, I chose to omit them and only include the other two. The convention for named objectives of this datapack is sb.<B>.<D>.

Here are some examples:

Vanilla	Statistics Book Datapack
minecraft.custom:minecraft.walk_one_cm	sb.custom.walk_one_cm
minecraft.mined:minecraft.stone	sb.mined.stone
minecraft.killed:minecraft.zombie	sb.killed.zombie

Secret Mode

If enabled in the settings, players can enable secret mode for any book inside a lectern by standing on the lectern and running /trigger sb.secret. This will cycle through the different modes:

Default: Everything is shown.
Secret Names: Names are hidden, scores are visible.
Secret Scores: Names are visible, scores are hidden.

Settings

There are various settings you can use to adjust the datapacks behavior to your liking. All of these are stored in the sb.settings objective and can only be changed by an OP of lvl 2 or above through a scoreboard command.

/scoreboard players set <settingName> sb.settings <value>

You can show all current settings by setting the sidebar to display sb.settings.

/scoreboard objectives setdisplay sidebar sb.settings

To hide them again, run the same command without the sb.settings at the end.

autoOptIn

Default: 1
If autoOptIn is set to 1, everyone is automatically included in the statistics collection and they cannot opt-out. If set to 0, players need to run /trigger sb.optin to be included in the statistics collection.
If a player that was previously opted in chooses to opt-out, their scores are removed from the storage and will be removed from the books in the next update.

Note: If you switch this value from 1 to 0, all collected values will stay included (but won't get updated anymore) unless a player specifically opts out again.

allowSecret

Default: 1
When set to 1 it allows players to use /trigger sb.secret to toggle a books "secretive" mode (see above).
Setting it to 2 keeps the secrecy status active, but the stati can only be changed by admins using /function sb:admin/secret.

Setting it to 0 does disable secrets, but books remember their status, so if it's re-enabled the books will turn secretive again.

refreshType

Default: 0
Refreshing books can be a resource intensive task, depending on the amount of players a server has, how many books need to be updated and more. These options allow you to finetune when and how books are supposed to be updated.

Value	Type	Description
0	Upon Opening	(Default) Updates a book every time someone interacts with the lectern the book is placed on. Probably best option for most servers. Not recommended if you have more than 30+ players that show up in the statistics.
1	Single Trigger	Updates the book inside the lectern the player is standing on when running /trigger sb.update.
2	Area Trigger	Updates all books in lecterns in a 16 block radius around the player running /trigger sb.update.
3	Global Timer	Will automatically refresh all loaded lecterns every 5 minutes (together with the statistics storage update).
4	Admin Only	Only updates when an admin / moderator runs the respective commands as described below.

• /function sb:admin/one: Updates the book inside the lectern the player is standing on.
• /function sb:admin/area: Updates all books in lecterns in a 16 block radius around the player.
• /function sb:admin/all Updates all loaded lecterns.

Other modifications

Text

The pack uses translation text for all its texts, including the title and the lore of the books. So if you want to adjust that, you can create a language file in a resourcepack that include whatever texts you want to override and it should use those texts instead. List of included texts:

Identifier	Text
sb.update.success	Lectern(s) updated.
sb.update.fail	No lectern found.
sb.book.title	Statistics Book
sb.book.lore.1	Automatically lists everyones statistic.
sb.book.lore.2	Needs to be placed in lectern.
sb.book.lore.3	Tracked statistic:
sb.opt_in	You have chosen to be included in the statistics.
sb.opt_out	You have chosen not to be included in the statistics. Your scores will be removed the next time the books are updated.
sb.secret.default	Secret Mode: No secrets.
sb.secret.names	Secret Mode: Names hidden.
sb.secret.scores	Secret Mode: Scores hidden.

Combining Scoreboards

Sometimes you want to have a scoreboard that isn't easily tracked by the default stats, because it's a combination of two or more different scores / stats.
Starting in v1.5.1 you can register a function to the sb:run_before function tag that is run as @a before the player scores are stored in the storage.
This lets you easily add combined scoreboards that are tallied up just-in-time instead of needing to combine them constantly.

You can use this Scoreboard Combiner Utility to create such combined scoreboards easily.

Administrative work

If you want / need to get into the nitty gritty of the administrative side (removing tracked statistics, removing players, etc), it's probably easiest to contact me directly at contact@plagiatus.net or use my contact form on my website.