Script Language: Predefined Functions and Properties: Object Manipulation and Direction


The properties and functions are used to define the appearance and and behavior of each object, and direct its movement and animation.

Properties


Functions



property SoundVolume = VOLUME_HALF

Sets the volume of sounds played by this object. The range is from 0 (mute) to 255 (full).

To set the volume without relation to the master volume, just negate the value. The absolute value will then be used for the absolute volume level. Cute, isn't it?

The constants VOLUME_MUTE, VOLUME_HALF, VOLUME_FULL are predefined for your volume-setting convenience.

Example
// Set a relative volume of 200
                    Ego.SoundVolume = 200;

                    // Set an absolute volume of 200
                    Ego.SoundVolume = -200;



property SoundPan = PAN_CENTER

Sets the linear pan position of sounds played through this object. Values range from 0 for full left, to 127 for the center, and to 255 for full right. The constants PAN_LEFT, PAN_CENTER, and PAN_RIGHT are defined for these values.

In addition to this range of values, there are two special values. PAN_SURROUND simulates surround sound by inverting the waveform on one speaker. Whereas PAN_CENTER and PAN_SURROUND effectively halve the volume of the left and right speakers to acheive a stereo effect, PAN_STEREO plays a sound at full volume on both speakers, for maximum loudness.



property SoundFrequency = FREQUENCY_DEFAULT

Sets the frequency of sounds played by this object. Valid frequencies range from 100 to 705,600 Hz. Setting this variable to FREQUENCY_DEFAULT automatically uses the default frequency specified by the sound resource.



property Visible = true

If set to true, the object is visible, otherwise it is not.



property Enabled = true

If set to false, the object is completely disabled.



property Clickable = true

Can the user click this object to trigger an event?



property UseAnimAsClickMask = false

If true, the object's current frame is used as the ClickMask. If the object is not clickable, this property is ignored.



property ClickMask = none

This property specifies a sprite resource to use in determining if a click event should be triggered. If the user clicks on a transparent pixel, the click event will not occur. If the object is not clickable, or if UseAnimAsClickMask is set to true, this property is ignored.



property ClickMaskFrame = none

This property specifies which frame of the sprite referenced by ClickMask should be used to determine whether or not a click event should be triggered.



property Absolute = false

Absolute means that an object is attached to the screen instead of the background. Also, the object's clickable area is defined then by absolute coordinates.



property Priority = 0

The priority of an object tells the interpreter which order to draw the objects, so that they appear to be in above or behind other objects and priority bands in the zbuffer. An object with a higher priority value is drawn above all other objects and priority bands with lower priority values.

The lowest possible priority is 0, and highest is 255. If the priority is set to the special value PRIORITY_AUTO, the interpreter will automatically recalculate the object's priority each time it draws that object, using the formula positionY / 8. If the priority is below zero, the zbuffer will be ignored when the object is drawn.

Notes

The constants PRIORITY_LOWEST, PRIORITY_HIGHEST and PRIORITY_AUTO are defined in the standard script file "Constants.s".

See Also...



property Scale = 1000

Scale factor of the object's sprite size, walk speed, text offset, and click area. If set to 0, and the object has a path, the object will take the scale factor from the path automatically, depending upon its PositionX and PositionY. Values 1 to 1000 are valid scale factors (e.g. 1000 is actual size, 500 is half size, and 1 is a thousanth of actual size).

If the object's PathAutoScale is set to true, the Scale property will be ignored, and the object will be scaled automatically according to the current path.

Notes

There is no way to make an object larger than the original size, because that would result in repeated pixels and therefore poor image quality. So just be sure to draw the image at the greatest size that you require.



property PositionX = 0

X-position of the object. If the absolute property is set to true, this property refers to screen space, otherwise it refers to scrolling-background space.



property PositionY = 0

Y-position of the object. If the absolute property is set to true, this property refers to screen space, otherwise it refers to scrolling-background space.



property PositionZ = 0

z-projection of the object. This is subtracted from the y-position to simulate height. Use this property to adjust the objects height from the ground without affecting its sort order.



property Path = none

This chooses the path resource that will be used to keep the object contained in a certain polygonal area on the screen. Whenever an object is directed to move with the walk function, he will find the shortest route in this path from his current position to the target position, and follow it until he reaches his target (unless he is interrupted by another call to walk or a call to stop).

See Also...



property PathAutoScale = false

Turn automatic scaling according to the current path on or off. When false, the object's scale will be determined by the Scale property, and when true, the scale value interpolated from the surrounding points on the current path.

See Also...



