Bevy Histrion Packer

[!WARNING] This crate is in early development, and its API may change in the future.

A Bevy plugin to allows to efficiently pack all game assets, such as textures, audio files, and other resources, into a single common PAK like file format.

Usage

Packing assets

By default, the pack_assets_folder function compress metadata with Brotli and uses Deflate for data except for some specific loaders/extensions:

Pack assets folder with pack_assets_folder function:

# Cargo.toml

[dependencies]
bevy = "0.14"
bevy-histrion-packer = "0.4"

[build-dependencies]
bevy = { version = "0.14", features = [
  "asset_processor",
  "file_watcher",
  "embedded_watcher",
] }
bevy-histrion-packer = { version = "0.4", features = [
  "writer",
] }

// build.rs
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // only run this code for release builds
    #[cfg(not(debug_assertions))]
    {
        use bevy::{app::ScheduleRunnerPlugin, prelude::*};
        use bevy_histrion_packer::pack_assets_folder;
        use std::path::Path;

        let imported_assets = Path::new("imported_assets");

        // delete the imported_assets folder
        if imported_assets.exists() {
            std::fs::remove_dir_all(imported_assets)?;
        }

        // generate the processed assets during build time
        let mut app = App::new();

        app.add_plugins(MinimalPlugins.set(ScheduleRunnerPlugin::run_once()))
            .add_plugins(bevy::asset::AssetPlugin {
                mode: AssetMode::Processed,
                ..Default::default()
            })
            .init_asset::<Shader>()
            .init_asset_loader::<bevy::render::render_resource::ShaderLoader>()
            .add_plugins(bevy::render::texture::ImagePlugin::default())
            .add_plugins(bevy::pbr::PbrPlugin::default())
            .add_plugins(bevy::gltf::GltfPlugin::default());

        app.run();

        // pack the assets folder
        let source = Path::new("imported_assets/Default");
        let destination = Path::new("assets.hpak");

        pack_assets_folder(&source, &destination)?;
    }

    Ok(())
}

It's also possible to have more control over the packing process with Writer:

// build.rs
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // only run this code for release builds
    #[cfg(not(debug_assertions))]
    {
        use bevy_histrion_packer::{CompressionAlgorithm, WriterBuilder};
        use std::fs::{File, OpenOptions};
        use std::path::Path;

        let destination = Path::new("assets.hpak");

        let mut writer = WriterBuilder::new(
            OpenOptions::new()
                .write(true)
                .truncate(true)
                .create(true)
                .open(&destination)?,
        )
        .meta_compression(CompressionAlgorithm::Brotli)
        .build()?;

        let mut data = File::open("assets/texture_1.png")?;
        let mut meta = File::open("assets/texture_1.png.meta")?;

        writer.add_entry(
            Path::new("my_texture_path.png"),
            &mut meta,
            &mut data,
            CompressionAlgorithm::Deflate,
        )?;

        // ...

        writer.finish()?;
    }

    Ok(())
}

Loading assets

// main.rs
use bevy::prelude::*;
use bevy_histrion_packer::HistrionPackerPlugin;

fn main() {
    let mut app = App::new();

    app.add_plugins(
        DefaultPlugins
            .build()
            .add_before::<bevy::asset::AssetPlugin, HistrionPackerPlugin>(
                HistrionPackerPlugin {
                    source: "assets.hpak".into(),
                    mode: bevy_histrion_packer::HistrionPackerMode::ReplaceDefaultProcessed,
                },
            )
            .set(bevy::asset::AssetPlugin {
                mode: AssetMode::Processed,
                ..default()
            }),
    );

    app.run();
}

Features

Bevy Compatibility

License

Dual-licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.