Struct gate_build::AssetPacker

pub struct AssetPacker { /* fields omitted */ }

Packs image atlases and other assets as part of the build script for a Gate application.

Contains methods to pack all assets needed for a game and generate code to refer to these assets.

Methods

impl AssetPacker

fn new(assets_dir: &Path) -> AssetPacker

Constructs a new AssetPacker where packed asset files will be written to assets_dir.

Except when building to WASM, the assets_dir must be a directory named "assets" relative to the current directory used when the Gate application is run. This is usually in the base directory of the Rust project.

fn cargo_rerun_if_changed(&mut self)

Invoke this method to print "cargo:rerun-if-changed" statements for all files read and written by self.

This will retrigger a build script if any of these files are changed. Refer to Cargo documentation for more details.

Panics if called after calling methods to pack assets.

fn sprites(&mut self, in_dir: &Path) -> &[String]

Packs sprite images into an atlas, to be rendered by Gate renderer in "sprite" mode.

Image ".png" files are read from in_dir, generating enum handles with the same names as the image files. Returns the list of these handles indexed by ID, in the same order that they appear in the generated enum code.

The center of the image is used as the anchor point. If the width or height is odd, then the center of the image is between pixels. Transparent pixels padded around the image rectangle will be stripped before packing, so there is no need to worry about efficiency in regards to padded pixels.

If any image filename ends with "_t#", where # is a number, then it will interpret that image as a collection of tiles with width and height equal to #. The names generated to refer to each of these tiles are suffixed with "R#C#", referencing the row and column number. Empty tiles will be omitted.

Note: in the current implementation of gate there is only one atlas for sprites, but in the future there are plans to allow for larger games that may need multiple atlases loaded at different times.

fn tiles(&mut self, in_dir: &Path) -> &[String]

Packs tile images into an atlas, to be rendered by Gate renderer in "tiled" mode.

Follows the same packing conventions as self.sprites(in_dir). See that method for more details.

Note: in the current implementation of gate there is only one atlas for tiles, but in the future there are plans to allow for larger games that may need multiple atlases loaded at different times.

fn music(&mut self, in_dir: &Path) -> &[String]

Creates handles for and moves music files from in_dir to the assets directory.

Music files are expected to be in .ogg format, generating enum handles with the same names as the audio files. Returns the list of these handles indexed by ID, in the same order that they appear in the generated enum code.

fn sounds(&mut self, in_dir: &Path) -> &[String]

Creates handles for and moves sound files from in_dir to the assets directory.

Music files are expected to be in .ogg format, generating enum handles with the same names as the audio files. Returns the list of these handles indexed by ID, in the same order that they appear in the generated enum code.

fn gen_javascript_and_html(&mut self)

Creates a "gate.js" and "index.html" file in the assets directory for use with the WASM target architecture.

Build a gate app for WASM using the command cargo build --release --target wasm32-unknown-unknown. Aside from the html and javascript file, you will also need to manually copy the built wasm file to the assets directory after the build is complete. Specifically, copy the file "target/wasm32-unknown-unknown/release/my_app.wasm" to "my_assets_dir/gate_app.wasm". You will also need a copy of "howler.js" (see https://howlerjs.com/).

fn gen_javascript(&mut self)

Like gen_javascript_and_html, but omits the "index.html" file.

Use this if you are providing your own html file, which gives you the flexibility to e.g. add a title to the page. Although, you may want to generate the html file once during development to use as a reference.

fn gen_asset_id_code(self, out: &Path)

Generates Rust enums to use as handles for all of the packed assets.

The generated code will consist of four enums: SpriteId, TileId, MusicId, and SoundId. These types are collected together in the type AssetId, which implements gate::asset_id::AppAssetId. Constructing a gate::App instance with this as the Asset ID type will allow you to use the generated handles to refer to assets.

This method should be called after packing all of the assets. The sprites and tiles methods must be called before this, but music and sounds may be omitted if there is no audio.

The generated Rust code is written to out. This will typically be a file in the env::var("OUT_DIR") directory. Refer to the Cargo build script documentation for more details.