UOX3 v26.06 Trigger System

UOX3 v69.02+ Trigger System
By Zadius (linkage@xmission.com)
(Document version 6)
Visit the Official Quests and Triggers Web Page

Introduction:
The trigger system first derived from an idea I had when I created a game a while back that was much like Diablo and UO. In fact it was during the glory days of Diablo and I remember that UO was still in beta at this time. Hmmm. Where does the time go eh? Anyway, for my game, I needed some what to make the NPC and items react to the actions of the player, so I designed and implemented the trigger system into this game. Recently, something just hit me. I realized that this trigger system would be the perfect thing for UOX3 and thus, with a little coding and studying the UOX3 code, I began my work with much success. Even though UOX3 was not optimally designed in some aspects, I was still able to add a fully functional trigger system with very little to no performance deteriations. What this document contains is a description of the trigger system, a table containing trigger tokens and some trigger samples. Remember, the Trigger System is still in its infancy and will get more robust as it progresses. There are tons of cool tokens already that can allow you to do some pretty cool things so have fun!

The Trigger System Defined:
The trigger system is a internal processing engine for processing functionality commands to cause an effect on the player or thier environment when an item or NPC is triggered. The trigger code is described as "flow through" which means that all triggers flow through the code from top to bottom. For speed considerations, there are no condition branches. There are however, some tokens that will abort the flow when a certain condition is not met. Basically, they are true/false conditions only. There are currenty 3 types of triggers available. They are:

1. Static triggers which are triggers that can be activated when a user uses an evoked item on a static item or a dynamic item. Static triggers are defined by thier ID and are coded in the "wtrigrs.scp" file. To specify an item to be envokable, specify it by its ID in the "envoke.scp" file. You can also activate a static world item by typing "/use" and then clicking on the object. For instance the following Static trigger will allow the player to drink from any fountain in the world.

`SECTION x173fx1738x1739x173bx1741x173dx173cx139ex179b`
`{ Replenish from a fountain`
`EMT *Slurp* Ahhhh... Tasty!`
`SND 00 50`
`ACT 22`
`STAM 10`
`}`

2. Dynamic Triggers are triggers that can be assigned to an item by typing "/itrig #" then clicking on the item. This will set the items "TRIGGER" property to the specified trigger as refferenced by the trigger number in the "triggers.scp" file. There are two types so far for dynamic triggers. They are:

A. Type 0 (default). User double-clicks item to fire trigger.
B. Type 1. User walks over item to fire trigger.
(Note: To set a trigger type, enter "/ttrig #" then click the item.)

I plan on adding more trigger types in the future. For instance, fire trigger when dopped on ground, fire trigger when dropped in pack, fire trigger when character dies, fire trigger when character is attacked and fire trigger when dropped on NPC. ect ect ect. You can make any item in the "items.scp" file be automatically triggered upon creation by entering a "TRIGGER #" token and a "TRIGTYPE # " token in the items section. The following Dymanic trigger will allow you to play chess using a chess board.

`SECTION TRG 7`
`{ Play chess`
`EMT Your move....`
`SND 00 42`
`CALCUSES -1`
`RNDUSES 5 20`
`EMT Checkmate! I win!`
`SND 00 3d`
`}`
(After creating the chess board, enter "/itrig 7" then click on the chessboard. Or you can add the token "TRIGGER 7" in the "items.scp" file in the chessboards section to have every chessboard triggered when created. In this case the triggers number is 7.)

3. NPC triggers are fired when you speak to NPC's and say a certain word. Well, in acuality I made it so that NPC triggers can also be assigned to the players for gaming purposes. For instance, giving a player a curse, or for making spreadable diseases. :) To set a trigger on a NPC or character enter "/ctrig #" as specified by the trigger number in the "ntrigrs.scp" file then click on the char. Then set the trigger word by entering "/wtrig !hail" for instance. You can also make the NPC or character be automatically triggered upon creation by entering the "TRIGGER #" token and the "TRIGWORD <string>" token in the characters section of the "npc.scp" file. NPC triggers are not fired unless the trigger word is spoken to the character. The following example makes a NPC serve you a drink when you say. "Im thirtsy! Give me a drink!":

`SECTION TRG 1`
`{ ask tavern keeper for drink`
`EMT Thar ya be yer warshipness! Drinks are on the house!`
`SND 00 42`
`IADD 5004`
`NPCACT 13`
`DISABLE 10`
`}`
(After creating the character, enter "/ctrig 1" then click on the character. Then enter "/wtrig !drink" and click the character. Or you can add the token "TRIGGER 1" and the "TRIGWORD drink" token in the "npc.scp" file in the characters section to have every said character triggered when created. In this case the triggers number is 1.)

