API 参考 / 渲染、资源与语言

ResourceManager

想先跑起来？

这一页是签名与行为参考。按命名空间加载贴图，失败行为见页面。直接做一遍：教程 · 贴图与译文。

用途：模组资源入口，经 ModContext#resources() 获取。读取模组自带的字节、文本与图像。

路径约定

一个 ResourceLocation（namespace:path）对应文件路径 assets/<namespace>/<path>，模组资源放在 src/main/resources/assets/<模组id>/…；
宿主按两级查找：① 磁盘覆盖 data/mods/<模组id>/assets/<namespace>/<path>（玩家可直接替换，无需重打包）；② 模组 jar 内 assets/<namespace>/<path>；
找不到即抛 ResourceNotFoundException，没有裸路径回退；
namespace 约定等于模组 id（内置内容为 seecmd），namespace 与 path 均强制小写（[a-z0-9_.-] / [a-z0-9/._-]）。

完整签名

java

public interface ResourceManager {

    byte[] readBytes(ResourceLocation location) throws ResourceNotFoundException;

    String readText(ResourceLocation location) throws ResourceNotFoundException;

    RenderImage loadImage(ResourceLocation location) throws ResourceNotFoundException;

    CompletableFuture<RenderImage> loadImageAsync(ResourceLocation location);

    List<ResourceLocation> list(String pathPrefix);

    RenderImage createImage(int width, int height, int[] argbPixels);
}

readBytes(location) / readText(location)

签名：

java

byte[] readBytes(ResourceLocation location) throws ResourceNotFoundException;

String readText(ResourceLocation location) throws ResourceNotFoundException;

行为：读取原始字节 / 以 UTF-8 读取文本（语言文件、JSON 配置等）。两级查找都未命中或读取失败时抛 ResourceNotFoundException。读取不依赖渲染上下文，可在任意线程执行（但阻塞 IO 别放在渲染线程）。

loadImage(location)

签名：

java

RenderImage loadImage(ResourceLocation location) throws ResourceNotFoundException;

行为：同步加载并解码图像（在调用线程解码，只依赖 JDK）。找不到或解码失败抛 ResourceNotFoundException。返回的句柄可在任意后端绘制，但后端纹理在渲染线程首次绘制时才创建，所以句柄要在渲染线程用。

loadImageAsync(location)

签名：

java

CompletableFuture<RenderImage> loadImageAsync(ResourceLocation location);

行为：在宿主 IO 线程池解码，是游戏/渲染线程加载大图的首选。失败时 future 以 ResourceNotFoundException 异常完成。

list(pathPrefix)

签名：

java

List<ResourceLocation> list(String pathPrefix);

行为：列出模组 jar 内 assets/ 下的条目（磁盘覆盖目录不参与枚举），用于「扫描目录里全部皮肤/音效」。

pathPrefix 形如 "<namespace>:<路径前缀>"，前缀可为空（"mymod:"）；
返回的 ResourceLocation 的 path 是相对 assets/<namespace>/ 的完整路径，可直接传给 readBytes / loadImage；
结果按字典序稳定排序，可能为空；pathPrefix 不含 ':' 或命名空间非法时抛 IllegalArgumentException。

createImage(width, height, argbPixels)

签名：

java

RenderImage createImage(int width, int height, int[] argbPixels);

行为：由像素数组生成新图像（配合 getPixelsARGB() 做模糊/变暗/缩放等处理）。width / height 须大于 0；argbPixels 为 0xAARRGGBB，长度不小于 width * height；否则抛 IllegalArgumentException。

示例：加载贴图并容忍缺失

java

private RenderImage logo;

@Override
public void onInit(ModContext ctx) {
    try {
        logo = ctx.resources().loadImage(ResourceLocation.of("mymod", "textures/logo.png"));
    } catch (ResourceNotFoundException e) {
        ctx.getLogger().warn("缺少 logo 贴图，使用纯色占位: " + e.location());
    }
}

上一页RenderImage 下一页ResourceNotFoundException