ScriptingIntro

Scriptable

---

Calling all Cars, There's an Introduction in Progress

This short guide is in no way a substitute for the full scriptable guide located here. Its goal is to provide a beginners look at scripting in CoffeeMud. After this introduction you should feel free to look at the example scripts located in the /resources/progs/ directory of your install and try out some of your own!

So you've built up the areas in your own Mud and populated them with items, equipment and creatures (Mobs), but now what? From a player’s perspective, things are still relatively bland. The mobs are always in the same places/area and they never react to anything the players do. Kill a dwarf in front of his friend and he just stands there. Steal an altar right out from a temple priest and he acts like nothing happened. There are many solutions to these problems in this ever expanding codebase:

* Add an emoter behavior to a mob to make them randomly emote an action.

* Add the Sounder behavior to a Mob to make them randomly seem to say something

* Add the RaceHelper behavior to make mobs protect each other.

The methods are various, but the outcome is the same; attempting to make your Mobs act and react in order to appear more life-like. There is a cure-all to this predicament, and it goes by the name of Scriptable. It's not Java coding, it's a handful of progs triggering a multitude of actions and working from information gleaned from built in functions. At times it can be frustrating, but if you're willing to experiment and see where it can take you, your Mob and players will thank you for the enriching environment you have created for them.

Ok, You've Piqued My Interest, Now What?

Well, first you need a trigger. You'll need an action if you want to invoke an equal and opposite reaction type of thing. Check out the section of the Scripting Guide called "Scripting Events", it's full of progs in the form of 'something_prog'. These are what will contain you're scripted actions and are used to trigger those actions when called for.

Lets take the "time_prog". This may be the most easily understood prog as it functions exactly like an alarm clock. To give an appropriate example, lets take this small snippet of code:

 if ($b == 3) {
     do some stuff;
 }

A trigger prog in Scriptable is set up in much the same way, asking when it should trigger and followed by a bounded list of actions to take. Lets see how much the time_prog looks like that...

 time_prog 3
     do some stuff
 ~

So basically, when it is the third hour in any mud day, the Mob (or item or room) with this script will do the actions listed until it reaches the tilde (~).

Lets take another side by side example of code and scriptable. In this snippet of code, we look at some text to see if it contains a word we are looking for.

 if ($b eq 'help') {
     do some stuff
 }

and in scriptable is would look like:

 speech_prog help
     do some stuff
 ~

Putting a script that contains this trigger on a mob will cause it to react anything the word "help" is said by anyone in the room. It could be "Please help me" or "I'm looking for some help", both would trigger the prog.

There are a wide variety of progs to react to just about every situation you can imagine. From consume_prog to react to eating something, to greet_prog to react to people entering the same room, to rand_prog to just have things trigger randomly.

"Do Some Stuff", Like What?

Well, now that you have the Mob triggering once a certain event takes place, you have to figure out what actions it should take. Again, an effort has been made to accommodate any action you can imagine - though some may be more work than other to get to happen. From simple mundane talking and spell casting, to setting variables and item creation - a scripted mob has a multitude of action at its fingertips.

Lets go back to the last prog we used and have the scripted mob take an action this time.

 speech_prog help
     say What do you need help with?
 ~

Looks pretty simple? That’s right, you can script a mob to take any regular in game action, like using skills it has, dropping items, or just talking. Say you wanted to help that poor player out, you could script the Mob to instead do this:

 speech_prog help
     say Here you go!
     drop potion
 ~

As shown here, you can have any number of commands bounded between the trigger and the tilde. The mob will speak and then immediately drop a potion from it's inventory.

"But I want the Mob to give the potion directly to the player!" - This is perfectly doable. It will however require delving deeper into the murky depths of scripting. If you've made it this far, I encourage you to continue onward...

It's Code Time!

No, not as in Java code. Scripting codes. The Scripting Guide has a section labeled "Scripting Codes" that contains a long list of crazy characters like $a or $P. These are little variable that get filled in with information by certain triggers that use them. They get parsed and filled in with the correct values before the script action are run - so lets take an easy one for example...

 speech_prog help
     say Here you go $n.
     give potion $n
 ~

Looking at the list, $n is "The Source of the triggers name". This means it's the name of the player that said "help". If that player's name was Jeremy, the scripted mob would run two command, "say Here you go Jeremy." and "give potion to Jeremy". The codes listed allow you to build sentences that make sense based on how the mob is talking to... He or She, his or her, as well as quest items and random room elements. With the inclusion of these codes your scripts can have dynamic commands and actions that vary depending on what triggers them.

Does it Function?

Functions are listed in the Scripting Guide just after the scripting codes. Using these functions allows for far more customized and dynamic scripts than just using the codes. Lets continue the script we've been making - say you didn't want to give a potion to anyone who was evil... There is no code like '$n' to give you this information, but the ISEVIL() function will do the trick! Here's how:

 speech_prog help
     IF (ISEVIL($N))
         say You're evil! I don't want to help you.
     ELSE
         say Here you go $n.
         give potion $n
     ENDIF
 ~

Now the prog checks for a player's alignment first, and if it is evil they will not get any help. This script also makes use the IF statement which simply checks the information returned by functions and acts on its result. If the player wasn't evil, the ELSE part of the statement would have been executed instead.

There are plenty of functions for checking on things, like race, class, or the weather. There are also functions that give you information to further work with, like ISHERE() to tell you what area you're in, or RANDNUM() to give you a random number. With the clever use of functions your Mobs can gather more information about their surrounding to work with, and more knowledgeable Mobs generally provide more entertainment and intrigue to players.

I Command It!

So now your Mobs know things and can act upon that knowledge, but what can they do? Well, if you've made it this far you deserve to be rewarded. As such, I have saved the best section for last. All scripts have access to the Scripting Commands which are located in the similarly named section of the scripting guide. These commands let your Mobs have the power to do nearly anything that needs doing, from moving to a location, creating items, starting quests, or just dishing out some justice.

Looking back at our script, what happens when the Mob runs out of potions to give? Well this problem can be solved with the proper use of scripting commands. Here's how:

 speech_prog help
     IF (ISEVIL($N))
         say You're evil! I don't want to help you.
     ELSE
         mpoload potion
         mpecho $i digs around in $k pocket for a potion.
         say Here you go $n.
         give potion $n
     ENDIF
 ~

And there you have it, a Mob that's a regular potion factory. With short scripts like this, your cities can come alive with Mobs that speak their minds and make observations on their surroundings. Mobs can go about on daily routines and react to players along the way. No messing around with code is needed, no custom Behaviors involved at all. With such a robust system, Mobs are truly limited only by your imagination!

user:jpagens