AlliedModders Wiki - User contributions [en]

Base Plugins (SourceMod)

2008-05-03T20:15:42Z

Belsebub: fixed broken link

__FORCETOC__
The following is a full list of [[SourceMod]]'s base plugins and the purpose of each one.

Plugins with a bold name are safe to be used in [[War_Mode_(SourceMod)|War Mode]], as they do not contain anything that could be considered abusive or unfair.

=Default Plugins=
{| style="width:600px;" cellpadding="5"
|- class="t2th"
|Plugin
|Purpose
|- class="t2td"
| '''admin-flatfile'''
| Loads admins from the admin configuration files.
|- class="t2td"
| '''adminhelp'''
| Provides the sm_help command (lists other commands and their syntax).
|- class="t2td"
| '''adminmenu'''
| Provides the admin menu API and core features.
|- class="t2td"
| antiflood
| Prevents clients from spamming messagemode/chat.
|- class="t2td"
| '''basebans'''
| Provides basic banning commands and menu options.
|- class="t2td"
| basechat
| Provides commands and menu options for managing player's abilities to use voice chat or say chat.
|- class="t2td"
| basecomm
| Provides functionality for tweaking how players can communicate (in comparison to sv_alltalk).
|- class="t2td"
| '''basecommands'''
| Provides basic administrative commands unrelated to player abuse (for example, map changing, kicking, and cvar changing).
|- class="t2td"
| basetriggers
| Provides automated responses to phrases such as "nextmap", "thetime", and "timeleft".
|- class="t2td"
| basevotes
| Provides basic voting commands, such as map voting.
|- class="t2td"
| funcommands
| Provides "fun" commands, like slapping.
|- class="t2td"
| funvotes
| Provides votes based on basefuncommands.
|- class="t2td"
| '''nextmap'''
| Allows admins or other plugins to dynamically alter or retrieve the effective mapcycle.
|- class="t2td"
| reservedslots
| Allows the server to have slots that are reserved for administrators (or privileged people), to ensure prioritized entry.
|}

=Extra Plugins=
The following plugins are in the <tt>addons/sourcemod/plugins/disabled</tt> folder by default, and must be moved out of that folder to be enabled.

If a plugin has cvars, you can load it once to generate its config file in <tt>cfg/sourcemod</tt>.

{| style="width:600px;" cellpadding="5"
|- class="t2th"
|Plugin File
|Purpose
|- class="t2td"
| '''admin-sql-prefetch'''
| Loads admins from an SQL database as a big lump every mapchange. If enabled, <tt>admin-sql-threaded</tt> must be disabled; see [[SQL_Admins_(SourceMod)|SQL Admins]].
|- class="t2td"
| '''admin-sql-threaded'''
| Loads admins from an SQL database dynamically as each admin connects. If enabled, <tt>admin-sql-prefetch</tt> must be disabled; see [[SQL_Admins_(SourceMod)|SQL Admins]].
|- class="t2td"
| mapchooser
| Provides an automated system for players to vote for map changes. If enabled, <tt>rockthevote</tt> and <tt>randomcycle</tt> should be disabled. Cvars are generated in <tt>plugin.mapchooser.cfg</tt>.
|- class="t2td"
| randomcycle
| Randomizes the map cycle. If enabled, <tt>mapchooser</tt> and <tt>rockthevote</tt> should be disabled. Cvars are generated in <tt>plugin.randomcycle.cfg</tt>.
|- class="t2td"
| rockthevote
| Provides a player-initiated system for players to vote for map changes. If enabled, <tt>mapchooser</tt> and <tt>randomcycle</tt> should be disabled. Cvars are generated in <tt>plugin.rtv.cfg</tt>.
|}

[[Category:SourceMod Documentation]]

AMX Mod X 1.75 Scripting Changes

2006-06-10T20:26:18Z

Belsebub:

The AMX Mod X 1.75 release made important changes. While backwards compatibility was kept, intended functionality shifted in esoteric areas that will affect some plugins. Reading this article is highly recommended.

=Module Requirement System=
As part of the new Automatic Module Loading, the old <tt>#pragma library</tt> has been deprecated. You must now use:
<pawn>#pragma reqlib <library>
</pawn>
This means "require library". Plugins still compiled with <tt>#pragma library</tt> will still fail on load if the given module is not found. However, core will try to load each module given the rules below under "Automatic Module Loading".

=Auto Plugin Files=
With the introduction of callfunc and register_native, many people now distribute plugins in large sets. To make this easier on users, you can now distribute an "extended plugin file." For example, say you have five plugins in a set. Normally, you would have to ask the user to write each name into plugins.ini, like so:
<pre>
file1.amxx ;file1
file2.amxx ;file2
file3.amxx ;file3
file4.amxx ;file4
file5.amxx ;file5
</pre>

With AMX Mod X 1.75, any file in the configs folder which follows a certain name pattern will be auto-loaded as an additional plugins.ini file. The pattern is: plugins-*.ini.

For example, you could distribute <tt>plugins-carmod.ini</tt> as:
<pre>
;put a semi-colon to disable a plugin
cars_honda.amxx
cars_toyota.amxx
cars_ford.amxx
cars_bmw.amxx
cars_gaben.amxx
</pre>

This way, you can easily distribute an extractable install, rather than giving the user overcomplicated instructions. Furthermore, the file is easily disabled by simply modifying the name (for example, "disabled-carmod.ini").

=Automatic Module Loading=
==Overview==
As of AMX Mod X 1.75, there is a new, powerful automatic module loading system. That means that <tt>modules.ini</tt> is largely deprecated for general use. Instead, modules are loaded as plugins need them. This is done dynamically by core before plugins are even loaded, without the need to patch <tt>modules.ini</tt> and then change the map.

Modules can now define "Libraries" and "Library Classes". A library is a specific identifier that should match the filename of the module. For example, Engine's defined library is "engine". FakeMeta's library is "fakemeta", and so on.

A "library class" defines membership to a set of modules. For example, CSX has the library name "csx", but it is part of the library class "xstats". Library classes are also used for DBI and SQLX. This is very useful for being able to require one module type of any implementation.

==New API==
===Compiler Pragmas===
This is expanded with a number of new <tt>#pragma</tt> directives:
*<tt>#pragma reqlib <library></tt> - Requires that a given library must be loaded.
*<tt>#pragma reqclass <libclass></tt> - Requires that a given library class must be loaded.
*<tt>#pragma loadlib <library></tt> - Automatically attempts to load a given library (see more info below).
*<tt>#pragma expectlib <library1> <library2></tt> - If the first library is not loaded, the second one will be attempted to load (not very useful).
*<tt>#pragma expectclass <class> <library></tt> - If the expected class is not found, the given library will be attempted to load. This is useful for defining a default module to be loaded with a given class of modules.
*<tt>#pragma defclasslib <class> <library></tt> - Same as <tt>expectclass</tt>, however, <tt>defclasslib</tt> waits until all expectations are resolved. This lets plugins override defaults by adding their own expectations.

===Module Filtering===
The module_filter prototype now includes a second parameter, which tells you whether the requirement is a class or library.

Furthermore, module_exists has been deprecated for LibraryExists().

==How it Works==
The precise order of events is as follows:
*When the first entity is spawned, AMX Mod X loads all unloaded modules in <tt>modules.ini</tt>.
*After <tt>modules.ini</tt> is parsed, <tt>plugins.ini</tt> is read. Each file is mapped into a cache.
*The cache is previewed.
**First, the "library" table is read. This table is read for backwards compatibility with AMX Mod X 1.71 and prior. Each entry is read as a module file shortname, and the module is loaded if it exists.
**Next, the "pubtags" table is read. Each entry is decoded to one of the special #pragma commands.
***All loadlib commands are executed, and the modules loaded.
***All expect commands are executed.
***All defclasslib commands are executed.
*AMX Mod X then waits until ServerActivate is called.
*All plugins are loaded. If the plugin is in the cache, the cache is read instead. For each plugin...
**The library table is read. For each library that is both nonexistant and unhandled by a module filter, the plugin fails to load.
**The pubtags table is read. For each reqlib and reqclass entry that are both nonexistant and unhandled by a module filter, the plugin fails to load.
*The plugin cache is invalidated and the server is considered "loaded".

=SQLX=
==Introduction==
SQLX is a new Database API that supercedes DBI. Its main feature is that you can load two SQLX modules at once, whereas you cannot with DBI. It also supports threaded queries, which let you process data without interrupting gameplay from a bad network connection.

These additions come at a hefty price. The SQLX API is significantly more complex than DBI. Although some might find it easier to use due to its simpler error checking and iteration, it requires more manual memory management and has less simple abstraction. Furthermore, taking advantage of the new <tt>SQL_ThreadQuery</tt> native will require nothing short of a rewrite for most plugins, as it is ''asynchronous'' instead of ''synchronous''. Because of this, the new SQLX modules also implement the old DBI functionality, for both backwards compatibility and for plugin developers familiar with the old API. All three APIs - SQL-threaded, SQL-non-threaded, and DBI, are still fully supported.

