How to Script - Revision history

ZUERCAT: /* Global Variables */

2025-11-08T08:34:42Z

Global Variables

← Older revision		Revision as of 03:34, 8 November 2025
Line 137:		Line 137:

	There are two major script commands for interacting with standard variables. The first is SETVARIABLE, which uses the syntax "SETVARIABLE ''<variable name without the %>'' ''<variable contents>''" such as "SETVARIABLE weapon sword". One thing to realize is that you can set a variable to nothing, by using "SETVARIABLE ''<variable name>''", which can be useful in some advanced scripting.		There are two major script commands for interacting with standard variables. The first is SETVARIABLE, which uses the syntax "SETVARIABLE ''<variable name without the %>'' ''<variable contents>''" such as "SETVARIABLE weapon sword". One thing to realize is that you can set a variable to nothing, by using "SETVARIABLE ''<variable name>''", which can be useful in some advanced scripting.

			To check all your current global variables, open the "scripts" window and at the bottom-left will be a "variables" button.

	The second way to interact with them is using DELETEVARIABLE, which does what you'd expect: it removes the variable and its contents.		The second way to interact with them is using DELETEVARIABLE, which does what you'd expect: it removes the variable and its contents.

SPICYDIAPSID: Updating FE name.

2022-02-03T00:21:08Z

Updating FE name.

← Older revision		Revision as of 19:21, 2 February 2022
Line 9:		Line 9:
	{{RTOC}}		{{RTOC}}

	This section will cover the most basic tools for scripting in the eScape and StormFront FEs.		This section will cover the most basic tools for scripting in the eScape and Wrayth (formerly StormFront) FEs.

	==Important Notes==		==Important Notes==
Line 76:		Line 76:
	MATCH has some quirks that can sometimes be exploited for specialized purposes, but at other times causes unexpected script behavior.		MATCH has some quirks that can sometimes be exploited for specialized purposes, but at other times causes unexpected script behavior.

	While MATCH is almost always used with a MATCHWAIT (and indeed the ~~StormFront~~ Scripting Reference describes MATCH only in terms of being followed by a MATCHWAIT), a MATCHWAIT is not actually required. Once a MATCH is defined, any occurrence of matched text will trigger the script to jump to the corresponding label. For this reason, a MATCH table should generally be placed only immediately before the command that is expected to produce text to be matched; if the MATCHes are active too early, they could coincidentally be triggered by text unrelated to their intended targets, such as if another character in the room manipulates an object with the same name as an object your script is meant to interact with. And when no MATCHWAIT is used, the MATCHes will continue searching and can be triggered as long as the script is still running.		While MATCH is almost always used with a MATCHWAIT (and indeed the Wrayth Scripting Reference describes MATCH only in terms of being followed by a MATCHWAIT), a MATCHWAIT is not actually required. Once a MATCH is defined, any occurrence of matched text will trigger the script to jump to the corresponding label. For this reason, a MATCH table should generally be placed only immediately before the command that is expected to produce text to be matched; if the MATCHes are active too early, they could coincidentally be triggered by text unrelated to their intended targets, such as if another character in the room manipulates an object with the same name as an object your script is meant to interact with. And when no MATCHWAIT is used, the MATCHes will continue searching and can be triggered as long as the script is still running.

	<pre>1 root:		<pre>1 root:
Line 191:		Line 191:
	4 ECHO the counter is %c</pre>		4 ECHO the counter is %c</pre>

	It should be noted that ~~StormFront~~ does not handle decimals at all, and they are simply truncated (rounded down to the nearest whole number).		It should be noted that Wrayth does not handle decimals at all, and they are simply truncated (rounded down to the nearest whole number).

	===Multiple Counters===		===Multiple Counters===
