Script Language: Predefined Functions and Properties: Interpreter System


These properties and functions are used to define the operation of the interpreter.

Properties


Functions



property CycleTime = none

Delay time in milliseconds between interpreter cycles.

Example
// set 30-frames-per-second
CycleTime = 1000/30;



property PlayerObject = none

Tells the interpreter which object becomes the active one whenever an event which is not explicitly associated with any object is started. This is usually the player character.

Example
playerObject = Ego;



property DefaultFont = none

This property must be set in the game's main event. It chooses which font to use if an object's font property, or the printFont property is not set.

Example
deafultFont = MyFavorite_font;



property SoundMasterVolume = VOLUME_HALF

Sets the master volume for sound and music. Valid levels range from 0 (mute) to 255 (full). The constants VOLUME_MUTE, VOLUME_HALF, and VOLUME_FULL are predefined.



function ShellExecute (filename, arguments, directory, wait)

Executes a program using the Windows command-line.

Parameters

filename Filename of the program. You may specify the full path to the file. If the full path is not given, the path of "Play.exe" will be assumed.

arguments Command-line arguments to pass to the program. You may set this to null if there are none to pass.

directory The program will be run with this directory set as current.

wait Set this to true if you want the interpreter to minimize, and wait for the program to return before continuing. Otherwise, the external program will run in the background.
Returns

ShellExecute always returns 0.



function CallScript (ScriptIndex)

This function calls a user-defined script. CallScript may only be used to call scripts, not interpreter functions.

Parameters

ScriptIndex Index of the script to be called.
Returns

Value returned by the script.

Notes

CallScript is a wrapper for a call statement, and is provided mainly for compatibility with version 1.08 of AGAST.

This standard script is defined in functions.s.



function CurrentScene

Gets the index of the current (the most recently entered) scene.

Returns

Index of this scene.



function PreviousScene

Returns the index of the most recently exited scene.

Returns

Index of last scene.



function InstallScreenPreDrawingHandler (HandlerScriptIndex)

This handler is called after the background is painted and before the objects are drawn. An example in which this hander might be handy is to draw shadows under certain objects.

Parameters

HandlerScriptIndex Index of handler script, which should have no parameters.



function InstallScreenPostDrawingHandler (HandlerScriptIndex)

This handler is called after the objects have been drawn. It might be used to draw text overlays, for example, such as interactive menus or displays that are active while the game is in progress.

Parameters

HandlerScriptIndex Index of handler script, which should have no parameters.



function InstallScreenDrawingHandler (HandlerScriptIndex)

If this is installed, it will override the the automatic drawing of objects. The paint handler accepts no arguments.

Parameters

HandlerScriptIndex Index of handler script, which should have no parameters.



function InterruptCaptions

This will interrupt the caption of any object who's captionClick property is set to true, thereby causing it to disappear and continue their scripts.



function RestartGame

Restarts the game just as if the user quit the interpreter and loaded it up again.



function SaveGame (Slot)

This saves a game in a slot.

Saving a game kills the script that is currently running.

Parameters

Slot A positive slot number.



function RestoreGame (Slot)

This restores a previously saved game. Saved-games are invalid to future game compilations. In other words, when you run the compiler, all your saved games will become unrestorable.

Restoring a game kills the script that is currently running.

Parameters

Slot A positive slot number.
Returns

If this function returns at all, the restore operation was unsuccessful.



function QuitGame

Immediately quits the interpreter program.



function MinimizeGame

This minimizes the interpreter program and returns to the Windows desktop. The game will remain paused until the user returns to it by clicking on the "interpreter" icon in the Windows taskbar or pressing Alt-Tab or Alt-Esc.



function SetWindowCaption (caption)

Changes the caption of the interpreter window.

Parameters

caption The new caption.



function PlayMusic (MusicResource)

Plays these types of resources:

  • MIDI Format (MID/MIDI/RMI)
  • Various Module Formats (MOD, S3M, XM, IT)
  • Mpeg Streams (MP2, MP3)
  • Ogg Vorbis Stream (OGG)

If the resource is already being played, this function will block execution until the end of that song. [MP2, MP3, and OGG formats will not block, causing this function to behave identically to StartMusic.]

Parameters

MusicResource The music resource to play.
Notes

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



function StartMusic (MusicResource)

Same as PlayMusic(), except it does not block execution of the calling script.

Using this function, it is possible to play the same song during the same time.

Parameters

MusicResource The music resource to start playing.



function SetMusicLoopCount (MusicResource, LoopCount)

Sets the number of times a music resource should loop (repeat) before finishing.

Parameters

MusicResource The music resource to loop.

LoopCount Number of loops. LOOP_NONE for no looping, LOOP_FOREVER to loop endlessly.

 LoopMusic
Notes

Currently only supported for MPEG and OGG VORBIS resources.



function MusicIsPlaying (MusicResource)

Checks if a particular music resource is playing.

Parameters

MusicResource The music resource to test.
Returns

True or false.

Example
// wait for the music to stop
                         delay while MusicIsPlaying(Popcorn_mid);



function StopMusic (MusicResource)

Stops playing a music resource that is currently playing.

Parameters

MusicResource The music resource to stop playing.
Example
StopMusic(Popcorn_mid);



function SetMusicPosition (MusicResource, time)

Sets the position of a currently playing piece of music.

Parameters

MusicResource The music resource to adjust.

time The new position, in miliseconds.
Notes

At this time, SetMusicPosition works only for MP3 and Ogg files.



function GetMusicPosition (MusicResource)

Gets the position of a currently playing piece of music.

Parameters

MusicResource The music resource being checked.
Returns

The current position of the song, in miliseconds.

Notes

At this time, GetMusicPosition works only for MP3 and Ogg files.



function StopAllSound

Stops all sounds that are currently playing.



function StopAllMusic

Stops all music that is currently playing.



function SetDisplayMode (width, height)

Changes the graphics mode.

Parameters

width Width of the display.

height Height of the display.



function PlayMovie (file)

Plays a video from a file. While the video is playing, no input is received, no objects are drawn, and no scripts are executed. Since AGAST plays the video back using Windows Media Player, the video may be encoded using any codec present on the user's system. If you're using a codec not included with Windows (for example, DivX), you might want to install it with your game.

Parameters

file Name of the file to play back.
Notes

Due to the added complexity of implementing .asf playback, PlayMovie does not currently support the .asf format.

To avoid bloating resource.data, movie files are not treated as normal resources. Instead, they must be distributed with your game and opened as files.

Example
print("Meanwhile,  in the king's audience chamber...");
          playMovie("audienceChamber.mpg");