==Usage==
Since SQLX is an expansive API, showing a single plugin of its usage would be difficult. It is highly recommended that users interested in the new API look at the [http://cvs.tcwonline.org/viewvc.cgi/amxmodx/plugins/testsuite/sqlxtest.sma?view=log SQLxTest] plugin, which compares two different DBI methods and both SQL methods of querying a database. It is highly useful for both regression testing and for getting an idea of how the API works.

The most important concept of SQLX is "Handles," which are a precursor to a system planned for SourceMod. Handles are datatypes that store internal information that you should not modify. Whenever you create a handle, you must also free it, with <tt>SQL_FreeHandle</tt>().

==Native Overview==
The basic natives of SQLX are:
*<tt>SQL_MakeDbTuple</tt> (or simple stock version, <tt>SQL_MakeStdTuple</tt>) - This creates a variable that holds information about a database. It does not connect to the database. This is so you don't have to keep retrieving cvar info on every connection. You do not have to free these handles, although it is a good idea if you create them dynamically.
*<tt>SQL_Connect</tt> - Connects to a database and returns a new Handle, or <tt>Empty_Handle</tt> on failure.
*<tt>SQL_PrepareQuery</tt> - Prepares a query for execution, and returns a new Handle to the query.
*<tt>SQL_Execute</tt> - Executes a prepared query, and returns 0 on failure (1 on success).
*<tt>SQL_MoreResults</tt> - Returns 1 if there are more results in the query result queue, 0 if none.
*<tt>SQL_ReadResult</tt> - Reads the current row result by the column's numerical index, similar to dbi_field/dbi_result.
*<tt>SQL_NextRow</tt> - Advances to the next result row. '''Compatibility Warning''': This does not need to be called first! Unlike <tt>dbi_nextrow</tt>, the query is automatically at the first row. If you call <tt>SQL_NextRow</tt> before <tt>SQL_ReadResult</tt>, your are actually skipping a row.
*<tt>SQL_FreeHandle</tt> - Frees a Handle. You must do this or else memory will leak.
*<tt>SQL_ThreadQuery</tt> - Places a query and connection info into a threaded queue. In another thread, the connection is established, the query is executed, and the connection is dropped. The query results are then posted back into the main thread and given to the plugin on the next server-frame.
**Note that while powerful, the mechanism is very simplistic. Similar to <tt>set_task</tt>, you must differentiate multiple queries having the same callback by packing binary data into an array. Furthermore, you can only make one query at a time, since the queue is "push one, resolve one, pop one." If you plan on making five queries in a row in order to get aggregate information about a player, you must make each of these five queries in separate stages, and you must also take into account asynchronous factors such as the player dropping during the middle of a query. (One way to do this is to pack the player's authid and client index into the callback data and verify it when the query finishes.)

=New Natives / Native Changes=
==Register Message==
The <tt>register_message</tt> set of natives, including <tt>get/set_msg_block</tt>, has been moved to Core. This is to facilitate users who prefer to use FakeMeta, and like the simplicity and speed of using Engine's message interception functions.
<br />
This change is backwards compatible.

==Argument Formatting==
The <tt>format_args</tt> function is now replaced with a much faster, more compatible <tt>vformat</tt> function. Its usage is slightly different (read the include file, <tt>string.inc</tt>), but it accepts %L, whereas format_args does not. A quick example:
<pawn>debugprint(const fmt[], ...)
{
static temp[2048]
vformat(temp, sizeof(temp)-1, fmt, 2)
log_message("[DEBUG] %s", temp)
}</pawn>

==Other Core Natives==
*<tt>register_plugin</tt> - Now returns a plugin id.
*<tt>get_amxx_verstring</tt> - Returns the AMX Mod X version string.
*<tt>get_weaponid</tt> - Gets a weapon id from a weapon name.

==FakeMeta==
===New Natives===
*<tt>get_orig_retval</tt> - Gets the original return value of an engine or game DLL function.
*<tt>copy_infokey_buffer</tt> - Copies the given infobuffer pointer into output buffer.
*<tt>get/set_cd</tt> - Gets or sets members of a clientdata data structure (used with UpdateClientData).
*<tt>get/set_es</tt> - Gets or sets members of an entity_state data structure (used with AddToFullPack).
*<tt>get/set_uc</tt> - Gets or sets members of a usecmd data structure (used with CmdStart).

===New Engine/GameDLL Functions===
The <tt>register_forward</tt> native now allows for hooking a number of new functions from the engine or game DLL including:
*<tt>UpdateClientData</tt>
*<tt>AddToFullPack</tt>
*<tt>CmdStart</tt>
*<tt>CmdEnd</tt>
*<tt>CreateInstBaselines</tt> - Game DLL function
*<tt>CreateInstBaseline</tt> - Engine function
*<tt>CreateBaseline</tt>
*<tt>GetInfoKeyBuffer</tt>
*<tt>AlertMessage</tt> - This now can be called via <tt>engfunc</tt>
*<tt>ClientPrintf</tt>

These functions can also be called via <tt>engfunc</tt> or <tt>dllfunc</tt>.

===Breaking Changes===
Using <tt>engfunc</tt> in order to call <tt>EngFunc_InfoKeyValue</tt>, <tt>EngFunc_SetKeyValue</tt>, or <tt>EngFunc_SetClientKeyValue</tt> now requires passing an infobuffer pointer. An infobuffer pointer can be obtained by calling <tt>EngFunc_GetInfoKeyBuffer</tt>. For example:
<pawn>some_function(id, name[])
{
new infokey = engfunc(EngFunc_GetInfoKeyBuffer, id)
engfunc(EngFunc_SetClientKeyValue, id, infokey, "model", name)
}</pawn>

If you hook ClientUserInfoChanged via Fakemeta, an infobuffer pointer is now also forwarded to your function in addition to the client id.

==Cstrike==
*<tt>cs_get_user_mapzones</tt> - Returns bitwise flags of where on the map a player is located such as buy zone, bomb site, hostage rescue zone, VIP safety zone, and escape zone.
*<tt>cs_set_user_vip</tt> - Now takes two additional (but optional) parameters for determining whether or not the player model and scoreboard get updated.

==New Stocks==
===Engine===
*<tt>IsInWorld</tt> - Checks if an entity is within the bounds of the world (from HLSDK).

===FakeMeta===
*<tt>DF_UpdateClientData</tt> - Calls UpdateClientData game DLL function.
*<tt>DF_AddToFullPack</tt> - Calls AddToFullPack game DLL function.
*<tt>DF_CmdStart</tt> - Calls CmdStart game DLL function.
*<tt>DF_CmdEnd</tt> - Calls CmdEnd game DLL function.
*<tt>DF_CreateBaseline</tt> - Calls CreateBaseline game DLL function.
*<tt>DF_CreateInstBaselines</tt> - Calls CreateInstancedBaselines game DLL function.
*<tt>EF_CreateInstBaseline</tt> - Calls CreateInstancedBaseline engine function.
*<tt>EF_GetInfoKeyBuffer</tt> - Calls GetInfoKeyBuffer engine function.
*<tt>EF_ClientPrintf</tt> - Calls ClientPrintf engine function.

==New Constants==
Various sound constants (<tt>SND_SPAWNING</tt>, <tt>SND_STOP</tt>, <tt>SND_CHANGE_VOL</tt>, and <tt>SND_CHANGE_PITCH</tt>) from the HL SDK as well as a constant for pi were added to <tt>amxconst.inc</tt>. <tt>TE_*</tt> (temp entity) message constants have also been added which will automatically be included with <tt>#include <amxmodx></tt>. And finally, a new <tt>hlsdk_const.inc</tt> file has been added that contains many more constants from the SDK. This is automatically included with <tt>#include <engine></tt> or <tt>#include <fakemeta></tt>.

=Module API=
The AMX Mod X module API received a small overhaul for 1.75.

==Versioning/Interface Additions==
The internal module interface version is 4. However, modules from M/SDK 3 will still load.

M/SDK Version 4 modules have two new members of public information: the library string, and the library class string. These contain comma delimited names of whatever libraries or library classes the module would like to be registered.

For backwards compatibility, M/SDK Version 4 modules have an automatically empty library class string, and a library string equal to the logtag string.

==New Callbacks==
Modules can now be informed of when plugins are about to be unloaded, and when plugins have been fully unloaded. This means that modules don't have to hook ServerActivate and ServerActivate_Post (implementation dependent), don't need to be loaded by Metamod, and don't need to detach simply to release resources.

==New Functions==
*<tt>MF_GetLocalInfo</tt> - Intended for modules using LOCALINFO, which required a Metamod attachment. This is equal to AMX Mod X's core function <tt>get_localinfo</tt>.
*<tt>MF_OverrideNatives</tt> - Given a native list, this specifies that any other module already providing these natives will no longer provide them. This was added to force backwards compatibility between SQLITE and MySQLX. Usage is not recommended.
*<tt>MF_FindLibrary</tt> - Essentially the same function as LibraryExists() for plugins.
*<tt>MF_AddLibraries</tt> - Adds a comma delimited list of libraries or library classes. You must specify a "parent" pointer that identifies the module. This is easily accomplished by taking the address of any static variable.
*<tt>MF_RemoveLibraries</tt> - Removes all library entries with the given parent pointer. This is useful if your module adds custom entries not in its defined list.

==MSVC8 Compatibility==
M/SDK Version 4 now contains preprocessor definitions for compatibility with Microsoft's Visual Studio 2005/8.0 (provided by [[User:Damaged Soul|Damaged Soul]]). These macros can be turned off in the <tt>moduleconfig.h</tt> file by uncommenting the definition of <tt>NO_MSVC8_AUTO_COMPAT</tt>.

=Minor Changes=
==Compiler Defines==
Since <tt>__DATE__</tt> was fixed in 1.75, the macro <tt>__TIME__</tt> was also added.

=Full Changelog=
This changelog is tentative. Developers will be editing it as things are changed.

* Core Changes
** Modules are now automatically loaded by detecting plugin usage.
*** modules.ini is now primarily deprecated, except for SQL and unsupported libraries.
** Rewrote SQLX modules (again). You can now load multiple SQL modules and toggle them per-plugin.
*** Added new SQL API called SQLX. DBI was kept backwards-compatible.
*** Added new function to thread SQL queries (which prevents lag from a bad connection).
** Fixed some very small memory leaks.
** Fixed binary logging building wrong on Linux.
** Fixed some debugging crashes.
** Fixed serious bug when creating plugin_pause/plugin_unpause forwards.
** Fixed serious crash bug involving set_hudmessage and plugins using high hudchannels.
** Added natives:
*** fputs()
*** get_weaponid()
*** rename_file()
*** vformat()
** Any file starting with "plugins-" and ending in ".ini" will now be treated as an extended plugins file. This is useful for distributing sets of plugins separately, and easily disabling them with a name change.

* Fakemeta Changes
** Added new hookable/callable functions:
*** AddToFullPack
*** AlertMessage
*** ClientPrintf
*** ClientUserInfoChanged
*** CmdEnd
*** CmdStart
*** CreateBaseline
*** CreateInstancedBaseline
*** GetInfoKeyBuffer
*** InfoKeyValue
*** UpdateClientData
*** SetClientKeyValue
*** SetKeyValue
** Added new natives:
*** copy_infokey_buffer
*** get_orig_retval
** Fixed various trace bugs in FakeMeta with certain natives.
** Fixed some unhooking on server-deactivate problems in FakeMeta.

* Scripting Changes:
** Added __DATE__ and __TIME__ auto-macros to the compiler.
** Added many HLSDK constants and improved include organization.
** Added new compiler #pragma directives for using the module autoloading system.
** Added cs_get_user_mapzones (thanks VEN!).
** Added IsInWorld() stock (thanks Twilight Suzuka!).
** Added nvault_remove().
** Moved various natives from Engine and into Core:
*** register_message
*** get_msg_args
*** get/set_msg_arg_type
*** get/set_msg_arg_int
*** get/set_msg_arg_float
*** get/set_msg_arg_string
*** get_msg_origin
*** get/set_msg_block
*** velocity_by_aim
*** vector_to_angle
*** angle_vector
*** vector_length
*** vector_distance
*** precache_generic
** Dynamic natives that are paused now also pause parent plugins (with an error).
** register_plugin() now returns the plugin ID.
** Fixed a corruption bug in strip_user_weapons().
** Fixed a bug in set_view() (thanks jtp10181!).
** Fixed is_in_viewcone() always returning 0.
** Fixed is_visible causing a crash, improved accuracy.
** Fixed a crash bug in get_tr2() (thanks Orangutanz!).
** Fixed cs_get_user_buyzone() returning existence in other areas.
** Fixed a rare floatround() bug where values ending strictly in .5 were IEEE rounded.
** Fixed a bug where removing the current parent task could damage the task queue.
** Fixed a bug in get_entity_visibility (thanks VEN!).
** Removed non-existant take_damage() entry.
** Expanded XS Stock Library with addition of xs_vec_make2d.
** Expanded usage of cs_set_user_vip().
** Improved get_brush_entity_origin() and ViewContents (thanks Orangutanz!).

* Plugin Changes:
** Added amx_showrcon command to show rcon results in admincmd.sma.
** Added weapon restriction compatibility for bots in CS (KWo).
** Added admin identifier (asterisk which is red if colors are available) to all menus with a user list.
** Upgraded admin.sma to the new SQLX API.
** Fixed a bug in amx_reloadadmins not giving admins new access.
** Fixed a weapon restriction exploit in restmenu.sma.
** Fixed an HTML exploit in /top15 displaying player names.
** Fixed various and plentiful amx_addadmin bugs.
** Fixed telemenu.sma not letting you teleport yourself (thanks jtp10181!).
** Fixed a bug with adminslots.sma lowering the slots by 1.
** Fixed overlapping hud messages with miscstats.

* Module API Changes:
** Added and fixed module API for inter-module communication.
** Added native overriding and replacing to module API.
** Added plugin unloading/unloaded callbacks to module API.
** Added MSVC8 project files to most CVS projects.

* Configuration Changes:
** Added amx_sql_type cvar to sql.cfg.
** Re-organized and simplified modules.ini.
** Error logging can now be redirected to separate logs.
** Fixed modules.ini parsing bugs and simplified parsing.
** Fixed a double entry in cvars.ini.

* Other Changes:
** Added a Bulgarian translation (thanks lubb!).
** Added a leetspeak translation (thanks, I think, Twilight Suzuka!).
** Improved FTP option of the graphical installer.
** Updated the GeoIP library to June.
** Updated PCRE from v6.1 to v6.4.
** Updated sqLite from 3.3.4 to 3.3.5.
** Fixed a steam account path bug in the installer.

[[Category:AMX Mod X]]

Advanced Scripting (AMX Mod X)

2006-05-20T15:24:21Z

Belsebub:

This article will briefly summarize some of the more advanced topics of [[:Category:Scripting (AMX Mod X)|AMX Mod X Scripting]].

=Tasks=

Tasks are timers that let you run code at an interval, either once or repeated. They are useful for things like waiting a few seconds, setting objects to destroy themselves, or just repeating a task over and over.

A task can be set in a number of different ways. The actual function is set_task():
<pawn>set_task(Float:time,const function[],id = 0,parameter[]="",len = 0,flags[]="", repeat = 0)</pawn>

The parameters break down as such:

* Float:time - Interval of timer in seconds (minimum 0.1 seconds)
* function[] - A string that contains the public function to run on the timer
* id - A unique id to assign to the task
* parameter - An array contain data to send to the timer function
* len - Size of the array to send to the timer function
* flags - One of the following:
** "a" - Repeat task a specified number of times
** "b" - Loop task infinitely
** "c" - do task on time after a map timeleft
** "d" - do task on time before a map timeleft
* repeat - If flags is "a", specifies the number of times to repeat the task

An example of a task is below. It will slap a specified player 5 times, once per second.

<pawn>//the timed function receives the parameter array and its task id
public slapTask(params[], id)
{
new player = params[0]
user_slap(player, 5)
}

public start_slapping(id)
{
new params[1]
params[0] = id
//we don't need a specific id
set_task(1.0, "slapTask", 0, params, 1, "a", 5)
}
</pawn>

Note that if you specify 0 for parameter length, then the task function should look like:

<pawn>public slapTask(id)</pawn>

=Menus=

Menus are HUD messages that give a player a choice of options to select. They are quite messy to deal with but can be very useful for things like voting and command selection.

Menus must be registered by two things - a set of "keys" that tells how many options to register and a string which identifies the menu as unique. This string must appear in the beginning of every menu you want to trigger your function. When you display a menu, you can show it to one or more players. Once they hit a key, the result of their key press will be sent to the function you registered the menu to.

For our example, we'll make a menu that displays a list of guns: AK47, M4A1, or AWP, to a player. Whichever he selects, he will be given.

<pawn>#include <amxmodx>
#include <amxmisc>
#include <fun>
public plugin_init()
{
register_plugin("Menu Demo", "1.0", "BAILOPAN")
new keys = MENU_KEY_0|MENU_KEY_1|MENU_KEY_2
register_menucmd(register_menuid("Which Weapon?"), keys, "giveWeapon")
}
</pawn>

Two commands are apparent here - register_menuid and register_menucmd. register_menuid registers a short phrase that will appear at the beginning of the menu, then returns an id. This id is the first parameter to register_menucmd. The second parameter to register_menucmd is the key configuration. Our menu will have three options, so we've added three menu keys in. In actuality, these are bitwise flags totalling "7", but that's not important. The last parameter is the public function that will handle the menu results.

Next, how do we show the menu? Let's make a quick console command: "giveme".

<pawn>public plugin_init()
{
register_plugin("Menu Demo", "1.0", "BAILOPAN")
new keys = MENU_KEY_0|MENU_KEY_1|MENU_KEY_2
register_menucmd(register_menuid("Which Weapon?"), keys, "giveWeapon")
register_clcmd("giveme", "showWeaponMenu")
}
</pawn>

register_clcmd is similar to register_concmd, except it only takes two parameters. It's used to register any command a client can use (except for special ones, like +attack).

<pawn>//The clcmd function will just give us the player id
public showWeaponMenu(id)
{
new menu[192]
new keys = MENU_KEY_0|MENU_KEY_1|MENU_KEY_2

format(menu, 191, "Which Weapon?^n^n1. AK47^n2. M4A1^n3. AWP")
show_menu(id, keys, menu)
return PLUGIN_HANDLED
}

//Our menu function will get the player id and the key they pressed
public giveWeapon(id, key)
{
//key will start at zero
if (key == 0)
{
give_item(id, "weapon_ak47")
} else if (key == 1) {
give_item(id, "weapon_m4a1")
} else if (key == 2) {
give_item(id, "weapon_awp")
}
}
</pawn>

And we're done! The format line may be a little confusing. The "^n" means "new line", so the menu looks nicely formatted. You can use other modifiers in VGUI2 mods, such as "\w" for white text, "\r" for red text, and "\y" for yellow text. When a player types the command, he will see the menu. When he hits a key, the giveWeapon function will receive his id and the key number he pressed. Then he will get a gun corresponding to what he chose.

=Events/Messages=

For this demonstration, we're going to extend the above example. Every time a player respawns, he will be shown the menu to choose a weapon (note - we're ignoring other things like blocking buying and removing buyzones, this is just a demonstration).

Messages are a way for Half-Life clients to talk to servers, and vice versa. They are specially formatted lists of parameters. For example, the message "DeathMsg" (message id 83) has three parameters: Attacker (byte), Victim (byte), and Weapon (string). You can either capture messages or send them. Here, we'll do a simple demonstration of both. First let's make it so a user gets their gun menu when they spawn.

<pawn>public plugin_init()
{
register_plugin("Menu Demo", "1.0", "BAILOPAN")
new keys = MENU_KEY_0|MENU_KEY_1|MENU_KEY_2
register_menucmd(register_menuid("Which Weapon?"), keys, "giveWeapon")
//flags - b means "sent to one target", e means "target is alive"
//this event is sent when a player spawns
register_event("ResetHUD", "hook_hud", "be")
}

public hook_hud(id)
{
//since we specify no parameters to the task,
//the task id will be given to the function
//this is useful because we can reuse our old
//show menu function which takes an id
set_task(0.2, "showWeaponMenu", id)
}
</pawn>

Note that we've set a small delay when we receive the message - this is to make sure that the user has had time to respawn. register_event can take more parameters in order to help restrict the event you catch - for example only matching certain parameters. You can read more about this in the function reference.

Now, let's say we want to figure out when a player has died...

<pawn>public plugin_init()
{
register_plugin("Message Demo", "1.0", "BAILOPAN")
//this message informs everyone of a death, so we use
// flag "a" - global event
register_event("DeathMsg", "hook_death", "a")
}

public hook_death()
{
new Killer = read_data(1) //get the first message parameter
new Victim = read_data(2) //get the second message parameter
new headshot = read_data(3) //was this a headshot?
new weapon[32]
read_data(4, weapon, 31) //get the weapon name
}
</pawn>

Or, let's say we want to make a simple function for generating a death message:

<pawn>stock make_deathMsg(Killer, Victim, const weapon[])
{
//message_begin starts a message. NEVER start two messages at once.
//MSG_ALL means send the message to everyone
//get_user_msgid returns the id of a message name
//{0,0,0} is the origin vector - not used here
//0 is the target - no specific target here
message_begin(MSG_ALL, get_user_msgid("DeathMsg"), {0,0,0}, 0)
write_byte(Killer)
write_byte(Victim)
write_string(weapon)
message_end()
}
</pawn>

To find more about messages, consult the HLSDK, AMX Mod X forums, HL-related programming sites, or other plugins. To list the messages a mod has, type "meta game" in the server console (with metamod loaded). You can also use register_message, the more advanced message disection method found in the Engine module.

=Catching Log Messages=

Catching log messages is not used heavily any more, but it's still good to know how to do it. As log messages are sent by the mod, AMX Mod X will be able to catch them and let you hook them. For our example, let's give everyone $16,000 on round start.

The log messages for rounds are sent like this: World triggered "Round_Start". AMX Mod X will consider "World_triggered" as the first parameter and "Round_Start" as the second parameter. So:

<pawn>#include <amxmodx>

public plugin_init()
{
register_plugin("Log Demo", "1.0", "BAILOPAN")
//this will filter for two parameters
//roundstart is the public function
register_logevent("roundstart", 2, "0=World triggered", "1=Round_Start")
}

public roundstart()
{
//set a small delay to make sure everyone spawns
set_task(1.0, "roundDelay")
}

public roundDelay(taskId)
{
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
cs_set_user_money(players[i], 16000)
}
}
</pawn>

