Getting Started with Macros – Part 1

If you are a novice CC3+ user, you may think that macros sounds way to complicated to even touch. But, the fact is that from the moment you start making a map, you have already been exposed to several macros. You might not have noticed, but CC3+ uses macros for quite a lot of things. Every time you start a new map or load an existing one, a macro is run to set up the environment appropriately for that type of map. A lot of the buttons on the toolbars and elements in the menus call macros, and many of the drawing tools have embedded macros that are being run when you draw something with them.

So, why don’t we take a brief look at the basics of macros?

Campaign Cartographer 3+ is a command driven program. Basically, the user selects one command, then follows the prompts on the command line to complete that command, being it picking entities, placing nodes or just tell it how wide your line should be. Once you are done with one command, you start another, and then another, and so on. In day to day use of CC3+ you might not think to much about this, but if you look down on the command line when you are between two commands, you may notice that it says Command followed by a word in square brackets. That word is the last command you ran.

Now, what does this have to do with macros? Well, simply put, a macro is noting more than a series of commands that runs in sequence to produce a result. The very same commands that you use in the software when you map. Yes, there are some additional commands that helps control the flow of the macro, but the basic premise of macros are just a string of several commands executed in a row, simple as that.

For example, when you load a map, most maps have a macro with a series of commands that does the following:

  • Resets the current symbol catalog filter since it may be incompatible with the map being loaded
  • Changes the active symbol catalog filters so the symbol catalog buttons will load the appropriate symbols
  • Changes which menu is displayed to match the map type (overland, city, dungeon, etc…)
  • Loads up an appropriate symbol catalog in the symbol catalog window.

You could do all of this yourself easily enough, but having a macro that does it makes everything so much simpler. Especially a novice user might not even know which settings to load up. You can have a look at these macros yourself by clicking the Map Notes button and picking the OnOpenMacro map note and view it. For a standard Mike Schley Overland map, it looks something like this (lines matching the explanation above):

SYMICONMR
SYMICONFLOAD CC3MS
MENUDM @fcw32.mnu
CATALOG @Symbols\Maps\Mike Schley\Coast.FSC

As you can see, a macro is just a series of commands. Now, these commands themselves can look a bit cryptic if you are not used to seeing them, but you can find them all listed and explained in either the CC3+ help files (Pick Help from the Help menu, go to the Index tab, and search for commands to find the alphabetical list) or in the Tome of Ultimate Mapping if you own it (it comes with a detailed spreadsheet found in @Documentation\Tome\Commands.xlsx).

You should note one thing about each of the four lines above. Each line always starts with a command, then after the first space (or semicolon) we have the parameters to the command. Most commands needs some input, or parameters to tell it exactly what to do. For example, on the third line, the command itself is MENUDM which is the command that loads in a new set of toolbars, while @fcw32.mnu is the parameter that tells it which set of toolbars to load (in this case the overland ones). There will never be two commands on the same line (Normally; there are ways of writing things more compact so you can write several on one line, but that doesn’t change anything, it is just a visual layout, so we won’t use that here now, it is very rarely used anyway and doesn’t give any advantage or improved functionality). Likewise, the command itself will always be the first thing on the line.

 

Hopefully that clears up a bit what a macro really is. It is just a predefined series of standard commands, nothing more.

Now, as I mentioned in the introductions, we find macros everywhere. The macro that is being run when we open the map is one example. Another example are found in many drawing tools. For example, the forest drawing tools contains a macro that first loads in a predefined setup for which trees to use, then executes a CC3+ command called FOREST that is responsible for actually filling the polygon we drew with trees. Clicking a toolbar button may just call a single command, but it may just as well call a series of them, a macro. And finally, CC3+ contains a macro file where we can put our own named macros in. These macros can then be run just by typing the name of the macro on the command line. So let us finish this introduction by writing such a macro.

