MCF (Minecraft Collections Framework): Map
适用于 Minecraft 数据包、类似 JCF 风格的地图式数据存储
MCF: Map 是一个用于极速且简便数据存储的数据包库。受 Java HashMap API 启发,EntityMap 允许在不频繁使用 /data 命令的麻烦下,将属性和其他相关数据存储在独立的条目中,从而实现更高级别的交互。
Map 还是 EntityMap?
这些库相对相似,但工作原理不同,服务于不同的目的。MCF: Map 在通用数据管理方面更胜一筹,因为它不与游戏中的对象(如实体)绑定,如果你的数据包依赖于非实体存储,它是更好的选择。MCF: EntityMap 按实体基础存储数据,并自动处理 UUID(MCF: Map 不具备此功能)。如果你的数据包重度依赖实体,它是更好的选择。
特性
- 按 ID 存储 - 使用唯一名称轻松创建和管理数据条目。
- 镜像几乎所有
HashMap 方法的函数 - 熟悉、简单且直观的功能!
- 无需直接操作存储 - 除了获取器的输出外,所有存储位置都在内部访问和修改。
- 调试工具 - 易于打印和捕获错误,让生活更轻松。
- 文档化和注释代码 - 所有顶层函数都包含简要描述和参数列表。
用法
所有旨在使用的函数都在顶层或位于 settings 下。 强烈不建议直接调用 internal 中的任何函数,因为结果很可能不符合预期,并可能导致问题。
示例
function mcfmap:new {path: "classes", name: "warrior"}
function mcfmap:put {path: "classes", name: "warrior", key: "health", value: 150}
上面的示例展示了如何将新地图 warrior 注册到存储路径 mcfmap:maps classes,然后添加属性 health: 150。这些值可以以与在 JCF 地图中使用提供函数时大致相同的方式进行修改或访问。
注意:更改此数据包的空间命名以匹配你的项目可能会有所帮助。在 VSCode 中实现此目的的最简单方法是在搜索选项卡中将所有 mcfmap 实例替换为 mynamespace。
“path”是什么,我该如何知道使用哪些参数?
所有提供的函数都需要传入一个路径。由于 Minecraft 函数不能重载,存储路径不能被数据包推断或由用户忽略。
该路径用于在用户选择的 mcfmap:maps 下的存储位置存储给定的地图。例如,如上所述,提供的示例将添加的地图存储在 mcfmap:maps entities。确切地说,path 参数指的是存储地图条目的列表。
同样,请随意配置空间命名和存储位置。
调试
有多种调试工具供你使用。例如,要轻松查看条目的属性,只需使用正确的 path 和 name 参数运行函数 mcfmap:print_map。这将逐行在聊天中打印其映射。
此外,当发生错误时,此数据包会捕获错误并停止执行。这些错误包括但不限于:
- 无效的参数
- 尝试访问不存在的路径
- 尝试修改不存在的条目
默认情况下,这些不会显示在聊天中,但运行函数 mcfmap:settings/show_errors 或将你的分数 mcfm.show_errors 设置为 1 将允许你在捕获这些错误时在聊天中看到它们。
如果愿意,你可以运行函数 mcfmap:settings/disable_errors 完全禁用错误捕获,但这强烈不建议,仅在你认为错误捕获对你的项目构成实际问题时才推荐这样做。
常见问题:
这究竟与 EntityMap 有何不同?
EntityMap 对于管理基于实体的对象和数据很有用,但不能可靠地超出该用例,因为每个地图都由实体 UUID 唯一标识。另一方面,Map 非常适合管理与实体无关的数据,因为每个地图都由(字符串)名称标识。Map 缺乏 UUID 解析以及显而易见的基于实体的标识。
不幸的是,将这些解决方案合并为一个会导致大量混乱(对用户和计算而言),因为函数需要尝试适应两种用例(或者拆分为两个)。最终,这种分离允许每个库专门从事各自类型的存储。
26.1 以下的版本会得到支持吗?
26.1 以下的版本未得到官方支持,因为它们未经过测试,但鉴于没有重大 overhaul,此数据包几乎肯定能在大多数 1.21 补丁上工作。但请酌情考虑。
如需联系,请在 Discord 上向 wisoven 发送消息!
MIT 许可。
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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