Spriting and Compressing Images

Minifying Images

Resources in devkit games are typically placed inside the resources/ folder. Anywhere within resources/ you may put a JSON file named metadata.json to configure compression settings for images.

Properties found in a folder/metadata.json file apply to every resource in the folder and its subfolders, though metadata.json in the subfolders may override properties.

A metadata.json file has a key rules with one or more rules. Each rule has one or more properties (key/value pairs):

{
  "rules": [
    {
      "files": ["1.png", "2.png"],
      "sprite": false
    },
    {
      "target": "browser-mobile",
      "compress": {"quantize": true}
    },
    ...
  ]
}

The package property

It's worth a brief note that there's a property package which applies to non-images as well. Any file with the property "package": false won't be included in a build.

The compress property

The compress property has a value that itself is a JSON object. This object can specify a format and options for that format. Supported formats are "jpg" and "png". Here's a simple rule for compressing in the png format:

<simple png rule>
"compress": {
  "format": "png"
}

There are actually several types of pngs: 32-bit pngs have 8-bits per channel (four channels, rgba, per pixel), while 8-bit pngs have only 8-bits per pixel (and 128 colors in a palette). 8-bit pngs are good for images that need to be downloaded quickly, since they're much smaller in file size (at the cost of quality). Converting a 32-bit png to an 8-bit png is called quantization, and you can do this by adding a quantize property:

<simple png8 rule>
"compress": {
  "format": "png",
  "quantize": true
}

For non-quantized pngs, you can specify an optimizationLevel between 0 and 7, which is passed to the underlying optimizer (optipng).

For the format jpg, you can specify progressive and arithmetic for jpegtran.

See [imagemin-pngquant](https://github.com/imagemin/imagemin-pngquant#api) for the full list of options for quantized pngs.

metadata.json hierarchy

If you specify compress in a nested metadata.json file, note that you will not get any of the compress properties from the ancestor. For example: if resources/metadata.json contains {"compress": {"optimizationLevel": 6}} and resources/images/metadata.json contains {"compress": {"format": "png"}}, images in the resources/images folder will get the default optimizationLevel of 2, not 6.

The sprite property

Settings "sprite": false includes the image in the build but does not sprite it into a spritesheet.

The target property:

The property target can be set to a string or array of build targets that the rule should apply to. For example, to quantize pngs for mobile browser builds, use:

{
  "target": "browser-mobile",
  "compress": {"quantize": true}}
}

The files property

The property files can be set to a string or array of filenames that the rule should apply to. Filenames can be paths to files or subfolders:

{
  "files": ["1.png", "animations/walking.png", "spaceships/"],
  "compress": { ... }
}

The example above explicitly matches for two png files and any images in the spaceships folder.

Schemes: debug versus release

DevKit supports two schemes - debug and release. Images are compressed only in the release scheme by default, but you can override this using the command-line options --compress-images or --no-compress-images:

devkit release browser-mobile --no-compress-images

devkit debug native-android --compress-images

Additionally, the flags --compress and --no-compress apply to both javascript files and images.