Lesson 3: functions

And lo!  There were functions, and they were good...  Yes, we're doing functions.  This is where everything will hopefully come together.  If it doesn't, you may just need to tinker with it til you get the hang of it.  What are functions, you ask?  Well, they're the things that control what gets run when you want it to.  There's 3 special functions that you've probably seen/made in your own code.

create()
init()
reset()

The first one, create is used in every object that a user will come in contact with.  Every line within the {} of the create function gets run when the object is first created. (hence, the name create).  I'll go into more detail when we go over the example code.

init() is run for any player that comes in contact with it.  if init() is in a room, init() is run for each person who enters the room.  if it's in an object or monster, it's run as soon as the player is in the same room.  This function is usually used to limit who can have the item (check to see if they're an imm, and if not, make it disappear.  That's what my anti-matter gun does.)  init() is mostly used in rooms for the add_action() command.

3 guesses on when reset() gets run.  Right!  You've heard of rooms being reset...  well, reset is called in rooms by the driver.  so, mobs aren't automatically replaced if they get killed.  You need to put code in reset() that checks to see if the mobs are there, and then code to add new ones.

Now you've probably noticed that functions look like they're declared like variables.  for instance, the declaration of main() looks like this:

int main() {

//Code goes here

}

A new one you may have also noticed is "void".  void is another type of variable.  what data does it hold?  nothing.  That may seem somewhat pointless, but it's needed for some functions to make their name special(functions need to be declared just like variables).  Ok.  Now we're going to go deep...

When a function is run, it "returns" something.  for instance, the function of query_level() returns an int.  for example:

int lev;

lev = this_player()->query_level();

So when that function runs, it becomes the int that it returns.  Follow?  I hope so :P  A function can return any type of variable.  query_cap_name() returns a string (the player's name).  What does write() return?  nothing.  it just runs, shows a message, and ends up not equalling anything.  write() is an example of a "void" function.  Here's how they look when coded:

int query_level() {

//Code

return <int variable containing the player's level>;
}

string query_cap_name() {

//Code

return <string variable containing the player's name>;
}

void write(string str) {

//Code

//No return command
}

Wait!  write has stuff in the ()s!  well, if you look at how you run those functions, they all look like this:

this_player()->query_level();

this_player()->query_cap_name();

write("Nightshade is the coolest!");

What's the difference?  well, we'll go over the -> symbol in lesson 5 I think.  the other difference is...  the first 2 functions just end with ().  write has a string in the ().  write() has to know what it is you want written, so you send it a string variable.  That variable gets used in the write() function.  Here's what I think the whole write code looks like:

void write(string str) {

  tell_object(str, this_player());

}

the (string str) part looks like a variable declaration, right?  well, that's cause it is!  the variable str is formed and contains whatever was put in the () by the code.  Now let's say I want to modify the say command...  (I'll go over it bit by bit):

int say_cmd(string str) {

//The reason it's say_cmd, is because commands you can do always have the function name of <command>_cmd().
//Whatever the user inputs after "say" gets put into the variable called 'str'.

  if(!str)
    return 0;

//If the variable str has no value, it returns an error.  why return 0?  well, if it's a special function like create() or a command, you either return 1 or 0.
//if you return 0, you're saying that the code didn't go like you wanted it to, and the game will show the user the infamous "What?".
//If you return 1, you're saying that the code ran like you wanted, and the driver can process the next command.

  if(str == "Nightshade is a dork!") {
    write("No..  You are!");
    return 1;
  }

//The person didn't do what we wanted, but we returned 1 because we (well, I) wanted a custom error.  if I returned 0 after that, the player would get both "No.. You are!" followed by "What?"
//And that would look very silly.

  message("info", this_player()->query_cap_name()+" says: "+str, users());
  return 1;
}

That isn't perfectly right, but look at the middle part (this_player()->query_cap_name()+" says: "+str).  query_cap_name() returns a string, so if you add the strings together, you get:

<Playername> says: <the message they typed in>

Note: once the return command is run, the function returns the value and STOPS.  so if the person is going to say anything, BOTH of the if() statments must be false.

In the next lesson, we'll go over some basic commands that you can use in functions such as write(), say(), sprintf(), sscanf(), message(), etc...

And at the end of the next lesson I'll have you rewrite the score command!  Yes, that's how far along we are ;)

