MCF: Map

# 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 ```mcfunction 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.