Skip to main content
When two source sprites are pixel-for-pixel identical, alias detection deduplicates them: only one copy is packed into the atlas. All duplicates point back to the same atlas frame via an aliasOf field in the data file. This shrinks atlas area without changing the public sprite ID set — every sprite ID still resolves correctly at runtime.
Alias detection is enabled by default.

​
Usage

​
CLI flags

Alias detection is controlled via the .fpsheet project file. There is no dedicated CLI flag — it’s always enabled unless explicitly disabled in your project configuration.

​
Project file configuration

Set the detect_aliases field in your .fpsheet project file: 
[sprites]
detect_aliases = true   # default
Set detect_aliases = false to pack every sprite independently even if some are identical.

​
Example output

Consider two sprites icons/star_gold.png and icons/star_gold_copy.png with identical pixels. With alias detection enabled: JSON Hash output: 
{
  "frames": {
    "icons/star_gold": {
      "frame": { "x": 2, "y": 2, "w": 32, "h": 32 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "sourceSize": { "w": 32, "h": 32 }
    },
    "icons/star_gold_copy": {
      "frame": { "x": 2, "y": 2, "w": 32, "h": 32 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "sourceSize": { "w": 32, "h": 32 },
      "aliasOf": "icons/star_gold"
    }
  }
}
Both IDs are present in the output. icons/star_gold_copy shares the same frame rect and carries an aliasOf field. The atlas texture only contains the pixels once.

​
Technical details

Equality is determined by a 64-bit xxHash of the raw RGBA pixel data, computed after loading and before trimming. Two sprites match if and only if their hashes are equal.
The canonical frame (the one that occupies the atlas rect) is chosen deterministically: the sprite that sorts first alphabetically by ID becomes the primary; all others become aliases of it.
Metadata fields (pivot, nine-patch) on alias entries are written independently — an alias can carry its own pivot even though it shares pixels with another sprite.

​
TexturePacker compatibility

TexturePacker also outputs an aliasOf field. FastPack uses the camelCase aliasOf key that matches TexturePacker’s JSON Hash exporter, ensuring compatibility with engines that already support TexturePacker atlases.

Build docs developers (and LLMs) love

Get started for freeTalk to us