Platform-specific Resources

You may want to use different versions of a resource on one or more of the Aplite, Basalt or Chalk platforms. To enable this, it is now possible to "tag" resource files with the attributes that make them relevant to a given platform.

The follows tags exist for each platform:

To tag a resource, add the tags after the file's using tildes (~) — for instance, example-image~color.png to use the resource on only color platforms, or example-image~color~round.png to use the resource on only platforms with round, color displays. All tags must match for the file to be used. If no file matches for a platform, a compilation error will occur.

If the correct file for a platform is ambiguous, an error will occur at compile time. You cannot, for instance, have both example~color.png and example~round.png, because it is unclear which image to use when building for Chalk. Instead, use example~color~rect.png and example~round.png. If multiple images could match, the one with the most tags wins.

We recommend avoiding the platform specific tags (aplite, basalt etc). When we release new platforms in the future, you will need to create new files for that platform. However, if you use the descriptive tags we will automatically use them as appropriate. It is also worth noting that the platform tags are not special: if you have example~basalt.png and example~rect.png, that is ambiguous (they both match Basalt) and will cause a compilation error.

An example file structure is shown below.

my-project/
  resources/
    images/
      example-image~bw.png
      example-image~color~rect.png
      example-image~color~round.png
  src/
    main.c
  package.json
  wscript

This resource will appear in package.json as shown below.

"resources": {
  "media": [
    {
      "type": "bitmap",
      "name": "EXAMPLE_IMAGE",
      "file": "images/example-image.png"
    }
  ]
}

Single-platform Resources

If you want to only include a resource on a specific platform, you can add a targetPlatforms field to the resource's entry in the media array in package.json. For example, the resource shown below will only be included for the Basalt build.

"resources": {
  "media": [
    {
      "type": "bitmap",
      "name": "BACKGROUND_IMAGE",
      "file": "images/background.png",
      "targetPlatforms": [
        "basalt"
      ]
    }
  ]
}