#texture-atlas #texture #atlas #bevy #sprites #manifest-file

bevy_heterogeneous_texture_atlas_loader

Load heterogenous texture atlases from a ron manifest

19 releases (8 breaking)

0.10.0 Nov 14, 2022
0.9.3 Oct 12, 2022
0.7.0 Jul 31, 2022
0.5.1 Feb 27, 2022

#1247 in Game dev

MIT/Apache

35KB
105 lines

Bevy Heterogenous Texture Atlas Loader

crates.io MIT/Apache 2.0 crates.io

Bevy Heterogenous Texture Atlas Loader allows you to load heterogenous texture atlases from a RON file manifest.

Bevy Compatibility

version bevy
0.10 0.9
0.7 to 0.9 0.8
0.6 0.7
< 0.6 0.6

Basic usage

  1. Add to your project's Cargo.toml [dependencies] section

    bevy_heterogeneous_texture_atlas_loader = "0.10.0"
    
  2. Add the TextureAtlasLoaderPlugin to your Bevy App.

    use bevy_heterogeneous_texture_atlas_loader::*;
    app.add_plugin(TextureAtlasLoaderPlugin);
    
  3. Add the atlas source image and .ron manifest to your assets folder.

  4. Load the texture atlas manifest using the asset server:

    let texture_atlas: Handle<TextureAtlas> = asset_server.load("<path>.ron");
    

    The plugin will then load the atlas image and create the TextureAtlas asset automatically.

  5. The TextureAtlas's sprite indices respect the order of the sprites in the manifest. Atlas index 0 will be the first sprite in the manifest, 1 the second, and so on. You can also use the TextureAtlas::get_texture_index method to look up the index using an asset path:

    texture_atlas.get_texture_index(&Handle::weak("sprite_name".into()))
    

    which you can see used in \examples\example.rs

The Manifest

  • To create a manifest for a sprite sheet with irregular sized and positioned sprites like:

    /assets/example.png

  1. Create a .ron file in your assets folder.

    The sprite indices in the output TextureAtlas are ordered implicitly according to the order of the input list sprite rects.

  • The name field is used to give a sprite a unique name that can be used to look up their TextureAtlas index using a weak Handle<Image> with the asset_path "sprite_name".

    (
        // Path to the texture atlas source image file 
        path: "example.png",        
    
        // List of sprites        
        sprites: [    
            (
                // use a handle with the asset path "rothko" 
                // to retrieve this sprite's index using TextureAtlas::get_texture_index.
                name: "rothko",  
    
                // top left x coordinate of the sprite in pixels
                x: 18,           
    
                // top left y coordinate of the sprite in pixels
                y: 19,              
    
                // width of the sprite in pixels
                w: 46,              
    
                // height of the sprite in pixels
                h: 48               
            ),
            (
                name: "face", 
                x: 93, 
                y: 108, 
                w: 32, 
                h: 31
            ),
            (
                name: "patches", 
                x: 176, 
                y: 34, 
                w: 20, 
                h: 34
            ),
        ]
    )
    
  • If you don't need names for the sprites, you can leave out the name field:

    (
        path: "example.png",
    
        sprites:[         
            (    
                // sprite at atlas index 0
                x: 18, 
                y: 19, 
                w: 46, 
                h: 48
            ),
             (
                // sprite at atlas index 1
                x: 93, 
                y: 108, 
                w: 32, 
                h: 31
            ),
            // ...
        ]
    )
    

Examples

  • minimal.rs

    Loads a texture atlas and cycles through its textures. Run with

    cargo run --example minimal
    
  • example.rs

    Example of loading and displaying a texture atlas. Run with

    cargo run --example example
    

two.rs

Another example of loading and displaying texture atlases. Run with
```
cargo run --example example
```
  • bevy_asset_loader.rs

    Example using bevy_asset_loader to manage loading. Run with

    cargo run --example bevy_asset_loader
    

Dependencies

~20–35MB
~591K SLoC