AnimateCharacter (CHARID, int loop, int delay, int repeat)Starts the character named CHARID animating, using loop number LOOP of his current view. The overall speed of the animation is set with DELAY, where 0 is the fastest, and increasing numbers mean slower. The delay for each frame is worked out as DELAY + FRAME SPD, so the individual frame speeds are relative to this overall speed.
The REPEAT parameter sets whether the animation will continuously repeat the cycling through the frames. If REPEAT is zero, the animation will start from the first frame of LOOP, and go through each frame in turn until the last frame, where it will stop. If REPEAT is 1, when the last frame is reached, it will go back to the first frame and start over again with the animation.
If the character is moving it will be stopped.
Example:
AnimateCharacter(EGO,3,0,0);will animate the character using loop number 3 of his current view only once.
See Also: AnimateCharacterEx, AnimateObject, SetCharacterView
AnimateCharacterEx (CHARID, int loop, int delay, int repeat, int direction, int blocking)As AnimateCharacter, but with two extra options:
DIRECTION specifies which way the animation plays. 0 is forward (like AnimateCharacter), or pass 1 to play the loop backwards.
If BLOCKING is 1, the function will wait for the animation to finish before returning.
See the description of AnimateCharacter for more information.
Example:
AnimateCharacterEx(EGO, 3, 0, 0, 1, 1);will animate the character once using loop number 3 of his current view backwards, and wait until the animation finishes before returning.
See Also: AnimateObjectEx
AreCharactersColliding (CHARID1, 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:
if (AreCharactersColliding(EGO,MAN)==1)
{ colliding code here }
will execute the colliding code only if the characters EGO and MAN are colliding. See Also: AreCharObjColliding, AreObjectsColliding, AreThingsOverlapping
AreCharObjColliding (CHARID, int obj)Checks if character CHARID and object OBJ are touching each other. Returns 1 if they are, and 0 if they are not.
NOTE: This function checks the character's feet against the whole of the object. This is used to see if the character is standing on an object, and so on. The top two-thirds of the character do not trigger.
Example:
if (AreCharObjColliding(EGO,3)==1) { colliding code here }
will execute the colliding code only if the character EGO and the object number 3 are colliding. See Also: AreCharactersColliding, AreObjectsColliding, AreThingsOverlapping
AreThingsOverlapping(int thing1, int thing2)Checks whether two characters or objects are overlapping each other on screen. This simply carries out a quick rectangular check on the two things to decide - so if they have large transparent regions around the edges, it may seem to be overlapping too soon.
THING1 and THING2 can either be a CHARID, or can be an object number PLUS 1000. So for example, passing EGO as THING1, and 1004 as THING2, will compare the character EGO with Object 4 in the current room.
Returns 0 if they are not overlapping, or the overlapping amount if they are. This amount is an arbitrary scale, but 1 means they are just about touching, all the way up to higher numbers for more overlappingness.
Calling this function with both the parameters as objects is the same as calling AreObjectsColliding.
Example:
if (AreThingsOverlapping(1002, EGO)) {
// code here
}
will run the code if object 2 is overlapping EGO. This could be useful if object 2 was a bullet,
for instance.See Also: AreCharactersColliding, AreObjectsColliding
ChangeCharacterView (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.
NOTE: This command is not intended to change the view temporarily to perform an animation. If you want to do that, use SetCharacterView instead. This command is intended for permanently changing the character's normal walking view.
Example:
ChangeCharacterView(EGO,5);will make the character use view number 5 as his walking view.
See Also: SetCharacterView
FaceCharacter (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).
NOTE: Because this command is non-blocking, the screen will not be updated immediately. Rather, the character will face in the specified direction when your script finishes or when a blocking function is called. To force an update, call Wait(1);
Example:
FaceCharacter(EGO,MAN);will make the character EGO face the character MAN
See Also: FaceLocation, MoveCharacter
FaceLocation (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 co-ordinates by watching the co-ordinates displayed in the Room Settings mode as you move the mouse over the room background).
NOTE: Because this command is non-blocking, the screen will not be updated immediately. Rather, the character will face in the specified direction when your script finishes or when a blocking function is called. To force an update, call Wait(1);
Example:
FaceLocation(EGO,150,146);will make the character face at the room location (150,146)
See Also: FaceCharacter
FollowCharacter (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 characters 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:
FollowCharacter(MAN,EGO);will make character MAN follow the characterEGO wherever he goes.
See Also: FollowCharacterEx
FollowCharacterEx (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.
There is also another special use for this command. You can pass the special value FOLLOW_EXACTLY as the DIST parameter rather than passing a number. If you do this, then CHARID will always remain at exactly the same X and Y co-ordinates as CHARTOFOLLOW. This might be useful for effects such as a temporary halo over the character and so forth.
If you use FOLLOW_EXACTLY, then EAGERNESS has another meaning. If you pass 0, CHARID will be drawn in front of CHARTOFOLLOW; if you pass 1, it will be drawn behind.
Example:
FollowCharacterEx(MAN, EGO, 5, 80);will make character MAN follow character EGO standing about 5 pixels near him and waiting for a while before he makes his move.
See Also: FollowCharacter
GetCharacterAt (int x, int y)Checks if there is a character at SCREEN co-ordinates (X,Y). Returns the character number if there is, or -1 if there is not. See the description of GetLocationName for more on screen co-ordinates.
NOTE: Any characters with the "No interaction" flag set will not be seen by this function.
Example:
if (GetCharacterAt(mouse.x, mouse.y) == EGO) {
Display("The mouse is over the main character");
}
will display the message if the mouse cursor is over the EGO characterSee Also: GetHotspotAt, GetObjectAt, GetLocationName
GetCharacterProperty (CHARID, string property)Returns the custom property setting of the PROPERTY for the specified character.
This command works with Number properties (it returns the number), and with Boolean properties (returns 1 if the box was checked, 0 if not).
Use the equivalent GetPropertyText function to get a text property.
Example:
if (GetCharacterProperty(EGO, "Value") > 200)
Display("EGO's value is over 200!");
will print the message if EGO has its "Value" property set to more than 200.See Also: GetCharacterPropertyText
GetCharacterPropertyText (CHARID, string property, string buffer)Returns the custom property setting of the PROPERTY for the specified character.
This command works with Text properties only. The property's text will be copied into the BUFFER that you pass to this command.
Use the equivalent GetProperty function to get a non-text property.
Example:
string buffer;
GetCharacterPropertyText(EGO, "Description", buffer);
Display("EGO's description: %s", buffer);
will retrieve EGO's "description" property into the buffer, then display it.See Also: GetCharacterProperty
GetPlayerCharacter ()Returns the current character which the player is controlling.
Example:
if (GetPlayerCharacter()==2)
{ code here}
will execute the code only if the player controls the character number 2.See Also: SetPlayerCharacter
MoveCharacter (CHARID, int x, int y)Starts the character CHARID moving 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.
Control returns to the script immediately. The character will move in the background.
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 for more information.
Example:
MoveCharacter(EGO,155,122); while (character[EGO].walking) Wait(1);will make the character walk to 155,122 and return control to the player when he gets there. (in reality you would use MoveCharacterBlocking instead of this).
See Also: FaceCharacter, MoveCharacterBlocking, MoveCharacterToObject, MoveObject, StopMoving
MoveCharacterBlocking (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:
MoveCharacterBlocking(EGO,234,122,1);will make the character EGO walk to 234,122 ignoring walkable areas and return the control to the player when he gets there.
See Also: MoveCharacter, MoveCharacterDirect
MoveCharacterDirect (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:
MoveCharacterDirect(EGO,222,145);will make the character EGO walk to 222,145 ignoring walkable areas
See Also: MoveCharacter, MoveCharacterPath, MoveCharacterStraight
MoveCharacterPath (CHARID, int x, int y)Tells the character CHARID to move to (X,Y) directly, after it has finished its current move. This function allows you to queue up a series of moves for the character to make, if you want them to take a preset path around the screen. Note that this works equivalently to MoveCharacterDirect, ignoring walkable areas.
This is useful for situations when you might want a townsperson to wander onto the screen from one side, take a preset route around it and leave again.
Example:
MoveCharacter (SOMEGUY, 160, 100); MoveCharacterPath (SOMEGUY, 50, 150); MoveCharacterPath (SOMEGUY, 50, 50);tells character SOMEGUY to first of all walk to the centre of the screen normally (obeying walkable areas), then move to the bottom left corner and then top left corner afterwards.
See Also: MoveCharacter, MoveCharacterDirect
MoveCharacterStraight (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:
MoveCharacterStraight(EGO,166,78);will move the character EGO in a straight line towards co ordinates 166,78 until he hits a non walkable area.
See Also: MoveCharacter, MoveCharacterDirect
MoveCharacterToHotspot (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:
MoveCharacterToHotspot(EGO,6);will move the character EGO to the hotspot’s 6 "walk to point".
See Also: GetHotspotPointX, GetHotspotPointY, MoveCharacter, MoveCharacterToObject
MoveCharacterToObject (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:
MoveCharacterToObject (EGO, 0); ObjectOff (0); AddInventory (3);Will move the character EGO below object number 0, then disappear object 0 and add inventory item number 3 in the players inventory.
See Also: MoveCharacter, MoveCharacterToHotspot
ReleaseCharacterView (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:
ReleaseCharacterView(EGO);will return character EGO to its original view.
See Also: SetCharacterView
RunCharacterInteraction (CHARID, int mode)Processes the interaction list as if the player had clicked the mouse on character CHARID in cursor mode MODE. MODE is one of the MODE_* constants listed in the ProcessClick description.
Example:
RunCharacterInteraction(MAN,MODE_TALK);will execute the code defined in the MAN’S "TALK TO CHARACTER" interaction.
See Also: ProcessClick, RunHotspotInteraction, RunInventoryInteraction
SetCharacterBaseline (CHARID, int baseline)Changes CHARID's baseline to BASELINE. This allows you to set a specific base line for the character, which works similarly to walk-behind area and object baselines. BASELINE can be from 1 to the height of the room (normally 200), or set it to 0 to go back to using the character's feet as the baseline.
Example:
SetCharacterBaseline(MAN, 120);will move the character’s baseline ( which can be used for testing collisions, or for walk-behinds) to a line positioned at y coordinate = 120.
See Also: SetObjectBaseline, SetWalkBehindBase
SetCharacterBlinkView (CHARID, int view, int interval)Changes the character CHARID's blinking view to VIEW.
INTERVAL specifies how long the game waits between playing the animation. This is specified in game loops - an interval of 80 would play the blinking animation about every 2 seconds.
Example:
SetCharacterBlinkView(EGO, 10, 160);will change the character EGO's blink view to view 10, and play the animation every 4 seconds.
See Also: SetCharacterSpeechView
SetCharacterClickable (CHARID, int is_clickable)Sets whether the character CHARID is recognised as something which the player can interact with. This allows you to modify the "No interaction" tick-box set initially in the GUI Editor. 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 whatever is behind them (as with the old Lucasarts games).
Example:
SetCharacterClickable(MAN,0);will make the game ignore clicks on the character MAN.
See Also: SetObjectClickable
SetCharacterFrame(CHARID, int view, int loop, int frame)Sets the specified character's graphic to frame FRAME of loop LOOP of view number VIEW. This is useful if you don't want an animation, but just want to change the character to display a specific frame.
The frame will be locked to the one you specify until you call ReleaseCharacterView.
Example:
SetCharacterFrame(EGO,AGHAST,2,4); Wait(40); ReleaseCharacterView(EGO);will change EGO to have frame 4 of loop 2 in the AGHAST view, wait for a second, then return him to normal.
See Also: AnimateCharacter, ReleaseCharacterView, SetCharacterView
SetCharacterIdle (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:
SetCharacterIdle(EGO, 12, 30);will change/set the character’s EGO idle view to 12. The idle view will be played if the character is idle for 30 seconds.
SetCharacterIgnoreLight (CHARID, int ignore)Allows you to dynamically modify the "ignore lighting" checkbox for the character. Pass IGNORE as 1 for this character to always look the same, and not be affected by the light level of walkable areas. Pass 0 for this character to behave as normal and be affected by area light levels.
Example:
SetCharacterIgnoreLight(EGO,1);will make the character look the same no matter if he stands on walkable areas with different light levels.
SetCharacterIgnoreWalkbehinds (CHARID, int ignore)Sets whether character CHARID is affected by walkbehind areas. Passing 0 (the default setting) means that the character will be placed behind walk- behind areas according to the relevant baselines. Passing 1 means that the character will never be placed behind a walk-behind area. This is useful if for example you want to use the character as an overlay to display rain or snow onto a scene.
Example:
SetCharacterIgnoreWalkbehinds (EGO,1);will make the character EGO ignore walk-behinds.
See Also: SetCharacterProperty, SetObjectIgnoreWalkbehinds
SetCharacterProperty (CHARID, PROPERTY, int new_value)Changes one of the character properties, originally set in the editor. CHARID is the character, PROPERTY is which property to change, and NEW_VALUE is either 0 or 1, depending on whether you want to switch that property on or off.
PROPERTY's possible values are as follows:
CHAR_IGNORESCALING the editor 'Ignore room area scaling' checkbox CHAR_NOINTERACTION the editor 'No interaction' checkbox CHAR_NODIAGONAL the editor 'No diagonal loops' checkbox CHAR_IGNORELIGHT the editor 'Ignore room area lighting' checkbox CHAR_NOTURNING the editor 'Do not turn before walking' checkbox CHAR_WALKTHROUGH the editor 'Can be walked through' checkbox CHAR_SCALEMOVESPEED the editor 'Adjust speed with scaling' checkboxSee Also: SetCharacterIgnoreWalkbehinds
SetCharacterSpeechView (CHARID, int view)Changes the character CHARID's talking view to VIEW. The new view number will be used as the character's talking view in all future conversations.
Example:
SetCharacterSpeechView(EGO, 10);will change the character EGO's speech view to view 10.
See Also: ChangeCharacterView, SetCharacterBlinkView, SetTalkingColor
SetCharacterSpeed (CHARID, int newspeed)Changes the character CHARID to have a uniform walking speed of NEWSPEED. The values used for NEWSPEED are identical to those set in the AGS Editor for walking speed.
NOTE: This function CANNOT be called while the character is moving, so you must stop him first.
Example:
SetCharacterSpeed(EGO,10);will change the character EGO's speed to 10.
See Also: MoveCharacter, SetCharacterSpeedEx, StopMoving
SetCharacterSpeedEx(CHARID, int x_speed, int y_speed)Changes the character CHARID to have a non-uniform walking speed of X_SPEED in the horizontal direction and Y_SPEED in the vertical direction. The values used for X_SPEED and Y_SPEED are identical to those set in the AGS Editor for walking speed.
NOTE: This function CANNOT be called while the character is moving, so you must stop him first.
Example:
SetCharacterSpeedEx(EGO, 6, 3);will change the character EGO's speed to 6 horizontally and 3 vertically.
See Also: MoveCharacter, SetCharacterSpeed, StopMoving
SetCharacterTransparency (CHARID, int amount)Sets CHARID to be AMOUNT % transparent.
Setting AMOUNT to 100 means it is totally invisible, and lower values represent varying levels of transparency. Pass AMOUNT as 0 to stop the character being transparent.
NOTE: Transparency currently only works in hi-color games, and the character sprites must have been imported in hi-colour for the transparency to work.
NOTE: Having a large transparent character can significantly slow down the engine.
Example:
SetCharacterTransparency(EGO,50);will make the character EGO look semi transparent.
See Also: SetObjectTransparency
SetCharacterView (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:
SetCharacterView(EGO,12); AnimateCharacter(EGO,0,0,0); while(character[EGO].animating) Wait(1); ReleaseCharacterView(EGO);will change the character’s EGO view to view 12, perform an animation using loop 0, wait until the animation finishes and then return the character to his normal view.
See Also: AnimateCharacter, ChangeCharacterView, ReleaseCharacterView, SetCharacterViewEx, SetCharacterViewOffset
SetCharacterViewEx (CHARID, int view, int loop, align)Sets character CHARID's view to VIEW, and sets the character's current frame to the first frame in LOOP of VIEW.
The main purpose of this command is that it can align the new frame to the previous one. This is particularly useful if you want to go from the character's normal walking view to a specific animation - since the characters have the central point as their 'axis', if you have a wider animation then it can be difficult to stop yourself getting a jumping effect when the animation starts.
ALIGN can have one of the following values:
| align | Description |
| ALIGN_LEFT | Moves the new frame so that the left hand side is at exactly the same X co-ordinate as the old one was. |
| ALIGN_CENTRE | Leaves the frames centred in the middle. This is the default and using this is equivalent to just calling SetCharacterView. |
| ALIGN_RIGHT | Moves the new frame so that the right hand side is at exactly the same X co-ordinate as the old one was. |
Note that this only aligns the first frame of the animation, so to get the full benefit all your frames in the animation loop should be the same width. All following frames will be shifted by the same amount, until ReleaseCharacterView is called.
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:
SetCharacterViewEx(EGO, 12, 1, ALIGN_LEFT); AnimateCharacter(EGO, 1, 5, 0); while(character[EGO].animating) Wait(1); ReleaseCharacterView(EGO);will change the character’s EGO view to view 12, perform an animation using loop 1, wait until the animation finishes and then return the character to his normal view.
See Also: ReleaseCharacterView, SetCharacterView, SetCharacterViewOffset
SetCharacterViewOffset(CHARID, int view, int xOffset, int yOffset)Sets character CHARID's view to VIEW, in the same way as SetCharacterView does. However, it also adds a specified offset to all the character's frames until ReleaseCharacterView is called.
The XOFFSET and YOFFSET parameters specify in actual game resolution units how much to move the character's sprite. Positive values for X move right, for Y move down; negative values do the opposite.
This command is designed to allow you to cope with those niggly situations where animations don't quite line up with the standing frame, assuming all the frames of the animation are the same size. Note that SetCharacterViewEx is easier to use if your frames will align at the left or right hand side.
NOTE: You should only use this command for minor adjustments, since the offsets do not affect the clickable area of the character, what walkable area he is in, and so forth. You should limit the use of this command to in-game cutscenes where the player has no control.
NOTE: This is the only command in AGS which uses actual game-resolution co-ordinates. Therefore, specifying an x offset of 1 will actually move 1 pixel in a 640x400 game, and will not be multiplied up to 2 (they will be automatically adjusted though if the player chooses to play the game at another resolution).
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:
SetCharacterViewOffset(EGO, 12, 1, -1); AnimateCharacter(EGO, 1, 5, 0); while(character[EGO].animating) Wait(1); ReleaseCharacterView(EGO);will change EGO's view to view 12 and animate using loop 1, meanwhile all frames will be shifted 1 pixel right and 1 pixel up.
See Also: ReleaseCharacterView, SetCharacterView, SetCharacterViewEx
SetPlayerCharacter (CHARID)Changes the character which the player controls to CHARID. 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:
SetPlayerCharacter(MAN);will change the character that the player controls to character MAN and also change to the room that MAN is in, if he is not in the current room.
See Also: GetPlayerCharacter, NewRoom
SetTalkingColor (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:
SetTalkingColor (EGO, 14);will change the character’s EGO talking color to yellow.
StopMoving (CHARID)Stops the character CHARID moving and sets its graphic to the standing frame of the current loop.
Example:
if (character[EGO].x>299)
StopMoving(EGO);
will stop the character when he reaches the coordinate x=300.See Also: MoveCharacter, StopObjectMoving