A.G.S. v2.21
Text Script Commands Manual by Spyros

AnimateCharacter (int charid, int loop, int speed, int repeat)
Starts character CHARID animating. See the description for AnimateObject for more details, as this command is identical to AnimateObject except it works with characters. If the character is moving it will be stopped.
Example: (Animate a character using view 5, loop 4 and wait until the animation has finished )
SetCharacterView(NAME,5);
AnimateCharacter(NAME,4,0,0);
while (character[NAME].animating) Wait(1);

AreCharactersColliding (int charid1, int charid2)
Checks if character CHARID1 is touching CHARID2. This function just checks the base line of both characters, so that if one is standing a fair distance behind the other, it will not be marked as colliding.
Returns 1 if the characters feet are touching, 0 otherwise.
Example: (Make character NAME1 stop moving if he falls on a walking NPC character NAME2 )
if (AreCharactersColliding (NAME1,NAME2)==1) StopMoving (NAME1);

ChangeCharacterView (int charid, int newview)
Changes the normal view number of character CHARID to NEWVIEW. This is useful if, for example, you want the character to change the clothes they are wearing, and so permanently alter their view number.
Example: (Change character's NAME view from normal to 5)
ChangeCharacterView (NAME,5);

FaceCharacter (int charid, int tofaceid)
Turns the graphic of character CHARID so that it looks like he is facing character TOFACEID. This involves changing the current loop of CHARID to the appropriate loop number, and setting the frame number to 0 (standing).
Example: (Make character NAME1 face character NAME2)
FaceCharacter (NAME1,NAME2);

FaceLocation (int charid, int x, int y)
Similar to the FaceCharacter function, except that this faces the character to screen location (X,Y). This allows him to face not only other characters, but also objects and hotspots as well (you can get their co-ordinates from the Ask Position feature in the Room Editor).
Example: ( Make character NAME face left )
FaceLocation (NAME,-1000,100);

FollowCharacter (int charid, int chartofollow)
Tells the character CHARID to follow CHARTOFOLLOW around, wherever he goes. You could use this command to have a group of main character who go around together, or for example when the hero has rescued someone from the bad guy, they can follow the hero home. Pass CHARTOFOLLOW as -1 to stop the character following.
Example: (Make character NAME2 follow character NAME1)
FollowCharacter (NAME2,NAME1);

FollowCharacterEx (int charid, int chartofollow, int dist, int eagerness)
Does the same thing as FollowCharacter (see above), but allows you to set extra parameters.
 DIST sets how far away from CHARTOFOLLOW that CHARID will stand. If DIST is 1, they will try to stand very close; if DIST is for example 20, they will stand about 20 pixels away.
EAGERNESS sets on average how long the character will stand around before checking if he needs to move again. Setting this to 0 means that he will always be on the move until he reaches CHARTOFOLLOW; setting this to 99 means that he will pause and think for a while on route. Values in between specify different lengths of idle time. The default values are DIST=10 and EAGERNESS=97.
As a special case, setting DIST=0 and EAGERNESS=0 makes CHARID behave as if it is chasing CHARTOFOLLOW - it will try and get there as quickly as possible. Setting EAGERNESS=0 also tells the character not to stop when they reach
CHARTOFOLLOW, but instead to randomly wander around the character - useful perhaps for a very energetic dog or something.
Example: (Make character NAME2 follow character NAME1 at a distanco of 10 pixels )
FollowCharacterEx (NAME2,NAME1,10,97);

GetPlayerCharacter ()
Returns the current character which the player is controlling.
Example: (In games where you can control more than one character make each one tell a different thing )
if (GetPlayerCharacter()==2) DisplaySpeech (2, "My name is Tom");
else if (GetPlayerCharacter()==3) DisplaySpeech (3, "My name is Jerry");

MoveCharacter (int charid, int x, int y)
Moves the character CHARID from its current location to X,Y. CHARID can be either the character's number (as GetPlayerCharacter returns) or its ID set in the Room Editor.
If the character cannot get to X,Y it will be moved as close as possible.
Note: this function only works with characters which are on the current screen.
Note: if you need to find out when the character has reached its destination, use the character[charid].walking variable.
See the variables section below for more information.
Example: (Make a character walk to 120,100 and wait until he reached there)
MoveCharacter (NAME,120,100);
while (character[NAME].walking) Wait(1);

MoveCharacterBlocking (int charid, int x, int y, int direct)
Moves the character CHARID to location (X,Y), waiting until they arrive there before returning to the script.
If DIRECT is 0, this acts like MoveCharacter; if it is 1 then this acts like MoveCharacterDirect.
Example: (Make a character walk to 120,100 ignoring walkable areas and wait until he reached there):
MoveCharacterBlocking (NAME,120,100,1);

MoveCharacterDirect (int charid, int x, int y)
Moves the character CHARID from its current location to (X,Y) directly, ignoring walkable areas on the screen.
This is identical to the "Move to, ignore walls" animation command.
Example: (Make a character walk to 120,100 ignoring walkable areas
MoveCharacterDirect (NAME,120,100);

MoveCharacterStraight (int charid, int x, int y)
Moves the character CHARID from its current location to (X,Y) in a straight line as far as is possible before hitting a non-walkable area. This is useful for use with the arrow keys for character movement, since it guarantees that the character will move in a straight line in the direction specified. This function is non-blocking.
Example: (Make a character walk to 120,100 in a straight line )
MoveCharacterStraight (NAME,120,100);

MoveCharacterToHotspot (int charid, int hotspot)
Moves the character CHARID from its current location to the walk-to point for the specified hotspot. If the hotspot has no walk-to point, nothing happens.
This is a blocking call - control is not returned to the script until the character has reached its destination.
Example: (Move character to hotspot's 7 walk-to point )
MoveCharacterToHotspot (NAME,7);

MoveCharacterToObject (int charid, int object)
Moves the character CHARID from its current location to a position just below the object OBJECT.
 This is useful for example, if you want the man to pick up an object.
This is a blocking call - control is not returned to the script until the character has reached its destination.
Example: (Move character to object number 6 )
MoveCharacterToObject (NAME,245,5);

ReleaseCharacterView (int charid)
Allows the engine to automatically control the character's view, as normal. Use this once you have finished doing the animation which you started with the SetCharacterView command.
Example: (Set character's view to 10, animate using loop 4 and then change the viw back to normal )
SetCharacterView (NAME,10);
AnimateCharacter(NAME,4,0,0);
while (character[NAME].animating) Wait(1);
ReleaseCharacterView (NAME);

SetAreaLightLevel (int area, int level)
Changes walkable area number AREA to have light level LEVEL. This does the same thing as the Light Level buttons in roomedit, but allows you to
change it at run-time.
AREA is from 1 to 15 (the walkable area number), and LEVEL is from -100 to 100. (0 is the defualt non-lit level).
NOTE: The light level will be reset when the player leaves the room, so you need to use it in Player Enters Screen if you want a permanent
change.
Example: (To change the light level of an area depending on a GlobalInt )
In the PLAYER ENTERS SCREEN of the room:
if (GetGlobalInt(10)==0) SetAreaLevel (4,-50);
else SetAreaLevel (0);

SetCharacterClickable (int charid, int is_clickable)
Sets whether the character CHARID is recognized as something which the player can interact with.
This allows you to modify the "No interaction" tick-box set initially in RoomEdit.
If you pass IS_CLICKABLE as 1, then the player can look at, speak to, and so on the character (as with the old Sierra games).
If you pass IS_CLICKABLE as 0, then if the player clicks on the character it will activate whateveris behind them (as with the old Lucasarts games).
Example: (Make the character ignored by the mouse )
SetCharacterClickable (NAME,0);

SetCharacterIdle (int charid, int idleview, int delay)
Changes the character CHARID's idle view to IDLEVIEW, with a timeout of DELAY seconds of inactivity before it is played. Inactivity is defined as when the character is not moving and not being animated. Setting DELAY to 0 causes the idle view to be looped continuously when the character is not moving - this is useful when for example the character is swimming and they need to tread water when idle.
Pass IDLEVIEW as -1 to disable the idle view completely.
Example: (Make a NPC animate continiously using view 12)
SetCharacterIdle (NAME,12,0);

SetCharacterSpeed (int charid, int newspeed)
Changes the character CHARID's walking speed to NEWSPEED.
The values used for NEWSPEED are identical to those set in the Room Editor for walking speed.
NOTE: This function CANNOT be called while the character is moving, so you must stop him first.
Example: (Change character's speed to 8)
SetCharacterSpeed (NAME,8);

SetCharacterTransparency (int charid, int amount)
Sets character CHARID to be AMOUNT % transparent. This works in a similar way to SetObjectTransparency - see that description for more information.
Example: (Make the character semi-transparent)
SetCharacterTransparency (NAME,50);

SetCharacterView (int charid, int view)
Sets character CHARID's view to VIEW. This can be used to perform animations with charaters, for example bending down to pick something up, which don't use the default view.
NOTE: This function locks the character's view to the specified view, so that it can only be changed by other script commands (ie. it won't automatically be changed by the program on shadow areas, screen changes, etc). When you are done with the animation, call ReleaseCharacterView to allow the program to take control back.
Example:( Change character's view to 10)
SetCharacterView (NAME,12);

SetPlayerCharacter (int char_id)
Changes the character which the player controls to CHAR_ID. You can either use the character's number, or the ID string set in the Room Editor. This function will also cause the room to change to the room which the chosen character is currently in. (It calls NewRoom with the character's room, so the change won't happen until the end of the script).
Note: The "player" global variable is not updated with the new character; so using "player.x", "player.name" and so on will change the original character, not the current player character.
Example: (Change the player to NAME2)
SetPlayerCharacterIdle (NAME2);

SetTalkingColor (int charid, int newcolor)
Changes the character CHARID's speech text color to NEWCOLOR. This could be useful if in a particular room, the background colour is very similar to the speech colour, so you can override it using this function.
NEWCOLOR is the colour slot index from 0 to 255.
Example: (Change the talking colour of character NAME2 to 15);
SetTalkingColor (NAME2,15);

StopMoving (int charid)
Stops the character CHARID moving and sets its graphic to the standing frame of the current loop.
Example: (Stop the character NAME1 if he falls on a walking NPC character NAME2)
if (AreCharactersColliding (NAME1,NAME2)==1) StopMoving (NAME1);

GLOBAL VARIABLES

*character[CHARID].x
X co-ordinate of the character (see Note1 below)
Example: ( if the player passes a border at x=100 make him say a message and walk 10 pixels back )
if (character[NAME].x>100)
   { DisplaySpeech (NAME, "I can't go further now ");
      MoveCharacterBlocking(NAME, character[NAME].x-10,character[NAME].y); }

 *character[CHARID].y
Y co-ordinate of the character
Example: (Make the character arise to the top of the screen like it's kidnapped by aliens )
while (character[NAME].y>0)
          { character[NAME].y--;
            Wait(2); }

character[CHARID].name
 The character's full name
Example: (Display the players name on GUI 2 label 1)
string name;
StrCopy (name, character[CHARID].name );
SetLabelText(2,1,name);

*character[CHARID].walking
Whether the character is currently moving
Example: (Wait for the character to reach his destination and then execute the rest of the script )
while (character[NAME].walking) Wait(1);

*character[CHARID].animating
Set to 1 while an AnimateCharacter animation runs
Example: (Wait for the character to end the animation and then execute the rest of the script )
while (character[NAME].animating) Wait(1);

character[CHARID].talkview
The character's talking view number (-1 for none)
Example: (Change the character's talking view to 5)
character[NAME].talkview=4 (Note that talking view = game view-1, so that command sets the talking view to 5 )

player.[x,y,name,...]
Alias to character[EGO]. Note: only set at game start, does not update if you change the player character.
Examples:
Same as for character but it refers only to the original player.