Elanthipedia - User contributions [en]

Talk:Scout ogre

2021-05-06T00:55:34Z

DSETHK93: Added section and response about spawning locations.

==Manipulate Friendship==
Able to be manipulated at 617 Empathy. Did not learn. [[User:HERALD42|HERALD42]] ([[User talk:HERALD42|talk]]) 08:31, 11 August 2015 (CDT)

==Spawning Locations==
I could not find these neither out Riverhaven's nor Crossing's west gates in the TEST instance. After several minutes, I had only seen dozens of [[young ogre]]s. Maybe the Scout Ogres don't spawn in these areas anymore? [[User:TRAIGA|TRAIGA]] ([[User talk:TRAIGA|talk]]) 00:38, 9 March 2021 (CST)
:In the main instance, I encountered them in the [[RanikMap5|Rocky Outcrop]] west of Crossing. This was in the area where the map says "Young Ogres/Blood Wolves." I've only been hunting there recently, maybe a week or two, and just a few minutes ago was the first time I saw a scout ogre there. I managed to kill one, and then two more entered, so I made my exit. I'm not quite up to taking on a group of them, but at least they didn't eviscerate me like a dire bear does. Anyway, I was just surprised because I still haven't seen any young ogres, which are on the map, and then here were these more difficult scout ogres, that aren't on the map. But they're there in the game. --[[User:DSETHK93|DSETHK93]] ([[User talk:DSETHK93|talk]]) 19:55, 5 May 2021 (CDT)

Talk:Zone map

2021-03-03T05:48:46Z

DSETHK93: /* Visual Representation */ new section

== Maps Still Needing Zone Placement ==

These maps still need placement in their appropriate zone(s). They are typically maps that are near zone borders and simply need someone to go through in game and verify which zone the majority of the map belongs to. 
If a map is predominantly made up of one zone, with a smattering of non-landmark rooms from another zone, just include it in the first zone. 
If a map contains large portions made up two zones, include it in both zones with the qualifier 'Portions of' in front of it. This is also the approach to take if only a smattering of rooms belong to one zone, but they make up a landmark area.
:* [[RanikMap3 | Map 3 ]] - Outside the West Gate + Lake of Dreams
:* [[RanikMap3a | Map 3a ]] - Temple Hill Housing Area
:* [[RanikMap4 | Map 4 ]] - Goblins + The Hunting Preserve
:* [[RanikMap11 | Map 11 ]] - NTR, including Vipers + Rock Guardians
:* [[RanikMap11a | Map 11a ]] - Leucros and Vipers
:* [[RanikMap12 | Map 12 ]] - More NTR + Reavers
:* [[RanikMap12a | Map 12a ]] - Dense Copse + Temple
:* [[RanikMap13a | Map 13a ]] - North Roads Caravansary
:* [[RanikMap14 | Map 14 ]] - Blue-Belly Crocodile Area, Homes, a few other things
:* [[RanikMap14a | Map 14a ]] - Gate of Souls
:* [[RanikMap14b | Map 14b ]] - Greater Fist
:* [[RanikMap14c | Map 14c ]] - Swim to Haven!
:* [[RanikMap31c | Map 31c ]] - Pejek Bog
:* [[RanikMap31e | Map 31e ]] - Abandoned Castle
:* [[RanikMap33 | Map 33 ]] - Road to Theren
:* [[RanikMap34d | Map 34d ]] - Forest Gryphons
:* [[RanikMap60b | Map 60b ]] - River Sprites and Segoltha River
:* [[RanikMap61a | Map 61a ]] - Boggy Marsh of Leth, Moss Meys
:* [[RanikMap61c | Map 61c ]] - Treehopper Toads
:* [[RanikMap70 | Map 70 ]] - Outside the West gate of Shard
:* [[RanikMap70a | Map 70a ]] - Crystal Forest housing area
:* [[RanikMap128a | Map 128a ]] - Liirewsag River

== Rakash Village and Road to Rakash Village ==

The placement of these two zones (MM and NN) are currently just a logical guess based on nearby locations and various Locate-shift capabilities. Confirmation of their exact locations would be appreciated as I am currently unable to do so myself.--[[User:Evran|Evran]] 18:30, 28 September 2010 (UTC)
:Done--[[User:Evran|Evran]] 20:01, 1 December 2010 (UTC)

== Questions on the Map and Formulas ==

