Advanced Techniques

In TyranoScript, you can create reusable blocks of code—like a library—for processes you want to use repeatedly.
This is where Subroutines and Macros come in. These two features both call reusable, grouped functionality, but they differ in how and when they’re used.

■ Typical Use Cases for Subroutines
・When a scenario branches significantly, you can split it into different scenario files and use a subroutine to switch between them.

■ Typical Use Cases for Macros
・When you have script code that’s reused often, defining it as a macro allows you to reuse it just by calling a tag.

Sound a bit abstract? Let’s look at concrete usage examples to make it clearer.

【Important】
Tags like [jump], [button], and [link] can also be used to move between scenario files or labels. However, there's a big difference compared to subroutines and macros.
With subroutines and macros, control returns to the original caller after execution. But with [jump], [button], or [link], the script does not return to the caller.

Subroutines are called using the [call] tag. To return from a subroutine to the calling point, use the [return] tag.

[wait time=200]

*start

[cm]


Calling the subroutine...[l][r]


[call target=*subroutine]


The subroutine has been called.


[s]


*subroutine


This is the subroutine.[l][r]


Click to return to the caller.[l][r]


[return]

As shown above, you can call a subroutine from a label.
If you want to call a subroutine from a different file, specify the file name using the `storage` attribute.

A macro is a function that allows you to group certain operations together and call them with a single tag.
In other words, it's a powerful feature that lets you freely define new tags by combining existing tags and text.
If you turn frequently used tags into macros, you can reuse them when creating other games—so feel free to macro things as much as possible!

Once a macro is defined, it can be used from anywhere.
Because of that, it must be executed when the game launches, so it’s recommended to write it at the beginning of first.ks.


Let’s look at an example.
When progressing through a scenario, you often use the tags [l] and [r] together to wait for a click.
But typing both tags each time is a hassle, so let’s define a macro to combine them into one tag like this:

; -- Define the macro --
[macro name=lr]


    [l][r]



[endmacro]

; Call the macro


Test test[lr]


This is also a test[lr]

In TyranoScript, you can pass custom values when calling a defined macro.
See the example below:

; -- Define the macro --


[macro name=newtag]


    [font color=%iro]


    This text will appear in the specified color


    [resetfont]


[endmacro]





; -- Use the macro --


[newtag iro=0x00ff00]

In this example, we call the defined tag [newtag] and pass a value through the attribute "iro".
On the receiving side, the value is accessed by using %iro.

Additionally, if you use an asterisk * inside a macro’s attribute, it will pass along all the attributes given to the macro.
For example, if you want to create a macro that includes a trans tag followed by a wt tag:

[macro name=transwait]


    [trans *]


    [wt]


[endmacro]

With this setup, all the attributes passed to the transwait macro will be applied to the trans tag.



Furthermore, if a value is omitted, you can specify a default by adding a pipe | after the attribute name in the macro definition.

[macro name=newtag]


    [font color=%color|0xff0000]


    This is how you create a macro with a default value


    [resetfont]


[endmacro]

In this case, if the macro call doesn’t include the "color" attribute, the value after the pipe symbol (|) will be used as the default.


Also, attributes passed into a macro can be used as variables. Check the example below:

[macro name="test"]
    The value passed to the macro is “[emb exp="mp.your_name"]”.
[endmacro]

;Calling the macro


[test your_name="Shikemoku"]

When executed, this code will display:
The value passed to the macro is “Shikemoku”.

Inside macros, you can use mp.your_name as a local variable.
Keep in mind that this variable is only valid inside the macro.

How was that? With smart use of macros, you can significantly ease the game development process.
Also, TyranoScript is always looking for macro submissions from users! Let’s share and improve the development environment together.