Tag Archives: hook

***Labels***

In my “Defusing” series I’ve mentioned a ManiaScript technique called “Labels” which might be confusing for many developers because of its uniqueness.
Actually I myself needed some time as well in order to fully get the point of it.

A code example:

Void LogSomething() {
declare Message = "Hello World!";
+++BeforeLog+++
log(Message);
}

***BeforeLog***
***
Message ^= " It's me!";
***

Log:
Hello World! It’s me!

So what’s happening there and what do all the plusses and stars mean?

You can declare Labels between your usual statements by writing: +++LabelName+++
TGYoshi describes these declarations as “hooks” which fits pretty well.

Only declaring a label doesn’t do anything unless you actually implement it.

That’s done by writing:

***LabelName***
***
// Your code
***

So you start the implementation block by surrounding the label’s name with 3 *. Directly following is the actual implementation (code) which is surrounded by 3 * as well.

Now whenever a label-“hook” is found inside your coding the implementation of the label will be executed.
Imagine it just as if the code of the implementation is copy-pasted to the location of the declaration (hook).

In the code example the label “+++BeforeLog+++” manipulates the “Message” logged by the function “LogSomething()”.

Let me point out some things that are important to know regarding this technique:

  • Labels aren’t functions/callbacks: You can’t directly pass them parameters.
  • Labels Implementations don’t have an own scope:
    => Variables visible where the label is declared are also visible inside the label’s implementation.
    => Variables declared inside the label’s implementation are also visible afterwards outside of the implementation.
  • You can declare the same label multiple times in your script in order to execute it at different locations in your code.
  • If you implement a label that hasn’t been declared your script is still valid but your label implementation won’t be executed.
  • If you implement the same label twice (or more often) all implementations will be executed at every declaration (“hook”).
  • If another script is extending yours it will have access to all the labels declared in your script (#Extend directive).
  • Using “-” instead of “+” for the label declaration (---LabelName---) will reduce the execution of implementations to the most derived one, other implementations will be ignored.
  • (The ManiaScript compiler has an error(?): You will need to add at least one function declaration below your last label implementation, otherwise a syntax error occurs.)

Nadeo is widely using labels for their ShootMania game modes.
The “ModeBase” script (included in the game’s files) declares many different labels which mark specific moments during the execution of game modes.
If you want to build your own game mode you can extend the ModeBase and use these labels in order to execute your own code for example as soon as the script started or when a map has been loaded.

Another example is the “ModeSport” script which is extended by the game modes Elite and Heroes. It’s offering the basic round-based game play used for the modes (among other things). Additionally the ModeSport script itself is extending the ModeBase script so you can find an even deeper chain of extending scripts.

The using of labels and the extending of scripts reduces the amount of code that has to be written and improves the clarity of scripts because the code of the base script can be used for several other scripts. It can be compared to object-oriented class hierarchies.

Please don’t hesitate to comment in case you have any questions regarding Labels.

Regards,
steeffeen