property Direction = 0

There are 12 directions, numbered 0 to 11, where 0 is north (up), 3 is east (right), 6 is south (down), 9 is west (left), and the rest are in-between. Just think of it as the hands of a clock, but with 0 at the top instead of 12.



property ClickAreaX1 = 0

Left-offset of clickable region from the object's x-position.



property ClickAreaY1 = 0

Top offset of clickable region from the object's y-position.



property ClickAreaX2 = 0

Right offset of clickable region from the object's x-position.



property ClickAreaY2 = 0

Bottom offset of clickable region from the object's y-position.



property Caption = 0

The string index of the text currently being displayed in the object's caption.



property Name = 0

This property has no meaning to the AGAST interperter, and is just provided in case the programmer has a purpose for it.



property Description = 0

This property has no meaning to the AGAST interpreter, and is just provided in case the programmer has a purpose for it.



property CaptionWidth = 0

This controls the width, in pixels, of the caption. If the caption is too long to fit within this width, it is wrapped.

If this width is set to 0, the interpreter will position the caption automatically according to the object's position. This feature works very well when the object is not too close to the edges of the screen. It is up to the script programmer to guarantee the object will be in a reasonable position, or to override this behavior by setting the caption's position manually.



property CaptionJustify = JUSTIFY_CENTER

This controls the justification, or horizontal alignment, of the text in the caption. The three possible settings are:

JUSTIFY_LEFT Aligns the caption to the left.

JUSTIFY_RIGHT Aligns the caption to the right.

JUSTIFY_CENTER Centers the caption horizontally.



property CaptionBase = BASE_ABOVE

This controls the vertical alignment in relation to the baseline. There are three possible settings:

BASE_ABOVE The caption appears above the baseline.

BASE_BELOW The caption appears below the baseline.

BASE_CENTER The caption is centered vertically on the baseline.



property CaptionColor = COLOR_GRAY

The color of the caption, the text which is "spoken". You can use the RGB function to define a color.



property CaptionX = 0

Horizontal offset from the center of object to the point its text is centered around.



property CaptionY = 0

Vertical offset from the center of object to the caption's basline.



property CaptionFont = 0

Font resource that the object uses when talking.



property CaptionClick = true

When this property is true, the caption will disappear whenever the user clicks the left mouse button. This behavior only occurs while user input is suspended (although the script programmer can change this by modifying the system and game input handler scripts if desired).

There is a strategy when using this propery, which is mostly just common sense. If your object is, or is involved with, the main character during conversations, you will probably want to let the user interrupt the talking to continue at his own faster reading pace. But if there is a conversation going on in the background without direct involvement from the main character, you don't want to interrupt that. Also, you don't want to interrupt captions that are important to the timing of such background events.



property AutoAnimate = true

Set it to true for an object's sprite's frames to be flipped automatically during each cycle, or set it to false to manually control an object's frame.



property Frame = 0

Sets the next frame of animation for the object to display.



property StopAnimDelay = 1

Number of interpreter cycles that occurs before the stop animation flips to the next frame.



property TalkAnimDelay = 1

Number of interpreter cycles that occurs before the talk animation flips to the next frame.



property WalkAnimDelay = 1

Number of interpreter cycles that occurs before the walk animation flips to the next frame.



property TurnAnimDelay = 1

Number of interpreter cycles that occurs before the walk animation flips to the next frame.



property PlayAnimDelay = 1

Number of interpreter cycles that occurs before the play animation flips to the next frame.



property AnimMode = ANIM_STOP

Gets or sets the animation mode.

Notes

This property was originally hidden in the implementation of the interpreter, and not exposed in the AGAST programming language. The programmer must have a thorough understanding of animation in AGAST to modify this property without adversely affecting this object's other animation routines.



property WalkingSpeed = 10

The object's walking speed, in 1/10 pixels per cycle. As an example, if the speed is set to 30, the object will move at 3 pixels per cycle. Or, if the speed is set to 5, the object will only walk at a half a pixel per cycle.



property ObjectPaintingHandler = none

This is an object's painting handler. If it is installed for an object, it will be responsible for drawing that object based on the current state of animation. It will override both the interperter's paint-routine and the paint-object event.

To install a painting handler, assign to it the index of a script, as in the example. The script must have no parameters. To uninstall, assign a value of null.

When not installed, the object will be drawn automatically by the interpreter, based upon its various animation and display properties.

Notes

The handler script must have NO parameters, the interpreter ignores the return value.

