MCF: 实体映射

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 操作，全在幕后完成。
• 无需直接操作存储 — 除 getter 的输出外，所有存储位置均在内部访问和修改。
• 调试工具 — 简单的打印和错误捕获功能，让开发更轻松。
• 文档化和注释代码 — 所有顶层函数都包含简要描述和参数列表。

使用方法

所有预期使用的函数都在顶层或 settings 目录下。 强烈不建议直接调用 internal 中的任何函数，因为结果很可能不符合预期，并可能引发问题。

示例

function mcfentitymap:new {path: "entities"}
function mcfentitymap:put {path: "entities", key: "class", value: "mage"}

上述示例展示了如何将实体注册到存储路径 mcfentitymap:maps entities，然后添加属性 class: mage。这些值可以使用提供的函数以与 JCF 映射基本相同的方式进行修改或访问。

注意：将此数据包的命名空间改为与你的项目匹配可能会很有帮助。在 VSCode 中实现此操作最简单的方法是在搜索选项卡中将所有 mcfentitymap 替换为 mynamespace。

什么是“路径”，我如何知道要使用什么参数？

所有提供的函数都需要传入一个路径。由于 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 许可证。