"核心标签"

"核心标签"

为物品、方块和实体提供统一的标签API，实现跨模组兼容性

图书馆

Header

TagCore 是一个 Hytale 服务端模组/插件，它为游戏内容添加了一个简单、可复用的标签系统。

它允许你定义命名的 ID 组，例如物品、方块、实体、生物群系、效果、流体和伤害类型，然后通过一个简洁的 Java API 查询这些组。

特性

  • 以 JSON 格式定义标签
  • 支持以下标签类型：
    • item（物品）
    • block（方块）
    • entity（实体）
    • biome（生物群系）
    • effect（效果）
    • fluid（流体）
    • damage_type（伤害类型）
  • 使用 #命名空间:路径 从一个标签引用另一个标签
  • 在启动时解析完全扁平化的标签内容
  • 检测无效值、缺失引用、类型错误的引用以及循环引用
  • 从以下位置加载标签：
    • 打包的类路径资源，位于 tags/ 目录下
    • 来自服务器 mods/ 目录的外部 .zip 和 .jar 包
  • 为其他模组/插件提供易于使用的 TagService API

标签 ID 的工作原理

标签 ID 使用 命名空间:路径 的格式。

示例：

  • hytale:logs
  • tagcore:starter_weapons
  • mymod:undead

如果一个标签 ID 没有命名空间，TagCore 会将其标准化为默认命名空间：

hytale

因此，像这样的裸标签：

starter_weapons

会被视为：

hytale:starter_weapons

定义标签

标签文件是放置在 tags/ 目录下的 JSON 文件。

一个标签定义包含：

  • id - 标签 ID
  • type - 标签类型
  • values - 具体 ID 和/或标签引用的列表

示例物品标签

{
  "id": "tagcore:starter_weapons",
  "type": "item",
  "values": [
    "Weapon_Sword_Wood",
    "Weapon_Shortbow_Crude",
    "#tagcore:starter_ammo"
  ]
}

示例方块标签

{
  "id": "tagcore:logs",
  "type": "block",
  "values": [
    "Wood_Amber_Trunk",
    "Wood_Ash_Trunk",
    "Wood_Aspen_Trunk"
  ]
}

示例实体标签

{
  "id": "tagcore:undead",
  "type": "entity",
  "values": [
    "Zombie",
    "Skeleton",
    "#tagcore:boss_undead"
  ]
}

引用其他标签

你可以通过在引用的标签 ID 前加上 # 来将一个标签包含在另一个标签中。

{
  "id": "tagcore:all_logs",
  "type": "block",
  "values": [
    "#tagcore:logs",
    "#tagcore:modded_logs"
  ]
}

规则：

  • 被引用的标签必须存在
  • 被引用的标签必须是同一类型
  • 循环引用会被拒绝

标签的加载来源

TagCore 按以下顺序从两个位置加载标签：

  1. tags/ 目录下的类路径资源
  2. 服务器 mods/ 目录中的外部 .zip 或 .jar 包

外部包可以覆盖具有相同 ID 的内置标签。

使用 API

TagCore 提供了一个共享的 TagService 用于查询标签。

获取共享服务

import com.azuredoom.tagcore.api.TagService;
var tagServiceOptional = TagService.getTagService();
if (tagServiceOptional.isEmpty()) {
    return;
}


TagService tagService = tagServiceOptional.get();

检查标签是否存在

boolean exists = tagService.hasTag("tagcore:starter_weapons");

解析指定类型的标签

var result = tagService.resolveItemTag("tagcore:starter_weapons");
if (result.isSuccess()) {
    for (String itemId : result.value()) {
        System.out.println(itemId);
    }
} else {
    System.out.println("Failed to resolve tag: " + result.status());
    for (var issue : result.issues()) {
        System.out.println(issue.detail());
    }
}

检查成员是否属于某个标签

var result = tagService.isInItemTag("tagcore:starter_weapons", "Sword_Wooden");
if (result.isSuccess() && result.value()) {
    System.out.println("Sword_Wooden is in the tag.");
}

解析方块标签

var logs = tagService.resolveBlockTag("tagcore:logs");
if (logs.isSuccess()) {
    System.out.println("Resolved block IDs: " + logs.value());
}

通用成员检查

var result = tagService.isInTag("tagcore:starter_weapons", "Sword_Wooden");
if (result.isSuccess()) {
    System.out.println("Contained: " + result.value());
}

理解查询结果

大多数 TagCore API 调用返回一个 TagQueryResult<T>。

它提供以下信息：

  • status() - 总体结果状态
  • value() - 返回值
  • definition() - 匹配的标签定义（如果可用）
  • issues() - 验证或解析过程中的问题

常见状态：

  • SUCCESS（成功）
  • EMPTY（空）
  • NOT_FOUND（未找到）
  • WRONG_TYPE（类型错误）
  • INVALID_TAG_ID（无效标签 ID）
  • INVALID_CONTENT（无效内容）
  • CIRCULAR_REFERENCE（循环引用）

示例：

var result = tagService.resolveBlockTag("tagcore:logs");
switch (result.status()) {
    case SUCCESS, EMPTY -> {
        System.out.println("Resolved values: " + result.value());
    }
    case NOT_FOUND -> {
        System.out.println("Tag not found.");
    }
    default -> {
        System.out.println("Tag resolution failed: " + result.status());
        for (var issue : result.issues()) {
            System.out.println(issue.type() + ": " + issue.detail());
        }
    }
}

推荐的文件夹布局

打包资源布局示例：

src/main/resources/
└── tags/
    ├── items/
    │   └── starter_weapons.json
    ├── blocks/
    │   └── logs.json
    └── entities/
        └── undead.json

tags/ 下的具体子文件夹结构是灵活的。重要的是文件能够在 tags/ 根目录下被发现。

覆盖包示例

你可以在模组中打包一个默认标签，然后通过 mods/ 中的外部包覆盖它。

打包的标签：

{
  "id": "tagcore:starter_weapons",
  "type": "item",
  "values": [
    "Sword_Wooden"
  ]
}

外部覆盖：

{
  "id": "tagcore:starter_weapons",
  "type": "item",
  "values": [
    "Sword_Wooden",
    "Bow_Basic",
    "Dagger_Rusty"
  ]
}

备注

  • 值必须是声明类型的有效 ID。
  • 引用必须指向相同类型的标签。
  • TagCore 会立即解析引用，以便尽早暴露配置问题。
  • 裸标签 ID 会被标准化为默认命名空间 hytale。

托管合作伙伴

正在寻找可靠的服务器来运行 LevelingCore 和其他 Hytale 模组吗？

BisectHosting 提供预配置的游戏服务器、快速设置以及对模组环境的稳定性能支持。

使用代码 azuredoom 可享受 首月 25% 折扣。

BisectHosting