onCampaignLoad: Difference between revisions

Latest revision as of 23:59, 16 February 2024

Languages: English • 日本語

onCampaignLoad Macro

• Introduced in version 1.3b51

A special macro that can be created on library tokens to have macro code automatically execute when a campaign is loaded. A campaign is considered to have been loaded if it is opened via the File menu, or upon connecting to a server running that campaign. All output from an onCampaignLoad macro is discarded, when it is executed automatically.

This special macro is ideally suited for loading your User Defined Functions (UDFs) via defineFunction().

When an onCampaignLoad macro is executed automatically, it is considered a Trusted Macro. If you wish to use trusted functions within onCampaignLoad and execute it manually (e.g. while developing macros), you will have to make sure that it follows all of the rules of Trusted Macros.

How to Create an onCampaignLoad Macro

You can create an onCampaignLoad macro on any library token; simply create a macro that is specifically named onCampaignLoad.

The library token must have "Owner: All Players" unchecked, otherwise onCampaignLoad is not executed. To avoid permission issues with called functions, the onCampaignLoad macro should have "Options: Allow Players to Edit Macro" unchecked.

Limitations

Do not make changes within the onCampaignLoad macro to the library token it resides upon. This is not supported by MapTool. A duplicate lib token can/will appear and this will/can break stuff.
Some macro functions may not work as expected if run in onCampaignLoad without deferring their execution by using the defer option of execLink().
- goto(), setZoom() and similar function calls should be placed in a separate macro to be called via execLink()

Example of Deferred Function Calls

Inside the onCampaignLoad macro place code like this:

[h: link = macroLinkText("deferredCalls@"+getMacroLocation())]
[h: execLink(link,1)]

And in the deferredCalls() macro place the functions to be deferred.

[h: goto("2")]
[h: setZoom(2)]

@@ Line 1: / Line 1: @@
+{{Languages|onCampaignLoad}}
 ==onCampaignLoad Macro==
 '''• Introduced in version 1.3b51'''
-A special macro that can be created on library tokens to have macro code automatically execute when a campaign is loaded. A campaign is considered to have been loaded if it is opened via the File menu, or upon connecting to a server running that campaign. All output from onCampaignLoad is discarded, when it is executed automatically. This special macro is ideally suited for loading your defined functions via [[defineFunction|defineFunction()]].
+A special macro that can be created on [[Library_Token|library tokens]] to have macro code automatically execute when a campaign is loaded. A campaign is considered to have been loaded if it is opened via the File menu, or upon connecting to a server running that campaign. All output from an {{code|onCampaignLoad}} macro is discarded, when it is executed automatically.
-When onCampaignLoad is executed automatically, it is considered a [[Trusted Macro]]. If you wish to use trusted functions within onCampaignLoad and execute it manually (e.g. while developing macros), you will have to make sure that it follows all of the rules of [[Trusted Macro]]s.
+This special macro is ideally suited for loading your User Defined Functions (UDFs) via [[defineFunction|defineFunction()]].
+When an onCampaignLoad macro is executed automatically, it is considered a [[Trusted Macro]]. If you wish to use trusted functions within {{code|onCampaignLoad}} and execute it manually (e.g. while developing macros), you will have to make sure that it follows all of the rules of [[Trusted Macro]]s.
 ===How to Create an onCampaignLoad Macro===
-You can create an onCampaignLoad macro on any library token; simply create a macro that is specifically named {{code|onCampaignLoad}}
+You can create an {{code|onCampaignLoad}} macro on any [[Library_Token|library token]]; simply create a macro that is specifically named {{code|onCampaignLoad}}.
+The library token must have "Owner: All Players" unchecked, otherwise {{code|onCampaignLoad}} is not executed. To avoid permission issues with called functions, the {{code|onCampaignLoad}} macro should have "Options: Allow Players to Edit Macro" unchecked.
+===Limitations===
+* Do not make changes within the {{code|onCampaignLoad}} macro to the library token it resides upon. This is not supported by MapTool. A duplicate lib token can/will appear and this will/can break stuff.
+* Some macro functions may not work as expected if run in {{code|onCampaignLoad}} without deferring their execution by using the defer option of [[execLink|execLink()]].
+** [[goto|goto()]], [[setZoom|setZoom()]] and similar function calls should be placed in a separate macro to be called via [[execLink|execLink()]]
+===Example of Deferred Function Calls===
+Inside the {{code|onCampaignLoad}} macro place code like this:
+<syntaxhighlight lang="mtmacro" line>
+[h: link = macroLinkText("deferredCalls@"+getMacroLocation())]
+[h: execLink(link,1)]
+</syntaxhighlight>
+And in the deferredCalls() macro place the functions to be deferred.
+<syntaxhighlight lang="mtmacro" line>
+[h: goto("2")]
+[h: setZoom(2)]
+</syntaxhighlight>
-[[Category:Special Macro]]
+[[Category:Special Macro]][[Category:Event]]
+[[Category:Macro Function]]