Trigger Tokens Described:

TOKEN | REV | PARAMETERS | DESCRIPTION | S | D | N
ACT (action) | 1 | <hex1> "ACT 15" | Make the player perform a certain action like fall down backwards for instance. | Yes | Yes | Yes
CALCUSES | 1 | <value> "CALCUSES -1" | Performs math on the items uses. If the uses reaches 0 then the trigger will flow on otherwise a use is calculated and the trigger is aborted. Use this in conjuction with the "RNDUSES" and the "SETUSES" tokens. | No | Yes | No
COLOR | 1 | <hex1> <hex2> "COLOR 04 81" | Tells the trigger to also make a color check on a NEED check. Use this token before the NEED token. *NOTE* This token is coded but not yet functional. | Yes | Yes | Yes
CSKL (Check Skill) | 2 | <skill> "CSKL 7" | Performs a check on the players specified skill. This function will select a random number between 1 and 1000. If the value is below the players current skill, then the trigger will continue flow otherwise the trigger is aborted. | Yes | Yes | Yes
CMSG (Completed token message) | 1 | <string> "CMSG Found it!" | Prints the the message if the previous token was completed. Only works with RANDOM_ITEM and RANDOM_NPC right now | Yes | Yes | No
DEX (Dexterity) | 1 | <value> "DEX 1" | Performs math on the dexterity of the player that fired the trigger. See "HEA" | Yes | Yes | Yes
DISABLE | 1 | <seconds> "DISABLE 10" | Disabled the item or the NPC for n seconds. This means that the trigger cannot be fired until the disabled timer reached zero. | No | Yes | Yes
EMT (Emote) | 1 | <string> "EMT Hail stranger!" | Make the player that fired the trigger emote something to all the other players around them. | Yes | Yes | Yes
END_TRIGGER (0/1) | 1 | <value> END_TRIGGER 1 | If value is a 1 will end if the previous token completed, if 0 will end the trigger if the previous token failed. So far only works with RANDOM_ITEM AND RANDOM_NPC | Yes | Yes | No
FMSG (Fail Message) | 1 | <message> "FMSG That did not work." | Set a Fail Message variable that can be used in conjunction witht he CSKL token to display a specific message if the skill check fails. | Yes | Yes | Yes
HEA (Health) | 1 | <value> "HEA -5" <-subtract 5 "HEA 5" <-add 5 | Performs math on the health of the player that fired the trigger. Specifying a negative number will subtract that value from the players health. A positive value will add that value to the players health. (checks for the invulnerable flag) | Yes | Yes | Yes
IADD (Add Item) | 1 | <script> "IADD 5004" | Add a item according to the script number as defined in the "items.scp" file. Item is placed at the players location depending on the direction they are facing. | Yes | Yes | Yes
IDADD (add item by ID) | 2 | <hex1> < hex2> <amt 1> <amt 2> "IDADD 19 b9 1 5" | Add a item to the players pack according to the ID specified here. If the item is already in the pack, the item will be stacked. This token is used to add items not scripted in the "items.scp" file. The amount added is a random amount from amt1 to amt2, for a fixed amount just use amt1 like: IDADD 19 b9 5 will add 5 | Yes | Yes | Yes
IDFX (Effect by ID) | 2 | <hex1> <hex2> "IDFX 37 1a" | Make a special effect occur from the players location to the target location. If token is used in a NPC trigger, then the effect will go from the NPCs location to the players location. | Yes | Yes | Yes
IFOWNER | 1 | "IFOWNER" | If triggered item or NPC is owned by the triggering character, then fire trigger or else abort the trigger. | No | Yes | Yes
IFSKL (If Skill) | 1 | <skill> <value> "IFSKL 7 -100" | Does a specific check on the skill of the player. A negative value will make the check under the specified skill, a positive value will make the check above the specified skill. For example, "IFSKL 7 -100" will continue flow of the trigger if the players Blacksmithy skill is below or equal to 10.0. "IFSKL 7 300" will continue flow of the trigger if the skill is 30.0 or above. | Yes | Yes | Yes
INT (Intelligence) | 1 | <value> "INT 1" | Perform math on the intelligence of the player that fired the trigger. See "HEA" | Yes | Yes | Yes
MAKE | 2 | <script> <skill> "MAKE 1 7" | This will make a item menu pop up for the player to select from as according to the script number in the "create.scp" file and by skill. | Yes | Yes | Yes
MAN (Mana) | 1 | <value> "MANA -5" | Perform math on the mana of the player that fired the trigger. See "HEA" | Yes | Yes | Yes
MISC | 1 | <function> "MISC BANK" | This token is used to be able to perform a miscellaneous gaming function. The functions currently coded in the token are: BANK | Yes | Yes | Yes
MSG (Message) | 1 | <string> "MSG You eat the bread" | Sends a message to the players client that is displayed at the bottom. | Yes | Yes | Yes
NADD (Add NPC) | 1 | <script> "NADD 7021" | Add an NPC according to thier script number as defined in the "npc.scp" file. Static will add NPC at envoked location. Dynamic adds NPC at items location if on ground or in front of player if item is in the pack. NPC will add the NPC in front of player. | Yes | Yes | Yes
NEED | 1 | <xHex1Hex2> "NEED x19b7" | Specifies that the player must contain at least one item in thier pack that matches the specfied ID's. If the item exists then the triggers flow will continue otherwise the trigger is aborted. | Yes | Yes | Yes
NEWNAME | 1 | <name> "NEWNAME a bottle of apple cider" | Set the name of the newly created item or NPC to a different name. | Yes | Yes | Yes
NEWOWNER | 1 | "NEWOWNER" | Set the newly created item or NPC to be owned by the triggering character. Use after a NADD, IADD or a IDADD. | Yes | Yes | Yes
NEWTRIG | 1 | <trigger> "NEWTRIG" | Use after a NADD, IADD or IDADD to assign a dynamic trigger number to the newly created item or NPC. | Yes | Yes | Yes
SETTYPE & NEWTYPE | 2 | <type> "NEWTYPE 14" | Used to set the type of the current item. If used after the IDADD, then it will set the type of the item just created. If the trigger containing this token was fired by an item, will set the type of that item. | Yes | Yes | No
NEWWORD | 1 | <word> "NEWWORD Im thristy" | Used after a NADD to set a new trigger word to the newly created NPC. Not to be confused with "SETWORD". | Yes | Yes | Yes
NPCACT (NPC Action) | 1 | <hex1> "NPCACT 15" | Makes the triggered NPC perform a certain action like falling down for instance. | No | No | Yes
PUT | 1 | <x> <y> <z> "PUT 560 2173 0" | Teleport the player that fired the trigger to a specified location. | Yes | Yes | Yes
RAND (Random) | 1 | <hival> <failval> "RAND 1000 200" | Chooses a random number between 1 and <hival> and will abort the trigger if the value chosen is above the <failval>. | Yes | Yes | Yes
RANDOM_ITEM | 1 | <item #> <%> RANDOM_ITEM 3194 10 | Creates the specified script item based on the % chosen. RANDOM_ITEM 3197 10 gives a 10% chance of finding an Emerald | Yes | Yes | No
RANDOM_NPC | 1 | <NPC#> <%> | Creates the specified script NPC based on the % chosen. RANDOM_NPC 518 25 gives a 25% chance of creating a random undead monster | Yes | Yes | No
RANGE | 1 | <range> "RANGE 2" | Use at the beginning of a trigger to determine if the character is close enough to use the trigger. If the character is not within the range specified here, then a message is displayed indicating so and the trigger is aborted. Ommiting this token indicates that there is no range required to activate the trigger | Yes | Yes | No
REMOVE | 2 | "REMOVE" | Remove one of the triggered items from the game. If the item is stacked, one will be removed from the stack otherwise the item is removed from the game. | No | Yes | No
REQ (Requires Item) | 1 | <xHex1Hex2> "REQ xf43" | Specifies that the trigger can only be fired by triggering it with an evoked item that contains the hex id if the evoked item. If the condition is met then flow will continue otherwise the trigger is aborted. | Yes | Yes | No
RNDUSES (random uses) | 1 | <lowvalue> <hivalue> "RNDUSES 5 20" | Will calculate a random amount of uses for the item from 1 to <hivalue> then adding <lowvalue>. | No | Yes | No
SETID | 1 | <hex1> <hex2> "SETID 10 72" | Set the items or NPCs graphical ID to a new value. For morphing characters or making flipping switches. | No | Yes | Yes
SETEVID (Set evoked items ID) | 1 | <hex1> <hex2> "SETEVID 10 72" | Changes the ID of the item that evoked the trigger. | Yes | Yes | No
SETOWNER | 2 | "SETOWNER" | Sets the triggered item or NPC to be owned by triggereing character. If the trigger is an NPC trigger, it will set the NPC to be owned by the triggering player. Not to be confused by NEWOWNER. | No | Yes | Yes
SETTRG (Set Trigger) | 1 | <trigger> "SETTRG 20" | Sets the items or NPC's trigger to a new trigger assignment to enable you to chain triggers together. | No | Yes | Yes
SETUSES | 1 | <value> "SETUSES 10" | Sets the items uses to the specified value. You can also have the item have a predetermined amount of uses upon creation by adding the "USES #" token to the items section in the "items.scp" file | No | Yes | No
SETWORD | 1 | <string> "SETWORD Hail" | Used to change the trigger word of an NPC. | No | No | Yes
SKL (Skill Math) | 2 | <skill> <value> "SKL 7 5" | Performs math on the specified skill of the player that fired the trigger. If the <value> is '0' (zero) then this will force this token to call the advanceskill routine to perform more conplex skill calculations. | Yes | Yes | Yes
SND (Play Sound) | 1 | <hex1> <hex2> "SND 00 42" | Plays a sound at the players location and to all players within ear shot. | Yes | Yes | Yes
STAM (Stamina) | 1 | <value> "STAM 10" | Perform math of the stamina of the player that fired the trigger. See "HEA" | Yes | Yes | Yes
STR (Strength) | 1 | <value> "STR 1" | Perform math on the strength of the player that fired the trigger. See "HEA" | Yes | Yes | Yes
TARG (Target location) | 1 | <dynamic trigger> "TARG 22" | Gives the player a targeting cursor and assigns a dynamic trigger number to the targeter that gets fired when the user clicks the targeting cursor at some desination. | Yes | Yes | No
USEUP | 1 | <xHex1Hex2> "USEUP x19b7" | Will use up one item in the players pack that matches the ID specified here. Use this in conjunction with the "NEED" token to make sure the item exists before using it up. If the Item is stacked, then one will be removed from the stack otherwise the item is removed. | Yes | Yes | Yes