You can also read specific log parameters with read_logdata(), which can only be used inside the "plugin_log()" forward:

<pawn>//receives all log messages
public plugin_log()
{
new data[32]
read_logdata(data, 31)
}
</pawn>

=Multi-Lingual Support=

Adding multi-lingual support to a plugin can be difficult, but it's usually worth it if you have clients who are willing to translate your strings into their native language.

The first step is to identify what needs to be translated. Say you have a call like this:

<pawn>new score = get_score()
client_print(id, print_chat, "[AMXX] Your score is %d", score)
</pawn>

This is a good candidate for being multi-lingual. First, create a .txt file (preferrably named after your plugin) and store it in addons\amxmodx\data\lang\. Let's use "myplugin.txt" for the example. For each language, add an entry to the file. Entries are set up as 'keys', which are matched to 'translation strings'. Observe:

<pre>(addons\amxmodx\data\lang\myplugin.txt)

[en]
SCORE_MSG = Your score is %d

[de]
SCORE_MSG = Ihr Spielergebnis ist %d

[es]
SCORE_MSG = Su cuenta es %d

[fr]
SCORE_MSG = Votre score est %d
</pre>

Then, in plugin_init(), you must register the language keys:

<pawn>public plugin_init()
{
...
//assumes placed in amxmodx\data\lang
register_dictionary("myplugin.txt")
}
</pawn>

