MCF (Minecraft Collections Framework): Map

JCF-style map-like data storage for Minecraft datapacks

MCF: Map is a datapack library for incredibly fast and easy data storage. Inspired by Java's HashMap API, EntityMap allows for storing attributes and other relevant data in individual entries without the hassle of constant /data commands, enabling more high-level interaction.

Map or EntityMap?

These libraries are relatively similar, but they work in different ways to serve different purposes. MCF: Map is superior for general data management as it is not tied to in-game objects such as entities, making it a better choice if your datapack relies on non-entity-based storage. MCF: EntityMap stores data on a per-entity basis with automatic UUID handling (MCF: Map does not do this). It becomes a better choice if your datapack is heavily entity-based.

Features

• Per-ID storage - easily create and manage data entries using unique names.
• Functions to mirror nearly all HashMap methods - familiar, simple, and intuitive functionality!
• No direct storage manipulation required - other than outputs from getters, storage locations are all accessed and modified internally.
• Debug tools - easy printing and error catching to make life easier.
• Documented and commented code - all top-level functions include a brief description and parameter list.

Usage

All functions intended to be used are at the top level or under settings. Calling any functions in internal directly is strongly discouraged as the result will more than likely not be as intended and may potentially cause issues.

Example

function mcfmap:new {path: "classes", name: "warrior"}
function mcfmap:put {path: "classes", name: "warrior", key: "health", value: 150}

The example above shows how a new map warrior would be registered to the storage path mcfmap:maps classes, then have the attribute health: 150 added. These values can be modified or accessed in largely the same way they could be in JCF maps using the provided functions.

Note: it may be helpful to change the namespace for this datapack to match that of your project. The simplest way to achieve this in VSCode is by replacing all instances of mcfmap with mynamespace in the search tab.

What is the "path", and how do I know what parameters to use?

All provided functions require a path to be passed in. As Minecraft functions cannot be overloaded, storage paths cannot be inferred by the datapack or disregarded by the user.

The path is used to store a given map at the user's choice of storage location under mcfmap:maps. For instance, as stated above, the provided example stores the added map at mcfmap:maps entities. To be exact, the path parameter refers to a list in which map entries are stored.

Again, feel free to configure namespaces and storage locations as you see fit.

Debugging

There are multiple debugging tools at your disposal. For example, to easily view an entry's attributes, simply run the function mcfmap:print_map with the correct path and name parameters. This will print its mappings line-by-line in chat.

Additionally, this datapack will catch errors and stop execution when they occur. These errors can include, but are not limited to:

• Invalid parameters
• Attempting to access a path that doesn't exist
• Attempting to modify an entry that doesn't exist

By default, these are not shown in chat, but running the function mcfmap:settings/show_errors or simply setting your score mcfm.show_errors to 1 will allow you to see in chat when these errors are caught.

If you wish, you can disable error catching entirely by running the function mcfmap:settings/disable_errors, but this strongly discouraged and only recommended if error catching poses an actual problem to your project.

FAQ:

How exactly is this different from EntityMap?

EntityMap is useful for managing entity-based objects and data, but cannot reliably work beyond that use case, as each map is uniquely identified by an entity UUID. On the other hand, Map is great for managing data independent of entities, as each map is identified by a (string) name. Map lacks UUID resolution and, obviously, entity-based identification.

Unfortunately, combining these solutions into one would cause lots of jank for the user (and computationally) as functions need to attempt to accommodate both use cases (or be split into two). Ultimately, this separation allows each library to specialize in their respective types of storage.

Will versions below 26.1 be supported?

Versions below 26.1 are not officially supported as they have not been tested, but given a lack of major overhauls this datapack will almost certainly work on most 1.21 patches. But take this with a grain of salt.

---

To get in contact for any reason, message wisoven on Discord!

MIT licensed.