S=Static
D=Dynamic
N=NPC

Future Token Ideas:

There will be some more tokens being coded in the next version or versions. Here are a few of the ideas I have in mind. If you have some suggestions for some trigger tokens, please feel free to visit my web site and submit your suggestion.

-SETCOLOR (Will be used to set the color of an item that was created by the IDADD token for use in making gold, silver, adamantium and silver ore for instance)
-NPCPUT (Will place the triggered NPC at a specified location)
-EVREMOVE (Will remove the envoked item)
-SWAP (Will swap the ID of the item if one of the given IDs match the other ID given)

Trigger Examples:

Here are a few examples of triggers. Hopefully these will get your brain juices flowing.

1. Static Examples (wtrigrs.scp)

This trigger will perform the functionality of allowing the player to chop at a dynamic tree or a static tree to produce wood.

`SECTION xce0xce3xcddxcd3xce6xcd8 <- The ID of the trees. Ommit leading zeros and include an "x"`
`{ Chop at a tree`
`REQ xf43xf47xf49xf4bxf51 <- If the player used one of these items..`.
`STAM -5 <- Subtract 5 from the users stamina...`
`SND 01 3e <- Play the wood chopping sound effect..`.
`ACT d <- Make player do the "swing low" action...`
`CSKL 44 <- Make check against players lumberjacking skill...`
`SKL 44 1 <- If check passes, add 1 point to jumberjacking skill...`
`IADD 7021 <- Add a log at the players feet.`
`}`

This tigger will allow the player to use tongs on the small forge to produce iron ingots considering they have ore in thier pack.

`SECTION xfb1 <- The ID of the forge`
`{ Use a small forge`
`REQ xfbbxfbc <- Requires tongs...`
`NEED x19b7x19b8x19b9x19ba <- Must have ore in thier pack...`
`STAM -3 <- If they have ore, lower stamina by 3...`
`SND 00 54 <- Play pumping forge sound effect...`
`ACT e <- Make player do a "staff jab" action...`
`CSKL 7 <- Make check against blacksmithy skill...`
`USEUP x19b7x19b8x19b9x19ba <- If check passes, use up some ore...`
`SKL 7 5 <- Add 5 to thier blacksmithy skill...`
`IADD 7030 <- Add an iron ingot at thier feet.`
`}`

Credits:
Zadius Trigger code, trigger token and documentation author
SpaceDog Trigger token designer and testing
Tauriel Trigger code testing and merging
Genesis Trigger token submissions and testing
Myth Trigger code suggestions and testing