Compendium Image Mapping

A common question from users is how to safely apply art to compendiums. Applying art to creatures in compendiums in Foundry (opening the file browser and pointing to a new image) is unsafe. When the system updates, those image updates will be lost. The system includes a handy tool for applying art to system Actor compendiums, to retain your images after updates. This page will guide you through creating an art mapping.

A note on file paths

The structure of your module is entirely up to you. This guide assumes you have an art folder in your module, and that your mapping file is in the root folder of your module, but you can set it up however you like. Just remember Foundry's file paths start from the Data folder, so they'll always start with modules/your-module-name/ unless you're using art from another module/system, for some reason.

Step 1: Creating a module, and module.json

This can be a bit alien if you haven't done so before, but it's really just filling in the blanks. This FoundryVTT KB article article has more in-depth steps if you're stuck. In your FoundryVTT data/modules folder, create a new folder with your module's name. E.g sf-mapping. The name must be all lowercase, and spaces must be replaced with - (aka in slug-case or kebab-case).

In that folder, create a file called module.json. This is where we tell Foundry what is in our module. You can copy and paste the template below.

{
  "id": "sf-mapping",
  "title": "Starfinder Image Mapping",
  "description": "A cool module that adds cool art.",
  "authors": [
    {
    "name": "LebombJames"
    }
  ],
  "version": "1.0.0",
  "compatibility": {
    "minimum": "10",
    "verified": "10.291"
  },
  "relationships": {
    "systems": [{
      "id": "sfrpg",
      "type": "system",
      "manifest": "https://raw.githubusercontent.com/foundryvtt-starfinder/foundryvtt-starfinder/master/src/system.json",
      "compatibility": {
        "minimum": "0.22.1"
      }
    }]
  },
  "flags": {
    "sf-mapping": {
      "sfrpg-art": "modules/sf-mapping/art-mapping.json"
    }
  }
}

The full details of each field can be found on the KB article above, but the one relevant to us is the flags object (an object just being anything enclosed by {}). In the flags object, you can see a sf-mapping object. The name of that object must match your module's id (which must match the folder name). Inside that object, we have the sfrpg-art field. This is the file path to our mapping file, which we shall create in the next step.

+ Note: while the `sfrpg-art` field is typically a file path, 
+ you can include your mapping directly in it as an object like so:

  "flags": {
    "sf-mapping": {
      "sfrpg-art": {
        /* your mapping here, see Step 2 */
      }
    }
  }

Step 2: Creating a mapping

For your mapping file, create a new file in the root of your module folder, and name it sf-mapping.json. (The name doesn't actually matter, that's just what this guide is using as an example) The easiest way to explain the contents of a mapping file, is to show you an example, and then to explain what each field means.

{
  "alien-archives": {
    "2qbiJSmMCDVdaRrR": {
      "actor": "modules/sf-mapping/art/cool-image.webp",
      "token": {
        "img": "modules/sf-mapping/art/cool-image.webp",
        "scale": 2
      }
    },
    "74I5mQmMMiZWJ7jf": {
      "actor": "modules/sf-mapping/art/cool-image.webp",
      "token": "modules/sf-mapping/art/cool-image.webp"
    }
  }
}

• alien-archives is the id of the pack you're applying a mapping to. You can see these by typing game.packs in the console (F12) (omit the sfrpg. prefix in your mapping`. You can apply mappings to multiple compendia, each as its own object.
• "2qbiJSmMCDVdaRrR" is the id of the specific actor you're applying art to. You can find this by opening the actor in the compendium and clicking the little book icon on the title bar next to its name.
• actor is the file path of the image to be set to the actor's portrait image (the one directly visible on its character sheet)
• token is either (see the example above for instances of both):
  • The file path of the image to be set as the actor's prototype token image (the image when the actor is placed as a token)
  • An object, containing img, which is the file path as above, and scale, which is the scale of the token image, useful for tokens with pop-out.

Step 3: Testing your module

Make sure to restart Foundry after making any changes to your module.json. Open a Starfinder world and enable your module, then check your target compendium(s) to see if the art has applied. If it has, congrats! If it hasn't, check the console (F12) to see if anything has gone wrong. As usual, you can always come over to the #starfinder channel on the FoundryVTT discord for help too.