General

General API documentation

Concepts

Function List

Mission Setups

acre_api_fnc_setupMission
acre_api_fnc_setRevealToAI
acre_api_fnc_isInitialized

Difficulty Settings

acre_api_fnc_setLossModelScale
acre_api_fnc_setFullDuplex
acre_api_fnc_setInterference

System Configuration

acre_api_fnc_setPTTDelay
acre_api_fnc_getPTTDelay
acre_api_fnc_setGlobalVolume
acre_api_fnc_getGlobalVolume

Radio Manipulation

acre_api_fnc_getCurrentRadioList
acre_api_fnc_setCurrentRadio
acre_api_fnc_getCurrentRadio
acre_api_fnc_getRadioByType
acre_api_fnc_setRadioChannel
acre_api_fnc_getRadioChannel
acre_api_fnc_setCurrentRadioChannelNumber
acre_api_fnc_getCurrentRadioChannelNumber
acre_api_fnc_setRadioSpatial
acre_api_fnc_getRadioSpatial
acre_api_fnc_setMultiPushToTalkAssignment
acre_api_fnc_getMultiPushToTalkAssignment

Radio Class Helpers

acre_api_fnc_isRadio
acre_api_fnc_hasRadio
acre_api_fnc_hasKindOfRadio
acre_api_fnc_isKindOf
acre_api_fnc_isBaseRadio
acre_api_fnc_hasBaseRadio

Channel & Radio Presets

acre_api_fnc_setPreset
acre_api_fnc_getPreset
acre_api_fnc_setPresetData
acre_api_fnc_getPresetData
acre_api_fnc_setPresetChannelData
acre_api_fnc_getPresetChannelData
acre_api_fnc_setPresetChannelField
acre_api_fnc_getPresetChannelField

Speaking Status

acre_api_fnc_isBroadcasting
acre_api_fnc_isSpeaking
acre_api_fnc_isSpectator
acre_api_fnc_setSpectator

Curve Models

acre_api_fnc_setCurveModel
acre_api_fnc_getSelectableVoiceCurve

Mission Setups

acre_api_fnc_setupMission(babel, radios)

This function generically sets up a mission so that each side will have their own radios as well as speak their own separate languages. Further API calls will be needed to allow them to speak to each other, or configure specific intermingling channels.

This function should allow for the most basic and common TVT and gameplay setups; allowing for different radios that do not interfere, as well as different languages.

Example: [true, true] call acre_api_fnc_setupMission;
Parameters:
  • babel (bool) – True/False setting to specify whether each side should speak their own Babel language; making them incomprehensible to eachother.
  • radios (bool) – True/False to specify whether default radio channels should be setup differently for each side in the game.
Returns:

setup was successful

Return type:

bool

acre_api_fnc_setRevealToAI(flag)

Sets whether AI can detect players speaking. This utilizes an advanced model of inverse-square volume detection and randomization against the range of the unit, and duration and quantity of speaking. In a nutshell, the closer you are to an AI unit and the more you speak - the better chance he has of hearing you.

Example: _status = [false] call acre_api_fnc_setRevealToAI;

Parameters:flag (bool) – status to change to
Returns:value provided
Return type:bool
acre_api_fnc_isInitialized()

Returns the true or false flag of whether the ACRE radios have initialized. This means that they have been replaced with ID specified radios.

Example: _status = [] call acre_api_fnc_isInitialized;

Returns:The status if all radios have initialized
Return type:bool

Difficulty Settings

acre_api_fnc_setLossModelScale(lossValue)

Specify and value between 1.0 and 0. Setting it to 0 means the terrain loss model is disabled, 1 is default. Note this setting only effects loss caused by terrain, loss due to power dissipation over range will always occur.

Example: [0.5] call acre_api_fnc_setLossModelScale;
Parameters:lossValue (float) – a value of 1.0 to 0 on the strength of the loss model.
Returns:value provided
Return type:float
acre_api_fnc_setFullDuplex(arg)

Sets the duplex of radio transmissions. If set to true, it means that you will receive transmissions even while talking and multiple people can speak at the same time.

Example: [true] call acre_api_fnc_setFullDuplex;
Parameters:arg (bool) – True/false to set full duplex.
Returns:value provided
Return type:float
acre_api_fnc_setInterference(arg)

Sets whether transmissions will interfere with each other. This, by default, causes signal loss when multiple people are transmitting on the same frequency.

Example: [true] call acre_api_fnc_setInterference;
Parameters:arg (bool) – True/false to set interference.
Returns:value provided
Return type:float

System Configuration

