CDAudio (int command, int param)This function allows you to play and control an audio CD in your game. Different tasks are performed, depending on the value of the COMMAND parameter. If there is no CD-ROM drive on the system, the function does nothing.
The PARAM parameter is used by some of the functions for various reasons; if it is not needed for the particular function you are calling, pass zero instead.
The tasks performed are as follows depending on the COMMAND parameter:
0 Query CD-ROM support - checks if there is a CD-ROM drive available on the system. Returns 1 if there is, and 0 if there is not. 1 Get playing status - checks whether the CD drive is currently playing an audio track. Returns 1 if it is, and 0 if it is not. 2 Play track - starts playback from track PARAM on the CD. If the track does not exist, or if it is a data track, nothing happens. 3 Pause playback - pauses the currently playing audio track. 4 Resume playback - continues from where the track was paused. 5 Get number of tracks - returns the number of tracks on the CD currently in the drive. If the drive is empty, returns 0. 6 Eject - ejects the drive tray if the drive has the ability. This is a feature you'll play with to start off because it's neat, and then realize that it has no real use in your game. Your script does not continue until the drive is fully ejected. 7 Close tray - the reverse of Eject. This will pull the drive tray back in again. Your script does not continue until the drive has been fully closed. 8 Get number of CD-ROM drives - returns the number of CD drives in the system, normally 1. 9 Select current CD-ROM drive - changes the current CD drive to PARAM, where PARAM ranges from 1 to (number of CD drives). All the other CD Audio functions operate on the current CD drive.NOTE: These CD Audio functions are slow compared to all the other script functions. This will not be noticeable if you call them from most scripts, but using CDAudio in a repeatedly_execute script will noticeably slow down the game.
NOTE: If the game is run under plain MS-DOS, the user's CD-ROM driver will need to be loaded in memory for these functions to work. If it is not, the game assumes that there is no CD-ROM drive on the system.
NOTE: The Windows version of the engine only supports a single CD-ROM drive, so functions 8 and 9 currently do not work.
Example:
CDAudio(2,3);will play track 3 of the CD that’s in the CD ROM drive.
GetCurrentMusic()Returns the number of the currently playing background music, or -1 if no music is playing.
Example:
if (GetCurrentMusic()==-1)
PlayMusic(2);
will play music2 if no music is playing.See Also: IsMusicPlaying, IsSoundPlaying, SetMusicRepeat, SetMusicVolume
GetMIDIPosition ()Returns the current MIDI beat number of the current track. If there is no track playing, or if it's not a MIDI track, returns -1.
Example:
if(GetMIDIPosition()==50) PlayMusic(2);will play music2 if the current midi’s beat is the 50th beat.
See Also: SeekMIDIPosition
GetMP3PosMillis ()Returns the position of the currently playing MP3 background music file, in milliseconds from the start.
If the current track is not an MP3 track, returns 0.
Example:
if (GetMP3PosMillis() > 30000) SeekMP3PosMillis(0);will loop the track back to the start after 30 seconds.
See Also: SeekMP3PosMillis
IsMusicPlaying ()Returns 1 if the background music track is still playing. If you are using the Repeat Music option, this will always return 1 since the music will loop round when it finishes. Otherwise, this will return 0 once the current track finishes.
Example:
if(IsMusicPlaying()==0) PlayMusic(3);will play music3 if no music is playing.
See Also: GetCurrentMusic
IsMusicVoxAvailable()Returns whether the MUSIC.VOX file is being used by the game. This could be useful if you have an optional MP3 download pack, and you want to know whether the player has it or not.
Returns 1 if the MP3 music files are available, 0 if not.
NOTE: This function ONLY deals with the MUSIC.VOX file. If you have bundled MP3 files seperately in the game directory, they will still be played by the game, but this function will not return 1 if they are there.
Example:
if (IsMusicVoxAvailable()==0)
Display ("You don't have the music pack");
will display a message if the music pack is not available.See Also: IsVoxAvailable
IsSoundPlaying ()Returns 1 if there is currently a sound effect playing. This could be a manually started sound (eg. with PlaySound) or an automatic sound (eg. with GiveScore).
If the sound has finished, or none was played, returns 0.
NOTE: Be careful with this function for actions like looping sounds, since if the user doesn't have a sound card this will always return 0.
NOTE: This function does not report if background music or ambient sounds are playing.
Example:
if (IsSoundPlaying()==0) PlaySound(20);will play sound20 if no sound is playing.
See Also: GetCurrentMusic
IsVoxAvailable()Returns whether the SPEECH.VOX file is being used by the game. This could be useful if you have an optional speech download pack, and you want to know whether the player has it or not.
Returns 1 if the speech files are available, 0 if not.
Example:
if (IsVoxAvailable()==0)
Display ("You don't have the voice pack");
will display a message if the voice pack is not available.See Also: IsMusicVoxAvailable
PlayAmbientSound (int channel, int sound, int volume, int x, int y)Plays a looping sound effect in the background.
CHANNEL is the sound channel number. Currently this must always be 1, but in future multiple sounds at once may be supported in which case you would be able to specify a different channel.
SOUND is the sound number, which identifies the file to load. The game will try to load SOUNDx.MP3 and SOUNDx.WAV, where X is the sound number you specify here.
VOLUME is the volume of the sound. This can be from 1 to 255, where 255 is the loudest. Generally you won't want to make this very loud since it's only supposed to be a background noise, such as a humming machine room or flowing water.
X and Y allow you to specify co-ordinates if you want a directional ambient sound. If you just pass X and Y as zero, the sound will be played at the specified volume throughout the room. However, if there is a certain spot in the room where the sound is emanating from, you can pass its co-ordinates here, and the sound will get louder as the player approaches that spot in the room. In this case, the VOLUME parameter specifies the maximum possible volume, when the player is standing right on the spot.
NOTE: The sound will stop when the player leaves the room.
NOTE: In order to optimise the looping of the sound, the entire sound effect is loaded into memory. Therefore, do not use this function to play normal background music with, since music files tend to be very large and are better streamed from disk with the normal music functions.
Example:
PlayAmbientSound (1, 10, 150, 250, 110);starts SOUND10.MP3 playing in the background, at a medium volume and coming from co-ordinates (250, 110).
See Also: PlayMusic, PlaySound, StopAmbientSound
PlayFlic (int flic_number, int options)Plays a FLI or FLC animation. The game checks for FLICx.FLC and FLICx.FLI (where X is FLIC_NUMBER) and if it finds one, plays it.
OPTIONS has these meanings:
0 player can't skip animation 1 player can press ESC to skip animation 2 player can press any key or click mouse to skip animation +10 (ie.10,11,12) do not stretch to full-screen, just play at flc sizeThis is identical to the room interaction command "Play FLI/FLC VAL". The game is paused while the animation plays.
Example:
PlayFlic (2,1);will play flic2 and the player will be able to skip the flic by pressing the ESC key.
See Also: PlayVideo
PlayMusic (int music_number)Changes the currently playing background music to MUSICx.MID, MUSICx.MOD or MUSICx.XM (where X is MUSIC_NUMBER). The game will search for the files in that order until it finds one to play.
Example:
PlayMusic(2);will play music2.
See Also: PlaySound, StopMusic
PlaySound (int sound_number)Plays a WAV or VOC sound effect. The game will search for SOUNDx.VOC and SOUNDx.WAV (where x is SOUND_NUMBER) and play it. This is identical to the room interaction command "Play sound VAL".
Pass -1 as SOUND_NUMBER to stop any currently playing sounds.
Example:
PlaySound(3);will play sound3.
See Also: PlayMusic
PlayVideo (string filename, int skip, int flags)Plays an AVI or MPG file, or any other file type supported by Media Player.
FLAGS can be one of the following:
0: the video will be played at original size, with AVI audio 1: the video will be stretched to full screen, with appropriate black borders to maintain its aspect ratio and AVI audio. 10: original size, with game audio continuing (AVI audio muted) 11: stretched to full screen, with game audio continuing (AVI audio muted)SKIP defines how the player can skip the video:
0 player can't skip video 1 player can press ESC to skip video 2 player can press any key to skip animationThe game is paused while the animation plays.
IMPORTANT: This function is ONLY supported by the Windows engine. The DOS engine simply ignores this command.
IMPORTANT: Any video files you have for this cannot be compiled into the main game data file, so you will have to place them seperately in the Compiled folder for them to work.
IMPORTANT: The end player will have to have the correct codecs installed in order to play the video. Bear in mind that if you encode your intro with DivX, for instance, the player will need to have that codec installed in order to view the video.
NOTE: Since the video must play at your game's colour depth, you may notice that in a 256-colour game it is very difficult to get a video that looks good, due to the attempt to reduce the depth of the video on the fly. FLIC may be a better choice for 256-colour games.
Example:
PlayVideo ("intro.mpg", 1, 1);
will play the video Intro.mpg, allowing the player to skip with ESC if they've seen it
before.See Also: PlayFlic
SeekMIDIPosition (int position)Seeks the currently playing MIDI file to midi beat number POSITION. If the current track is not a MIDI track, has no effect.
Example:
SeekMIDIPosition(60);will play the current midi from beat number 60..
See Also: GetMIDIPosition
SeekMODPattern (int pattern)Jumps directly to PATTERN in the currently playing MOD/XM music. If the pattern does not exist, the music will stop.
Example:
SeekMODPattern(30);will play the current mod from pattern 30.
SeekMP3PosMillis (int position)Seeks the currently playing MP3 background music file to POSITION milliseconds from the start. If the current track is not an MP3 track, has no effect.
Example:
SeekMP3PosMillis(30000);will seek the current MP3 to 30 seconds from its start.
See Also: GetMP3PosMillis
SetMusicMasterVolume (int volume)Sets the overall music volume, from 0-100. This is slightly mofidied by the individual room volume settings.
Example:
SetMusicMasterVolume(80);will set the music volume to 80.
See Also: SetMusicVolume
SetMusicRepeat (int loopflag)Tells the system whether to repeat background music tracks. LOOPFLAG is either 1 (repeat, default) or 0 (don't repeat).
This function must be called BEFORE PlayMusic - it sets whether future music tracks will repeat or not.
Example:
SetMusicRepeat(1);will loop the background music.
See Also: SetMusicVolume
SetMusicVolume (int volume)Overrides the room volume setting and sets the volume to VOLUME instead. The values range from 1 to 5, representing each stage in the RoomEdit volume options (ie. 1=quietest, 5=loudest). NOTE: The volume will be reset when the player enters a new room.
Example:
SetMusicVolume(1);will set the room volume to quitest.
See Also: SetMusicMasterVolume, SetSoundVolume, GetCurrentMusic
SetSoundVolume (int volume)Sets the sound effect volume. VOLUME ranges from 0-255, where 255 is the loudest. This also effects MOD and XM music.
Example:
SetSoundVolume(230);will set the sound effects volume to 230.
See Also: SetMusicVolume
SetSpeechVolume (int volume)Sets the volume for in-game speech. VOLUME ranges from 0-255, where 255 is the loudest. The default speech volume is 255 so this function can only be used to reduce the volume.
Example:
SetSpeechVolume(200);will set the speech volume to 200.
See Also: SetMusicVolume, SetSoundVolume
SetVoiceMode (int new_mode)Changes whether voice speech is used with dialog lines. The default is on if the voice file is present, or off otherwise.
Valid values are:
0 no voice, text only 1 both voice and text 2 voice only, no textWARNING: you should only ever use mode 2 at the player's request to do so, because there is no guarantee that they even have a sound card and so may not understand what is going on.
Example:
if (IsVoxAvailable()==1)
SetVoiceMode(1);
will set the voice mode to voice and text if the voice pack is available.
StopAmbientSound (int channel)Stops the currently playing ambient sound on the specified channel (which must always be 1 in this version of AGS).
See Also: PlayAmbientSound
StopMusic ()Stops the currently playing background music.
Example:
StopMusic();See Also: PlayMusic