The purpose of this thread is to help beginners to zMUD scripting.
Anyone willing to share tips, tricks, or help is encouraged to do so.
zMUD Scripting 101
zMUD Scripting 101
Last edited by Taziar on Mon Nov 06, 2017 6:02 pm, edited 6 times in total.
Re: zMUD Scripting 101
The best place to begin is getting to know zMUD as a program well. Search through every menu item, preference setting, and feature to gain a working knowledge of the program. Even if you do not understand them at first, tinkering with stuff is the best way to learn. Which bring me to my first point...
MAKE BACKUPS!
zMUD settings tend to get corrupted from time to time and this will lose everything without a way get it back. It can be easy also to delete things or change a setting and not know how to get back to the way it was before. Make backups of the entire folder that you save zMUD to, I try to make one every couple months or so. Also keep all of your scripts stored in individual text files so if you do need to re-install it will be easy to systematically add them all back into the program. Backup copies of your map files is also recommended.
zScript
I learned zScript through reading the online help files and by looking at other peoples scripts and seeing how they worked. Having a couple intro programming classes in college helped tremendously, but without that background it is still very possible to learn how to write scripts for zMUD. One lesson I would like to pass along from one of my instructors in college is about naming conventions and constancy: Keeping an easily recognizable structure will pay off dividends further down the road. When naming any part of the script (alias, variables, trigger, ect...) it helps tremendously to have structure. One reason is you do not ever want to name something the same as this will cause conflicts. Another reason is for readability, if you ever need to come back and work on something days, months, or even years later it helps to be able to understand what everything is doing at a glance. Also if you need a function to work across scripts it is easier to manage. There are no hard/fast rules about this, you can use whatever method works for you... here are a few examples of my naming conventions for the purpose of learning.
#CLASS {Example}
#ALIAS helpExample {#SHOW {This is the help file}}
#ALIAS exampleAliasOne {}
#VARIABLE exampleVar {}
#VARIABLE exampleVar2 {}
#VARIABLE exampleVar3 {}
#TRIGGER "exampleTrigger" {^Hello world!$} {say This is an example.}
#CLASS 0
I named the first #ALIAS helpExample because I like to add help files to my scripts since I share them. This helps people use the script and any options to its full extent (they also help me remember how to use them
). The reason I used "help" as the first part of the name is so I can name all help files this way and it it easy to remember and not have conflicts later. The second part of the name is the name of the script "Example" in this case, again this keeps naming help file names unique across each script for ease of remembering and not having conflicts.
The rest of the names for #ALIAS, #VARIABLE, and #TRIGGER I use the name of the script (the scripts #CLASS name) as the first word, this reminds me what script "owns" any of these functions if I share them among other scripts. Since these names cannot be more than one word it helps for readability to have the first part be all lowercase, then each other word attached to the next having the first letter capitalized. Example: exampleAliasOne (This makes each word stand out for readability.)
The second thing I would suggest once you begin writing more and more of your own scripts is the idea of recycling. Copy and paste is your friend! Re-use as much code you have previously written whenever possible. Keep things simple at first and worry about optimization later. Getting the experience writing something that works at first is more important than perfection, you can always spend days and days and days and days....
zMUD Information Links: (I still use these all the time)
zMUD Reference Manual
zMUD Program Basics
zMUD Programing Language
zMUD Function Reference
zMUD Command Reference
zMUD Pattern Matching
zMUD Expressions
zMUD Predifined Variables
zMUD Advanced Triggers
zMUD Variables Overview
MAKE BACKUPS!
zMUD settings tend to get corrupted from time to time and this will lose everything without a way get it back. It can be easy also to delete things or change a setting and not know how to get back to the way it was before. Make backups of the entire folder that you save zMUD to, I try to make one every couple months or so. Also keep all of your scripts stored in individual text files so if you do need to re-install it will be easy to systematically add them all back into the program. Backup copies of your map files is also recommended.
zScript
I learned zScript through reading the online help files and by looking at other peoples scripts and seeing how they worked. Having a couple intro programming classes in college helped tremendously, but without that background it is still very possible to learn how to write scripts for zMUD. One lesson I would like to pass along from one of my instructors in college is about naming conventions and constancy: Keeping an easily recognizable structure will pay off dividends further down the road. When naming any part of the script (alias, variables, trigger, ect...) it helps tremendously to have structure. One reason is you do not ever want to name something the same as this will cause conflicts. Another reason is for readability, if you ever need to come back and work on something days, months, or even years later it helps to be able to understand what everything is doing at a glance. Also if you need a function to work across scripts it is easier to manage. There are no hard/fast rules about this, you can use whatever method works for you... here are a few examples of my naming conventions for the purpose of learning.
#CLASS {Example}
#ALIAS helpExample {#SHOW {This is the help file}}
#ALIAS exampleAliasOne {}
#VARIABLE exampleVar {}
#VARIABLE exampleVar2 {}
#VARIABLE exampleVar3 {}
#TRIGGER "exampleTrigger" {^Hello world!$} {say This is an example.}
#CLASS 0
I named the first #ALIAS helpExample because I like to add help files to my scripts since I share them. This helps people use the script and any options to its full extent (they also help me remember how to use them
![Razz :P](./images/smilies/icon_razz.gif)
The rest of the names for #ALIAS, #VARIABLE, and #TRIGGER I use the name of the script (the scripts #CLASS name) as the first word, this reminds me what script "owns" any of these functions if I share them among other scripts. Since these names cannot be more than one word it helps for readability to have the first part be all lowercase, then each other word attached to the next having the first letter capitalized. Example: exampleAliasOne (This makes each word stand out for readability.)
The second thing I would suggest once you begin writing more and more of your own scripts is the idea of recycling. Copy and paste is your friend! Re-use as much code you have previously written whenever possible. Keep things simple at first and worry about optimization later. Getting the experience writing something that works at first is more important than perfection, you can always spend days and days and days and days....
zMUD Information Links: (I still use these all the time)
zMUD Reference Manual
zMUD Program Basics
zMUD Programing Language
zMUD Function Reference
zMUD Command Reference
zMUD Pattern Matching
zMUD Expressions
zMUD Predifined Variables
zMUD Advanced Triggers
zMUD Variables Overview
Last edited by Taziar on Tue May 23, 2017 1:57 am, edited 7 times in total.
Re: zMUD Scripting 101
Lesson: #CLASS
[Updated: 5/18/2017]
#CLASS command
#CLASS [class name] [state|options]
The #CLASS command is going to be the basic framework for writing your scripts in zMUD. Classes are used like folders to group triggers, alias, and variables of your script together.
Format:
#CLASS {NAME}
<script>
#CLASS 0
Whenever you use the #CLASS command you are essentially setting that class as the current default class. Make sure to always add the #CLASS 0 as shown in the examples to ensure the default class is reset.
Inside the following example I show how I group my script components inside of a #CLASS:
#CLASS {Example}
#ALIAS exampleAlias1 {}
#ALIAS exampleAlias2 {}
#ALIAS exampleAlias3 {}
#ALIAS exampleAlias4 {}
#VAR exampleVariable1 {}
#VAR exampleVariable2 {}
#VAR exampleVariable3 {}
#VAR exampleVariable4 {}
#VAR exampleVariable5 {}
#VAR exampleVariable6 {}
#TRIGGER "exampleTrigger1" {} {} "" {}
#TRIGGER "exampleTrigger2" {} {} "" {}
#CLASS 0
Since zScript is a language that does not support code comments very well and it is helpful to keep some kind of structure for readability. I like to have all of my #ALIAS at the top, my #VAR in the middle, and my #TRIGGER at the bottom. The zMUD editor follows this formatting also.
#CLASS options: There are two class options that I use regularly and would like to give some insight on {disable} and {enable}.
To set a class option place it inside of brackets after the name of the #CLASS.
#CLASS {Example} {disable}
<script>
#CLASS 0
One other useful command that is used with classes is the #T+ {setting name} and #T- {setting name}. These two commands turn classes, triggers, and most all settings on (#T+) and off (#T-) similar to the class options described below: {disable} and {enable}. The difference is that #T+ and #T- can be used inside your scripts to turn things on and off at will, where the {disable} and {enable} settings turn class folders on and off when you first connect to the mud. To turn the above example class on and off you would write the commands like this: #T+ {example} to enable the class "example" or #T- {example} to disable the class "example".
The disable option is used for whenever you want a class to be turned off when zMUD connects to the mud. When a class is turned off (disabled) zMUD will not use any alias, variables, or triggers inside that class. It is essentially invisible to zMUD.
The enable option is just the opposite of the disable option, it turns the #CLASS on (enabled) when you connect to the mud. This class option will ensure the #CLASS is always enabled when you start your session in case you turned it off (disabled it) at some point during the last session.
Another reason to turn something off (disable) is resource related, zMUD can get bogged down and lag if too many triggers are trying to pattern match on every line from the mud. By writing your scripts so that the majority of your triggers are turned off and only turned on right before you need them (then turned off again) this will help maintain performance. We will go more into this with the upcoming #TRIGGER lesson.
EDIT- I stopped using the {setdef} option as it was creating too many duplicate variables inside multiple places when triggers in different {setdef} classes fired too close to each other. Another way to ensure your variables get saved in the correct place is through explicitly telling zMUD in the variable options where it should go. More of this in the upcoming #VAR lesson.
[Updated: 5/18/2017]
#CLASS command
#CLASS [class name] [state|options]
The #CLASS command is going to be the basic framework for writing your scripts in zMUD. Classes are used like folders to group triggers, alias, and variables of your script together.
Format:
#CLASS {NAME}
<script>
#CLASS 0
Whenever you use the #CLASS command you are essentially setting that class as the current default class. Make sure to always add the #CLASS 0 as shown in the examples to ensure the default class is reset.
Inside the following example I show how I group my script components inside of a #CLASS:
#CLASS {Example}
#ALIAS exampleAlias1 {}
#ALIAS exampleAlias2 {}
#ALIAS exampleAlias3 {}
#ALIAS exampleAlias4 {}
#VAR exampleVariable1 {}
#VAR exampleVariable2 {}
#VAR exampleVariable3 {}
#VAR exampleVariable4 {}
#VAR exampleVariable5 {}
#VAR exampleVariable6 {}
#TRIGGER "exampleTrigger1" {} {} "" {}
#TRIGGER "exampleTrigger2" {} {} "" {}
#CLASS 0
Since zScript is a language that does not support code comments very well and it is helpful to keep some kind of structure for readability. I like to have all of my #ALIAS at the top, my #VAR in the middle, and my #TRIGGER at the bottom. The zMUD editor follows this formatting also.
#CLASS options: There are two class options that I use regularly and would like to give some insight on {disable} and {enable}.
To set a class option place it inside of brackets after the name of the #CLASS.
#CLASS {Example} {disable}
<script>
#CLASS 0
One other useful command that is used with classes is the #T+ {setting name} and #T- {setting name}. These two commands turn classes, triggers, and most all settings on (#T+) and off (#T-) similar to the class options described below: {disable} and {enable}. The difference is that #T+ and #T- can be used inside your scripts to turn things on and off at will, where the {disable} and {enable} settings turn class folders on and off when you first connect to the mud. To turn the above example class on and off you would write the commands like this: #T+ {example} to enable the class "example" or #T- {example} to disable the class "example".
The disable option is used for whenever you want a class to be turned off when zMUD connects to the mud. When a class is turned off (disabled) zMUD will not use any alias, variables, or triggers inside that class. It is essentially invisible to zMUD.
The enable option is just the opposite of the disable option, it turns the #CLASS on (enabled) when you connect to the mud. This class option will ensure the #CLASS is always enabled when you start your session in case you turned it off (disabled it) at some point during the last session.
Another reason to turn something off (disable) is resource related, zMUD can get bogged down and lag if too many triggers are trying to pattern match on every line from the mud. By writing your scripts so that the majority of your triggers are turned off and only turned on right before you need them (then turned off again) this will help maintain performance. We will go more into this with the upcoming #TRIGGER lesson.
EDIT- I stopped using the {setdef} option as it was creating too many duplicate variables inside multiple places when triggers in different {setdef} classes fired too close to each other. Another way to ensure your variables get saved in the correct place is through explicitly telling zMUD in the variable options where it should go. More of this in the upcoming #VAR lesson.
Last edited by Taziar on Tue May 23, 2017 12:12 pm, edited 2 times in total.
Re: zMUD Scripting 101
Lesson: #ALIAS
#ALIAS command
#ALIAS [aliasname] [string] [classname]
The #ALIAS command in my opinion is one of the top three most important settings in all of zScript. As a basic function (like the alias command in WoTmud) you can use #ALIAS to make short cuts to longer commands. But the most important thing to think of the #ALIAS setting is as a mini program inside of your script. Just like when you type an alias into the command line you can also place the alias name inside of another setting and the alias will run. Why is this important?
Each script ran in zMUD has to be recopied with references like %1 being replaced with text, and then it is parsed for execution. As with any programming language whatever duplication you can eliminate is going to help performance, the #ALIAS command can help reduce this. Whenever you find that you have a block of code that is being repeated by more than one setting you can instead create an #ALIAS that carries out that block of code and just call that #ALIAS in any of the settings that need it!
Special Alias
zMUD has a few special #ALIAS that get called when certain conditions are met, the following list is sort of self explanatory:
atconnect
atdisconnect
atexit
onroomcreate
onroomenter
onwalkend
Each of these special alias are called when the event occurs. To use a special alias just create it like a normal alias with one of the above names.
Example: #ALIAS atconnect {#SAY {Hello World}} would show the text "Hello World" whenever zMUD connected to a mud.
Note: One instance of a setting...
All settings in zMUD will only be called once. This means if you duplicate a setting zMUD will only call one instance of it, and even to the point where zMUD will not create another copy of a duplicate setting in the same class. Duplicate settings can be created in different classes though...
Whenever an alias is called only one instance of it will be called, even if there are more than one with the same name across different classes. This makes using the special alias very difficult across multiple scripts because only one version will ever be called. When mixing other peoples scripts with your own it is important to check for any alias names that could conflict. I try to not use any of the special alias in my HoM scripts to help avoid possible conflicts for others that use them. If you choose to use special alias I suggest creating a class to keep them in so you can keep track and access them easily. This way if you use more than one script that contains special alias you can cut/paste them all together into one instance.
Trigger ID's come into play in an important way: lets say you have two triggers that you want to fire on the same pattern, problem is that zMUD won't create multiple triggers this way inside the same class because the pattern to be matched is used as a default ID, you need to give them each a unique ID. With different IDs each trigger becomes its own unique setting and can even duplicate patterns you previously assigned within the same class. Triggers inside different classes can be created with the same pattern and they will fire, but caution should be taken and giving triggers IDs can help in other ways. I suggest giving triggers IDs whenever convenient.
Alias and variables behave slightly different as neither has the ability to assign an ID other than the name you give them. Variables created with the same name inside of a class with another variable of the same name will write over any previous, but a variable can be created in another class with the same name! zMUD should look for variables first inside of the same class that the setting that is trying to use that variable is in, but this is another reason naming conventions should be followed closely because if you create duplicate variables like this zMUD might not use the one you want it to, creating conflict.
#ALIAS command
#ALIAS [aliasname] [string] [classname]
The #ALIAS command in my opinion is one of the top three most important settings in all of zScript. As a basic function (like the alias command in WoTmud) you can use #ALIAS to make short cuts to longer commands. But the most important thing to think of the #ALIAS setting is as a mini program inside of your script. Just like when you type an alias into the command line you can also place the alias name inside of another setting and the alias will run. Why is this important?
Each script ran in zMUD has to be recopied with references like %1 being replaced with text, and then it is parsed for execution. As with any programming language whatever duplication you can eliminate is going to help performance, the #ALIAS command can help reduce this. Whenever you find that you have a block of code that is being repeated by more than one setting you can instead create an #ALIAS that carries out that block of code and just call that #ALIAS in any of the settings that need it!
Special Alias
zMUD has a few special #ALIAS that get called when certain conditions are met, the following list is sort of self explanatory:
atconnect
atdisconnect
atexit
onroomcreate
onroomenter
onwalkend
Each of these special alias are called when the event occurs. To use a special alias just create it like a normal alias with one of the above names.
Example: #ALIAS atconnect {#SAY {Hello World}} would show the text "Hello World" whenever zMUD connected to a mud.
Note: One instance of a setting...
All settings in zMUD will only be called once. This means if you duplicate a setting zMUD will only call one instance of it, and even to the point where zMUD will not create another copy of a duplicate setting in the same class. Duplicate settings can be created in different classes though...
Whenever an alias is called only one instance of it will be called, even if there are more than one with the same name across different classes. This makes using the special alias very difficult across multiple scripts because only one version will ever be called. When mixing other peoples scripts with your own it is important to check for any alias names that could conflict. I try to not use any of the special alias in my HoM scripts to help avoid possible conflicts for others that use them. If you choose to use special alias I suggest creating a class to keep them in so you can keep track and access them easily. This way if you use more than one script that contains special alias you can cut/paste them all together into one instance.
Trigger ID's come into play in an important way: lets say you have two triggers that you want to fire on the same pattern, problem is that zMUD won't create multiple triggers this way inside the same class because the pattern to be matched is used as a default ID, you need to give them each a unique ID. With different IDs each trigger becomes its own unique setting and can even duplicate patterns you previously assigned within the same class. Triggers inside different classes can be created with the same pattern and they will fire, but caution should be taken and giving triggers IDs can help in other ways. I suggest giving triggers IDs whenever convenient.
Alias and variables behave slightly different as neither has the ability to assign an ID other than the name you give them. Variables created with the same name inside of a class with another variable of the same name will write over any previous, but a variable can be created in another class with the same name! zMUD should look for variables first inside of the same class that the setting that is trying to use that variable is in, but this is another reason naming conventions should be followed closely because if you create duplicate variables like this zMUD might not use the one you want it to, creating conflict.
Last edited by Taziar on Sun Jun 18, 2017 1:59 pm, edited 10 times in total.
Re: zMUD Scripting 101
Lesson: #VARIABLE
#VARIABLE command
#VARIABLE [variable] [value] [defaultval] [classname]
The #VARIABLE command is another of the top three most important settings of zMUD... this is where you save any of the information that you may need to use again at a latter point in your script.
(more lesson coming soon)
#VARIABLE command
#VARIABLE [variable] [value] [defaultval] [classname]
The #VARIABLE command is another of the top three most important settings of zMUD... this is where you save any of the information that you may need to use again at a latter point in your script.
(more lesson coming soon)
Last edited by Taziar on Tue May 23, 2017 1:58 am, edited 2 times in total.
Re: zMUD Scripting 101
Lesson: #TRIGGER
#TRIGGER command
#TRIGGER [id] {pattern} {command} [classname] [options]
The #TRIGGER command is the most powerful of the settings in zMUD as well as one of the most important. Triggers "fire" when predefined text (a pattern) from the mud is detected.
(more lesson coming soon)
#TRIGGER command
#TRIGGER [id] {pattern} {command} [classname] [options]
The #TRIGGER command is the most powerful of the settings in zMUD as well as one of the most important. Triggers "fire" when predefined text (a pattern) from the mud is detected.
(more lesson coming soon)