Minecraft Utilities V2.1.1

---

Known Issues

I need to take a look at how Havenstone will work across dimensions. For now, please do not use your Havenstone when in the Nether or End. The issue here isn't whether or not it can work - it perfectly well can - but that I didn't take dimension into consideration before now. I need to include dimension in the module (dimension is already tracked). But I'm also not sure I want Havenstones to work across dimensions.

---

INDEX

1) Front Matter - changelog, scope discussion, usage rights, contact information and credits.
2) Manual - a breakdown of the various modules included in this datapack.
3) Technical - technical information explaining how this datapack is built, and why certain decisions were made (or not made).
4) How-To - a description of how to create your own module.
5) Future - a discussion on what my future plans are.


FRONT MATTER

Changes
2.1.1: 7/7/2019
1) Added chunk and region tracking. Scores are now kept that indicate what chunk and region each player is in.
2) Corrected the updater function name.
3) Updated the newest updater to 2_1_1.
4) Added a new datapack command "update_pack" which will run the appropriate update file.
5) Fixed Orienteer overriding Soulsand Grimoire channeling.
6) Added a toggle for players to turn Insomnia on/off for themselves. Use "/trigger toggle_insomnia" to change this.
7) Added a new admin tool to allow for easier setup of the real-time clock. To use it be in creative mode and type "/trigger set_rt_clock"
8) Added a new admin trigger "/trigger update_pack". This will only be available after running "function mcutilities:commands/update_pack".

2.1.0: 6/12/2019 - Orienteer
1) Added Orienteer, a clock/compass module based on the works by Mouleagauffre. You can check out his work here: www.planetminecraft.com/member/mouleagauffre/submissions


Scope
Minecraft Utilities (MCU) aims to add tools that would be common to many datapacks, where each individual would otherwise have to rewrite those tools on their own and ensure they are compatible with other datapacks. MCU will add many basic (and some not-so-basic) tools and functions starting with the MCU Core module.

To assist in achieving the above, this datapack will also utilize what is internally called the Control Queue. This will help separate out commands that don't need to be run every tick, reducing load on the system.

This datapack will also come with additional modules that can be activated and deactivated as desired. Ideally these modules will be generic enough so that they can be built upon by other developers.

Usage
This datapack is free to use and modify.

Contact
Please contact me at vultaz86@gmail.com for bug submissions and suggestions.

Credits
Daniel Scutt (Vultaz)
Mouleagauffre - Orienteer Module - based on works found here: www.planetminecraft.com/member/mouleagauffre/submissions
Recipes created using TheDestruc7i0n's crafting generator: crafting.thedestruc7i0n.ca
Many commands and items used in this datapack are generated using MCStacker: mcstacker.net


MANUAL

Core
The Core module is required to run all other MCU modules. The Core module adds basic methods as follow:
1) Player session tracking: includes user ID, current coordinates, current dimension, etc.
2) System data tracking: includes number of online players and in-game time of day.
3) PRNG calculator.
4) A real-world clock. This is based on game ticks and may actually run slower than real time. I will try to address slower game-ticks in the future.

Additional methods may be added at a later date.

Soulsand Sorcerer
This module adds the Soulsand Grimoire. This book allows players to easily obtain certain special items such as a new Havenstone. These items can normally be obtained with /trigger, but this book allows easy access to learning about and obtaining these items (and it's more fun). Additionally, this book is required to use these items' features. Additional uses will likely be added in the future.

Run /trigger ssg_give to obtain a copy of this book.

Siesta
The Siesta module is required to allow multi-player sleep. Using Siesta allows one player to speed up time to get through the night. More sleeping players means time speeds up faster.

Siesta also comes with an older module, called Insomnia, wrapped in. This portion of Siesta is optional. Insomnia alerts players when they have not slept in a while. At a future date Insomnia will try to address phantom spawning, which can be a real pain on multiplayer servers. At the moment, this cannot be addressed the way I'd like.

Havenstone
The Havenstone module adds home teleporting functionality. A Havenstone is set when you hold it while sleeping. It is used while holding your Soulsand Grimoire and your Havenstone. It has a 1 hour cooldown and 10 second channel time.

Run hs_give or use the Conjure Havenstone page of your Soulsand Grimoire to obtain a Havenstone.

Orienteer
This module adds a clock, compass and depth HUD. When holding a compass anywhere in your inventory you'll see your cardinal facing and X/Z coordinates. When you're holding a clock anywhere in your inventory you'll see the time of day. When you're holding a golden or diamond pickaxe either in your main hand or off hand you'll see your depth. Holding any of these three items in any combination, you'll see their respective data simultaneously.

This module is based on the works of Mouleagauffre. You can check out his datapacks here: www.planetminecraft.com/member/mouleagauffre/submissions



TECHNICAL

This section will discuss how this datapack was built and what decisions went into the result. Casual users of this datapack should not need to familiarize themselves with this information.

Load Concerns
The first goal with MCU was to establish a system that runs various methods at a rate that wouldn't cause undue load on the computer system running the game, be it client or server. To achieve this it runs a counter that counts each tick. At 20 ticks (1 second) it resets to 0 and starts over. Many methods only need to run once a second, or even less often, and this is how we control that. These methods can be staggered, to spread the datapack's load over a full second.

MCU tries to be conscious of potential load issues on multiplayer servers. One of the things it does to address this is to include what is called the Control Queue. Players are added to the queue as they log in, and various methods are run at them only when their number comes up in the queue. This occurs once per second for all players, staggered.

The Random Number Generator
The PRNG calculator is an LCG-type, and thus each iteration of the calculator produces an output based on the last value it produced. For this reason, we run the calculator once a second to keep the number good and random across time.

The Real-time Clock
For the moment the real-time clock is dependant on game-ticks. In theory, 20 game ticks pass every second. However, in practice it can often be as low as 10 or 15, depending in system load. It is for this reason that, if you choose to utilize the real-time clock, you may find yourself tweaking the clock on a regular basis. I will try to address this in the future.


HOW-TO

<work-in-progress>



FUTURE

I'll continue refining what has already been added to this datapack, but there are other things I'd like to add as well.

I'd like to add more scores, so that future datapacks or modules written to use this datapack can ensure they're compatible with other datapacks/modules written for this datapack.

I'm also interested in adding some sort of basic professions system, rewarding players with certain perks who perform particular duties on a regular basis. I'd like also to add a basic banking system. This system would include a growth/shrink mechanic that rewards communities who utilize the banking-backed economy more often (economic GDP).

Another thing I'd like to add is an older module I removed some time ago - holidays. I like the idea of an automated holiday tracker, that sends out little gifts or initiates certain events based on the time of year or what holidays are on.

There are other ideas out there, and you are free to submit them to me for consideration. I have more of my own to discuss at a later date. If you have any feedback on this datapack, please don't hesitate to contact me or post a comment on the PMC datapack page: www.planetminecraft.com/mod/minecraft-utilities-for-1-14/