WML for Complete Beginners: Chapter 9

English

Index
Introduction
1 - Syntax
2 - The Userdata Directory and the Campaign Folder
3 - The _main.cfg
4 - Creating Your First Scenario
5 - Events
6 - Custom Units
7 - Variables Introduction
8 - Non-scalar Variables
9 - Macros
10 - Logic
11 - More Logic
Conclusion

Chapter 9: Macros

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
    name=start
    [message]
        speaker=Leader
        message= _ "What do you think our plan should be, Stooge?"
    [/message]
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
    [message]
        speaker=Leader
        message= _ "I said, what do you think our battle plan should be?"
    [/message]
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
    [message]
        speaker=Leader
        message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
    [/message]
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
    [message]
        speaker=Leader
        message= _ "Grrr..."
    [/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write

    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]

three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

The Parts of a Macro

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

The Macro Preprocessor Directives

The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

The Macro Symbol

The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:

STOOGE_REPLY

The Macro Body

The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:

    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]

Calling A Macro

Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:

    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]

with the following line:

{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:

{STOOGE_REPLY}

it should substitute the following code in place of that line:

    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]

Macro Arguments

Navigation
Chapter 8 Non-scalar Variables	WML for Complete Beginners: Chapter 9	Chapter 10 Logic