Example
script ParticleManPaintHandler() {
     // Is he a dot or is he a speck?
     // Nobody knows, Particle man
     DrawingColor = RGB(RandomRange(127, 255), 127, RandomRange(127, 255));
     DrawPixel(PositionX, PositionY);
}
object ParticleMan {
     ObjectPaintHander = &ParticleManPaintHandler; // install
}



property ObjectAnimationHandler = none

This handler controls the animation of an object by updating the object's frame. If it is not installed (set to 0), then the object's frame will be incremented on each game cycle by the interpreter's animate routine. This handler will override both the interpreter's animation routine, and the animate-object event.

To install an animation handler, assign to it the index of a script. The script must have no parameters. To uninstall, assign a value of null.

Parameters

HandlerScriptIndex Index of object drawing handler script.
Notes

The handler script must have NO parameters, the interpreter ignores the return value.

See Also...



property MouseCheckHandler

This handler lets you control how the interpreter decides whether or not the mouse is over an object. This handler will override the interpreter's default check. It will be called every time the interpreter has to check for a MouseOver or click event, as well as by functions such as ObjectUnderMouse.

To install a mouse check handler, assign to it the index of a script. The script must have no parameters. To uninstall, assign a value of null.

Parameters

HandlerScriptIndex Index of handler script.
Notes

The handler script must have two parameters, x and y. If either of these parameters equals -1, check MouseX or MouseY instead of using the coordinate as specified.

The handler must return -1 if the mouse coordinates are not over the object, or a priority value if the coordinates are over the object.



property ShowDebugLines = false

If this is enabled, extra information will be drawn on the screen to indicate all objects' x- and y-positions, clickable areas, and path boudries, for the purpose of testing and debugging. During game development, it may be a good idea to assign a key to toggle this feature on and off.



property Filter = 0xFEFFFFFF

Sets the RGBA filter value for the sprite. When the sprite is drawn, each pixel in each frame will have its pixels filtered by the value.

See Also...



property FilterMode = FILTER_GLOBAL

Determines which of the available types of filtering to use. Currently, supported values are FILTER_GLOBAL, which shades the object evenly, and FILTER_GRADIENT, which determines the shade of the object at each corner.



property FilterTopLeft = 0xFFFFFFFF

If FilterMode is equal to FILTER_GRADIENT, this determines the filter value at the top-left corner of the object's sprite.



property FilterTopRight = 0xFFFFFFFF

If FilterMode is equal to FILTER_GRADIENT, this determines the filter value at the top-right corner of the object's sprite.



property FilterBottomLeft = 0xFFFFFFFF

If FilterMode is equal to FILTER_GRADIENT, this determines the filter value at the bottom-left corner of the object's sprite.



property FilterBottomRight = 0xFFFFFFFF

If FilterMode is equal to FILTER_GRADIENT, this determines the filter value at the bottom-right corner of the object's sprite.



property TransparencyMode = 0

When set to 1, the interpreter uses the alpha channel of the object's sprite. When set to 2, the interpreter blends the sprite additively (evenly adding the RGB value of the sprite to that of the pixel behind it). Otherwise, the interpreter disregards the alpha channel unless a filter has been applied, or PathAutoFilter has been enabled.



property PathAutoFilter = false

Turn automatic filtering according to the current path on or off. When false, the object's filter values will be determined by the Scale property, and when true, the scale value interpolated from the surrounding points on the current path.

See Also...



property Class = none

This lets you set another object as the class for the current object. This means that if an event occurs, and the current object does not have a script for handling that event, the object's class will be searched for a script to handle the event, then the class's class, and so on.



function SourceName

Provides the name of the object, as given in source code.

Returns

Index of a string containing the object's name.



function ParentScene

Provides the the scene the object belongs to.

Returns

Index of the scene.



function Say (String)

Function form of the say-statement. The active object will "say" the given line of text by entering the "talk" anim mode and having the line of text appear in a position typically above the character's head. The text will be centered and formatted automatically by the interpreter.

Parameters

String Index of string for the active object to say.



function SetPosition (ToX, ToY)

Moves an object's x- and y-position. If the object is using the relative coordinate system (absolute is false), the position is relative to the top left corner of the background image (no matter where it is scrolled). In absolute mode, the top-left corner of the screen is at position (0, 0) and the bottom-right is at (SCREEN WIDTH - 1, SCREEN HEIGHT - 1). (The y-values increase for lower positions on the screen.)

Generally, it is better to use the move function, which also takes animation into account.

Parameters

ToX New x-position.

ToY New y-position.



function SetClickArea (x1, y1, x2, y2)

