doc/spadsPluginApiDoc.html

<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SPADS Plugin API Doc</title>
<link rel="stylesheet" href="pod2html.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body>
<script src="https://cdn.jsdelivr.net/npm/anchor-js/anchor.min.js"></script>


<ul id="index">
  <li><a href="#NAME">NAME</a></li>
  <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="#PYTHON-SPECIFIC-NOTES">PYTHON SPECIFIC NOTES</a>
    <ul>
      <li><a href="#How-to-read-the-documentation">How to read the documentation</a></li>
      <li><a href="#Perl-strings-conversions">Perl strings conversions</a></li>
      <li><a href="#Windows-limitations">Windows limitations</a></li>
    </ul>
  </li>
  <li><a href="#CALLBACK-FUNCTIONS">CALLBACK FUNCTIONS</a>
    <ul>
      <li><a href="#Mandatory-callbacks">Mandatory callbacks</a></li>
      <li><a href="#Configuration-callback">Configuration callback</a></li>
      <li><a href="#Dependencies-callback">Dependencies callback</a></li>
      <li><a href="#Event-based-callbacks">Event-based callbacks</a></li>
      <li><a href="#Customization-callbacks">Customization callbacks</a></li>
      <li><a href="#Event-loop-callback">Event loop callback</a></li>
    </ul>
  </li>
  <li><a href="#API-FUNCTIONS">API FUNCTIONS</a>
    <ul>
      <li><a href="#Accessors">Accessors</a></li>
      <li><a href="#Plugin-management">Plugin management</a></li>
      <li><a href="#Handlers-management">Handlers management</a></li>
      <li><a href="#SPADS-operations">SPADS operations</a></li>
      <li><a href="#AutoHost-messaging-system">AutoHost messaging system</a></li>
      <li><a href="#Time-utils">Time utils</a></li>
      <li><a href="#Data-formatting">Data formatting</a></li>
      <li><a href="#Forking-processes">Forking processes</a></li>
      <li><a href="#Timers-management">Timers management</a></li>
      <li><a href="#Sockets-management">Sockets management</a></li>
      <li><a href="#Python-specific">Python specific</a></li>
    </ul>
  </li>
  <li><a href="#SHARED-DATA">SHARED DATA</a>
    <ul>
      <li><a href="#Constants">Constants</a></li>
      <li><a href="#Variables">Variables</a></li>
    </ul>
  </li>
  <li><a href="#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="#COPYRIGHT">COPYRIGHT</a></li>
</ul>

<h1 id="NAME">NAME</h1>

<p>SpadsPluginApi - SPADS Plugin API</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<p>Perl:</p>

<pre><code>package MyPlugin;

use SpadsPluginApi;

my $pluginVersion=&#39;0.1&#39;;
my $requiredSpadsVersion=&#39;0.11&#39;;

sub getVersion { return $pluginVersion; }
sub getRequiredSpadsVersion { return $requiredSpadsVersion; }

sub new {
  my $class=shift;
  my $self = {};
  bless($self,$class);
  slog(&quot;MyPlugin plugin loaded (version $pluginVersion)&quot;,3);
  return $self;
}

1;</code></pre>

<p>Python:</p>

<pre><code>import perl
spads=perl.MyPlugin

pluginVersion = &#39;0.1&#39;
requiredSpadsVersion = &#39;0.12.29&#39;

def getVersion(pluginObject):
    return pluginVersion

def getRequiredSpadsVersion(pluginName):
    return requiredSpadsVersion


class MyPlugin:

    def __init__(self,context):
        spads.slog(&quot;MyPlugin plugin loaded (version %s)&quot; % pluginVersion,3)</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p><code>SpadsPluginApi</code> is a Perl module implementing the plugin API for SPADS. This API allows anyone to add new features as well as customize existing SPADS features (such as balancing algorithms, battle status presentation, players skills management, command aliases...).</p>

<p>This API relies on plugin callback functions (implemented by SPADS plugins), which can in turn call plugin API functions (implemented by SPADS core) and access shared SPADS data.</p>

<p>Plugins can be coded in Perl (since SPADS 0.11) or Python (since SPADS 0.12.29).</p>

<h1 id="PYTHON-SPECIFIC-NOTES">PYTHON SPECIFIC NOTES</h1>

<h2 id="How-to-read-the-documentation">How to read the documentation</h2>

<p>This documentation was written when SPADS was only supporting plugins coded in Perl, so types for function parameters and return values are described using Perl terminology, with Perl sigils (<code>%</code> for hash, <code>@</code> for array, <code>$</code> for scalars). Python plugins just need to ignore these sigils and use their equivalent internal Python types instead (Python dictionaries instead of Perl hashes, Python lists instead of Perl arrays, Python tuples instead of Perl lists, Python None value instead of Perl undef value...).</p>

<p>In order to call functions from the plugin API, Python plugin modules must first import the special <code>perl</code> module, and then use the global variable of this module named after the plugin name to call the functions (refer to the SYNOPSYS for an example of a Python plugin named <code>MyPlugin</code> calling the <code>slog</code> API function).</p>

<h2 id="Perl-strings-conversions">Perl strings conversions</h2>

<p>SPADS uses the <code>Inline::Python</code> Perl module to interface Perl code with Python code. Unfortunately, some versions of this module don&#39;t auto-convert Perl strings entirely when used with Python 3 (Python 2 is unaffected): depending on the version of Python and the version of the <code>Inline::Python</code> Perl module used by your system, it is possible that the Python plugin callbacks receive Python byte strings as parameters instead of normal Python strings. In order to mitigate this problem, the plugin API offers both a way to detect from the Python plugin code if current system is affected (by calling the <code>get_flag</code> function with parameter <code>&#39;use_byte_string&#39;</code>), and a way to workaround the problem by calling a dedicated <code>fix_string</code> function which fixes the string values if needed. For additional information regarding these Python specific functions of the plugin API, refer to the <a href="#Python-specific">API FUNCTIONS - Python specific</a> section. Python plugins can also choose to implement their own pure Python function which fixes strings coming from SPADS if needed like this for example:</p>