acre_api_fnc_setPTTDelay(delay)

Specify a value between 0 and 1 for the amount of time, in seconds, to delay releasing the radio PTT key. This compensates for network latency issues with cutting off at the end of a transmission.

Example sets delay to 50ms : [0.05] call acre_api_fnc_setLossModelScale;

Parameters:delay – A value between 0 and 1 for the delay to release
Returns:success
Return type:bool
acre_api_fnc_getPTTDelay(delay)

Gets the current delay value for releasing radio PTT events. The default value for this is 50ms, or 0.05

Example: _delay = [] call acre_api_fnc_getPTTDelay;

Returns:The delay time, in seconds, to release PTT radio events.
Return type:float
acre_api_fnc_setGlobalVolume(volume)

Sets the global volume of the output from ACRE. 1 is normal, 0 is silent.

Example: [0.05] call acre_api_fnc_setGlobalVolume;

Parameters:volume (float) – A value between 0 and 1
Returns:success
Return type:bool
acre_api_fnc_getGlobalVolume(volume)

Gets the current global output volume for all ACRE voices and radios.

Example: _delay = [] call acre_api_fnc_getGlobalVolume;

Returns:The current ACRE global volume, A value between 0 and 1
Return type:float

Radio Manipulation

acre_api_fnc_getCurrentRadioList()

Retrieves the array of current unique radio ID’s that are on the local player.

Example: _radioIdList = [] call acre_api_fnc_getCurrentRadioList;

Returns:Array of RadioID’s
Return type:Array
acre_api_fnc_setCurrentRadio(radio_id)

Sets the unique radio ID of the currently active radio on the local player object.

Example: _success = ["ACRE_PRC148_ID_7"] call acre_api_fnc_setCurrentRadio;

Parameters:radio_id (RadioID) – ID to switch to the current radio.
Returns:true or false for success
Return type:bool
acre_api_fnc_getCurrentRadio()

Returns the unique radio ID of the currently active radio on the local player object.

Example: _radioId = [] call acre_api_fnc_getCurrentRadio;

Returns:ID of the current radio
Return type:RadioID

Warning

getRadioByType function does not compensate for a unit having multiple radios of the same type. There is no guarantee which radio it will return.

acre_api_fnc_getRadioByType(radio_type)

Returns the unique radio ID of the first radio the local player or unit possesses of a given type. This function does not compensate for units with multiple radios of the same type. There is no guarantee of which radio it will return.

Example: _radioId = ["ACRE_PRC152"] call acre_api_fnc_getRadioByType;

Example 2: _radioId = ["ACRE_PRC152", _unit] call acre_api_fnc_getRadioByType;

Parameters:radio_type (classname) – The class name type of the radio to search for, such as ACRE_PRC343 or ACRE_PRC152
Returns:ID of the current radio
Return type:RadioID
acre_api_fnc_setRadioChannel(radio_id, channel_number)

Sets the channel number of the currently active channel on the provided radio ID.

Example: _success = ["ACRE_PRC152_ID_123", 5] call acre_api_fnc_setRadioChannel;

Parameters:
  • radio_id (RadioID) – ID of radio to modify.
  • channel_number (integer) – New channel number to set, 1-N depending on the radio.
Returns:

success on setting the channel

Return type:

bool

acre_api_fnc_getRadioChannel(radio_id)

Returns the channel number of the currently active channel on the provided radio ID.

Example: _currentChannel = ["ACRE_PRC152_ID_123"] call acre_api_fnc_getRadioChannel;

Parameters:radio_id (RadioID) – ID of the target radio.
Returns:Channel number, 1-N depending on the radio.
Return type:integer
acre_api_fnc_setCurrentRadioChannelNumber(channel_number)

Set the channel number that the currently active radio is on.

Example: _success = [5] call acre_api_fnc_setCurrentRadioChannelNumber;

Parameters:channel_number (integer) – New channel number to set, 1-N depending on the radio.
Returns:ID of the current radio
Return type:RadioID
acre_api_fnc_getCurrentRadioChannelNumber()

Returns the channel number that the currently active radio is on.

Example: _channelNumber = [] call acre_api_fnc_getCurrentRadioChannelNumber;

Returns:Channel number of the current radio
Return type:integer
acre_api_fnc_setRadioSpatial(radio_id, spatial)

Sets what spatialization zone the specified radio ID should be in. “LEFT”, “RIGHT” or “CENTER”.

Example: _success = ["ACRE_PRC148_ID_3", "LEFT" ] call acre_api_fnc_setRadioSpatial;