Now, here comes the hard part. AMX Mod X's Multi-Lingual API is built into the format() style routines. For anything that looks like or uses format()-style strings, you can use the ML API.

<pawn> client_print(id, print_chat, "[AMXX] %L", id, "SCORE_MSG", get_score())
</pawn>

Let's break this down. For each %L that appears, we need at least two parameters. The first parameter is the TARGET. This must be a player id, LANG_SERVER (meaning show in the server's native language), or LANG_PLAYER. LANG_PLAYER is a special modifier that should only be used when sending a message to all players - it means "show in every player's native language". The second parameter is the key string that identifies the language phrase to translate. Lastly, if the translated string requires any parameters itself (ours needs %d, one integer), that must be added as well.

You can get very complicated designs with this, but it's recommended that you keep things simple for clarity. Here is a final example using a global message to all players, assuming the key HELLO is properly translated in all the languages available:

<pawn> client_print(0, print_chat, "[AMXX] %L", LANG_PLAYER, "HELLO")
</pawn>

=SQL Support=

SQL support has greatly improved in AMX Mod X. There is a common set of natives that work with a single driver, so as long as one (and only one) SQL module is loaded, the SQL (or DBI) natives will work. Here is a short primer on how to use the DBI natives:

<pawn>//Create a connection
new Sql:mysql = dbi_connect("localhost", "dvander", "pass", "dbase")

//If the connection is less than 1, it is bad
if (mysql < SQL_OK) {
new err[255]
new errNum = dbi_error(mysql, err, 254)
server_print("error1: %s|%d", err, errNum)
return 1
}

server_print("Connection handle: %d", mysql)
//Run a query
new Result:ret = dbi_query(mysql, "INSERT INTO config (keyname, val) VALUES ('amx', 'yes')")

//If the query is less than 0, it failed
if (ret < RESULT_NONE) {
new err[255]
new errNum = dbi_error(mysql, err, 254)
server_print("error2: %s|%d", err, errNum)
return 1
}

//Do a select query
new Result:res = dbi_query(mysql, "SELECT * FROM config")

//If the query is greater than 0, you got a handle to the result set
if (res <= RESULT_NONE) {
new err[255]
new errNum = dbi_error(mysql, err, 254)
server_print("error3: %s|%d", err, errNum)
return 1
}

server_print("Result handle: %d", res)

//Loop through the result set
while (res && dbi_nextrow(res)>0) {
new qry[32]
//Get the column/field called "keyname" from the result set
dbi_result(res, "keyname", qry, 32)
server_print("result: %s", qry)
}

//Free the result set
dbi_free_result(res)

//Close the connection
ret = dbi_close(mysql)
if (ret <= RESULT_NONE) {
new err[255]
new errNum = dbi_error(mysql, err, 254)
server_print("error4: %s|%d", err, errNum)
return 1
}
</pawn>

=Regular Expressions=

Regular Expressions let you describe ways in which to break down strings. They are extremely powerful. AMX Mod X uses the Perl Compatible RE library, you can read the specifics at their site. AMX Mod X offers regular expressions with the regex_amxx module. Here is a short example:

<pawn>#include <amxmodx>
#include <regex>

public plugin_init()
{
register_plugin("Regex", "1.0", "BAILOPAN")
register_srvcmd("amx_regex", "cmdtest")
}

public cmdtest()
{
new str[] = "It's Walky!"
//this pattern will match any string which contains
// two groupings of characters separated by a space
// the two groupings are substrings 1 and 2
new pattern[] = "(.+) (.+)"

new num, error[128]
//str = string
//pattern = pattern to use
//num = special return case code
//error = if there's an error, it will go here
//127 - error's max length
new Regex:re = regex_match(str, pattern, num, error, 127)

server_print("Result=%d, num=%d, error=%s", re, num, error)

//REGEX_OK means there was a match
if (re >= REGEX_OK)
{
new str2[64]
new i
//since it returned REGEX_OK, num has
// the number of substrings matched by the pattern.
//the first substring (0) seems to match the whole string.
for (i=0; i<num; i++)
{
regex_substr(re, i, str2, 63)
server_print("Substring %d: %s", i, str2)
}
//the regular expression matcher uses memory.
//you must free it if you get REGEX_OK
//This will also set re to 0.
regex_free(re)
}

//note the invalid regular expression pattern
//this will return REGEX_PATTERN_FAIL, -1
re = regex_match("Bruno the Bandit", ".+(]", num, error, 127)

server_print("Result=%d, num=%d, error=%s", re, num, error)
}
</pawn>

If you compile and run this script (amx_regex in server console) you will see the following output:

<pre>
Result=1, num=3, error=
Substring 0: It's Walky!
Substring 1: It's
Substring 2: Walky!
Result=-1, num=4, error=missing )
</pre>

Note that the third parameter to "regex_match()" is special. It's either the number of substrings, a match error code, or a pattern error position (depending on the return value).

=Entities=

Entities are basically any dynamic structure in Half-Life. Players, weapons, grenades, and other little objects laying around are entities. They have a unique "entity id" which you can use to change their values.

I won't go into this too deeply as it's a complicated subject, but the Engine module features natives that let you modify the properties of entities, or search for entities in game by their class/owner (class is the type of entity, such as "player").

For this example, we'll make an entity that looks like a fake player holding a gun.

<pawn> //create a basic entity
entid = create_entity("info_target")
//set its classname
entity_set_string(entid, EV_SZ_classname, "some_guy")
//set its model
entity_set_model(entid, "models/w_suit.mdl")
new Float:Vec[3] = {0.0,0.0,0.0}
//set its origin
entity_set_origin(entid, Vec)
//set some basic properties
entity_set_int(entid, EV_INT_solid, 1)
entity_set_int(entid, EV_INT_movetype, 6)
//create the weapon - thanks to pimp_daddy!
entWeapon = create_entity("info_target")
entity_set_string(entWeapon, EV_SZ_classname, weapString)
//set to follow
entity_set_int(entWeapon, EV_INT_movetype, MOVETYPE_FOLLOW)
entity_set_int(entWeapon, EV_INT_solid, SOLID_NOT)
entity_set_edict(entWeapon, EV_ENT_aiment, entid)
entity_set_model(entWeapon, "models/p_m4a1.mdl")
</pawn>

You can also change other basic things, such as:

<pawn>//how set_user_armor() works in the fun module
stock set_armor(player, Float:value)
{
entity_set_int(player, EV_FL_armorvalue, value)
}
</pawn>

=FakeMeta=

FakeMeta is the next generation of Half-Life scripting. It essentially lets you write MetaMod plugins in Pawn. It is extremely powerful, and for this reason, it won't really be covered here. This is just to tell you what it is capable of.

* Engine/DLL Calls
**There are two types of functions in the HL namespace - Engine functions and DLL functions (DLL functions are ones the game/mod library must export). Both of these can be called using the FakeMeta module using the dllfunc() and engfunc() natives. The parameters are directly passed on to MetaMod, so be careful! You could easily crash a server doing the wrong thing.
* Engine/DLL Hooks
**As stated above, HL provides Engine and DLL functions. You can also hook/supercede these calls using register_forward. You can supercede these calls using fm_return() and return PLUGIN_HANDLED. Again, make sure you know what you are doing. Malformed hooks will cause crashes.
* Easy entity manipulation
**FakeMeta replaces Engine's entity__() function with a natives called "pev()" and "set_pev()". They are a bit easier to use. For more information see the fakemeta includes.
* Private Offset Hacking
**Private offsets are offsets into a block of memory called "pvPrivateData". The right offsets can often modify game-specific features, such as money in Counter-Strike, or resources in Natural-Selection. However, the wrong offsets can cause game crashes.

[[Category:Scripting (AMX Mod X)]]

Sample Plugins (Metamod:Source)

2006-05-16T06:01:52Z

Belsebub: Reverted edit of Venusparkle85

This guide briefly explains about and how to compile the sample plugins for SourceMM.

=Sample Plugins=
==stub_mm==
This plugin is a bare-minimum example of what you need to build a [[SourceMM]] plugin. It implements the ISmmPlugin class, exposes it as a DLL, and nothing more. As a single example, it also hooks ServerActivate in IServerGameDLL. "Stub" was designed such that a developer could open it and quickly modify it to begin a plugin.

*meta_hooks.h - Definition of main hooks
*stub_mm.cpp - Main plugin file and implementation
*stub_mm.h - Main plugin header

==sample_mm==
This plugin attempts to recreate all of the functionality a Server Plugin has. Server Plugins receive twelve callbacks, three of which are GameDLL overridable. In order to replicate this functionality, sample_mm hooks eleven of the callbacks as either post or pre handlers. Furthermore, it also demonstrates how to build a CallClass for calling original functions. Every hook produces a log message so you can see when events occur.

Sample_mm fully replicates every callback a Server Plugin is capable of receiving, except for NetworkIDValidated. This callback has no known representation in the engine, is not very useful, and can be replicated easily with GameFrame() (in the future, we might demonstrate this). If you are having trouble porting a Server Plugin over, or are wondering how you can keep the same features, this plugin will show you where to start.

*meta_hooks.h - Definition of main hooks
*SamplePlugin.cpp - Main plugin file and implementation
*SamplePLugin.h - Main plugin header

=Where to Get=
You can find the source code to the sample plugins in either the source code package or [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/ CVS]. They are located in the main source code folder in "stub_mm" and "sample_mm".

=Compiling=
==Windows==
These plugins have been compiled and tested with Microsoft Visual Studio 7.1 (.NET 2003). Before you compile, you must have these directories in your include options. To set these, go to Tools, Options, Projects, VC++ Directories.

*From the Include Files menu, add these HL2SDK paths:
**public
**public/dlls
**public/engine
**public/tier0
**public/tier1
**public/vstdlib
**tier1
*From the Library Files menu, add these HL2SDK paths:
**lib/public
*From the Include Files menu, add these SourceMM paths:
**sourcemm
**sourcemm/sourcehook
**sourcemm/sourcemm

