Who this tutorial is for
This tutorial is for developers new to KQ.
This tutorial assumes you know basic lua syntax. I do not explain the syntax at all. If you do not know basic lua syntax, you may be able to figure it out from the context in this tutorial. If you have trouble understanding the lua code, you can learn about lua at the official lua website.
In this tutorial, you will be using the mapdraw2 program, which comes with KQ, to make map files. Sometimes, the word "map" refers to a tile based file. In this document, map means the tile based file and the lua script that accompanies it. In this tutorial, you will learn how to create a simple map, with a few trees, and an inn. After the next tutorial, you will be able to walk into the inn and sleep for the night.
Mapdraw2 can not do everything, and so you will be using mapdraw where mapdraw2 falls short. You will also be using a text editor to write the lua script. A lua compiler is not required for this tutorial. "Preparing" (don't worry if you don't know what that means) is also not required for this tutorial.
If you wish to use this tutorial, you should either install the latest KQ release (July 2007 or newer), or a recent CVS version. Distribution specific packages sometimes do not include mapdraw2, and if they do, it might be too old; your mileage may vary.
If you find a bug in this tutorial, please report it at the sourceforge bug tracker as a documentation bug. Even better, you can log in to this wiki and fix it yourself.
If you are using the latest CVS version (Sept 1, 2007 or later) you do not have to put the script in the KQ scripts directory as tutorial1.lob. You can save it as tutorial1.lua. When KQ is requested to load a script, such as tutorial1, it first looks for tutorial1.lob in the KQ scripts directory. If it can not find tutorial1.lob, it then looks for tutorial1.lua.
Part 1 - Creating your first map file
First, you need to download, build and install KQ. If you need help using CVS, read http://sourceforge.net/cvs/?group_id=61344. To build and install KQ, read the README file.
The next thing we need to do is to create a new, empty map file. mapdraw2 is not capable of doing this, so we will be using the older, more functional, but less friendly, mapdraw. Change directory to maps in your KQ source directory. Run mapdraw. Press "n" for new map. Make it 50x50 tiles. Use tileset 1, which mapdraw will say is "newtown.pcx". Press "F3" to save this map. Save it as "tutorial1.map". If you are curious about mapdraw, press "F1" for help, but for now press "q" to exit.
Now, run "mapdraw2 tutorial1.map". You should see a screen like the following. It will help if you resize the vertical slider so that your palette is the same width as mine. My palette is twenty icons wide.
Before we continue, you should know about layers. KQ maps have three layers. Layer 1 is the ground. When you are playing the game, everything in Layer 1 is drawn underneath your character. Everything in Layer 2 is drawn on top of Layer 1, but still underneath your character. Layer 2 includes things such as chairs, and beds, and tables. Layer 3 is above your character's head. Tree tops, and the arches in arched gates are in Layer 3.
Your next step is to create the first layer. Select "Layer 1" in the Layers Area. The checkbox determines whether that layer is visible or not. You can't manipulate an area unless it is visible, so leave the checkbox checked.
Now, select the first piece of grass in the Palette. It is in the upper left corner, between the blank (gray) square and the yellow button. You select a tile by clicking on it. Now, click anywhere on the map area. Notice that you have just placed a grass tile on the map area. Right-click that grass tile to delete it. Now, create a field. It should look something like this:
Notice the empty squares. You will be filling these in. First, using what you have learned about selecting and placing tiles, create the stone plaza. When you are done, it will look like the following picture. I have highlighted the palette tiles that you will be using in pink.
After you have created the stone plaza, you will create some trees next to it. Trees, because they are so tall, occupy all layers. First, add a stump next to the plaza. The stump is in layer 1. You can use any stump you want from the first row of the palette.
Now, add two tree tops in Layer 3. Notice that some tree tops have transparent pixels in their upper corners, while others are kind of green in the upper corners. Each of these tree tops have their special purpose. Use the tree top with the extra green if this tree top is covering an alleged stump. Use the tree top with the transparent pixels if it is not. I have highlighted and numbered which tree top goes where.
Now, it is time to make the inn. We will start with the parts in layer 1. This is the "bottom half" of the inn. Here is what it should look like when you are done. I have highlighted the inn tiles you will be using in pink. I have highlighted the stone tiles in blue.
Now, add the layer 3 part of the inn. This the "top half" of the inn. It will appear that your character is walking behind the inn, and that you can not see him because of the camera angle. I have highlighted the tiles you will be using in pink.
Finally, add the sign to the inn in layer 2.
Now, we will add an entity. Entity is usally a fancy word for person. Select Entity in the Layers Area. Now click on the map area near the trees. An Entity Dialog pops up. Change chrx to another number, such as 10. Notice that your character's icon changes. There is an upper limit of about 30. You can make this number whatever you want. Note that the entity icon you see here does not always correlate to the entity icon in KQ. This is a bug in mapdraw2.
Now, it is time to add obstacles. Obstacles are special, invisible tiles that prevent your character from moving onto a square. Without any obstacle tiles, your character would be able to walk on top of everything. Select Obstacles in the Layers Area. Check the checkbox, so you can see and manipulate them. Click on a tile in the Map Area. Notice the whitish square. That is an obstacle. Click on it again. Notice that the square changes to a line. These are special obstacles, that only work from certain angles. We will cover these in another tutorial. For now, we'll just use full obstacles. Now, right click on that obstacle to remove it.
Place obstacles everywhere that your character should not be able to walk, except for the entity. Entities are their own obstacles. Also, you only have to obstacle the borders. There is no need to obstacle tiles if your character can't reach them. When you are done, your map should look like this:
Now, it is time to place zones. A zone is "triggered" when your charcter moves on top of it, or when your character is facing it and presses the "action" button. We use zones to trigger random monster encounters. We also use them for special messages, such as when a door is locked, or when your character examines a bookshelf. They are also used for treasure chests, and for warping from one map to another, such as when you leave a town. You will learn more about zones, such as how to utilize them, when you learn to script for KQ. For now, you will just be placing the zones.
Select Zones in the Layers Area, and check the checkbox. There are two ways to place a zone. The first, is to edit the "Current Value" in the bottom left corner. Type the value "1", without the quotes. Now, click on the Map Area. Notice the number "1" is on that tile. Now right click on that tile to delete that zone. The second method for placing a zone is to middle click your mouse button on the Map Area. Doing so increases the zone value of that square by 1. Each square, by default, has a zone value of 0. Place zones in such a way that your map looks like this:
Now, it is time to add a marker. Markers are special "reference" squares. We use them to mark the location of a square. Usually, we use markers to mark where something is going to be placed later, such as through a script. Markers are most commonly used to specify where to warp the player, such as when entering a village, or an inn.
Select Markers in the Layers Area. Check the checkbox. Now, type the word "entrance" in the Current Value field. Now, click on the map where you want the character to appear when this map is loaded. Next to the "zone 1" on the bottom row is a good choice, but you can choose anywhere you want.
This map file is done. Make sure you save it using the menu at the top of the window. Notice that we did not cover adding shadows. Mapdraw2 can't do shadows yet. We didn't use Pink. Pink isn't a layer. If you check Pink, then all of the invisible squares will be pink, instead of the usual black. This is helpful for making sure that you don't have any stray invisible pixels that you thought were black pixels, or vice versa. Note that Pink is not something that is saved in the map file.
Part Two - Creating your first script
Here is the script that goes with this map. It is called tutorial1.lua:
-- tutorial1 - First Map function autoexec() return end function postexec() return end function entity_handler(en) if (en == 0) then bubble(en, "Hello, World!") end return end function zone_handler(zn) if (zn == 1) then change_map("main", "tutorial1") end return end
-- tutorial1 - First Map
This is a comment.
function autoexec() return end function postexec() return end
KQ calls the function autoexec() before the map is visible. It calls postexec() after the map is visible, but before the user is given control.
function entity_handler(en) if (en == 0) then bubble(en, "Hello, World!") end return end
KQ calls the entity_handler() function every time you speak with an entity. It sets "en" to be the number of the entity you are speaking with. You set this number when you wrote the map file. It is the entity's "eid" variable.
Often, entities just say something such as "Hello, World!" Sometimes, this is the function you would use to advance quest variables. Quest variables will be covered more thoroughly in a later tutorial.
The bubble function makes someone talk. It takes two arguments. The first is the number of the entity speaking. Use en to mean whichever entity you are talking to. Use HERO1 to mean you. Use HERO2 to mean your partner. Use a specific eid number if you want another entity to speak. The second string is what you want that entity to say. In this case, it is "Hello, World!"
function zone_handler(zn) if (zn == 1) then change_map("main", "tutorial1") end return end
KQ calls the zone_handler() function every time you walk onto a zone. If there is an obstacle on the zone, it calls this function when you face the zone and press the action key. "zn" is which zone you stepped on. You set the zones when you wrote the map.
The change_map function warps you to another map, at a specified location. It takes two arguments. The first is which map to warp to. In this case, it is "main", which is represented by the file "main.map". The second argument that change_map takes is which marker to warp the character to. In this case, it is the marker labeled as "tutorial1". This marker doesn't exist yet in main.map, but it will before you are done with this tutorial.
So, now you have tutorial1.map, and tutorial1.lua. Where do you put these files? On a linux system, you put map files in $PREFIX/share/kq/maps, and scripts in $PREFIX/share/kq/scripts, where $PREFIX is the prefix you, or whoever compiled KQ for you, used when compiling KQ. $PREFIX is usually either /usr/local or /usr. I'm not sure where they go in Windows. Maybe something like C:\Program Files\KQ\maps and C:\Program Files\KQ\scripts? Please change this if you know better.
Put tutorial1.map and tutorial1.lua in the appropriate KQ directories. Now, you have to change main.map and main.lua so your character can access your new map. First, backup main.map and main.lua as main.map.orig and main.lua.orig. Now, open main.map in mapdraw2. Remember, your current directory has to be the maps source directory, so that mapdraw2 can access the pcx and glade files.
Add a warp button near Nostik's manor. Make the button Zone 200. I usually use zone 200 to be a "temporary" zone. You can use any number you want, as long as it isn't taken. Currently, approximately, the first 100 zones are used by KQ. Place a marker right outside the button. Label the marker "tutorial1" (this is where we warp to when we exit the tutorial1 map). Save this file as main.map, and place it in your KQ maps directory.
Now copy main.lua from your source scripts directory into your KQ scripts directory as main.lob. lob files are usually compiled, and we are not going to compile main.lua, but that is OK. KQ will only read the lob files, but will read them even if they are not compiled. Open main.lob with a text editor, and add the following code at the beginning of the zone_handler() function:
if (zn == 200) then change_map("tutorial1", "entrance") return end
Now, start KQ. Start a new game. Exit Nostik's manor, and head to the button you added. Walk inside. Hopefully, you have just entered your first map.