I'm very new to the guild, so I'm not yet comfortable with what the ranges should be; however, I know that something is wrong. On the page, it shows that I need a minimum of about 241 PM to go 2 zones on mainland with 80 mana in a moongate. I have 111 PM. I dropped a beam at the NE gate of Crossing (solidly in P) and opened a moongate from the south dock of the Haven ferry using 35 held mana. Because that location is not directly listed, I wanted to make sure I was solidly two zones away, so I went to Riverhaven. I was able to, at 111 PM, open a moongate to Crossing with 50 mana. The data on the page indicates I shouldn't be able to do it with any less than 241 PM at 80 mana. I think something is off on the page. --[[User:Aristrondr|Aristrondr]] 04:04, 1 December 2010 (UTC)

Also just confirmed range with opening a gate from Throne City to Crossing at 111 PM using about 45 mana. --[[User:Aristrondr|Aristrondr]] 04:47, 1 December 2010 (UTC)
:All those formulae I reconstructed from memory of output from the [[Coordinate Chart]] since I currently don't have access to the coordinate chart. I do remember at low ranks there was a certain minimum distance that kicked in regardless of skill, and I had placed that at a distance of 1. Its entirely possible that's a distance of >2 when the formula applies instead of the >=2 that I have listed. I also might have the whole mainland scale off by 100 ranks... When I'm able to actually run the coordinate program, I'll confirm them. Let me know what ranges you can get once you hit 141 ranks? That would let me know if I've got that off by 100 ranks or not.--[[User:Evran|Evran]] 19:59, 1 December 2010 (UTC)
::Okay, that should be fixed now. I had the both the distance modifiers and constant off by a bit so that the island to mainland values were correct, but the mainland numbers were wrong. Let me know if you find any more inconsistancies. --[[User:Evran|Evran]] 21:21, 1 December 2010 (UTC)

== Visual Representation ==

