@bscotch/gml-parser

<?xml version="1.0" encoding="utf-8"?> <GameMakerLanguageSpec xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" RuntimeVersion="2022.4" Module="Base"> <Functions> <Function Name="animcurve_channel_evaluate" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function can be used to get the value at a specific point in time from a channel struct. You supply the struct pointer for the channel (as returned by the function animcurve_get_channel(), or as returned in the animation curve struct from the function animcurve_get()) and the "x" (time) position along the curve channel to evaluate. This position should be between 0 and 1, and the function will return the curve value at that position, or it will return 0 if the channel struct supplied is invalid.</Description> <Parameter Name="channel_struct" Type="Struct.AnimCurveChannel" Optional="false">The struct pointer for the channel to evaluate.</Parameter> <Parameter Name="posx" Type="Real" Optional="false">The position in time to check (from 0 to 1).</Parameter> </Function> <Function Name="animcurve_channel_new" Deprecated="false" ReturnType="Struct.AnimCurveChannel" Pure="true"> <Description>This function can be used to create a new animation curve channel struct. A channel struct has the following variables:</Description> </Function> <Function Name="animcurve_create" Deprecated="false" ReturnType="Struct.AnimCurve" Pure="true"> <Description>This function will create an empty animation curve struct, ready for you to populate with channel data. The function will return a pointer to the struct and this is then used to add channels and other data to the animation curve. You can also supply this to functions like animcurve_get() to later get the data from the curve.</Description> </Function> <Function Name="animcurve_destroy" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function can be used to destroy any animation curves that have been previously created with the function animcurve_create(). Calling this function will remove the animation curve from memory and clean up any channels or points that it contains as well (these never need to be cleaned up manually). Note that you cannot destroy any animation curves created in the asset browser, only those created at runtime.</Description> <Parameter Name="curve_struct" Type="Struct.AnimCurve" Optional="false">The pointer to the curve struct to destroy.</Parameter> </Function> <Function Name="animcurve_get" Deprecated="false" ReturnType="Struct.AnimCurve" Pure="true"> <Description>This function will return a struct containing all the data for the given animation curve. You supply the animation curve asset ID (as defined in the Asset Browser), and the function will return a struct with the following variables:</Description> <Parameter Name="curve_id" Type="Asset.GMAnimCurve" Optional="false">The asset browser ID (index) of the animation curve to get.</Parameter> </Function> <Function Name="animcurve_get_channel" Deprecated="false" ReturnType="Struct.AnimCurveChannel" Pure="true"> <Description>This function will return the struct containing the channel data for the channel specified in an animation curve asset. You supply the animation curve ID or struct as well as the channel name or index, and the function will return a struct with the following format:</Description> <Parameter Name="curve_struct_or_id" Type="Any" Optional="false">The ID or struct pointer of the animation curve to target</Parameter> <Parameter Name="channel_name_or_index" Type="Any" Optional="false">The channel name (a string) or the channel index (an integer).</Parameter> </Function> <Function Name="animcurve_get_channel_index" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the index value for any given animation curve channel. You supply the animation curve ID or struct, where the curve ID is the name of the animation curve as it was defined in the Asset Browser, or the struct pointer as returned by the function animcurve_create(). You then supply the name of the channel, as a string, and the function will return the index value associated with that channel. Note that if the curve or channel does not exist then you will get an error.</Description> <Parameter Name="curve_struct_or_id" Type="Any" Optional="false">The ID or struct pointer of the animation curve to target</Parameter> <Parameter Name="channel_name" Type="String" Optional="false">The channel name (a string).</Parameter> </Function> <Function Name="animcurve_point_new" Deprecated="false" ReturnType="Struct.AnimCurvePoint" Pure="true"> <Description>This function can be used to create a new points struct to be added to an animation curve channel. When created a points struct is empty and you need to set the following variables to generate the point data:</Description> </Function> <Function Name="asset_add_tags" Deprecated="false" ReturnType="Bool" Pure="false"> <Description>With this function you can add one or more tag strings to any asset from the asset browser. You supply either the asset name (as a string) or its asset index, as well as either a single tag string or an array where each item is a single tag string. If you supply an asset index value, then you will need to supply the optional asset type argument (a constant), as assets of different types can have the same index, even though they cannot have the same name. The available asset types are listed in the table below:</Description> <Parameter Name="name_or_index" Type="Any" Optional="false">The name of the asset (a string) or its index value (an integer).</Parameter> <Parameter Name="tags" Type="String,Array[String]" Optional="false">A single asset tag string or an array with various asset tags.</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="true">OPTIONAL! The type of asset to set the tags on, only used when supplying an index for the first argument.</Parameter> </Function> <Function Name="asset_clear_tags" Deprecated="false" ReturnType="Bool" Pure="false"> <Description>With this function you can clear all the tags present on any asset from the asset browser. You supply either the asset name (as a string) or its asset index, and if you supply an asset index value, then you will need to supply the optional asset type argument (a constant), as assets of different types can have the same index, even though they cannot have the same name. The available asset types are listed in the table below:</Description> <Parameter Name="name_or_index" Type="Any" Optional="false">The name of the asset (a string) or its index value (an integer).</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="true">OPTIONAL! The type of asset to clear the tags from, only used when supplying an index for the first argument.</Parameter> </Function> <Function Name="asset_get_index" Deprecated="false" ReturnType="Real" Pure="true"> <Description>You can use this function to get the unique identifying index for a game asset from its name. If the asset is not found, the function will return a value of -1, otherwise it will return the unique index id for the asset being checked. This id can then be used in other functions as you would any other index value, like the sprite_index or the path_index, for example. Please note that although this function can be used to reference assets from strings (see example below) you should always make sure that the asset exists before using it otherwise you may get errors that will crash your game.</Description> <Parameter Name="name" Type="String" Optional="false">The name of the game asset to get the index of (a string).</Parameter> </Function> <Function Name="asset_get_tags" Deprecated="false" ReturnType="Array[String]" Pure="true"> <Description>With this function you can retrieve all the tags assigned to an asset from the Asset Browser. You supply either the asset name (as a string) or it's asset index, and the function will return an array of tags for that asset. If no tags are found or there is an error (ie: the name string given doesn't exist) then the returned array will be empty. If you supply an asset index value, then you will need to supply the optional asset type argument (a constant), as assets of different types can have the same index, even though they cannot have the same name. The available asset types are listed in the table below:</Description> <Parameter Name="name_or_index" Type="Any" Optional="false">The name of the asset (a string) or its index value (an integer).</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="true">OPTIONAL! The type of asset to get the tags for, only used when supplying an index for the first argument.</Parameter> </Function> <Function Name="asset_get_type" Deprecated="false" ReturnType="Constant.AssetType" Pure="true"> <Description>With this function you can get the type of asset being referenced from its name (a string). One of the constants listed below will be returned.</Description> <Parameter Name="name" Type="String" Optional="false">The name of the game asset to get the type of (a string).</Parameter> </Function> <Function Name="asset_has_tags" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>With this function you can check to see if one or more tag strings is assigned to any asset from the asset browser. You supply either the asset name (as a string) or its asset index, as well as either a single tag string or an array where each item is a single tag string. If you supply an asset index value, then you will need to supply the optional asset type argument (a constant), as assets of different types can have the same index, even though they cannot have the same name. The available asset types are listed in the table below:</Description> <Parameter Name="name_or_index" Type="Any" Optional="false">The name of the asset (a string) or its index value (an integer).</Parameter> <Parameter Name="tags" Type="String,Array[String]" Optional="false">A single asset tag string or an array with various asset tags.</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="true">OPTIONAL! The type of asset to check the tags for, only used when supplying an index for the first argument.</Parameter> </Function> <Function Name="asset_remove_tags" Deprecated="false" ReturnType="Bool" Pure="false"> <Description>With this function you can remove one or more tag strings to any asset from the asset browser. You supply either the asset name (as a string) or its asset index, as well as either a single tag string or an array where each item is a single tag string. If you supply an asset index value, then you will need to supply the optional asset type argument (a constant), as assets of different types can have the same index, even though they cannot have the same name. The available asset types are listed in the table below:</Description> <Parameter Name="name_or_index" Type="Any" Optional="false">The name of the asset (a string) or its index value (an integer).</Parameter> <Parameter Name="tags" Type="Any" Optional="false">A single asset tag string or an array with various asset tags.</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="true">OPTIONAL! The type of asset to remove the tags from, only used when supplying an index for the first argument.</Parameter> </Function> <Function Name="tag_get_assets" Deprecated="false" ReturnType="Array[String]" Pure="true"> <Description>With this function you can retrieve the names of all assets that have been assigned the given tag or tags. You supply either a single tag string or an array, where each item in the array is a tag string. The function will return an array where each entry is the name (as a string) of the asset with the given tag. If you need the unique index for the asset, then you can use the function asset_get_index() along with the returned name. If there are no assets with the given tag(s), or if there is an error (eg: the given tags do not exist), then an empty array will be returned.</Description> <Parameter Name="tags" Type="String,Array[String]" Optional="false">A single asset tag string or an array with various asset tags.</Parameter> </Function> <Function Name="tag_get_asset_ids" Deprecated="false" ReturnType="Array[Asset]" Pure="true"> <Description>With this function you can get all the assets of a given type that have the given tags assigned to them. You supply either a single tag (as a string) or an array, where each item in the array is a tag (as a string), as well as the type of asset to check. the type of asset should be one of the following constants:</Description> <Parameter Name="tags" Type="String,Array[String]" Optional="false">A single asset tag string or an array with various asset tags.</Parameter> <Parameter Name="asset_type" Type="Constant.AssetType" Optional="false">An asset type constant (listed above)</Parameter> </Function> <Function Name="audio_channel_num" Deprecated="false" ReturnType="Undefined" Pure="true"> <Description>With this function you can set how many audio channels are available for playing audio in GameMaker. What this basically means is that you give the number of simultaneous sounds that can be played at any one time, and if the number exceeds the amount, those sounds with a lower priority are stopped to free up a channel for the sounds with a higher priority. You can use this function to optimise your game for devices as the lower the number of channels for audio the better the performance, but bear in mind that this may also cause noticeable cut off of certain sounds if many are played at once.</Description> <Parameter Name="num" Type="Real" Optional="false">Number of available audio channels (default is 128).</Parameter> </Function> <Function Name="audio_create_stream" Deprecated="false" ReturnType="Asset.GMSound" Pure="true"> <Description>With this function you can create a new sound index which can then be used in the regular audio functions to stream audio directly from an external OGG file source. The function requires the filename (which can be an included file, for example) and will return the new sound index for use. Note that after you no longer need the sound you should call the function audio_destroy_stream() with the sound index to remove it from memory otherwise you may get a memory leak which will slow down and eventually crash your game.</Description> <Parameter Name="filename" Type="String" Optional="false">The file (OGG only) to stream the audio from.</Parameter> </Function> <Function Name="audio_debug" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function can be used to display debug information about the audio system, with true switching it on and false to switch it off. When you are debugging audio in this way, the overlay will show the following information:</Description> <Parameter Name="enable" Type="Bool" Optional="false">Enable (set to true) or disable (false) audio debugging.</Parameter> </Function> <Function Name="audio_destroy_stream" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>If you have previously created an audio stream from a file using the function audio_create_stream() and no longer need that sound, you can call this function to delete it from memory. Any further calls to the sound index after it has been destroyed will give an error. It should be noted that this will free up the stream but on the target platform this may not show up in a memory manager. This is because GameMaker pools memory resources to prevent memory allocation overhead, and so the memory will remain allocated until required for something else or re-used for a new stream.</Description> <Parameter Name="filename" Type="String" Optional="false">The file to stream the audio from.</Parameter> </Function> <Function Name="audio_exists" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function returns whether a sound exists (true) or not (false). Note that if the index you search for has not been initialised previously, this function will cause an error as it is searching for non-existent asset indices. The sound to check can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to check the existence of.</Parameter> </Function> <Function Name="audio_falloff_set_model" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>To add more versatility to the audio engine, GameMaker permits you to select the falloff model that suits your game. This model will be used for all the audio functions in the game or app, and so you should make sure that the model you choose is the correct one, as each one will affect how the listener perceives the sounds you play through emitters or with the function audio_play_sound_at.</Description> <Parameter Name="model" Type="Constant.AudioFalloff" Optional="false">The constant used to set the falloff model.</Parameter> </Function> <Function Name="audio_get_master_gain" Deprecated="false" ReturnType="Real" Pure="true"> <Description>With this function you can get the absolute value for the global volume of all sounds and music for a specific listener. The default listener index is 0, but you can use the function audio_get_listener_info() to get the different indices available for the target platform. The gain value returned is based on a linear scale from 0 (silent) to 1 (full volume). Note that on some platforms you can have a gain of greater than 1, although a value of 1 is considered "full volume" and anything greater may introduce audio clipping.</Description> <Parameter Name="listenerindex" Type="Id.AudioListener" Optional="false">The index of the listener to get the gain of.</Parameter> </Function> <Function Name="audio_get_name" Deprecated="false" ReturnType="String" Pure="true"> <Description>This function will return the name of a given audio resource as a string. The "index" value can be that of the resource itself (as seen in the Asset Browser) or the unique ID value that is given when you play the sound using, for example, audio_play_sound(). Note that the string returned is not the same as the resource ID and cannot be used to access the resource itself, so should only be used for displaying or error checking.</Description> <Parameter Name="index" Type="Id.Sound,Asset.GMSound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_get_type" Deprecated="false" ReturnType="Real" Pure="true"> <Description>When adding audio to GameMaker it can be either streamed or in memory. If you need to know whether a given sound index is for streamed audio or not you can use this function which will return 1 for streamed, 0 for sound in memory, and -1 if there is any error or the index does not point to a valid sound resource.</Description> <Parameter Name="index" Type="Id.Sound,Asset.GMSound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_is_paused" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function will check the given sound to see if it is currently paused. The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset, in which case all instances of the given sound will be checked and if any of them are paused the function will return true otherwise it will return false.</Description> <Parameter Name="index" Type="Id.Sound,Asset.GMSound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_is_playing" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function will check the given sound to see if it is currently playing. The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset, in which case all instances of the given sound will be checked and if any of them are playing the function will return true otherwise it will return false. Note that this function will still return true if the sound being checked has previously been paused using the audio_pause_sound() function.</Description> <Parameter Name="index" Type="Id.Sound,Asset.GMSound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_master_gain" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can set the absolute value for the global volume of all sounds and music. It is based on a linear scale from 0 (silent) to any value greater than 0, although normally you'd consider the maximum volume as 1. Anything over 1 can be used but, depending on the sound used and the platform being compiled to, you may get distortion or clipping when the sound is played back. This function will affect the relative volume of all sounds and music played from within your game.</Description> <Parameter Name="gain" Type="Real" Optional="false">Value for the global volume (0 to 1).</Parameter> </Function> <Function Name="audio_pause_all" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can pause all sounds that are currently playing.</Description> </Function> <Function Name="audio_pause_sound" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can pause any sound that is currently playing. The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset, in which case all instances of the given sound will be paused.</Description> <Parameter Name="index" Type="Id.Sound,Asset.GMSound" Optional="false">The index of the sound to pause.</Parameter> </Function> <Function Name="audio_play_sound" Deprecated="false" ReturnType="Id.Sound" Pure="false"> <Description>With this function you can play any sound resource in your game. You provide the sound index and assign it a priority, which is then used to determine how sounds are dealt with when the number of sounds playing is over the limit set by the function audio_channel_num(). Lower priority sounds will be stopped in favour of higher priority sounds, and the priority value can be any real number (the actual value is arbitrary, and can be from 0 to 1 or 0 to 100, as GameMaker will prioritize them the same). Note that when dealing with priority, the higher the number the higher the priority, such that a sound with priority 100 will be favoured over a sound with priority 1. The final argument is for making the sound loop and setting it to true will make the sound loop until it is stopped and setting it to false will play the sound once only.</Description> <Parameter Name="index" Type="Asset.GMSound" Optional="false">The index of the sound to play.</Parameter> <Parameter Name="priority" Type="Real" Optional="false">Set the channel priority for the sound.</Parameter> <Parameter Name="loop" Type="Bool" Optional="false">Sets the sound to loop or not.</Parameter> <Parameter Name="gain" Type="Real" Optional="true">Sets the gain of the sound played.</Parameter> <Parameter Name="offset" Type="Real" Optional="true">Sets the start offset (in seconds) of the sound played.</Parameter> <Parameter Name="pitch" Type="Real" Optional="true">Sets the pitch of the sound played.</Parameter> <Parameter Name="listener_mask" Type="Real" Optional="true">Sets the listener mask of the sound played.</Parameter> </Function> <Function Name="audio_play_sound_at" Deprecated="false" ReturnType="Id.Sound" Pure="false"> <Description>With this function you can play any sound resource at a given position within the audio space. You provide the sound index and then assign it a position within the 3D space. The default listener position is (0, 0, 0) so this means that if the listener has not been moved and you want the sound to come from the left (for example), you should set the x position to a negative value (for more information on setting the listener position see audio_listener_position()).</Description> <Parameter Name="index" Type="Asset.GMSound" Optional="false">The index of the sound to play.</Parameter> <Parameter Name="x" Type="Real" Optional="false">The x position.</Parameter> <Parameter Name="y" Type="Real" Optional="false">The y position.</Parameter> <Parameter Name="z" Type="Real" Optional="false">The z position.</Parameter> <Parameter Name="falloff_ref" Type="Real" Optional="false">The falloff reference relative to the listener (clamp).</Parameter> <Parameter Name="falloff_max" Type="Real" Optional="false">The maximum falloff distance relative to the listener.</Parameter> <Parameter Name="falloff_factor" Type="Real" Optional="false">The falloff factor (default 1).</Parameter> <Parameter Name="loop" Type="Bool" Optional="false">Flags the sound as looping or not.</Parameter> <Parameter Name="priority" Type="Real" Optional="false">Set the channel priority for the sound.</Parameter> <Parameter Name="gain" Type="Real" Optional="true">Sets the gain of the sound played.</Parameter> <Parameter Name="offset" Type="Real" Optional="true">Sets the start offset (in seconds) of the sound played.</Parameter> <Parameter Name="pitch" Type="Real" Optional="true">Sets the pitch of the sound played.</Parameter> <Parameter Name="listener_mask" Type="Real" Optional="true">Sets the listener mask of the sound played.</Parameter> </Function> <Function Name="audio_play_sound_ext" Deprecated="false" ReturnType="Id.Sound" Pure="false"> <Description>With this function you can play any sound resource in your game. You provide a struct which contains a set of required parameters as well as any additional playback parameters. Parameters not specified will fall back to their default values/behaviour.</Description> <Parameter Name="params" Type="Struct" Optional="false">A struct containing a set of playback parameters.</Parameter> </Function> <Function Name="audio_resume_all" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can resume all sounds that have been paused previously.</Description> </Function> <Function Name="audio_resume_sound" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can resume any sound that is currently paused (after using the function audio_pause_sound()). The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset, in which case all instances of the given sound will be re-started.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to resume.</Parameter> </Function> <Function Name="audio_set_master_gain" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can set the absolute value for the global volume of all sounds and music for a specific listener. The default listener index is 0, but you can use the function audio_get_listener_info() to get the different indices available for the target platform. The gain value is based on a linear scale from 0 (silent) to 1 (full volume) and will affect the relative volume of all sounds and music played from within your game through that listener.</Description> <Parameter Name="listenerindex" Type="Id.AudioListener" Optional="false">The index of the listener to set the gain on.</Parameter> <Parameter Name="gain" Type="Real" Optional="false">Value for the global volume (0 to 1).</Parameter> </Function> <Function Name="audio_sound_gain" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can fade a sound in or out over a given length of time, or it can be used to set the sound gain instantly. The time is measured in milliseconds, and the function requires that you input a final level of gain for the sound to have reached by the end of that time. This gain can be between 0 (silent) and any value greater than 0, although normally you'd consider the maximum volume as 1. Anything over 1 can be used but, depending on the sound used and the platform being compiled to, you may get distortion or clipping when the sound is played back. Note that the gain scale is linear, and to instantly change the gain, simply set the time argument to 0.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to set the gain for.</Parameter> <Parameter Name="volume" Type="Real" Optional="false">Value for the music volume.</Parameter> <Parameter Name="time" Type="Real" Optional="false">The length for the change in gain in milliseconds.</Parameter> </Function> <Function Name="audio_sound_get_gain" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the current gain value for the given sound. The sound can either be one referenced from an index for an individual sound being played which has been stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions, or an actual sound asset from the Asset Browser. Gain is usually calculated as a value from 0 to 1, but on some platforms you can have a gain of greater than 1, although a value of 1 is considered "full volume" and anything greater may introduce audio clipping.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to get the gain of.</Parameter> </Function> <Function Name="audio_sound_get_listener_mask" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the bit-mask data that defines which audio listeners a sound should be played from. See the section on Audio Listeners for more information.</Description> <Parameter Name="soundid" Type="Asset.GMSound,Id.Sound" Optional="false">The unique ID of the sound to get the mask of</Parameter> </Function> <Function Name="audio_sound_get_pitch" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function can be used to get the get pitch of a given sound. The sound can either be one referenced from an index for an individual sound being played which has been stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions, or an actual sound asset from the Asset Browser.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to get the pitch of.</Parameter> </Function> <Function Name="audio_sound_get_track_position" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will get the position (in seconds) within the sound file for the sound to play from. The sound can only be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions).</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to get the play position of.</Parameter> </Function> <Function Name="audio_sound_is_playable" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function can be used to checks if the given sound index can be played currently. This is needed due to the different ways streamed and unstreamed sound playback is handled on the HTML5 target platform, and will return true if the sound can be played and false if it can't. Note that on all other platforms other than HTML5, the function will always return true..</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_sound_length" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the length of the given sound in seconds. The sound can either be a referenced from index for an individual sound being played which has been stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions, or an actual sound asset from the Asset Browser.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to check.</Parameter> </Function> <Function Name="audio_sound_pitch" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function can be used to change the pitch of a given sound. The sound can either be one referenced from an index for an individual sound being played which has been stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions, or an actual sound asset from the Asset Browser. If it is an index of a playing sound, then only that instance will be changed, however when using a sound asset from the Asset Browser, all further instances being played of that sound will be changed.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to change.</Parameter> <Parameter Name="pitch" Type="Real" Optional="false">The pitch multiplier (default 1).</Parameter> </Function> <Function Name="audio_sound_set_listener_mask" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function can be used to set the the bit-mask for a sound so that it will play only from those listeners specified. You can create a bit-mask by using the audio_get_listener_info() and then using the bitwise or ("|") to create a custom mask with those listeners that you require the sound to play from, and then apply this custom mask to the sound after you have played it. This mask will over-ride the default mask or that which you may have set using the function audio_set_listener_mask().</Description> <Parameter Name="soundid" Type="Asset.GMSound,Id.Sound" Optional="false">The unique ID of the sound to set the mask of</Parameter> <Parameter Name="mask" Type="Real" Optional="false">The bitmask data to set for the sound</Parameter> </Function> <Function Name="audio_sound_set_track_position" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will set the position (in seconds) within the sound file for the sound to play from. The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset. If it is a unique sound ID that you use, then the position will change immediately to the new time given, and if it is a Asset Browser asset then all further plays of the given sound will start at the new time. The function will ignore any value given that is longer than the length of the sound given for the "index" value.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to change.</Parameter> <Parameter Name="time" Type="Real" Optional="false">The time (in seconds) to set the start point to.</Parameter> </Function> <Function Name="audio_sound_loop" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will set the state of a playing sound's loop section.</Description> <Parameter Name="index" Type="Id.Sound" Optional="false">The index of the sound to change.</Parameter> <Parameter Name="state" Type="Bool" Optional="false">The state that the loop section should be set to.</Parameter> </Function> <Function Name="audio_sound_get_loop" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function will return the state of a playing sound's loop section.</Description> <Parameter Name="index" Type="Id.Sound" Optional="false">The index of the sound whose loop section state is retrieved.</Parameter> </Function> <Function Name="audio_sound_loop_start" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will set the offset (in seconds) of the start of a sound's loop section.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to change.</Parameter> <Parameter Name="time" Type="Real" Optional="false">The offset (in seconds) to set the start of the loop section to.</Parameter> </Function> <Function Name="audio_sound_get_loop_start" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the offset (in seconds) of the start of a sound's loop section.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound whose loop-start is retrieved.</Parameter> </Function> <Function Name="audio_sound_loop_end" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will set the offset (in seconds) of the end of a sound's loop section.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to change.</Parameter> <Parameter Name="time" Type="Real" Optional="false">The offset (in seconds) to set the end of the loop section to.</Parameter> </Function> <Function Name="audio_sound_get_loop_end" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the offset (in seconds) of the end of a sound's loop section.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound whose loop-end is retrieved.</Parameter> </Function> <Function Name="audio_stop_all" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will stop all sounds that are currently playing.</Description> </Function> <Function Name="audio_stop_sound" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will stop the given sound if it is currently playing. The sound can either be a single instance of a sound (the index for individual sounds being played can be stored in a variable when using the audio_play_sound() or audio_play_sound_at() functions) or a sound asset, in which case all instances of the given sound will be stopped.</Description> <Parameter Name="index" Type="Asset.GMSound,Id.Sound" Optional="false">The index of the sound to stop.</Parameter> </Function> <Function Name="audio_system_is_available" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function can be used to check and see if the audio system has been initialised, or if the audio context is running. On all platforms, this function will return true immediately after Game Start when the audio engine is initialised, except on the Opera GX and HTML5 targets. On Opera GX and HTML5, the audio context status can change at any time depending on user input, the browser being used, and its version, so this function can be used to check and see if audio can be played or not. If the function returns false (ie: the audio context status is not running), then only unstreamed sounds may play (but it's not guaranteed, and you should assume that no audio can be played), while if it returns true then all audio will play.</Description> </Function> <Function Name="audio_system_is_initialised" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function can be used to check if the audio engine has been initialised, after which all audio functions can be called normally. For all targets other than HTML5, this will return true on Game Start. On HTML5, this may only begin to return true after Game Start. While audio_system_is_available() reflects the ability to play audio, this function reflects the ability to call audio functions more generally.</Description> </Function> <Function Name="audio_create_buffer_sound" Deprecated="false" ReturnType="Asset.GMSound" Pure="true"> <Description>With this function you can create a new sound from the contents of a buffer. The buffer will have been created previously (see the buffer functions for details on how to do this), and have had data added or loaded into it. You then pass it to this function with the data format (only buffer_u8 or buffer_s16 are currently supported), the sample rate (which can be between 1000hz and 48000hz), and an offset into the buffer to get the data from. You also need to supply the number of samples in the buffer and the channels that the sound requires. These channels are defined by one of the following constants:</Description> <Parameter Name="bufferId" Type="Id.Buffer" Optional="false">The ID of the buffer to use.</Parameter> <Parameter Name="bufferFormat" Type="Constant.BufferDataType" Optional="false">The format of the data in the buffer (buffer_u8 or buffer_s16).</Parameter> <Parameter Name="bufferRate" Type="Real" Optional="false">The sample rate of the data in the buffer.</Parameter> <Parameter Name="bufferOffset" Type="Real" Optional="false">The offset into the buffer to read the sample data from (in bytes).</Parameter> <Parameter Name="bufferLength" Type="Real" Optional="false">The length of the buffer (the number of bytes of audio data, excluding the header).</Parameter> <Parameter Name="bufferChannels" Type="Constant.AudioChannelType" Optional="false">The channels to use (audio_mono, audio_stereo or audio_3D).</Parameter> </Function> <Function Name="audio_create_play_queue" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function prepares a buffer queue for audio. You pass data format (only buffer_u8 or buffer_s16 are currently supported), the sample rate (which can be between 1000hz and 48000hz), and the channels that the audio requires from one of the constants listed below:</Description> <Parameter Name="queueformat" Type="Constant.BufferDataType" Optional="false">The format of the buffer data to use (buffer_u8 or buffer_s16).</Parameter> <Parameter Name="queuerate" Type="Real" Optional="false">The sample rate of the data in the buffer queue.</Parameter> <Parameter Name="queuechannels" Type="Real" Optional="false">The channels to use from one of the constants listed below.</Parameter> </Function> <Function Name="audio_free_buffer_sound" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can free up the pointer index value associated with the sound ID. Freed sounds will not be available for playing, and if multiple instances of the sound are being played they will all be stopped. Note that before you can delete the buffer itself, you must first free all sound ID's associated with it.</Description> <Parameter Name="index" Type="Real" Optional="false">The index of the buffered sound to free.</Parameter> </Function> <Function Name="audio_free_play_queue" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function is used to free up the memory associated with the given audio queue. The queue index is the value returned when you created the queue using the function audio_create_play_queue(), and this function should be called when the queue is no longer required to prevent memory leaks. Freeing the queue will stop any sound that is be playing, and you cannot delete the buffer that a sound is being streamed from until the queue it is assigned to has been freed. This function will trigger an Audio Playback Asynchronous Event, and in this event a special DS map will be created in the variable async_load with the following key/value pairs:</Description> <Parameter Name="queueindex" Type="Real" Optional="false">The index of the queue to free.</Parameter> </Function> <Function Name="audio_get_recorder_count" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return the number of audio recording sources (like microphones, etc...) currently available to your game. So, if you have a return value of, for example, four, then you will have audio input on the sources 0, 1, 2 and 3, with one of these values being that which you use to start recording from using the function audio_start_recording(). This value can change at any time as people plug/unplug microphones or other input sources to the device. Note that you can use the function audio_get_recorder_info() to get information on each device connected.</Description> </Function> <Function Name="audio_get_recorder_info" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will return a DS Map with information about the given recorder source index. You can find out how many recorder sources are available using the function audio_get_recorder_count(), and the map returned will contain the following key/value pairs:</Description> <Parameter Name="recorder_index" Type="Real" Optional="false">The index of the recorder source to get the information from.</Parameter> </Function> <Function Name="audio_queue_sound" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>This function will add the data from a buffer into the audio queue that you previously created using the function audio_create_play_queue(). You specify the queue index to add to, and the buffer ID to get the data from as well as the position (offset) within the buffer and the number of bytes to add. Once you have added audio from a buffer to a queue, the buffer cannot be deleted until you have first freed the queue using the function audio_free_play_queue(), and the buffer properties should match those of the the queue that you are adding the sound to.</Description> <Parameter Name="queueindex" Type="Real" Optional="false">The index of the queue to add to.</Parameter> <Parameter Name="bufferid" Type="Id.Buffer" Optional="false">The buffer to add to the queue.</Parameter> <Parameter Name="bufferoffset" Type="Real" Optional="false">The offset within the source buffer to start from.</Parameter> <Parameter Name="bufferlength" Type="Real" Optional="false">The length of the buffer (the number of the bytes in the buffer).</Parameter> </Function> <Function Name="audio_start_recording" Deprecated="false" ReturnType="Real" Pure="true"> <Description>This function will start recording audio from the recorder source indexed. You can get the number of recorder sources using the function audio_get_recorder_count(), and once you start recording the audio will be stored in a temporary buffer and start triggering an Audio Recording Asynchronous Event. This event is triggered every step that recording takes place and will create the special DS map in the variable async_load with the following key/value pairs:</Description> <Parameter Name="recorder_index" Type="Real" Optional="false">The index of the recorder source to use.</Parameter> </Function> <Function Name="audio_stop_recording" Deprecated="false" ReturnType="Undefined" Pure="true"> <Description>This function will stop recording on the given recorder channel (the channel index is returned when you call the function audio_start_recording()). When you stop recording, no further Audio Recording Asynchronous Events will be triggered for the given recorder channel, so you would normally use this function in the actual asynchronous event to ensure that you have captured all the data.</Description> <Parameter Name="channel_index" Type="Real" Optional="false">The index of the recorder channel to stop.</Parameter> </Function> <Function Name="audio_emitter_create" Deprecated="false" ReturnType="Id.AudioEmitter" Pure="true"> <Description>This function creates a new audio emitter and returns the index for it. This index should be stored in a variable for all further functions that relate to this emitter, and then when it is no longer needed it should be removed from memory using the function audio_emitter_free() to prevent memory leaks which may eventually crash your game.</Description> </Function> <Function Name="audio_emitter_exists" Deprecated="false" ReturnType="Bool" Pure="true"> <Description>This function returns whether an audio emitter exists (true) or not (false). Note that if the index you search for has not been initialised previously, this function will cause an error as it is searching for non-existent indices.</Description> <Parameter Name="index" Type="Id.AudioEmitter" Optional="false">The index of the emitter to check the existence of.</Parameter> </Function> <Function Name="audio_emitter_falloff" Deprecated="false" ReturnType="Undefined" Pure="false"> <Description>With this function you can set the fall-off distance for an emitter. This is the distance from the listener the emitter has to be before the sound will have "fallen off" to a volume of 0. The default value for this is 100, but beware of setting this to any value lower than 1 as that will make any sound played throug