Below is a template that can be used when starting a new plugin. You can download this template as an sma file here. This skeleton demonstrates the main elements of an Admin Mod plugin, and good style for writing Small source code.
/*********************************************************
* A sample plugin - Version 1.0 *
*********************************************************
* *
* Name: plugin_sample *
* Author: ravenousbugblatterbeast@hotmail.com *
* Released: 1st September 2002 *
* *
* Version 1.0: *
* *
* - <your version history goes here> *
* *
*********************************************************
*/
/* Includes */
#include <core>
#include <console>
#include <string>
#include <plugin>
#include <admin>
#include <adminlib>
/* Constants */
/* The access level for the command admin_sample */
#define ACCESS_SAMPLE ACCESS_CONFIG
/* Global Variables */
new g_Version[]="1.0"; /* Plugin version number */
/* Function Declarations */
forward AdminSample(HLCommand,HLData,HLUserName,UserIndex);
/* Event Handlers */
public plugin_init() {
plugin_registerinfo("Sample Plugin","A example plugin",g_Version);
plugin_registercmd("admin_sample","AdminSample",ACCESS_SAMPLE,
"admin_sample: A sample Admin Mod command");
return PLUGIN_CONTINUE;
}
/* Command Handlers */
public AdminSample(HLCommand,HLData,HLUserName,UserIndex) {
say("Hello World");
return PLUGIN_HANDLED;
}
/* Support Functions */
The opening comment of the plugin shows the plugin name, the authors name / e-mail address and a version history. Including a history will allow both you and those that download your plugin to keep track of changes.
Also note that all comments in the plugin use the C-Style /* */, not the C++ style //. This is because the Small compiler has problems handling source files saved in DOS format (carriage return and line feed characters at the end of each line) on linux if the plugin contains //. If you always use /* */, other people will not have any problems compiling your plugins on linux even if they forget to convert the file format.
This tells the Small compiler about the names and syntax of all the built-in Admin Mod functions. This is boiler-plate code that you can leave in all plugins - there is no performance hit if you include stuff that you will not be using.
The next part of the plugin is the list of all the hard-coded constants that your plugin uses. You should provide a comment explaining the meaning of each constant, especially if you intend that users change their values before compiling. It is convention to declare constants in UPPER_CASE_WITH_UNDERSCORES.
A global variable is visible throughout the plugin - i.e. all functions can access it. Note that a global variable is not a half-life cvar; it is not visible outside the plugin, Admin Mod can't see it, you can't see it from the server console and other plugins can't see it. It is not possible for plugins to create their own cvar's.
Like the constants, you should include a comment explaining the meaning of each global variable - this can be a massive boost for anyone attempting to understand your source code.
Now comes the part many plugin authors omit, and get away with. The Small language has a two-pass compiler, so theoretically it is not necessary to declare your functions in advance. However, the compiler is known to be buggy - and if you do not declare all functions then sometimes the compiler forgets to include some functions in the compiled AMX file. The results of this are random, and extremely hard to diagnose.
To avoid headaches when debugging, always declare every function in your plugin. The only exceptions are the event handlers plugin_init, plugin_continue, plugin_disconnect and plugin_info as these are already declared in the include file admin.inc.
Plugin authors even go to the extremes of changing the order of the functions in their plugins so that they compile properly without declarations, as if they should receive some award for this. Don't do it - the order of the functions in your source should be determined by one thing and one thing only: Put them in the order that makes it easiest for someone reading your code to understand it.
The remainder of the plugin contains the implementations of the functions. You should place the functions in the order that makes them easiest for someone new to your plugin to read and understand your source code.