Parameters:
  • radio_id (float) – ID of the radio to spatialize
  • spatial (string) – “LEFT”, “RIGHT” or “CENTER”
Returns:

true or false for success

Return type:

bool

acre_api_fnc_getRadioSpatial(radio_id)

Gets what spatialization zone the specified radio ID is currently in. “LEFT”, “RIGHT” or “CENTER”.

Example: _spatial = ["ACRE_PRC148"] call acre_api_fnc_getRadioSpatial;

Parameters:radio_id (float) – ID of the radio to spatialize
Returns:“LEFT”, “RIGHT” or “CENTER”
Return type:string
acre_api_fnc_setMultiPushToTalkAssignment(radio_list)

Sets the assignment order for the Multi-Push-To-Talk keys, also known as Alternate Push-to-Talk keys. These assign the keys 1-3, in order, to the ID’s provided in the array. All radios must be valid assigned ACRE radio id’s and must be present on the local player.

Example: ``
_personalRadio = [“ACRE_PRC343”] call acre_api_fnc_getRadioByType; _handheldRadio = [“ACRE_PRC152”] call acre_api_fnc_getRadioByType; _manpackRadio = [“ACRE_PRC117F”] call acre_api_fnc_getRadioByType; _success = [ [ _personalRadio, _handheldRadio, _manpackRadio ] ] call acre_api_fnc_setMultiPushToTalkAssignment;

``

Parameters:radio_list – Array of radio ID’s retrieved from the player to assign to keys. These must be valid ACRE radio ids such as ACRE_PRC343_ID_1
Returns:The success of setting the list.
Return type:bool
acre_api_fnc_getMultiPushToTalkAssignment(radio_id)

Returns the current radios assigned to Multiple Push-to-Talk keys, or Alternate PTT keys.

Example: _mpttRadioList = [] call acre_api_fnc_getMultiPushToTalkAssignment;

Returns:The array of radio ID’s which are assigned to each PTT talk key. These are returned in order, from key 1-3
Return type:Array
acre_api_fnc_isRadio(className)

Returns true or false whether the provided weapon is a ACRE radio or not.

Example: _isRadio = ["NVGoggles"] call acre_api_fnc_isRadio;

Parameters:className (string) – Class name of a weapon or item
Returns:Whether the provided object class name is a radio or not
Return type:bool
acre_api_fnc_hasRadio(object)

Returns true or false whether the provided unit has a ACRE radio in their inventory

Example: _hasRadio = [player] call acre_api_fnc_hasRadio;

Parameters:object (unit) – player or unit object
Returns:whether the unit or player has a radio
Return type:bool
acre_api_fnc_hasKindOfRadio(object, radio_class)

returns true or false whether the provided unit has the specified ACRE radio type in their inventory

Example: _hasRadio = [player, "ACRE_PRC148"] call acre_api_fnc_hasKindOfRadio;

Example 2: _hasRadio = [(items player), "ACRE_PRC148"] call acre_api_fnc_hasKindOfRadio;

Parameters:
  • object (unit or array) – The unit to check or a arbitrary array of string class names to check
  • radio_class (string) – The root radio type to check for
Returns:

Whether the unit has the given radio class

Return type:

bool

acre_api_fnc_isKindOf(className, radio_class)

Returns true or false whether the provided Weapon is the specified ACRE radio type

Example: _ret = [((weapons player) select 0), "ACRE_PRC117F"] call acre_api_fnc_isKindOf;

Example 2: _ret = ["ACRE_PRC117F_ID_123", "ACRE_PRC117F"] call acre_api_fnc_isKindOf;

Parameters:
  • lossValue (string) – String class name of the weapon or item to check
  • lossValue – Radio class to check
Returns:

Whether the provided item is of the radio class type

Return type:

bool

acre_api_fnc_getBaseRadio(radioId)

Takes an actual unique radio ID, and returns its actual base radio type. E.g. “ACRE_PRC148_ID_1” base radio is “ACRE_PRC148”

Example: _radioType = ["ACRE_PRC148_ID_15"] call acre_api_fnc_getBaseRadio;

Parameters:radioId (RadioID) – string radio id
Returns:The base radio class, if any, of the provided radio ID. Otherwise, it is empty “”
Return type:RadioType
acre_api_fnc_isBaseRadio(item_name)

Checks if a class name is a base radio or not. Base radios are ACRE radios without IDs. e.g. “ACRE_PRC148” would return true, “ACRE_PRC148_ID_1” would return false.

