Command of the Week - File Paths (Week 10)
This series is called the command of the week, but it could also explain a feature. The explanations will tend to explain the technical parts of the command, and is intended to highlight the basics (and complexities) of the command, and information about how to use it, but won't be a detailed tutorial. It is up to you to use it creatively in your maps.
Week 10 - File PathsFor basic maps, you don't really need to know where the various files your map needs are stored, since references in the official ProFantasy symbol catalogs and templates are already set up correctly. But once you start adding additional resources to a map, for example using custom symbols, importing fill style from other styles, or inserting images into your map, file paths become very important. It is these file paths that tells CC3+ where to find the resources needed in your map. If you don't do this correctly, everything will work fine right now, but you will soon get into problems when you try to open the map on another computer or share it with someone else if this isn't handled correctly.
For example, say you insert an image into you map from your documents folder, called image.png. The path to this file on my computer would be C:\Users\monsen\Documents\image.png. If I used this path for the image in CC3+, and then gave the map (and the image) to someone else, for it to work, they would actually have to make the C:\Users\monsen\Documents\ path on their computer, even if their username isn't monsen, because that is where the map tells CC3+ to find the resource. Some people may also keep their images on the -drive, while others have the D-drive as their DVD-Rom drive, where they definitely can't simply copy in some files for use with the map. You could also experience the same problems yourself if you switched to a new computer with a different setup.
To avoid problems like this, we need to be aware of how to use file paths when we use external images in CC3+. Typical external resources includes fill styles and inserted images, as well as images used as part of effects. With regards to symbols, their path is set in the symbol catalog that contains them, so this is very important when creating a symbol catalog, but you don't need to think about this when using symbols (assuming the symbol catalog was correctly created int he first place
Absolute PathAn absolute path is a path that points to a specific location on your disk, such as C:\ProgramData\Profantasy\CC3Plus\Bitmaps\Tiles\Dungeon\Mike Schley\Brick Grey.PNG or d:\mysymbols\dungeons\rock.png
These kind of paths are generally very bad for the portability of the map, since the recipient must have the files in those exact locations. For example, if the user of that computer chose to put his CC3+ data directory on d:\CC3Plus instead of the more common c:\ProgramData\ProFantasy\CC3Plus, those resources wouldn't work on that computer, and the symbols/fills would show up as red X'es, even if he had the correct add-on installed. Suffice to say, these kinds of paths should always be avoided
Relative PathsA relative path is a path that is relative to something else. For example, a you can indicate that the fill bitmap is located in the same folder as the map itself, meaning that the recipient can put the map you shared with him wherever he want, as long as he put the fill bitmap in the same location. It is also possible to put files relative to the CC3+ installation directory and the CC3+ data directory. The latter is used in all ProFantasy template and symbol catalogs to ensure that everything works fine no matter where the users chooses to install CC3+.
There are three types of relative paths:
Relative to data directoryPaths relative to the data directory always starts with the @-symbol. CC3+ knows that this symbol refers to the location of your CC3+ data directory, no matter where that may be. For example, if you start a new map in the CC3 Standard Overland style, and click the fill style indicator, and activate the bitmap files tab, you can see that the path for all the fill styles here start with @Bitmaps\Tiles\Overland. The @-symbol at the beginning tells CC3+ to go look in the CC3+ data directory, no matter where that may be. The rest of the path just refers to the directory structure inside the data directory. So, if your data directory is the standard c:\ProgramData\ProFantasy\CC3Plus, CC3+ will translate that path to c:\ProgramData\ProFantasy\CC3Plus\Bitmaps\Tiles\Overland. On someone elses computer, CC3+ might be installed to e:\mappingSoftware\CC3P, and in that case, CC3+ would translate the path to e:\mappingSoftware\CC3P\Bitmaps\Tiles\Overland
So, no matter where CC3+ is actually installed, the @-symbol will refer to the data directory.
Relative to installation directoryFor those of you who have used version of CC prior to CC3+, you may remember that it didn't have a separate data directory, everything was stored in the installation directory instead. The reference for something relative to the installation directory is the #-symbol. Except for a different symbol, it behaves exactly as the @-symbol above, only that it points to the installation directory instead.
For CC3+ you should NEVER use this, as there is nothing of interest in the installation directory anymore, all resources was moved to the data directory. However, you may find this reference in older documentation. Usually, you can just straight swap it out with the @-symbol when applying these older instructions to CC3+.
Also note that for compatibility reasons, if CC3+ sees the #-reference, and the file it points to is not found in the installation directory, it will look for it in the data directory instead. This ensures that old CC3 maps works with CC3+. However, when this fallback occurs in CC3+, it won't be able to reference the four different resolutions of each image, but only the specific one the reference points to (resulting in slow redraw if it points to the VH one, or poor textures if it points to the VL one), so unless you need to keep map compatibility with CC3, DO NOT use this reference in CC3+, and always replace it as you encounter it.
Note that the FFIX command can be used to replace all the # references in a map.
Relative to the mapGenerally, resources are used by many maps, so it makes more sense to keep them in your CC3+ data directory, but for easier distribution and sharing, you can also keep resources along with the map.
To do this, use the $-symbol. This behaves in the same manner as the above path references, except that it always refer to the directory the current map is in. So, if an image reference in a map is $images\tree.png it means that the image is in a subfolder called images, which is located in the same folder as the current map. This is a good way of handling resources if you intend to distribute a collection of maps, you can simply have a subfolder with all the resources in.
Where to I see/set these paths?There are multiple elements in CC3+ that uses paths, let us look at them
Fill StylesIf you click the fill style indicator in the top left, and go to the bitmap files tab, you should see something similar to this screenshot. The left dialog correctly uses a relative path (relative to the CC3+ data directory), the right dialog shows an absolute path, which means that this will will not work for anyone having installed CC3+ to a different lcoation than the default. Note that CC3+ will not make the path relative by default when you use the find button to browse for the texture, you MUST fix this yourself.
Inserting ImagesWhen you go to Draw -> Insert image, there is a Bitmap Options button. Always click it, and make sure to set the option to make the path relative to either the drawing or the CC3 path (for CC3+, this refers to the data directory, not the installation directory), depending on where you keep the image. Note that CC3+ will only be successful if it is possible to refer to the image using a relative path. For example, you can't make it relative to the CC3+ data directory unless the image is actually located inside that directory somewhere. It is therefore very important to store your images and other resources in proper locations.
HotspotsIf you want to link your maps together in an interactive atlas, or link to external files like map notes and such, you should always keep these resources along with your map, so that you can use the $-reference. Feel free to use subdirectories. Keeping a directory structure and using $-references ensures that the links work fine no matter where you move your atlas.
Note that when you make hyperlinks using the Link with map feature, CC3+ will try to make it relative, but it doesn't always find a relative path, so sometimes you need to edit the hotspot with numeric edit and change the path yourself.
The image below shows three hyperlinks in the Ezrute map. The first one is a link to another map in the same directory, the second one shows a relative link that moves out of the current directory (the .. symbol), and then into another directory to access a map there. The third one is an absolute path. The first two will work wherever you move the root folder as long as you keep the internal directory structure intact, while the last one will fail once you move anything.
Importing SymbolsWhen you are creating symbol catalogs, and go to Symbols -> import pngs, the dialog will have an option like the one described for inserting images above. So even if the path shown in the dialog is an absolute path, CC3+ will convert it, assuming the correct option is set and the images are stored in an appropriate location. You should ALWAYS keep the images for your symbols somewhere inside the CC3+ data directory, such as @Symbols\User\MySymbols\Buildings
Importing fill stylesThe same rules applies to importing fill styles (Draw -> Import bitmap fill styles) as for importing symbols above. Fills styles should generally be put in a folder under @Bitmaps\Tiles
Where should I keep my files?Because of the huge advantages using relative paths gives you, you should usually always keep files intended for use with more than one map inside your CC3+ data directory. Don't be afraid to make your own subfolders. Some people like to keep their images in different locations, such as a network drive for easy backup and so on, but if you do, consider that a backup, always keep the copy you actually use inside your CC3+ data directory, never reference files in other locations from your maps. This can save lot a lot of trouble when you share your maps or change to a new computer.
If you have files that are only used by a single map, such as a special background image or similar, keep it in the same folder as the map, and use the $-reference in the path.