ResourceLocation

命名空间资源标识（namespace:path），取代旧 API 的裸字符串 id，是注册表键、资源路径、模组贡献内容的统一身份。不可变、可安全作为 Map 键、可跨线程共享。构造器是私有的，必须经 of(...) / parse(...) 工厂创建，因此构造即校验：非法格式在创建时抛 IllegalArgumentException 并给出可读原因，让「注册了但 id 写错」立刻可见，而不是静默失效。

方法速览

完整签名

类声明为 public final class ResourceLocation implements Comparable<ResourceLocation>（下方围栏块省略 implements 子句，compareTo 即该接口的实现）：

public final class ResourceLocation {

    public static final String DEFAULT_NAMESPACE = "seecmd";

    public static ResourceLocation of(String namespace, String path);

    public static ResourceLocation parse(String id);

    public String namespace();

    public String path();

    public String toString();

    public boolean equals(Object o);

    public int hashCode();

    public int compareTo(ResourceLocation o);
}

of(namespace, path)

签名：

public static ResourceLocation of(String namespace, String path);

行为：由两段构造标识，先对两段做 trim，再分别匹配格式：

• namespace：[a-z0-9_.-]{1,64}，约定等于模组 id，内置内容用 seecmd；
• path：[a-z0-9/._-]{1,255}，允许 / 分组（如 textures/note.png）。

强制小写的原因：资源路径会落到 桌面系统 的大小写不敏感文件系统上。null 会被当作空串处理，随后因长度不足抛 IllegalArgumentException；非法时报错文案形如「只允许 [a-z0-9_.-]，长度 1~64，且必须小写」。

示例：

ResourceLocation tex = ResourceLocation.of("mymod", "textures/note.png");

parse(id)

签名：

public static ResourceLocation parse(String id);

行为：解析 namespace:path 字符串（null 视为空串）。空串抛 IllegalArgumentException("非法标识：不能为空")；含一个以上 : 抛 IllegalArgumentException（最多只能包含一个 :）；不含 : 时使用 DEFAULT_NAMESPACE（seecmd）；两段仍走 of(...) 的格式校验，因此 "mymod:" 这样的空路径同样抛异常。

示例：

ResourceLocation a = ResourceLocation.parse("seecmd:hold");
ResourceLocation b = ResourceLocation.parse("hold");
// b.toString() == "seecmd:hold"

namespace() / path()

签名：

public String namespace();

public String path();

行为：分别返回命名空间与路径，均为构造时已校验的小写字符串。资源加载时 <namespace> 对应 assets/<namespace>/，<path> 对应其后的相对路径。

示例：

String asset = "assets/" + id.namespace() + "/" + id.path();

toString()

签名：

public String toString();

行为：返回 namespace:path。该字符串在构造时缓存，高频作为键使用时不会重复拼接；直接打印或交给日志即可。

示例：

ctx.getLogger().info("loaded " + id);

equals(o) / hashCode()

签名：

public boolean equals(Object o);

public int hashCode();

行为：都基于缓存的 namespace:path 字符串。因为命名空间与路径都不允许 :、两段的分界无歧义，字符串相等即两段都相等。可安全用作 HashMap / HashSet 的键。

示例：

Set<ResourceLocation> seen = new HashSet<>();
if (!seen.add(id)) {
    ctx.getLogger().warning("duplicate " + id);
}

compareTo(o)

签名：

public int compareTo(ResourceLocation o);

行为：按 namespace:path 的字典序比较，用于需要稳定顺序的场合（如把模组内容排序后再输出）。注册表自身的遍历顺序是注册顺序，不是字典序。

示例：

List<ResourceLocation> ids = new ArrayList<>(regs.renderFilters().keys());
ids.sort(ResourceLocation::compareTo);

线程：不可变类型，可安全作为 Map 键、可跨线程共享。

生命周期阶段：注册窗口内用于构造注册键；运行期作为通用资源标识使用（资源加载、音效注册等）。

稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）。