Games-Axmud
view release on metacpan or search on metacpan
share/docs/guide/ch07.mkd view on Meta::CPAN
[Previous](ch06.html) [Index](index.html) [Next](ch08.html)
---
#7 Creating Interfaces
####Table of Contents
* [7.1 Triggers](#7.1)
* [7.1.1 Editing triggers ](#7.1.1)
* [7.1.2 Trigger attributes](#7.1.2)
* [7.1.3 Trigger styles](#7.1.3)
* [7.1.4 Rewriter triggers](#7.1.4)
* [7.1.5 Substrings in rewriter triggers](#7.1.5)
* [7.1.6 Substrings in other triggers](#7.1.6)
* [7.1.7 Splitter triggers](#7.1.7)
* [7.1.8 Simple splitter triggers](#7.1.8)
* [7.1.9 Advanced splitter triggers](#7.1.9)
* [7.2 Aliases](#7.2)
* [7.2.1 Adding aliases](#7.2.1)
* [7.2.2 Safer aliases](#7.2.2)
* [7.2.3 Editing aliases](#7.2.3)
* [7.2.4 Alias attributes](#7.2.4)
* [7.2.5 Substrings in aliases](#7.2.5)
* [7.3 Macros](#7.3)
* [7.3.1 Axmud keycodes](#7.3.1)
* [7.3.2 Adding macros](#7.3.2)
* [7.3.3 Editing macros](#7.3.3)
* [7.3.4 Macro attributes](#7.3.3)
* [7.4 Timers](#7.4)
* [7.4.1 Adding timers](#7.4.1)
* [7.4.2 Editing timers](#7.4.2)
* [7.4.3 Timer attributes](#7.4.3)
* [7.5 Hooks](#7.5)
* [7.5.1 Hook events](#7.5.1)
* [7.5.2 Hook data](#7.5.2)
* [7.5.3 Adding hooks](#7.5.3)
* [7.5.4 Editing hooks](#7.5.4)
* [7.5.5 Hook attributes](#7.5.5)
* [7.5.6 Using hook data](#7.5.6)
* [7.5.7 Redirect mode](#7.5.7)
* [7.5.8 Custom hook events](#7.5.8)
* [7.6 Active and inactive interfaces](#7.6)
* [7.7 Exporting/importing interfaces](#7.7)
---
The quickest way to create a trigger, alias, macro, timer or hook is from the main window menu.
##<a name="7.1">7.1 Triggers</a>
We'll start with triggers. Click on **Interfaces > Triggers > World triggers** and this window will appear.
All interfaces have a *stimulus* and a *response*.
A trigger uses a pattern as a stimulus. When Axmud receives a line of text that matches the pattern, we say that the trigger *fires*. After the trigger fires, it can send a world command in response.
* In the **Trigger stimulus** box, enter the pattern **You kill the orc**
* In the **Trigger response** box, enter the world command **get coins from corpse**
* In the **Name** box, enter the name **mytrigger**
* A name will be created for you, if you don't enter one
* Click the **Starts enabled** checkbutton to de-select it
* If the trigger starts disabled, we'll have a chance to finish editing it before Axmud starts checking it against received text
* Make sure the **Splitter** and **Rewriter** checkbuttons are deselected, too
* Click the **Add** button to create the trigger
###<a name="7.1.1">7.1.1 Editing triggers</a>
Triggers are highly customisable. Select **mytrigger** by clicking on it, and then click the **Edit** button.
The new edit window contains three tabs. The **Name** tab allows you to change the trigger's stimulus and response, and also allows you to enable or disable the trigger.
The **Attributes** tab allows you to customise the trigger - for example, to make matching lines disappear from view, or to disable the trigger automatically after the first match.
When Axmud is testing triggers against a line of text, it checks the triggers in the same order each time. Sometimes the order is important, so the **Before / after** tab allows you to name the triggers that should be checked before or after this one...
###<a name="7.1.2">7.1.2 Trigger attributes</a>
Click on the **Attributes** tab.
We'll talk about rewriter triggers in [Section 7.1.4](#7.1.4) and splitter triggers in [Section 7.1.6](#7.1.6). First, let's examine the other attributes.
**Igore the trigger response (e.g. just apply a style)**
When this checkbutton is selected, nothing happens when the trigger fires (but any trigger style is still applied - see [Section 7.1.3](#7.1.3).
share/docs/guide/ch07.mkd view on Meta::CPAN
The new edit window contains three tabs. The **Name** tab allows you to change the stimulus and response, and also allows you to enable or disable the alias.
The **Attributes** tab allows you to customise the alias - for example, to disable the alias automatically after the first match.
When Axmud is testing aliases against a world command, it checks the aliases in the same order every time. Sometimes the order is important, so the **Before / after** tab allows you to name the aliases that should be checked before or after this one.
###<a name="7.2.4">7.2.4 Alias attributes</a>
Click on the **Attributes** tab. There are four attributes which can be customised.
**Ignore case**
When the checkbutton is selected, this alias doesn't care about capital letters. In the examples above, **amazing red crown** will be substituted for all of the following world commands:
arc
Arc
ARC
From your reading of [Section 6](ch06.html) you'll remember that patterns are usually case-sensitive. De-select the button to make the pattern **arc** match only the first command above.
(Although it's unlikely that you would want to distinguish between upper-case and lower-case world commands, the capability is available, if you should ever need it.)
**Keep checking aliases after a match**
If the checkbutton is not selected, when this alias's pattern matches a world command, Axmud will not check any other aliases. If the checkbutton is selected, Axmud will continue checking the command against other aliases.
**Temporary alias**
If the checkbutton is selected, the alias only fires once. After that, the active alias becomes an inactive alias - it will be available again, the next time you connect to the world, but it will not be available again during this session.
**Cooldown (in seconds)**
You can prevent an alias from firing too often by setting a cooldown period. For example, if you set the cooldown to 10, after firing the alias won't be able to fire again for another 10 seconds. The default value is 0, meaning no cooldown period is ...
###<a name="7.2.5">7.2.5 Substrings in aliases</a>
Aliases, like triggers, can contain substrings.
For example, suppose you want Axmud to convert a world command like **give 50 gc to orc** to **give 50 gold coins to orc**. This is how to do it, so that the alias will work with any number of coins being given to any creature:
* In the **Alias stimulus** box, enter the pattern **^give (.\*) gc to (.\*)$**
* In the **Alias response** box, enter the text **give $1 gold coins to $2**
* In the **Name** box, enter the name **myalias3**
* Click the **Add** button to create the alias
You can now test the alias by typing the world command **give 50 gc to orc**.
There are a few things left to mention:
* NB Before v1.1.270, the instruction had to be enclosed in double-quotes
* e.g. **"give $1 gold coins to $2"**
* This is no longer necessary (but your old aliases will continue to work)
* If you *actually* want the intruction to begin and end with double quotes, you must use two of them
* e.g. **""give $1 gold coins to $2""**
* If you want the instruction to contain a literal **$1**, precede it with a backslash
* e.g. **give \$1 to $1**
* This instruction would look something like **give $1 to Gandalf**
* If you *actually* want a backslash *anywhere* in the instruction, use must use two of them
* e.g. **apples and\\\\or oranges**
##<a name="7.3">7.3 Macros</a>
Macros wait for you to press a key like F1, and then do something in response.
Like all interfaces, Axmud macros have a *stimulus* and a *response*. The stimulus is a *keycode* that represents one of the keys on your keyboard. When you press the key, we say that the macro *fires*.
The response can be any kind of instruction. It's usually a world command like **get coins from corpse**, but it could be a client command like **;openautomapper** or any other kind of instruction (see [Section 4.4](ch04.html#4.4)).
###<a name="7.3.1">7.3.1 Axmud keycodes</a>
A key part of Axmud's design is *platform independence*. If you install Axmud on one computer with Linux and on another computer with MS Windows, the data you save on one can be transferred to the without problems.
For this reason, Axmud uses a set of standard keycodes - short strings corresponding to every key on the keyboard. The keycode for each key is the same, regardless of which operating system you're using.
Axmud's keycodes - always in lower-case - are:
shift alt alt_gr ctrl num_lock
escape pause break insert delete return backspace space tab
home page_up page_down end
up down left right
f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
grave tilde exclam at number_sign dollar percent
ascii_circum ampersand asterisk paren_left parent_right
plus minus equal underline
bracket_left bracket_right brace_left brace_right colon
semicolon apostrophe quote slash backslash pipe comma
full_stop less_than greater_than question_mark
There are also a set of keycodes for the keypad (the keys, normally on the right side of the keyboard, which are laid out like a calculator):
kp_0 kp_1 kp_2 kp_3 kp_4 kp_5 kp_6 kp_7 kp_8 kp_9
kp_add kp_subtract kp_multiply kp_divide kp_enter kp_full_stop
The keycodes 'full_stop' and 'kp_full_stop' represent the full stop/period keys. Axmud supports a number of alternatives to the standard keycodes, including 'period'. (Type **;listkeycodealternative** for a list of alternative keycodes.)
Keycodes can be combined when two or more keys are pressed together. For example, CTRL + F1 corresponds to the keycode string "ctrl f1" (a string containing two words separated by a single space character).
Note that, for technical reasons, Axmud cannot use SHIFT or ALT-GR in macros (although ALT + SHIFT + some other key is acceptable). Therefore, if you try to add a macro that fires when you press SHIFT + F1, it won't work.
###<a name="7.3.2">7.3.2 Adding macros</a>
* From the main window menu, click **Interfaces > Macros > World macros**
* In the **Macro stimulus** box, enter the keycode **f1**
* Axmud standard keycodes are always in lower-case characters
* In the **Macro response** box, enter the command **get coins from corpses**
* In the **Name** box, enter the name **mymacro**
* Click the **Add** button to create the macro
###<a name="7.3.3">7.3.3 Editing macros</a>
Like triggers and aliases, macros are customisable. Select **mymacro** by clicking on it, and then click the **Edit** button.
The new edit window contains three tabs. The **Name** tab allows you to change the stimulus and response, and also allows you to enable or disable the macro.
The **Attributes** tab allows you to customise the macro - for example, to disable the macro automatically after the first matching keypress.
When Axmud is testing macros against a keypress, it checks the macros in the same order every time. Sometimes the order is important, so the **Before / after** tab allows you to name the macros that should be checked before or after this one.
###<a name="7.3.4">7.3.4 Macro attributes</a>
Click on the **Attributes** tab. There are two attributes which can be customised.
**Temporary macro**
If the checkbutton is selected, the macro only fires once. After that, the active macro becomes an inactive macro - it will be available again, the next time you connect to the world, but it will not be available again during this session.
**Cooldown (in seconds)**
You can prevent a macro from firing too often by setting a cooldown period. For example, if you set the cooldown to 10, after firing the macro won't be able to fire again for another 10 seconds. The default value is 0, meaning no cooldown period is u...
##<a name="7.4">7.4 Timers</a>
Timers allow you to execute an instruction repeatedly at regular intervals. They can also be used to execute an instruction once, after a certain period of time. They can even be used to execute an instruction once a day, at the same time each day (o...
Like all interfaces, Axmud timers have a *stimulus* and a *response*. The stimulus is usually a time interval, expressed in seconds. The minimum value is 0.1 seconds. When this interval has passed, we say that the timer *fires*.
The stimulus can also a 24-hour clock time in the form HH:MM (for example, 00:00 for midnight, 12:00 for midday, 13:30 for half past one in the afternoon). If you use a clock time, the timer fires at the time, once a day.
Axmud recognises special clock times in the form 99:MM. For example, a timer whose stimulus is 99:00 will fire once an hour, on the hour. A timer whose stimulus is 99:15 will fire once an hour, at a quarter past the hour.
The response can be any kind of instruction. It's usually a world command like **score**, but it could be a client command like **;playsoundeffect beep** or any other kind of instruction (see [Section 4.4](ch04.html#4.4)).
###<a name="7.4.1">7.4.1 Adding timers</a>
Let's create a timer which will *fire* every 60 seconds, and which sends the world command **score** each time it fires.
* From the main window menu, click **Interfaces > Timers > World timers**
* In the **Timer stimulus** box, enter the time interval **60**
* In the **Timer response** box, enter the command **score**
* In the **Name** box, enter the name **mytimer**
* Click the **Add** button to create the timer
###<a name="7.4.2">7.4.2 Editing timers</a>
Like triggers, aliases and macros, timers are customisable. Select **mymacro** by clicking on it, and then click the **Edit** button.
The new edit window contains three tabs. The **Name** tab allows you to change the stimulus and response, and also allows you to enable or disable the timer.
The **Attributes** tab allows you to customise the timer - for example, to disable the timer automatically after it fires for the first time.
When Axmud is testing whether it's time to fire a timer, or not, it checks the timers in the same order every time. Sometimes the order is important, so the **Before / after** tab allows you to name the timers that should be checked before or after t...
###<a name="7.4.3">7.4.3 Timer attributes</a>
Click on the **Attributes** tab. There are several attributes which can be customised.
**Repeat count**
Some timers should continue firing indefinitely; others should only fire a certain number of times.
The repeat count sets how many times the timer fires, before disabling itself. You can use any positive integer value; alternatively, use the value -1 to make the timer repeat indefinitely.
**Initial delay**
Some timers should fire immediately, but usually you'll want the timer to fire for the first time after a delay.
If you use an initial delay of 0, an enabled timer fires as soon as it becomes active. Otherwise, it waits for the specified number of seconds before firing for the first time.
You will often set the repeat count and the initial delay to the same value, so that the timer fires (for example) 10 seconds after becoming active, then every 10 seconds after that.
( run in 0.932 second using v1.01-cache-2.11-cpan-75ffa21a3d4 )