Line 322:		Line 322:
	This will match "blue ball bounces by", "green ball bounces by", or even "BlUE baLL bounces by".		This will match "blue ball bounces by", "green ball bounces by", or even "BlUE baLL bounces by".

	A list of additional regex syntax options can be found here: [https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx#character_classes] However, note that ~~StormFront~~'s implementation of regex is not inclusive of all syntax. For example, the only option flag permitted is i, for case insensitivity.		A list of additional regex syntax options can be found here: [https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx#character_classes] However, note that Wrayth's implementation of regex is not inclusive of all syntax. For example, the only option flag permitted is i, for case insensitivity.

	==Roundtime Handling==		==Roundtime Handling==
	~~StormFront~~, in general, will not proceed to the next action until the previous action's roundtime has ended. Other front ends do not share this function, and even in ~~StormFront~~ it is not always effective. Often, a script will quickly enter two consecutive game commands by way of PUT or MOVE script commands. The player may think nothing of chaining commands in this way, due to the claim that ~~StormFront~~ scripts automatically wait during roundtimes. But, in actuality, this can result in the second command being entered before the first command has been parsed. The second command is entered before the game has generated results for the first command, including any roundtime. Thus, at the instant that the script is ready to enter the second command, a fraction of a second after the first command is entered, it finds the game state to ''not'' be in a roundtime and enters that second command. If the first command causes a roundtime and the second command is one that cannot be done in roundtime, the game will be unable to carry out the second command, but this is already out of the script's control. In addition, even when a script is waiting for a roundtime to end as intended by the player, ~~StormFront~~'s timing is sometimes off; it is common for a script to enter a command with 1 second left on a roundtime, which can cause the rest of the script to become useless.		Wrayth, in general, will not proceed to the next action until the previous action's roundtime has ended. Other front ends do not share this function, and even in Wrayth it is not always effective. Often, a script will quickly enter two consecutive game commands by way of PUT or MOVE script commands. The player may think nothing of chaining commands in this way, due to the claim that Wrayth scripts automatically wait during roundtimes. But, in actuality, this can result in the second command being entered before the first command has been parsed. The second command is entered before the game has generated results for the first command, including any roundtime. Thus, at the instant that the script is ready to enter the second command, a fraction of a second after the first command is entered, it finds the game state to ''not'' be in a roundtime and enters that second command. If the first command causes a roundtime and the second command is one that cannot be done in roundtime, the game will be unable to carry out the second command, but this is already out of the script's control. In addition, even when a script is waiting for a roundtime to end as intended by the player, Wrayth's timing is sometimes off; it is common for a script to enter a command with 1 second left on a roundtime, which can cause the rest of the script to become useless.

	There are remedies to roundtime issues. One common solution is to catch failures by including a MATCH for "...wait" from the roundtime messaging; if the script inadvertently runs afoul of a roundtime, the MATCH can be used to direct the script to a label that will let it re-attempt the action. Alternatively, the line <pre>WAITFOR ROUNDTIME</pre> is very common in scripts. This isn't a special command; it's just a normal WAITFOR that is looking for the text "roundtime". If placed immediately after a command that results in a roundtime, this line forces the script to wait until the game's messaging for the previous command is complete, because the labeled roundtime is the last line printed. At that point, ~~StormFront~~ normally will correctly identify that the player character is in roundtime, and will not attempt to enter the next command until that roundtime finishes. To ensure it correctly times that last second, a simple PAUSE command can be included immediately before the next game command. (With no numerical argument, PAUSE defaults to one second.) Note that WAITFOR ROUNDTIME is unnecessary if the command is already followed by MATCHWAIT or a more specific WAITFOR, because these commands also force the script to wait for the game's messaging. In fact, they would interfere with each other; if WAITFOR ROUNDTIME comes first, it will prevent the script from finding any other target text that is part of the command's messaging, and if it comes second it will not find the roundtime for that action because it wouldn't start waiting until after the full messaging, including the roundtime, has already been output.		There are remedies to roundtime issues. One common solution is to catch failures by including a MATCH for "...wait" from the roundtime messaging; if the script inadvertently runs afoul of a roundtime, the MATCH can be used to direct the script to a label that will let it re-attempt the action. Alternatively, the line <pre>WAITFOR ROUNDTIME</pre> is very common in scripts. This isn't a special command; it's just a normal WAITFOR that is looking for the text "roundtime". If placed immediately after a command that results in a roundtime, this line forces the script to wait until the game's messaging for the previous command is complete, because the labeled roundtime is the last line printed. At that point, Wrayth normally will correctly identify that the player character is in roundtime, and will not attempt to enter the next command until that roundtime finishes. To ensure it correctly times that last second, a simple PAUSE command can be included immediately before the next game command. (With no numerical argument, PAUSE defaults to one second.) Note that WAITFOR ROUNDTIME is unnecessary if the command is already followed by MATCHWAIT or a more specific WAITFOR, because these commands also force the script to wait for the game's messaging. In fact, they would interfere with each other; if WAITFOR ROUNDTIME comes first, it will prevent the script from finding any other target text that is part of the command's messaging, and if it comes second it will not find the roundtime for that action because it wouldn't start waiting until after the full messaging, including the roundtime, has already been output.

DSETHK93: /* Regular Expressions */ Added known exception to standard syntax.

2020-08-20T09:40:16Z

Regular Expressions: Added known exception to standard syntax.

← Older revision		Revision as of 04:40, 20 August 2020
Line 294:		Line 294:

	==Regular Expressions==		==Regular Expressions==
	Both the MATCHRE and WAITFORRE functions support regular expressions, a way of setting conditions that can match several options. They are incredibly useful for keeping the amount of lines your code is down to a minimum.		Both the MATCHRE and WAITFORRE functions support regular expressions (regex), a way of setting conditions that can match several options. They are incredibly useful for keeping the amount of lines your code is down to a minimum.

	It functions exactly the same as a MATCH/WAITFOR, except that a pipe ( <code>\|</code> ) separates each of the regular expressions, and that it must start and end with forward slashes ( <code>/</code> ).		It functions exactly the same as a MATCH/WAITFOR, except that a pipe ( <code>\|</code> ) separates each of the regular expressions, and that it must start and end with forward slashes ( <code>/</code> ).
Line 322:		Line 322:
	This will match "blue ball bounces by", "green ball bounces by", or even "BlUE baLL bounces by".		This will match "blue ball bounces by", "green ball bounces by", or even "BlUE baLL bounces by".

	A list of additional regex syntax options can be found here: [https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx#character_classes]		A list of additional regex syntax options can be found here: [https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx#character_classes] However, note that StormFront's implementation of regex is not inclusive of all syntax. For example, the only option flag permitted is i, for case insensitivity.

	==Roundtime Handling==		==Roundtime Handling==

DSETHK93: /* Roundtime Handling */ Included more detailed information about causes, and additional solutions.

2020-08-20T09:35:54Z

Roundtime Handling: Included more detailed information about causes, and additional solutions.

← Older revision		Revision as of 04:35, 20 August 2020
Line 325:		Line 325:

	==Roundtime Handling==		==Roundtime Handling==
			StormFront, in general, will not proceed to the next action until the previous action's roundtime has ended. Other front ends do not share this function, and even in StormFront it is not always effective. Often, a script will quickly enter two consecutive game commands by way of PUT or MOVE script commands. The player may think nothing of chaining commands in this way, due to the claim that StormFront scripts automatically wait during roundtimes. But, in actuality, this can result in the second command being entered before the first command has been parsed. The second command is entered before the game has generated results for the first command, including any roundtime. Thus, at the instant that the script is ready to enter the second command, a fraction of a second after the first command is entered, it finds the game state to ''not'' be in a roundtime and enters that second command. If the first command causes a roundtime and the second command is one that cannot be done in roundtime, the game will be unable to carry out the second command, but this is already out of the script's control. In addition, even when a script is waiting for a roundtime to end as intended by the player, StormFront's timing is sometimes off; it is common for a script to enter a command with 1 second left on a roundtime, which can cause the rest of the script to become useless.
	StormFront, in general, will not proceed to the next action until the previous action's roundtime has ended. This is a function not shared by other front ends, but is not always effective.

			There are remedies to roundtime issues. One common solution is to catch failures by including a MATCH for "...wait" from the roundtime messaging; if the script inadvertently runs afoul of a roundtime, the MATCH can be used to direct the script to a label that will let it re-attempt the action. Alternatively, the line <pre>WAITFOR ROUNDTIME</pre> is very common in scripts. This isn't a special command; it's just a normal WAITFOR that is looking for the text "roundtime". If placed immediately after a command that results in a roundtime, this line forces the script to wait until the game's messaging for the previous command is complete, because the labeled roundtime is the last line printed. At that point, StormFront normally will correctly identify that the player character is in roundtime, and will not attempt to enter the next command until that roundtime finishes. To ensure it correctly times that last second, a simple PAUSE command can be included immediately before the next game command. (With no numerical argument, PAUSE defaults to one second.) Note that WAITFOR ROUNDTIME is unnecessary if the command is already followed by MATCHWAIT or a more specific WAITFOR, because these commands also force the script to wait for the game's messaging. In fact, they would interfere with each other; if WAITFOR ROUNDTIME comes first, it will prevent the script from finding any other target text that is part of the command's messaging, and if it comes second it will not find the roundtime for that action because it wouldn't start waiting until after the full messaging, including the roundtime, has already been output.
	Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

DSETHK93: /* Simple Commands */ Added GOTO, which is used but not explained.

2020-08-20T05:30:53Z

Simple Commands: Added GOTO, which is used but not explained.

← Older revision		Revision as of 00:30, 20 August 2020
Line 26:		Line 26:
	* WAITFOR ''<string>'': This will pause the script until it sees the string.		* WAITFOR ''<string>'': This will pause the script until it sees the string.
	* WAITFORRE ''<string>'': Same as WAITFOR but allows the use of Regular Expressions. See the advanced section for more details.		* WAITFORRE ''<string>'': Same as WAITFOR but allows the use of Regular Expressions. See the advanced section for more details.
			* GOTO ''<string>'': Instructs the script to jump to the line labeled with the string.
	* NEXTROOM: This will cause the script to wait until you enter a new room.		* NEXTROOM: This will cause the script to wait until you enter a new room.
	* PAUSE ''<#>'': This will pause the script for the indicated number of seconds.		* PAUSE ''<#>'': This will pause the script for the indicated number of seconds.

DSETHK93: /* Labels */ Added info about labels encountered during script execution.

2020-08-20T05:24:03Z

Labels: Added info about labels encountered during script execution.

← Older revision		Revision as of 00:24, 20 August 2020
Line 38:		Line 38:

	Labels are not case sensitive, so "Label" is the same as "label" is the same as "lAbEl". Labels cannot have spaces in them, or anything after the colon.		Labels are not case sensitive, so "Label" is the same as "label" is the same as "lAbEl". Labels cannot have spaces in them, or anything after the colon.

			Note that labels do not restrict the script or actually divide it into sections. If the script comes to a line with a label on it, it will continue to execute, regardless of whether or not it was explicitly sent to that label. If your intention is ''not'' that the script continue on through a label and to the next line, you need to include some code to prevent that, such as preceding the label with an EXIT command or a GOTO for a different label.

	==Pause and Wait==		==Pause and Wait==

DSETHK93: /* Matches */ Clarified acceptability of label reuse.

2020-08-20T05:17:52Z

Matches: Clarified acceptability of label reuse.

← Older revision		Revision as of 00:17, 20 August 2020
Line 61:		Line 61:
	The combination of lines one and two illustrate the most common use for for MATCH. If the game pops up "...wait x seconds" when you attempt a command, it will cycle back to the label on line one and attempt it again.		The combination of lines one and two illustrate the most common use for for MATCH. If the game pops up "...wait x seconds" when you attempt a command, it will cycle back to the label on line one and attempt it again.

	Lines 3-6 watch for the various outcomes of the command on 7, and will jump to the specified label upon detecting them. ~~The~~ ~~fact~~ that the label is the ~~same~~ ~~regardless~~ of the ~~outcome~~ is not ~~important~~ ~~since~~ ~~any~~ ~~number~~ of ~~labels~~ ~~can~~ be ~~mixed~~.		Lines 3-6 watch for the various outcomes of the command on 7, and will jump to the specified label upon detecting them. It is fine that multiple results use the same label, since the label exists independently of the MATCH table. For example, the instruction for a MATCH of "You" to go to the cycle label does not replace or alter the previous instruction that a MATCH of "Stow what?" should go to the same label.

	Lastly, line 8 is a special command that tells the script "wait here until a match is found". This can either be desirable, such as if you're waiting for the barge and don't want to do anything till it shows up, or can be undesirable, such as when your action produces a result you didn't put in a MATCH for and will wait forever.		Lastly, line 8 is a special command that tells the script "wait here until a match is found". This can either be desirable, such as if you're waiting for the barge and don't want to do anything till it shows up, or can be undesirable, such as when your action produces a result you didn't put in a MATCH for and will wait forever.

DSETHK93: /* Match Priority */ Added that line breaks interrupt MATCH priority.

2020-08-20T05:08:35Z

Match Priority: Added that line breaks interrupt MATCH priority.

← Older revision		Revision as of 00:08, 20 August 2020
Line 68:		Line 68:

	===Match Priority===		===Match Priority===
	It is important to understand how MATCH operates on text containing more than one MATCH string. The MATCH will be triggered by the first line containing at least one match string. But if the line contains more than one possible ~~match~~, the script assigns priority by the order in which the MATCHes are listed in the script itself--''not'' the order in which the strings appear in the triggering line. So MATCHes should be listed in order of importance.		It is important to understand how MATCH operates on text containing more than one MATCH string. The MATCH will be triggered by the first line containing at least one match string. But if the line contains more than one possible MATCH, the script assigns priority by the order in which the MATCHes are listed in the script itself--''not'' the order in which the strings appear in the triggering line. So MATCHes should be listed in order of importance. However, when game text contains line breaks, the script searches for all MATCHes up to the first line break, then for all MATCHes up to the second line break, and so forth. Once a MATCH is found, it can only be supplanted by a higher-priority MATCH if it occurs before the next line break.

	===MATCH Quirks===		===MATCH Quirks===

DSETHK93: /* MATCH Quirks */ Added information about these and other quirks.

2020-08-20T04:56:02Z

MATCH Quirks: Added information about these and other quirks.

← Older revision		Revision as of 23:56, 19 August 2020
Line 71:		Line 71:

	===MATCH Quirks===		===MATCH Quirks===
	MATCH has some ~~odd~~ quirks that can be ~~used~~ for specialized purposes. A ~~MATCH~~ ~~will keep looking for it's string until any MATCH is made. This is unimportant in the typical "MATCH table" such as the first example given above. But if no MATCHWAIT is used,~~ ~~the~~ ~~MATCHes~~ ~~will~~ ~~continue~~ ~~searching~~.		MATCH has some quirks that can sometimes be exploited for specialized purposes, but at other times causes unexpected script behavior.

			While MATCH is almost always used with a MATCHWAIT (and indeed the StormFront Scripting Reference describes MATCH only in terms of being followed by a MATCHWAIT), a MATCHWAIT is not actually required. Once a MATCH is defined, any occurrence of matched text will trigger the script to jump to the corresponding label. For this reason, a MATCH table should generally be placed only immediately before the command that is expected to produce text to be matched; if the MATCHes are active too early, they could coincidentally be triggered by text unrelated to their intended targets, such as if another character in the room manipulates an object with the same name as an object your script is meant to interact with. And when no MATCHWAIT is used, the MATCHes will continue searching and can be triggered as long as the script is still running.

	<pre>1 root:		<pre>1 root:
Line 85:		Line 87:
	</pre>		</pre>

	In the above example, since there is no MATCHWAIT it will punch, then kick, then head onto the retreat label. If somewhere down the line, "punches you" shows up, then it will ~~suddenly~~ divert to the run label, ~~which~~ ~~can~~ be ~~good~~ or ~~bad~~.		In the above example, since there is no MATCHWAIT it will punch, then kick, then head onto the retreat label. If somewhere down the line, "punches you" shows up, then it will divert to the run label; if this was not the player's intention, the script needs to be edited appropriately.

			Again, note that once any MATCH has been made, all previous MATCHes are removed. If the MATCHes are desired again later, they need to be written in the script again, or the script needs to execute from a label preceding the MATCHes.

		⚫	In addition, MATCHes will not occur on text that shows up during a PAUSE or a WAIT, but will during a MATCHWAIT. So if you need the script to PAUSE or WAIT in relation to a command used with a MATCH, it is best to include that after the MATCH's label, rather than immediately after a command that is expected to generate text containing MATCHes.
	Again, note that once any MATCH has been made, all previous MATCHes are removed.

			Further, after a MATCH occurs, any segment of text that the game output at the same time as the MATCHed text has already been scanned, even if it contained line breaks. As a result, if you want to MATCH with a string only when it occurs after some other string, in a single game output, you cannot do it by chaining MATCHES, i.e., by MATCHing the first string and then immediately trying to MATCH the second string; by the time the second MATCH starts, the output in which the first string was found can no longer be searched due to having already been searched for the first MATCH. Instead, try a regular expression (see below) containing both strings, with wildcards between them.
⚫	In addition, MATCHes will not occur on text that shows up during a PAUSE or a WAIT, but will during a MATCHWAIT. ~~This~~ ~~means~~ ~~including~~ PAUSE or WAIT ~~into~~ a MATCH ~~table~~ ~~will~~ ~~result~~ in ~~very~~ ~~odd~~ ~~behavior~~.

	==Variables==		==Variables==

DSETHK93: /* Match Order */ Clarified section.

2020-08-20T03:52:11Z

Match Order: Clarified section.

← Older revision		Revision as of 22:52, 19 August 2020
Line 67:		Line 67:
	MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.		MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

	===Match ~~Order~~===		===Match Priority===
	An important ~~thing~~ to understand ~~the~~ ~~order~~ in ~~which~~ text is ~~MATCHed.~~ It ~~can~~ be ~~thought~~ of as ~~being~~ a ~~first~~ ~~come~~ ~~first~~ ~~serve command. The~~ first line ~~with~~ a ~~MATCH~~ ~~result~~ to ~~come up triggers the MATCH~~. ~~However,~~ if a line contains ~~two~~ possible ~~MATCHes~~, ~~then~~ it ~~will~~ go by the order in which the MATCHes are listed in the script itself. ~~Therefor,~~ it is a ~~good~~ ~~idea~~ to ~~list~~ ~~them~~ in order of importance.		It is important to understand how MATCH operates on text containing more than one MATCH string. The MATCH will be triggered by the first line containing at least one match string. But if the line contains more than one possible match, the script assigns priority by the order in which the MATCHes are listed in the script itself--''not'' the order in which the strings appear in the triggering line. So MATCHes should be listed in order of importance.

	===MATCH Quirks===		===MATCH Quirks===