Most of you have heard about macros. If you are an existing CC3+ user you’ve used them, knowingly or not, and you might even have written your own. For some people, the word macro may sound a little scary because it is associated with programming, but they’re really not that complicated.

Macros are used in a lot of places in the program. For example, when you start a new map or load an existing map, CC3+ uses a macro (stored in the OnNewMacro/OnOpenMacro map notes) to show you the appropriate toolbars and load the filters needed for the style of the map. A lot of the drawing tools uses macros to accomplish the more complex stuff, for example the forest drawing tools use a macro to call the commands to fill the area with trees, or the fields drawing tools in several styles use a macro to align the fields to the first edge of the polygon (These macros are stored with the drawing tools).

Lastly, CC3+ also has a macro file that contains named macros. These are often called from the toolbar buttons and menu elements in the program, so editing this file may change how the program behave.

And then we have script files….

Before we go on, let us just briefly look at what a macro in CC3+ really is.

At its most basic form a macro is simply a list of CC3+ commands that are run in sequence. And most macros take this form. The commands in the macro are the exact same as you would type on the CC3+ command line, and even if you are not normally typing commands yourself, you may have seen that after clicking a button and drawn something, you may see the name of the command you just used in square brackets on the command line:

Looking at the command line is a good way of learning the actual name of a command, but you can also find them in the CC3+ help files or in the Tome of Ultimate Mapping.

So, for example, a macro that sets the color to red, the fill style to solid, line width to 0 and then draws a big circle on the screen may look like this

COLOR 2
FSTYLE Solid
LWIDTH 0
CIRP 100,100 150,150

And that’s all that’s to it, four line, each line it’s own command doing a single thing.

Now, that’s the basic macro. In addition to commands, a macro may contain variables, labels and conditionals. With these, we are moving closer to the programming aspect of things, but while these are great for the more advanced macro writers, most macros never need these, and a novice macro writer can safely just ignore them for now.

When you write a custom macro in CC3+, you basically have 3 places you can chose to put them.

1) In the macro file. The macro file can be edited by going to the Tools -> Macros -> Edit Macros menu option, or it can be edited using an external text editor by editing the fcw32.mac file you find in your CC3+ data directory. This file contains a long list of named macros, so when you put your macros in here, they need to have a name. The actual macro would look exactly like my example above, but it needs two more lines. The line MACRO MACRONAME should be added at the start, and ENDM at the end. Just look at the other macros in there for an example. Once you have added your macro to this file, you can call them by typing the name you gave it (MACRONAME in my example) on the command line (and hitting enter).

This file is a good place to place custom macros, but it has a couple of disadvantages. First of all, if you mess up the syntax, you may break the entire file, and since many buttons and menu elements call upon the macros in here, this can cause parts of CC3+ to stop working properly. And since this is an important file for CC3+ itself, it may be overwritten in a later update to add functionality or fix bugs, which means your custom changes may be lost.

2) In a drawing tool. You can always make a macro drawing tool with your macro. In these cases, the macro is executed when you run the drawing tool. This is a good way of storing a simple macro. However, since tools are different depending on the current map style, it means that you may need to actually switch drawtool style to find your macros (and back afterwards). This isn’t a problems for macros that are closely related to the style, since you would only want them available in that style anyway, but maybe not as smooth when making more generic macros.

I wrote more about macro drawing tools in the Advanced Drawing Tools article.

3) In a script file.

So, we’re finally getting to the title of the article.

Script files are simply text files that contain a macro. Compared to the main macro file (fcw32.mac) they only hold a single macro, so they don’t have the MACRO/ENDM lines, just the actual macro itself, similar to how it would also appear in a drawing tool. So, writing them doesn’t present any additional difficulties or challenges, they’re pretty straight-forward. The only difference is that there is no way to write them in CC3+ itself, they have to be written using an external text editor, such as notepad.

So, what makes script files so great for macros then?

