Macro


A macro is a technique that allows you to group together processes that are somewhat similar to each other.
All Utage macros must be entered on the sheet called Macro.

Basic Method for Writing a Macro

Sample

Macros are written on the Macro sheet. (If you do not have a sheet called Macro, then you need to create one.)
Similar to the scenario label, at the beginning of the macro you set “*Macro name” in the Command column.
At the end of the macro you set “EndMacro” in the Command column.

Macro definition in the Macro sheet

Call a Macro

You can call macros from any scenario sheet.
Enter “Macro name” in the Command column.
Macros are basically designed for creating a new command that combines multiple commands.

Sample

Using Arguments with Macros

With Arguments

Just like %Arg1, the setting “%column name” can be used as an argument when calling a macro.

How to Write a Macro

** How to Call a Macro**

In this macro sample:
・Arg1 is the name of the background to change to
・Arg2 is the fade color
・Arg3 is the fade-out time
・Arg4 is the wait time after the fade
・Arg5 is the fade-in time

For any sections that you are not using any %macro arguments, you can input the normal command format, so you can enter directly the values of “0.2,” “black,” etc.

Default Arguments

You can also set default arguments in macros.
Default arguments are set as individual values on each respective column of the macro name.
If you have set default arguments, these values are used if the macro is called with empty arguments.

How to Write a Macro

How to Call a Macro

In this macro sample:
・Arg1 is the name of the background to change to
・Arg2 is the fade color (the default is black)
・Arg3 is the fade-out time (the default is 0.2)
・Arg4 is the wait time after the fade (the default is 1)
・Arg5 is the fade-in time (the default is 0.2)

Arguments as Parameters

Macro arguments can also be used as variables of the Param command.

How to Write a Macro

How to Call a Macro

The macro argument symbol % and the remainder operator % can be used at the same time; however, when doing so we recommend enclosing them with ().
In addition, macro arguments do not have a type, so they are all handled as characters within the internal commands.
By using this, you can display parameter names easily.

Arguments in a Parameter Table

When using parameter tables, arguments can be assigned to each of the elements in “table name, key, parameter name.”

How to Write a Macro

How to Call a Macro

Entity (inside the macro, parameters are used as arguments for each command)

This is a special method for taking the strings and numerical values set in parameters and setting them as arguments for each command.
This functionality is used for when you want to change display characters dynamically but it would be too complex to process them using automatic branching.

How to Write an Entity

Write “&parameter name” inside the macro.

For example, this is a macro that displays the character set in the parameter name “entity_name”.

Difference Between Entity and Macro Arguments

When calling a macro, you always set fixed numerical values and characters as macro arguments inside a scenario.
On the other hand, with entities, because you use parameters as arguments, you can set dynamic numerical values and characters as macro arguments. This is the biggest difference between the two.

Important Notes on Entities

Entities are very useful as they allow you to change scenarios by using parameters; however, this can also be risky.
As they invalidate the checks performed when importing Utage scenarios, there is a risk that they may cause unstable behavior.
For example, if you pass a non-numeric parameter as a numeric command argument, this may cause a runtime error if it is an inappropriate value.
In other words, an error may occur depending on the values set in the parameters.
Please note that this functionality is only available in macros; it cannot be used with normal commands.

In addition, when doing an import, the initial values of parameter names are checked for errors, so please make sure that no inappropriate values are set as initial values of entity parameters.

Important Points on Macros

The general idea behind macros is to create new commands by combining multiple commands.
Unlike subroutines, the strong advantage of macros is their ability to take arguments and make changes.

Whereas subroutines call processes, macros are designed to embed commands beforehand.
Therefore, although already-read pages are determined individually, if you enter a scenario label inside a macro, you may end up with the same scenario label appearing here and there, causing a flaw in the execution.

Combine them with Subroutines