One Line at a Time - Module Tutorial for Legend of the Green Dragon
by SaucyWench
This tutorial uses the file in the core release called findgem.php and explains what is happening in a basic special. You should have a copy of the untouched file open as you read this - I suggest opening that file in Notepad and comparing as you read, so that you can see how it looks without my comments.
This tutorial is probably not for someone who has never, ever seen code before, but should be suitable for a beginner at php / perl. I have attempted to explain each line, and usually I treat things as if the game is a person that the code speaks to - if you are an experienced coder you will probably notice that some of my explanations are not perfectly accurate, but are easier to understand in that kind of teminology.
If you are quite new and find it all very baffling, don't dispair. Just read the next section and try to understand that. Most of this you can simply copy and paste into your own module without breaking anything. Ideally you would understand what you're pasting, but it would be a start! If you still find it too hard, it might be best to do a basic, more thorough, tutorial. I recommend www.webmonkey.com.
If you have any comments or suggestions please let me know - SaucyWench -at- gmail -dot- com =)
A word on variables:
If you are not familiar with them here is my quick explanation. Think of them as cardboard boxes. You're in a room with shelves all over the place, and as you work you need to use items, and you are perfectly neat person. EVERYTHING is in cardboard boxes. Each time you need a pen, you go to the box labelled "$pen" and wow, there is a blue pen in there. You always put it back when you finish.
You're using the pen, and a piece of paper, to write a story. You put a few words on the paper then return the pen where it came from. You put the paper into a new box labelled $story. Now, let's say you want to add to the story, or change the story. The only way to do that is to go back to the shelf, get the box named $story, and inside it is a piece of paper. We can change what is in the story. Maybe add a few lines and cross out a word or two. When you are finished, go and put the paper back in the box and put $story back on the shelf.
Mr Game comes into the room and starts taking orders from you (pretend you are the code, telling the game what to do). "Mr Game, go and read my $story!" What does the game do? He goes to the shelf, looks for a box marked $story, takes it down, and reads whatever is in the box. He always puts it back, too.
In php we simply say a name of a variable and what we want in it, like this:
$aNumber = 4;
We just told the game to look for the box marked $aNumber, so he grabbed it off the shelf, and placed a bit of paper with a number 4 in the box. (The general rule is to always put a semicolon at the end of a command.) Maybe we change our mind a moment later and want something else in the $aNumber box?
$aNumber = 10;
If you do this, the game will throw that piece of paper in the bin and put a new one in there saying 10. Usually we would not do that straight away. Usually we would use that existing number for something.
$newNumber = $aNumber + 5;
Wow! There is no box called $newNumber, because Mr Game checked all the shelves. So, Mr Game is a very good boy. He decides you must need a new box, so he makes a lovely label saying $newNumber, puts it on a brand new empty box. He then keeps going, and the code tells him to read and remember whatever is in the box called $aNumber, then add five in his head, write the answer on a slip of paper and put it in that new box. When he has done all of that there will be a piece of paper in there saying 15.
Variables don't have to contain numbers. They can contain anything you like. If they are not number values you should put it in quotes. For Legend of the Green Dragon, use double quotes unless there is a special reason needing single ones.
$color = "red";
You can use any word you like for a variable name but firstly use names that make sense so that you understand it later (and others do too). It would be dumb to use $MyFavouriteCar = "Michael Jackson", even though it would work. If I saw $MyFavouriteCar written somewhere, I expect it to contain a car... so if it is about singers, call it $singer so I don't get confused. Secondly, avoid very "code" type words, because some of them do special things. Things like $print $list $edit are a bad idea. Use $printMyWords or something like that.
About Comments
Comment lines all begin with a double slash //. That means "a note for myself, ignore the rest of this line please, Mr Game". If you leave out comments, it will make absolutely no difference to the way the code runs. It is a good idea to put lots of comments in as you code, because that way other people will understand what you were thinking when you did something. You can make a whole block of text be ignored by the game like this:
/* blah blah, my name is shannon
this file is so players can find gems in the forest.
remember to buy bread at the shop
anything else you want to remind yourself or let someone else know about */
Editing the Files
Start with Notepad. On a Windows PC, this is under Start > (All) Programs > Accessories. When you're saving (and save often!) change the file type to All Files and make sure the file name ends with .php (if it doesn't, it won't work). There is more info on text editors after the tutorial.
Lets Start.
"Find Gems",
"version"=>"1.1",
"author"=>"Eric Stevens",
"category"=>"Forest Specials",
"download"=>"core_module", instead of core_module you should put a correct website link here for others to download your completed module.
); end our array
return $info; hey Mr Game, wherever you came from, take that box of $info back with you!
} end this function here.
function findgem_install(){ we are starting another mini program
module_addeventhook("forest", "return 100;"); add a hook between this file and the forest file. A hook lets them interact. Think of them like bungy cords in a game of chutes and ladders! The forest is already set up to sometimes give the player a special event. The forest handles all the tricky part, but what this hook does here is let our file be one of those specials. When a special happens in the forest code, and it happens to be ours that is chosen (yay!) the forest uses that "hook" to jump down and do our code, and when it's finished, it will bounce back up that hook and continue exactly where it came from. "return 100" means, give our special 100% of the chance that it is allowed to have fairly. We could set 50 instead, to make it happen half as often as the others... or perhaps 10 to make it quite rare.
module_addeventhook("travel", "return 20;"); exactly the same, but in travel instead of the forest. If your server has only one city, therefore there is no travel, it's ok, the other file will look after that.
return true; a beginner can ignore this for now. Just make sure it's there. There's no need to really understand it for now. Bascially, if there is no other type of "return" needed (that you know of), put in return true, and the game will go back where it came from saying, "everything is fine".
}
function findgem_uninstall(){ Hello Mr Game, please do all these special things if someone uninstalls me! Our module doesn't have anything special that will need to be fixed if it gets uninstalled, so there is nothing in our uninstall function.
return true;
}
function findgem_dohook($hookname,$args){ We would use this section if it was an item that we hooked to another place or event - for example, if we want them to gain some gold at every new day, or lose a turn every time they visit the village, or display some text if they go into the Inn. We have left this empty function in place anyway, because it is a good idea to follow the game convention (that means, make all the files look the same to help each other read them easily).
The items in the () are values the other areas have brought with them. The other areas bring those two boxes with them to use while they run though all the amazing things we didn't do but could have. They are another thing a beginner can leave for lesson ten.
return $args; The part up there in the () means that another file, when reading this one, has brought with it the box called $args. Usually when we tell a file to bring a box of information with them, they are going to unpack the box, fiddle with the contents, do something to them and then do something else. Once it had finished doing all the things we might have coded in that function there, we use "return $args" to tell it to take the new, changed info in that box, pack it up and go back where they came from. In our case we did nothing in the function, so nothing happens, and it takes the box back exactly how it was when it arrived.
}
function findgem_runevent($type,$link) { In our case, we are making a special, so it was either Travel or Forest that has been sent over here on a mission, and they are carrying a box of stuff to use while they are here. $type happens to contain some info on whether it is a travel or forest event. $link just tells it what web page to go back to. Neither one is vitally important to understand just now, so just put them both in if you are making a special event like we are.
global $session; global tells us that we need to pay attention to the variables (boxes!) that are used in the *entire* game. Mainly, these are the special ones for a player's stats. The player's information always begins with $session and is always followed with square brackets (because it is an array!). If you forget to put this line and ask Mr Game to work with boxes called $session, he will not know where they are, he will assume they don't exist, and he will take a new, empty cardboard box and write the word "session" on it. You will then be quite annoyed when the calculations always come back as empty! No, Mr Game, I don't want an empty box, I want you to use the box that the rest of the game uses. The global (everywhere) box that we all share. It's in the hallway, go out and get it and bring it in here.
output("`^Fortune smiles on you and you find a gem!`0"); output is our print statement to put words on the user's screen. `0 resets the colour. Try to use this on the last output in each section, so that the colour doesn't "bleed" into something else the game might put on the screen underneath.
$session['user']['gems']++; Open the Global variable box for this user's gems, read the number on that paper, then add one in your head, write the answer on a new piece of paper, put it in the box and put the box back. Putting a double plus sign is shorthand for "add one to the total". For more info you should Google "PHP Operands".
debuglog("found a gem in the dirt"); We keep a player log for later when they complain they don't know where this gem came from. The game will work without them, but a good idea to use debuglog when they lose anything important like, lost all their turns.
}
function findgem_run(){ this is where we would put the codeif we made a shop, or wanted this module to put some words on the screen in the Inn, or do something amazing in the Graveyard. Since all we are doing is making a forest special event, nothing happens here at all!
}
?> close our php file. Some php files are sensitive to white space, so make sure there is nothing after the > .
Notes
There are many other tutorials out there. Most don't address LoGD in particular. If you feel that you've done this one with relative ease, my next recommendation is to take sampleshop.txt from here, and create your own shop. This is the building block of most modules in the game. In its case, it does not charge you anything - that's ok, start by changing the text, and have it give you useless trinkets instead. Once you have done that, look into other shops like the kitchen, or the ghost hut, to see how they do things, and change it to let you take only one each day, or as many as you like. Then change it to charge you a fee, change it to tell you that you haven't enough gold, and so on. You will need to rename the file to sampleshop.php - if you do that in Notepad remember to choose All Files from the drop-down menu in the Save As dialogue!
There is a complete list of the operands and functions used in PHP at www.php.net . It also has complete information on all aspects of the language. I have avoided using these for beginners as they are not geared towards a beginner in any way, shape or form. If you're an experienced coder in another language you may find it more useful than I did.
Author Credit
Remember to credit the original author. More information is available on www.DragonPrime.net - a place I highly recommend you visit and become involved in. It is the module community of LoGD and a very supportive place to gain assistance and show the world your code. The guidelines adopted by the DragonPrime community are:
If you use another person's file as your template, always take out these lines:
// addnews ready
// translator ready
// mail ready
If you did not change the code, but only the text (for example, if you used the Kitchen to create a Liquorice shop, but the effects are similar) it should say ", text modifications by ". Example for a new shop: Shannon Brown, text modifications by Some Dude.This is probably how your first few modules will look.
If you add to a file: ", additions by ". Example for Petra: Shannon Brown, custom tats by Lonny Luberts
If you used the person's code as a framework and changed a few things, but it was still not your main code, it should say, ", based on by ". Example for the Jewelry Monster: Shannon Brown, based on tatmonster by Chris Vorndran
If you used creative input from someone else, it should say, ", concept by " (or similar) Example for the Experience Bar: JT Traub based on idea by Dan Van Dyke
At the time of writing this (4 November 2005) ALL races are descended from modules by either Eric Stevens, Chris Vorndran, or Shannon Brown - if you use one as a base for your own, and module information only has one name, it is missing its credit to one of us.
At the time of writing this (4 November 2005) ALL specialties are descended from modules by either Eric Stevens or Ben "blarg" Wong - if you use one as a base for your own, and module information only has one name, it is missing its credit to one of them.
::: Made with CoffeeCup : Web Design Software & Website Hosting :::