Character functions and properties

Character functions and properties

AddInventory

(Formerly known as global function AddInventory, which is now obsolete)
(Formerly known as global function AddInventoryToCharacter, which is now obsolete)

Character.AddInventory(InventoryItem *item, optional int addAtIndex)

Adds the specified item to the character's inventory. This ensures that the item gets added to the character's inventory list, and that any on-screen inventory display gets updated if appropriate.

The first parameter is the inventory item's Script O-Name from the editor (for example, iPoster).

By default, the new item is added to the end of the character's inventory list. However, you can insert it in a particular position in the list by supplying the second parameter. The new item is inserted before the current item at addAtIndex. Indexes are numbered from 0, so to add the item at the start of the list, pass 0 as the second parameter.

Example:

character[EGO].AddInventory(iKey);

will give inventory item iKey to character EGO.

AddWaypoint

(Formerly known as MoveCharacterPath, which is now obsolete)

Character.AddWaypoint(int x, int y)

Tells the character 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 any moves made with this command ignore 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:

character[SOMEGUY].Walk(160, 100);
character[SOMEGUY].AddWaypoint(50, 150);
character[SOMEGUY].AddWaypoint(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: Character.Walk

Animate (character)

(Formerly known as AnimateCharacter, which is now obsolete)
(Formerly known as AnimateCharacterEx, which is now obsolete)

Character.Animate(int loop, int delay, optional RepeatStyle,
                  optional BlockingStyle, optional Direction)

Starts the character 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.

Before using this command, you should use LockView in order to select the view you want to animate with and prevent any automatic animations (eg. walking or idle animations) from playing.

The RepeatStyle parameter sets whether the animation will continuously repeat the cycling through the frames. This can be eOnce (or zero), in which case 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 RepeatStyle is eRepeat (or 1), then when the last frame is reached, it will go back to the first frame and start over again with the animation.

direction specifies which way the animation plays. You can either pass eForwards (the default) or eBackwards.

For blocking you can pass either eBlock (in which case the function will wait for the animation to finish before returning), or eNoBlock (in which case the animation will start to play, but your script will continue). The default is eBlock.

If the character is currently moving, it will be stopped.

Example:

character[EGO].LockView(5);
character[EGO].Animate(3, 1, 0, eBlock, eBackwards);
character[EGO].UnlockView();

will animate the character once using loop number 3 of view 5 backwards, and wait until the animation finishes before returning.

See Also: Object.Animate

ChangeRoom

(Formerly known as NewRoom, which is now obsolete)
(Formerly known as NewRoomEx, which is now obsolete)
(Formerly known as NewRoomNPC, which is now obsolete)

Character.ChangeRoom(int room_number, optional int x, optional int y)

Changes the room that the character is in.

If you call this on the player character, then the current room is unloaded from memory and ROOMx.CRM is loaded instead, where X is room_number.

IMPORTANT: This command does not change the room immediately; instead, it will perform the actual room change once your script function has finished (This is to avoid problems with unloading the script while it is still running). This means that you should not use any other commands which rely on the new room (object positionings, and so on) after this command within the same function.

If you call this on a non-player character, then they are instantly transported to the new room number.

Optionally, you can include an X and Y co-ordinate (you must include either both or neither). If you do so, then the character will also be moved to the specified co-ordinates in the new room.

Example:

character[EGO].ChangeRoom(4, 100, 50);

will move the player character to room 4 and also place him at coordinates 100,50. This will also mean that the game moves into room 4.

ChangeView

(Formerly known as ChangeCharacterView, which is now obsolete)

Character.ChangeView(int view)

Changes the normal view number of the character to view. 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 the LockView command instead. This ChangeView command permanently changes the character's normal walking view.

Example:

character[EGO].ChangeView(5);

will make the EGO character use view number 5 as his walking view.

FaceCharacter

(Formerly known as global function FaceCharacter, which is now obsolete)

Character.FaceCharacter(Character* toFace, optional BlockingStyle)

Turns the graphic of the character so that it looks like he is facing character TOFACE. This involves changing the current loop to the appropriate loop number, and setting the frame number to 0 (standing).

If the character has Turning enabled (ie. the "Characters turn to face direction" game option is turned on, and the character does not have the "Do not turn before walking" option checked), then the character will turn on the spot in order to face the new direction. In this case, the BlockingStyle parameter determines whether the script waits for the character to finish turning (eBlock, the default) or whether the script continues immediately and the character finishes turning later on (eNoBlock).

If the character does not have Turning enabled, he will immediately turn to face the new direction and the BlockingStyle parameter has no effect. In this case, the screen will not be refreshed straight away -- if you want to see the character facing his new direction immediately, call Wait(1);

Example:

cEgo.FaceCharacter(cMan);

will make the character EGO face the character MAN

FaceLocation

(Formerly known as global function FaceLocation, which is now obsolete)

Character.FaceLocation(int x, int y, optional BlockingStyle)

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 hotspots or anything else 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).

