资源管理

客户端统一资源管理系统，支持图片/GIF/视频/文件/目录资源，GIF 使用 Blaze3D 优化解码，视频使用 ffmpeg 硬解（最高 8k60）。

前置知识

资源目录位于游戏目录下的 Behemiron/ 文件夹。

Quick Start

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

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

// 获取并绑定纹理
val texture = ResourceManager.getResourceAndBind<PngData>("textures/icon.png")

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

API Reference

ResourceManager

方法	签名	返回值	说明
getResource	getResource<T>(path: String)	T?	获取指定类型的资源
getResourceAndBind	getResourceAndBind<T>(path: String)	T?	获取资源并绑定到纹理单元 0
preload	preload(pattern: String)	—	异步预加载匹配的资源
setZipPasswords	setZipPasswords(map: Map<String, String>)	—	设置加密 ZIP 的密码映射

泛型参数 T 可选值：

类型	说明
PngData	PNG 图片
GifData	GIF 动画
VideoData	视频
FileData	通用文件
DirectoryData	目录

PngData

方法	返回值	说明
getResourceLocation()	ResourceLocation?	获取 Minecraft ResourceLocation
bind()	—	绑定纹理
unload()	—	释放资源

GifData

方法	返回值	说明
getResourceLocation()	ResourceLocation?	获取当前帧的 ResourceLocation（根据时间自动计算）
bind()	—	绑定当前帧纹理

VideoData

方法	参数	返回值	说明
play()	—	—	开始播放
pause()	—	—	暂停播放
stop()	—	—	停止播放
seekToTime(ms)	Long	—	跳转到指定毫秒
seekToFrame(frame)	Int	—	跳转到指定帧
setPlaybackSpeed(speed)	Float (0.25~4.0)	—	设置播放速度
setVolume(volume)	Float (0.0~1.0)	—	设置音量
isPlaying()	—	Boolean	是否正在播放
isPaused()	—	Boolean	是否已暂停
isBuffering()	—	Boolean	是否正在缓冲
unload()	—	—	释放资源

FileData

方法	返回值	说明
getText()	String?	获取文本内容（UTF-8）
getBytes()	ByteArray?	获取字节数组
getInputStream()	InputStream?	获取输入流（可多次读取）

DirectoryData

方法	参数	返回值	说明
list()	—	List<String>?	列出所有文件
list(vararg ext)	String (扩展名)	List<String>?	按扩展名过滤
open(name)	String	InputStream?	打开目录中的文件

资源目录结构

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

ZIP 资源包

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

优先级

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

加密 ZIP

ResourceManager.setZipPasswords(mapOf(
    "resources.zip" to "password123",
    "dlc.zip" to "dlcPassword"
))

完整示例

@Component
class ResourceLoader {

    @PostConstruct
    fun init() {
        // 预加载 UI 资源
        ResourceManager.preload("textures/ui/*.png")
        ResourceManager.preload("textures/ui/*.gif")
    }

    // 渲染 PNG 图标
    fun renderIcon(iconPath: String) {
        val png = ResourceManager.getResourceAndBind<PngData>(iconPath)
        val loc = png?.getResourceLocation() ?: return
        // 使用 loc 进行渲染 ...
    }

    // 渲染 GIF 动画
    fun renderAnimation(gifPath: String) {
        val gif = ResourceManager.getResource<GifData>(gifPath)
        gif?.bind()  // 自动绑定当前帧
        val loc = gif?.getResourceLocation() ?: return
        // 使用 loc 进行渲染 ...
    }

    // 播放视频
    fun playVideo(videoPath: String) {
        val video = ResourceManager.getResource<VideoData>(videoPath)
        video?.setVolume(0.8f)
        video?.play()
    }

    // 读取配置文件
    fun loadConfig(path: String): String? {
        val file = ResourceManager.getResource<FileData>(path)
        return file?.getText()
    }

    // 列出目录内容
    fun listTextures(): List<String> {
        val dir = ResourceManager.getResource<DirectoryData>("textures/")
        return dir?.list("png", "jpg") ?: emptyList()
    }
}

注意事项

• 优先使用 preload() 预加载常用资源，避免运行时频繁加载。
• 视频和大资源不再使用时应调用 stop() + unload() 及时释放。
• ZIP 资源包中的路径与文件系统路径一致，可无缝切换。