Example: _result = ["ACRE_PRC343"] call acre_api_fnc_isBaseRadio;
Parameters:item_name (string) – item or weapon class name to check
Return type:bool
acre_api_fnc_hasBaseRadio(unit)

Checks whether the given unit has a base radio.

Example: _result = [player] call acre_api_fnc_hasBaseRadio;
Parameters:unit (unit) – The unit object to check.
Return type:bool

Radio Presets

Warning

All presets must exist and match on all clients and especially the server; regardless of where the presets are used. If you create a preset, copy a preset or modify a presets data information; these changes must occur on all clients and the server. If they do not, ACRE may not work.

acre_api_fnc_setPreset(radio_type, preset_name)

Sets the preset name to utilize on the provided radio class during initialization.

Example: _success = ["ACRE_PRC152", "default2"] call acre_api_fnc_setPreset;

Parameters:
  • radio_class (RadioType) – Class type of radios to change the preset for
  • preset_name (string) – The text name of the preset to change to. Defaults are usually default, default2, default3 and default4.
Returns:

success on setting the preset

Return type:

bool

acre_api_fnc_getPreset(radio_type)

Gets the preset name to utilize on the provided radio class during initialization.

Example: _currentPreset = ["ACRE_PRC152"] call acre_api_fnc_getPreset;

Parameters:radio_class (RadioType) – : Class type of radios to get the preset for
Returns:The string name of the current preset
Return type:string

Warning

All presets must exist on all clients and especially the server. If you create a new preset using copyPreset, you must ensure that it was called on all clients and the server. Even if a client does not use it, it must be created to ensure proper data between all clients.

acre_api_fnc_copyPreset(radio_type, src_preset_name, dst_preset_name)

Copies all parameters of the source preset to a new destination preset name.

This function must be called on all clients and the server to work properly.

Example: _success = ["ACRE_PRC152", "default2", "balls"] call acre_api_fnc_copyPreset;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • src_preset_name (string) – Name of the source preset to copy from.
  • dst_preset_name (string) – Name of the destination preset to copy to.
Returns:

success on copying the preset

Return type:

bool

acre_api_fnc_setPresetData(radio_type, preset_name, preset_data)

Sets the full data set to be utilized for the specified preset name. You should use the return value from getPresetChannelData to provide new data to this function. Improper data will most likely break ACRE on all clients.

This function must be called on all clients and the server to work properly.

Example: _success = ["ACRE_PRC152", "new_preset", _presetData] call acre_api_fnc_setPresetData;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • preset_name (string) – The string name of the preset to modify.
  • preset_data (Hash) – The ACRE2 Hash value array of preset data information.
Returns:

success on setting the channel

Return type:

bool

acre_api_fnc_getPresetData(radio_type, preset_name)

Returns the full ACRE2 Hash data of the specified preset name for the specified radio.

Example: _presetData = ["ACRE_PRC152", "default"] call acre_api_fnc_getPresetData;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • preset_name (string) – The string name of the preset to get.
Returns:

ACRE Hash value array of preset data information

Return type:

Hash

acre_api_fnc_setPresetChannelData(radio_type, preset_name, channel_number, preset_data)

Sets the full data set to be utilized for the specified preset name. You should use the return value from getPresetChannelData to provide new data to this function. Improper data will most likely break ACRE on all clients.

The channel number must be a valid channel for that type of radio.

This function must be called on all clients and the server to work properly.

Example: _success = ["ACRE_PRC152", "new_preset", 4, _presetData] call acre_api_fnc_setPresetChannelData;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • preset_name (string) – The string name of the preset to modify.
  • channel_number (integer) – channel number to set, 1-N depending on the radio.
  • preset_data (Hash) – The ACRE2 Hash value array of preset channel information.
Returns:

success on setting the channel preset data

Return type:

bool

acre_api_fnc_getPresetChannelData(radio_type, preset_name, channel_number)

Returns the full ACRE2 channel Hash data of the specified preset name for the specified radio.

The channel number must be a valid channel for that type of radio.

Example: _presetData = ["ACRE_PRC152", "default", 4] call acre_api_fnc_getPresetChannelData;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • preset_name (string) – The string name of the preset to modify.
  • channel_number (integer) – channel number to set, 1-N depending on the radio.
Returns:

ACRE Hash value array of preset channel information

Return type:

Hash

acre_api_fnc_setPresetChannelField(radio_name, preset_name, channel_number, field_name, value)

Sets the value of a given channel field for the given radio preset.

This function must be called on all clients and the server to work properly.

Example: _success = ["ACRE_PRC148", "default", 5, "label", "COY"] call acre_api_fnc_setPresetChannelField;