Example:

character[EGO].FaceLocation(character[EGO].x + 50, character[EGO].y);

will make the character face to the east.

See Also: Character.FaceCharacter

FaceObject

Character.FaceObject(Object* object, optional BlockingStyle)

Similar to the FaceCharacter function, except that this faces the character to object OBJECT in the current room.

Example:

player.FaceObject(object[2]);

will make the player character face object 2.

See Also: Character.FaceCharacter

FollowCharacter

(Formerly known as global function FollowCharacter, which is now obsolete)
(Formerly known as global function FollowCharacterEx, which is now obsolete)

Character.FollowCharacter(Character* chartofollow, optional int dist,
                          optional int eagerness)

Tells the character 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 null to stop the character following.

There are a couple of extra optional 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:

cMan.FollowCharacter(cEgo, 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.

GetAtScreenXY (character)

(Formerly known as global function GetCharacterAt, which is now obsolete)

static Character* Character.GetAtScreenXY(int x, int y)

Checks if there is a character at SCREEN co-ordinates (X,Y). Returns the character if there is, or null 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 (Character.GetAtScreenXY(mouse.x, mouse.y) == cEgo) {
  Display("The mouse is over the main character");
}

will display the message if the mouse cursor is over the EGO character

GetProperty (character)

(Formerly known as GetCharacterProperty, which is now obsolete)

Character.GetProperty(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 (character[EGO].GetProperty("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: Character.GetPropertyText

GetPropertyText (character)

(Formerly known as GetCharacterPropertyText, which is now obsolete)

Character.GetPropertyText(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;
character[EGO].GetPropertyText("Description", buffer);
Display("EGO's description: %s", buffer);

will retrieve EGO's "description" property into the buffer, then display it.

See Also: Character.GetProperty

IsCollidingWithChar

(Formerly known as AreCharactersColliding, which is now obsolete)

Character.IsCollidingWithChar(Character* otherChar)

Checks if the character is touching OTHERCHAR. This function just checks the baseline of both characters, so 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 (character[EGO].IsCollidingWithChar(cMan) == 1)
   { colliding code here }

will execute the colliding code only if the characters EGO and MAN are colliding.

IsCollidingWithObject (character)

(Formerly known as AreCharObjColliding, which is now obsolete)

Character.IsCollidingWithObject(Object* obj)

Checks whether the character's feet (ie. the bottom third of the character) are touching OBJ. This can be used to determine if the character is standing on the object.

Returns 1 if they are, and 0 if they are not.

Example:

if (character[EGO].IsCollidingWithObject(object[3]) == 1) {
  // colliding code here
}

will execute the colliding code only if the character EGO and the object number 3 are colliding.

LockView

(Formerly known as SetCharacterView, which is now obsolete)

Character.LockView(int view)

Sets the character'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 AGS on walkable areas, screen changes, etc). When you are done with the animation, call UnlockView to allow AGS to take control back.

Example:

character[EGO].LockView(12);
character[EGO].Animate(0, 0, eOnce, eBlock, eForwards);
character[EGO].UnlockView();

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.

LockViewAligned

(Formerly known as SetCharacterViewEx, which is now obsolete)

Character.LockViewAligned(int view, int loop, Alignment)

Sets the character'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 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.

Alignment can have one of the following values:

align Description

eAlignLeft Moves the new frame so that the left hand side is at exactly the same X co-ordinate as the old one was.

eAlignCentre Leaves the frames centred in the middle. This is the default and using this is equivalent to just calling LockView.

eAlignRight 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 UnlockView 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 UnlockView to allow the program to take control back.

Example:

character[EGO].LockViewAligned(12, 1, eAlignLeft);
character[EGO].Animate(1, 5, eOnce, eBlock, eForwards);
character[EGO].UnlockView();

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.

LockViewFrame

(Formerly known as SetCharacterFrame, which is now obsolete)

Character.LockViewFrame(int view, int loop, int frame)

Sets the 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 UnlockView.

Example:

character[EGO].LockViewFrame(AGHAST, 2, 4);
Wait(40);
character[EGO].UnlockView();

will change EGO to have frame 4 of loop 2 in the AGHAST view, wait for a second, then return him to normal.

LockViewOffset

(Formerly known as SetCharacterViewOffset, which is now obsolete)

Character.LockViewOffset(int view, int xOffset, int yOffset)

Sets the character's view to VIEW, in the same way as LockView does. However, it also adds a specified offset to all the character's frames until UnlockView 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 LockViewAligned 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).

Example:

character[EGO].LockViewOffset(12, 1, 1, -1);
character[EGO].Animate(1, 5, eOnce, eBlock, eForwards);
character[EGO].UnlockView();

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.

LoseInventory

(Formerly known as global function LoseInventory, which is now obsolete)
(Formerly known as LoseInventoryFromCharacter, which is now obsolete)

Character.LoseInventory(InventoryItem *item)

Removes the specified inventory item from the character's inventory. If they do not have the item, nothing happens.

The parameter is the inventory item's Script O-Name from the editor.

Example:

character[EGO].LoseInventory(iKey);

will make the character EGO lose the inventory item iKey from the inventory tab

See Also: Character.AddInventory

PlaceOnWalkableArea

(Formerly known as MoveToWalkableArea, which is now obsolete)

Character.PlaceOnWalkableArea()

Places the character in the nearest walkable area to its current location. If the character is already on a walkable area, nothing happens.

This is useful for example in the Player Enters Screen event of a room, to make sure the character can move if a ChangeRoom with co-ordinates has been issued to get there. You could also use this in on_event for eEventEnterRoomBeforeFadein to use whenever a player enters a room.

Example:

character[EGO].x = Random(320);
character[EGO].y = Random(200);
character[EGO].PlaceOnWalkableArea();

will move character EGO to a random position but make sure that he is on a walkable area.

RemoveTint (character)

Character.RemoveTint()

Undoes the effects of calling Tint, and returns the character to using the room's ambient tint.

Example:

player.Tint(0, 250, 0, 30, 100);
Wait(40);
player.RemoveTint();

will tint the player character green for a second, then turn it back to normal.

See Also: Character.Tint

RunInteraction (character)

(Formerly known as RunCharacterInteraction, which is now obsolete)

Character.RunInteraction(CursorMode)

Processes the interaction list as if the player had clicked the mouse on the character in the specified cursor mode. This is one of the mouse cursor modes, as defined in your Cursors tab in the editor.

Example:

character[MAN].RunInteraction(eModeTalk);

will execute the code defined in the MAN's "TALK TO CHARACTER" interaction.

Say

(Formerly known as DisplaySpeech, which is now obsolete)

Character.Say(string message)

Displays the text MESSAGE as speech above the character's head. The text will remain on screen for a limited time, and the user may or may not be able to click it away depending on the setting of "Player can't skip speech text". The text displayed by this function looks identical to that used by the dialog system.

You can insert the value of variables into the message. For more information, see the string formatting section.

Example:

character[EGO].Say("My name is ego");

will display the message above the character's EGO head like the LEC games, whilst playing the character's talking animation.

SayAt

(Formerly known as DisplaySpeechAt, which is now obsolete)

SayAt(int x, int y, int width, string message)

Similar to Say, except that the text is displayed with its top left corner at (X,Y), in an area WIDTH wide.

You can use this function to write the character's speech text anywhere you like, and AGS will still play the character's talking animation and so on if appropriate.

NOTE: This function does not support QFG4-style speech.

Example:

character[EGO].SayAt(220, 20, 100, "My name is ego");

will display the message in the top right corner of the screen, whilst playing the character's talking animation.

SayBackground

(Formerly known as DisplaySpeechBackground, which is now obsolete)

Overlay* Character.SayBackground(string message)

Similar to Say, except that this function returns immediately and the game continues while the character is talking. This allows you to have characters talking in the background while the player does other things. Note that the character's talking animation is not played if this function is used.

This command works by creating a text overlay with an automatic removal time delay. The overlay is returned by this command, so you can save it for use later with Overlay.IsValid and Overlay.Remove, if you want to remove the text prematurely.

If background speech is already on-screen for the character, it will be removed and replaced with the new MESSAGE.

All background speech is automatically removed when a normal Say command is used (unless you set the global variable game.bgspeech_stay_on_display to 1).

Example:

character[MAN].SayBackground("Hey, why won't you talk to me?");

will display the message above character MAN's head without pausing the game.

See Also: Character.Say

SetAsPlayer

(Formerly known as SetPlayerCharacter, which is now obsolete)

Character.SetAsPlayer()

Changes the character which the player controls to the specified character. This function will also cause the room to change to the room which the chosen character is currently in (though as with ChangeRoom, the change won't happen until the end of the script).

Additionally, calling this command will cause the "player" variable to be updated to point to the specified character.

Example:

character[MAN].SetAsPlayer();

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: Character.ID, Character.ChangeRoom

SetIdleView

(Formerly known as SetCharacterIdle, which is now obsolete)

Character.SetIdleView(int idleview, int delay)

Changes the character'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.

NOTE: Due to a quick in AGS, you cannot set the Idle View to view 1. In the unlikely event that you created your idle view in View 1, you'll need to move it to another view number.

Example:

character[EGO].SetIdleView(12, 30);

will change/set the character EGO's idle view to 12. The idle view will be played if the character is idle for 30 seconds.

SetWalkSpeed

(Formerly known as SetCharacterSpeed, which is now obsolete)
(Formerly known as SetCharacterSpeedEx, which is now obsolete)

Character.SetWalkSpeed(int x_speed, int y_speed)

Changes the character to have a 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.

X_SPEED and Y_SPEED can be identical, in which case the character moves with the same speed in any direction. (the editor calls this "Uniform movement speed")

NOTE: This function CANNOT be called while the character is moving, so you must stop him first.

Example:

character[EGO].SetWalkSpeed(10, 10);

will change the character EGO's speed to 10.

StopMoving (character)

(Formerly known as global function StopMoving, which is now obsolete)

Character.StopMoving()

Stops the character moving and sets its graphic to the standing frame of the current loop.

Example:

if (character[EGO].x > 299) {
  character[EGO].StopMoving();
}

will stop the character when he reaches the coordinate x=300.

See Also: Character.Walk, Object.StopMoving

Think

(Formerly known as DisplayThought, which is now obsolete)

Character.Think(string message, ...)

Displays the text MESSAGE as a thought above the specified character's head. The text will remain on screen for a limited time, and the user may or may not be able to click it away depending on the setting of "Player can't skip speech text".

How this function displays the text depends on a few things: the Speech Style setting, the 'Thought uses bubble GUI' setting, and whether the character has a thinking animation or not.

If the "Thought uses bubble GUI" setting is not checked, then the thought will be displayed in the same way as normal speech - the difference being that the character's thinking animation will play (or no animation if they don't have one).

If you are using Sierra-style speech and the character doesn't have a thinking animation, the thought bubble will be displayed in lucasarts-style.

If the "Thought uses bubble GUI" setting has been set, then the thought will be displayed like normal speech, except that the bubble GUI will be used for the window background. In Lucasarts-style speech this means above the character's head, in Sierra-style it will be done along the top of the screen as normal.

If the character has a thinking animation, it will just loop through once (it won't repeat).

You can insert the value of variables into the message. For more information, see the string formatting section.

Example:

character[EGO].Think("I wonder what's for dinner.");

will display the message above EGO's head and play the character's thinking animation.

Tint (character)

Character.Tint(int red, int green, int blue,
               int saturation, int luminance)

Tints the character on the screen to (RED, GREEN, BLUE) with SATURATION percent saturation.

This function applies a tint to a specific character. For the meaning of all the parameters, see SetAmbientTint.

The tint set by this function overrides any ambient tint set for the room. For this reason, passing the SATURATION as 0 to this function does not turn it off - rather, it ensures that no tint is applied to the character (even if an ambient tint is set).

To remove the tint set by this function and return to using the ambient tint for this character, call RemoveTint.

NOTE: This function only works in hi-colour games and with hi-colour sprites.

Example:

cEgo.Tint(0, 250, 0, 30, 100);

will tint the EGO character green.

UnlockView

(Formerly known as ReleaseCharacterView, which is now obsolete)

Character.UnlockView()

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 LockView command.

Example:

character[EGO].LockView(12);
character[EGO].Animate(0, 0, eOnce, eBlock, eForwards);
character[EGO].UnlockView();

will play an animation using loop 0 of view 12, then return the character to its normal view.

See Also: Character.LockView

Walk

(Formerly known as MoveCharacter, which is now obsolete)
(Formerly known as MoveCharacterBlocking, which is now obsolete)
(Formerly known as MoveCharacterDirect, which is now obsolete)

Character.Walk(int x, int y, optional BlockingStyle,
                             optional WalkWhere);

Starts the character moving from its current location to X,Y.

If blocking is eNoBlock (the default) then control returns to the script immediately, and the character will move in the background.

If blocking is eBlock then this command will wait for the character to finish moving before your script resumes.

If walkWhere is eWalkableAreas (the default), then the character will attempt to get as close a possible to (X,Y) by using the room's walkable areas.

If walkWhere is eAnywhere, then the character will simply walk directly from its current location to (X,Y), ignoring the room walkable areas.

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 Moving property. See the variables section for more information.

Example:

character[EGO].Walk(155, 122, eBlock);

will make the character walk to 155,122. The script will not continue until the character has reached his destination.

WalkStraight

(Formerly known as MoveCharacterStraight, which is now obsolete)

Character.WalkStraight(int x, int y, optional BlockingStyle);

Moves the character from its current location towards (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.

blocking determines whether the function waits for the character to finish moving before your script resumes. eNoBlock is the default (which means your script resumes straight away, and the character moves in the background). You can also pass eBlock, in which case your script will not resume until the character finishes moving.

Example:

character[EGO].WalkStraight(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: Character.Walk

ActiveInventory property

(Formerly known as SetActiveInventory, which is now obsolete)
(Formerly known as character[].activeinv, which is now obsolete)

InventoryItem* Character.ActiveInventory

Gets/sets the character's current active inventory item. Setting it will update the mouse cursor if appropriate.

To deselect the current inventory, set it to null.

Example:

character[EGO].ActiveInventory = iKey;

will make the inventory item iKey active (before you use it make sure that the player has the inventory item)

Animating property (character)

(Formerly known as character[].animating, which is now obsolete)

readonly bool Character.Animating

Returns 1 if the character is currently animating.
Returns 0 if the character has finished its animation.

This property is read-only. To change character animation, use the Animate command.

Example:

character[EGO].Animate(5, 0);
while (character[EGO].Animating) Wait(1);

will animate EGO and wait until the animation finishes.

In reality, you would simply use the Blocking parameter of Animate so you wouldn't need to do this.

AnimationSpeed property

(Formerly known as character[].animspeed, which is now obsolete)

int Character.AnimationSpeed;

Gets/sets the character's animation delay, as set in the editor.

Example:

player.AnimationSpeed = 4;

will change the player character's animation speed to 4.

See Also: Character.SetWalkSpeed

Baseline property (character)

(Formerly known as SetCharacterBaseline, which is now obsolete)

int Character.Baseline

Gets/sets the character's baseline. This allows you to set a specific base line for the character, which works similarly to walk-behind area and object baselines.

The 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:

character[MAN].Baseline = 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: Object.Baseline, SetWalkBehindBase

BlinkInterval property

(Formerly part of SetCharacterBlinkView, which is now obsolete)

int Character.BlinkInterval

Gets/sets the character's blinking interval, which specifies how long the game waits between playing the blinking animation. This is specified in game loops - an interval of 80 would play the blinking animation about every 2 seconds.

This property has no effect if no BlinkView has been set.

Example:

character[EGO].BlinkView = 10;
character[EGO].BlinkInterval = 160;

will change the character EGO's blink view to view 10, and play the animation every 4 seconds.

BlinkView property

(Formerly part of SetCharacterBlinkView, which is now obsolete)

int Character.BlinkView

Gets/sets the character's blinking view. To stop the character from blinking, set this to -1.

The BlinkInterval property sets how often the blinking animation is played.

Example:

character[EGO].BlinkView = 10;
character[EGO].BlinkInterval = 160;

will change the character EGO's blink view to view 10, and play the animation every 4 seconds.

BlinkWhileThinking property

bool Character.BlinkWhileThinking

Gets/sets whether the character can blink while thinking. By default this is set to true, but if your blinking animation only goes with the talking animation and not the thinking one, you can stop the character from blinking while Thinking by setting this to false.

Example:

cEgo.BlinkWhileThinking = false;

will stop EGO from blinking while his thinking animation is playing.

BlockingHeight property (character)

int Character.BlockingHeight

Gets/sets the character's blocking height.

The blocking height determines how large of a blocking rectangle the character exerts to stop other characters walking through it. If this is set to 0 (the default), then the blocking rectangle is automatically calculated to be the character's width, and 5 pixels high.

You can manually change the setting by entering a blocking height in pixels, which is the size of walkable area that the character effectively removes by standing on it.

NOTE: This property has no effect unless the Solid property is set to 1.

Example:

character[EGO].BlockingHeight = 20;

will make EGO block 20 pixels high (10 above and 10 below his baseline)

BlockingWidth property (character)

int Character.BlockingWidth

Gets/sets the character's blocking width.

The blocking width determines how large of a blocking rectangle the character exerts to stop other characters walking through it. If this is set to 0 (the default), then the blocking rectangle is automatically calculated to be the character's width, and 5 pixels high.

You can manually change the setting by entering a blocking width in pixels, which is the size of walkable area that the character effectively removes by standing on it.

NOTE: This property has no effect unless the Solid property is set to 1.

Example:

character[EGO].BlockingWidth = 50;

will make EGO block 50 pixels wide (25 pixels to the left of his X co-ordinate, and 25 to the right)

Clickable property (character)

(Formerly known as SetCharacterClickable, which is now obsolete)

bool Character.Clickable

Gets/sets whether the character is recognised as something which the player can interact with. This allows you to modify the "No interaction" tick-box set initially in the Editor.

If you set this to 1 then the player can look at, speak to, and so on the character (as with the old Sierra games). If you set this to 0, then if the player clicks on the character it will activate whatever is behind them (as with the old Lucasarts games).

Example:

character[MAN].Clickable = 0;

will make the game ignore clicks on the character MAN.

See Also: Object.Clickable

DiagonalLoops property

(Formerly part of SetCharacterProperty, which is now obsolete)

bool Character.DiagonalLoops

Gets/sets whether diagonal walking loops are used for the character. If this is set to true, then loops 4-7 will be used as diagonal walking loops. If this is set to false, then the character will only face in 4 directions and you can use loops 4-7 for other purposes.

Example:

character[EGO].DiagonalLoops = true;

will enable diagonal walking loops for character EGO.

Frame property

(Formerly known as character[].frame, which is now obsolete)

int Character.Frame

Gets/sets the character's current frame number. Usually you won't change this directly, but will use the Animate command to play an animation.

Example:

Display("EGO currently using frame %d.", cEgo.Frame);

displays EGO's current frame number within his view.

SeeAlso: Character.Animate, Character.Loop, Character.View

ID property (character)

readonly int Character.ID

Gets the character's ID number. This is the character's number from the editor, and is useful if you need to interoperate with legacy code that uses the character's number rather than name.

Example:

MoveCharacter(cEgo.ID, 100, 50);

uses the obsolete MoveCharacter function to move EGO to (100, 50)

IdleView property

readonly int Character.IdleView

Gets the character's current idle view. If the character doesn't have one, returns -1.

This property is read-only; to change the view, use the SetIdleView function.

Example:

Display("EGO's idle view is currently view %d.", character[EGO].IdleView);

will display EGO's current idle view number.

SeeAlso: SetIdleView

IgnoreLighting property

(Formerly known as SetCharacterIgnoreLight, which is now obsolete)

bool Character.IgnoreLighting

Allows you to dynamically modify the "ignore lighting" checkbox for the character. If this is set to 0, the character will be affected by region light levels and tints; if this is set to 1, then the character will ignore all region lighting.

Example:

character[EGO].IgnoreLighting = 1;

will make the character look the same no matter if he stands on regions with different light levels.

IgnoreScaling property

(Formerly part of SetCharacterProperty, which is now obsolete)

bool Character.IgnoreScaling

Gets/sets whether the character is affected by walkable area scaling. This is equivalent to the "Ignore room area scaling" checkbox in the editor.

If this is set to 1, the character will always be the same size. If it is set to 0, then the character will be stretched or shrunk as appropriate on walkable areas.

Example:

character[EGO].IgnoreScaling = 1;

will tell EGO to ignore walkable area scaling levels.

IgnoreWalkbehinds property (character)

(Formerly known as SetCharacterIgnoreWalkbehinds, which is now obsolete)

bool Character.IgnoreWalkbehinds

Gets/sets whether the character 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:

character[EGO].IgnoreWalkbehinds = 1;

will make the character EGO ignore walk-behinds.

See Also: Object.IgnoreWalkbehinds

InventoryQuantity property

(Formerly known as character[].inv, which is now obsolete)

int Character.InventoryQuantity[]

Gets/sets the quantity of the specified inventory item that the character currently has. The array index is the inventory item number, from the Inventory pane in the editor.

Usually, you should use the AddInventory and LoseInventory functions to modify the character's inventory; however, if you need to add or remove a large number of items in one go, directly changing this array can be an easier method.

If you change this array directly, the on-screen inventory will not be updated. In this case, you must call UpdateInventory to see any new or removed items.

Example:

Display("The player has $%d.", player.InventoryQuantity[iCash.ID]);

will display how many inventory items of type iCash the player has.

Loop property

(Formerly known as character[].loop, which is now obsolete)

int Character.Loop

Gets/sets the character's current loop number. Usually you won't change this directly, but will use the Animate command to play an animation.

Example:

Display("EGO currently using loop %d.", cEgo.Loop);

displays EGO's current loop number within his view.

SeeAlso: Character.Animate, Character.Frame, Character.View

Moving property (character)

(Formerly known as character[].walking, which is now obsolete)

readonly bool Character.Moving

Returns 1 if the character is currently moving, or 0 if not.

This property is read-only; to change the character's movement, use the Walk and StopMoving commands.

Example:

character[EGO].Walk(125, 40);
while (character[EGO].Moving) Wait(1);

will move EGO to 125,40 and return control to the player when he gets there.

NormalView property

(Formerly known as character[].defview, which is now obsolete)

readonly int Character.NormalView

Gets the character's normal view. This is the character's standard walking view, that is used when his view is not locked to something else.

This property is read-only; to change it, use the ChangeView command.

Example:

if (cEgo.View == cEgo.NormalView) {
  Display("EGO is not animating, not talking and not idle.");
}

will display a message if EGO is currently displayed using his normal view.

PreviousRoom property

(Formerly known as character[].prevroom, which is now obsolete)

readonly int Character.PreviousRoom

Gets the room number that the character was previously in. If the character is still in the room that they started in, this will be -1. Otherwise, it will be the room number of the room that they were last in.

This is a read-only property. It is set automatically by ChangeRoom.

Example:

Display("EGO's previous room was %d.", character[EGO].PreviousRoom);

will display the EGO character's previous room.

Room property

(Formerly known as character[].room, which is now obsolete)

readonly int Character.Room

Gets the room number that the character is currently in.

This is a read-only property. It is set by ChangeRoom.

Example:

Display("EGO is in room %d.", character[EGO].Room);

will display the EGO character's current room.

ScaleMoveSpeed property

(Formerly part of SetCharacterProperty, which is now obsolete)

bool Character.ScaleMoveSpeed

Gets/sets whether the character's movement speed is adjusted in line with his current scaling level. This allows you to modify the "Adjust speed with scaling" option from the editor.

If you set this to 1, the character's movement speed will be adjusted so that he walks at a speed relative to his current scaling level. If you set this to 0, the character will always just move at his normal speed.

Example:

character[EGO].ScaleMoveSpeed = 1;

will mean that EGO's speed is adjusted in line with his scaling

Solid property (character)

(Formerly part of SetCharacterProperty, which is now obsolete)

bool Character.Solid

Gets/sets whether the character can be walked through by other characters.

If this is set to 1, then the character is solid and will block the path of other characters. If this is set to 0, then the character acts like a hologram, and other characters can walk straight through him.

Example:

character[EGO].Solid = 1;

will mean that EGO blocks the path other characters.

Speaking property

readonly bool Character.Speaking

Returns true if the character is currently talking, or false if not.

This property is read-only. It will only return true for the active talking character; that is, it will not return true for any characters talking with the SayBackground command.

Since this property will only be true while the character is speaking, and speaking is a blocking command, this property will probably only be useful to access from the repeatedly_execute_always handler.

Example:

if ((cEgo.Speaking) && (!cEgo.Animating)) {
  cEgo.Animate(3, 5, eRepeat, eNoBlock);
}

will animate the character using loop 3 while they are talking (only useful with Sierra-style speech).

SpeechColor property

(Formerly known as SetTalkingColor, which is now obsolete)

int Character.SpeechColor

Gets/sets the character's speech text color. This is set by default in the editor.

NEWCOLOR is the colour slot index from the Palette Editor. This can be 0-255 for a 256-colour game, or one of the hi-colour indexes available from the Palette Editor.

Example:

character[EGO].SpeechColor = 14;

will change the character�s EGO talking color to yellow.

See Also: Character.SpeechView

SpeechView property

(Formerly known as SetCharacterSpeechView, which is now obsolete)
(Formerly known as character[].talkview, which is now obsolete)

int Character.SpeechView

Gets/sets the character's talking view. If you change it, the new view number will be used as the character's talking view in all future conversations.

You can set this to -1 to disable the character's speech view.

Example:

character[EGO].SpeechView = 10;

will change the character EGO's speech view to view 10.

ThinkView property

(Formerly known as character[].thinkview, which is now obsolete)

int Character.ThinkView

Gets/sets the character's thinking view. This is used to animate the character when a thought is being displayed.

Example:

character[EGO].ThinkView = 14;

will change the character EGO's thinking view to 14.

See Also: Character.Think

Transparency property (character)

(Formerly known as SetCharacterTransparency, which is now obsolete)

int Character.Transparency

Gets/sets the character's transparency. This is specified as a percentage, from 0 to 100. 100 means fully transparent (ie. invisible), and 0 is totally opaque (fully visible). Numbers in between represent varying levels of transparency.

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.

Some rounding is done internally when the transparency is stored -- therefore, if you get the transparency after setting it, the value you get back might be one out. Therefore, using a loop with character[EGO].Transparency++; is not recommended as it will probably end too quickly.

In order to fade a character in, the best approach is shown in the example below:

Example:

int trans = character[EGO].Transparency;
while (trans < 100) {
  trans++;
  character[EGO].Transparency = trans;
  Wait(1);
}

will gradually fade out the character from its current transparency level to being fully invisible.

See Also: Object.Transparency

TurnBeforeWalking property

(Formerly part of SetCharacterProperty, which is now obsolete)

bool Character.TurnBeforeWalking

Gets/sets whether the character turns to face his new direction before walking. This is equivalent (though opposite) to the editor "Do not turn before walking" tick-box.

If you set this to 1, the character will turn on the spot to face his new direction before setting off on a walk. If you set this to 0, the character will instantly face in the correct direction and start walking.

Example:

character[EGO].TurnBeforeWalking = 1;

will tell EGO to turn to face his new direction before setting off, whenever he walks.

View property (character)

readonly int Character.View

Gets the view that the character is currently displayed using.

This property is read-only; to change the view, use the ChangeView and LockView functions.

Example:

Display("EGO's view is currently view %d.", character[EGO].View);

will display EGO's current view number.

SeeAlso: Character.ChangeView, Character.Frame, Character.LockView, Character.Loop, Character.NormalView

WalkSpeedX property

readonly int Character.WalkSpeedX;

Gets the character's walking speed in the X direction. If using uniform movement, this will be the same as the Y walking speed.

This property is read-only. To change the walking speed, use the SetWalkSpeed function.

Example:

Display("player's x speed: %d", player.WalkSpeedX);

will display the player's X speed.

WalkSpeedY property

readonly int Character.WalkSpeedY;

Gets the character's walking speed in the Y direction. If using uniform movement, this will be the same as the X walking speed.

This property is read-only. To change the walking speed, use the SetWalkSpeed function.

Example:

Display("player's y speed: %d", player.WalkSpeedY);

will display the player's Y speed.

x property (character)

int Character.x;

Gets/sets the character's current X co-ordinate. This is expressed in normal room co-ordinates, and specifies the centre-bottom of the character's sprite.

NOTE: Do NOT change this property while the character is moving. Make sure the character is standing still before changing his co-ordinates.

Example:

Display("The player is at %d,%d.", player.x, player.y);

displays the player character's current coordinates.

See Also: Character.y, Character.z

y property (character)

int Character.y;

Gets/sets the character's current Y co-ordinate. This is expressed in normal room co-ordinates, and specifies the centre-bottom of the character's sprite.

NOTE: Do NOT change this property while the character is moving. Make sure the character is standing still before changing his co-ordinates.

Example:

Display("The player is at %d,%d.", player.x, player.y);

displays the player character's current coordinates.

See Also: Character.x, Character.z

z property (character)

int Character.z;

Gets/sets the character's current Z position. This allows the character to levitate off the ground, whilst still retaining its normal Y co-ordinate for baseline calculations and regions.

Normally this is set to 0 (ground-level), but you can increase it to make the character float.

Example:

while (player.z < 20) {
  player.z++;
  Wait(1);
}

gradually levitates the character up to 20 pixels.

See Also: Character.x, Character.y

SetCharacterProperty

SetCharacterProperty (CHARID, PROPERTY, int new_value)

This command is now obsolete. It has been replaced by the following properties:

Clickable
DiagonalLoops
IgnoreLighting
IgnoreScaling
ScaleMoveSpeed
Solid
TurnBeforeWalking

Browser Based Help. Published by chm2web software.

align	Description
eAlignLeft	Moves the new frame so that the left hand side is at exactly the same X co-ordinate as the old one was.
eAlignCentre	Leaves the frames centred in the middle. This is the default and using this is equivalent to just calling LockView.
eAlignRight	Moves the new frame so that the right hand side is at exactly the same X co-ordinate as the old one was.