Struct AssetPacker

pub struct AssetPacker { /* private fields */ }

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.

Implementations

impl AssetPacker

pub 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.

pub 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.

pub fn mp3_fallback(&mut self)

Invoke this method to copy .mp3 files along with .ogg files for audio.

This is useful when compiling to the WASM target architecture. The Safari browser does not support the .ogg file format, so .mp3 files can be used as a fallback option.

Panics if called after calling methods to pack audio assets.

pub 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.

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

Creates handles for and copies 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.

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

Creates handles for and copies 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.

pub 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/).

pub 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.

pub 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, 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 method 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.