You can then open the .vcproj project file. Go to Build, Set Active Configuration, and select Release. You can then select Build from the Build menu, which will produce a .dll file in the Release folder in the project folder.

==Linux==
To build on Linux, you must have a copy of Source Dedicated Server installed. Open the project Makefile and edit the following lines at the top:

*SRCDS - Location of main srcds installation
*SMM_ROOT - Location of folder containing sourcemm and sourcehook
*HL2SDK - Location of HL2SDK

Once done, you can just type "make" to run the build scripts. The binary will appear in ./Release/.

[[Category:Documentation (SourceMM)]]

AMX Mod X 1.75 Scripting Changes

2006-05-13T18:50:01Z

Belsebub: gaben

Sample Plugins (Metamod:Source)

2006-03-30T16:35:13Z

Belsebub: Reverted edit of Dayve

Metamod:Source Development

2006-03-28T09:55:35Z

Belsebub: added a missing )

This article is an introduction to [[SourceMM]] coding.

{{qnotice|The majority of this documentation should be merged or moved into an article about [[SourceHook]].}}

{{qnotice|This article probably needs some better formatting.}}

=Requirements=
You must have the Valve [[HL2SDK]], available from your [[Steam]] Menu. For Windows, you must have [[Microsoft Visual Studio]] 7.0 or 7.1 (we have not tried 6.0). For [[Linux]], Valve requires you use at least [[GCC]] 3.4.1. You should also have a copy of the [[Metamod:Source]] source code, available [http://www.sourcemm.net/ here] (sourcemm/sourcehook and sourcemm/sourcemm).

For [[Microsoft Visual Studio]], you should make sure that you have the following HL2SDK paths in your include settings (Tools -> Options -> Projects, VC++ Directories, Include Files), as well as the "sourcehook" and "sourcemm" folders:
*dlls
*public
*public\vstdlib
*public\tier1
*public\tier0
*public\engine
*public\dlls
*tier1
*lib\public (this should be in your Library Paths!)

=Plugin API=
In order to write a plugin, you must implement the ISmmPlugin interface, similar to IServerPluginCallbacks. Each Metamod:Source release has a minimum required interface version and a current version. The minimum version is guaranteed to be upward compatible to the current, however, it may be lacking some features.

Once you've implemented the interface, you must also have a global singleton of your plugin available. There are a few macros to assist you in properly exposing the interface as a DLL and setting up the API states.

*{{bcode|PLUGIN_GLOBALVARS}}() - Place in header. Declares the global variables that some API calls require (such as g_SHPtr and g_PLAPI).
*{{bcode|PLUGIN_EXPOSE}}(class, singleton) - Place in .cpp file. Declares the external CreateInterface function which exposes the API.
*{{bcode|PLUGIN_SAVEVARS}}() - Use first thing in ISmmPlugin::Load(), saves the global variables sent from SourceMM.

The actual plugin API you must implement as of this writing is version 004. To see a description of each of the functions, you can view the doxygen information here. Note that the Load, Unload, Pause, and Unpause functions allow you to refuse the action and copy an error message (you should check to make sure error is not NULL - it can be).

=SourceHook (Hooking)=
SourceHook is the engine used to intercept function calls, much like Metamod. The difference with SourceHook is that it can intercept any virtual function in any class that, at compile time, you have the header for. SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you can safely remove it.

For example, let's say you wanted to intercept log messages in VEngineServer. Observe the prototype:
<pre>
virtual void LogPrint( const char *msg ) = 0;
</pre>
This is a virtual, public function of a class we have an instance of (let's say in IVEngineServer *m_Engine) and that we have the header for. It can be intercepted.

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
</pre>
This line must appear outside of a function. It means "Declare a hook prototype for LogPrint in IVEngineServer, which is a void function that has one parameter, which is a const char *".

Next we must actually hook the function. You can do this wherever you want to begin the interception. The two macros for hooking look like this:

*{{bcode|SH_ADD_HOOK_STATICFUNC}}(class, memberfunction, instance_pointer, handler, post) Hooks a virtual function to a static/global function.
**class - The name of the class
**memberfunction - The name of the member function
**instance - A pointer to an instance of the class
**handler - Your function that will be called on hooking
**post - true for post operation, false for pre operation
*{{bcode|SH_ADD_HOOK_MEMFUNC}}(class, memberfunction, instance, myinstance, myfunction, post) Hooks a virtual function to a member function of another class.
**class - The name of the class
**memberfunction - The name of the member function
**instance - An pointer to an instance of the class
**myinstance - A pointer to an instance of the class that has the handler member function
**myfunction - The name of the handler member function in your class
**post - true for post operation, false for pre-operation

Let's continue with the example. To hook LogPrint to a function in your class, CMetaHooks (instance, g_MetaHooks), you would use:
<pre>
SH_ADD_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine, &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
To remove the hook (either once it will no longer be unused, or at unload time):
<pre>
SH_REMOVE_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
Now, your function contents will look something like this:
<pre>
void CMetaHooks::LogPrint(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note this return statement. This style of returning is similar to Metamod's, where you can set four different flags to indicate how you would like SourceHook to proceed. In Metamod, this return statement was required. In SourceMM, it is only required if you wish to set a return state other than MRES_IGNORED.

*{{bcode|MRES_IGNORED}} - No states were changed, act as though nothing happened. Original function is still called.
*{{bcode|MRES_HANDLED}} - Something changed, but the original function was still called. This can be used to tell another plugin that you did something.
*{{bcode|MRES_OVERRIDE}} - The original function will still be called, but your return value will override whatever it returns.
*{{bcode|MRES_SUPERCEDE}} - The original function is not called, and your return value will be what is returned to the caller.

Note, that if you need to return a value, there is another macro. For example:
<pre>
RETURN_META_VALUE(MRES_SUPERCEDE, value);
</pre>
This is required for non-void functions, athough the return value is ignored using MRES_IGNORED or MRES_HANDLED.

Alternatively, you can hook to static member functions which has a slightly easier syntax. The DECL_HOOK line does not change. To add the hook:
<pre>
SH_ADD_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Removing the hook:
<pre>
SH_REMOVE_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Declaring the handler:
<pre>
void LogPrint_handler(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note that vafmt functions hooked with SourceHook assume that the vafmt is for a printf style string, and that the vafmt occurs at the end. When setting the parameters, you do not include the '...' notation, and SourceHook will vafmt the input string for you (meaning you also don't specify ... in your hooked function).

=Calling Original Functions=
Often it will be necessary for you to call a function that's hooked, however, you don't want the hooks to be included in the calling. For example, if you want to entirely supercede a function and call it yourself from within a hook. To do this, you must request a call class. This is similar to MDLL_x() from Metamod for Half-Life 1.

Continuing with the above example, let's say we want to supercede the original call and log a different message. Assume we also have the pointer m_Engine which is a <tt>IVEngineServer *</tt>.
<cpp>
SourceHook::CallClass<IVEngineServer> *Engine_CC = SH_GET_CALLCLASS(m_Engine);

SH_CALL(Engine_CC, &IVEngineServer::LogPrint)("This is a log message!\n");

//When you are done with the pointer..
SH_RELEASE_CALLCLASS(Engine_CC);
</cpp>

Because of the complex nature of inheritance, instance pointers, and vtables, this syntax can be quite daunting. You may wish to make macros for specific functions or classes you use quite often, to reduce the amount of typing. For example:
<cpp>
//Assuming you have a global pointer g_Engine...
#define ENGCALL(func) SH_CALL(g_Engine, &IVEngineServer::func)

//Then you can do:
ENGCALL(LogPrint)("This is a test!");
</cpp>

The syntax of calling class construction is:
*<tt>SourceHook::CallClass<class> *ptr = SH_GET_CALLCLASS(instance);</tt>
**Returns an object which allows you to call the original function. Class is the name of the class which is the target, instance is an instance of that class.
*<tt>SH_CALL(cc_ptr, &class::func)([params])</tt>
**Pass the pointer returned from SH_GET_CALLCLASS as cc_ptr. The target function you call must be passed as a pointer-to-member-function, which takes the form &Class::Function as seen in previous examples. You must then complete the function call by adding a parenthetical parameter expression, even for void functions, which would be ().

=Other Macros=
All of the macros take g_PLAPI as the first parameter. For more information on this, see the global variables section.

*{{bcode|META_CONPRINT}}(const char *msg)
*{{bcode|META_CONPRINTF}}(const char *fmt, ...)
**These two functions are recommended over Msg() for printing to the server console. Msg() does not relay commands back through rcon, and as of this writing Valve does not expose the function which does. To be able to display text through the rcon console (much like HL1), you should use these functions. If SourceMM is unable to extract the function properly, it will automatically default to Msg.
*{{bcode|META_LOG}}(g_PLAPI, const char *msg, ...)
**Logs a message through IVEngineServer::LogPrint(). A newline is automatically added, and msg is formatted as a sprintf() style string.
*{{bcode|META_REGCVAR}}(var)
**Registers a ConCommandBase pointer through SourceMM. The correct way to use this is to create an IConCommandBaseAccessor, and inside RegisterConCommandBase, call the macro on the given ConComandBase. This will ensure that SourceMM correctly detects and unloads your cvars and concommands at the appopriate time. Otherwise, unloading your plugin will cause a crash.
*{{bcode|META_UNREGCVAR}}(var)
**Unregisters a ConCommandBase pointer. This is not needed if you have set up your IConCommandBaseAccessor correctly (and called ConCommandBaseMngr::OneTimeInit()).

=Events System=
The Events System is based on IMetamodListener. By implementing the IMetamodListener class and using g_SMAPI->AddListener, you can watch for certain, low-traffic events. These events are split into three categories:

*Plugin Events let you listen for plugin pauses and unloads. This is important if you're relying on information from another plugin, as you can handle cases where a live plugin has become invalid.
*Game Events are simple events that SourceMM is already hooking and makes available. These are LevelShutdown and LevelInit right now.
*Query Events occur when a factory is used. The four main factories (Engine, GameDLL, FileSystem, and Physics) are all overridable. You should simply return a non-NULL result to override, and fill the return code with IFACE_OK if available. There is no way to handle the case of two plugins overriding right now. The final factory is the Metamod Factory, which is the factory that Metamod:Source adds to the runtime space for plugins. By default, it only contains the interfaces for the PluginManager and SourceHook. Plugins can use this to add new interfaces. Other plugins request these interfaces through g_SMAPI->MetaFactory().

=Global Variables=
These global variables are saved by PLUGIN_EXPOSE and PLUGIN_SAVEVARS. They are declared with PLUGIN_GLOBALVARS.

*{{bcode|g_PLAPI}}
**ISmmPlugin * pointer to your global class singleton.
*{{bcode|g_PLID}}
**The internal PluginId of your plugin.
*{{bcode|g_SHPtr}}
**The SourceHook::ISourceHook * pointer to SourceHook's interface.
*{{bcode|g_SMAPI}}
**The ISmmAPI * pointer to SourceMM's interface.

=Compiling=
To see more about compiling, see the Sample Plugin Compiling section.

Modifying the default Makefiles for your own projects:

*<tt>OPT_FLAGS</tt> - Optimization flags
*<tt>DEBUG_FLAGS</tt> - Debug flags
*<tt>CPP</tt> - C++ Compiler
*<tt>OBJECTS</tt> - List of C++ files to compile
*<tt>LINK</tt> - Linker Options
*<tt>CFLAGS</tt> - Base Compiler Flags
*<tt>BINARY</tt> - Output Binary Name

Makefile commands:

*clean - Cleans all build files
*debug - Builds debug version

=1.1 Changes - Late Loading, Events=
SourceMM 1.1 changed quite a few things internally, and externally made many breaking changes. These include:

*ISmmPlugin::Load() has removed the factory list parameter (the factory system was replaced with the event system). Also, a boolean parameter was added, specifying whether the plugin was loaded late or not.
*ISmmPlugin::Load() is now called BEFORE DLLInit(), rather than after. This means it might not have all information it needs -- for example, IGameEvents won't be parsed yet. You will need to do things like this in ISmmPlugin:AllPluginsLoaded() instead, as it is guaranteed to occur when all DLLs are initialized.
*ISmmPlugin now has default functions -- you don't have to implement all of them.
*SourceHook was modified to use interfaces rather than straight struct pointers. This breaking changes will ensure that future SourceHook modifications do not break older plugins.
*SourceHook was modified to be re-entrant.
*SourceHook now has a tiny template library with it. This removes the necessity to link against libstdc++.so.*, which harms binary compatibility across linux distributions.
*SourceMM's GameDLL code was completely rewritten. It will now work with newer mods much easier, and issues like the DoD:S release will be much easier to deal with (if at all). It also removes a few important speed bottlenecks.
*An events system was added.

=1.2 Changes - Changing Parameters, Manual Hooking=
SourceMM 1.2 now supports changing the parameters in a hook chain. For example, say the GameDLL has a function called IGameDLL::PrintString(const char *str). You can hook this, let it continue, but change the "str" parameter passed in to the rest of the hooks and the GameDLL. To do this, use the following macros:

*<tt>RETURN_META_NEWPARAMS</tt>
*<tt>RETURN_META_VALUE_NEWPARAMS</tt>

Example:
<cpp>
class ISomething
{
virtual void Function1(int num) =0;
virtual bool Function2(bool what, int hi) =0;
}

void MyHook1(int num)
{
//if num is 0,
// we will change the num parameter in the rest of the hooks, and the gamedll, to be 1.
if (num == 0)
RETURN_META_NEWPARAMS(MRES_IGNORED, &ISomething::Function1, (1))
RETURN_META(MRES_SUPERCEDE);
}

bool MyHook2(bool what, int hi)
{
//change the "what" and "hi" parameters to be false and 3 respectively
//also, return true, but specify that the value is ignored
RETURN_META_VALUE_NEWPARAMS(MRES_IGNORED, true, &ISomething::Function2, (false, 3));
}
</cpp>
SourceHook also supports manual hooking of functions. This means you must know the virtual table index, the virtual table offset (for polymorphism), and the "this" pointer offset. Luckily, the polymorphic offsets are usually zero. This type of hook is ideal when supporting different ABI, for example, across different gamedlls. The API is almost identical:

*<tt>SH_DECL_MANUALHOOKn[_void|_vafamt]</tt> -
**Declares the manual hook. A unique name must be given to each manual hook.
*<tt>SH_[ADD|REMOVE]_MANUALHOOK_[STATIC|MEM]FUNC</tt> -
**Adds or removes a static or member function hook on a manually declared hook.
*<tt>SH_MANUALHOOK_RECONFIGURE</tt> -
**Reconfigures the indexes and offsets of a manual hook.

An example is below, using the ISomething class from above.

<cpp>
SH_DECL_MANUALHOOK2(_M_Function1, 1, 0, 0, bool, bool, int);

void OnLoad(ISomething *pSomething)
{
//we reference the static function by its unique handle we gave it
//the parameters are otherwise the same - this pointer, hook handler, and post/non-post
SH_ADD_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}

void OnUnload(ISomething *pSomething)
{
SH_REMOVE_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}
</cpp>

For more examples of the above features, you can look in SourceHook CVS's [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/sourcehook/test/ test suite], which demonstrates a variety of hooking scenarios.

[[Category:SourceHook]]
[[Category:Documentation (SourceMM)]]

Troubleshooting AMX Mod X

2006-03-15T16:38:00Z

Belsebub: removed HzK's edit

[[Category:AMX_Mod_X]]
If something goes wrong with your AMX Mod X installation, it's usually a problem someone else before has had. This FAQ shows some of the more common problems with steps to solving them.

=Plugin Problems=
==Loading Errors==
{{qa|What does "function not found" mean?}}
'''A:''' This means a function the plugin uses could not be found. Most likely you forgot to enable a module that the plugin uses. Check the plugin's documentation, then see [[Configuring AMX Mod X#Modules|Configuring Modules]].

{{qa|What does "module required for plugin" mean?}}
'''A:''' See above question. If you get this error, it should also tell you exactly which module you need to enable.

{{qa|What does "Run time error ... debug not enabled" mean?}}
'''A:''' This means an internal error occured in the plugin. To enable debug mode, and report the problem to the author, add the word "debug" after the plugin's entry in amxmodx/plugins/plugins.ini. For example:
<pre>myplugin.amxx debug</pre>

For more information, see [[Debugging Plugins (AMX Mod X)|Debugging Plugins]].

{{qa|I have debug enabled and I still get run time errors!}}
'''A:''' Copy and paste the runtime errors and give them to the plugin author. If the errors occur in official AMX Mod X plugins, make a bug report.

Metamod:Source Development

2006-03-15T16:37:10Z

Belsebub: removed Phettachu's edit

This article is an introduction to [[SourceMM]] coding.

{{qnotice|The majority of this documentation should be merged or moved into an article about [[SourceHook]].}}

{{qnotice|This article probably needs some better formatting.}}

=Requirements=
You must have the Valve [[HL2SDK]], available from your [[Steam]] Menu. For Windows, you must have [[Microsoft Visual Studio]] 7.0 or 7.1 (we have not tried 6.0). For [[Linux]], Valve requires you use at least [[GCC]] 3.4.1. You should also have a copy of the [[Metamod:Source]] source code (sourcemm/sourcehook and sourcemm/sourcemm).

For [[Microsoft Visual Studio]], you should make sure that you have the following HL2SDK paths in your include settings (Tools -> Options -> Projects, VC++ Directories, Include Files), as well as the "sourcehook" and "sourcemm" folders:
*dlls
*public
*public\vsdtlib
*public\tier1
*public\tier0
*public\engine
*public\dlls
*tier1
*lib\public (this should be in your Library Paths!)

=Plugin API=
In order to write a plugin, you must implement the ISmmPlugin interface, similar to IServerPluginCallbacks. Each Metamod:Source release has a minimum required interface version and a current version. The minimum version is guaranteed to be upward compatible to the current, however, it may be lacking some features.

Once you've implemented the interface, you must also have a global singleton of your plugin available. There are a few macros to assist you in properly exposing the interface as a DLL and setting up the API states.

*{{bcode|PLUGIN_GLOBALVARS}}() - Place in header. Declares the global variables that some API calls require (such as g_SHPtr and g_PLAPI).
*{{bcode|PLUGIN_EXPOSE}}(class, singleton) - Place in .cpp file. Declares the external CreateInterface function which exposes the API.
*{{bcode|PLUGIN_SAVEVARS}}() - Use first thing in ISmmPlugin::Load(), saves the global variables sent from SourceMM.

The actual plugin API you must implement as of this writing is version 004. To see a description of each of the functions, you can view the doxygen information here. Note that the Load, Unload, Pause, and Unpause functions allow you to refuse the action and copy an error message (you should check to make sure error is not NULL - it can be).

=SourceHook (Hooking)=
SourceHook is the engine used to intercept function calls, much like Metamod. The difference with SourceHook is that it can intercept any virtual function in any class that, at compile time, you have the header for. SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you can safely remove it.

For example, let's say you wanted to intercept log messages in VEngineServer. Observe the prototype:
<pre>
virtual void LogPrint( const char *msg ) = 0;
</pre>
This is a virtual, public function of a class we have an instance of (let's say in IVEngineServer *m_Engine) and that we have the header for. It can be intercepted.

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
</pre>
This line must appear outside of a function. It means "Declare a hook prototype for LogPrint in IVEngineServer, which is a void function that has one parameter, which is a const char *".

Next we must actually hook the function. You can do this wherever you want to begin the interception. The two macros for hooking look like this:

*{{bcode|SH_ADD_HOOK_STATICFUNC}}(class, memberfunction, instance_pointer, handler, post Hooks a virtual function to a static/global function.
**class - The name of the class
**memberfunction - The name of the member function
**instance - A pointer to an instance of the class
**handler - Your function that will be called on hooking
**post - true for post operation, false for pre operation
*{{bcode|SH_ADD_HOOK_MEMFUNC}}(class, memberfunction, instance, myinstance, myfunction, post) Hooks a virtual function to a member function of another class.
**class - The name of the class
**memberfunction - The name of the member function
**instance - An pointer to an instance of the class
**myinstance - A pointer to an instance of the class that has the handler member function
**myfunction - The name of the handler member function in your class
**post - true for post operation, false for pre-operation

Let's continue with the example. To hook LogPrint to a function in your class, CMetaHooks (instance, g_MetaHooks), you would use:
<pre>
SH_ADD_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine, &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
To remove the hook (either once it will no longer be unused, or at unload time):
<pre>
SH_REMOVE_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
Now, your function contents will look something like this:
<pre>
void CMetaHooks::LogPrint(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note this return statement. This style of returning is similar to Metamod's, where you can set four different flags to indicate how you would like SourceHook to proceed. In Metamod, this return statement was required. In SourceMM, it is only required if you wish to set a return state other than MRES_IGNORED.

*{{bcode|MRES_IGNORED}} - No states were changed, act as though nothing happened. Original function is still called.
*{{bcode|MRES_HANDLED}} - Something changed, but the original function was still called. This can be used to tell another plugin that you did something.
*{{bcode|MRES_OVERRIDE}} - The original function will still be called, but your return value will override whatever it returns.
*{{bcode|MRES_SUPERCEDE}} - The original function is not called, and your return value will be what is returned to the caller.

Note, that if you need to return a value, there is another macro. For example:
<pre>
RETURN_META_VALUE(MRES_SUPERCEDE, value);
</pre>
This is required for non-void functions, athough the return value is ignored using MRES_IGNORED or MRES_HANDLED.

Alternatively, you can hook to static member functions which has a slightly easier syntax. The DECL_HOOK line does not change. To add the hook:
<pre>
SH_ADD_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Removing the hook:
<pre>
SH_REMOVE_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Declaring the handler:
<pre>
void LogPrint_handler(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note that vafmt functions hooked with SourceHook assume that the vafmt is for a printf style string, and that the vafmt occurs at the end. When setting the parameters, you do not include the '...' notation, and SourceHook will vafmt the input string for you (meaning you also don't specify ... in your hooked function).

=Calling Original Functions=
Often it will be necessary for you to call a function that's hooked, however, you don't want the hooks to be included in the calling. For example, if you want to entirely supercede a function and call it yourself from within a hook. To do this, you must request a call class. This is similar to MDLL_x() from Metamod for Half-Life 1.

Continuing with the above example, let's say we want to supercede the original call and log a different message. Assume we also have the pointer m_Engine which is a <tt>IVEngineServer *</tt>.
<cpp>
SourceHook::CallClass<IVEngineServer> *Engine_CC = SH_GET_CALLCLASS(m_Engine);

SH_CALL(Engine_CC, &IVEngineServer::LogPrint)("This is a log message!\n");

//When you are done with the pointer..
SH_RELEASE_CALLCLASS(Engine_CC);
</cpp>

Because of the complex nature of inheritance, instance pointers, and vtables, this syntax can be quite daunting. You may wish to make macros for specific functions or classes you use quite often, to reduce the amount of typing. For example:
<cpp>
//Assuming you have a global pointer g_Engine...
#define ENGCALL(func) SH_CALL(g_Engine, &IVEngineServer::func)

//Then you can do:
ENGCALL(LogPrint)("This is a test!");
</cpp>

The syntax of calling class construction is:
*<tt>SourceHook::CallClass<class> *ptr = SH_GET_CALLCLASS(instance);</tt>
**Returns an object which allows you to call the original function. Class is the name of the class which is the target, instance is an instance of that class.
*<tt>SH_CALL(cc_ptr, &class::func)([params])</tt>
**Pass the pointer returned from SH_GET_CALLCLASS as cc_ptr. The target function you call must be passed as a pointer-to-member-function, which takes the form &Class::Function as seen in previous examples. You must then complete the function call by adding a parenthetical parameter expression, even for void functions, which would be ().

=Other Macros=
All of the macros take g_PLAPI as the first parameter. For more information on this, see the global variables section.

*{{bcode|META_CONPRINT}}(const char *msg)
*{{bcode|META_CONPRINTF}}(const char *fmt, ...)
**These two functions are recommended over Msg() for printing to the server console. Msg() does not relay commands back through rcon, and as of this writing Valve does not expose the function which does. To be able to display text through the rcon console (much like HL1), you should use these functions. If SourceMM is unable to extract the function properly, it will automatically default to Msg.
*{{bcode|META_LOG}}(g_PLAPI, const char *msg, ...)
**Logs a message through IVEngineServer::LogPrint(). A newline is automatically added, and msg is formatted as a sprintf() style string.
*{{bcode|META_REGCVAR}}(var)
**Registers a ConCommandBase pointer through SourceMM. The correct way to use this is to create an IConCommandBaseAccessor, and inside RegisterConCommandBase, call the macro on the given ConComandBase. This will ensure that SourceMM correctly detects and unloads your cvars and concommands at the appopriate time. Otherwise, unloading your plugin will cause a crash.
*{{bcode|META_UNREGCVAR}}(var)
**Unregisters a ConCommandBase pointer. This is not needed if you have set up your IConCommandBaseAccessor correctly (and called ConCommandBaseMngr::OneTimeInit()).

=Events System=
The Events System is based on IMetamodListener. By implementing the IMetamodListener class and using g_SMAPI->AddListener, you can watch for certain, low-traffic events. These events are split into three categories:

*Plugin Events let you listen for plugin pauses and unloads. This is important if you're relying on information from another plugin, as you can handle cases where a live plugin has become invalid.
*Game Events are simple events that SourceMM is already hooking and makes available. These are LevelShutdown and LevelInit right now.
*Query Events occur when a factory is used. The four main factories (Engine, GameDLL, FileSystem, and Physics) are all overridable. You should simply return a non-NULL result to override, and fill the return code with IFACE_OK if available. There is no way to handle the case of two plugins overriding right now. The final factory is the Metamod Factory, which is the factory that Metamod:Source adds to the runtime space for plugins. By default, it only contains the interfaces for the PluginManager and SourceHook. Plugins can use this to add new interfaces. Other plugins request these interfaces through g_SMAPI->MetaFactory().

=Global Variables=
These global variables are saved by PLUGIN_EXPOSE and PLUGIN_SAVEVARS. They are declared with PLUGIN_GLOBALVARS.

*{{bcode|g_PLAPI}}
**ISmmPlugin * pointer to your global class singleton.
*{{bcode|g_PLID}}
**The internal PluginId of your plugin.
*{{bcode|g_SHPtr}}
**The SourceHook::ISourceHook * pointer to SourceHook's interface.
*{{bcode|g_SMAPI}}
**The ISmmAPI * pointer to SourceMM's interface.

=Compiling=
To see more about compiling, see the Sample Plugin Compiling section.

Modifying the default Makefiles for your own projects:

*<tt>OPT_FLAGS</tt> - Optimization flags
*<tt>DEBUG_FLAGS</tt> - Debug flags
*<tt>CPP</tt> - C++ Compiler
*<tt>OBJETS</tt> - List of C++ files to compile
*<tt>LINK</tt> - Linker Options
*<tt>CFLAGS</tt> - Base Compiler Flags
*<tt>BINARY</tt> - Output Binary Name

Makefile commands:

*clean - Cleans all build files
*debug - Builds debug version

=1.1 Changes - Late Loading, Events=
SourceMM 1.1 changed quite a few things internally, and externally made many breaking changes. These include:

*ISmmPlugin::Load() has removed the factory list parameter (the factory system was replaced with the event system). Also, a boolean parameter was added, specifying whether the plugin was loaded late or not.
*ISmmPlugin::Load() is now called BEFORE DLLInit(), rather than after. This means it might not have all information it needs -- for example, IGameEvents won't be parsed yet. You will need to do things like this in ISmmPlugin:AllPluginsLoaded() instead, as it is guaranteed to occur when all DLLs are initialized.
*ISmmPlugin now has default functions -- you don't have to implement all of them.
*SourceHook was modified to use interfaces rather than straight struct pointers. This breaking changes will ensure that future SourceHook modifications do not break older plugins.
*SourceHook was modified to be re-entrant.
*SourceHook now has a tiny template library with it. This removes the necessity to link against libstdc++.so.*, which harms binary compatibility across linux distributions.
*SourceMM's GameDLL code was completely rewritten. It will now work with newer mods much easier, and issues like the DoD:S release will be much easier to deal with (if at all). It also removes a few important speed bottlenecks.
*An events system was added.

=1.2 Changes - Changing Parameters, Manual Hooking=
SourceMM 1.2 now supports changing the parameters in a hook chain. For example, say the GameDLL has a function called IGameDLL::PrintString(const char *str). You can hook this, let it continue, but change the "str" parameter passed in to the rest of the hooks and the GameDLL. To do this, use the following macros:

*<tt>RETURN_META_NEWPARAMS</tt>
*<tt>RETURN_META_VALUE_NEWPARAMS</tt>

Example:
<cpp>
class ISomething
{
virtual void Function1(int num) =0;
virtual bool Function2(bool what, int hi) =0;
}

void MyHook1(int num)
{
//if num is 0,
// we will change the num parameter in the rest of the hooks, and the gamedll, to be 1.
if (num == 0)
RETURN_META_NEWPARAMS(MRES_IGNORED, &ISomething::Function1, (1))
RETURN_META(MRES_SUPERCEDE);
}

bool MyHook2(bool what, int hi)
{
//change the "what" and "hi" parameters to be false and 3 respectively
//also, return true, but specify that the value is ignored
RETURN_META_VALUE_NEWPARAMS(MRES_IGNORED, true, &ISomething::Function2, (false, 3));
}
</cpp>
SourceHook also supports manual hooking of functions. This means you must know the virtual table index, the virtual table offset (for polymorphism), and the "this" pointer offset. Luckily, the polymorphic offsets are usually zero. This type of hook is ideal when supporting different ABI, for example, across different gamedlls. The API is almost identical:

*<tt>SH_DECL_MANUALHOOKn[_void|_vafamt]</tt> -
**Declares the manual hook. A unique name must be given to each manual hook.
*<tt>SH_[ADD|REMOVE]_MANUALHOOK_[STATIC|MEM]FUNC</tt> -
**Adds or removes a static or member function hook on a manually declared hook.
*<tt>SH_MANUALHOOK_RECONFIGURE</tt> -
**Reconfigures the indexes and offsets of a manual hook.

An example is below, using the ISomething class from above.

<cpp>
SH_DECL_MANUALHOOK2(_M_Function1, 1, 0, 0, bool, bool, int);

void OnLoad(ISomething *pSomething)
{
//we reference the static function by its unique handle we gave it
//the parameters are otherwise the same - this pointer, hook handler, and post/non-post
SH_ADD_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}

void OnUnload(ISomething *pSomething)
{
SH_REMOVE_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}
</cpp>

For more examples of the above features, you can look in SourceHook CVS's [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/sourcehook/test/ test suite], which demonstrates a variety of hooking scenarios.

[[Category:SourceHook]]
[[Category:Documentation (SourceMM)]]

Metamod

2006-03-12T14:45:20Z

Belsebub: removed Bbz's changes

[[Category:Half-Life_1]]
Metamod is a plugin/DLL manager that sits between the [[Half-Life_1|Half-Life]] Engine and an HL Game mod, allowing the dynamic loading/unloading of mod-like DLL plugins to add functionality to the HL server or game mod.

[[AMX_Mod_X|AMX Mod X]] is a Metamod plugin.

{{Stub}}

Optimizing Plugins (AMX Mod X Scripting)

2006-03-10T16:46:53Z

Belsebub: changed all 1.65 to 1.70

==Introduction==
[[Admin-Mod]] and [[AMX Mod X]] became very popular because of their easy to use scripting language. However, the words "scripting language" come with a lot of loaded preconceptions. Most people assume that because it's scripted:
*You can't possibly make it any faster
*It's pre-compiled, so it's already quite fast
*Details don't matter, as it's only "scripting" anyway

Especially, with [[Pawn]] (formerly Small), none of these are true. The compiler, in fact, is very poor at optimizing, and you can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

===Terms===
To read this document, you will need to understand a few concepts beforehand:
*<tt>BRANCHING</tt> - When the processor takes a different path of code. For example, to call a function or to use an if statement, the processor will "branch". Modern processors attempt to predict pathways with "branch prediction", but it's best to avoid branching a lot if possible.
*<tt>STACK ALLOCATION</tt> - In Pawn, all local data is stored on the stack, a big chunk of continuous memory. Whenever you create a variable on the stack, it is automatically written with zeroes.
*<tt>HEAP ALLOCATION</tt> - In Pawn, temporary data that needs to be referenced by a native is stored on the heap, another area of contiguous, but less restrictive memory.
*<tt>DATA SECTION</tt> - This is an area of memory built into your .amxx file. In fact, it "becomes" the heap at load time. All your strings and arrays are hardcoded into this area.
*<tt>EXPENSIVENESS</tt> - To be "expensive" in computer science means an operation requires a lot of CPU processing. It usually does not refer to memory size, only to processing cycles and time. Addition is inexpensive, floating power operations are expensive. However, both are inexpensive in comparison to writing a file. An inexpensive operation can also be called "cheap".
*<tt>BIG-OH NOTATION</tt> - O(*) notation refers to the expensiveness of an algorithm. If something is O(n), it occurs in linear time -- meaning that for N items, it will complete relative to N. O(N^2) means with N items, it will complete relative to N^2. O(1) means "constant time" - no matter what N is, it will run in the same amount of time.

==Compiler Optimizations==
These optimizations have to do with changing how your code is compiled. While the syntax may remain the same, you are not only increasing compile time, but increasing your plugin's efficiency and speed at run time.

===Always Save Results===
Observe the example code snippet below:
<pawn>if (get_user_team(player) == TEAM_T)
{
//...code
} else if (get_user_team(player) == TEAM_CT) {
//...code
} else if (get_user_team(player) == TEAM_SPECTATOR) {
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
</pre>
Notice the problem? We have called <tt>get_user_team</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = get_user_team(player)
if (team == TEAM_T)
{
//...code
} else if (team == TEAM_CT) {
//...code
} //...etc</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+BRANCH
COMPARE+BRANCH
COMPARE+BRANCH
</pre>
If <tt>get_user_team</tt> were an expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case.

===Switch instead of If===
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an if statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = get_user_team(player)
switch (team)
{
case TEAM_T:
//code...
case TEAM_CT:
//code...
case TEAM_SPECTATOR:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values, which the virtual machine knows to browse through:
<pre>
CALL get_user_team
COMPARE
COMPARE
COMPARE
</pre>

===Don't Re-index Arrays===
A common practice in Small is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below:
<pawn>new players[32], num, team
get_players(players, num)
for (new i=0; i<num; i++)
{
if (!is_user_connected(players[i]))
continue;
team = get_user_team(players[i])
set_user_frags(players[i], 0)
}</pawn>
For this, the compiler generates code similar to:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
CALL is_user_connected
LOAD i
LOAD players
CALC
LOAD players[i]
CALL get_user_team
LOAD i
LOAD players
CALC
LOAD players[i]
CALL set_user_frags
</pre>
See what happened? The compiler does not cache array indexing. Because we've used <tt>players[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>players</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:
<pawn>new player
for (new i=0; i<num; i++)
{
player = players[i]
if (!is_user_connected(player))
continue;
team = get_user_team(player)
}</pawn>
Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
STORE player
CALL is_user_connected
LOAD player
CALL get_user_team
LOAD player
CALL set_user_frags
</pre>
In a large loop you can drastically reduce codesize in this manner.

===Global vs Local and Variables in Loops===
It is important to realize that every variable in [[Pawn]] is automatically zeroed. For global variables, they are static and permanent, thus they are zeroed when your plugin is loaded. Variables in functions, however, must be zeroed dynamically. This is a slow and tedious operation, and you should not only avoid relying on it when necessary, but you should keep that fact in mind when using arrays.

[[Arrays]] in [[Pawn]] are "cells" of data. Each cell is four or eight bytes, depending on whether your processor is 32bit or 64bit. To create an array of 4096 cells, for example:
<pawn>new array[4096]</pawn>
The compiler generates code to manually zero every single one of the 16,384 bytes in that location. Normally, this isn't too bad -- but it can be absolutely deadly in a function which is called quite often. For example, <tt>server_frame</tt> is called on every [[server tick]] in [[AMX Mod X]]. To declare an array of that size in <tt>server_frame</tt> is highly unnecessary. Instead, you can take advantage of the fact that not only are globals free of charge, but <tt>server_frame</tt> does not need to be re-entrant. That is, you will never call <tt>server_frame</tt> inside of <tt>server_frame</tt>, so making the variable global will not bring up the problem of one instance of the function overwriting data from another instance of the same function. Observe:
<pawn>new g_serverframe_array[4096]
public server_frame()
{
//...code that uses g_serverframe_array
}</pawn>
This will execute conseridably faster. You can do this with smaller arrays too.

Likewise, it is equally important to avoid declaring arrays inside of loops. Consider the following block of code:
<pawn>for (new i=0; i<num; i++)
{
new message[255], name[32], player
player = players[i]
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
If there are 32 players, this loop will actually resize and zero out over 1K of memory thirty two times in a row. Not good! However, on the other hand, it's nice that the message is zeroed out for us each time. <tt>Tip:</tt> you often only need to zero out the first character of a string. This will make the entire string empty. The code below is much more efficient:
<pawn>new message[255], name[32], player
for (new i=0; i<num; i++)
{
player = players[i]
name[0] = '^0'
message[0] = '^0'
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
This has the effect of safely making the string empty beforehand, as well as largely reducing a lot of run-time overhead.

===Static vs Global===
An alternative to global variables is static variables, which are internally the same but easier to work with for programming.

A variable declared with the keyword "static" instead of "new" operates in the same way a global does (it is created only once) but the variable is local to the function; this means the code is much easier to read, while drastically improving speed just like a global variable. Example:
<pawn>stock SomeBigFunction()
{
static gaben[255];
format(gaben, "%L", LANG_SERVER, "STUFF");
}</pawn>

This has the same effect as declaring <tt>gaben</tt> as global, except only <tt>SomeBigFunction</tt> can use it.

{{qnotice|Be careful of re-entrancy!}}
When a variable is static, it has the same re-entrancy problems of a global variable. That means, if your function might be called recursively, or twice in the same stack frame, you should not use static variables. This is most often the case for API provided to other plugins or helper functions. Triggered events are usually never called twice on the same execution chain.

===Constant variables===
You can declare a variable "constant" by adding the "const" keyword before the variable name:

<pawn>new const AMX_GABEN[] = "amx_gaben"</pawn>

What this does is prevents the variable from being changed; essentially, you've locked the variable to a certain value. In this way, a constant can offer a type safe method of simplifying code, unlike a define, which is not type safe.

In addition, constant variables are often optimized out, resulting in quicker and smaller code.

===For Loop Comparisons===
A common mistake is to write code like this:
<pawn>new string[256] = "something long"
for (new i=0; i<strlen(string); i++)
//...code</pawn>
This plays off a similar principle from before: cache results. The compiler will actually recompute your string length on each iteration of the loop. This will have even worse effects if your string changes mid-loop. A more sensible method is:
<pawn>new string[256] = "something long"
new len = strlen(string)
for (new i=0; i<len; i++)
//...code</pawn>

==Tips and Tricks==
===Lookup Tables===
Precompute what can be precomputed. For example, say you have a mapping of weapon indices to names:
<pawn>if (weapon == CSW_AK47)
copy(name, len, "weapon_ak47")</pawn>
Ignoring the fact that we have <tt>get_weapon_name</tt> in [[AMX Mod X]], this is inefficient. We could precompute this result in a table:
<pawn>new g_WeaponNamesTable[TOTAL_WEAPONS][] = {
//..0 to CSW_AK47-1
"weapon_ak47",
//..CSW_AK47+1 to TOTAL_WEAPONS-1
};</pawn>

===Perfect Hashing===
:TODO: explain this

===Local Strings===
The [[Pawn]] compiler does not optimize the DATA section, which stores all hardcoded strings and global arrays. If you reference the same hardcoded string 500 times in your plugin, it will appear 500 different times. If this seems bad enough, it actually does this with all strings. For example, the empty string ("") appears everywhere in the include files, usually used as a default parameter to many natives. This too is copied into the data section for each unique reference.

For example:
<pawn>set_cvar_string("amx_gaben", get_cvar_string("amx_gaben") + 1)</pawn>
This will create two copies of "amx_gaben" in the DATA section. While this doesn't really hurt, it does increase the size of your plugin.

Similarly, this has the same problem:
<pawn>#define AMX_GABEN "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>
The only way to avoid this mess is to use global variables. As stated earlier, they're basically free storage.
<pawn>new AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Again, while not necessary, this will reduce your plugin's size in memory and on disk. If you're already using defines, you can make this switch easily.

In order to prevent this from changing, you may want to declare it constant:

<pawn>new const AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Now it is a perfectly safe method of storage.

==Faster Natives==
AMX Mod X replaces many of the old AMX Mod natives with faster versions. Read below to discover them.

===Cvar Pointers===
As of AMX Mod X 1.70, you can cache "cvar pointers". These are direct accesses to cvars, rather than named access. This is a critical optimization which is dozens of times faster. For example:
<pawn>new g_enabled = register_cvar("csdm_enabled", "1")
//OR
new g_enabled = get_cvar_pointer("csdm_enabled")

stock SetCSDM(num)
set_pcvar_num(g_enabled, num)

stock GetCSDM()
return get_pcvar_num(g_enabled)
</pawn>
All of the cvar* functions (except for set_cvar_string) are mapped to [get|set]_pcvar_*. You can get a cached cvar pointer with get_cvar_pointer() or register_cvar().

===FormatEX===
As of AMX Mod X 1.70, there is an ultra high-speed version of format() called formatex(). It skips copy-back checking, unlike format(). formatex() cannot be used if a source input is the same as the output buffer. For example, these are invalid:
<pawn>new buffer[255]
formatex(buffer, 254, "%s", buffer);
formatex(buffer, 254, buffer);
formatex(buffer, 254, "%d %s", buffer[2]);</pawn>

It should be noted that format() will behave the same as formatex() if it detects that there will be no copy-back needed. However, formatex() does not check this, and thus is slightly faster for situations where the coder is sure of its usage.

===File Writing===
As of AMX Mod X 1.70, there are new natives for file writing. Read_file and write_file are O(n^2) functions for consecutive read/writes. fopen(), fgets(), fputs(), and fclose() are O(n) (or better) depending on how you use them.

[[Category:Scripting (AMX Mod X)]]