MCF (Minecraft Collections Framework): EntityMap
适用于 Minecraft 数据包的类 JCF 实体映射
MCF: EntityMap 是一个数据包库,用于实现极快且简单的按实体数据存储。受 Java HashMap API 启发,EntityMap 允许在实体上存储属性和其他相关数据,而无需处理 UUID,并支持高级交互。
感谢 CJDev 提供的 UUID 转换支持!
Map 还是 EntityMap?
这两个库功能相似,但专为不同目的设计。MCF: Map 更适合通用数据管理,因为它不与游戏中的对象(如实体)绑定,如果你的数据包依赖非实体存储,它是更好的选择。MCF: EntityMap 按实体基础存储数据,并具有自动 UUID 处理功能(MCF: Map 不具备此功能)。如果你的数据包高度依赖实体,那么它是更好的选择。
功能
- 按实体存储 - 支持在不同路径下拥有同一实体的多个实例。数据不同步。
- 镜像几乎所有
HashMap 方法的函数 - 熟悉、简单且直观的功能!
- 自动 UUID 解析和处理 - 无需担心任何与 UUID 相关的操作,底层会自动处理一切。
- 无需直接操作存储 - 除了获取器输出的结果外,所有存储位置的访问和修改均在内部完成。
- 调试工具 - 轻松打印和错误捕获,让工作更轻松。
- 文档化和注释代码 - 所有顶层函数均包含简要描述和参数列表。
用法
所有旨在使用的函数都位于顶层或 settings 下。 强烈不建议直接调用 internal 中的任何函数,因为结果可能不符合预期,甚至可能导致问题。
示例
function mcfentitymap:new {path: "entities"}
function mcfentitymap:put {path: "entities", key: "class", value: "mage"}
上面的示例展示了如何将实体注册到存储路径 mcfentitymap:maps entities,然后添加属性 class: mage。这些值可以使用提供的函数以与在 JCF maps 中大致相同的方式进行修改或访问。
注意:更改此数据包的命名空间以匹配你的项目可能会很有帮助。在 VSCode 中实现这一点的最简单方法是在搜索标签中将所有 mcfentitymap 实例替换为 mynamespace。
“path”是什么,我该如何知道使用哪些参数?
所有提供的函数都需要传入一个路径。由于 Minecraft 函数不能重载,存储路径无法由数据包推断或由用户忽略。
该路径用于在 mcfentitymap:maps 下用户选择的存储位置中存储给定实体。例如,如上所述,提供的示例将添加的实体存储在 mcfentitymap:maps entities。确切地说,path 参数指的是存储实体条目的列表。
再次强调,请随意配置命名空间和存储位置。
调试
你有多种调试工具可用。例如,要轻松查看实体的条目,只需运行函数 mcfentitymap:print_entity 并指定你想查看的实体。这将逐行在聊天窗口中打印它们的映射。
此外,当发生错误时,此数据包会捕获错误并停止执行。这些错误包括但不限于:
- 无效的参数
- 尝试访问不存在的路径
- 尝试修改不存在的条目
默认情况下,这些错误不会显示在聊天窗口中,但运行函数 mcfentitymap:settings/show_errors 或将你的分数 mcfem.show_errors 设置为 1,即可在聊天窗口中看到捕获到的错误。
如果你愿意,可以通过运行函数 mcfentitymap:settings/disable_errors 完全禁用错误捕获,但这强烈不推荐,仅建议在错误捕获对你的项目造成实际问题时才考虑这样做。
如需联系,请在 Discord 上向 wisoven 发送消息!
MIT 许可证。
MCF (Minecraft Collections Framework): EntityMap
JCF-style per-entity mapping for Minecraft datapacks
MCF: EntityMap is a datapack library for incredibly fast and easy per-entity data storage. Inspired by Java's HashMap API, EntityMap allows for storing attributes and other relevant data on entities without having to handle UUIDs and enables high-level interaction.
Thanks to CJDev for UUID conversion!
Map or EntityMap?
These libraries are similar, but specialized for 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-entity storage - supports multiple instances of the same entity under different paths. Data is not synchronized.
- Functions to mirror nearly all
HashMap methods - familiar, simple, and intuitive functionality!
- Automatic UUID resolution and handling - don't worry about doing anything with UUIDs, as it's all handled under the hood.
- 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 mcfentitymap:new {path: "entities"}
function mcfentitymap:put {path: "entities", key: "class", value: "mage"}
The example above shows how an entity would be registered to the storage path mcfentitymap:maps entities, then have the attribute class: mage 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 mcfentitymap 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 entity at the user's choice of storage location under mcfentitymap:maps. For instance, as stated above, the provided example stores the added entity at mcfentitymap:maps entities. To be exact, the path parameter refers to a list in which entity 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 entity's entry, simply run the function mcfentitymap:print_entity as the entity whom you wish to view. This will print their 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 mcfentitymap:settings/show_errors or simply setting your score mcfem.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 mcfentitymap:settings/disable_errors, but this strongly discouraged and only recommended if error catching poses an actual problem to your project.
To get in contact for any reason, message wisoven on Discord!
MIT licensed.
评论 0
登录后参与评分
还没有评论,来抢沙发吧