___  _____  _____  ____     _____  __    ____
 / __)(  _  )(  _  )(  _ \   (  _  )(  )  (  _ \
( (_-. )(_)(  )(_)(  )(_) )   )(_)(  )(__  )(_) )
 \___/(_____)(_____)(____/   (_____)(____)(____/
   __    ____  _  _  ____  _  _  ____  __  __  ____  ____  ___
  /__\  (  _ \( \/ )( ___)( \( )(_  _)(  )(  )(  _ \( ___)/ __)
 /(__)\  )(_) )\  /  )__)  )  (   )(   )(__)(  )   / )__) \__ \
(__)(__)(____/  \/  (____)(_)\_) (__) (______)(_)\_)(____)(___/

Documentation
(c) Q42 2003, written by Martin Kool

Note 1: Please post your questions at the forum at www.agigames.com instead of mailing me
 Note 2: If you don't want to read too much, skip to Chapter 10 immediately.
Note 3: Sorry if this documentation is incomplete, not clear or has typo's. I wrote it pretty quickly ;)

1. About the files in this package

In this package you should find the following files:

The only two files of this project you'd be editing are the locations.js and actors.js files. They are also commented, to make editing even more easy.

2. The basics

The gaming world consists of locations and characters. Both of them are built with images and a tiny bit of code. So basically, we need to grab some screens from the original game or by using the cool tool called AGI Studio, and then open the locations.js file in our text-editor to add some lines of text there.

This document will describe most key parts of building this world. Each part explains a bit about what it's all about, and ends with a list of reminders or checks you need to keep in mind. All these lists of reminders are combined in the end, in the "Full Reference". That containts all nessesary information. To tell you the truth, the Full Reference is the most important part of this document. The rest is just about explaining some stuff in detail. If you are an experienced programmer or you've read this document already, then all you need to check out is the Full Reference.

3. Grabbing and editing images

Like we said, a location is based on ONE background image containing the static items, and some doors and tables placed over it as different png images (or animated .gif files). In the original games, some static content is added later as an object. In our case, if it isn't a door to open/close, or a table to walk behind/in front of, add it to the static background image!

So, when using AGI Studio to extract a background still from an original game, check (by playing the game?) if you should grab a still from the running game as well, and combine certain elements...

Reminders:

4. Locations

Now that we've created all .png files, we need some html code to position things correctly and allow our character to walk where you think would make any sense. The engine just loads the locations you create in locations.js, so let's have a quick look at our basic location template shall we?

Location.prototype.locationNAMEHERE = function() {
this.html = "<img label='layer0' src='world/img/yourimagehere.png' style='z-index:0; position:absolute; width:320px; height:168px; top:0px; left:0px' />"
this.polygons = [ { allow:true, coords:[[0,0],[320,0],[320,168],[0,168]] } ];
this.startAts = { center:{ x:160, y:84, direction:'down'} };
};

Wow, what was that all about? Well, if this is the first time you have seen javascript, here are some very basic things that you'll find interesting to know: So, still it seems tough then? Really, in fact it is dead easy. Let's go through it briefly, line by line. You can forget the Location.prototype.locationNAMEHERE line for it merely adds a location to the main engine, which is done by a fancy thing we call "prototyping" (but you should instantly forget that I said that).

First we specify that our location has some html. The word "this" really points to our location object, so we can tell what "this.html" should be. As you can see, the html consists of only 1 image tag, with a style property to position it correctly on the screen. The second line says something about polygons. A polygon is any kind of shape, created by a series of coordinates. The polygons line here states that there can be more polygons, only this example uses only 1: a polygon that allows full walking in this screen (0,0

  • 320,168). More about polygons later in this document. Then, we have to give this location some possible positions for our hero to start. Normally these would be places he/she enters from another adjacent location, or in this case a "center" position to start somewhere in the middle of the room. Also, more about startAts later.

    Reminders:

    5. Walking in front of and behind objects

    You know about x and y axis right? That's where our hero is standing. Now, consider the bottom pixel of a character's feet his z-axis. This means, how far in 3-D he is standing. "The bottom pixel of his feet? That means z-axis is same as the y-position!!!". Correct. So, the y-position of our hero directly specifies his position in 3-D. Now, each <img ... > element has a z-index value, which means: If the hero moves above this pixel, he is behind it, and if our hero moves below this pixel, you will fully see him. Just experiment with it and you'll see how it works.

    Reminders:

    6. Polygons

    The area we are allowed to walk in is specified by defining one or more polygons. One polygon is a mere set of coordinates to define a certain shape, and an explicit property called "allow" to define that if walking is allowed there or not. Also, you can attach a special property called "action", which will be fired upon entering that certain polygon.

    While our hero is walking, at each step the polygons are checked in the order they are in the locations.js file. As soon as our hero is fully inside one , checking is stopped because we know we ARE or are NOT allowed to walk any further (specified by the "allow" property remember?). So, if you want to have a shape that DOES NOT allow walking, INSIDE a bigger shape that DOES, then first specify the smaller one, because when the bigger one is found first, the rest is not checked. Sounds difficult? If you want to create a hole in a piece of paper, you first need to have the piece of paper! Well, just check the locations.js file or read this text again until you get the idea.

    Polygons can be created very easily by using the development kit. Just check the checkbox and click the coordinates that you want. Then just copy and paste the coordinates in your polygon (in the locations.js file).

    Reminders:

    7. Starting positions

    This is quite easy. You just want a room to have one or more places for the characters to start. These are called startAts, and consist of a name (any name), an x and y position and of course the direction for our hero to face. When an actor in a location walks on a certain polygon which looks like this

    this.polygons = [{ allow:true, action:['changeroom','HQ','topright'], coords:[[0,75],[5,75],[5,89],[0,89]] }];

    The action 'changeroom' is called. This will draw the 'HQ' room and place our character on the startAt position defined as 'topright'. One more thing about that: the 'allow' in this polygon can actually not be used for allowing to walk on this walkrect, since we're immediatly changing rooms and repositioning the actor. That's why it has a different meaning here: allow:true means keep on walking in the next room, allow:false means stand still there.

    Reminders:

    8. Animations

    I won't go into animations right now. If you got the hang of creating rooms and you want to add animations other than "static" animated .gifs, you might want to check out the original code of the HQ location, which has an interactive door.

    9. Actors

    Check out the included howtobuildactors.html for a full reference on how to build actors. The excellent documentation was written by Patrick Schiess! Also, I've written a lot of comments in the actors.js file, so when you read that it'll all become clear too.

    Keep in mind the fact that AGI Studio shows an actor frame twice the size as it really is, and that the rules about grabbing and editing images (chapter 5 in this document) apply for actors as well. Just look at the examples!

    10. Full Reference

    Ok, a location/room is a set of .pngs on top of eachother, some transparent, some not. In the locations.js file, just edit some of the script of the desired room to reflect the correct html, positioning, walking area and starting points. Here are the key aspects:

    Images

    Scripting: html

    Scripting: polygons

  • the area to walk in is specified by a series of polygons
  • any x or y pixel position is based upon the VISIBLE image size, NOT the half-sized version on disk!
  • polygon properties are :
  • polygons are not affected by the left and top offsets of your images. In other words, the easiest way to find all values are by hovering your mouse in Paint Shop Pro over the cropped but NOT resized image.
  • place the polygons in this order: polygon A must be before B when A is (partially) INSIDE B, otherwise A will not be checked

    • Scripting: startats