This defines the clickable area of an object, which is relative to the object's position in relative mode, and the origin of the screen in absolute mode.

Parameters

x1 Left boundry of rectangle.

y1 Top boundry of rectangle.

x2 Right boundry of rectangle.

y2 Bottom boundry of rectangle.



function PlaySound (Sound_wav)

Plays Windows wave (WAV) resources, using the current object's SoundVolume, SoundPan, and SoundFrequency properties.

Using other features of the script language, sounds can be played in a continuous loops, at random intervals, and even while other sounds are being played by other scripts. Some of these features are demonstrated below.

Parameters

Sound_wav Resource index of sound to play.
Notes

This script can be found in the standard file functions.s.

Example
// Wait for a cow to "moo"
     PlaySound(Moo_wav);

     // Continue executing the current script during the "moo"
     start PlaySound(Moo_wav);
     
     // "Moo" continuously
     loop PlaySound(Moo_wav);

     // "Moo" at random intervals, without overlapping
     loop {
          delay random(100);
          PlaySound(Moo_wav);
     }

     // "Moo" at random intervals, with possible overlapping
     loop {
          delay random(100);
          start PlaySound(Moo_wav);
     }

     // Let a couple different frogs join in, a big slow frog,
     // and a small fast one, by starting two separate loops
     
     start loop {
          delay random(200);
          start PlaySound(Croak_wav);
     }
     start loop {
          delay random(50);
          start PlaySound(Ribbit_wav);
     }

     // And how about a cricket at position (200, 300), that stops
     // "chirping" when Ego gets within a 100-pixel radius
     start loop {          
          delay until FindDistance(Ego.x, Ego.y, 200, 300) >= 100;
          PlaySound(Chirp_wav);
     }

     // But be careful not to create an infinite loop, or else
     // it will execute forever and never return control to the
     // intepreter:

     loop start PlaySound(Moo_sound); // stampede!



function StartSound (Sound_wav)

This is just like PlaySound(), except it does not block execution of the calling script while the sound plays.

Parameters

Sound_wav Resource index of sound to play.



function StopSound

Stops the most recently started sound.



function SoundIsPlaying

Checks if this object is currently playing a sound.

Returns

True if a sound is playing, or false if not.



function SetAnim (All_sprite)

Each object has five anim modes: stop, walk, turn, talk, and play. There is a whole group of SetAnim functions that are used to specify which sprites will be displayed when an object is in a certain anim mode and facing a certain direction.

The names of these function follow a simple naming convention: Set<Mode>Anim<Configuration>. The modes are the five mentioned above. If the mode is not specified, the function will set the animations for all modes.

The configuration tells how the object should appear when it is facing each different direction.

Configuration Meaning Optimal Directions
(not given) unidirectional none
2H bidirectional (horizontal) east, west
2V bidirectional (vertical) north, south
4 4-directional north, east, south, west
4D 4-directional (diagonal) northeast, southeast, southwest, northwest
8 8-directional all of the above
12 12-directional all possible directions

The optimal configuration for an object is one that meets all its animation needs. A character that walks only left or right can be rendered perfectly using the 2H configuration, while a door (or other stationary object) can use a unidirectional configuration. More robust objects, such as the main character, can use configuration 4 for walking (or higher), 8 for standing, and 12 for turning, for optimal quality.

Parameters

All_sprite List of sprite resources (one for each direction supported by the particular configuration).
Example
setWalkAnim4(
     GuyWalkingNorth_sprite,
     GuyWalkingEast_sprite,
     GuyWalkingSouth_sprite,
     GuyWalkingWest_sprite);



function GetAnim (AnimMode, Direction)

Gets the sprite resource index for a given anim mode and direction (that was set using a SetAnim function).

Parameters

AnimMode Anim mode (ANIM_STOP, ANIM_WALK, ANIM_TURN, ANIM_TALK, or ANIM_PLAY).

Direction Direction (0 to 11).
Returns

Sprite resource index, or 0 if none was previously set.

Notes

Anim mode constants are defined in the standard script file "Constants.s".



function Walk (ToX, ToY)

Instructs the active object to walk to the given coordinates. If a path is specified, the shortest route will be calculated and followed. When the object is finished, it is put into the "stop" anim mode.

Parameters

ToX Target x-coordinate.

ToY Target y-coordinate.
Notes

This function is defined in the standard script file "Functions.s".



function Stop

Stops an object by putting it into the "stop" anim mode.

Notes

This function is defined in the standard script file "Functions.s".



function Turn (TowardsDirection)

Turns to face a given direction using the turn animation over several cycles, leaving the object in the "stop" anim mode.