• They are standalone. They are not tied to a specific style, and editing the file is not likely to break CC3+ even if you mess it up.
• They are loaded on demand. A lot of the bigger more complicated macros are only used for limited, specific uses, you don’t need these loaded into CC3+’s memory at all times. This allows you to have a folder of scripts you can call on when you need them.
• They’re easy to maintain. When you write a complicated macro with lots of lines and conditionals and jumps, knowing that each file is a single macro makes it much easier to avoid mixing things up.
• Loading a macro from a script doesn’t mess with the standard macros. CC3+ allows you to load in a new macro file instead of the standard (fcw32.mac) one. However, doing this means all the macros in the standard file will be unloaded, and only the macros from the new file will be loaded. Unless the new file contains the definitions for all the various macros called from the CC3+ interface, this actually breaks lots of functionality. In earlier days, it was common to provide your new fancy macro this way, so people could load it, and then get access to your macros (by typing them on the command line), but it is problematic for the reason mentioned above, namely unloading the standard macros. However, loading a script file doesn’t have this disadvantage, because the script file isn’t loaded into macro memory, instead it is simply being executed and forgotten.
• Script files can be easily called from macros. Just as a macro can call another macro, which is helpful when you need to create helper functions for a complex macro, a macro (or script file) can just as easily call another script file. So even if each script file contains just one macro as compared to the macro’s file list of macros, you can still easily have many macros, just that they are in individual files, and you basically call the file name instead of a macro name.
• Script files can have all the complexity of a regular macro, like variables, labels, jumps and conditionals.
• They’re easy to back up. Just keep them all in the same folder (perhaps even with subfolders) and you only have to remember to backup that folder regularly. This folder can also easily be copied to another CC3+ installation and shared with other people easily.

So, how to use script files then?

Creating & Editing Script Files

To create a new script file, simply start notepad (or your preferred text editor, I prefer Notepad++ myself, but since notepad comes with windows, it is a good choice for those not wanting to install additional software), put in the macro lines one for one, just as with any macro (Remember, no MACRO/ENDM lines in a script file, it is just a single unnamed macro) and when done, save it in a sensible location (I recommends creating a Scripts folder inside your CC3+ data directory). You can of course name the file what you want. but I recommend a sensible file name. For example, my macro above draws a red circle, so naming it “Red Circle.scr” is probably appropriate. Remember, it should have the file extension .scr. Unfortunately, Windows has a default setting to hide file extensions (Presumably because most people don’t understand what they’re for) and if this is enabled, trying to save a file as “Red Circle.scr” in Notepad will save it as “Red Circle.scr.txt” (With the .txt part hidden, but still there), so watch out for this. [Also ignore that Windows thinks this is a screen saver file. This is purely based on the file extension, not the content of the file, and unfortunately, there isn’t an unlimited number of 3-letter combinations so collisions sometimes occur (CC3+’s use of this is for legacy reasons, it was in use before Windows ever used it for screen saver files, and it comes from the days when file extensions had to be 3 characters, something no longer required)]

Editing a script file is just a matter of opening it up in notepad. But since the .scr extension isn’t associated with notepad, you’ll need to start notepad first, then chose File -> Open to open the file.

When editing a script file, keep in mind that it has the same restrictions as macro files. The most common mistake to make here is extra empty lines. In CC3+, an empty line means repeat the previous command, which you almost never want in a macro (And if you do, it is usually better to just repeat the actual command so readers of the macro can see it is deliberate, rather than using an empty line). So, do NOT leave any empty lines anywhere within the macro. The only exception is that the very last line in the file should be completely blank (I.e., you should hit enter at the end of the last command in the file), but it should only be that single line.

Calling Script Files

Calling a script file can be done from the menu: Tools -> Macros -> Script file (This is why the files should have the .scr extension, or they won’t show up in this dialog since it filters files with this extension). Once you have picked the file, it will be run immediately, it is not like loading a new macro file where you need to type the name of the macro afterwards to run it. However, you need to load the script file this way every time you wish to run it, it won’t stay in memory like a macro file.

If you want to call a script file from the command line or a macro, you have the handy SCRIPTM command. This is the macro friendly version of the command, and it allows you to type in the filename on the command prompt instead of picking it through a dialog. For example, I can then in another macro have the command SCRIPTM @Scripts\Red Circle.scr and it wil load and run the script file without user input.

And, if there is a script file you use often, why not associate it with a toolbar button?

And that’s all there is to it really. You can find more about macro writing in general in other articles, but for a deeper dive, I recommend having a look at the Tome of Ultimate Mapping. I tried deliberately keeping this article about script files and other places to place your macros, not the act of writing the macros themselves.

If you have questions regarding the content of this article, please use the ProFantasy forums. It can take a long time before comments on the blog gets noticed, especially for older articles. The forums on the other hand, I frequent daily.