Multi-resolution variants

Scale variants generate atlas files at multiple resolutions in a single pass. A common setup produces @1x and @2x atlases from the same source sprites: the high-resolution atlas serves retina or high-DPI displays; the low-resolution one serves standard displays. Each variant specifies a scale factor, an optional filename suffix, and a resampling mode. All variants are produced from the same loaded source sprites — images are only read from disk once.

Configuration

Single variant

To produce a single scaled atlas:

fastpack pack sprites/ --scale 0.5 --suffix @1x

Multiple variants

Multiple variants require a project file:

.fpsheet

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "smooth"

[[variants]]
scale = 1.0
suffix = "@1x"
scale_mode = "smooth"

Scale modes

Resamples with Lanczos3. Use it for photographic sprites or mixed content.

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "smooth"

Best for realistic artwork, photos, and general-purpose scaling.

Uses nearest-neighbor. Hard pixel edges, no blurring. Good for pixel art at non-integer factors.

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "fast"

Preserves crisp edges, no interpolation.

Applies the EPX / Scale2x algorithm. Each source pixel expands to a 2×2 block, with corners filled by adjacent cardinal neighbors when they form a clean edge.

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "scale2x"

Intended for pixel art scaled to exactly 2×, but works at any factor: the 2× intermediate is then resampled with nearest-neighbor to reach the target size.

The 3× EPX variant. Same idea as scale2x, producing a 3×3 block per source pixel.

[[variants]]
scale = 3.0
suffix = "@3x"
scale_mode = "scale3x"

Use it for 3× pixel art upscaling.

Uses an edge-aware blend. It is a simplified version of the HQ2x algorithm: corner pixels blend towards matching cardinal neighbors to smooth diagonal edges in pixel art without blurring axis-aligned edges.

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "hq2x"

Produces softer output than scale2x at 2×.

Applies the Eagle 2× algorithm. Each corner of the 2×2 output block picks the diagonal neighbor’s color when that neighbor also matches both adjacent cardinal neighbors.

[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "eagle"

Sharper than hq2x, similar to scale2x but with different edge detection logic.

Output structure

With two variants and atlas name "sprites", the output directory contains:

output/
  [email protected]
  [email protected]
  [email protected]
  [email protected]

Each data file’s meta.scale reflects its variant’s scale factor:

{
  "meta": {
    "scale": "2"
  }
}

Multi-pack with variants

When multipack overflows on a variant, sheets are numbered before the suffix:

[email protected]
[email protected]
[email protected]
[email protected]

[email protected]
[email protected]

Scale variants each run an independent multipack sequence. The @2x variant may need multiple sheets while @1x fits in one.

Loading variants at runtime

PixiJS
Phaser 3
Unity

Detect device pixel ratio and load the appropriate variant:

const suffix = window.devicePixelRatio >= 2 ? '@2x' : '@1x';
await PIXI.Assets.load(`atlas${suffix}.json`);

// PixiJS automatically scales sprites based on meta.scale
const sprite = PIXI.Sprite.from('character.png');

function preload() {
  const suffix = window.devicePixelRatio >= 2 ? '@2x' : '@1x';
  this.load.atlas('sprites', `atlas${suffix}.png`, `atlas${suffix}.json`);
}

function create() {
  this.add.sprite(100, 100, 'sprites', 'character.png');
}

Import both variants and use Unity’s sprite atlas variant system:

// Unity selects the appropriate variant based on device DPI
Sprite sprite = Resources.Load<Sprite>("character");

Technical details

Each variant runs a full independent pipeline: sprites are scaled, trim rects are recomputed, the atlas is repacked, and the output is recompressed. Trim rects, nine-patch borders, and polygon vertices are all scaled proportionally so data file values are always in the variant’s own pixel space. Pivot points are normalized and scale-independent; they are copied to each variant unchanged. A scale factor of exactly 1.0 skips resampling entirely and copies source pixels directly. Pixel art modes (scale2x, scale3x, hq2x, eagle) apply their integer upscaler first, then resize to the exact target dimensions with nearest-neighbor if the factor does not align with the algorithm’s native multiplier. For example, scale2x at factor 4.0 produces a 2× EPX intermediate and then doubles it again with nearest-neighbor to reach 4×. Metadata (trim rects, nine-patch borders, polygon vertices) is always scaled by the requested factor, not by the algorithm’s native multiplier.

Best practices

Use power-of-two scales

For best results with GPU texture filtering, use power-of-two scale factors:

[[variants]]
scale = 2.0    # @2x for retina
suffix = "@2x"

[[variants]]
scale = 1.0    # @1x for standard
suffix = "@1x"

[[variants]]
scale = 0.5    # @0.5x for low-end devices
suffix = "@0.5x"

Choose the right scale mode

Realistic art / photos: Use smooth (Lanczos3)
Pixel art at 2×: Use scale2x or hq2x
Pixel art at 3×: Use scale3x
Fast processing / crisp edges: Use fast (nearest-neighbor)

Optimize for target platforms

Mobile devices often have high DPI screens but limited memory:

# Desktop: 2× for retina, 1× for standard
[[variants]]
scale = 2.0
suffix = "@2x"

[[variants]]
scale = 1.0
suffix = "@1x"

# Mobile: 1.5× for high-DPI, 0.75× for budget devices
[[variants]]
scale = 1.5
suffix = "@1.5x"

[[variants]]
scale = 0.75
suffix = "@0.75x"

TexturePacker calls these “Variants” and uses the same suffix convention. The meta.scale field in data files is a string (e.g. "2", "0.5") to match TexturePacker’s serialization.

Get Started

Guides

Packing

Export Formats

Features

Multi-resolution variants

Configuration

Single variant

Multiple variants

Scale modes

Output structure

Multi-pack with variants

Loading variants at runtime

Technical details

Best practices

Use power-of-two scales

Choose the right scale mode

Optimize for target platforms

Build docs developers (and LLMs) love

Get Started

Guides

Packing

Export Formats

Features

​Configuration

​Single variant

​Multiple variants

​Scale modes

​Output structure

​Multi-pack with variants

​Loading variants at runtime

​Technical details

​Best practices

​Use power-of-two scales

​Choose the right scale mode

​Optimize for target platforms

Build docs developers (and LLMs) love

Configuration

Single variant

Multiple variants

Scale modes

Output structure

Multi-pack with variants

Loading variants at runtime

Technical details

Best practices

Use power-of-two scales

Choose the right scale mode

Optimize for target platforms