Not signed in (Sign In)

Vanilla 1.1.4 is a product of Lussumo. More Information: Documentation, Community Support.

Welcome Guest!
Want to take part in these discussions? If you have an account, sign in now.
If you don't have an account, apply for one now.
    •  
      CommentAuthorMonsen
    • CommentTimeApr 24th 2017 edited
     

    Index


    CC3+ contains a huge amount of various commands and features. In this series, I plan to highlight some of these. There won't be any special progression to this series, and the command will be selected from the entire range, from the simple basic commands, to more advanced features intended for the more advanced users. Feel free to use this topic to discuss the command presented. If you have a command you wish to have showcased, feel free to request it, and it may get presented.
    This series is called the command of the week, but it could also explain a feature or effect. The explanations will tend to explain the technical parts of the command, and is intended to highlight the basics (and complexities) of the command, but won't be a detailed tutorial on how to use it. It is up to you to use it creatively in your maps.

    Week 16 - Macros

    Most commands in CC3+ has a text-only equivalent, allowing you to type in the command and any parameters and coordinates directly on the command line instead of using your mouse, toolbars and menus. Not only does this make a lot of tasks a lot faster to accomplish, but it also means that we can create macros containing series of these commands, to automate frequent or difficult tasks.
    For this Command of the Week entry, I will highlight the bare basics of Macros and how to use them. For a more in-depth look at macros, I recommend having a look at the relevant chapters in the Tome of Ultimate Mapping, or the Macro issue of The Cartographers Annual vol 3. Also note that the map links we discussed in an earlier installment are also actually single-command macros.

    Where to find it

    Menu: Tools -> Macros
    Command Line: Enter the name of any macro to execute it

    How to use it

    Macros are a very large topic, so I won't go into detail on what you can put in a macro here. Instead, I'll construct a very simple macro, and have a look at various ways to use it. More advanced macros are used the exact same way as our simple macro here, and you will find examples of them in the sources mentioned above.

    Our example Macro

    FSTYLE waves
    LWIDTH 0
    COLOR 54
    BOX 10,10 100,100
    This is a very simple macro. What it does is to set a fill style (waves - used for the sake of example since any template will have this, but oviously you can use nicer fills), a line width (0 - ensuring a filled entity and not just an outline), a color (54 - blue) and then using the box command to draw a square starting at (10,10) and ending at (100,100). Depending on your map size, background color and current zoom, this may or may not be easy to see when drawn.
    This example is really simple, but shows how a macro is basically just a series of commands.

    Adding them to the CC3+ macro file

    CC3+ has a single macro file where all macros are stored. Technically, you can load in a different file than the standard one, but this is not recommended, since a lot of the functionality in CC3+ relies on these standard macros being present. Before we start working on this file, I recommend making a backup copy of the file @fcw32.mac, this is the CC3+ macro file.
    Before we add macros to this file, be aware that patches and updates may overwrite this file, so always keep a separate copy of your personal macros somewhere else so you can paste them back in after running an update.
    There are two ways to edit this file, either from within CC3+ itself, or through the use of an external text editor, like notepad. The file itself is a plain text file.

    Now, let us add our macro to this file. Activate the Tools -> Macros -> Edit Macros menu item. This will pop up a box with all the macros in it. You can add your macro anywhere in this file (like the top), just make sure to not add it in the middle of another macro.
    When adding a macro to this file, we need a bit of a framework. We need to start with telling CC3+ the name of our macro, and we need to tell CC3+ when the macro ends. So, for our example macro, add this to the file:
    MACRO DRAWBOX
    FSTYLE waves
    LWIDTH 0
    COLOR 54
    BOX 10,10 100,100
    ENDM
    After the ENDM (end Macro) line, leave one blank line before the next macro start. Scroll down in the file and see how the other macros does this if you are uncertain.
    Once you click OK, a save as box will appear. CC3+ will offer to save the file under it's existing name, fcw32.mac in the CC3+ data directory. This is fine, so just click Save, and confirm that you want to overwrite the existing file. (If you ever mess up this file, you may need to restore the backup you made)

    Now, simply type DRAWBOX and hit enter on the command line in CC3+, and your macro should be run. You can try to change some properties beforehand, like fill style and color to make sure the macro work as intended.
    After adding your macro to the macro file, you can also call it from other places in CC3, such as assigning the command to a toolbar button or menu item. The Tome and the helpfiles have more information on editing menu items.

    Using it in a script file

    A script file is a macro contained in a separate file that must be loaded each time you wish to run the command. This is great for complex commands that you rarely need, but for commands you often use, you should add them to the macro file instead.
    To create a script file, simply create a new blank file in a text editor and insert the macro commands (The ones from our example macro above, NOT including the additional MACRO/ENDM commands we used in the CC3+ macro file). Then save this file with a .scr extension. Make sure the file is saved as a plain text file, and if you have file extensions hidden by default in windows, be aware that it will probably add a hidden .txt extension at the end, making it file.scr.txt, which is NOT what you want. Also note that some version of windows treats the .scr extension as a screensaver executable, so you can't simply double click on it to open it.
    Note the last line of the script file should be a blank line, but do NOT add additional blank lines. A blank line causes the previous command (but without the parameters) to be repeated, much the same as when you click the left mouse button inside the drawing windows in CC3+ without picking a new command.
    Once you have saved your macro as a script file, you can run it from within CC3+ by going to Tools -> Macros -> Script file and simply browse to your desired file. It will be run immediately upon loading it (and if you wish to run it again, you need to load it again)

    Adding it to a hotspot

    The most common usage of hotspots are to link to maps and files, but a hotspot can contain a complete macro.
    Simply go to Tools -> Macros - Make Hotspot; In the dialog that pops up, add the macro command (again, just the commands, NOT the MACRO/END lines from the macro file), click ok, and define the hotspot area. You now have a clickable area in your map which will execute the macro. Note that the hotspot window will be shown using a visual rectangle for now, but it will be gone the next time you start CC3+ and load the map. You can also toggle the visibility from View -> Show/Hide Hyperlinks. (Se the Link with map entry of this series for more on hyperlinks)

    Adding it to a drawing tool

    You can also create drawing tools that contain macros. For example, the forest drawing tools typically work by letting you draw a polygon, and then use a macro command to call the fil with symbols command on the polygon you just drew. A drawing tool can also execute a macro directly, without you drawing anything manually.
    To add your macro to a drawing tool, click the All Drawing Tools button, and hit Advanced. Now, create yourself a new drawing tool with whatever name you choose, and enable the 'Use Macro Command' option for this tool. Click the Command to execute button, and add our macro commands in this edit box. Click OK to close it, save your new tool, and close the window. Whenever we activate this tool, it will draw our square. Obviously, since we have the coordinates hard-coded, it will still draw it in the same position as before. If we made the macro a bit more advanced, we could have it ask the user to click a spot first, and place the rectangle there. This is probably a bit more in line for how we expect our drawing tools to work, but I won't go into these changes here.

    Final Notes

    There are a lot more to macros than just being a series of CC3+ commands. There are variables and branching logic, ensuring that macros can do complex tasks depending on situation and user choice. All of this is documented in the sources mentioned earlier. This installment only touches the very surface of the topic to get you started.
    Also note that only commands that accept all their inputs on the command line can be used in macros. A command that pops up a dialog box cannot be automated using a macro. Do note that there are often text-only versions of many regular commands. For example, the FRX (Fractalize) command pops up a dialog and is thus unsuited for use in a macro, but there also exists a text-only equivalent, FRXM that is macro-friendly. Look for the macro-friendly versions of the commands.
    • CommentAuthorRoyalWolf
    • CommentTimeApr 25th 2017
     
    just curious, does anyone here use macros in their maps? if so, what sorts of things do you use them for? I am struggling to figure out what I might apply it to
    •  
      CommentAuthorQuenten
    • CommentTimeApr 25th 2017
     
    I use a macro called mtns, which is also good for drawing cliffs. Also one called star, which draws precise stars with a given number of arms, and a given size - very useful. Happy to share if you want. They were made by someone else (don't know whom) but were free for public use (not resale).
    •  
      CommentAuthorMonsen
    • CommentTimeApr 25th 2017
     
    If you look at the maps for the community atlas project, they contain simple macros for opening the map notes, showing/hide the grid, enabling/disabling effects and showing/hiding visible hotspot markers.
    More advanced macros can draw city walls, rivers, cliffs and more.
    •  
      CommentAuthorDogtag
    • CommentTimeApr 25th 2017 edited
     
    For another very accessible and newbie-friendly resource, you might want to check out Joachim de Ravenbel's awesome macro tutorials. Be aware his site is bi-lingual (French and English) so it might throw you off at first, but the English content and links are there.
    • CommentAuthorHadrianVI
    • CommentTimeApr 28th 2017
     
    What language do macros use?
    •  
      CommentAuthorQuenten
    • CommentTimeApr 28th 2017
     
    Arcane! :D
    •  
      CommentAuthorDogtag
    • CommentTimeApr 28th 2017 edited
     
    I don't know much about macros, so someone more knowledgeable than I may correct me here. It appears to just be a simple, mostly-proprietary, macro language. Possibly tied to FastCAD? CC3 macros are mostly a series of CC3 commands. There are commands to get/set variables and to get/display values to the user but they're limited. The control structures, such as For...Next loops appear to be constructed rather than actually part of the language. That is, you initialize a variable to a negative value, label the start of a loop, increment the variable, then check if the variable is zero and, if not, GO to (goto) the label.

    It reminds me a lot of DOS batch files, but I think even they might have more [control] commands.

    Cheers,
    ~Dogtag
    •  
      CommentAuthorMonsen
    • CommentTimeApr 28th 2017 edited
     
    FastCAD macro syntax. I don't think it has a separate name.

    Edit: Ninja'ed :)
    •  
      CommentAuthorQuenten
    • CommentTimeApr 28th 2017
     
    It's a front for the Illuminati, Hadrian. Don't be fooled by their tech talk