Script Language Reference and Guide

[TheGreatCthulhu]

It'd be great to get some examples of why you might actually use some of the more complicated parts, specifically I was thinking of enumerations (cause I didn't know what they were before, but now I'm not sure why I would want them (in a script, at least))

You're right: enumerations aren't all that common in scripting languages; but they provide a neat way to group related constants (for example, the meaning of lever positions). They are more useful in some languages than others; generally, on an object-oriented language, you'd use enumerations for the "magic number"-type constants, and for flags, both of which are intended to be passed as function arguments, and you'd use constants for things like the value of pi, or max and min values of something, etc.

Now, here's the thing with enums. When you have a lot of constants defined, you might confuse some of them: you can use enums to let the compiler catch any errors for you. This is because the compiler won't let you pass in constants from one enum when another is expected, and it won't let you pass "raw" integers either (that is, it won't allow for an implicit conversion - you may chose to force a conversion, though).
It's always better to set up things so that the computer can spot errors, since it's much better then a human for that job.

In Amnesia specifically, you might never use them and do just fine; however, I wanted to explain them anyway, so that people know enums are at their disposal.

and reference parameters (cause I've only found 1 excuse to use them so far, and they kick ass).

Please do share the code! Anyway, reference parameters may be of use in certain situations (like multiple returns, or using an output parameter, while returning an error code from the function), especially when reference types like strings, arrays, and ultimately, classes are involved. Note that all predefined functions take strings as (inout) references - I wanted people to understand what that means.

Since HPL3 will use a lot of classes and objects (which I intend to cover as well), and since objects are often passed around by reference, knowing about references (and something similar - object handles) will pay off in the long run.

Aside from that, there's a couple of very, very slight knit-picky suggestions
1 - Theres a bit of a problem in the enum section, where you've provided an example of a couple of items that they player may define stats for, you have this...
HealingPotion vial = HealingPotion::Small;
HealingPotion leatherArmor = BodyArmor::Small;

Forgive me if I am mistaken, but it should be BodyArmor leatherArmor = BodyArmor::Weak;

Will correct soon.

2 - Do you think that the input-output reference parameter, for the sake of readability would be better when explicitly written as &inout ? I was surprised when you said it would be preferable to just use &, I figured given that you'd pointed out that its better to explicitly write things like HealingPotion::Small; rather than just Small; for the sake of clarity, that similar rules should apply elsewhere, particularly as accidentally returning modified variables could be a real pain in the A to debug

There are several reasons I prefer using just &:

• When writing, say, string&, it can only be an inout reference, and nothing else
  
• The in- and out- references are rather specific to AngelScript; in most other languages, there's just "reference", and it's equivalent to the inout reference of AS. This is what is generally meant when someone talks about passing by reference, and this is the reason why the creator(s?) of AS decided to provide an alternate notation solely for the concept of inout reference. Besides, references in C++ use the notation typename& as well, and people might be familiar with that.
  
• The Engine Scripts page on the wiki lists all inout string parameters as string&, not strint &inout, so I wanted to be consistent with that.
  

P.S. Armour, not Armor, and while we're at it, colour and too

American English vs British English - a matter of preference.