General Commands - adambiser/agk-adlib-plugin GitHub Wiki
Init
Init(emulator as integer) as integer
- emulator - The emulator to use.
1 = Nuked OPL3 emulator
2 = DOSBox emulator.
3 = Ken Silverman's emulator.
4 = Tatsuyuki Satoh's emulator.
5 = Dual OPL.
Initializes the OPL2 soft synth. This method should be called before attempting to do anything else with this plugin.
All emulators play as 16-bit stereo 44100 Hz sounds.
Returns: 1 on success; otherwise 0.
Update
Update()
Must be called each frame to ensure that the sound buffers are being loaded.
Shutdown
Shutdown()
Destroys the OPL2 soft synth and removes all songs. This is done when the plugin unloads and does not need to be explicitly called.
DeleteAllExternalData
DeleteAllExternalData()
Deletes all external data entries.
DeleteAllMusic
DeleteAllMusic()
Deletes all music managed by the plugin.
DeleteExternalData
DeleteExternalData(entryname as string)
- entryname - The name of the entry to remove.
Deletes an external data entry.
DeleteMusic
DeleteMusic(songID as integer)
- songID - The song ID to delete.
Deletes the song information and invalidates the ID.
GetMusicAuthor
GetMusicAuthor(songID as integer) as string
- songID - The ID of the song.
Returns a song's author.
Returns: A string.
GetMusicDescription
GetMusicDescription(songID as integer) as string
- songID - The ID of the song.
Returns the song's description.
Returns: A string.
GetMusicDuration
GetMusicDuration(songID as integer) as float
- songID - The song ID.
Returns the duration of the song in seconds. This should not be called on a song while it is playing or the song will start again from the beginning.
Returns: Duration in seconds.
GetMusicExists
GetMusicExists(songID as integer) as integer
- songID -
Checks the existence for the given song ID.
Returns: 1 if a song exists at the specified ID; otherwise 0.
GetMusicLoopCount
GetMusicLoopCount() as integer
Returns the number of times the current song has looped.
Returns: The loop count.
GetMusicPaused
GetMusicPaused() as integer
Returns whether music playback is paused.
Returns: 1 if paused; otherwise 0.
GetMusicPlaying
GetMusicPlaying() as integer
Returns whether the OPL synth is playing.
Returns: 1 if playing; otherwise 0.
GetMusicPosition
GetMusicPosition(songID as integer) as float
- songID - The song ID.
Returns the current position in the music file in seconds, between 0 for the beginning of the song and GetMusicDuration for the end of the song. This position is only an approximation.
Returns: Position in seconds.
GetMusicRate
GetMusicRate(songID as integer) as integer
- songID - The song ID.
Returns the song's playback rate.
Returns: The song's rate.
GetMusicSoundInstance
GetMusicSoundInstance() as integer
Returns the sound instance used for music playback. There should be no need to change the sound instance directly. Use the available plugin methods instead.
Returns: The sound instance ID.
GetMusicSubsong
GetMusicSubsong(songID as integer) as integer
- songID - The ID of the song.
Returns the current subsong for a song.
Returns: A 0-based subsong index.
GetMusicSubsongCount
GetMusicSubsongCount(songID as integer) as integer
- songID - The ID of the song.
Returns the number of subsongs in a song.
Returns: The number of subsongs in a song.
GetMusicSystemVolume
GetMusicSystemVolume() as integer
Returns the volume of the emulator.
Returns: An integer from 0 to 100.
GetMusicTitle
GetMusicTitle(songID as integer) as string
- songID - The ID of the song.
Returns a song's title.
Returns: A string.
GetMusicType
GetMusicType(songID as integer) as string
- songID - The ID of the song.
Returns a song's file type.
Returns: A string.
GetMusicVolume
GetMusicVolume(songID as integer) as integer
- songID - The song ID.
Returns the volume of the given song ID.
Returns: An integer from 0 to 100.
LoadExternalDataFromFile
LoadExternalDataFromFile(filename as string)
- filename - The file to load. This is used as the entry name internally.
Load external data required for some music file formats from a file. Will raise an error if an entry with this name already exists.
ie: The standard.bnk for ROL files.
LoadExternalDataFromFileEx
LoadExternalDataFromFileEx(filename as string, entryname as string)
- filename - The file to load.
- entryname - The name of the entry. Each music file format has its own naming convention.
Loads external data required for some music file formats from a file. Will raise an error if an entry with this name already exists.
ie: The standard.bnk for ROL files.
This is the same as LoadExternalDataFromFile, but allows the internal entry name to be set.
LoadExternalDataFromMemblock
LoadExternalDataFromMemblock(memblockID as integer, entryname as string)
- memblockID - The memblock to load.
- entryname - The name of the entry. Each music file format has its own naming convention.
Loads external data required for some music file formats from a memblock. Will raise an error if an entry with this name already exists.
An internal copy of the memblock is made. The memblock in the calling code can be deleted after calling this method.
ie: The standard.bnk for ROL files.
LoadMusicFromFile
LoadMusicFromFile(filename as string) as integer
- filename - The name of the file to load.
Loads song information from the given file name.
Returns: The music ID of the loaded song or 0 if an error occurs.
LoadMusicFromMemblock
LoadMusicFromMemblock(memblockID as integer, filetype as string) as integer
- memblockID - The memblock containing song information.
- filetype - The file extension without the leading period indicating the type of data in the memblock.
Loads song information from the given memblock.
Returns: The music ID of the loaded song or 0 if an error occurs.
PauseMusic
PauseMusic()
Pauses music playback. GetMusicPlaying will continue to return 1.
PlayMusic
PlayMusic(songID as integer, loop as integer)
- songID - The song ID to play.
- loop - The number of times to loop, or 1 to loop forever.
Play the song ID.
PlaySound
PlaySound(songID as integer, subsong as integer)
- songID - The song ID containing the subsong.
- subsong - The subsong to play.
Plays a subsong as a sound effect. Some file formats, such as ADL files, contain many subsongs, some that are music and some that are sound effects. Sound effects can be played simultaneously with the songs.
If the given song is not currently playing, the plugin will change to the given song. The subsong will be played one time.
ResumeMusic
ResumeMusic()
Resumes music playback if it was paused.
SeekMusic
SeekMusic(songID as integer, seconds as float, mode as integer)
- songID - The song ID.
- seconds - The time in seconds to seek to.
- mode - 0 for absolute seeking, 1 for relative seeking.
Seeks to a given time value within the song. If the song is currently playing, it will continue playing from the new position. If the song is not currently playing, it will take effect after the next call to PlayMusic.
If the song contains subsongs, this only affects the current subsong. Changing subsongs resets the seek position to the beginning.
SetMusicLoopCount
SetMusicLoopCount(loop as integer)
- loop - The number of times to loop, or 1 to loop forever.
Changes the number of times the current song will loop. This resets the loop count to 0.
SetMusicSubsong
SetMusicSubsong(songID as integer, subsong as integer)
- songID - The ID of the song.
- subsong - The subsong index.
Sets the subsong for a song. This also resets the seek position for the song to 0.
If changing the subsong for the currently playing song, the subsong will immediately begin playing from the beginning.
SetMusicSystemVolume
SetMusicSystemVolume(volume as integer)
- volume - A number between 0 and 100 inclusive.
Sets the volume of the emulator.
SetMusicVolume
SetMusicVolume(songID as integer, volume as integer)
- songID - The ID of the song to change.
- volume - A number between 0 and 100 inclusive.
Sets the volume for a song. By default, songs start with a volume of 100.
StopMusic
StopMusic()
Stops music playback.