The visual representation of the distance calculation is very nicely done. But it only goes up to distances of 10, while it appears that zone 00 (Fang Cove) is further than that from zones A (Muspar'i) and B. I calculate those distances at 12 and 11, respectively; it's 9 up and 9 or 7 over: 9^2 + 9^2 = 162 > 12^2, 9^2 + 7^2 = 130 > 11^2. I don't believe any other distances greater than 10 exist between any zones containing locations. Does the game in fact treat these zones as having those greater distances between them? Or does it use some other mechanic, such as defaulting them to 10, or asserting that their distance is too great for any mechanic that relies on distance? --[[User:DSETHK93|DSETHK93]] ([[User talk:DSETHK93|talk]]) 23:48, 2 March 2021 (CST)

Pathway of Damage

2020-11-23T08:25:07Z

DSETHK93: Added messaging.

{{GuildAbility
|name=Damage
|guild=warrior mage
|prereqs=4th Circle, Quest
|slots=-
|diff=-
|type=pathway
|contest1=-
|contest2=-
|skill=Summoning
|path=Fire
|desc=By manipulating this pathway into your targeting matrices, it will allow you to increase the damage capacity of your targeted spells.
|buffs=No buffs
|debuffs=No debuffs
|dtype=No damage
|htype=No heal
|effect=Increase damage of TM spells
|messaging=You focus on manipulating an aethereal pathway to enhance the damage of your targeted spells.

You continue to discharge power, carving a favorable pathway into the aethereal landscape.
}}
==Notes==
"This one is fairly straightforward. It provides a damage boost to TM spells if they hit the target. The reasoning behind Pathway Focus Damage (PF Damage) being the first ability of AP is that we'd like to help the younger folk in learning TM. A boost to TM damage should help add some experience to the TM pool and hopefully make it a bit easier to learn the skill. The best is wreaking more havoc upon your enemies by adding some extra oompf to you spells." -GM [[Chakram]]

Talk:RanikMap1

2020-09-15T06:37:59Z

DSETHK93: /* Map info to be fixed or added */

See [[Talk:RanikMap1/Archives]] for archived discussions.

== Map info to be fixed or added==
* Access to swim the Segoltha River (to Leth) can be found in the room West from the Sand Spit Tavern.
* Alchemy Society building is 1 East from the Engineering Society
* Enchanting Society building is up by the Paladin Guild (confirm 2 or 3 rooms South)
* Meeting Hall building is near the Barbarian Guild (confirm 1 or 2 rooms West)
* That "E" under the Oxenwaithe Bridge is difficult to notice in white against the river (just north of pawn shop); to my eye, it looks like "go bridge" is provided as a bidirectional movement command. Maybe the box to the right of the bridge could be moved further right, leaving space for "E" in normal font against white background? --[[User:DSETHK93|DSETHK93]] ([[User talk:DSETHK93|talk]]) 01:37, 15 September 2020 (CDT)

Primary Magic skill

2020-08-24T14:44:35Z

DSETHK93: Significant rewrite, explaining formulas and impact of PM on casting.

{{UpdateDR3|Article needs development, correction}}
The '''Primary Magic [[page type is::skill]]''' (also known as '''PM''' or simply '''Primary''') is a [[magic skillset|magic skill]] that partly determines how many mana streams you can put into a [[Spells|spell]] without backfiring, when casting any [[:Category:Analogous_Patterns_Spellbook|Analogous Patterns spell]] or a spell of your [[:Category:Magic Types|magic type]]. Ironically, the Primary Magic skill is of secondary importance, compared to the specific magic skills ({{skill|Augmentation}}, {{skill|Debilitation}}, {{skill|Targeted Magic}}, {{skill|Utility}}, and {{skill|Warding}}); the effective casting level is a weighted average of Primary Magic and the specific magic skill, with Primary Magic counting only one-fourth as much as the specific skill (see formulas, below). For most magic users, Primary Magic effectively provides a small bonus to the specific magic skills.
Primary Magic is replaced by {{skill|Sorcery}} when casting [[:Category:Sorcerous Magic|Sorcery]] or a spell not of your magic type.

Your magic type and the corresponding name of your Primary Magic skill is different depending on your [[guild]].

{|class="wikitable sortable"
|-
!Guild!!Skill Name!![[Mana]] Type
|-
|[[Barbarian]]||Inner Fire skill||None
|-
|[[Bard]]||Elemental Magic skill||Elemental
|-
|[[Cleric]]||Holy Magic skill||Holy
|-
|[[Empath]]||Life Magic skill||Life
|-
|[[Moon Mage]]||Lunar Magic skill||Lunar
|-
|[[Necromancer]]||Arcane Magic skill||Necromatic
|-
|[[Paladin]]||Holy Magic skill||Holy
|-
|[[Ranger]]||Life Magic skill||Life
|-
|[[Thief]]||Inner Magic skill||None
|-
|[[Trader]]||Lunar Magic skill||Lunar
|-
|[[Warrior Mage]]||Elemental Magic skil|||Elemental
|}

Outside teaching issues, the skill works the same for all guilds.

==Spells and abilities that boost Primary Magic==
{{#ask:[[Boosts::Primary Magic skill]]
|?guild association is
|format=ul
|headers=hide
|default=None
}}

==Spells and abilities that decrease Primary Magic==
{{#ask:[[Debuffs::Primary Magic skill]]
|?guild association is
|format=ul
|headers=hide
|default=None
}}

==Teaching==
Attempting to teach someone using a different form of skill, such as a Lunar Magic caster teaching an Elemental Magic user, will result instead in the learning of the [[Sorcery skill]]. Teaching within mana types will teach the skill, even if the teacher and student are different guilds, such as a Bard teaching a Warrior Mage.

Magic users cannot teach this skill to non-magic users.

==Training==
In general, PM is learned best from casting higher tier (thus more difficult) spells without full preparation, especially when straining your ability (i.e. near backfiring).

==Casting Formula==
Reverse engineering has been performed on years of game data and determined that there are two formulas in place for this mastery skill. In these formulas, the Primary Magic skill is represented by "PM," and the applicable specific magic skill is represented by "SMS." These are base formulas, and do not account for any bonuses the character may have in effect, such as from feats or from other spells. Note that every spell falls into at least one of the specific magic skill categories; most use exactly one, but for any spell that uses more than one the caster's effective level will be calculated using the skill in which they have the fewest ranks, to reflect that competence in all specific magic skills is required to cast that spell. Casting will teach mainly that SMS, with a modicum of experience for any other SMS used by the spell.

Normally, the formula for your effective casting ranks is (PM+(SMS*4))/5, which can also be written as 0.2*PM + 0.8*SMS. It can also be described as 20% of your Primary Magic plus 80% of your specific magic skill, or a weighted average with the specific magic skill counting four times as much. However, effective casting ranks are capped at 130% of your Primary Magic skill; in the event that your specific magic skill is greater than 1.38 times your PM, which using the default formula would produce values great than 130% of PM, the effective casting ranks are instead just set equal to PM*1.3.

Most magic users will have at least as many ranks in PM as in their highest specific magic skill, because training a specific skill usually also trains PM. So PM will normally provide a small boost to a specific magic skill when casting. In particular, since even magic primary guilds can advance indefinitely while leaving at least one specific magic skill untrained, this enables a high-circle character to pick up a new spell for an untrained specific magic skill and start using it modestly, without having to backtrack to training methods for absolute beginners. In contrast, most magic users will have lower Sorcery skill ranks than their other magic skills, so the same mechanic will prevent them from gaining the full benefits of their skill ranks in the specific magic skills when casting sorcerously, even before the additional difficulty level of sorcerous casting is considered.

{{RefAl}}
{{cat|Magic skillset,Skills}}

Scholarship skill

2020-08-23T07:45:12Z

DSETHK93: /* Training Scholarship */ Added sigil harvesting.

{{RTOC}}

Scholarship is used to more effectively teach and learn from being taught. It is also used to determine how much information you can obtain from the [[Recall command]]. It may also have some other benefits especially for [[Moon Mage|Moon Mages]] and [[Bard|Bards]]. 
 
The following guilds have circle requirements in scholarship:
*[[Empath]]
*[[Moon Mage]]
*[[Warrior Mage]]
*[[Paladin]]

==Spells and abilities that boost Scholarship==
{{#ask:[[Boosts::Scholarship skill]]
|?guild association is
|format=ul
|headers=hide
|default=None
}}

==Spells and abilities that decrease Scholarship==
{{#ask:[[Debuffs::Scholarship skill]]
|?guild association is
|format=ul
|headers=hide
|default=None
}}

==Teaching==

'''Teaching''' is the art of conveying concepts and ideas to others in such way as to improve the students' ability in the subject being taught.

===Class size===

Student size is now as many as will listen in to the class. Scholarship ranks will impact how well one teaches, but virtually anyone can teach any class regardless of skill in the topic or scholarship skill.

===Factors That Affect Experience Gained From Classes===

*Scholarship ranks
*[[Charisma (stat)|charisma]]: the bonus is linear
*[[Intelligence (stat)|intelligence]]: the bonus is linear
*[[Wisdom (stat)|wisdom]]: plays a small role; the bonus is linear
*whether the teacher and student belong to the same guild
*whether the teacher and student are of the same race
*The Bard spell [[Faenella's Grace]] boosts scholarship and reduces the time between teaching pulses.
*For purposes of experience earned for teaching a class, only one F2P character in the class will count regardless of the number of F2P characters in the class.
 
Room-based bonuses to teaching were removed on 4/4/2015.<ref>[[Post:Teaching Updates - 04/04/2015 - 16:04]]</ref>
:"They were extremely inconsistent and poorly implemented anyhow, so I doubt this will have any practical ramifications, but I'm including it for the sake of transparency. (It gave bonuses based off key words in the name of rooms for example...)" --GM [[Raesh]] (4/4/2015)

===Teaching Supernatural Skills===

{|border="1" class="wikitable sortable"
|-
!Skill!!Who Can Teach!!Who Can Learn
|-
|[[Arcana skill|Arcana]]||everyone||everyone
|-
|[[Augmentation skill|Augmentation]]||all except Commoners||all except Commoners*
|-
|[[Debilitation skill|Debilitation]]||all except Commoners||all except Commoners*
|-
|[[Utility skill|Utility]]||all except Barbarians and Commoners||all except Barbarians and Commoners*
|-
|[[Warding skill|Warding]]||all except Commoners and Thieves||all except Commoners and Thieves*
|-
|[[Attunement skill|Attunement]]||magic users||magic users
|-
|[[Primary Magic skill|Holy Magic]]||Clerics, Paladins||magic users**
|-
|[[Primary Magic skill|Life Magic]]||Empaths, Rangers||magic users**
|-
|[[Primary Magic skill|Elemental Magic]]||Warrior Mages, Bards||magic users**
|-
|[[Primary Magic skill|Lunar Magic]]||Moon Mages, Traders||magic users**
|-
|[[Primary Magic skill|Arcane Magic]]||Necromancers||magic users**
|-
|[[Sorcery skill|Sorcery]]||magic users||magic users
|-
|[[Targeted Magic skill|Targeted Magic]]||magic users||magic users
|-
|[[Astrology skill|Astrology]]||Moon Mages||Moon Mages
|-
|[[Empathy]]||Empaths||Empaths
|-
|[[Primary Magic skill|Inner Fire]]||Barbarians||Barbarians
|-
|[[Primary Magic skill|Inner Magic]]||Thieves||Thieves
|-
|[[Summoning skill|Summoning]]||Warrior Mages||Warrior Mages
|-
|[[Theurgy skill|Theurgy]]||Clerics||Clerics
|}
<nowiki>*</nowiki>Magic users can teach each other at normal efficiency, as can Barbarians teaching Barbarians and Thieves teaching Thieves. Between magic users and non-magic users, the class is least efficient. Classes between Barbarians and Thieves are at the mid-point. 
<nowiki>**</nowiki>When teaching [[Primary Magic skill|primary magic]], if the teacher and student are attuned to different frequencies of mana, the student will learn [[Sorcery skill|sorcery]] instead of primary magic. This does not trigger justice like an actual Sorcery class does.

===Teaching in Combat===

As of 4/4/2015, all guilds can teach only the following skills in combat<ref>[[Post:Teaching Updates - 04/04/2015 - 03:44]]</ref>:
*[[Armor Skillset|all armor skills]]
*[[Weapon Skillset|all weapon skills]]
*[[Debilitation skill|debilitation]]
*[[Warding skill|warding]]
*[[Targeted Magic skill|targeted magic]]
*[[Evasion skill|evasion]]
*[[Tactics skill|tactics]]
*[[Barbarian|Barbarians]] can teach [[Expertise skill|expertise]] to fellow [[Barbarian|Barbarians]].
*[[Thief|Thieves]] can teach [[Backstab skill|backstab]] to fellow [[Thief|Thieves]].
*[[Paladin|Paladins]] can teach [[Conviction skill|conviction]] to fellow [[Paladin|Paladins]].
*[[Scholarship skill|scholarship]] can be learned by OBSERVING any class that can be taught during combat.
 
'''While teaching during combat only''', "the rate of learning will depend on the lore skill set placement of the teacher."<ref>[[Post:Teaching Updates - 04/04/2015 - 03:44]]</ref> 
 
It is by design that [[Bard|Bards]] can no longer teach any skill in combat.
:"I was asked to even out the teaching perk to all lore primaries instead of benefiting just Bards." --GM [[Raesh]] (4/4/2015)
:"Learning even more skills while in combat is the reverse of what we want to be encouraging." --GM [[Raesh]] (4/4/2015)

===Invisibility/Hiding===

The teacher must be visible in order to teach all but the following skills:
*[[Backstab skill|backstab]]
*[[Perception skill|perception]]
*[[Scouting skill|scouting]]
*[[Stealth skill|stealth]]
*[[Thievery skill|thievery]]

===Teaching and the Justice Mechanics===

While in a [[Justice|justice]] zone:
*Teaching or listening to [[Thievery skill|thievery]] or [[Sorcery skill|sorcery]] will result in a charge of aiding and abetting unless both the teacher and student are in hiding.<ref>[[Post:Teaching Updates - 04/04/2015 - 16:04]]</ref> 
*Teaching [[Sorcery skill|sorcery]] will result in a charge of [[Justice|forbidden practices]].

==Training Scholarship==

The following activities teach scholarship:
*teaching a class of any subject
*listening to any class
:*Teaching a class on scholarship is now wasteful, since any student can convert any ongoing class to his own personal scholarship class by using {{com|listen}} {{tt|to [player] observe}}
*reading books at a [[:Category:Libraries|library]]
*reading guild [[:Category:Renown scrolls|renown scrolls]]
*reading primers for [[Prayer Beads|bead carving]]
*studying [[crafting]] books
*studying art
*studying instructions for [[origami]]
*studying patterns for [[embroidery]]
*studying spellbooks
*studying [[anatomy charts]] (also teaches [[Empathy skill]] to Empaths and [[First Aid skill]] to all guilds)
*using the {{com|Recall}} command
*reading enchantment scolls (Moon Mages only)
*studying trading ledgers (Traders only)
*[[sigil harvesting]] (also teaches [[Arcana skill|Arcana]] and [[Outdoorsmanship skill|Outdoorsmanship]])
:*It is not necessary that one actually harvest a sigil; the [[Perceive command|PERCEIVE]] SIGIL command can teach scholarship twice in a given room, once each for the primary and secondary sigil when they are found.

{{RefAl|r=y}}
{{cat|Lore skillset,Skills}}[[page type is::skill| ]]
*[http://www.play.net/dr/news.asp?id=75 Teaching 2.0 on Play.net]

How to Script

2020-08-20T09:40:16Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* PAUSE ''<#>'': This will pause the script for the indicated number of seconds.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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. 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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==Regular Expressions==
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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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.

==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.

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.

How to Script

2020-08-20T09:35:54Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* PAUSE ''<#>'': This will pause the script for the indicated number of seconds.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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. 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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==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.

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.

How to Script

2020-08-20T05:30:53Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* PAUSE ''<#>'': This will pause the script for the indicated number of seconds.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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. 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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T05:24:03Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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. 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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T05:17:52Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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.

==Pause and Wait==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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. 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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T05:08:35Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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.

==Pause and Wait==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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.

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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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. 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 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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T04:56:02Z

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

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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.

==Pause and Wait==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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.

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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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.

===MATCH Quirks===
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:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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 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.

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.

==Variables==
Variables are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T03:52:11Z

DSETHK93: /* Match Order */ Clarified section.

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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.

==Pause and Wait==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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.

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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===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.

===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.

<pre>1 root:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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.

Again, note that once any MATCH has been made, all previous MATCHes are removed.

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 are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.

How to Script

2020-08-20T00:46:36Z

DSETHK93: /* Simple Commands */ Added ECHO, which is used in examples below but never explained on this page.

{| align="center" width="800" style="background-color: #FFAAAA; border: 1px solid #FF0000; width:85%; padding:1em; text-align:center"
|rowspan=2|[[Image:Caution.png]]
| Read This First 
Unless you are playing in [[The Fallen]], scripting while unresponsive, regardless of your status at the keyboard, is against the rules. It is your responsibility to create scripts that will not continue endlessly, in case you fall asleep or have to leave the keyboard suddenly. 
This is not a trivial matter and can result in experience penalties, character loss, or permanent lockout. '''In game type "NEWS 5 17" to review DR scripting policy.''' 
You have been warned. 
|}

{{RTOC}}

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

==Important Notes==
* Empty space before a command is ignored.
* Empty lines are ignored.
* If the end of the script is reached, the script exits.
* All commands are case insensitive, though variables are not.
* Only one command can be put on a line.

==Simple Commands==
* # : Used for commenting, any line that begins with the number symbol is ignored by the script.
* ECHO ''<string>'': This displays the string in the game window. It is useful for debugging and generally for monitoring script run status.
* PUT ''<string>'': This will cause the script to enter the string as if you typed it into the game and hit enter.
* MOVE ''<string>'': This will do the same thing as PUT, but will then pause the script until a new room is entered.
* WAIT: This command will pause the script until a prompt is received. It is not affected by suppressing prompts in game.
* 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.
* 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.
* SAVE: This is only useful in the Wizard, as it does not support standard global variables. See [[#Variables|Variables section]] for the function that replaced it.
* EXIT: This will end the script.

==Labels==
Labels are basically like signposts that you can cause the script to jump to. The most common way to cause a script to switch to a label is using "GOTO ''<label>''" although MATCH/MATCHRE is another way.

A label is placed by putting a word on its own line, followed by a colon, such as
<pre>thisIsALabel:</pre>

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.

==Pause and Wait==
Note that these are problematic commands to use, as the entire script pauses when used. This means that it won't do things like match strings, even if the text shows up. Note that this does not happen during MATCHWAIT (see Match section).

It is generally a better idea to use a MATCH/MATCHWAIT pair instead.

==Matches==
The combined use of MATCH, MATCHRE and MATCHWAIT are essential tools for the majority of intermediate and advanced scripts.

The MATCH command is executed with two parts, the label and the match string, in the form of "MATCH ''<label>'' ''<string>''". If the ''<string>'' is found, the script will immedately jump to the specified label.

Here's an example pulled from a real script (note: the numbers are the line numbers and are not part of the script):
<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCH cycle Stow what?
4 MATCH cycle You are already wearing that.
5 MATCH cycle But that is already in your inventory.
6 MATCH cycle You
7 PUT stow my pickle
8 MATCHWAIT</pre>

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.

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.

MATCHRE allows use of Regular Expressions in the search string. See the advanced section for details on regular expressions.

===Match Order===
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.

===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.

<pre>1 root:
2 MATCH root ...wait
3 MATCH run punches you
4 MATCH hide shoots you
5 PUT punch bob
6 PUT kick bob
7
8 retreat:
9 PUT retreat
10 .....
</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.

Again, note that once any MATCH has been made, all previous MATCHes are removed.

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 are basically storage locations for words. They allow you to imput information in one place and retreive it at another. They are refered to using the syntax "%''<variable name>''" such as "%target" or "%person". Note: Unlike labels, variables are case sensitive; "%variable" is NOT the same as "%Variable" or "%vArIaBlE".

There are two main types of variables, and two special ones.

===Command Line Variables===
The first type is called a command line variable. When you start your script using the ".''<scriptname>''" method, after the name you can input up to 9 other words for storage. Example:

<pre> .kill him andHim andHimToo her monkey randomGuy</pre>

These are then able to be accessed by the script. They are accessed using "%0" through "%9", with "%1" being the first word after the script name, "%2" being the second, etc. Note that "%0" is the same as putting "%1 %2 %3 %4 %5" .... "%9", listing out all the command line variables.

%0 is a special variable that contains all command line variables, including those beond %9.

If you want to use multiple words as a single variable, there are two ways to do this.
* word_word_word
* "word word word"

Unfortunately, command line variables cannot be changed once the script is started, with a few exceptions, the major one being SHIFT. Upon encountering SHIFT, "%1" is deleted, and the rest is shifted down one, with "%2" now being "%1", "%3" being "%2", all the way to "%9" which is now empty.

How are these useful? Perhaps you wish to write a script that picks and disarms a box for you, however your box can be a crate, a strongbox, a box or even a coffer. Using "%1" in the proper place, you can run your script with ".pick coffer" and it will target your coffer for opening.

Note: These variables are deleted if the script ends for any reason.

It should be noted that if more than 9 variables are used, the program will store them, but they will be unavailable without use of the SHIFT command. For example, if you do include a tenth variable, the first SHIFT will cause it to become "%9".

===Save===
The SAVE command, while supported by later versions, is only useful in the Wizard FE. Using SAVE will store the following text into a special variable called %s.

For example,

<pre> SAVE VariableContents</pre>

will store VariableContents in %s. This has been superceded by global variables in all later Simutronics Front Ends.

===Global Variables===
These variables are a different sort, because they can both be accessed from within the script and because they will remain after the script ends. However, unlike command line variables, they can only be altered by a script or through the Variables panel. Like all variables, they take the form of "%''<variable name>''".

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.

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

It is important to distinguish between an empty variable and a deleted variable. An empty variable when you call it, simply adds a blank space, but a deleted variable will insert the variable name when called. Example:

'''Command:'''
: PUT pick coffer %way

'''Empty:'''
: Result: pick coffer
:: This will end up picking your coffer normally

'''Deleted:'''
: Result: pick coffer %way
::This will result in the game telling you it cannot find your "coffer %way".

==Counter==
The counter command provides the ability to do simple math and store the outcome to a variable. You are able to use the counter command in the following ways.
: COUNTER ( SET | ADD | SUBTRACT | MULTIPLY | DIVIDE ).

The ability to do simple math and store the the value for use later opens up some great possibilities for your scripts.

The counter value itself is stored in the %c variable.

===Counter Commands===
'''SET:'''
: The SET command allows you to set the %c variable to whatever number (or another variable holding a number)
<pre>1 COUNTER SET 52
2 ECHO the counter is %c</pre>
'''ADD:'''
: The ADD command allows you to add a specified number (or variable containing a number) to the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER ADD 10
4 ECHO the counter is %c</pre>
'''SUBTRACT:'''
: The SUBTRACT command allows you to subtract a specified number (or variable containing a number) from the current counter value.
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER SUBTRACT 10
4 ECHO the counter is %c</pre>
'''MULTIPLY:'''
: The MULTIPLY command allows you to multiple the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER MULTIPLY 10
4 ECHO the counter is %c</pre>
'''DIVIDE:'''
: The DIVIDE command allows you to divide the current counter value by a specified number (or variable containing a number).
<pre>1 COUNTER SET 52
2 ECHO the counter is %c
3 COUNTER DIVIDE 10
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).

===Multiple Counters===
The scripting engine itself does not allow you to have multiple counter variables going at once, there is however a way to get around this.
Since the engine allows you to store one variable to another, and also allows you to set the current value of the counter you are able
to preform a little coding magic, and give yourself multiple counters to work with.

The example below takes use of the fact you can set the counter to another variable (provided its a number), then do your math on it, and then
store its value back to the original variable. Essentially this allows you to have as many counters going on as your heart desires.

<pre>1 SETVARIABLE MyCounter1 10
2 SETVARIABLE MyCounter2 20
3
4 ECHO MyCounter1 is %MyCounter1
5 ECHO MyCounter2 is %MyCounter2
6
7 COUNTER SET %MyCounter1
8 ECHO the counter is currently %c
9 COUNTER ADD 5
10 ECHO the counter is currently %c
11 SETVARIABLE MyCounter1 %c
12
13 COUNTER SET %MyCounter2
14 ECHO the counter is currently %c
15 COUNTER ADD 5
16 ECHO the counter is currently %c
17 SETVARIABLE MyCounter2 %c
18
19 ECHO MyCounter1 is %MyCounter1
20 ECHO MyCounter2 is %MyCounter2
</pre>

==Logic==
Many people look at the list of commands and falsely believe that there is no way to control a script beyond the initial command line variables and primative MATCHes and that there are no ways to compare values. The following is a list of ways to give greater responsiveness to these scripts.

===IF===
The most basic logic statements is the IF_''<#1-9>''. When this is added to the line before a command, it will check whether or not the variable is present and, if so, execute the command normally.

<pre>1 IF_1 GOTO %1
2 GOTO exit</pre>

This set of lines would check to see if there was anything in command line variable 1 and if so, go to the label that matches it. If not, it would exit the program.

===MATCH/Variable Pairs===
One of the issues often encountered that MATCH can't do alone is finding a way to match a string and alter it's behavior later, beyond the next step. This can be done by using a MATCH to go to a label that will then set a variable.

<pre>1 MATCH scorpion A scorpion walks in
2 MATCH spider A spider walks in
3 MATCHWAIT
4
5 scorpion:
6 SETVARIABLE someVariable scorpion
7 GOTO nextstep</pre>

As you can see, this enables a variable that can be used much later in the script. In theory, you can set it to react to as many conditions as you want to build MATCH and SETVARIABLE pairs for.

However, the is no way to directly load text from the game into a variable. All possible settings have to be built into the script prior to the event.

===Label/Variable Pairs===
One of the other important functions needed to a way to vary a script's behavior based on variables. While IF can do a primitive version of this, and using variables with in game commands can cover many situations, there is a way to do completely internal changes.

An important fact is that both GOTO and MATCH will allow the use of variables in their names. We saw this earlier with GOTO %1, but it's possible to build compound labels, such as GOTO weapon%WeaponVariable.

If we continue the previous example:
<pre>1 nextstep:
2 GOTO creature%someVariable
3
4 creatureScorpion:
5 GOTO fight
6
7 creatureSpider:
8 GOTO runAway</pre>

This would allow you to set your script to fight scorpions, but run away if spiders arrive.

====Labelerror====
There is a special use for the special errorlabel label. Recall that errorlabel will catch any GOTO or MATCH that attempts to go to a label that doesn't exist.

This label can be used with Label/Variable pairs to handle all cases which do not have a section for them. This doesn't happen with variable labels that are set inside the script as you can be sure to set all options, but can be useful in the case of a label that uses a command line. Since it is impossible to be account for all possible things that might be entered by the user, this is a good catchall for "everything else."

<pre>1 GOTO punch%1
2
3 punchBob:
4 blah blah blah blah</pre>

If you were to use this, and the user enters anything other than "bob" then the script aborts with an error about the label not existing.

Not that this can be a problematic process to use, as this label will catch ALL nonexistent labels, including all labels that are typoed or otherwise bugged, and this can make troubleshooting difficult.

====Partial Matching====
While there is no built in way to partially match an incomplete command line variable, there is brute force trick to save yourself some typing,

<pre>1 GOTO %1
2
3 swo:
4 swor:
5 sword:
6 swords:
7 blah blah blah blah</pre>

As you can see by that, it will match even a partial piece of "swords." This often best used when a command line variable is used to activate a small piece of a program, for example, to activate the pounding section of a forging script.

==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.

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> ).

<pre>1 putAway:
2 MATCH putAway ...wait
3 MATCHRE cycle / (Stow what?|You are already wearing that.|But that is already in your inventory.|You) /
4 PUT stow my pickle
5 MATCHWAIT</pre>

This will goto cycle if "Stow what?" "You are already wearing that." "But that is already in your inventory." or even just plain "You" occurs.

The /s are used to set the area, the ( and ) sets the area that will vary, and the | will separate the possibilities. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/
3 PUT get ball</pre>

This will match either "blue ball bounces by" or "green ball bounces by".

If the line is ended in /i rather then /, then it will ignore the case of the letters, otherwise it is case sensitive. For example:

<pre>1 PUT pull lever
2 MATCH ball /(blue|green) ball bounces by/i
3 PUT get ball</pre>

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]

==Roundtime Handling==
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.

Thus, while it is not always needed, it is useful to add a MATCH for "...wait" to catch failures.