First of all, make a backup copy of the file fcw32.mac which is found in the CC3+ data directory (c:\ProgramData\ProFantasy\CC3Plus\ by default). CC3+ is pretty reliant on this file being intact, so we should always have a backup so we don’t need to risk a reinstall if we do something stupid. Also note that this file may be overwritten by program updates, so also keep a backup of your own changes once you have something interesting put in there.

There are two ways to edit this file, either from inside CC3+, or by using an external editor. The editor window inside CC3+ is small and cramped, so you may prefer an external editor, but you may find it simpler to just use the CC3+ editor for a quick change. If you wish to use an external editor, you should know that this file is just a plain text file and can be edited with any plain text editor, like notepad (I don’t recommend using a word processor like Microsoft Word or OpenOffice or similar though)

If you wish to edit this file from inside CC3+, just go to Tools -> Macros -> Edit Macros. When you are done editing, CC3+ will ask you to save it. If you wish to keep the changes, just keep the default name and location suggested in the Save macro definitions dialog and hit Save and confirm you wish to overwrite the existing file. Of course, if you don’t want to keep your changes, just hit Cancel instead. If you edit the file from inside CC3+, the changes will take effect immediately, while if you edited using an external editor, you have to reload the file, either by simply starting CC3+ anew, or by going to Tools -> Macros -> Load Macros.

Now, what you will find inside the macro file are lots of individual macros. Each of them starts with the line

MACRO macroname

and ends with the line

ENDM

followed by a blank line

Between those two lines are a series of commands, just as we looked at with the map open macro earlier. Do note that the use of the MACRO/ENDM lines is a system only used in this file, you won’t be using that in map load macros or drawing tool macros, but this file is a special file containing not just one macro, but a list of named macros.

Now, when editing this file, you can keep your macros at the top, the bottom, or anywhere else, just make sure to not place it inside of another macro. It is also important that your macros doesn’t have the same name as another macro. So, let us just finish this first article with a simple macro you can put into that file.

MACRO MYMARKER
COLOR 2
FSTYLE Solid
CIRR 2 ^DCentre;
ENDM

This is a simple macro, that when run by typing the command MYMARKER into the CC3+ command line will do the following:

  • Change the current color to red (Color number 2 in the palette)
  • Change the fill style to a solid colored fill
  • Draw a circle with a radius of 2 (It depends on the size of your open map how large/visible this is) which it asks you to place.

For example, a use for a macro like this in a simple/modern map style could be to draw preset city markers of different sizes, as an alternative to them being symbols.

Now, I think most of the lines above should be pretty self-explanatory when you read the macro line in combination with the description. But one thing may have caught your attention, the ^D in the CIRR command. In Macros, ^D is a way to tell CC3+ that instead of supplying a value for this parameter, we should ask the user. The ^D is immediately followed by the text we want to display on the command line, to indicate to the user what to do now. I could for example instead have made the command CIRR 2 10,10 which would have led to a circle always being drawn with the center at the coordinate 10,10, but that doesn’t sound very useful. Instead, we make a macro that ensures the circle always looks the same, but we let the user place it. There is also a more subtle thing going on with that line. You see, the CIRR command allows people to continue placing circle after circle until they manually end the command by right clicking or hitting escape. I decided I didn’t want that in my macro, I only wanted them to place one circle then end. The way I did that was adding a semicolon at the end. Note that this cannot be done blindly anywhere, and can cause weird results if you do, but here it is the correct way to stop the command from repeating. If you want to try the repeating version, just remove the semicolon.

A final word about blank lines in a macro. To CC3+, a blank line is interpreted as a request to repeat the last command, so blank lines should always be avoided. In the macro file, there are generally only two places you see blank lines. The first one is between each macro. After each ENDM line, there is a blank line before the next MACRO xxx line. And the very last line of the file is a blank line (This latter one also applies to all other places you add macros, like in the map load note or in drawing files, you always hit enter after the last line of text so you have a blank line at the bottom [but never more than one])

 

And with that, we finish this first introduction. I’ll come back with another article later that touches on more interesting things with macros, like variables and flow.

 

 

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.

Comments are closed.