Parameters

TowardsDirection Direction number to face.
Notes

This function is defined in the script file "Functions.s".



function Face (TowardsDirection)

Faces a given direction immediately without intermediate turning steps.

Parameters

TowardsDirection Direction to face (0 to 11).
Notes

This function is defined in the script file "Functions.s".



function Play (FirstFrame, FinalFrame, CyclesPerFrame)

Plays an object animation, using the animation configured under ANIM_PLAY. If the beginning frame index is greater than the ending frame index, the animation will play in reverse.

Parameters

FirstFrame Index of first frame to play.

FinalFrame Index of final frame to play.

CyclesPerFrame Number of cycles to show each frame.
Notes

This function is defined in the standard script file "Functions.s".



function Move (ToX, ToY)

Same as SetPosition, except the object is also put into the "stop" anim mode after it is moved.

Parameters

ToX X-position.

ToY Y-position.
Notes

This function is defined in the standard script file "Functions.s".



function SetTextPosition (HorizontalOffset, VerticalOffset)

Determines the offset of the center of the text an object displays when talking, relative to the object's position.

Parameters

HorizontalOffset Horizontal-offset of spoken text.

VerticalOffset Vertical-offset of spoken text.



function SetAnimFrameDelay (WhichAnimMode, DelayTime)

Sets the frame delay for a given anim mode, which is the number of cycles each frame in the animation will be displayed. Each anim mode has its own corresponding frame delay.

Parameters

WhichAnimMode The anim mode to affect.

DelayTime The number of cycles to show each frame.
Notes

All anim mode delays default to 1 cycle per frame.



function GetAnimFrameDelay (WhichAnimMode)

Gets the frame duration for a given anim mode. Each anim mode has its own corresponding frame delay.

Parameters

WhichAnimMode The anim mode to query.



function GetField (Field)

Gets a custom field from an object, which can be used by the programmer to store any data associated with an object. The field must have been previously created with a call to SetField; otherwise, GetField will return 0.

Parameters

Field Positive integer specifying the field to get.
Returns

The value stored in the field. If the field has not been created with a call to SetField, GetField will return 0.

See Also...



function SetField (Field, Value)

Sets and/or creates a custom field on an object. An object may have any number of fields.

Parameters

Field Positive integer specifying the field to set. If the field does not already exist, it will be created.

Value Value to set field to.
See Also...



function GetPathRGBA (X, Y)

Gets the RGBA filter value of the path at the given point.

Parameters

X X-coordinate at which to test.

Y Y-coordinate at which to test.
Returns

The RGBA filter value of the path at point (x,y)



function GetPathScale (X, Y)

Gets the scale value of the path at the given point.

Parameters

X X-coordinate at which to test.

Y Y-coordinate at which to test.
Returns

The scale value of the path at point (x,y)



function FindRoute (ToX, ToY)

Finds a route from the object's position (PositionX, PositionY) to the destination position (x, y). If the object has no path, then the route will always be a straight line.

Parameters

ToX Destination x-position

ToY Destination y-position



function InsidePath (TestX, TestY)

Tests whether the point is inside the object's current path.

Parameters

TestX x-position of point.

TestY y-position of point.
Returns

Returns true if the point is in the path, or false otherwise. (If there is no path currently selected, this function will always return true.)



function PutInsidePath

If there is a path for this object, and this object's position is outside of it, this function will put the object inside at the nearest point in the path. If the object is already inside the path, its positions will will not be affected.



function RouteSegments

Tells the number of line segments in the route most recently plotted by the FindRoute function.

Returns

This function returns zero if there is no route, or a number greater than zero if there is a route, which is the number of segments in the route.



function RouteSegmentX (SegmentIndex)

Tells the x-coordinate of the segment selected by the index.

Parameters

SegmentIndex Index of desired coordinate.



function RouteSegmentY (SegmentIndex)

Tells the x-coordinate of the segment selected by the index.

Parameters

SegmentIndex Index of desired coordinate.



function DeleteRoute

Deletes an objects route.



function ObjectAtPosition (x, y)

Searches for an object at the given coordinates.

Parameters

x X-coordinate.

y Y-coordinate.
Returns

If an object is found, its index is returned. Otherwise, if there is no object at that position, a hacky special value of -1 is returned instead.



function ObjectUnderMouse

Searches for an object at the mouse coordinates.

Returns

If an object is found, its index is returned. Otherwise, if there is no object under the mouse cursor, a value of -1 is returned instead.



function ObjectCount

Returns the number of objects in the game.