Getting Started: Base MAM Framework

[Hammer]

The base MoH_AdminMod (MAM) framework is made up of three components: 1) mod registration/launcher module, 2) command processing module, and 3) helper utilities module. This thread is intended for both server administrators and mod developers. It should help server admins better understand how MAM integrates and launches other mods, as well as basic command processing operation. Mod developers should gain a good understanding on how to develop add-on mods using MAM's built-in helper functions and interfacing new commands with MAM.

Before diving into the details surrounding these components, I should mention that MAM contains extensive debugging capabilities. Debugging is controlled by the mam_debug cvar, which by default is set to zero in MoH_AdminMod.cfg, the main MAM configuration file. Values greater than zero cause debugging output to be sent to the game server's console or log file (note: you must have the developer cvar set to a non-zero value, otherwise no debug output will be seen). The larger the value in mam_debug, the more detailed output is produced. Almost all MAM debugging lines are prefixed using ---- MAM(<session>, <time>):, where <session> indicates the number of times MAM has run since the server started and <time> is the number of seconds since the current level began. NOTE: This feature should only be used when troubleshooting a problem or new-mod development. Enabling debugging may cause severe performance problems during gameplay, i.e. LAG.

The current version of MAM is found in the mam_running cvar (which also indicates that the mod is active), while the session number is in mam_session.

Now on to the module descriptions ...

--[MC] Hammer

[Hammer]

One of MAM's strongest features is that it provides the ability to register add-on packages, or mods, without requiring extensive knowledge on the inner workings of the mods themselves. A package (mod) is a collection of one or more files used to provide a common function or set of functions, i.e. modification to the game. To register a package with MAM, simply add the following line to the server's startup configuration:

[code:1]append mam_register_mod "<package_file_name.scr>"[/code:1]
where <package_file_name.scr> is the name of the main file that initializes the mod you wish to register, e.g. "global/Hammer_Goodies.scr". You can register as many packages as you require, each will be executed by MAM's main startup process in the order established in the mam_register_mod cvar.

MAM uses the DMprecache.scr hack method to integrate itself with MoH:AA. Several other mods exist using this same method, unfortunately none of them allow for integration with other mods, creating huge problems for game administrators. MAM's registration facility allows mods of this type to work independently of other mods, without requiring that admins hack a mod to make it work. As of version 1.1, MAM also uses a hack on ambient.scr to guarantee mod startup through-out many maps and all versions of MoH:AA

In technical terms, at the start of each map (level) MAM scans mam_register_mod and performs a script-level exec on each entry found. Duplicate entries in mam_register_mod are silenty dropped, guaranteeing that a mod's startup file is only called once at the start of each level. MAM's launching process is found in it's DMprecache.scr and ambient.scr files.

--[MC] Hammer

[Hammer]

MAM provides a very strong and flexible command-processing module intended for introducing new features (commands) into the game. The command module allows modders to create external commands and easily integrate them with the rich set of commands already included in MAM's add-on support packages (MAM_Security.scr, MAM_DefaultCmds.scr, described in another thread). The module also provides server administrators with a simple yet powerful mechanism for invoking custom commands.


Command Syntax:

Commands are entered into the game's console window or through rcon using the following general syntax:

command "[<statnum> ]<command>[ <arg>[ <arg>[…]]]"

where <command> is the name of the command to execute (more later), <arg> is one or more arguments that may be required by <command>, and <statnum> is an optional number that when specified will be interpreted as the player number of the admin, obtained by issuing a console status command, that will receive feedback after/during a command's execution. If <statnum> is missing or invalid, then the command will be processed silently. Here's an example using the built-in cmdlist command:

command "0 cmdlist"

will output the list of currently registered commands to player number 0's console window.

You may enter any number of commands on a single command line by separating each one with a semicolon ( ; ), e.g.:

command "0 cmdlist; swith_axis spectator allies; 0 screenshot all"

MAM queues commands entered using the command statement and processes them in the order in which they are received. A non-queue version of this is available by using mam instead of command. When encountered, MAM will process the entered commands immediately, instead of queueing it until processing resources become available. The mam statement can be used to supply an emergency-type command.

Obtaining Command Usage:

The MAM command processor implements a generic command-usage facility to allow each registered command to return a simple usage message to an administrator. You can request command usage on a command by using the following syntax:

command "<statnum> <command> usage"

For example,

command "6 cmdlist usage"

will result in the following being displayed in player 6's console window:

[code:1]usage: cmdlist [<prefix>][/code:1]

Escaping Special Characters:

To work around certain limitations found in the MoH:AA console interpreter (especially in Spearhead), a quoting mechanism has been devised to help escape (or hide) special characters from the normal game parser. The following character sequences will be interpreted specially within a command:
[code:1]\\ - The backslash character (\)
\q - The double-quote character (")
\s - A single space
\: - A semi-colon (;)
\x - Any other character as itself
[/code:1]
For example:

command "switch_name \qThis\sis\smy\snew\sname\q"

would be interpreted by MAM as switch_name "This is my new name".


Basic Built-in Commands:

MAM's command processing module includes a handful of built-in commands. These are:

______________________ con:

command "[<statnum> ]con \q<cmd>\q[ all|allies|axis|spectator|<playerid>[ <playerid>[ …]]]"

The con command is used to send any MoH:AA console command (<cmd>) to players. The strings allies, axis, and spectator match players currently joined in as allies, axis or spectator, respectively, while all matches every player on the server. Individual players can be selected by specifying their status id in <playerid> entries. Examples:

- Force all players to join as axis:
command "con \qjoin_team axis\q all"

- Force screenshot on all allies (giving command feedback to player 10):
command "10 con \qscreenshot\q allies"

- For all axis and players with status number 1, 3, 5 and 8, chat "hello all":
command "con \qsay hello all\q 1 3 5 axis 8"

______________________ cmdlist:

command "<statnum> cmdlist [<cmd_prefix>]"

Lists currently registered commands. If <cmd_prefix> is specified, only those commands that start with the cmd_prefix will be listed.

______________________ modfiles:

command "<statnum> modfiles"

Lists the names of all command mod file packages currently registered with MAM.

______________________ unregister:

command "<statnum> unregister <command>[ <command>[ ...]]"

Remove one or more MAM commands from the command processor. Entering a command that has been unregistered will result in a command not found error being sent back to the admin.


Adding New Commands:

Mod developers that wish to add new commands to the MAM command processor should look at MAM_cmds.scr in the main MAM mod file for a description of the register function. Each new command in a mod must be registered before MAM will recognize it. Registering informs MAM of the name of the command, as well as the mod file and function to call when entered. It may be useful to also study the code used by the built-in commands con, cmdlist and modfiles. Additional tutorial files can be found under the tutorial folder in the MAM mod file.

--[MC] Hammer

[Hammer]

To help reduce code duplication, MAM provides a rich set of built-in utilities (commonly used library functions) to assist developers in their development efforts. This powerful set of functions allows developers to produce more compact and reliable code, reducing problems and time required to implement desired functionality. Functions range from simple string conversion tools, to complex methods used to identify players from within scripts, and corrective functions to help work around certain game limitations. The module also initializes several common script variables into MAM level vars for easy reference.

For a complete list of helper functions and level variables initialized, including full usage description, mod developers are encouraged to view the MAM helper utility module source file, MAM_utils.scr, containted within the main MAM mod file.

--[MC] Hammer