<pre><code> def fix_spads_string(spads_string):
     if hasattr(spads_string,&#39;decode&#39;):
         return spads_string.decode(&#39;utf-8&#39;)
     return spads_string
 
 def fix_spads_strings(*spads_strings):
     fixed_strings=[]
     for spads_string in spads_strings:
         fixed_strings.append(fix_spads_string(spads_string))
     return fixed_strings</code></pre>

<h2 id="Windows-limitations">Windows limitations</h2>

<p>On Windows systems, Perl emulates the <code>fork</code> functionality using threads. As the <code>Inline::Python</code> Perl module used by SPADS to interface with Python code isn&#39;t thread-safe, the fork functions of the plugin API (<code>forkProcess</code> and <code>forkCall</code>) aren&#39;t available from Python plugins when running on a Windows system. On Windows systems, using native Win32 processes for parallel processing is recommended anyway. Plugins can check if the fork functions of the plugin API are available by calling the <code>get_flag</code> Python specific plugin API function with parameter <code>&#39;can_fork&#39;</code>, instead of checking by themselves if the current system is Windows. Refer to the <a href="#Python-specific">API FUNCTIONS - Python specific</a> section for more information regarding this function.</p>

<p>Automatic asynchronous socket management (<code>addSocket</code> plugin API function) is also unavailable for Python plugins on Windows systems (this is due to the file descriptor numbers being thread-specific on Windows, preventing SPADS from accessing sockets opened in Python interpreter scope). However, it is still possible to manage asynchronous sockets manually, for example by hooking the SPADS event loop (<code>eventLoop</code> plugin callback) to perform non-blocking <code>select</code> with 0 timeout (refer to <a href="https://docs.python.org/3/library/select.html#select.select">Python select documentation</a>). Plugins can check if the <code>addSocket</code> function of the plugin API is available by calling the <code>get_flag</code> Python specific plugin API function with parameter <code>&#39;can_add_socket&#39;</code>, instead of checking by themselves if the current system is Windows. Refer to the <a href="#Python-specific">API FUNCTIONS - Python specific</a> section for more information regarding this function.</p>

<h1 id="CALLBACK-FUNCTIONS">CALLBACK FUNCTIONS</h1>

<p>The callback functions are called from SPADS core and implemented by SPADS plugins. SPADS plugins are actually Perl or Python classes instanciated as objects. So most callback functions are called as object methods and receive a reference to the plugin object as first parameter. The exceptions are the constructor (Perl: <code>new</code> receives the class/plugin name as first parameter, Python: <code>__init__</code> receives the plugin object being created as first parameter), and a few other callbacks which are called/checked before the plugin object is actually created: <code>getVersion</code> and <code>getRequiredSpadsVersion</code> (mandatory callbacks), <code>getParams</code> and <code>getDependencies</code> (optional callbacks).</p>

<h2 id="Mandatory-callbacks">Mandatory callbacks</h2>

<p>To be valid, a SPADS plugin must implement at least these 3 callbacks:</p>

<dl>

<dt id="Perl-new-pluginName-context-.-.-.-.-Python-__init__-self-context">[Perl] <code>new($pluginName,$context)</code> . . . . [Python] <code>__init__(self,context)</code></dt>
<dd>

<p>This is the plugin constructor, it is called when SPADS (re)loads the plugin.</p>

<p>The <code>$context</code> parameter is a string which indicates in which context the plugin constructor has been called: <code>&quot;autoload&quot;</code> means the plugin is being loaded automatically at startup, <code>&quot;load&quot;</code> means the plugin is being loaded manually using <code>!plugin &lt;pluginName&gt; load</code> command, <code>&quot;reload&quot;</code> means the plugin is being reloaded manually using <code>!plugin &lt;pluginName&gt; reload</code> command.</p>

</dd>
<dt id="getVersion-self"><code>getVersion($self)</code></dt>
<dd>

<p>returns the plugin version number (example: <code>&quot;0.1&quot;</code>).</p>

</dd>
<dt id="getRequiredSpadsVersion-pluginName"><code>getRequiredSpadsVersion($pluginName)</code></dt>
<dd>

<p>returns the required minimum SPADS version number (example: <code>&quot;0.11&quot;</code>).</p>

</dd>
</dl>

<h2 id="Configuration-callback">Configuration callback</h2>

<p>SPADS plugins can use the core SPADS configuration system to manage their own configuration parameters. This way, all configuration management tools in place (parameter values checking, <code>!reloadconf</code> etc.) can be reused by the plugins. To do so, the plugin must implement following configuration callback:</p>

<dl>

<dt id="getParams-pluginName"><code>getParams($pluginName)</code></dt>
<dd>

<p>This callback must return a reference to an array containing 2 elements. The first element is a reference to a hash containing the plugin global settings declarations, the second one is the same but for plugin preset settings declarations. These hashes use setting names as keys, and references to array of allowed types as values. The types must be either strings that match the keys of the <code>%paramTypes</code> hash defined in SpadsConf.pm file, or custom functions to implement custom value checks. Such custom value checking functions take 2 parameters: the value to check as first parameter and a boolean specifying if the value is the default value (i.e. first value declared in the definition, for preset settings) as second parameter. The function must return <code>true</code> if the value is valid, or <code>false</code> if it is invalid (refer to examples below).</p>

<p>As for global SPADS core settings, the global settings of the plugin cannot be changed dynamically except by editing and reloading the configuration files (for example by using the <code>!reloadConf</code> command). The global settings are defined before the preset definition sections in the plugin configuration file. Only one definition is allowed for each global setting, and only one value can be configured in each global setting definition. Global settings aren&#39;t impacted by preset changes. Global settings should be used for the structural parameterization of the plugin, which isn&#39;t supposed to be modified during runtime and isn&#39;t useful from end user point of view (for example file/directory path settings...).</p>

<p>As for SPADS core preset settings, the preset settings of the plugin can be changed dynamically (using the <code>!plugin &lt;pluginName&gt; set &lt;settingName&gt; &lt;settingValue&gt;</code> command for example, or simply by changing current global preset). The preset settings are defined in the preset definition sections of the plugin configuration file, after the global plugin settings. The preset settings can be defined multiple times (once in each preset declaration section). Multiple values can be configured in each preset setting definition (values are separated by pipe character <code>|</code>, the first value is the default value applied when loading the preset and the remaining values are the other allowed values). Preset settings are impacted by preset changes. Preset settings should be used for settings that need to be visible by end users and/or modifiable easily at runtime.</p>

<p>Example of implementation in Perl:</p>

<pre><code>my %globalPluginParams = ( MyGlobalSetting1 =&gt; [&#39;integer&#39;],
                           MyGlobalSetting2 =&gt; [&#39;ipAddr&#39;]);
my %presetPluginParams = ( MyPresetSetting1 =&gt; [&#39;readableDir&#39;,&#39;null&#39;],
                           MyPresetSetting2 =&gt; [&#39;bool&#39;, \&amp;myCustomSettingValueCheck] );

sub myCustomSettingValueCheck {
  my ($settingValue,$isDefault)=@_;
  return $settingValue eq &#39;true&#39; || $settingValue eq &#39;false&#39;
}

sub getParams { return [\%globalPluginParams,\%presetPluginParams] }</code></pre>

<p>Example of implementation in Python:</p>

<pre><code>def myCustomSettingValueCheck(settingValue,isDefault):
    return settingValue == &#39;true&#39; or settingValue == &#39;false&#39;

globalPluginParams = { &#39;MyGlobalSetting1&#39;: [&#39;integer&#39;],
                       &#39;MyGlobalSetting2&#39;: [&#39;ipAddr&#39;] }
presetPluginParams = { &#39;MyPresetSetting1&#39;: [&#39;readableDir&#39;,&#39;null&#39;],
                       &#39;MyPresetSetting2&#39;: [&#39;bool&#39;, myCustomSettingValueCheck], };

def getParams(pluginName):
    return [ globalPluginParams , presetPluginParams ]</code></pre>

<p>In these examples, the preset setting <code>MyPresetSetting2</code> is declared as supporting both the values of the predefined type &quot;bool&quot; and the values allowed by the custom function <code>myCustomSettingValueCheck</code>. The predefined type &quot;bool&quot; allows values <code>0</code> and <code>1</code>. The custom function <code>myCustomSettingValueCheck</code> allows values <code>&quot;true&quot;</code> and <code>&quot;false&quot;</code>. So in the end the allowed values for the preset setting <code>MyPresetSetting2</code> are: <code>0</code>, <code>1</code>, <code>&quot;true&quot;</code> and <code>&quot;false&quot;</code>.</p>

</dd>
</dl>

<h2 id="Dependencies-callback">Dependencies callback</h2>

<p>SPADS plugins can use data and functions from other plugins (dependencies). But this can only work if the plugin dependencies are loaded before the plugin itself. That&#39;s why following callback should be used by such dependent plugins to declare their dependencies, which will allow SPADS to perform the check for them. Also, SPADS will automatically unload dependent plugins when one of their dependencies is unloaded.</p>

<dl>

<dt id="getDependencies-pluginName"><code>getDependencies($pluginName)</code></dt>
<dd>

<p>This callback must return the plugin dependencies (list of plugin names).</p>

<p>Example of implementation in Perl:</p>

<pre><code>sub getDependencies { return (&#39;SpringForumInterface&#39;,&#39;MailAlerts&#39;); }</code></pre>

<p>Example of implementation in Python:</p>

<pre><code>def getDependencies(pluginName):
    return (&#39;SpringForumInterface&#39;,&#39;MailAlerts&#39;)</code></pre>

</dd>
</dl>

<h2 id="Event-based-callbacks">Event-based callbacks</h2>

<p>Following callbacks are triggered by events from various sources (SPADS, Spring lobby, Spring server...):</p>

<dl>

<dt id="onBattleClosed-self"><code>onBattleClosed($self)</code></dt>
<dd>

<p>This callback is called when the battle lobby of the autohost is closed.</p>

</dd>
<dt id="onBattleOpened-self"><code>onBattleOpened($self)</code></dt>
<dd>

<p>This callback is called when the battle lobby of the autohost is opened.</p>

</dd>
<dt id="onGameEnd-self-endGameData"><code>onGameEnd($self,\%endGameData)</code></dt>
<dd>

<p>This callback is called each time a game hosted by the autohost ends.</p>

<p>The <code>\%endGameData</code> parameter is a reference to a hash containing all the data stored by SPADS concerning the game that just ended. It is recommended to use a data printing function (such as the <code>Dumper</code> function from the standard <code>Data::Dumper</code> module included in Perl core) to check the content of this hash for the desired data.</p>

</dd>
<dt id="onJoinBattleRequest-self-userName-ipAddr"><code>onJoinBattleRequest($self,$userName,$ipAddr)</code></dt>
<dd>

<p>This callback is called each time a client requests to join the battle lobby managed by the autohost.</p>

<p><code>$userName</code> is the name of the user requesting to join the battle</p>

<p><code>$ipAddr</code> is the IP address of the user requesting to join the battle</p>

<p>This callback must return:</p>

<p><code>0</code> if the user is allowed to join the battle</p>

<p><code>1</code> if the user isn&#39;t allowed to join the battle (without explicit reason)</p>

<p><code>&quot;&lt;explicit reason string&gt;&quot;</code> if the user isn&#39;t allowed to join the battle, with explicit reason</p>

</dd>
<dt id="onJoinedBattle-self-userName"><code>onJoinedBattle($self,$userName)</code></dt>
<dd>

<p>This callback is called each time a user joins the battle lobby of the autohost.</p>

<p><code>$userName</code> is the name of the user who just joined the battle lobby</p>

</dd>
<dt id="onLeftBattle-self-userName"><code>onLeftBattle($self,$userName)</code></dt>
<dd>

<p>This callback is called each time a user leaves the battle lobby of the autohost.</p>

<p><code>$userName</code> is the name of the user who just left the battle lobby</p>

</dd>
<dt id="onLobbyConnected-self-lobbyInterface"><code>onLobbyConnected($self,$lobbyInterface)</code></dt>
<dd>

<p>/!\ RENAMED TO <code>onLobbySynchronized</code> /!\</p>

<p>This callback has been renamed to <code>onLobbySynchronized</code> since SPADS v0.13.35. It can still be used under the name <code>onLobbyConnected</code> for the sake of backward compatibility, however this name is misleading so its usage under this name is not recommended (the callback is only called when the lobby connection is fully synchronized, i.e. when all the initial commands sent by the lobby server after successfully logging in have been received).</p>

<p>The <code>$lobbyInterface</code> parameter is the instance of the <a href="https://github.com/Yaribz/SpringLobbyInterface">SpringLobbyInterface</a> module used by SPADS.</p>

</dd>
<dt id="onLobbyDisconnected-self"><code>onLobbyDisconnected($self)</code></dt>
<dd>

<p>This callback is called each time the autohost is disconnected from the lobby server.</p>

</dd>
<dt id="onLobbyLoggedIn-self-lobbyInterface"><code>onLobbyLoggedIn($self,$lobbyInterface)</code></dt>
<dd>

<p>This callback is called each time the autohost successfully logins on the lobby server. It is one of the three callbacks triggered when a new connection to the lobby server is established. These callbacks are called in following order:</p>

<ul>

<li><p>1) <code>onLobbyLogin</code> (called when trying to login)</p>

</li>
<li><p>2) <code>onLobbyLoggedIn</code> (called when successfully logged in)</p>

</li>
<li><p>3) <code>onLobbySynchronized</code> (called when state is synchronized with server)</p>

</li>
</ul>

<p>The <code>$lobbyInterface</code> parameter is the instance of the <a href="https://github.com/Yaribz/SpringLobbyInterface">SpringLobbyInterface</a> module used by SPADS.</p>

<p>Note: This callback is the ideal place for a plugin to register its lobby command handlers using the <code>addLobbyCommandHandler</code> function of the plugin API, if this plugin needs to process the commands sent by the lobby server during the initial lobby state synchronization phase (i.e. commands sent before the <code>LOGININFOEND</code> command). For plugins that do not require being called back during the initial lobby state synchronization phase, the <code>onLobbySynchronized</code> callback should be used instead to register the lobby command handlers.</p>

</dd>
<dt id="onLobbyLogin-self-lobbyInterface"><code>onLobbyLogin($self,$lobbyInterface)</code></dt>
<dd>

<p>This callback is called each time the autohost tries to login on the lobby server. It is one of the three callbacks triggered when a new connection to the lobby server is established. These callbacks are called in following order:</p>

<ul>

<li><p>1) <code>onLobbyLogin</code> (called when trying to login)</p>

</li>
<li><p>2) <code>onLobbyLoggedIn</code> (called when successfully logged in)</p>

</li>
<li><p>3) <code>onLobbySynchronized</code> (called when state is synchronized with server)</p>

</li>
</ul>

<p>The <code>$lobbyInterface</code> parameter is the instance of the <a href="https://github.com/Yaribz/SpringLobbyInterface">SpringLobbyInterface</a> module used by SPADS.</p>

</dd>
<dt id="onLobbySynchronized-self-lobbyInterface"><code>onLobbySynchronized($self,$lobbyInterface)</code></dt>
<dd>

<p>This callback is called each time the autohost completes the lobby state synchronization phase, which occurs after successfully logging in. It is one of the three callbacks triggered when a new connection to the lobby server is established. These callbacks are called in following order:</p>

<ul>

<li><p>1) <code>onLobbyLogin</code> (called when trying to login)</p>

</li>
<li><p>2) <code>onLobbyLoggedIn</code> (called when successfully logged in)</p>

</li>
<li><p>3) <code>onLobbySynchronized</code> (called when state is synchronized with server)</p>

</li>
</ul>

<p>The <code>$lobbyInterface</code> parameter is the instance of the <a href="https://github.com/Yaribz/SpringLobbyInterface">SpringLobbyInterface</a> module used by SPADS.</p>

<p>Note: This callback is the ideal place for a plugin to register its lobby command handlers using the <code>addLobbyCommandHandler</code> function of the plugin API, as long as this plugin does not need to process the commands sent by the lobby server during the initial lobby state synchronization phase (i.e. commands sent before the <code>LOGININFOEND</code> command). For plugins that require being called back during the initial lobby state synchronization phase, the <code>onLobbyLoggedIn</code> callback must be used instead to register the lobby command handlers.</p>

</dd>
<dt id="onPresetApplied-self-oldPresetName-newPresetName"><code>onPresetApplied($self,$oldPresetName,$newPresetName)</code></dt>
<dd>

<p>This callback is called each time a global preset is applied.</p>

<p><code>$oldPresetName</code> is the name of the previous global preset</p>

<p><code>$newPresetName</code> is the name of the new global preset</p>

</dd>
<dt id="onPrivateMsg-self-userName-message"><code>onPrivateMsg($self,$userName,$message)</code></dt>
<dd>

<p>This callback is called each time the autohost receives a private message.</p>

<p><code>$userName</code> is the name of the user who sent a private message to the autohost</p>

<p><code>$message</code> is the private message received by the autohost</p>

<p>This callback must return:</p>

<p><code>0</code> if the message can be processed by other plugins and SPADS core</p>

<p><code>1</code> if the message must not be processed by other plugins and SPADS core (this prevents logging)</p>

</dd>
<dt id="onReloadConf-self-keepSettings"><code>onReloadConf($self,$keepSettings)</code></dt>
<dd>

<p>This callback is called each time the SPADS configuration is reloaded.</p>

<p><code>$keepSettings</code> is a boolean parameter indicating if current settings must be kept.</p>

<p>This callback must return:</p>

<p><code>0</code> if an error occured while reloading the plugin configuration</p>

<p><code>1</code> if the plugin configuration has been reloaded correctly</p>

</dd>
<dt id="onSettingChange-self-settingName-oldValue-newValue"><code>onSettingChange($self,$settingName,$oldValue,$newValue)</code></dt>
<dd>

<p>This callback is called each time a setting of the plugin configuration is changed (using <code>!plugin &lt;pluginName&gt; set ...</code> command).</p>

<p><code>$settingName</code> is the name of the updated setting</p>

<p><code>$oldValue</code> is the previous value of the setting</p>

<p><code>$newValue</code> is the new value of the setting</p>

</dd>
<dt id="onSpringStart-self-springPid"><code>onSpringStart($self,$springPid)</code></dt>
<dd>

<p>This callback is called each time a Spring process is launched to host a game.</p>

<p><code>$springPid</code> is the PID of the Spring process that has just been launched.</p>

</dd>
<dt id="onSpringStop-self-springPid"><code>onSpringStop($self,$springPid)</code></dt>
<dd>

<p>This callback is called each time the Spring process ends.</p>

<p><code>$springPid</code> is the PID of the Spring process that just ended.</p>

</dd>
<dt id="onUnload-self-context"><code>onUnload($self,$context)</code></dt>
<dd>

<p>This callback is called when the plugin is unloaded. If the plugin has added handlers for SPADS command, lobby commands, or Spring commands, then they must be removed here. If the plugin has added timers or forked process callbacks, they should also be removed here. If the plugin handles persistent data, then these data must be serialized and written to persistent storage here.</p>

<p>The <code>$context</code> parameter is a string which indicates in which context the callback has been called: <code>&quot;exiting&quot;</code> means the plugin is being unloaded because SPADS is exiting, <code>&quot;restarting&quot;</code> means the plugin is being unloaded because SPADS is restarting, <code>&quot;unload&quot;</code> means the plugin is being unloaded manually using <code>!plugin &lt;pluginName&gt; unload</code> command, <code>&quot;reload&quot;</code> means the plugin is being reloaded manually using <code>!plugin &lt;pluginName&gt; reload</code> command.</p>

</dd>
<dt id="onVoteRequest-self-source-user-command-remainingVoters"><code>onVoteRequest($self,$source,$user,\@command,\%remainingVoters)</code></dt>
<dd>

<p>This callback is called each time a vote is requested by a player.</p>

<p><code>$source</code> indicates the way the vote has been requested (<code>&quot;pv&quot;</code>: private lobby message, <code>&quot;battle&quot;</code>: battle lobby message, <code>&quot;chan&quot;</code>: master lobby channel message, <code>&quot;game&quot;</code>: in game message)</p>

<p><code>$user</code> is the name of the user requesting the vote</p>

<p><code>\@command</code> is an array reference containing the command for which a vote is requested</p>

<p><code>\%remainingVoters</code> is a reference to a hash containing the players allowed to vote. This hash is indexed by player names. Perl plugins can filter these players by removing the corresponding entries from the hash directly, but Python plugins must use the alternate method based on the return value described below.</p>

<p>This callback must return <code>0</code> to prevent the vote call from happening, or <code>1</code> to allow it without changing the remaining voters list, or an array reference containing the player names that should be removed from the remaining voters list.</p>

</dd>
<dt id="onVoteStart-self-user-command"><code>onVoteStart($self,$user,\@command)</code></dt>
<dd>

<p>This callback is called each time a new vote poll is started.</p>

<p><code>$user</code> is the name of the user who started the vote poll</p>

<p><code>\@command</code> is an array reference containing the command for which a vote is started</p>

</dd>
<dt id="onVoteStop-self-voteResult"><code>onVoteStop($self,$voteResult)</code></dt>
<dd>

<p>This callback is called each time a vote poll is stoped.</p>

<p><code>$voteResult</code> indicates the result of the vote: <code>-1</code> (vote failed), <code>0</code> (vote cancelled), <code>1</code> (vote passed)</p>

</dd>
<dt id="postSpadsCommand-self-command-source-user-params-commandResult"><code>postSpadsCommand($self,$command,$source,$user,\@params,$commandResult)</code></dt>
<dd>

<p>This callback is called each time a SPADS command has been called.</p>

<p><code>$command</code> is the name of the command (without the parameters)</p>

<p><code>$source</code> indicates the way the command has been called (<code>&quot;pv&quot;</code>: private lobby message, <code>&quot;battle&quot;</code>: battle lobby message, <code>&quot;chan&quot;</code>: master lobby channel message, <code>&quot;game&quot;</code>: in game message)</p>

<p><code>$user</code> is the name of the user who called the command</p>

<p><code>\@params</code> is a reference to an array containing the parameters of the command</p>

<p><code>$commandResult</code> indicates the result of the command (if it is defined and set to <code>0</code> then the command failed, in all other cases the command succeeded)</p>

</dd>
<dt id="preGameCheck-self-force-checkOnly-automatic"><code>preGameCheck($self,$force,$checkOnly,$automatic)</code></dt>
<dd>

<p>This callback is called each time a game is going to be launched, to allow plugins to perform pre-game checks and prevent the game from starting if needed.</p>

<p><code>$force</code> is <code>1</code> if the game is being launched using <code>!forceStart</code> command, <code>0</code> else</p>

<p><code>$checkOnly</code> is <code>1</code> if the callback is being called in the context of a vote call, <code>0</code> else</p>

<p><code>$automatic</code> is <code>1</code> if the game is being launched automatically through autoStart functionality, <code>0</code> else</p>

<p>The return value must be the reason for preventing the game from starting (for example <code>&quot;too many players for current map&quot;</code>), or <code>1</code> if no reason can be given, or undef to allow the game to start.</p>

</dd>
<dt id="preSpadsCommand-self-command-source-user-params"><code>preSpadsCommand($self,$command,$source,$user,\@params)</code></dt>
<dd>

<p>This callback is called each time a SPADS command is called, just before it is actually executed.</p>

<p><code>$command</code> is the name of the command (without the parameters)</p>

<p><code>$source</code> indicates the way the command has been called (<code>&quot;pv&quot;</code>: private lobby message, <code>&quot;battle&quot;</code>: battle lobby message, <code>&quot;chan&quot;</code>: master lobby channel message, <code>&quot;game&quot;</code>: in game message)</p>

<p><code>$user</code> is the name of the user who called the command</p>

<p><code>\@params</code> is a reference to an array containing the parameters of the command</p>

<p>This callback must return <code>0</code> to prevent the command from being processed by other plugins and SPADS core, or <code>1</code> to allow it.</p>

</dd>
</dl>

<h2 id="Customization-callbacks">Customization callbacks</h2>

<p>Following callbacks are called by SPADS during specific operations to allow plugins to customize features (more callbacks can be added on request):</p>

<dl>

<dt id="addStartScriptTags-self-additionalData"><code>addStartScriptTags($self,\%additionalData)</code></dt>
<dd>

<p>This callback is called when a Spring start script is generated, just before launching the game. It allows plugins to declare additional scrip tags which will be written in the start script.</p>

<p><code>\%additionalData</code> is a reference to a hash which must be updated by Perl plugins by adding the desired keys/values. For example a Perl plugin can add a modoption named <code>hiddenoption</code> with value <code>test</code> like this: <code>$additionalData{&quot;game/modoptions/hiddenoption&quot;}=&quot;test&quot;</code>. For tags to be added in player sections, the special key <code>playerData</code> must be used. This special key must point to a hash associating each account ID to a hash containing the tags to add in the corresponding player section (subsections can be created by using nested hashes). For tags to be added in AI bot sections, the special key <code>aiData</code> must be used. This special key must point to a hash associating each AI bot name to a hash containing the tags to add in the corresponding AI bot section (subsections can be created by using nested hashes).</p>

<p>Note for Python plugins: As Python plugins cannot modify the data structures passed as parameters to the callbacks, an alternate way to implement this callback is offered. Instead of modifying the <code>additionnalData</code> dictionary directly, the callback can return a new dictionary containing the entries which must be added. For example a Python plugin can add a tag named <code>CommanderLevel</code> set to value <code>8</code> in the player section of the player whose account ID is <code>1234</code> like this: <code>return {&#39;playerData&#39;: { &#39;1234&#39;: { &#39;CommanderLevel&#39;: 8 } } }</code></p>

</dd>
<dt id="balanceBattle-self-players-bots-clanMode-nbTeams-teamSize"><code>balanceBattle($self,\%players,\%bots,$clanMode,$nbTeams,$teamSize)</code></dt>
<dd>

<p>This callback is called each time SPADS needs to balance a battle and evaluate the resulting balance quality. It allows plugins to replace the built-in balance algorithm.</p>

<p><code>\%players</code> is a reference to a hash containing the players in the battle lobby. This hash is indexed by player names, and the values are references to a hash containing player data. For balancing, you should only need to access the players skill as follows: <code>$players-&gt;{&lt;playerName&gt;}-&gt;{skill}</code></p>

<p><code>\%bots</code> is a reference to a hash containing the bots in the battle lobby. This hash has the exact same structure as <code>\%players</code>.</p>

<p><code>$clanMode</code> is the current clan mode which must be applied to the balance. Clan modes are specified <a href="http://planetspads.free.fr/spads/doc/spadsDoc_All.html#set:clanMode">here</a>. <code>&lt;maxUnbalance&gt;</code> thresholds are automatically managed by SPADS, plugins don&#39;t need to handle them. So basically, plugins only need to check if <code>tag</code> and/or <code>pref</code> clan modes are enabled and apply them to their balance algorithm.</p>

<p><code>$nbTeams</code> and <code>$teamSize</code> are the target battle structue computed by SPADS. The number of entities to balance is the number of entries in <code>\%players</code> + number of entries in <code>\%bots</code>. The number of entities to balance is always <code>&gt; $nbTeams*($teamSize-1)</code>, and <code>&lt;= $nbTeams*$teamSize</code>.</p>

<p>If the plugin is unable to balance the battle, it must not update <code>\%players</code> and <code>\%bots</code>. The callback must return undef or a negative value so that SPADS knows it has to use another plugin or the internal balance algorithm instead.</p>

<p>If the plugin is able to balance the battle, it can use two methods to transmit the desired balance to SPADS (Python plugins can only use the second method):</p>

<p>The first method consists in updating directly the <code>\%players</code> and <code>\%bots</code> hash references with the team and id information. Assigned player teams must be written in <code>$players-&gt;{&lt;playerName&gt;}-&gt;{battleStatus}-&gt;{team}</code>, and assigned player ids must be written in <code>$players-&gt;{&lt;playerName&gt;}-&gt;{battleStatus}-&gt;{id}</code>. The <code>\%bots</code> hash reference works the same way. The return value is the unbalance indicator, defined as follows: <code>standardDeviationOfTeamSkills * 100 / averageTeamSkill</code>.</p>

<p>The second method consists in returning an array reference containing the balance information instead of directly editing the <code>\%players</code> and <code>\%bots</code> parameters. The returned array must contain 3 items: the unbalance indicator (as defined in first method description above), the player assignation hash and the bot assignation hash. The player assignation hash and the bot assignation hash have exactly the same structure: the keys are the player/bot names and the values are hashes containing <code>team</code> and <code>id</code> items with the corresponding values for the balanced battle.</p>

</dd>
<dt id="canBalanceNow-self"><code>canBalanceNow($self)</code></dt>
<dd>

<p>This callback allows plugins to delay the battle balance operation. It is called each time a battle balance operation is required (either automatic if autoBalance is enabled, either manual if <code>!balance</code> command is called). If the plugin is ready for balance, it must return <code>1</code>. Else, it can delay the operation by returning <code>0</code> (the balance algorithm won&#39;t be launched as long as the plugin didn&#39;t return <code>1</code>).</p>

</dd>
<dt id="changeUserAccessLevel-self-userName-userData-isAuthenticated-currentAccessLevel"><code>changeUserAccessLevel($self,$userName,\%userData,$isAuthenticated,$currentAccessLevel)</code></dt>
<dd>

<p>This callback is called by SPADS each time it needs to get the access level of a user. It allows plugins to overwrite this level. Don&#39;t call the <code>getUserAccessLevel($user)</code> function from this callback, or the program will be locked in recursive loop! (and it would give you the same value as <code>$currentAccessLevel</code> anyway).</p>

<p><code>\%userData</code> is a reference to a hash containing the lobby data of the user</p>

<p><code>$isAuthenticated</code> indicates if the user has been authenticated (0: lobby server in LAN mode and not authenticated at autohost level, 1: authenticated by lobby server only, 2: authenticated by autohost)</p>

<p>The callback must return the new access level value if changed, or undef if not changed.</p>

</dd>
<dt id="delayShutdown-self"><code>delayShutdown($self)</code></dt>
<dd>

<p>This callback is called by SPADS each time it needs to quit or restart. It allows plugins to delay the shutdown operation, which can be useful to prevent SPADS from exiting before a process forked by the plugin ends for example.</p>

<p>The callback must return a false value if SPADS can quit right now, or a true value if SPADS must wait before exiting.</p>

</dd>
<dt id="filterRotationMaps-self-rotationMaps"><code>filterRotationMaps($self,\@rotationMaps)</code></dt>
<dd>

<p>This callback is called by SPADS each time a new map must be picked up for rotation. It allows plugins to remove some maps from the rotation maps list just before the new map is picked up.</p>

<p><code>\@rotationMaps</code> is a reference to an array containing the names of the maps currently allowed for rotation.</p>

<p>The callback must return a reference to a new array containing the filtered map names.</p>

</dd>
<dt id="fixColors-self-players-bots-battleStructure"><code>fixColors($self,\%players,\%bots,\%battleStructure)</code></dt>
<dd>

<p>This callback is called each time SPADS needs to fix the teams colors. It allows plugins to replace the built-in color fixing algorithm.</p>

<p><code>\%players</code> is a reference to a hash containing the players currently in the battle lobby. This hash is indexed by player names, and the values are references to hashes containing following player data: <code>team</code> (team number), <code>id</code> (id number) and <code>color</code> (current color configured in lobby, i.e. a hash containing keys <code>&quot;red&quot;</code>, <code>&quot;green&quot;</code>, <code>&quot;blue&quot;</code> and whose values are numbers between 0 and 255 included).</p>

<p><code>\%bots</code> is a reference to a hash containing the bots currently in the battle lobby. This hash has the exact same structure as <code>\%players</code>.</p>

<p><code>\%battleStructure</code> is a reference to a hash containing data concerning the battle structure. This parameter is provided to plugins for ease of use but actually these data are redundant with the data already provided in the two previous parameters (the <code>%players</code> and <code>%bots</code> hashes), they are just organized in a different way. The <code>%battleStructure</code> hash is indexed by team numbers. For each team number, the associated value is a reference to a hash indexed by the ID numbers contained in the team. For each ID number, the associated value is a reference to a hash containing the two following keys: <code>players</code> (the associated value is a reference to an array containing the names of the players belonging to this ID) and <code>bots</code> (the associated value is a reference to an array containing the names of the AI bots belonging to this ID).</p>

<p>If the plugin is unable to fix colors, then it must return <code>undef</code> so that SPADS knows it has to use another plugin or the internal color fixing algorithm instead.</p>

<p>If the plugin is able to fix the players and AI bots colors, then it must return a reference to a hash containing all colors assignations, indexed by ID numbers. The keys must be the ID numbers and the values are references to hash whose keys are <code>&quot;red&quot;</code>, <code>&quot;green&quot;</code> and <code>&quot;blue&quot;</code> and values are the corresponding RGB values (between 0 and 255 included) of the color assigned to the ID.</p>

</dd>
<dt id="setMapStartBoxes-self-boxes-mapName-nbTeams-nbExtraBox"><code>setMapStartBoxes($self,\@boxes,$mapName,$nbTeams,$nbExtraBox)</code></dt>
<dd>

<p>This callback allows plugins to set map start boxes (for &quot;Choose in game&quot; start position type).</p>

<p><code>\@boxes</code> is a reference to an array containing the start boxes definitions. A start box definition is a string containing the box coordinates separated by spaces, in following order: left, top, right, bottom (0,0 is top left corner and 200,200 is bottom right corner). If the array already contains box definitions, it means SPADS already knows boxes for this map.</p>

<p><code>$mapName</code> is the name of the map for which start boxes are requested</p>

<p><code>$nbTeams</code> is the current number of teams configured (at least this number of start boxes must be provided)</p>

<p><code>$nbExtraBox</code> is the number of extra box required. Usually this is 0, unless a special game mode is enabled such as King Of The Hill.</p>

<p>If the plugin isn&#39;t able or doesn&#39;t need to provide/override start boxes, it must not update the <code>\@boxes</code> array. It must return <code>0</code> so that SPADS knows it has to check other plugins for possible start boxes.</p>

<p>If the plugin needs to provide/override start boxes, it can use two methods to transmit the start box definitions (Python plugins can only use the second method):</p>

<p>The first method consists in replacing the <code>\@boxes</code> array content directly with the new desired start box definitions. If other plugins should be allowed to replace the start box definitions, the callback must return <code>0</code>, else it must return <code>1</code>.</p>

<p>The second method consists in returning an array reference containing the new start box definitions instead of directly updating the <code>\@boxes</code> parameter. The returned array must contain 2 items: the normal return value as first item (<code>0</code> to allow other plugins to replace the start boxes, or <code>1</code> else), and an array reference containg the new start box definitions as second item.</p>

</dd>
<dt id="setVoteMsg-self-reqYesVotes-maxReqYesVotes-reqNoVotes-maxReqNoVotes-nbRequiredManualVotes"><code>setVoteMsg($self,$reqYesVotes,$maxReqYesVotes,$reqNoVotes,$maxReqNoVotes,$nbRequiredManualVotes)</code></dt>
<dd>

<p>This callback allows plugins to customize the vote status messages.</p>

<p><code>$reqYesVotes</code> is the total number of &quot;yes&quot; votes required for vote to pass (if away-voters don&#39;t vote).</p>

<p><code>$reqNoVotes</code> is the total number of &quot;no&quot; votes required for vote to fail (if away-voters don&#39;t vote).</p>

<p><code>$maxReqYesVotes</code> is the maximum total number of &quot;yes&quot; votes required for vote to pass (if all away-voters come back and vote).</p>

<p><code>$maxReqNoVotes</code> is the maximum total number of &quot;no&quot; votes required for vote to fail (if all away-voters come back and vote).</p>

<p><code>$nbRequiredManualVotes</code> is the minimum number of manual votes required for vote to be taken into account.</p>

<p>The callback must return a list containing following 2 elements: the lobby vote message, and the in-game vote message (undef values can be used to keep default messages).</p>

</dd>
<dt id="updateCmdAliases-self-aliases"><code>updateCmdAliases($self,\%aliases)</code></dt>
<dd>

<p>This callback allows plugins to add new SPADS command aliases by adding new entries in the <code>\%aliases</code> hash reference. This hash is indexed by alias names and the values are references to an array containing the associated command. For example, a Perl plugin can add an alias &quot;<code>!cvmap ...</code>&quot; for &quot;<code>!callVote map ...</code>&quot; like this: <code>$aliases-&gt;{cvmap}=[&#39;callVote&#39;,&#39;map&#39;]</code></p>

<p><code>&quot;%&lt;N&gt;%&quot;</code> can be used as placeholders for original alias command parameters. For example, a Perl plugin can add an alias &quot;<code>!iprank &lt;playerName&gt;</code>&quot; for &quot;<code>!chrank &lt;playerName&gt; ip</code>&quot; like this: <code>$aliases-&gt;{iprank}=[&#39;chrank&#39;,&#39;%1%&#39;,&#39;ip&#39;]</code></p>

<p>Note for Python plugins: As Python plugins cannot modify the data structures passed as parameters to the callbacks, an alternate way to implement this callback is offered. Instead of modifying the <code>aliases</code> dictionary directly, the callback can return a new dictionary containing the alias entries which must be added.</p>

</dd>
<dt id="updatePlayerSkill-self-playerSkill-accountId-modName-gameType"><code>updatePlayerSkill($self,\%playerSkill,$accountId,$modName,$gameType)</code></dt>
<dd>

<p>This callback is called by SPADS each time it needs to get or update the skill of a player (on battle join, on game type change...). This allows plugins to replace the built-in skill estimations (rank, TrueSkill...) with custom skill estimations (ELO, Glicko ...).</p>

<p><code>\%playerSkill</code> is a reference to a hash containing the skill data of the player. A Perl plugin can update the <code>skill</code> entry as follows: <code>$playerSkill-&gt;{skill}=&lt;skillValue&gt;</code>. The skill uncertainty can also be updated by plugins, by updating the <code>sigma</code> entry as follows: <code>$playerSkill-&gt;{sigma}=&lt;skillUncertaintyValue&gt;</code>.</p>

<p><code>$accountId</code> is the account ID of the player for whom skill value is requested.</p>

<p><code>$modName</code> is the currently hosted MOD (example: <code>&quot;Balanced Annihilation V7.72&quot;</code>)</p>

<p><code>$gameType</code> is the current game type (<code>&quot;Duel&quot;</code>, <code>&quot;Team&quot;</code>, <code>&quot;FFA&quot;</code> or <code>&quot;TeamFFA&quot;</code>)</p>

<p>The return value is the skill update status: <code>0</code> (skill not updated by the plugin), <code>1</code> (skill updated by the plugin), <code>2</code> (skill updated by the plugin in degraded mode)</p>

<p>Note for Python plugins: As Python plugins cannot modify the data structures passed as parameters to the callbacks, an alternate way to implement this callback is offered. Instead of modifying the <code>playerSkill</code> dictionary directly, the callback can return a list containing the normal return value as first item (described above), the new skill value as second item, and optionally the new skill uncertainty value as third item.</p>

</dd>
<dt id="updateGameStatusInfo-self-playerStatus-accessLevel"><code>updateGameStatusInfo($self,\%playerStatus,$accessLevel)</code></dt>
<dd>

<p>This callback is called by SPADS for each player in game when the <code>!status</code> command is called, to allow plugins to update and/or add data which will be presented to the user issuing the command.</p>

<p><code>\%playerStatus</code> is a reference to the hash containing current player status data. A Perl plugin can update existing data or add new data in this hash. For example: <code>$playerStatus-&gt;{myPluginData}=&lt;myPluginValue&gt;</code></p>

<p><code>$accessLevel</code> is the autohost access level of the user issuing the <code>!status</code> command.</p>

<p>The return value must be a reference to an array containing the names of the status information updated or added by the plugin.</p>

<p>Note for Python plugins: As Python plugins cannot modify the data structures passed as parameters to the callbacks, an alternate way to implement this callback is offered. Instead of modifying the <code>playerStatus</code> dictionary directly, the callback can return a new dictionary containing the data to add/modify in the <code>playerStatus</code> dictionary.</p>

</dd>
<dt id="updateStatusInfo-self-playerStatus-accountId-modName-gameType-accessLevel"><code>updateStatusInfo($self,\%playerStatus,$accountId,$modName,$gameType,$accessLevel)</code></dt>
<dd>

<p>This callback is called by SPADS for each player in the battle lobby when the <code>!status</code> command is called, to allow plugins to update and/or add data which will be presented to the user issuing the command.</p>

<p><code>\%playerStatus</code> is a reference to the hash containing current player status data. A Perl plugin can update existing data or add new data in this hash. For example: <code>$playerStatus-&gt;{myPluginData}=&lt;myPluginValue&gt;</code></p>

<p><code>$accountId</code> is the account ID of the player for whom status data update is requested.</p>

<p><code>$modName</code> is the currently hosted MOD (example: <code>&quot;Balanced Annihilation V7.72&quot;</code>)</p>

<p><code>$gameType</code> is the current game type (<code>&quot;Duel&quot;</code>, <code>&quot;Team&quot;</code>, <code>&quot;FFA&quot;</code> or <code>&quot;TeamFFA&quot;</code>)</p>

<p><code>$accessLevel</code> is the autohost access level of the user issuing the <code>!status</code> command.</p>

<p>The return value must be a reference to an array containing the names of the status information updated or added by the plugin.</p>

<p>Note for Python plugins: As Python plugins cannot modify the data structures passed as parameters to the callbacks, an alternate way to implement this callback is offered. Instead of modifying the <code>playerStatus</code> dictionary directly, the callback can return a new dictionary containing the data to add/modify in the <code>playerStatus</code> dictionary.</p>

</dd>
</dl>

<h2 id="Event-loop-callback">Event loop callback</h2>

<p>SPADS uses the asynchronous programming paradigm, so it is based on a main event loop. The following callback is called during each iteration of this event loop:</p>

<dl>

<dt id="eventLoop-self"><code>eventLoop($self)</code></dt>
<dd>

<p>Warning: this callback is called very frequently (during each iteration of SPADS main event loop), so performing complex operations here can be very intensive on the CPU. It is recommended to use timers (<code>addTimer</code>/<code>removeTimer</code> functions) instead for all time related operations (timeouts, scheduled actions, regular serialization of persistent data to avoid data loss...). This callback shouldn&#39;t be blocking, otherwise SPADS may become unstable.</p>

</dd>
</dl>

<h1 id="API-FUNCTIONS">API FUNCTIONS</h1>

<p>The API functions are implemented by SPADS core and can be called by SPADS plugins (directly from Perl plugins, or via <code>spads.[...]</code> from Python plugins).</p>

<h2 id="Accessors">Accessors</h2>

<dl>

<dt id="getBosses"><code>getBosses()</code></dt>
<dd>

<p>This accessor returns a reference to the hash containing the names of the bosses in the battle lobby (if the hash is empty, the boss mode is disabled).</p>

</dd>
<dt id="getConfMacros"><code>getConfMacros()</code></dt>
<dd>

<p>This accessor returns a reference to the hash containing the configuration macros used to (re)start SPADS.</p>

</dd>
<dt id="getCurrentVote"><code>getCurrentVote()</code></dt>
<dd>

<p>This accessor returns a reference to a hash containing information regarding votes.</p>

<p>If there is no vote in progress and the last vote succeeded, then the returned hash is always empty.</p>

<p>If there is no vote in progress and the last vote failed, then the content of the returned hash depends on the delay since the last vote ended. If the delay is greater than the <a href="http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:reCallVoteDelay">reCallVoteDelay</a>, then the returned hash is empty, else it contains the two following keys:</p>

<ul>

<li><p><code>user</code>: the name of the user who started the last vote</p>

</li>
<li><p><code>expireTime</code>: the time when the last vote failed (in UNIX timestamp format)</p>

</li>
</ul>

<p>If there is a vote in progress, then the returned hash contains following keys:</p>

<ul>

<li><p><code>user</code>: the name of the user who started the vote</p>

</li>
<li><p><code>expireTime</code>: the time when the vote will timeout, in UNIX timestamp format</p>

</li>
<li><p><code>awayVoteTime</code>: the time when the automatic votes for away users (see <a href="http://planetspads.free.fr/spads/doc/spadsDoc_Preferences.html#pset:voteMode">voteMode</a> preference) will be taken into account, in UNIX timestamp format. This field is reset to zero when the corresponding time is reached and votes for away users are triggered.</p>

</li>
<li><p><code>source</code>: the source of the message which started the vote (either <code>&quot;pv&quot;</code>, <code>&quot;chan&quot;</code>, <code>&quot;game&quot;</code> or <code>&quot;battle&quot;</code>)</p>

</li>
<li><p><code>command</code>: a reference to an array containg the command being voted (the first element is the command name, the other elements are the command parameters)</p>

</li>
<li><p><code>remainingVoters</code>: a reference to a hash whose keys are the names of the players allowed to vote who didn&#39;t vote yet</p>

</li>
<li><p><code>yesCount</code>: current number of &quot;yes&quot; votes</p>

</li>
<li><p><code>noCount</code>: current number of &quot;no&quot; votes</p>

</li>
<li><p><code>blankCount</code>: current number of &quot;blank&quot; votes</p>

</li>
<li><p><code>awayVoters</code>: a reference to a hash whose keys are the names of the players who auto-voted blank due to being away (see <a href="http://planetspads.free.fr/spads/doc/spadsDoc_Preferences.html#pset:voteMode">voteMode</a> preference)</p>

</li>
<li><p><code>manualVoters</code>: a reference to a hash whose keys are the names of the players who voted manually, and the values are the actual votes (<code>&quot;yes&quot;</code>, <code>&quot;no&quot;</code> or <code>&quot;blank&quot;</code>)</p>

</li>
</ul>

<p>Note: An easy way to check if a vote is currently in progress consists in calling <code>getCurrentVote()</code> and checking if the returned hash contains the <code>command</code> key. If the hash contains the <code>command</code> key then it means a vote is in progress, else it means no vote is in progress.</p>

</dd>
<dt id="getLobbyInterface"><code>getLobbyInterface()</code></dt>
<dd>

<p>This accessor returns the instance of the <a href="https://github.com/Yaribz/SpringLobbyInterface">SpringLobbyInterface</a> module used by SPADS.</p>

<p>Following methods, called on the <code>SpringLobbyInterface</code> object, can be useful to plugins for accessing various lobby data:</p>

<ul>

<li><p>- <code>getUsers()</code></p>

<p>This method returns a reference to a hash containing the data regarding all the online users. The hash is indexed by player names and the values are references to hashes with following content:</p>

<ul>

<li><p><code>accountId</code>: the lobby account ID of the user</p>

</li>
<li><p><code>country</code>: the country code of the user (2 characters)</p>

</li>
<li><p><code>ip</code>: the IP address of the user, if known (<code>undef</code> else)</p>

</li>
<li><p><code>lobbyClient</code>: the name of the lobby client software used by the user</p>

</li>
<li><p><code>status</code>: the lobby status of the user, which is itself a reference to another hash, containing following content: <code>access</code> (<code>0</code>: normal user, <code>1</code>: moderator), <code>away</code> (<code>0</code>: active, <code>1</code>: away), <code>bot</code> (<code>0</code>: human, <code>1</code>: bot), <code>inGame</code> (<code>0</code>: out of game, <code>1</code>: in game), <code>rank</code> (integer between 0 and 7 included)</p>

</li>
</ul>

<p>Note 1: this method performs a deep copy of the data to prevent external code from corrupting internal data. However it is also possible to read the same data directly without triggering a deep copy by accessing the <code>users</code> field of the <code>SpringLobbyInterface</code> object.</p>

<p>Note 2: if you need to retrieve users indexed by lobby account IDs instead of names, you can access the <code>accounts</code> field of the <code>SpringLobbyInterface</code> object. It contains a reference to a hash whose keys are the lobby account IDs and values are the lobby user names.</p>

</li>
<li><p>- <code>getChannels()</code></p>

<p>This method returns a reference to a hash containing the data regarding all the lobby channels joined by SPADS. The hash is indexed by channel names and the values are references to hashes with following content:</p>

<ul>

<li><p><code>topic</code>: a reference to a hash with following content: <code>author</code> (the name of the user who set the topic), <code>content</code> (the topic content)</p>

</li>
<li><p><code>users</code>: a reference to a hash whose keys are the names of the users in the lobby channel</p>

</li>
</ul>

<p>Note: this method performs a deep copy of the data to prevent external code from corrupting internal data. However it is also possible to read the same data directly without triggering a deep copy by accessing the <code>channels</code> field of the <code>SpringLobbyInterface</code> object.</p>

</li>
<li><p>- <code>getBattles()</code></p>

<p>This method returns a reference to a hash containing the data regarding all the battle lobbies currently hosted on the lobby server. The hash is indexed by battle ID and the values are references to hashes with following content:</p>

<ul>

<li><p><code>engineName</code>: the name of the engine used by the battle lobby (usually <code>&quot;spring&quot;</code>)</p>

</li>
<li><p><code>engineVersion</code>: the version of the engine used by the battle lobby (example: <code>&quot;105.0&quot;</code>)</p>

</li>
<li><p><code>founder</code>: the name of the user who created the battle lobby</p>

</li>
<li><p><code>ip</code>: the IP address used by the battle lobby for game hosting</p>

</li>
<li><p><code>locked</code>: the lock status of the battle lobby (<code>0</code>: unlocked, <code>1</code>: locked)</p>

</li>
<li><p><code>map</code>: the map currently selected in the battle lobby</p>

</li>
<li><p><code>mapHash</code>: the hash of the map currently selected in the battle lobby (computed by the unitsync library)</p>

</li>
<li><p><code>maxPlayers</code>: the battle lobby size (maximum number of players who can be in the battle lobby, ignoring spectators)</p>

</li>
<li><p><code>mod</code>: the mod (game name) used by the battle lobby</p>

</li>
<li><p><code>natType</code>: the type of NAT traversal method used by the host (<code>0</code>: none, <code>1</code>: hole punching, <code>2</code>: fixed source ports)</p>

</li>
<li><p><code>nbSpec</code>: the number of spectators currently in the battle lobby</p>

</li>
<li><p><code>passworded</code>: the password status of the battle lobby (<code>0</code>: not password protected, <code>1</code>: password protected)</p>

</li>
<li><p><code>port</code>: the port used by the battle lobby for game hosting</p>

</li>
<li><p><code>rank</code>: the minimum rank limit used by the battle lobby</p>

</li>
<li><p><code>title</code>: the description of the battle lobby</p>

</li>
<li><p><code>userList</code>: a reference to an array containing the names of the users currently in the battle lobby</p>

</li>
</ul>

<p>Note: this method performs a deep copy of the data to prevent external code from corrupting internal data. However it is also possible to read the same data directly without triggering a deep copy by accessing the <code>battles</code> field of the <code>SpringLobbyInterface</code> object.</p>

</li>
<li><p>- <code>getBattle()</code></p>

<p>This method returns a reference to a hash containing the data regarding the battle lobby currently hosted by SPADS. This hash has following content:</p>

<ul>

<li><p><code>battleId</code>: the battle ID of the battle lobby</p>

</li>
<li><p><code>botList</code>: a reference to an array containing the names of the AI bots currently in the battle lobby</p>

</li>
<li><p><code>bots</code>: a reference to a hash containing the data regarding the AI bots currently in the battle lobby. This hash is indexed by AI bot names and the values are references to hashes with following content: <code>aiDll</code> (details regarding the AI bot, usually the AI name and version, or the AI DLL), <code>battleStatus</code> (data representing the status of the AI bot in the battle lobby, see BATTLESTATUS hash description below), <code>color</code> (data specifying the team color of the AI bot using RGB model, see COLOR hash description below), <code>owner</code> (name of the user hosting the AI bot)</p>

</li>
<li><p><code>restrictedUnits</code>: a reference to a hash whose keys are the names of the game units currently restricted, and values are the corresponding unit limit.</p>

</li>
<li><p><code>modHash</code>: the hash of the mod (game) used by the battle lobby</p>

</li>
<li><p><code>password</code>: the password used to protect the battle lobby (<code>&quot;*&quot;</code> if no password is set)</p>

</li>
<li><p><code>scriptTags</code>: a reference to a hash containing all the script tags (in lower case) and their associated values (used to generate the start script)</p>

</li>
<li><p><code>startRects</code>: a reference to a hash containing the start box definitions. This hash is indexed by box numbers and the values are references to hashes containing the box coordinates (<code>top</code>, <code>left</code>, <code>bottom</code> and <code>right</code>) in the <code>0-200</code> range (<code>0,0</code> is the top left corner and <code>200,200</code> is the bottom right corner).</p>

</li>
<li><p><code>users</code>: a reference to a hash containing the data regarding the users currently in the battle lobby. This hash is indexed by user names and the values are references to hashes with following content: <code>battleStatus</code> (data representing the status of the player in the battle lobby, see BATTLESTATUS hash description below), <code>color</code> (data specifying the team color of the player using RGB model, see COLOR hash description below), <code>ip</code> (IP address of the user if known, <code>undef</code> else), <code>port</code> (client port of the user if known, <code>undef</code> else), and optionally <code>scriptPass</code> if the client provided a script password when joining the battle lobby.</p>

</li>
</ul>

<p>BATTLESTATUS hash description:</p>

<ul>

<li><p><code>bonus</code>: resource bonus value (integer in <code>0-100</code> range, <code>0</code> means no bonus)</p>

</li>
<li><p><code>id</code>: player team number (starting at <code>0</code>)</p>

</li>
<li><p><code>mode</code>: player/spectator mode (<code>0</code>: spectator, <code>1</code>: player)</p>

</li>
<li><p><code>ready</code>: ready state (<code>0</code>: not ready, <code>1</code>: ready)</p>

</li>
<li><p><code>side</code>: game faction number</p>

</li>
<li><p><code>sync</code>: synchronization status (<code>0</code>: unsynchronized, <code>1</code>: synchronized)</p>

</li>
<li><p><code>team</code> (ally team number, starting at <code>0</code>)</p>

</li>
</ul>

<p>COLOR hash description:</p>

<ul>

<li><p><code>red</code>: red component intensity (integer in <code>0-255</code> range)</p>

</li>
<li><p><code>green</code>: green component intensity (integer in <code>0-255</code> range)</p>

</li>
<li><p><code>blue</code>: blue component intensity (integer in <code>0-255</code> range)</p>

</li>
</ul>

<p>Note: this method performs a deep copy of the data to prevent external code from corrupting internal data. However it is also possible to read the same data directly without triggering a deep copy by accessing the <code>battle</code> field of the <code>SpringLobbyInterface</code> object.</p>

</li>
</ul>

</dd>
<dt id="getLobbyState"><code>getLobbyState()</code></dt>
<dd>

<p>This accessor returns an integer describing the current lobby state. The corresponding constants are provided to ease lobby state handling/comparisons, as listed below:</p>

<ul>

<li><p><code>0</code> - <code>LOBBY_STATE_DISCONNECTED</code> (disconnected from lobby server)</p>

</li>
<li><p><code>1</code> - <code>LOBBY_STATE_CONNECTING</code> (connecting to lobby server)</p>

</li>
<li><p><code>2</code> - <code>LOBBY_STATE_CONNECTED</code> (connected to lobby server but not logged in yet)</p>

</li>
<li><p><code>3</code> - <code>LOBBY_STATE_LOGGED_IN</code> (logged in but not synchronized yet)</p>

</li>
<li><p><code>4</code> - <code>LOBBY_STATE_SYNCHRONIZED</code> (synchronized, i.e all the commands describing the initial state of the lobby have been received from server)</p>

</li>
<li><p><code>5</code> - <code>LOBBY_STATE_OPENING_BATTLE</code> (opening battle)</p>

</li>
<li><p><code>6</code> - <code>LOBBY_STATE_BATTLE_OPENED</code> (battle opened)</p>

</li>
</ul>

<p>Perl plugins can use these constants directly in the plugin code, like this for example:</p>

<pre><code>if(getLobbyState() &gt;= LOBBY_STATE_CONNECTED) {
  slog(&quot;SPADS is connected to lobby server&quot;,3);
}</code></pre>

<p>Python plugins must call them as SPADS functions, like this for example:</p>

<pre><code>if spads.getLobbyState() &gt;= spads.LOBBY_STATE_CONNECTED():
    spads.slog(&quot;SPADS is connected to lobby server&quot;,3)</code></pre>

</dd>
<dt id="getPluginList"><code>getPluginList()</code></dt>
<dd>

<p>This accessor returns a reference to an array containing the names of the plugins currently loaded (in load order).</p>

</dd>
<dt id="getRunningBattle"><code>getRunningBattle()</code></dt>
<dd>

<p>This accessor returns a reference to a hash representing the state of the battle lobby hosted by SPADS when the game currently running was launched. This is useful to find the actual characteristics of the currently running game (battle structure, settings...), because things might have changed in the battle lobby since the game started (players joined/left, map changed...) so the current battle lobby data aren&#39;t necessarily consistent with the game currently running.</p>

<p>If no game is in progress, this hash is empty.</p>

<p>If a game is in progress, the hash contains the same data as the data returned by the <code>getBattle()</code> and <code>getBattles()</code> methods of the <code>SpringLobbyInterface</code> object (see <code>getLobbyInterface()</code> accessor) when the game was launched. Concerning the <code>getBattles()</code> data, only the data related to the battle lobby hosted by SPADS are included in the hash.</p>

</dd>
<dt id="getSpadsConf"><code>getSpadsConf()</code></dt>
<dd>

</dd>
<dt id="getSpadsConfFull"><code>getSpadsConfFull()</code></dt>
<dd>

</dd>
<dt id="getSpringInterface"><code>getSpringInterface()</code></dt>
<dd>

</dd>
<dt id="getSpringPid"><code>getSpringPid()</code></dt>
<dd>

</dd>
<dt id="getSpringServerType"><code>getSpringServerType()</code></dt>
<dd>

</dd>
<dt id="getTimestamps"><code>getTimestamps()</code></dt>
<dd>

</dd>
<dt id="getUserPref-userName-prefName"><code>getUserPref($userName,$prefName)</code></dt>
<dd>

<p>This accessor returns the current value of a user&#39;s preference.</p>

</dd>
</dl>

<h2 id="Plugin-management">Plugin management</h2>

<dl>

<dt id="getPlugin-pluginName-caller"><code>getPlugin($pluginName=caller())</code></dt>
<dd>

<p>This function returns the plugin object matching the plugin name given as parameter <code>$pluginName</code>. If no parameter is provided, the plugin name of the plugin calling the function is used.</p>

</dd>
<dt id="getPluginConf-pluginName-caller"><code>getPluginConf($pluginName=caller())</code></dt>
<dd>

<p>This function returns the plugin configuration for the plugin named <code>$pluginName</code>. If no parameter is provided, the plugin name of the plugin calling the function is used. The return value is a reference to a hash using plugin settings names as keys and plugin settings values as values.</p>

</dd>
</dl>

<h2 id="Handlers-management">Handlers management</h2>

<dl>

<dt id="addLobbyCommandHandler-handlers-priority-caller-isPreCallback"><code>addLobbyCommandHandler(\%handlers,$priority=caller(),$isPreCallback)</code></dt>
<dd>

<p>This function allows plugins to set up their own handlers for Spring lobby commands received by SPADS from lobby server.</p>

<p><code>\%handlers</code> is a reference to a hash which contains the handlers to be added: each entry associates a lobby command (in uppercase) to a handler function implemented by the plugin. For example, with <code>{ JOINBATTLEREQUEST =&gt; \&amp;hLobbyJoinBattleRequest }</code>, the plugin has to implement the function <code>hLobbyJoinBattleRequest</code>. The parameters passed to the handlers are the command tokens: the command name followed by command parameters. Refer to <a href="http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html">Spring lobby protocol specifications</a> for more information.</p>

<p><code>$priority</code> is the priority of the handlers. Lowest priority number actually means higher priority. If not provided, the plugin name is used as priority, which means it is executed after handlers having priority &lt; 1000, and before handlers having priority &gt; 1000. Usually you don&#39;t need to provide priority, unless you use data managed by other handlers.</p>

<p><code>$isPreCallback</code> specifies whether the command handlers must be called before or after the lobby interface module handlers. If this parameter is set to a true value, the command handlers will be called before the lobby interface module handlers. If this parameter is not provided or set to a false value, the command handlers will be called after the lobby interface module handlers.</p>

<p>Note: As all lobby command handlers are automatically removed by SPADS when it is disconnected from the lobby server (due to network problems for example), plugins should always re-set up their lobby command handlers each time SPADS successfully reconnects. This can be done automatically by doing the <code>addLobbyCommandHandler</code> call in the <code>onLobbySynchronized</code> event-based callback (for plugins that don&#39;t need to process the commands sent by the lobby server during the initial lobby state synchronization phase) or in the <code>onLobbyLoggedIn</code> event-based callback (for plugins that need to process the commands sent by the lobby server during the initial lobby state synchronization phase).</p>

</dd>
<dt id="addSpadsCommandHandler-handlers-replace-0"><code>addSpadsCommandHandler(\%handlers,$replace=0)</code></dt>
<dd>

<p>This function allows plugins to add or replace SPADS command handlers.</p>

<p><code>\%handlers</code> is a reference to a hash which contains the handlers to be added or replaced: each entry associates a SPADS command to a handler function implemented by the plugin. For example, with <code>{ myCommand =&gt; \&amp;hSpadsMyCommand }</code>, the plugin has to implement the function <code>hSpadsMyCommand</code>. The parameters passed to the handlers are: <code>$source</code>,<code>$userName</code>,<code>\@params</code>,<code>$checkOnly</code>.</p>

<p><code>$source</code> indicates the way the command has been called (<code>&quot;pv&quot;</code>: private lobby message, <code>&quot;battle&quot;</code>: battle lobby message, <code>&quot;chan&quot;</code>: master lobby channel message, <code>&quot;game&quot;</code>: in game message)</p>

<p><code>$userName</code> is the name of the user issuing the command</p>

<p><code>\@params</code> is a reference to an array containing the command parameters</p>

<p><code>$checkOnly</code> indicates that the command must not be executed but only checked for consistency (this mode is used for !callVote command)</p>

<p>If the command cannot be executed (invalid syntax ...) the handler must return <code>0</code>. If the command is correct but requires automatic parameter adjustments (automatic case correction or name completion for example), a string containing the adjusted command must be returned. If it can be executed directly without any adjustement, <code>1</code> must be returned.</p>

<p><code>$replace</code> indicates if the handlers provided can replace existing ones: <code>0</code> means add handlers only if there is no handler for the given command (default), <code>1</code> means add or replace if existing.</p>

</dd>
<dt id="addSpringCommandHandler-handlers-priority-caller"><code>addSpringCommandHandler(\%handlers,$priority=caller())</code></dt>
<dd>

<p>This function allows plugins to set up their own handlers for Spring AutoHost commands received by SPADS from Spring server.</p>

<p><code>\%handlers</code> is a reference to a hash which contains the handlers to be added: each entry associates a Spring AutoHost command to a handler function implemented by the plugin. The Spring AutoHost command names must match the values of <code>%commandCodes</code> defined in SpringAutoHostInterface.pm. For example, with <code>{ SERVER_STARTED =&gt; \&amp;hSpringServerStarted }</code>, the plugin has to implement the function <code>hSpringServerStarted</code>. The parameters passed to the handlers are the command tokens: the command name followed by command parameters. Refer to <a href="https://raw.github.com/spring/spring/master/rts/Net/AutohostInterface.cpp">Spring autohost protocol specifications (from source comments)</a> for more information.</p>

<p><code>$priority</code> is the priority of the handlers. Lowest priority number actually means higher priority. If not provided, the plugin name is used as priority, which means it is executed after handlers having priority &lt; 1000, and before handlers having priority &gt; 1000. Usually you don&#39;t need to provide priority, unless you use data managed by other handlers.</p>

</dd>
<dt id="removeLobbyCommandHandler-commands-priority-caller-isPreCallback"><code>removeLobbyCommandHandler(\@commands,$priority=caller(),$isPreCallback)</code></dt>
<dd>

<p>This function must be called by plugins which added lobby command handlers previously using <code>addLobbyCommandHandler</code> function, when these handlers are no longer required (for example in the <code>onUnload</code> callback, when the plugin is unloaded).</p>

<p><code>\@commands</code> is a reference to an array containing the lobby command names (in uppercase) for which the handlers must be removed.</p>

<p><code>$priority</code> is the priority of the handlers to remove. It must be the same as the priority used when adding the handlers. If not provided, the plugin name is used as priority. Usually you don&#39;t need to provide priority, unless you use data managed by other handlers.</p>

<p><code>$isPreCallback</code> specifies the type of command handlers to remove (must match the value used for the <code>addLobbyCommandHandler</code> function call for these handlers)</p>

</dd>
<dt id="removeSpadsCommandHandler-commands"><code>removeSpadsCommandHandler(\@commands)</code></dt>
<dd>

<p>This function must be called by plugins which added SPADS command handlers previously using <code>addSpadsCommandHandler</code> function, when these handlers are no longer required (for example in the <code>onUnload</code> callback, when the plugin is unloaded).</p>

<p><code>\@commands</code> is a reference to an array containing the SPADS command names (in uppercase) for which the handlers must be removed.</p>

</dd>
<dt id="removeSpringCommandHandler-commands-priority-caller"><code>removeSpringCommandHandler(\@commands,$priority=caller())</code></dt>
<dd>

<p>This function must be called by plugins which added Spring AutoHost command handlers previously using <code>addSpringCommandHandler</code> function, when these handlers are no longer required (for example in the <code>onUnload</code> callback, when the plugin is unloaded).</p>

<p><code>\@commands</code> is a reference to an array containing the Spring AutoHost command names for which the handlers must be removed.</p>

<p><code>$priority</code> is the priority of the handlers to remove. It must be the same as the priority used when adding the handlers. If not provided, the plugin name is used as priority. Usually you don&#39;t need to provide priority, unless you use data managed by other handlers.</p>

</dd>
</dl>

<h2 id="SPADS-operations">SPADS operations</h2>

<dl>

<dt id="applyPreset-presetName"><code>applyPreset($presetName)</code></dt>
<dd>

</dd>
<dt id="cancelCloseBattle"><code>cancelCloseBattle()</code></dt>
<dd>

</dd>
<dt id="cancelQuit-reason"><code>cancelQuit($reason)</code></dt>
<dd>

</dd>
<dt id="closeBattle-reason-silentMode-0"><code>closeBattle($reason,$silentMode=0)</code></dt>
<dd>

<p>This function makes SPADS close current battle lobby.</p>

<p>The <code>$reason</code> parameter must be a string containing the reason for closing the battle lobby.</p>

<p>The <code>$silentMode</code> parameter is an optional boolean parameter specifying if the broadcast message (which is normally sent when the battle lobby is closed) must be prevented.</p>

</dd>
<dt id="getUserAccessLevel-user"><code>getUserAccessLevel($user)</code></dt>
<dd>

</dd>
<dt id="loadArchives"><code>loadArchives()</code></dt>
<dd>

</dd>
<dt id="queueLobbyCommand-lobbyCommand"><code>queueLobbyCommand(\@lobbyCommand)</code></dt>
<dd>

</dd>
<dt id="quit-type-reason-exitCode-0"><code>quit($type,$reason,$exitCode=0)</code></dt>
<dd>

</dd>
<dt id="rehost-reason"><code>rehost($reason)</code></dt>
<dd>

</dd>
<dt id="slog-message-level"><code>slog($message,$level)</code></dt>
<dd>

<p>This function uses SPADS logging system to write a message in main SPADS log file.</p>

<p><code>$message</code> is the log message</p>

<p><code>$level</code> is the log level of the message: <code>0</code> (critical), <code>1</code> (error), <code>2</code> (warning), <code>3</code> (notice), <code>4</code> (info), <code>5</code> (debug)</p>

</dd>
<dt id="updateSetting-type-name-value"><code>updateSetting($type,$name,$value)</code></dt>
<dd>

<p>This function updates current SPADS configuration in memory by changing the value of a setting and applying it immediatly. This function does not modify configuration files on disk. The new value provided by the plugin is not checked: the plugin is reponsible for providing only correct values.</p>

<p><code>$type</code> is the type of setting to update (<code>&quot;set&quot;</code> for preset setting, <code>&quot;hSet&quot;</code> for hosting setting, or <code>&quot;bSet&quot;</code> for battle setting)</p>

<p><code>$name</code> is the name of the setting to update</p>

<p><code>$value</code> is the new value of the setting</p>

</dd>
</dl>

<h2 id="AutoHost-messaging-system">AutoHost messaging system</h2>

<dl>

<dt id="answer-message"><code>answer($message)</code></dt>
<dd>

<p>This function must only be called from a SPADS command handler. It sends a message to the user who issued the command, using the same communication channel that has been used to send the command to SPADS: a private message, a message in battle lobby, a message in game or a message in a lobby chat channel.</p>

</dd>
<dt id="broadcastMsg-message"><code>broadcastMsg($message)</code></dt>
<dd>

<p>This function sends a message simultaneously in the battle lobby (if open), in the game (if running) and in the broadcast channels (as configured by the <code>broadcastChannels</code> global setting).</p>

</dd>
<dt id="invalidSyntax-user-commandName-cause"><code>invalidSyntax($user,$commandName,$cause=&#39;&#39;)</code></dt>
<dd>

<p>This function must only be called from a SPADS command handler. It triggers the default SPADS behavior when a user calls a command using invalid syntax, as detailed below:</p>

<p>It answers to the user (using the same communication channel as the one used to call the command) with a message indicating that the command usage is invalid. This message includes a detailed reason if provided as <code>$cause</code> parameter. If the user is not in game, it also automatically sends the corresponding command help in a private message.</p>

<p><code>$user</code> is the user who called the SPADS command</p>

<p><code>$commandName</code> is the name of the SPADS command which was called with invalid syntax</p>

<p><code>$cause</code> is the detailed reason explaining why the command usage is invalid (optional)</p>

</dd>
<dt id="sayBattle-message"><code>sayBattle($message)</code></dt>
<dd>

<p>This functions sends a message in the battle lobby (if open).</p>

</dd>
<dt id="sayBattleAndGame-message"><code>sayBattleAndGame($message)</code></dt>
<dd>

<p>This function sends a message simultaneously in the battle lobby (if open) and in the game (if running).</p>

</dd>
<dt id="sayBattleUser-user-message"><code>sayBattleUser($user,$message)</code></dt>
<dd>

<p>This function sends a message in the battle lobby (if open) to a specific user: only this user will receive the message, but for this user the message will appear in the battle lobby instead of being a private chat message.</p>

</dd>
<dt id="sayChan-channel-message"><code>sayChan($channel,$message)</code></dt>
<dd>

<p>This functions sends a message in a specific lobby chat channel (if already joined by SPADS).</p>

</dd>
<dt id="sayGame-message"><code>sayGame($message)</code></dt>
<dd>

<p>This functions sends a message in the game (if running).</p>

</dd>
<dt id="sayPrivate-user-message"><code>sayPrivate($user,$message)</code></dt>
<dd>

<p>This function sends a private message to a user.</p>

</dd>
</dl>

<h2 id="Time-utils">Time utils</h2>

<dl>

<dt id="getDirModifTime-directory"><code>getDirModifTime($directory)</code></dt>
<dd>

</dd>
<dt id="secToDayAge-seconds"><code>secToDayAge($seconds)</code></dt>
<dd>

</dd>
<dt id="secToTime-seconds"><code>secToTime($seconds)</code></dt>
<dd>

</dd>
</dl>

<h2 id="Data-formatting">Data formatting</h2>

<dl>

<dt id="formatArray"><code>formatArray</code></dt>
<dd>

</dd>
<dt id="formatFloat-float"><code>formatFloat($float)</code></dt>
<dd>

</dd>
<dt id="formatInteger-integer"><code>formatInteger($integer)</code></dt>
<dd>

</dd>
<dt id="formatList"><code>formatList</code></dt>
<dd>

</dd>
</dl>

<h2 id="Forking-processes">Forking processes</h2>

<dl>

<dt id="createDetachedProcess-applicationPath-commandParams-workingDirectory-createNewConsole"><code>createDetachedProcess($applicationPath,\@commandParams,$workingDirectory,$createNewConsole)</code></dt>
<dd>

<p>This function allows plugins to create a new detached/daemon process, which can keep running even if the main SPADS process exits. It returns <code>1</code> if the new process has correctly been created, <code>0</code> else.</p>

<p><code>$applicationPath</code> is the absolute path of the application that will be executed in the detached process.</p>

<p><code>\@commandParams</code> is a reference to an array containing the parameters passed to the application.</p>

<p><code>$workingDirectory</code> is the working directory for the detached process.</p>

<p><code>$createNewConsole</code> indicates if a console must be created for the detached process: <code>0</code> means no console is created for the process (daemon mode) <code>1</code> means a new console will be created for the detached process (this mode is only available on Windows system)</p>

</dd>
<dt id="forkProcess-processFunction-endProcessCallback-preventQueuing-1"><code>forkProcess(\&amp;processFunction,\&amp;endProcessCallback,$preventQueuing=1)</code></dt>
<dd>

<p>This function allows plugins to fork a process from main SPADS process, for parallel processing. In scalar context it returns the PID of the forked process on success, <code>-1</code> if the fork request has been queued, or <code>0</code> if the fork request failed. In list context it returns the PID as first parameter and a handle as second parameter. This handle can be passed as parameter to the <code>removeProcessCallback</code> function to remove the <code>endProcessCallback</code> callback.</p>

<p>Note: this function cannot be used by Python plugins on Windows system (refer to section <a href="#Windows-limitations">PYTHON SPECIFIC NOTES - Windows limitations</a> for details).</p>

<p><code>\&amp;processFunction</code> is a reference to a function containing the code to be executed in the forked process (no parameter is passed to this function). This function can call <code>exit</code> to end the forked process with a specific exit code. If it returns without calling exit, then the exit code <code>0</code> will be used.</p>

<p><code>\&amp;endProcessCallback</code> is a reference to a function containing the code to be executed in main SPADS process, once the forked process exited. Following parameters are passed to this function: <code>$exitCode</code> (exit code of the forked process), <code>$signalNb</code> (signal number responsible for forked process termination if any), <code>$hasCoreDump</code> (boolean flag indicating if a core dump occured in the forked process), <code>$pid</code> (PID of the forked process that just exited).</p>

<p><code>$preventQueuing</code> is an optional boolean parameter (default value: 1) indicating if the fork request must not be queued (i.e., the fork request will fail instead of being queued if too many forked processes are already running)</p>

</dd>
<dt id="forkCall-processFunction-endProcessCallback-preventQueuing-0"><code>forkCall(\&amp;processFunction,\&amp;endProcessCallback,$preventQueuing=0)</code></dt>
<dd>

<p>This function allows plugins to call a function asynchronously and retrieve the data returned by this function (this is done internally by forking a process to execute the function and use a socketpair to transmit the result back to the parent process). In scalar context it returns the PID of the forked process on success, <code>-1</code> if the fork request has been queued, or <code>0</code> on error. In list context it returns the PID as first parameter and a handle as second parameter. This handle can be passed as parameter to the <code>removeProcessCallback</code> function to remove the <code>endProcessCallback</code> callback.</p>

<p>Note: this function cannot be used by Python plugins on Windows system (refer to section <a href="#Windows-limitations">PYTHON SPECIFIC NOTES - Windows limitations</a> for details).</p>

<p><code>\&amp;processFunction</code> is a reference to a function containing the code to be executed in the forked process (no parameter is passed to this function). This function must not call <code>exit</code>, it should use <code>return</code> instead to return values (scalars, arrays, hashes...) that will be passed to the callback.</p>

<p><code>\&amp;endProcessCallback</code> is a reference to a function containing the code to be executed in main SPADS process, once the forked function call (<code>\&amp;processFunction</code>) returned. The values returned by the forked function call will be passed as parameters to this callback.</p>

<p><code>$preventQueuing</code> is an optional boolean parameter (default value: 0) indicating if the fork request must not be queued (i.e., the fork request will fail instead of being queued if too many forked processes are already running)</p>

</dd>
<dt id="removeProcessCallback-processHandle"><code>removeProcessCallback($processHandle)</code></dt>
<dd>

<p>This function can be used by plugins to remove the callbacks on forked processes added beforehand with the <code>forkProcess</code> and <code>forkCall</code> functions, if the callback hasn&#39;t been called yet (i.e. the corresponding forked process didn&#39;t exit yet). It returns <code>1</code> if the callback could be removed, <code>0</code> else.</p>

<p><code>$processHandle</code> is an internal process handle, returned as second return value by the <code>forkProcess</code> and <code>forkCall</code> functions.</p>

</dd>
</dl>

<h2 id="Timers-management">Timers management</h2>

<dl>

<dt id="addTimer-name-delay-interval-callback"><code>addTimer($name,$delay,$interval,\&amp;callback)</code></dt>
<dd>

<p>This function allows plugins to add timed events (timers) in order to delay and/or repeat code execution. It returns <code>1</code> if the timer has correctly been added, <code>0</code> else.</p>

<p><code>$name</code> is a unique name given by the plugin for this timer.</p>

<p><code>$delay</code> is the delay in seconds before executing the <code>\&amp;callback</code> function.</p>

<p><code>$interval</code> is the interval in seconds between each execution of the <code>\&amp;callback</code> function. If this value is set to 0, the <code>\&amp;callback</code> function will be executed only once.</p>

<p><code>\&amp;callback</code> is a reference to a function containing the code to be executed when the timed event occurs. This callback must not be blocking, otherwise SPADS may become unstable.</p>

</dd>
<dt id="removeTimer-name"><code>removeTimer($name)</code></dt>
<dd>

<p>This function must be used by plugins to remove timed events (timers) added previously with the <code>addTimer</code> function. It returns <code>1</code> if the timer could be removed, <code>0</code> else. Note: Non-repeating timers (i.e. having null interval value) are automatically removed once they are triggered.</p>

<p><code>$name</code> is the unique timer name given by the plugin when the timer was added using the <code>addTimer</code> function.</p>

</dd>
</dl>

<h2 id="Sockets-management">Sockets management</h2>

<dl>

<dt id="addSocket-socketObject-readCallback"><code>addSocket(\$socketObject,\&amp;readCallback)</code></dt>
<dd>

<p>This function allows plugins to add sockets to SPADS asynchronous network system. It returns <code>1</code> if the socket has correctly been added, <code>0</code> else.</p>

<p>Note: this function cannot be used by Python plugins on Windows system (refer to section <a href="#Windows-limitations">PYTHON SPECIFIC NOTES - Windows limitations</a> for details).</p>

<p><code>\$socketObject</code> is a reference to a socket object created by the plugin</p>

<p><code>\&amp;readCallback</code> is a reference to a plugin function containing the code to read the data received on the socket. This function will be called automatically every time data are received on the socket, with the socket object as unique parameter. It must not block, and only unbuffered functions must be used to read data from the socket (<code>sysread()</code> or <code>recv()</code> for example).</p>

</dd>
<dt id="removeSocket-socketObject"><code>removeSocket(\$socketObject)</code></dt>
<dd>

<p>This function allows plugins to remove sockets from SPADS asynchronous network system. It returns <code>1</code> if the socket has correctly been removed, <code>0</code> else.</p>

<p><code>\$socketObject</code> is a reference to a socket object previously added by the plugin</p>

</dd>
</dl>

<h2 id="Python-specific">Python specific</h2>

<dl>

<dt id="fix_string-spads_string"><code>fix_string(spads_string[,...])</code></dt>
<dd>

<p>This function allows Python plugins to automatically convert byte strings to normal strings if needed. The function takes any number of byte strings or normal strings as parameters, and returns them converted to normal strings if needed (parameters which are already normal strings are returned without any modification). Refer to section <a href="#Perl-strings-conversions">PYTHON SPECIFIC NOTES - Perl strings conversions</a> for the use case of this function. Here is an example of usage:</p>

<pre><code> import perl
 spads=perl.ExamplePlugin
 
 [...]
 
 class ExamplePlugin:

 [...]
 
     def onPrivateMsg(self,userName,message):
         (userName,message)=spads.fix_string(userName,message)

 [...]
 
 def hMyCommand(source,user,params,checkOnly):
     user=spads.fix_string(user)
     for i in range(len(params)):
         params[i]=spads.fix_string(params[i])</code></pre>

</dd>
<dt id="get_flag-flag_name"><code>get_flag(flag_name)</code></dt>
<dd>

<p>This function allows Python plugins to retrieve indicators (boolean flags) regarding the behavior of the plugin API and the availability of functionalities on current system.</p>

<p>Currently 3 flags are supported:</p>

<ul>

<li><p><code>can_add_socket</code> : indicates if the <code>addSocket</code> function of the plugin API is available from Python plugin on this system</p>

</li>
<li><p><code>can_fork</code> : indicates if the fork functions of the plugin API (<code>forkProcess</code> and <code>forkCall</code>) are available from Python plugins on this system</p>

</li>
<li><p><code>use_byte_string</code> : indicates if the strings passed as parameters to Python plugin callbacks on this system are Python byte strings or normal Python strings</p>

</li>
</ul>

<p>Here is an example of usage:</p>

<pre><code> import perl
 spads=perl.ExamplePlugin
 
 [...]
 
     if spads.get_flag(&#39;can_add_socket&#39;):
         spads.addSocket(socket,readSocketCallback)
     else:
         spads.slog(&quot;This plugin requires the addSocket function&quot;,1)
         return False</code></pre>

</dd>
</dl>

<h1 id="SHARED-DATA">SHARED DATA</h1>

<h2 id="Constants">Constants</h2>

<p>Following constants are directly accessible from Perl plugin modules (accessible via <code>perl.eval(&#39;$::SpadsPluginApi::...&#39;)</code> from Python plugin modules):</p>

<dl>

<dt id="spadsVersion"><code>$spadsVersion</code></dt>
<dd>

</dd>
<dt id="spadsDir"><code>$spadsDir</code></dt>
<dd>

</dd>
</dl>

<h2 id="Variables">Variables</h2>

<p>Following variables are directly accessible from Perl plugin modules (accessible via <code>perl.eval(&#39;...&#39;)</code> from Python plugin modules), but it is strongly recommended to use the accessors from the API instead:</p>

<dl>

<dt id="autohost"><code>$::autohost</code></dt>
<dd>

</dd>
<dt id="conf"><code>%::conf</code></dt>
<dd>

</dd>
<dt id="confMacros"><code>%::confMacros</code></dt>
<dd>

</dd>
<dt id="currentVote"><code>%::currentVote</code></dt>
<dd>

</dd>
<dt id="lobby"><code>$::lobby</code></dt>
<dd>

</dd>
<dt id="lobbyState"><code>$::lobbyState</code></dt>
<dd>

</dd>
<dt id="p_runningBattle"><code>$::p_runningBattle</code></dt>
<dd>

</dd>
<dt id="plugins"><code>%::plugins</code></dt>
<dd>

</dd>
<dt id="pluginsOrder"><code>@::pluginsOrder</code></dt>
<dd>

</dd>
<dt id="spads"><code>$::spads</code></dt>
<dd>

</dd>
<dt id="spadsCmdHandlers"><code>%::spadsCmdHandlers</code></dt>
<dd>

</dd>
<dt id="springPid"><code>$::springPid</code></dt>
<dd>

</dd>
<dt id="springServerType"><code>$::springServerType</code></dt>
<dd>

</dd>
<dt id="timestamps"><code>%::timestamps</code></dt>
<dd>

</dd>
<dt id="bosses"><code>%::bosses</code></dt>
<dd>

</dd>
</dl>

<h1 id="SEE-ALSO">SEE ALSO</h1>

<p><a href="http://springrts.com/wiki/SPADS_plugin_development">SPADS plugin development tutorials (Perl)</a></p>

<p><a href="http://springrts.com/wiki/SPADS_plugin_development_(Python)">SPADS plugin development tutorials (Python)</a></p>

<p>Commented SPADS plugin templates (Perl): <a href="http://planetspads.free.fr/spads/plugins/templates/commented/MySimplePlugin.pm">Simple plugin</a>, <a href="http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm">Configurable plugin</a>, <a href="http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm">New command plugin</a></p>

<p>Commented SPADS plugin templates (Python): <a href="http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py">Simple plugin</a>, <a href="http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py">Configurable plugin</a>, <a href="http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandPlugin.py">New command plugin</a></p>

<p><a href="http://planetspads.free.fr/spads/doc/spadsDoc.html">SPADS documentation</a>, especially regarding plugins management: <a href="http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir">pluginsDir setting</a>, <a href="http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:autoLoadPlugins">autoLoadPlugins setting</a>, <a href="http://planetspads.free.fr/spads/doc/spadsDoc_All.html#command:plugin">plugin command</a></p>

<p><a href="http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html">Spring lobby protocol specifications</a></p>

<p><a href="https://raw.github.com/spring/spring/master/rts/Net/AutohostInterface.cpp">Spring autohost protocol specifications (from source comments)</a></p>

<p><a href="http://perldoc.perl.org/perlintro.html">Introduction to Perl</a></p>

<p>Inline::Python Perl module (the bridge between Perl and Python): <a href="https://metacpan.org/pod/Inline::Python">documentation from meta::cpan</a>, <a href="https://github.com/niner/inline-python-pm">GitHub repository</a></p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>Copyright (C) 2013-2024 Yann Riou &lt;yaribzh@gmail.com&gt;</p>

<p>This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.</p>


<script>
  anchors.options.placement = 'left';
  anchors.add('h1,h2,dt');
</script>
</body>

</html>