Rust资源管理库pocket-resources使用指南

概述

pocket-resources是一个高效的Rust资源管理库，专门用于加载、缓存和管理本地与远程资源。它提供了简洁的API和强大的功能，特别适合游戏开发、多媒体应用或任何需要高效资源管理的场景。

主要特性

• 统一接口处理本地和远程资源
• 自动缓存管理
• 异步加载支持
• 资源生命周期管理
• 轻量级设计

安装

在Cargo.toml中添加依赖：

[dependencies]
pocket-resources = "0.3"
tokio = { version = "1.0", features = ["full"] } # 如果需要异步支持

基本使用方法

初始化资源管理器

use pocket_resources::Resources;

let mut resources = Resources::new();

添加资源路径

// 添加本地路径
resources.add_local_path("textures/", "/path/to/textures");

// 添加远程URL基础路径
resources.add_remote_path("textures/", "https://example.com/textures/");

加载资源

同步加载

let texture_data = resources.load("textures/character.png")?;

异步加载

let texture_data = resources.load_async("textures/character.png").await?;

缓存管理

// 预加载资源到缓存
resources.preload("textures/background.jpg")?;

// 从缓存中获取资源(如果存在)
if let Some(cached) = resources.get_cached("textures/background.jpg") {
    // 使用缓存资源
}

// 清除缓存
resources.clear_cache();

资源监听

use pocket_resources::ResourceEvent;

// 设置资源变更监听器
resources.watch(|event| {
    match event {
        ResourceEvent::Loaded { path } => println!("Loaded: {}", path),
        ResourceEvent::Error { path, error } => eprintln!("Error loading {}: {:?}", path, error),
        _ => {}
    }
});

高级用法

自定义加载器

use pocket_resources::{Loader, ResourceData};

struct CustomLoader;

impl Loader for CustomLoader {
    fn load(&self, path: &str) -> Result<ResourceData, Box<dyn std::error::Error>> {
        // 实现自定义加载逻辑
        Ok(ResourceData::new(vec![1, 2, 3, 4]))
    }
}

resources.add_loader("custom://", CustomLoader);

资源组管理

// 创建资源组
let mut group = resources.create_group("level1");

// 向组中添加资源
group.add("textures/level1_background.png");
group.add("models/level1_boss.glb");

// 加载整个组
group.load_all()?;

// 卸载组资源
group.unload_all();

示例：游戏资源管理

use pocket_resources::Resources;
use std::path::PathBuf;

async fn load_game_assets() -> Result<(), Box<dyn std::error::Error>> {
    let mut resources = Resources::new();
    
    // 设置资源路径
    resources.add_local_path("assets/", "./game_assets");
    resources.add_remote_path("dlc/", "https://game.com/dlc/");
    
    // 预加载关键资源
    resources.preload("assets/textures/ui/main_menu.png")?;
    
    // 异步加载其他资源
    let character_future = resources.load_async("assets/models/player.glb");
    let environment_future = resources.load_async("dlc/environments/forest.glb");
    
    let (character, environment) = tokio::join!(character_future, environment_future);
    
    // 使用资源...
    
    Ok(())
}

完整示例

下面是一个完整的游戏资源管理示例，展示了如何使用pocket-resources加载和管理游戏资源：

use pocket_resources::Resources;
use tokio::runtime::Runtime;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建Tokio运行时
    let rt = Runtime::new()?;
    
    // 异步代码块
    rt.block_on(async {
        // 初始化资源管理器
        let mut resources = Resources::new();
        
        // 添加本地资源路径
        resources.add_local_path("assets/", "./assets");
        
        // 添加远程资源路径
        resources.add_remote_path("dlc/", "https://example.com/game/dlc/");
        
        // 预加载关键UI资源
        resources.preload("assets/textures/ui/loading.png")?;
        resources.preload("assets/textures/ui/main_menu.png")?;
        
        // 异步加载角色模型
        let character = resources.load_async("assets/models/player.glb").await?;
        println!("Loaded character model: {} bytes", character.len());
        
        // 异步加载DLC环境
        let environment = resources.load_async("dlc/environments/castle.glb").await?;
        println!("Loaded environment: {} bytes", environment.len());
        
        // 创建关卡资源组
        let mut level1 = resources.create_group("level1");
        level1.add("assets/textures/level1/background.png");
        level1.add("assets/models/level1/enemies.glb");
        level1.add("assets/sounds/level1/bgm.mp3");
        
        // 加载整个关卡资源
        level1.load_all()?;
        println!("Level 1 resources loaded");
        
        // 模拟游戏运行...
        println!("Game is running...");
        
        // 卸载关卡资源
        level1.unload_all();
        println!("Level 1 resources unloaded");
        
        Ok(())
    })
}

性能提示

1. 对于频繁使用的资源，使用preload提前加载
2. 合理设置缓存大小避免内存占用过高
3. 对大型资源考虑使用流式加载
4. 使用资源组管理相关资源

pocket-resources通过其简洁的API和高效的设计，使得Rust项目中的资源管理变得更加轻松和高效。