atlaspack

Tiny deterministic sprite atlas packer for game dev.

Point it at a folder of PNGs. Get one atlas image and a JSON sheet. No engine dependency, no editor, no account — a finished CLI you can install and forget about.

atlaspack ./sprites -o atlas.png
# writes atlas.png + atlas.json

Install

# From crates.io (after publish)
cargo install atlaspack

# From this repository
cargo install --git https://github.com/vinybrun/atlaspack

# From a local checkout
cargo install --path .

Requires a Rust toolchain (MSRV 1.88).

Usage

atlaspack <INPUT> [OPTIONS]

Arguments:
  <INPUT>  Directory of .png sprites (recursive)

Options:
  -o, --output <OUTPUT>      Atlas PNG path [default: atlas.png]
  -j, --json <JSON>          JSON path [default: <output>.json]
  -p, --padding <PADDING>    Gap between sprites in px [default: 2]
      --max-size <MAX_SIZE>  Max atlas edge [default: 4096]
      --no-pot               Allow non power-of-two sizes
  -h, --help
  -V, --version

Example

atlaspack tests/fixtures/sprites -o /tmp/atlas.png -p 2
cat /tmp/atlas.json

JSON shape

{
  "atlas": {
    "image": "atlas.png",
    "width": 64,
    "height": 64,
    "padding": 2
  },
  "frames": [
    { "name": "coin", "x": 2, "y": 2, "w": 8, "h": 8 },
    { "name": "hero", "x": 12, "y": 2, "w": 16, "h": 16 }
  ]
}

• name — path relative to the input dir, without .png (stable, sorted).
• x, y, w, h — pixel rect in the atlas (top-left origin).

Drop the JSON into Bevy, macroquad, ggez, Godot, or your own loader. This tool does not care.

Guarantees

Library

use atlaspack::{pack_directory, PackConfig};

let packed = pack_directory(
    std::path::Path::new("./sprites"),
    &PackConfig::default(),
)?;
// packed.image : RgbaImage
// packed.json  : AtlasJson
# Ok::<(), atlaspack::Error>(())

API docs: https://docs.rs/atlaspack

Non-goals

• GUI / live preview
• Bevy (or any engine) plugin
• Texture compression (KTX2/Basis)
• Rotated packing, multipack, trimming

Those are fine projects for someone else. This crate stays small.

Status

Maintenance: best-effort. Scope is intentionally locked at v1. Bug fixes welcome; large feature expansions are out of scope (fork freely).

Contributing

Issues and small PRs are welcome. Please run cargo fmt, cargo clippy -- -D warnings, and cargo test before opening a PR.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://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.