Custom Modules

Contents:

1. Notes
2. Register Custom Modules
3. Integrate Selection Option
4. Dynamic Dialogs

Notes:

This page is dedicated to how to register custom modules. You can furthermore find here some useful functions for your module script.

Register Custom Modules:

As in Ares you can define your own custom modules. The function to register custom modules is Ares_fnc_RegisterCustomModule.
The function takes three arguments:

• _this select 0    STRING     Module Category Name (If the category already exists, the modul will be appended to that category)
• _this select 1    STRING     Module Name (If the module already exists, the old module gets overridden).
• _this select 2    CODE        Code that is executed when the module is placed.
  

There are two arguments available for your code:

• _this select 0    ARRAY     Returns position AGLS where the module was placed.
• _this select 1    OBJECT    Returns ObjNull or the object on which the module was placed.
  

There are two ways to integrate Ares_fnc_RegisterCustomModule:

1. You can define a custom module in the mission. As an example you can place the code below in the initPlayerLocal.sqf of your mission:

if (!isNull (getAssignedCuratorLogic player) && {isClass (configFile >> "CfgPatches" >> "achilles_modules_f_achilles")}) then
{
	// Note that the line below has to be uncommented if your mission is a Zeus Game Master mission.
	// waitUntil {missionnamespace getvariable ["BIS_moduleMPTypeGameMaster_init", false] and {not isNil "ares_category_list"}};
	["Module Category", "Module Name", 
	{
		// Get all the passed parameters
		params [["_position", [0,0,0], [[]], 3], ["_objectUnderCursor", objNull, [objNull]]];

		// Log the parameters
		systemChat str _position;
		systemChat str _objectUnderCursor;
	}] call Ares_fnc_RegisterCustomModule;
}

2. Execute Ares_fnc_RegisterCustomModule with the Execute Code module.

Integrate Selection Option:

A template to integrate the Selection Option is presented below:

["My Category", "My Module",
{
	// Get all the passed parameters
    params [["_position", [0,0,0], [[]], 3], ["_objectUnderCursor", objNull, [objNull]]];
    
	// Use select (is faster!) to check if there was an object under the cursor or not,
	// If the object under cursor is null (nothing was selected), then prompt the user to select object(s) by calling Achilles_fnc_SelectUnits.
	// But if the module had been placed upon an object, then return that object surounded by brackets (add it to an array). 
	private _selectedObjects = [[_objectUnderCursor], (["Objects"] call Achilles_fnc_SelectUnits)] select (isNull _objectUnderCursor);

	// If the selection was canceled, exit the script to prevent any issues and errors.
	if (isNil "_selectedObjects") exitWith {};

	// If the selection is empty, also exit, but with a message.
	// Side note: using isEqualTo [] is faster than count _selectedObjects == 0. So always try to improve performance when ever possible.
	if (_selectedObjects isEqualTo []) exitWith 
	{
		// This is only from 0.1.0 update and higher! Use old Ares_fnc_ShowZeusMessage and playSound "FD_Start_F" if below that version! Syntax is the same.
		// Show the message to the Curator.
		["No object was selected!"] call Achilles_fnc_showZeusErrorMessage;
	};

	// If everything went good, then log the variables.
	systemChat format ["Position: %1 and Selected objects: %2", _position, _selectedObjects];
}] call Ares_fnc_RegisterCustomModule;

As you see in the line with systemChat, there are two private variables available:

• _module_position    ARRAY     Returns position AGLS where the module was placed.
• _selected_object      ARRAY     Array of selected objects.

Dynamic Dialogs:

A good module needs a GUI. For this purpose Ares provides a dynamic dialog which is extended in Achilles.
The function to create dynamic dialogs is Ares_fnc_ShowChooseDialog.
The function takes two to three arguments:

• _this select 0    STRING     Dialog Title (will be displayed in the header)
• _this select 1    ARRAY       Array of arrays (see below)
• _this select 2    STRING     (optional) Name of a custom function that gets executed when the dialog is opened, closed and when the value of a combo box was changed.
  

The array of arrays can have different structures. One array corresponds to one GUI choice element. Note that the structure determines the type of the control.

Control Type	_this select _i	Data Type	Description
All Types	_i = 0	STRING	Label of the choice
Combo Box	_i = 1	ARRAY	Array of strings corresponding to the different choices
	_i = 2	SCALAR	(optional) Default choice (index given by array of choices starting with 0
Text	_i = 1	STRING	Has to be an empty string "" (one-liner) or "MESSAGE" (larger box; since 0.0.6)
	_i = 2	STRING	(optional) Default string in the text window.
Slider	_i = 1	STRING	String has to be "SLIDER"
	_i = 2	SCALAR	(optional) Default slider value (between 0 and 1).
Sides	_i = 1	STRING	String has to be "ALLSIDE" (include sideLogic) or "SIDE" (excludes sideLogic)
	_i = 2	SCALAR	(optional) Default side (0 => sideLogic; 1 => east; 2 => west; 3 => independent; 4 => civilian)
All Types	_i = 3	BOOLEAN	(optional) force to always use default value given in _i = 2 (false by default)

The function returns an array which contains all the choices in the order the GUI choice elements were given. The data type of the array element depends on the control type:

Control Type	Data Type	Description
Combo Box	SCALAR	Choice index (index given by array of choices starting with 0).
Text	STRING	Returns the text.
Slider	SCALAR	Returns the slider value (between 0 and 1).
*Sides	SCALAR	Value mapping: 0 => sideLogic; 1 => east; 2 => west; 3 => independent; 4 => civilian. The values correspond to "side ID" + 1 (except for sideLogic); also see BIS_fnc_sideType and BIS_fnc_sideName.

*Note that currently only a single "sides" control is supported per dialog.

Here is an example of a dialog that integrates several available control types:

private _dialogResult =
[
	"Test Dialog",
	[
		// The last number is optional! If you want the first selection you can remove the number.
		["Combo Box Control", ["Choice 1","Choice 2"], 1],
		["Text Control", "", "default text"],
		["Slider Control", "SLIDER", 1],
		["Side Control", "SIDE", 2]
	]
] call Ares_fnc_showChooseDialog;

// If the dialog was closed.
if (_dialogResult isEqualTo []) exitWith{};

// Get the selected data
_dialogResult params ["_comboBoxResult", "_typedText", "_sliderResult", "_side"];

// Output the data to the chat.
systemChat format ["Combo Box Result: %1", _comboBoxResult];
systemChat format ["Typed Text: %1", _typedText];
systemChat format ["Slider Result: %1", _sliderResult];
systemChat format ["Selected Side: %1", _side];

Note that if the dialog is cancled, the function returns an empty array. In order to catch that case, the following line was introduced:

if (_dialogResult isEqualTo []) exitWith {};

You should get the same result as below: