资源管理

Behemiron 提供统一的客户端资源管理系统，支持来自文件系统和压缩包的图片、视频和普通文件、目录资源。GIF使用为 Blaze3D 优化的解码器，视频使用 ffmpeg 硬解，最高支持 8k60 直出

概念导图

资源目录

所有资源位于游戏目录下的 Behemiron/ 文件夹：

.minecraft/
└── Behemiron/
    ├── textures/          # 图片资源
    │   ├── icon.png
    │   └── background.gif
    ├── videos/            # 视频资源
    │   └── intro.mp4
    ├── data/              # 数据文件
    │   └── config.json
    └── resources.zip      # ZIP 资源包

基本用法

获取资源

使用 ResourceManager 获取资源：

import com.behemiron.engine.forge.core.resource.ResourceManager

// 获取 PNG 图片
val png = ResourceManager.getResource<PngData>("textures/icon.png")

// 获取 GIF 动画
val gif = ResourceManager.getResource<GifData>("textures/loading.gif")

// 获取视频
val video = ResourceManager.getResource<VideoData>("videos/intro.mp4")

// 获取通用文件
val file = ResourceManager.getResource<FileData>("data/config.json")

// 获取目录
val dir = ResourceManager.getResource<DirectoryData>("textures/")

获取并绑定纹理

对于需要渲染的资源，使用 getResourceAndBind：

// 获取资源并绑定到纹理单元 0
val texture = ResourceManager.getResourceAndBind<PngData>("textures/icon.png")

预加载资源

异步预加载资源以提升性能：

// 预加载匹配的资源
ResourceManager.preload("textures/*.png")
ResourceManager.preload("videos/*.mp4")

资源类型

PngData - PNG 图片

val png = ResourceManager.getResource<PngData>("textures/icon.png")

// 获取 ResourceLocation（用于 Minecraft 渲染）
val location = png?.getResourceLocation()

// 绑定纹理
png?.bind()

// 释放资源
png?.unload()

GifData - GIF 动画

val gif = ResourceManager.getResource<GifData>("textures/loading.gif")

// 获取当前帧的 ResourceLocation（根据时间自动计算）
val currentFrame = gif?.getResourceLocation()

// 绑定当前帧
gif?.bind()

VideoData - 视频

视频资源支持完整的播放控制：

val video = ResourceManager.getResource<VideoData>("videos/intro.mp4")

// 播放控制
video?.play()
video?.pause()
video?.stop()

// 跳转
video?.seekToTime(5000L)      // 跳转到 5 秒
video?.seekToFrame(120)       // 跳转到第 120 帧

// 播放速度（0.25 ~ 4.0）
video?.setPlaybackSpeed(1.5f)

// 音量（0.0 ~ 1.0）
video?.setVolume(0.8f)

// 状态查询
video?.isPlaying()
video?.isPaused()
video?.isBuffering()

FileData - 通用文件

val file = ResourceManager.getResource<FileData>("data/config.json")

// 获取文本内容（UTF-8）
val text = file?.getText()

// 获取字节数组
val bytes = file?.getBytes()

// 获取输入流（可多次读取）
val stream = file?.getInputStream()

DirectoryData - 目录

val dir = ResourceManager.getResource<DirectoryData>("textures/")

// 列出所有文件
val allFiles = dir?.list()

// 按扩展名过滤
val pngFiles = dir?.list("png", "jpg")

// 打开目录中的文件
val stream = dir?.open("icon.png")

ZIP 资源包

基本使用

将资源打包为 ZIP 放入 Behemiron/ 目录，系统会自动识别：

Behemiron/
├── textures/         # 文件系统资源（优先）
└── resources.zip     # ZIP 资源包
    └── textures/
        └── icon.png

优先级

文件系统资源优先于 ZIP 资源包。相同路径的资源，文件系统中的版本会覆盖 ZIP 中的版本。

加密 ZIP

支持加密的 ZIP 资源包：

// 设置 ZIP 密码
ResourceManager.setZipPasswords(mapOf(
    "resources.zip" to "password123",
    "dlc.zip" to "dlcPassword"
))

最佳实践

1. 使用预加载

// ✅ 推荐：预加载常用资源
ResourceManager.preload("textures/ui/*.png")

// ❌ 不推荐：运行时频繁加载
fun render() {
    val icon = ResourceManager.getResource<PngData>("textures/icon.png")
    // ...
}

2. 及时释放资源

// 不再需要时释放
video?.stop()
video?.unload()