Parameters:
  • radio_type (RadioType) – The base name of radio to modify.
  • preset_name (string) – The string name of the preset to modify.
  • channel_number (integer) – channel number to set, 1-N depending on the radio.
  • field_name (string) – The name of the field to modify.
  • value (Any) – Value to set
Returns:

success on setting the channel field data

Return type:

bool

acre_api_fnc_getPresetChannelField(radio_type, preset_name, channel_number, field_name)

Returns the value of the channel field for the given radio preset.

Example: _success = ["ACRE_PRC148", "default", 2, "label"] call acre_api_fnc_getPresetChannelField;

Parameters:
  • radio_type (RadioType) – The base name of radio to use.
  • preset_name (string) – The string name of the preset to use.
  • channel_number (integer) – channel number to set, 1-N depending on the radio.
  • field_name (Hash) – The name of the field to retrieve.
Returns:

Value of the given field.

Return type:

Any

Speaking Status

acre_api_fnc_isBroadcasting(unit)

Returns true or false whether the provided unit is currently broadcasting on the radio

Example: _isBroadcasting = [player] call acre_api_fnc_isBroadcasting;

Parameters:unit (Unit) – Unit to check or player for local
Returns:Broadcasting status
Return type:bool
acre_api_fnc_isSpeaking(unit)

Returns true or false whether the provided unit is currently speaking, either on radio or direct

Example: _isSpeaking = [player] call acre_api_fnc_isSpeaking;

Parameters:unit (Unit) – Unit to check or player for local
Returns:Speaking status
Return type:bool
acre_api_fnc_isSpectator(unit)

Returns true or false. This value determines whether the player has been hard-set to a “spectator”, or dead channel member, permanently until switched by script.

Example: _isSpectator = [player] call acre_api_fnc_isSpectator;

Parameters:unit (Unit) – Unit to check or player for local
Returns:Spectator status
Return type:bool
acre_api_fnc_setSpectator(status)

Pass true or false to set the unit as a “spectator” or not. This will override current alive status, and join the player to dead channel regardless.

Example: _ret = [true] call acre_api_fnc_setSpectator;

Parameters:status (bool) – true or false on whether the unit should locally be considered a spectator
Returns:value provided
Return type:float

Voice Curve Manipulation

Warning

acre_api_fnc_setCurveModel function is global and affects all clients, no matter where it is executed!

acre_api_fnc_setCurveModel(curveModel)

Sets the curve model to be utilized across all clients. These models affect different dropoff for direct voice chat hearing. Meaning, this basically affects the distance you can hear people.

Example: ["ACRE_CURVE_MODEL_ORIGINAL"] call acre_api_fnc_setCurveModel;

Parameters:curveModel (string) – Curve model to utilize: “ACRE_CURVE_MODEL_ORIGINAL”, “ACRE_CURVE_MODEL_SELECTABLE_A”, or “”ACRE_CURVE_MODEL_SELECTABLE_B”
Returns:None
Curve Model Name Description
ACRE_CURVE_MODEL_ORIGINAL The volume range is static and based off a custom curve.
ACRE_CURVE_MODEL_SELECTABLE_A This method allows you to use the acre_api_fnc_setSelectableVoiceCurve to change how far the voice curve goes. The curve that the it modifies in mode A is the default X3DAudio curve based off the inverse square law.
ACRE_CURVE_MODEL_SELECTABLE_B Same as above but it modifies the distance of the custom curve available when using the ACRE_CURVE_MODEL_ORIGINAL mode.
acre_api_fnc_getSelectableVoiceCurve()

The addition of the selectable modes for the voice curve allows mission makers/addon makers to add their own functionality for setting the range of someones voice. This will allow them to add in for example modes for whispering, normal speaking, and yelling.

As an example a addon maker or mission maker would want to first set the server to use either selectable voice model using the acre_api_fnc_setCurveModel function described above. After setting the model at mission/game init they would then provide an interface to, either graphically or through keyboard commands, call the acre_api_fnc_setSelectableVoiceCurve with values reflecting the range that they would like the voice to travel. For example setting 0.25 for whispering, or 2 or more for yelling. A value of 1 should almost always be used as the value for a normal speaking voice. Be aware that mode ACRE_CURVE_MODEL_SELECTABLE_B is not based on any specific law, like ACRE_CURVE_MODEL_SELECTABLE_A is and will more than likely require some empirical testing to find values that are acceptable.

Example: _ret = [] call acre_api_fnc_getSelectableVoiceCurve;

Returns:Active voice curve string
Return type:string