W.I.P Amnesia: M.I.A - Printable Version

Spoiler below!

First off, you need a good scripting program to do this stuff in! (Excuse my excessive use of exclamation points) Personally, I use Notepad++ but other people use Geany. Both are wonderful programs.

The thing about scripting is that it's very fussy because you're telling a computer what to do, not a human. If you told a computer to go get you a cup of coffee, you would have to tell it to walk 5 steps to the door, turn the handle, open the door, go through the door, walk 10 steps forward, turn right, grab a cup, turn left, walk 2 steps to the coffee machine, turn right to face it, place the cup in the machine, turn the coffee machine on, add the coffee beans, add the water, press the start button, and so on and so forth. If you're talking to a human, you could just say "go get me some coffee, peasant!" and they would (hopefully) obey your orders and not spit in your beverage.

In C++, your script is CaSE sEnSiTiVe if you typed "Void onLeave" instead of "void OnLeave", your computer will have a tantrum because it doesn't understand you. Make sure you spell everything correctly and don't forget to capitalize your letters where needed.

On this topic, your engine scripts are like orders. You finish orders with periods (or exclamation points if you're really excited)! In C++, a period is a semi-colon (;) If you forget the period, the computer thinks you haven't finished talking to it, so it keeps looking for that semi-colon all the way through the file. It might find other semi-colons, but it ends up one short, so it'll put the error at the end of the file (ERROR: Unexpected end of file).

Scripting Language
-------------------------------------
In Notepad++ (and in Geany), there is a Language drop-down menu at the top. Since Amnesia uses AngelScript (a derivative of C++), you'll want to set the language to C++. This way, your functions will be colour-coded. It's a million times easier to find errors when something's not the right colour.

If you clicked the link for the Engine Scripts, you'll notice there are a few terms repeated throughout the page: string, int, float, and bool.

A string is a piece of text, like the name of an object. Strings are enclosed in quotations and will show up grey.

Code:
"This is a string"

Both integers and floats show up orange in Notepad++; integers and floats are numbers. The main difference between a float and an integer is that integers do not have decimal points (1, 2, 100, -53, 1024 are integers). Floats have decimal places (3.14159265, 1.628, 0.0001, 1.1, and 10000.1 are floats).

Code:
1.0f

1

The first is a float and the second is an integer.

Bools are true and false values. These are mainly used to set certain entities active or inactive (such as monsters). Bools show up in blue text.

Code:
SetEntityActive("monster_1", true);

The above code would be used to make the in-map monster active (active just means that it magically pops into existence).

There's another, slightly important feature which is not in the engine scripts: text comments. By putting two forward slashes in front of a piece of text, you're telling the computer to skip what's written there. These comments show up in green.

Code:
//This is a comment, which will not be read by the computer

Alright, now that I've kind-of explained what each thing is, let's get on to something more interesting.

Script Files
------------------------------------------
Every single one of your maps should be paired with a .hps file which has the exact same name. For example, if your map is named "reallyawesomemap.map", then your script file should be "reallyawesomemap.hps". To get the .hps extension in notepad++, just type the extension after the name when saving your file.

There are a few things which you should always always always include in your script file: OnStart, Intro, OnEnter, and OnLeave. They will look like this:
(php code colouring is slighlty different from notepad, but this is just to show you what the colour-coding potentially looks like).

PHP Code:
void OnStart()
{

}

void Intro()
{

}

void OnEnter()
{

}

void OnLeave()
{

} 

And now that I think I have explained everything in a haphazard manner, let's put it all together and write a script. In this script, we're just going to set a monster active and change the colour of a light to red when the player walks through a script area. To do this, we're going to use these three functions:

PHP Code:
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates); //for triggering the event when the player walks through an area
void SetEntityActive(string& asName, bool abActive); //for setting the monster active
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime); //for changing the colour of the light 

PHP Code:
void OnStart()
{
AddEntityCollideCallback("Player", "Area_ScaryEvent", "Script_ScaryEvent", true, 0); //the PLAYER collides with SCARY EVENT AREA to trigger the SCARY EVENT SCRIPT, which cannot be triggered twice (DeleteOnCollide = true) and can be triggered when entering, exiting, or standing in the script area (the 0 int at the end).
}

void Script_ScaryEvent(string &in asParent, string &in asChild, int alState) //make sure the name of your script is the same here as it was when you labelled it earlier
{
SetEntityActive("monster_1", true); //Sets the monster which, in the level editor, is named "monster_1" active
FadeLightTo("Pointlight_1", 1.0f, 0.0f, 0.0f, 1.0f, 5.0f, 1.5f); //Makes Pointlight_1 red (afRed = 1.0, everything else is 0.0, but could potentially be numbers in-between if you wanted), with a radius of 5.0, over a period of 1.5 seconds.
} 

That's it! That's scripting :D It's not as scary as it sounds! Now go out there and make some majestic scripts!

Oh, and if you have any more questions on how to do specific things, you can PM me, ask in the Development Support section, or take a looksie at other people's scripts (the ones in ATDD have comments explaining what most of the parts do, which is really helpful).

Now seriously, go make some beautiful scripts!