Authoring XA Modules

Overview

This article discusses all of the things you need to do in order to develop a module for Extensible Admin.

Name and location for you XA module

Your module and all it's data files are stored inside the following folder: addons/eventscripts/xa/modules/yourmodule/

Your main Python file in this case would be: yourmodule.py

Starting to code an XA module

To make use of xa you need to import the main library (which is unsurprisingly named xa!).

from xa import xa

Registering your module with XA

The first thing you need to do in the module load section is to register your module with XA. The xa.register(<name>) method returns a class providing access to XA functionality for use in the module. The class instance is also a required argument for some addition XA libraries / methods (notably the xa.setting library).

# The register module allows you to connect yourself to the XA API
xa.register(<name>)

• name - the name of your module (used by XA as an identifier)

Unregistering a module is done via xa.unregister(<name>), alternatively you can call unregister on your XA module instance (e.g. <my module>.unregister()). Example:

from xa import xa
 
def load():
    global test
    # Register the module
    test = xa.register("test") 
 
def unload():
    # Unregister the module
    test.unregister()

Note that for now you should always use the base name of the module when registering it - due to the way XA tracks addons. In the future this may not be necessary but is probably recommended

Settings and Server Variables

Any configuration variables needed in your script should be set via the xa.setting library. This creates server Cvars for your variables, handles Mani compatibility (see section below) and provides an interface for admins to edit these settings. The library interface is simple to use. The first time a module is loaded XA creates and stores the variables it creates, these can be edited by admins via menu's (this functionality is provided by a separate module) or in the server console. If the module is loaded again XA simply restores the previous settings from file.

• Note: xa.setting creates proper Valve cvars (with the format xa_<my var name>) - this allows admins to change settings via the console! You can interact with the cvar as normal (with server_var[<name>]).

xa.setting methods

xa.setting provides the following methods:

 # Server Variables
 # Note: All those methods automatically add the 'xa_' or 'mani_' prefixes!
 # Create a variable (returns the es.ServerVar instance of the variable)
 myvar = mymodule.setting.createVariable(<var name>, <default value>, <optional:description>) 
 # Returns the es.ServerVar instance of the variable as stored by XA
 myvar = mymodule.setting.getVariable(<var name>)
 # Deletes the named variable from the module and sets it's es.ServerVar instance to 0
 mymodule.setting.deleteVariable(<var name>)

 # KeyValues
 # Create a KeyValues object inside the XA data
 myvar = mymodule.setting.createKeyValues()
 # Returns the created KeyValues object as stored by XA
 myvar = mymodule.setting.useKeyValues()
 # Saves XA's data file with all the KeyValues objects of the modules
 xa.setting.deleteVariable()

• var name - The name of your variable / setting
• default value - Provide a default value for your setting, if it has not been created before xa.setting will use this as the starting value
• Optional: description - Try and provide a description of the variable you are creating (it will help people if they wish to change the values later)

Example usage

import es
from xa import xa
        
def load():
    global mymodule
    # Register the module
    mymodule = xa.register("test") 
    # Create the variable
    myvar = mymodule.setting.createVariable('test_var', '1', "A test variable!") 
 
def player_death(event_var)
    # Check the setting is greater than 0 (On
    if mymodule.setting.getVariable('test_var') != "0":
        es.tell(event_var["userid"], "Hello World!")

• Note: - Always do a string comparison on getVariable() - trying to compare it to an integer (for example) could crash the module. Try and check specifically for the value(s) you expected.

Displaying in the Admin Menu

This section is still incomplete or needs rewriting

This snippet from the xaplayers.py (Player Management) shows how to display a menu inside XA's main menu:

def load():
    #Load Function for Player Settings for XA.
    xaplayermenu = popuplib.easymenu("xaplayermenu", "_tempcore", _select_option)
    xaplayermenu.settitle(xalanguage["choose option"])
    xaplayers.addMenu("xaplayermenu", xalanguage["manage players"], "xaplayermenu", "punish_player", "#admin")

• Note: The second parameter of addMenu must be a langlib object, not a string.

Say and Console Commands

This section is still incomplete or needs rewriting

This snippet from the xasettings.py (Player Settings) shows how to register Say and Console commands with XA:

def load():
    #Load Function for Player Settings for XA.    
    xasettingmenu = popuplib.easymenu("xasettingmenu", "_tempcore", _select_setting)
    xasettingmenu.settitle(xalanguage["player settings"])
    xacommand = xasettings.addCommand("settings", _send_menu, "change_playersetting", "#all")
    xacommand.register(["console","say"])

Mani Compatibility

This section is still incomplete or needs rewriting

XA fully supports compatibility with the mani_server.cfg configuration file, the intention with XA is to provide Mani users with an easy upgrade option that can use their current setup and options. Mani cvar compatibility is managed via the xa.setting library (via a separate manilib library) and can be turned on and off at will by the server admin. If you wish to make your module backwards compatible with Mani then you must name your server variables appropriately, variables are created in the normal way (see above) but xa.settings is clever enough to use Mani substitutes if Mani mode is on.

• Note: You do not need to import manilib.py to use Mani compatibility. The xa.setting lib does this automatically

To use Mani vars you must name your variables the same as the Mani equivalent you wish to use without the "mani_" prefix; eg: "blind_ghosters" NOT "mani_blind_ghosters".

Try this example; shortened from the IP Ghosting module it checks a specific Mani var when a player dies.

import es
from xa import xa
 
ghosting = xa.register('xaipghosting')
 
def load():
    # Create the variable you want to use (in this case we are wanting to use mani_blind_ghosters)
    # Note how the variable is set up EAXACTLY in the normal way - only the naming is important
    ghosting.setting.createVariable('blind_ghosters', '1', "XA: Blind IP Ghosters when they die (1=On, 0=Off)") 
 
def player_death(event_var):
    '''
    Checks for the variable and if set fails to blind you :P .... 
    '''
    if ghosting.setting.getVariable('blind_ghosters') != "0":
        es.tell(event_var["userid"], "If you were a ghoster we could blind you now!")

You can use this method for ANY of the variables in the cfg/mani_server.cfg file.

In terms of admins XA supports the clients.txt file via a special Auth provider when Mani compatibility is turned on.

This section needs some info about using the Auth provider.. if there is anything specific that needs to be done!

Logging

The library xa.logging provides log capabilities for your modules. the log() method saves the text into a file in your XA logs folder (xa/logs/l<day><month>000.log). It does also forward the text to the server logs.

Example:

from xa import xa
 
test = xa.register("test")
test.logging.log("Testing the log capabilities")
 
def player_jump(event_var):
    test.logging.log("The player jumped!", int(event_var['userid']))

Examples

• XA Module Example: My First Module

See Also

• Creating a New Player Punishment
• Authorization Provider
• XA Modules
• eXtensible Admin