https://wiki.alliedmods.net/api.php?action=feedcontributions&feedformat=atom&user=FyrenAlliedModders Wiki - User contributions [en]2026-05-08T15:42:15ZUser contributionsMediaWiki 1.31.6https://wiki.alliedmods.net/index.php?title=Handle_API_(SourceMod)&diff=11718Handle API (SourceMod)2024-06-26T17:44:01Z<p>Fyren: Undo revision 5690 by Zerak (talk)</p>
<hr />
<div>The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.<br />
<br />
The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.<br />
<br />
Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.<br />
<br />
<br />
=Basic Types=<br />
==Handle_t==<br />
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.<br />
<br />
Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.<br />
<br />
==HandleType_t==<br />
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types cannot have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed. <br />
<br />
Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.<br />
<br />
Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.<br />
<br />
=Security=<br />
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.<br />
<br />
==Type Security==<br />
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.<br />
<br />
Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:<br />
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.<br />
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.<br />
<br />
The <tt>HTypeAccessRight</tt> enumeration has the following values:<br />
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.<br />
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.<br />
<br />
Below is a list of each Handle System function that requires type permissions, and which permissions may be required:<br />
*<tt>CreateType</tt>: <i><tt>HTypeAccess_Inherit</tt> if a parent is specified</i><br />
*<tt>RemoveType</tt>: <i>(none, always secured)</i><br />
*<tt>CreateHandle</tt>: <i><tt>HTypeAccess_Create</tt></i><br />
<br />
==Handle Security==<br />
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike handle types, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:<br />
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.<br />
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.<br />
<br />
Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:<br />
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:<br />
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.<br />
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is only granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.<br />
<br />
The following access rights exist for Handles:<br />
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.<br />
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.<br />
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.<br />
<br />
Below is a list of each Handle system function that requires permissions, and which permissions may be required:<br />
*<tt>FreeHandle</tt>: <i><tt>HandleAccess_Delete</tt></i><br />
*<tt>CloneHandle/CloneHandleEx</tt>: <i><tt>HandleAccess_Clone</tt></i><br />
*<tt>ReadHandle</tt>: <i><tt>HandleAccess_Read</tt></i><br />
<br />
SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.<br />
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.<br />
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.<br />
<br />
=Usage Examples=<br />
Here are some examples of Handle usages.<br />
<br />
==Basic Handles==<br />
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?<br />
<br />
After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility. <br />
<br />
===Creating the type===<br />
First, we have to create the type and its Dispatch interface.<br />
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */<br />
<br />
class FileTypeHandler : public IHandleTypeDispatch<br />
{<br />
public:<br />
void OnHandleDestroy(HandleType_t type, void *object)<br />
{<br />
/* :TODO: implement this */<br />
}<br />
};<br />
<br />
/* Create an instance of the handler */<br />
FileTypeHandler g_FileTypeHandler;<br />
<br />
Initialize()<br />
{<br />
/* Register the type with default security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
NULL, <br />
myself->GetIdentity(), <br />
NULL);<br />
}<br />
<br />
Shutdown()<br />
{<br />
/* Remove the type on shutdown */<br />
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());<br />
}</cpp><br />
<br />
===Creating Handles===<br />
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.<br />
<cpp>/* native CreateFile(const String:file[]) */<br />
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)<br />
{<br />
char path[PLATFORM_MAX_PATH];<br />
char *filename;<br />
<br />
/* Get the filename */<br />
pContext->LocalToString(params[1], &filename);<br />
/* Build a full path */<br />
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);<br />
<br />
/* Open for writing */<br />
FILE *fp = fopen(path, "wt");<br />
if (!fp)<br />
{<br />
return BAD_HANDLE;<br />
}<br />
<br />
/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */<br />
return g_pHandleSys->CreateHandle(g_FileType, <br />
fp, <br />
pContext->GetIdentity(), <br />
myself->GetIdentity(), <br />
NULL);<br />
}</cpp><br />
<br />
===Reading/Checking Handles===<br />
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.<br />
<cpp>/* native bool WriteLine(Handle hndl, const char[] line); */<br />
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)<br />
{<br />
Handle_t hndl = static_cast<Handle_t>(params[1]);<br />
HandleError err;<br />
HandleSecurity sec;<br />
<br />
/* Build our security descriptor */<br />
sec.pOwner = nullptr; /* Not needed, owner access is not checked */<br />
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */<br />
<br />
/* Attempt to read the given handle as our type, using our security info.<br />
* Note that we read the pointer directly in with a little cast.<br />
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.<br />
*/<br />
FILE *fp = nullptr;<br />
if ((err = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))<br />
!= HandleError_None)<br />
{<br />
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);<br />
}<br />
<br />
/* Get the text */<br />
char *text = nullptr;<br />
pContext->LocalToString(params[2], &text);<br />
<br />
/* Write it */<br />
fputs(text, fp);<br />
<br />
return 1;<br />
}</cpp><br />
<br />
===CloseHandle Support===<br />
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.<br />
<cpp>class FileTypeHandler : public IHandleTypeDispatch<br />
{<br />
public:<br />
void OnHandleDestroy(HandleType_t type, void *object)<br />
{<br />
fclose( (FILE *)object );<br />
}<br />
};</cpp><br />
<br />
==Restricting CloseHandle==<br />
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.<br />
<br />
For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().<br />
<br />
===New Security Rules===<br />
<cpp>Initialize()<br />
{<br />
/* Create default access rights */<br />
HandleAccess rules;<br />
g_pHandleSys->InitAccessDefaults(NULL, &rules);<br />
<br />
/* Restrict delete to only our identity */<br />
rules.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;<br />
<br />
/* Register the type with our security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
&rules, <br />
myself->GetIdentity(), <br />
NULL);<br />
}</cpp><br />
<br />
===Implementing the Native===<br />
<cpp>/* native Closefile(Handle:hndl); */<br />
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)<br />
{<br />
Handle_t hndl = static_cast<Handle_t>(params[1]);<br />
HandleError err;<br />
HandleSecurity sec;<br />
<br />
/* Build our security descriptor */<br />
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */<br />
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */<br />
<br />
/* Attempt to read the given handle as our type, using our security info.<br />
* Note that we read the pointer directly in with a little cast.<br />
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.<br />
*/<br />
FILE *fp;<br />
if ((err = g_pHandleSys->FreeHandle(hndl, &sec))<br />
!= HandleError_None)<br />
{<br />
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);<br />
}<br />
<br />
return 1;<br />
}</cpp><br />
<br />
==Restricting CloseHandle Per-Handle==<br />
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.<br />
<br />
In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.<br />
<br />
===Implementation===<br />
<cpp>Handle_t g_GlobalFile;<br />
<br />
Initialize()<br />
{<br />
/* Register the type with default security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
NULL, <br />
myself->GetIdentity(), <br />
NULL);<br />
<br />
/* Create our 'global' file */<br />
FILE *fp = tmpfile();<br />
<br />
/* Set up the security descriptor */<br />
HandleSecurity sec;<br />
sec.pOwner = NULL; /* No owner for this Handle */<br />
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */<br />
<br />
/* Set up the access permissions */<br />
HandleAccess rules;<br />
g_pHandleSys->InitAccessDefaults(NULL, &rules);<br />
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;<br />
<br />
/* Finally, create the Handle with our rules */<br />
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);<br />
}<br />
<br />
Shutdown()<br />
{<br />
/* Remove our global Handle (not needed, but we do it for clarity */<br />
HandleSecurity sec;<br />
sec.pOwner = NULL;<br />
sec.pIdentity = myself->GetIdentity();<br />
<br />
g_pHandleSys->FreeHandle(g_GlobalFile, &sec);<br />
<br />
/* Remove the type on shutdown */<br />
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());<br />
}</cpp><br />
<br />
[[Category:SourceMod Development]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11330Releasing Products2022-07-24T12:59:29Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** Run <code>mount -orw /mnt/downloads</code> on web01<br />
** Run <code>mkdir /mnt/downloads/smdrop/'''''1.11'''''</code>, chmod 775 it, fix ownership<br />
** Run <code>mount -oro /mnt/downloads</code><br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update <code>~sourcemod/public_html/downloads.php</code><br />
** Add an entry to <code>~sourcemod/web-commit-updater/updater.php</code> for the new version<br />
* Gamedata updater (run commands from inside <code>~sourcemod/update</code>)<br />
** Clone the new branch into <code>'''''1.11-dev'''''</code><br />
** Create a <code>'''''update-1.11.sh'''''</code> script for the new version<br />
** Run <code>php add_version.php --version '''''1.11.0''''' --path '''''1.11-dev'''''</code><br />
** Run <code>php update/add_version.php --version '''''1.12.0''''' --path master</code><br />
** Run <code>./'''''update-1.11.sh'''''</code><br />
** Run <code>./update-master.sh</code><br />
* Web compiler and forum<br />
** Create a <code>~sourcemod/'''''compiler-1.11'''''</code> directory, drop spcomp + includes there<br />
** Change the <code>~sourcemod/compiler</code> symlink to the new version<br />
** Update hardcoded version in <code>~sourcemod/public_html/compiler.php</code> and change the "you can use this to compile plugins for SourceMod '''''1.11''''' or higher" text if necessary<br />
** Update <code>~sourcemod/public_html/vbcompiler.php</code><br />
** Update forum's newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Pull and rebuild <code>~sourcemod/scripts/sourcepawn/exp/tools/docparse</code> if needed<br />
** <code>git checkout</code> new branch into <code>~sourcemod/scripts/sourcemod</code><br />
** From <code>~sourcemod/scripts/sourcepawn/exp/docgen/generate/</code>, run <code>python generate.py</code></div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11329Releasing Products2022-07-24T12:48:43Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Create a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11.0''''' --path '''''1.11-dev'''''<br />
** Run ~sourcemod/update/add_version.php --version '''''1.12.0''''' --path master<br />
** Run ~sourcemod/update/'''''update-1.11.sh''''' and ~sourcemod/update/update-master.sh<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php and change the "you can use this to compile plugins for SourceMod '''''1.11''''' or higher" text if necessary<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11328Releasing Products2022-07-24T12:40:33Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11.0''''' --path '''''1.11-dev'''''<br />
** Run ~sourcemod/update/add_version.php --version '''''1.12.0''''' --path master<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php and change the "you can use this to compile plugins for SourceMod '''''1.11''''' or higher" text if necessary<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11327Releasing Products2022-07-15T10:00:25Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php and change the "you can use this to compile plugins for SourceMod '''''1.11''''' or higher" text if necessary<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11326Releasing Products2022-07-15T10:00:12Z<p>Fyren: one more thing</p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php and change the "you can use this to compile plugins for SourceMod '''''1.10'''' or higher" text if necessary<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11324Releasing Products2022-07-04T05:02:12Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php.<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11323Releasing Products2022-07-03T04:52:09Z<p>Fyren: reorganize procedure</p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
* General<br />
** Create a git branch<br />
** Bump sourcemod/plugins/include/version.inc numbers for manual builds<br />
* Buildbot<br />
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
** Force builds on the new dev and stable branches via pushbuild.txt<br />
* Downloads<br />
** mount -orw /mnt/downloads on web01<br />
** mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
** mount -oro /mnt/downloads<br />
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
** Update ~sourcemod/public_html/downloads.php<br />
** Add an entry to web-commit-updater/updater.php for the new version<br />
* Gamedata updater<br />
** Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
** Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
** Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Web compiler and forum<br />
** Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
** Change the ~sourcemod/compiler symlink to the new version<br />
** Update hardcoded version in ~sourcemod/public_html/compiler.php.<br />
** Update ~sourcemod/public_html/vbcompiler.php<br />
** Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* SP docs<br />
** Rebuild ~sourcemod/scripts/sourcepawn/exp/tools/docparse if needed<br />
** git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11322Releasing Products2022-07-03T03:32:05Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
<br />
* Create a git branch<br />
* Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
* mount -orw /mnt/downloads on web01<br />
* mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
* mount -oro /mnt/downloads<br />
* Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
* Update ~sourcemod/public_html/downloads.php<br />
* Update ~sourcemod/public_html/vbcompiler.php<br />
* Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
* Add an entry to web-commit-updater/updater.php for the new version<br />
* Force builds on the new dev and stable branches via pushbuild.txt<br />
* Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
* Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
* Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Change the ~sourcemod/compiler symlink to the new version<br />
* Update hardcoded verison in ~sourcemod/public_html/compiler.php.<br />
* git checkout new branch in ~sourcemod/scripts/sourcemod, then run generate.py in ~sourcemod/scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11321Releasing Products2022-07-03T03:22:49Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
<br />
* Create a git branch<br />
* Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
* mount -orw /mnt/downloads on web01<br />
* mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
* mount -oro /mnt/downloads<br />
* Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
* Update ~sourcemod/public_html/downloads.php<br />
* Update ~sourcemod/public_html/vbcompiler.php<br />
* Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
* Add an entry to web-commit-updater/updater.php for the new version<br />
* Force builds on the new dev and stable branches via pushbuild.txt<br />
* Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
* Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
* Run ~sourcemod/update/add_version.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Change the ~sourcemod/compiler symlink to the new version<br />
* Update hardcoded verison in ~sourcemod/public_html/compiler.php.<br />
* git checkout new branch in ~sourcemod/sourcemod, then generate.py in /scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11320Releasing Products2022-07-03T03:22:13Z<p>Fyren: </p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
<br />
* Create a git branch<br />
* Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
* mount -orw /mnt/downloads on web01<br />
* mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
* mount -oro /mnt/downloads<br />
* Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
* Update ~sourcemod/public_html/downloads.php<br />
* Update ~sourcemod/public_html/vbcompiler.php<br />
* Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
* Add an entry to web-commit-updater/updater.php for the new version<br />
* Force builds on the new dev and stable branches via pushbuild.txt<br />
* Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
* Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
* Run ~sourcemod/update_addversion.php --version '''''1.11''''' --path '''''1.11-dev'''''<br />
* Change the ~sourcemod/compiler symlink to the new version<br />
* Update hardcoded verison in ~sourcemod/public_html/compiler.php.<br />
* git checkout new branch in ~sourcemod/sourcemod, then generate.py in /scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11319Releasing Products2022-07-03T03:14:32Z<p>Fyren: update instructions</p>
<hr />
<div>== Releasing SourceMod ==<br />
<br />
'''''Bold italic''''' values should be replaced as appropriate for the release.<br />
<br />
* Create a git branch<br />
* Update master.cfg in buildbot buildmaster. Don't forget to push the change to github<br />
* mount -orw /mnt/downloads on web01<br />
* mkdir /mnt/downloads/smdrop/'''''1.11''''', chmod 775 it, fix ownership<br />
* mount -oro /mnt/downloads<br />
* Fix sm_commit_log by updating last ~N master builds to be the new stable branch<br />
* Update ~sourcemod/public_html/downloads.php<br />
* Update ~sourcemod/public_html/vbcompiler.php<br />
* Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull<br />
* Create a ~sourcemod/'''''compiler-1.11''''' folder, drop spcomp + includes there<br />
* Add an entry to web-commit-updater/updater.php for the new version<br />
* Force builds on the new dev and stable branches via pushbuild.txt<br />
* Add a ~sourcemod/update/'''''update-1.11.sh''''' script for the new version<br />
* Clone the new branch into ~sourcemod/update/'''''1.11-dev'''''<br />
* Run ~sourcemod/update_addversion.php --version '''''1.11''''' --path '''''1.11-dev''''' (with appropriate values)<br />
* Change the ~sourcemod/compiler symlink to the new version<br />
* Update hardcoded verison in ~sourcemod/public_html/compiler.php.<br />
* git checkout new branch in ~sourcemod/sourcemod, then generate.py in /scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=11318Releasing Products2022-07-03T03:05:05Z<p>Fyren: wiki markup instead of HTML</p>
<hr />
<div>== Releasing SourceMod ==<br />
* Create a git branch.<br />
* Update master.cfg in buildbot buildmaster. Don't forget to push the change to github.<br />
* mount -orw /mnt/downloads on web01.<br />
* mkdir /mnt/downloads/smdrop/<new release folder>, chmod 775 it, fix ownership.<br />
* mount -oro /mnt/downloads.<br />
* Fix sm_commit_log by updating last ~N master builds to be the new stable branch.<br />
* Update ~sourcemod downloads.php.<br />
* Update ~sourcemod vbcompiler.php.<br />
* Update forums newpost.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull.<br />
* Create a ~sourcemod/compiler-1.<version> folder, drop spcomp + includes there.<br />
* Add an entry to web-commit-updater/updater.php for the new version.<br />
* Force builds on the new dev and stable branches via pushbuild.txt.<br />
* Add a script for the new version in ~sourcemod/update.<br />
* Change the ~sourcemod/compiler symlink to the new version.<br />
* Update hardcoded verison in ~sourcemod compiler.php.<br />
* git checkout new branch in ~sourcemod/sourcemod, then generate.py in /scripts/sourcepawn/exp/docgen/generate</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=11272Scripting FAQ (SourceMod)2022-03-06T12:33:24Z<p>Fyren: /* Where can I find all the SourcePawn functions and other information? */ swap IRC link to Discord</p>
<hr />
<div>[[Image:Yak.gif]]<br />
yak wuz heer<br />
<br />
=How do I learn SourcePawn?=<br />
A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br />
<br />
=Where can I find all the SourcePawn functions and other information?=<br />
All SourceMod plug-ins have this line:<br />
<br />
<pawn>#include <sourcemod></pawn><br />
<br />
This line instructs the compiler to retrieve the file <tt>sourcemod.inc</tt> from the <tt>sourcemod/scripting/include</tt> folder. Every function, variable, and definition can be found in the <tt>.inc</tt> files inside the <tt>sourcemod/scripting/include</tt> folder.<br />
<br />
But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br />
<br />
Also, if you are in the AlliedMods Discord server (https://discord.gg/HUc67zN), you can use the <tt>/docs</tt> command to search the API.<br />
<br />
=How do I find the classname of an entity? (e.g., "<tt>weapon_knife</tt>" or "<tt>prop_physics</tt>")=<br />
The classname of an entity (not to be confused with a netclass such as <tt>CCSPlayer</tt>) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br />
<br />
<pawn>char classname[128];<br />
GetEdictClassname(myentity, classname, sizeof(classname));<br />
<br />
PrintToServer("myentity classname: %s", classname);<br />
// myentity classname: weapon_knife</pawn><br />
<br />
=How do I block regular commands, such as <tt>kill</tt> and <tt>say</tt>?=<br />
As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br />
<br />
Here's how to use it to block the <tt>say</tt> command:<br />
<br />
<pawn>public void OnPluginStart()<br />
{<br />
AddCommandListener(SayCallback, "say");<br />
}<br />
<br />
public Action SayCallback(int client, const char[] command, int argc)<br />
{<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
=How do I hook +commands, such as <tt>+zoom</tt> and <tt>+attack</tt>?=<br />
Unlike regular commands, <tt>+commands</tt> are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook <tt>+commands</tt>. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a <tt>+command</tt>, you'll first have to find out its proper <tt>IN_</tt> constant (see <tt>[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]</tt>).<br />
<br />
Here's how to use it to block crouching when attacking:<br />
<br />
<pawn>public Action OnPlayerRunCmd(int client, int &buttons, int &impulse, float vel[3], float angles[3], int &weapon)<br />
{<br />
// Check if the player is attacking (+attack)<br />
if ((buttons & IN_ATTACK) == IN_ATTACK)<br />
{<br />
// If so, block their crouching (+duck)<br />
buttons &= ~IN_DUCK;<br />
}<br />
<br />
// We must return Plugin_Continue to let the changes be processed.<br />
// Otherwise, we can return Plugin_Handled to block the commands<br />
return Plugin_Continue;<br />
}</pawn><br />
<br />
=How do I get rid of loose indentation warnings?=<br />
<pre>myplugin.sp(#) : warning 217: loose indentation</pre><br />
<br />
Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br />
<br />
Good:<br />
<br />
<pawn>public void OnPluginStart()<br />
{<br />
int myvar = 5;<br />
if (myvar == (2 + 3))<br />
PrintToServer("myvar is %d", myvar);<br />
}</pawn><br />
<br />
Bad:<br />
<br />
<pawn>public voidOnPluginStart()<br />
{<br />
int myvar = 5;<br />
if (myvar == (2 + 3))<br />
PrintToServer("myvar is %d", myvar);<br />
}</pawn><br />
<br />
=How do I get rid of tag mismatch warnings?=<br />
Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are <tt>_</tt> (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), <tt>float</tt>, <tt>bool</tt>, and <tt>char</tt>. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br />
<br />
Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br />
<pawn>native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)</pawn><br />
<br />
This function calls for '''<tt>entity</tt>''', a cell with the implied tag '''''<tt>int</tt>'''''; '''<tt>type</tt>''', with the developer-defined tag '''''<tt>PropType</tt>'''''; '''<tt>prop</tt>''', with the built-in tag '''''<tt>char</tt>'''''; and '''<tt>value</tt>''', with the built-in tag '''''<tt>float</tt>'''''.<br />
To call this function, then, you must pass values with the specified tags. For example:<br />
<pawn>SetEntPropFloat(1234, Prop_Send, "m_fNumber", 1.0);</pawn><br />
<br />
This calls the function correctly: <tt>1234</tt> is a regular cell ('''''<tt>_</tt>'''''), <tt>Prop_Send</tt> is a variable defined in the enum '''''<tt>PropType</tt>''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], <tt>"m_fNumber"</tt> is a '''''<tt>char</tt>''''', and <tt>1.0</tt> is a '''''<tt>float</tt>'''''. For a nonexample:<br />
<pawn>SetEntPropFloat(1234.0, 1, "m_fNumber", 1337);</pawn><br />
<br />
This is incorrect! <tt>1234.0</tt> is a '''''<tt>float</tt>''''' that should be a regular cell ('''''<tt>int</tt>'''''); <tt>1</tt> is a regular cell ('''''<tt>int</tt>''''') that should be a '''''<tt>PropType</tt>'''''; and <tt>1337</tt> is a regular cell ('''''<tt>int</tt>''''') that should be a '''''<tt>float</tt>'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''<tt>PropType</tt>''''') can be found in the same file where a function uses them (you can find '''''<tt>PropType</tt>''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br />
<br />
=How do I add color to my messages?=<br />
Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters <tt>0x01</tt> to <tt>0x08</tt>. For example:<br />
<pawn>PrintToChatAll ("\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8");</pawn><br />
<br />
Example output from Left 4 Dead:<br />
<br />
[[Image:Left_4_Dead_Colors.png]]<br />
<br />
With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br />
<br />
* <tt style="color: blue;">0x01</tt> = Normal color<br />
* <tt style="color: blue;">0x02</tt> = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br />
* <tt style="color: blue;">0x03</tt> = Team color<br />
* <tt style="color: blue;">0x04</tt> = Location color<br />
<br />
This data comes from Counter-Strike: Source.<br />
<br />
For CS:GO, here are some colors:<br />
<pawn>PrintToChat("\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF");</pawn><br />
<br />
Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br />
<br />
<pawn>Handle hBf;<br />
hBf = StartMessageOne("SayText2", player_to); // To send the message to all players, use StartMessageAll("SayText2");<br />
if (hBf != null)<br />
{<br />
BfWriteByte(hBf, player_from); <br />
BfWriteByte(hBf, 0); <br />
BfWriteString(hBf, "<\x03player_from team color\x01> My message");<br />
EndMessage();<br />
}</pawn><br />
<br />
<tt>player_to</tt> is the client index to send the message to (or use [https://sm.alliedmods.net/new-api/usermessages/StartMessageAll StartMessageAll()] instead of [https://sm.alliedmods.net/new-api/usermessages/StartMessageOne StartMessageOne()] to send the message to all players). <tt>player_from</tt> is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming <tt>player_from</tt> is on the RED team):<br />
<br />
<span style="color:#AA0">&lt;</span><span style="color:#F00">player_from team color</span><span style="color:#AA0">&gt; My message</span><br />
<br />
There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br />
<br />
Additionally, CS:S, TF2, HL2:DM, and DoD:S all support RGB(A) hex values in chat messages with <tt style="color: blue;">0x07</tt> and <tt style="color: blue;">0x08</tt>, followed by a 6- or 8- char hex value (e.g., <tt>\x07ABCDEF</tt>, <tt>\x0801234567</tt>).<br />
<br />
==Color Libraries==<br />
There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br />
<br />
===exvel's Colors===<br />
This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as <span style="color: #AA0;"><tt>{default}</tt></span>, <span style="color: #0F0;"><tt>{green}</tt></span>, or <span style="color: #00F;"><tt>{blue}</tt></span>.<br />
<br />
Here's some example usage. Note that this code assumes client 1 is in game and on the <span style="color: #00F;">BLU</span> team:<br />
<br />
<pawn>#include <colors><br />
<br />
public void OnPluginStart()<br />
{<br />
CPrintToChatAll("{green}Hello {red}World! {default}Test 1 concluded.");<br />
<br />
int client_on_blu_team = 1;<br />
CPrintToChatAllEx(client_on_blu_team, "{teamcolor}BLU team {default}says {green}hi!");<br />
}</pawn><br />
<br />
<span style="color: #0F0;">Hello </span><span style="color: #F00;">World! </span><span style="color: #AA0;">Test 1 concluded.</span><br />
<span style="color: #00F;">BLU team </span><span style="color: #AA0;">says </span><span style="color: #0F0;">hi!</span><br />
<br />
Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to <span style="color: #0F0;"><tt>{green}</tt></span>.<br />
<br />
===SMLib===<br />
[http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as <span style="color: #AA0;"><tt>{N}</tt></span> and <span style="color: #0F0;"><tt>{G}</tt></span>, and all colors are supported in its <tt>Client_PrintToChat()</tt> function.<br />
<br />
Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the <span style="color: #00F;">BLU</span> team:<br />
<br />
<pawn>#include <smlib><br />
<br />
public void OnPluginStart()<br />
{<br />
Client_PrintToChatAll("{G}Hello {R}World! {N}Test 1 concluded.");<br />
<br />
int client_on_blu_team = 1;<br />
Client_PrintToChatAll(client_on_blu_team, "{T}BLU team {N}says {G}hi!");<br />
}</pawn><br />
<br />
<span style="color: #0F0;">Hello </span><span style="color: #F00;">World! </span><span style="color: #AA0;">Test 1 concluded.</span><br />
<span style="color: #00F;">BLU team </span><span style="color: #AA0;">says </span><span style="color: #0F0;">hi!</span><br />
<br />
=Why do I get an "unknown symbol" error when using an SDKTools native?=<br />
None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include <sourcemod> to use SourceMod's functions, you need to:<br />
<pawn>#include <sdktools></pawn><br />
to use an SDKTools native.<br />
<br />
=Why is Source telling me my command is an "Unknown command"?=<br />
This is because you're not returning <tt>Plugin_Handled</tt> in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br />
<br />
<pawn>public Action MyCommand(int client, int args)<br />
{<br />
// Do something...<br />
<br />
return Plugin_Handled;<br />
}</pawn></div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Pawn_Tutorial&diff=10290Pawn Tutorial2017-06-03T18:30:22Z<p>Fyren: /* Switch Statements */ ranges are not supported for switch cases</p>
<hr />
<div>{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}<br />
<br />
This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].<br />
<br />
=Introduction=<br />
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.<br />
<br />
Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera. <br />
<br />
==Language Paradigms==<br />
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.<br />
*No typing<br />
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.<br />
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning. If you're using SourcePawn (for SourceMod), there is actually a second type: String. In a String, letters are stored as separate bytes... essentially having 4 characters stored in every cell.<br />
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.<br />
**Pawn <i>does</i> support arrays of cells, which leads to C-style arrays for strings.<br />
*No garbage collection<br />
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.<br />
*Procedural<br />
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").<br />
*No thread-safety<br />
**Pawn is targetted toward single-thread instances.<br />
<br />
==Implementation Features==<br />
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.<br />
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.<br />
*IA32 JIT Compiler for vastly increasing script execution time.<br />
<br />
Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.<br />
<br />
==License==<br />
Pawn is licensed under the [[ZLib/libpng_License]] license.<br />
<br />
=Variables=<br />
Variables are simple structures for holding data throughout a period of time in your script.<br />
<br />
==Types==<br />
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols. <br />
<br />
===Integers===<br />
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:<br />
<br />
<pawn>new a //Declare empty variable "a"<br />
new b=5 //Declare variable "b" and set it to 5.<br />
new c=5.0 //This is invalid, technically not a whole number!<br />
new d="hello" //"hello" is not a number either, this is invalid.<br />
<br />
//You can also declare multiple variables on one line:<br />
new e,f,g,h<br />
new x=7, y=3<br />
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.</pawn><br />
<br />
===Floats===<br />
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:<br />
<br />
<pawn>new Float:a //Declare empty floating point variable "a"<br />
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.<br />
new Float:c=5 //This is valid, but the compiler will give you a warning.<br />
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn><br />
<br />
You can also do the following:<br />
<pawn>//float(n) is a function that takes a number n and makes it a<br />
// floating point number.<br />
new Float:var = float(5)<br />
new Float:var2 = 5.0 <br />
new Float:var3 = 1.0*5<br />
new var4 = floatround(5.0) <br />
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.<br />
// this makes the assignment to a regular integer variable valid.</pawn><br />
<br />
Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.<br />
<br />
===Booleans===<br />
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.<br />
<br />
<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false<br />
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn><br />
<br />
<br />
<br />
=Arrays=<br />
<br />
Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:<br />
<br />
<pawn>//This will declare a variable called "Players" which holds 32 numbers. <br />
new Players[32]<br />
<br />
//You can now store values in any of the 32 "slots" this array has. <br />
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.<br />
//Every slot starts off as 0.<br />
<br />
//Set slot 0 to 5<br />
Players[0] = 5<br />
<br />
//Set slot 1 to whatever is in slot 0, in this case, the number 5<br />
Players[1] = Players[0]<br />
<br />
//This is invalid! <br />
//Although there are 32 slots, they are numbered from 0 to 31.<br />
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS<br />
// or, it simply won't compile!<br />
Players[32] = 15<br />
<br />
//This is also totally invalid <br />
Players[-1] = 6<br />
<br />
new a = 3<br />
//This is also totally invalid. <br />
//a must be a constant number.<br />
new BadArray[a]<br />
<br />
//So this is valid:<br />
const b = 3<br />
new GoodArray[b]<br />
<br />
//You can also use Compiler Directives (See last section)<br />
<br />
#define ARRAY_SIZE 3<br />
new Array[ARRAY_SIZE]</pawn><br />
<br />
Arrays can also be declared with groups of data default, such as:<br />
<br />
<pawn>new Numbers[4] = {0,1,2,3}<br />
//Note: it is important that you make sure the amount of numbers<br />
// you pass and the size of the array match</pawn><br />
<br />
<br />
You can also use any data type with arrays:<br />
<br />
<pawn>//Array of floating points:<br />
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}<br />
//Array of booleans. Note this sets every slot to true.<br />
new bool:playerHasGun[33] = {true, ...}</pawn><br />
<br />
=Strings=<br />
<br />
You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:<br />
<br />
<pawn>//This will declare a number array "myString" that contains the data "Hello". <br />
//It will have 6 slots, because there are 5 characters. <br />
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.<br />
new myString[] = "Hello"<br />
// If you're using SourcePawn, do this instead:<br />
new String:myString[] = "Hello"</pawn><br />
<br />
Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.<br />
<pawn>new myString[6]<br />
myString[0] = 'H'<br />
myString[1] = 'e'<br />
myString[2] = 'l'<br />
myString[3] = 'l'<br />
myString[4] = 'o'<br />
myString[5] = 0</pawn><br />
<br />
{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}<br />
<br />
You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:<br />
<pawn>new myString[6]<br />
myString = "Hello" //INVALID!<br />
myString[0] = "Hello" //INVALID!<br />
//To add data to a string, you can do this:<br />
new goodString[7]<br />
copy(goodString, 6, "Hello")</pawn><br />
<br />
{{qnotice|In SourcePawn, copy was renamed to strcopy and avoids the issue with copy noted below.}}<br />
<br />
Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.<br />
<br />
More examples:<br />
<pawn>//Copy is a function that takes three parameters:<br />
copy(destination[], length, source[])<br />
//It copies the string inside the source array and places <br />
// it into the destination array, but only copies up to length characters.<br />
<br />
//Lastly, to prove that a string is really an array of numbers, this is completely valid:<br />
new weird[6]<br />
weird[0] = 68<br />
weird[1] = 65<br />
weird[2] = 73<br />
weird[3] = 86<br />
weird[4] = 68<br />
weird[5] = 0<br />
//This will set the variable "weird" to the string "DAVID".<br />
//To see how letters and symbols translate into numbers, visit www.asciitable.com </pawn><br />
<br />
=Functions=<br />
<br />
Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:<br />
<br />
<pawn>//This is a function that takes no parameters and returns 1.<br />
//When activated, it uses the (non-existant) print function.<br />
show()<br />
{<br />
print("Hello!")<br />
<br />
return 1 //End, return 1<br />
}<br />
<br />
//Activate like this:<br />
show()</pawn><br />
<br />
You can also declare functions to take parameters.<br />
<br />
<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.<br />
add_two_numbers(first, second)<br />
{<br />
new sum = first + second<br />
<br />
return sum //Return the sum<br />
}<br />
//Then you can use your new function like this:<br />
<br />
new a,b<br />
a = 5<br />
b = 12<br />
new c = add_two_numbers(a,b)<br />
//c will now be equal to 17.</pawn><br />
<br />
You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.<br />
<br />
<pawn>//This defines a new function called "add_two_floats"<br />
// which takes two floating points and returns the sum<br />
Float:add_two_floats(Float:first, Float:second)<br />
{<br />
new Float:sum = first + second<br />
<br />
return sum<br />
}<br />
<br />
new Float:a<br />
new Float:b<br />
a = 5.0<br />
b = 6.3<br />
new Float:c<br />
c = add_two_floats( a+b )<br />
//c is now equal to 11.3</pawn><br />
<br />
You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.<br />
<pawn>add_two_from_array(array[], a, b)<br />
{<br />
new first = array[a]<br />
new second = array[b]<br />
new sum = add_two_numbers(first, second) //use our function from earlier<br />
<br />
return sum<br />
}</pawn><br />
<br />
Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:<br />
<br />
<pawn>//This function will switch slots a and b inside any array passed to this function.<br />
swap_slots(array[], a, b)<br />
{<br />
//Note, you need to temporarily hold one of the slots before swapping them<br />
//Otherwise, you can't swap both values! This is a classic problem.<br />
//If you have a and b, setting b equal to a eliminates the original value in b.<br />
new temp<br />
<br />
temp = array[b]<br />
array[b] = array[a]<br />
array[a] = temp<br />
}<br />
<br />
new myArray[2]<br />
myArray[0] = 5<br />
myArray[1] = 6<br />
swap_slots(myArray, 0, 1)<br />
//myArray[0] is 6, myArray[1] is 5</pawn><br />
<br />
You can prevent arrays from being modified by declaring them "constant", like so:<br />
<pawn>add_two_from_array(const array[], a, b)<br />
{<br />
new first = array[a]<br />
new second = array[b]<br />
new sum = add_two_from_array(first, second)<br />
return sum<br />
}<br />
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn><br />
<br />
This function modifies an array passed as a constant. It will not work.<br />
<pawn>bad_function(const array[])<br />
{<br />
array[0] = 0<br />
}</pawn><br />
<br />
=Expressions=<br />
<br />
Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.<br />
<br />
<pawn>//This is the simplest expression. It returns the number zero.<br />
0<br />
//However, to make it easier to read, this is also valid:<br />
(0)</pawn><br />
<br />
If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".<br />
<br />
<pawn>//Here are more mathematical expressions. The mathematical operators are<br />
// + for addition<br />
// - for subtraction<br />
// * for multiplication<br />
// / for division<br />
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)<br />
(5+6) //returns 11<br />
((5*6)+3) //returns 33<br />
((((5+3)/2)*4)-9) //returns 7<br />
((5*6) % 7) //returns 2<br />
//Here are other expressions:<br />
(true) //returns true<br />
(5.0 + 2.3) //returns 7.3 as a floating point</pawn><br />
<br />
There are also extensions of these operators for direct use on variables.<br />
<pawn>new a = 5<br />
new b = 6<br />
//The first are the post/pre increment and decrement operators.<br />
a++ //returns a+1, or 6. This is a post increment.<br />
++a //also returns a+1, or 6. This is a pre increment.</pawn><br />
<br />
The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.<br />
<br />
<pawn>a-- //returns 4, post decrement<br />
--a //returns 4, pre decrement</pawn><br />
<br />
Note that a++ essentially trims down this code:<br />
<pawn>a = a + 1</pawn><br />
However, there is another way to write lines of code of this form:<br />
<pawn>a = a OP y</pawn><br />
Where OP is a math operator. It can be shortened to:<br />
<pawn>a OP= x</pawn><br />
Observe:<br />
<pawn>a += 1 //This sets a to a + 1<br />
a -= b //This sets a to a - b<br />
a *= 0 //This multiplies a by 0<br />
a /= 2 //This divides a by 2.</pawn><br />
<br />
However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.<br />
<br />
The and operator takes in the left expression and right expression. If both are "true", then it returns true.<br />
<br />
<pawn>//This is false, because 1 returns true and 0 returns false. <br />
//Since both are not true, && returns false.<br />
(1 && 0)<br />
(1 && 2) //Both numbers are "true", therefore the expression is true.<br />
(true && false) //false<br />
(false && false) //false<br />
(true && true) //true</pawn><br />
<br />
The other important operator is "or". It returns true if one of two expressions are true.<br />
<pawn>(1 || 0) //true, since one of the values is true.<br />
(1 || 2) //true<br />
(true || false) //true<br />
(false || false) //false<br />
(true || true) //true</pawn><br />
<br />
There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:<br />
<br />
<pawn>//This will return 8, which means 8 is indeed a bit in 9.<br />
(9 & 8)<br />
//4 (00100) is not a bit inside 16 (10000) and this will return 0.<br />
(16 & 4)<br />
//The next operator is "bitwise or" <br />
//which does an "or (||)' operation on each of the bits in both numbers.<br />
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.<br />
(9 | 3)</pawn><br />
<br />
These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.<br />
<br />
<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.<br />
(3 << 3)<br />
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.<br />
(24 >> 3)</pawn><br />
<br />
The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).<br />
<br />
<pawn>//This returns false<br />
(!true)<br />
//This returns true<br />
(!false)<br />
//This takes 9 (binary 1001) and makes it 6 (binary 0110).<br />
//This is the "bitwise complement" operator, which performs a !(not) on each bit.<br />
(~(9))</pawn><br />
<br />
=Conditionals=<br />
<br />
Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision. <br />
<br />
==If Statements==<br />
<br />
The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:<br />
<br />
This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.<br />
<br />
<pawn>if (a == 5)<br />
{<br />
a = 6<br />
}</pawn><br />
<br />
However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.<br />
<br />
<pawn>if (a == 5)<br />
{<br />
a = 6<br />
} else {<br />
a = 7<br />
}</pawn><br />
<br />
There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).<br />
<br />
<pawn>//This will return true if a does not equal 5<br />
if (a != 5) {}<br />
//Returns true if a is greater than 5<br />
if (a > 5) {}<br />
//Returns true if a is less than 5<br />
if (a < 5) {}<br />
//Returns true if a is greater than or equal to 5<br />
if (a >= 5) {}<br />
//Returns true if a is less than or equal to 5<br />
if (a <= 5) {}<br />
//Returns true because 11 is true<br />
if (5+6) {}<br />
//Returns true of both a and b are true<br />
if (a && b) {}<br />
//Returns true if 7.5 is greater than c<br />
if ( ((5*3)/2) > c) {}<br />
//Always returns true no matter what<br />
if (true) {}<br />
//Never returns true<br />
if (false) {}</pawn><br />
Note that array comparisons have restrictions. This is invalid:<br />
<br />
<pawn>my arrayOne[3]<br />
my arrayTwo[3]<br />
if (arrayOne == arrayTwo) {</pawn><br />
<br />
You must do:<br />
<pawn>if ((arrayOne[0] == arrayTwo[0]) && <br />
(arrayOne[1] == arrayTwo[1]) && <br />
(arrayOne[2] == arrayTwo[2])) {</pawn><br />
<br />
Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.<br />
<br />
The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.<br />
<br />
<pawn>//Example of "if...else if"<br />
if (a == 5) {<br />
//This code will be run if a is 5.<br />
} else if (a < 6) {<br />
//This code will be run if a is less than 6<br />
} else if (a == 7) {<br />
//This code will be run if a is 7.<br />
} else {<br />
//If none of the above conditions are met, this code will be run.<br />
}</pawn><br />
<br />
<br />
It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.<br />
<br />
==Switch Statements==<br />
<br />
Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".<br />
<br />
<pawn>//Example of a switch statement<br />
switch (a)<br />
{<br />
case 5:<br />
{<br />
//This code will run if a is equal to 5<br />
}<br />
<br />
case 6:<br />
{<br />
//This code will run if a is equal to 6<br />
}<br />
<br />
case 7:<br />
{<br />
//This code will run if a is equal to 7<br />
}<br />
<br />
default:<br />
{<br />
//This code will run if all other cases fail<br />
}<br />
}</pawn><br />
Multiple conditions are also possible in pawn:<br />
<pawn>//Example of an multiple switch statement<br />
switch (a)<br />
{<br />
case 1, 2, 3:<br />
{<br />
//This code will run if a is equal to 1 or 2 or 3<br />
}<br />
<br />
case 4, 5, 6:<br />
{<br />
//This code will run if a is equal to 4 or 5 or6<br />
}<br />
<br />
case 7, 8, 9:<br />
{<br />
//This code will run if a is equal to 7 or 8 or 9<br />
}<br />
<br />
default:<br />
{<br />
//This code will run if all other cases fail<br />
}<br />
}</pawn><br />
<br />
Note that switch cases do not "fall-through." If a case is true, no other cases are evaluated.<br />
<br />
=Looping=<br />
<br />
Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.<br />
<br />
==For Loops==<br />
<br />
The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:<br />
<br />
<pawn>/*A for loop has three parameters:<br />
for (initial; condition; increment)<br />
{<br />
//your code here<br />
}<br />
<br />
Before the first loop executes, it runs your initial condition.<br />
Then it begins looping your code with these steps:<br />
1. Check if the condition is true. If so, continue. If not, stop.<br />
2. Run the code.<br />
3. Run the "increment" parameter.<br />
4. Go to step 1.<br />
*/<br />
<br />
//Example of a for loop<br />
new i<br />
new sum<br />
for (i=1; i<=10; i++)<br />
{<br />
sum += i<br />
}</pawn><br />
<br />
Explanation:<br />
<br />
#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.<br />
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.<br />
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.<br />
#Since the condition is true, sum+=i is executed. This means i is added into sum.<br />
#The code block has finished, and i++ increments i to 2.<br />
#Now it repeats.<br />
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.<br />
#The code block has finished, and i now increments to 3.<br />
#This happens until...<br />
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.<br />
#The sum variable now holds the number 55, which is the sum of 1 through 10.<br />
<br />
This provides a nice way of managing arrays!<br />
<br />
<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.<br />
sum_of_array(myArray[], size)<br />
{<br />
//Note: Make sure the user passes the size of the array, so we don't overflow it.<br />
new i, sum<br />
<br />
//This loop will start at 0 and stop right before size is reached.<br />
//If the user passes the correct size of the array, <br />
// the loop will be going from 0 to size-1<br />
// This correctly matches the numbers of slots in the array.<br />
for (i=0; i<size; i++)<br />
{<br />
//For every time this loop executes, <br />
// i will be a number from 0 to size-1<br />
//Add the value of the slot (i) in the array to sum.<br />
//Once this is finished, sum will contain <br />
// the sum of all slots in the array.<br />
sum += myArray[i]<br />
}<br />
<br />
return sum<br />
}<br />
<br />
new NumberArray[4]<br />
NumberArray[0] = 3<br />
NumberArray[1] = 1<br />
NumberArray[2] = 4<br />
NumberArray[3] = 1<br />
<br />
new answer = sum_of_array(NumberArray, 4)<br />
//answer will be 3+1+4+1, or 9<br />
<br />
//Here is a function to compare if one array is equal to another (i.e. a string)<br />
bool:compare_arrays(array1[], array2[], size)<br />
{<br />
new i<br />
for (i=0; i<size; i++)<br />
{<br />
//If a slot does not match, halt the function and return false.<br />
if (array1[i] != array2[i])<br />
{<br />
return false<br />
}<br />
}<br />
<br />
//If the function got to this point without returning false, return true.<br />
return true<br />
}</pawn><br />
<br />
==While Loops==<br />
<br />
The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.<br />
<br />
<pawn>//Basic loop<br />
new i=0<br />
new sum<br />
<br />
while (++i <= 10)<br />
{<br />
sum+=i<br />
}<br />
<br />
sum_of_array(array[], size)<br />
{<br />
new i=0, sum<br />
<br />
//Do this loop while i is less than the size.<br />
//i is incremented at the end of every loop.<br />
while (i++ < size)<br />
{<br />
sum += array[i]<br />
}<br />
<br />
return sum<br />
}<br />
<br />
bool:compare_arrays(array1[], array2[], size)<br />
{<br />
new i<br />
while (i++ < size)<br />
{<br />
if (array1[i] != array2[i])<br />
{<br />
return false<br />
}<br />
}<br />
<br />
return true<br />
}</pawn><br />
<br />
<br />
==Two Dimensional Arrays==<br />
<br />
In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:<br />
<br />
<pawn>//This declares an array with 50 rows and 50 columns.<br />
new BigArray[50][50]<br />
//this declares a floating point array with 25 rows and 10 columns.<br />
new Float:BigArray[25][10]</pawn><br />
<br />
Each slot in the first subset of the array becomes its own array.<br />
<br />
<pawn>new BigArray[3][3]<br />
BigArray[0][0] = 10<br />
BigArray[0][1] = 20<br />
BigArray[0][2] = 30<br />
BigArray[1][0] = 40<br />
BigArray[1][1] = 50<br />
BigArray[1][2] = 60<br />
BigArray[2][0] = 70<br />
BigArray[2][1] = 80<br />
BigArray[2][2] = 90</pawn><br />
<br />
Will result in BigArray looking like this:<br />
:{|<br />
|-<br />
| BigArray<br />
| 0<br />
| 1<br />
| 2<br />
|-<br />
| 0<br />
| 10<br />
| 20<br />
| 30<br />
|-<br />
| 1<br />
| 40<br />
| 50<br />
| 60<br />
|-<br />
| 2<br />
| 70<br />
| 80<br />
| 90<br />
|}<br />
<br />
Note that our old sum_of_array() function can still work! We can do:<br />
<br />
<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn><br />
<br />
Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.<br />
<br />
<pawn>//This function will tally up a two dimensional array.<br />
sum_of_table(array[][], rows, cols)<br />
{<br />
new i, j, sum<br />
<br />
//Note, there is a loop inside the loop. <br />
//This lets you go through each array inside the <br />
// bigger array. <br />
for (i=0; i<rows; i++)<br />
{<br />
for (j=0; j<cols; j++)<br />
{<br />
sum += array[i][j]<br />
}<br />
}<br />
<br />
return sum<br />
}</pawn><br />
<br />
Note, it is also possible to store an array of strings using two dimensional arrays.<br />
<br />
<pawn>new StringList[3][] = {"Hello", "my", "friend"}<br />
/*<br />
StringList[0][0] through [0][5] contains "Hello"<br />
StringList[1][0] through [1][2] contains "my"<br />
StringList[2][0] through [2][6] contains "friend"<br />
*/</pawn><br />
<br />
The table for StringList will look like:<br />
StringList 0 1 2 3 4 5 6<br />
0 H e l l o \0 <br />
1 m y \0 <br />
2 f r i e n d \0<br />
<br />
Comparing strings in multidimensional arrays is also similar:<br />
<br />
<pawn>if (StringList[0] == "Hello") //INVALID<br />
if (StringList[0][0] == "Hello") //INVALID<br />
if (equali(StringList[0], "Hello")) //Valid</pawn><br />
<br />
=Compiler Pre-processor Directives=<br />
<br />
Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.<br />
<br />
<pawn>//To bind a symbol to a value, you can do this:<br />
#define SYMBOL VALUE<br />
//for example:<br />
<br />
#define MAX_STRING 250<br />
new String[MAX_STRING]<br />
<br />
#define HELLO "Hello. This is a generic greeting."<br />
new Hello[MAX_STRING] = HELLO</pawn><br />
<br />
You can also use #defines to change the flow of code the compiler makes.<br />
<pawn>#if defined LINUX<br />
//This portion will be compiled if #define LINUX exists<br />
execute_command("ls -l")<br />
#else<br />
//This portion will be compiled if #define LINUX does not exist<br />
execute_command("dir")<br />
#endif</pawn><br />
<br />
You can also change how much memory your script uses.<br />
<pawn>#pragma dynamic 4096<br />
//This creates a 16K stack of memory (default).<br />
//It is measured in blocks of 4 byte cells.</pawn><br />
<br />
You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required). <br />
<pawn>#pragma semicolon 1</pawn><br />
<br />
You can also change the control character( amxx std: '^' )<br />
<pawn>#pragma ctrlchar '\'<br />
//this sets the control character to backslash( c/c++/c#/java/... std )<br />
// now you have to use the \ instead of ^<br />
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn><br />
<br />
=Conclusion=<br />
<br />
This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/Pawn_Language_Guide.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!<br />
<br />
=External Links=<br />
*[http://www.compuphase.com/pawn/Pawn_Language_Guide.pdf Pawn Language Reference]<br />
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]<br />
*[http://www.compuphase.com/ ITB CompuPhase]<br />
<br />
[[Category:Scripting (AMX Mod X)]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Handle_API_(SourceMod)&diff=10237Handle API (SourceMod)2017-01-09T01:04:27Z<p>Fyren: /* Handle Security */ I guess.</p>
<hr />
<div>The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.<br />
<br />
The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.<br />
<br />
Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.<br />
<br />
<br />
=Basic Types=<br />
==Handle_t==<br />
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.<br />
<br />
Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.<br />
<br />
==HandleType_t==<br />
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types can also have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed. <br />
<br />
Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.<br />
<br />
Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.<br />
<br />
=Security=<br />
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.<br />
<br />
==Type Security==<br />
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.<br />
<br />
Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:<br />
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.<br />
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.<br />
<br />
The <tt>HTypeAccessRight</tt> enumeration has the following values:<br />
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.<br />
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.<br />
<br />
Below is a list of each Handle System function that requires type permissions, and which permissions may be required:<br />
*<tt>CreateType</tt>: <i><tt>HTypeAccess_Inherit</tt> if a parent is specified</i><br />
*<tt>RemoveType</tt>: <i>(none, always secured)</i><br />
*<tt>CreateHandle</tt>: <i><tt>HTypeAccess_Create</tt></i><br />
<br />
==Handle Security==<br />
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike handle types, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:<br />
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.<br />
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.<br />
<br />
Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:<br />
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:<br />
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.<br />
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is onyl granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.<br />
<br />
The following access rights exist for Handles:<br />
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.<br />
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.<br />
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.<br />
<br />
Below is a list of each Handle system function that requires permissions, and which permissions may be required:<br />
*<tt>FreeHandle</tt>: <i><tt>HandleAccess_Delete</tt></i><br />
*<tt>CloneHandle/CloneHandleEx</tt>: <i><tt>HandleAccess_Clone</tt></i><br />
*<tt>ReadHandle</tt>: <i><tt>HandleAccess_Read</tt></i><br />
<br />
SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.<br />
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.<br />
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.<br />
<br />
=Usage Examples=<br />
Here are some examples of Handle usages.<br />
<br />
==Basic Handles==<br />
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?<br />
<br />
After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility. <br />
<br />
===Creating the type===<br />
First, we have to create the type and its Dispatch interface.<br />
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */<br />
<br />
class FileTypeHandler : public IHandleTypeDispatch<br />
{<br />
public:<br />
void OnHandleDestroy(HandleType_t type, void *object)<br />
{<br />
/* :TODO: implement this */<br />
}<br />
};<br />
<br />
/* Create an instance of the handler */<br />
FileTypeHandler g_FileTypeHandler;<br />
<br />
Initialize()<br />
{<br />
/* Register the type with default security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
NULL, <br />
myself->GetIdentity(), <br />
NULL);<br />
}<br />
<br />
Shutdown()<br />
{<br />
/* Remove the type on shutdown */<br />
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());<br />
}</cpp><br />
<br />
===Creating Handles===<br />
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.<br />
<cpp>/* native CreateFile(const String:file[]) */<br />
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)<br />
{<br />
char path[PLATFORM_MAX_PATH];<br />
char *filename;<br />
<br />
/* Get the filename */<br />
pContext->LocalToString(params[1], &filename);<br />
/* Build a full path */<br />
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);<br />
<br />
/* Open for writing */<br />
FILE *fp = fopen(path, "wt");<br />
if (!fp)<br />
{<br />
return BAD_HANDLE;<br />
}<br />
<br />
/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */<br />
return g_pHandleSys->CreateHandle(g_FileType, <br />
fp, <br />
pContext->GetIdentity(), <br />
myself->GetIdentity(), <br />
NULL);<br />
}</cpp><br />
<br />
===Reading/Checking Handles===<br />
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.<br />
<cpp>/* native WriteLine(Handle:hndl, const String:line[]); */<br />
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)<br />
{<br />
Handle_t hndl = static_cast<Handle_t>(params[1]);<br />
HandleError err;<br />
HandleSecurity sec;<br />
<br />
/* Build our security descriptor */<br />
sec.pOwner = NULL; /* Not needed, owner access is not checked */<br />
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */<br />
<br />
/* Attempt to read the given handle as our type, using our security info.<br />
* Note that we read the pointer directly in with a little cast.<br />
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.<br />
*/<br />
FILE *fp;<br />
if ((err = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))<br />
!= HandleError_None)<br />
{<br />
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);<br />
}<br />
<br />
/* Get the text */<br />
char *text;<br />
pContext->LocalToString(params[2], &text);<br />
<br />
/* Write it */<br />
fputs(text, fp);<br />
<br />
return 1;<br />
}</cpp><br />
<br />
===CloseHandle Support===<br />
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.<br />
<cpp>class FileTypeHandler : public IHandleTypeDispatch<br />
{<br />
public:<br />
void OnHandleDestroy(HandleType_t type, void *object)<br />
{<br />
fclose( (FILE *)object );<br />
}<br />
};</cpp><br />
<br />
==Restricting CloseHandle==<br />
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.<br />
<br />
For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().<br />
<br />
===New Security Rules===<br />
<cpp>Initialize()<br />
{<br />
/* Create default access rights */<br />
HandleAccess rules;<br />
g_pHandleSys->InitAccessDefaults(NULL, &rules);<br />
<br />
/* Restrict delete to only our identity */<br />
rules.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;<br />
<br />
/* Register the type with our security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
&rules, <br />
myself->GetIdentity(), <br />
NULL);<br />
}</cpp><br />
<br />
===Implementing the Native===<br />
<cpp>/* native Closefile(Handle:hndl); */<br />
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)<br />
{<br />
Handle_t hndl = static_cast<Handle_t>(params[1]);<br />
HandleError err;<br />
HandleSecurity sec;<br />
<br />
/* Build our security descriptor */<br />
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */<br />
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */<br />
<br />
/* Attempt to read the given handle as our type, using our security info.<br />
* Note that we read the pointer directly in with a little cast.<br />
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.<br />
*/<br />
FILE *fp;<br />
if ((err = g_pHandleSys->FreeHandle(hndl, &sec))<br />
!= HandleError_None)<br />
{<br />
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);<br />
}<br />
<br />
return 1;<br />
}</cpp><br />
<br />
==Restricting CloseHandle Per-Handle==<br />
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.<br />
<br />
In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.<br />
<br />
===Implementation===<br />
<cpp>Handle_t g_GlobalFile;<br />
<br />
Initialize()<br />
{<br />
/* Register the type with default security permissions */<br />
g_FileType = g_pHandleSys->CreateType("File", <br />
&g_FileTypeHandler, <br />
0, <br />
NULL, <br />
NULL, <br />
myself->GetIdentity(), <br />
NULL);<br />
<br />
/* Create our 'global' file */<br />
FILE *fp = tmpfile();<br />
<br />
/* Set up the security descriptor */<br />
HandleSecurity sec;<br />
sec.pOwner = NULL; /* No owner for this Handle */<br />
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */<br />
<br />
/* Set up the access permissions */<br />
HandleAccess rules;<br />
g_pHandleSys->InitAccessDefaults(NULL, &rules);<br />
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;<br />
<br />
/* Finally, create the Handle with our rules */<br />
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);<br />
}<br />
<br />
Shutdown()<br />
{<br />
/* Remove our global Handle (not needed, but we do it for clarity */<br />
HandleSecurity sec;<br />
sec.pOwner = NULL;<br />
sec.pIdentity = myself->GetIdentity();<br />
<br />
g_pHandleSys->FreeHandle(g_GlobalFile, &sec);<br />
<br />
/* Remove the type on shutdown */<br />
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());<br />
}</cpp><br />
<br />
[[Category:SourceMod Development]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Counter-Strike:_Global_Offensive_Events&diff=10099Counter-Strike: Global Offensive Events2016-01-13T19:52:21Z<p>Fyren: </p>
<hr />
<div>:''Refer back to [[Game Events (Source)]] for more events.''<br />
<br />
=== player_death ===<br />
{{qnotice|When a client dies}}<br />
{{begin-hl2msg|player_death|string}}<br />
{{hl2msg|short|userid|user ID who died}}<br />
{{hl2msg|short|attacker|user ID who killed}}<br />
{{hl2msg|short|assister|user ID who assisted in the kill}}<br />
{{hl2msg|string|weapon|weapon name killer used }}<br />
{{hl2msg|string|weapon_itemid|inventory item id of weapon killer used}}<br />
{{hl2msg|string|weapon_fauxitemid|faux item id of weapon killer used}}<br />
{{hl2msg|string|weapon_originalowner_xuid|}}<br />
{{hl2msg|bool|headshot|singals a headshot}}<br />
{{hl2msg|short|dominated|did killer dominate victim with this kill}}<br />
{{hl2msg|short|revenge|did killer get revenge on victim with this kill}}<br />
{{hl2msg|short|penetrated|number of objects shot penetrated before killing target}}<br />
{{end-hl2msg}}<br />
<br />
=== player_hurt ===<br />
{{qnotice|When a client is damaged}}<br />
{{begin-hl2msg|player_hurt|string}}<br />
{{hl2msg|short|userid|user ID who was hurt}}<br />
{{hl2msg|short|attacker|user ID who attacked}}<br />
{{hl2msg|byte|health|remaining health points}}<br />
{{hl2msg|byte|armor|remaining armor points}}<br />
{{hl2msg|string|weapon|weapon name attacker used, if not the world}}<br />
{{hl2msg|short|dmg_health|damage done to health}}<br />
{{hl2msg|byte|dmg_armor|damage done to armor}}<br />
{{hl2msg|byte|hitgroup|hitgroup that was damaged ; <nowiki>1=hs 2=upper torso 3=lower torso 4=left arm 5=right arm 6=left leg 7=right leg</nowiki>}}<br />
{{end-hl2msg}}<br />
<br />
=== item_purchase ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|item_purchase|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|team|}}<br />
{{hl2msg|string|weapon|}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_beginplant ===<br />
{{qnotice|When the bomb is starting to get planted}}<br />
{{begin-hl2msg|bomb_beginplant|string}}<br />
{{hl2msg|short|userid|player who is planting the bomb}}<br />
{{hl2msg|short|site|bombsite index}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_abortplant ===<br />
{{qnotice|When the bomb planter stops planting the bomb}}<br />
{{begin-hl2msg|bomb_abortplant|string}}<br />
{{hl2msg|short|userid|player who is planting the bomb}}<br />
{{hl2msg|short|site|bombsite index}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_planted ===<br />
{{qnotice|When the bomb has been planted}}<br />
{{begin-hl2msg|bomb_planted|string}}<br />
{{hl2msg|short|userid|player who planted the bomb}}<br />
{{hl2msg|short|site|bombsite index}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_defused ===<br />
{{qnotice|When the bomb has been defused}}<br />
{{begin-hl2msg|bomb_defused|string}}<br />
{{hl2msg|short|userid|player who defused the bomb}}<br />
{{hl2msg|short|site|bombsite index}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_exploded ===<br />
{{qnotice|When the bomb explodes}}<br />
{{begin-hl2msg|bomb_exploded|string}}<br />
{{hl2msg|short|userid|player who planted the bomb}}<br />
{{hl2msg|short|site|bombsite index}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_dropped ===<br />
{{qnotice|When the bomb is dropped by a client}}<br />
{{begin-hl2msg|bomb_dropped|string}}<br />
{{hl2msg|short|userid|player who dropped the bomb}}<br />
{{hl2msg|long|entindex|}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_pickup ===<br />
{{qnotice|When the bomb is picked up by a client}}<br />
{{begin-hl2msg|bomb_pickup|string}}<br />
{{hl2msg|short|userid|player who picked up the bomb}}<br />
{{end-hl2msg}}<br />
<br />
=== defuser_dropped ===<br />
{{qnotice|When the defuser is dropped by a client}}<br />
{{begin-hl2msg|defuser_dropped|string}}<br />
{{hl2msg|long|entityid|defuser's entity ID}}<br />
{{end-hl2msg}}<br />
<br />
=== defuser_pickup ===<br />
{{qnotice|When the defuser is picked up by a client}}<br />
{{begin-hl2msg|defuser_pickup|string}}<br />
{{hl2msg|long|entityid|defuser's entity ID}}<br />
{{hl2msg|short|userid|player who picked up the defuser}}<br />
{{end-hl2msg}}<br />
<br />
=== announce_phase_end ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|announce_phase_end|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_intermission ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|cs_intermission|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_begindefuse ===<br />
{{qnotice|When the bomb is started to be defused}}<br />
{{begin-hl2msg|bomb_begindefuse|string}}<br />
{{hl2msg|short|userid|player who is defusing}}<br />
{{hl2msg|bool|haskit|}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_abortdefuse ===<br />
{{qnotice|When the bomb defusal is stopped}}<br />
{{begin-hl2msg|bomb_abortdefuse|string}}<br />
{{hl2msg|short|userid|player who was defusing}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_follows ===<br />
{{qnotice|When the hostage begins following a client}}<br />
{{begin-hl2msg|hostage_follows|string}}<br />
{{hl2msg|short|userid|player who touched the hostage}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_hurt ===<br />
{{qnotice|When a hostage is damaged}}<br />
{{begin-hl2msg|hostage_hurt|string}}<br />
{{hl2msg|short|userid|player who hurt the hostage}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_killed ===<br />
{{qnotice|When a hostage is killed}}<br />
{{begin-hl2msg|hostage_killed|string}}<br />
{{hl2msg|short|userid|player who killed the hostage}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_rescued ===<br />
{{qnotice|When a hostage is rescued}}<br />
{{begin-hl2msg|hostage_rescued|string}}<br />
{{hl2msg|short|userid|player who rescued the hostage}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{hl2msg|short|site|rescue site index}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_stops_following ===<br />
{{qnotice|When a hostage stops following a client}}<br />
{{begin-hl2msg|hostage_stops_following|string}}<br />
{{hl2msg|short|userid|player who rescued the hostage}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_rescued_all ===<br />
{{qnotice|When all the hostages are rescued}}<br />
{{begin-hl2msg|hostage_rescued_all|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== hostage_call_for_help ===<br />
{{qnotice|When the hostage calls for help}}<br />
{{begin-hl2msg|hostage_call_for_help|string}}<br />
{{hl2msg|short|hostage|hostage entity index}}<br />
{{end-hl2msg}}<br />
<br />
=== vip_escaped ===<br />
{{qnotice|When the VIP escapes}}<br />
{{begin-hl2msg|vip_escaped|string}}<br />
{{hl2msg|short|userid|player who was the VIP}}<br />
{{end-hl2msg}}<br />
<br />
=== vip_killed ===<br />
{{qnotice|When the VIP is killed}}<br />
{{begin-hl2msg|vip_killed|string}}<br />
{{hl2msg|short|userid|player who was the VIP}}<br />
{{hl2msg|short|attacker|user ID who killed the VIP}}<br />
{{end-hl2msg}}<br />
<br />
=== player_radio ===<br />
{{qnotice|When the player uses radio commands}}<br />
{{begin-hl2msg|player_radio|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|slot|}}<br />
{{end-hl2msg}}<br />
<br />
=== bomb_beep ===<br />
{{qnotice|Every time the bomb beep sound happens}}<br />
{{begin-hl2msg|bomb_beep|string}}<br />
{{hl2msg|long|entindex|c4 entity}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_fire ===<br />
{{qnotice|Every time a client fires their weapon}}<br />
{{begin-hl2msg|weapon_fire|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|string|weapon|weapon name used}}<br />
{{hl2msg|bool|silenced|is weapon silenced}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_fire_on_empty ===<br />
{{qnotice|Every time a client fires their weapon and it's empty}}<br />
{{begin-hl2msg|weapon_fire_on_empty|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|string|weapon|weapon name used}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_outofammo ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|weapon_outofammo|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_reload ===<br />
{{qnotice|Every time a client reloads their weapon}}<br />
{{begin-hl2msg|weapon_reload|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_zoom ===<br />
{{qnotice|Every time a client zooms a scoped weapon}}<br />
{{begin-hl2msg|weapon_zoom|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== silencer_detach ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|silencer_detach|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== inspect_weapon ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|inspect_weapon|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== weapon_zoom_rifle ===<br />
{{qnotice|exists for the game instructor to let it know when the player zoomed in with a regular rifle. Different from the above weapon_zoom because we don't use this event to notify bots}}<br />
{{begin-hl2msg|weapon_zoom_rifle|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_spawned ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|player_spawned|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|bool|inrestart|true if restart is pending}}<br />
{{end-hl2msg}}<br />
<br />
=== item_pickup ===<br />
{{qnotice|Every time an item is picked up (generally weapons)}}<br />
{{begin-hl2msg|item_pickup|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|string|item|either a weapon such as 'tmp' or 'hegrenade', or an item such as 'nvgs'}}<br />
{{hl2msg|bool|silent|}}<br />
{{end-hl2msg}}<br />
<br />
=== ammo_pickup ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|ammo_pickup|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|string|item|either a weapon such as 'tmp' or 'hegrenade', or an item such as 'nvgs'}}<br />
{{hl2msg|long|index|the weapon entindex}}<br />
{{end-hl2msg}}<br />
<br />
=== item_equip ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|item_equip|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|string|item|either a weapon such as 'tmp' or 'hegrenade', or an item such as 'nvgs'}}<br />
{{hl2msg|bool|canzoom|}}<br />
{{hl2msg|bool|hassilencer|}}<br />
{{hl2msg|bool|issilenced|}}<br />
{{hl2msg|bool|hastracers|}}<br />
{{hl2msg|short|weptype|see below}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_UNKNOWN &#61; -1}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_KNIFE &#61; 0}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_PISTOL &#61; 1}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_SUBMACHINEGUN &#61; 2}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_RIFLE &#61; 3}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_SHOTGUN &#61; 4}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_SNIPER_RIFLE &#61; 5}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_MACHINEGUN &#61; 6}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_C4 &#61; 7}}<br />
{{hl2msg|''none''|''none''|WEAPONTYPE_GRENADE &#61; 8}}<br />
{{hl2msg|bool|ispainted|}}<br />
{{end-hl2msg}}<br />
<br />
=== enter_buyzone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|enter_buyzone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|bool|canbuy|}}<br />
{{end-hl2msg}}<br />
<br />
=== exit_buyzone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|exit_buyzone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|bool|canbuy|}}<br />
{{end-hl2msg}}<br />
<br />
=== buytime_ended ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|buytime_ended|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== enter_bombzone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|enter_bombzone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|bool|hasbomb|}}<br />
{{hl2msg|bool|isplanted|}}<br />
{{end-hl2msg}}<br />
<br />
=== exit_bombzone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|exit_bombzone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|bool|hasbomb|}}<br />
{{hl2msg|bool|isplanted|}}<br />
{{end-hl2msg}}<br />
<br />
=== enter_rescue_zone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|enter_rescue_zone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== exit_rescue_zone ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|exit_rescue_zone|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== silencer_off ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|silencer_off|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== silencer_on ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|silencer_on|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== buymenu_open ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|buymenu_open|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== buymenu_close ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|buymenu_close|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== round_prestart ===<br />
{{qnotice|sent before all other round restart actions}}<br />
{{begin-hl2msg|round_prestart|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== round_poststart ===<br />
{{qnotice|sent after all other round restart actions}}<br />
{{begin-hl2msg|round_poststart|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== round_start ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|round_start|string}}<br />
{{hl2msg|long|timelimit|round time limit in seconds}}<br />
{{hl2msg|long|fraglimit|frag limit in seconds}}<br />
{{hl2msg|string|objective|round objective}}<br />
{{end-hl2msg}}<br />
<br />
=== round_end ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|round_end|string}}<br />
{{hl2msg|byte|winner|winner team/user id}}<br />
{{hl2msg|byte|reason|reson why team won}}<br />
{{hl2msg|string|message|round end round message }}<br />
{{end-hl2msg}}<br />
<br />
=== grenade_bounce ===<br />
{{qnotice|Every time a grenade bounces}}<br />
{{begin-hl2msg|grenade_bounce|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== hegrenade_detonate ===<br />
{{qnotice|Every time a hegrenade explodes}}<br />
{{begin-hl2msg|hegrenade_detonate|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== flashbang_detonate ===<br />
{{qnotice|Every time a flashbang detonates}}<br />
{{begin-hl2msg|flashbang_detonate|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== smokegrenade_detonate ===<br />
{{qnotice|Every time a smokegrenade detonates}}<br />
{{begin-hl2msg|smokegrenade_detonate|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== smokegrenade_expired ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|smokegrenade_expired|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== molotov_detonate ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|molotov_detonate|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== decoy_detonate ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|decoy_detonate|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== decoy_started ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|decoy_started|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== inferno_startburn ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|inferno_startburn|string}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== inferno_expire ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|inferno_expire|string}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== inferno_extinguish ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|inferno_extinguish|string}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== decoy_firing ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|decoy_firing|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|entityid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== bullet_impact ===<br />
{{qnotice|Every time a bullet hits something}}<br />
{{begin-hl2msg|bullet_impact}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|float|x|}}<br />
{{hl2msg|float|y|}}<br />
{{hl2msg|float|z|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_footstep ===<br />
{{qnotice|Every time a player takes a step}}<br />
{{begin-hl2msg|player_footstep|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_jump ===<br />
{{qnotice|Every time a player jumps}}<br />
{{begin-hl2msg|player_jump|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_blind ===<br />
{{qnotice|Every time a player is blinded by a flashbang}}<br />
{{begin-hl2msg|player_blind|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_falldamage ===<br />
{{qnotice|Every time a player takes damage due to a fall}}<br />
{{begin-hl2msg|player_falldamage|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|float|damage|}}<br />
{{end-hl2msg}}<br />
<br />
=== door_moving ===<br />
{{qnotice|Every time a door is put in motion (opened)}}<br />
{{begin-hl2msg|door_moving|string}}<br />
{{hl2msg|long|entindex|}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== round_freeze_end ===<br />
{{qnotice|When the round's mp_freezetime is up}}<br />
{{begin-hl2msg|round_freeze_end|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== mb_input_lock_success ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|mb_input_lock_success|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== mb_input_lock_cancel ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|mb_input_lock_cancel|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== nav_blocked ===<br />
{{qnotice|''Guess: Called when an area is blocked by the nav of a map''}}<br />
{{begin-hl2msg|nav_blocked|string}}<br />
{{hl2msg|long|area|}}<br />
{{hl2msg|bool|blocked|}}<br />
{{end-hl2msg}}<br />
<br />
=== nav_generate ===<br />
{{qnotice|Called when a nav file does not exist for a map and bots are added}}<br />
{{begin-hl2msg|nav_generate|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_stats_updated ===<br />
{{qnotice|''Guess: Called when the player stats (achievments) are sent to valve''}}<br />
{{begin-hl2msg|player_stats_updated|string}}<br />
{{hl2msg|bool|forceupload|}}<br />
{{end-hl2msg}}<br />
<br />
=== achievement_info_loaded ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|achievement_info_loaded|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== spec_target_updated ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|spec_target_updated|string}}<br />
{{hl2msg|byte|userid|entindex of the player}}<br />
{{end-hl2msg}}<br />
<br />
=== spec_mode_updated ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|spec_target_updated|string}}<br />
{{hl2msg|byte|userid|entindex of the player}}<br />
{{end-hl2msg}}<br />
<br />
=== hltv_changed_mode ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|hltv_changed_mode|string}}<br />
{{hl2msg|long|oldmode|}}<br />
{{hl2msg|long|newmode|}}<br />
{{hl2msg|long|obs_target|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_game_disconnected ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_game_disconnected|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_win_panel_round ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_win_panel_round|string}}<br />
{{hl2msg|bool|show_timer_defend|}}<br />
{{hl2msg|bool|show_timer_attack|}}<br />
{{hl2msg|short|timer_time|}}<br />
{{hl2msg|byte|final_event|defined in cs_gamerules.h}}<br />
{{hl2msg|string|funfact_token|}}<br />
{{hl2msg|short|funfact_player|}}<br />
{{hl2msg|long|funfact_data1|}}<br />
{{hl2msg|long|funfact_data2|}}<br />
{{hl2msg|long|funfact_data3|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_win_panel_match ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_win_panel_match|string}}<br />
{{hl2msg|''none''|''none''|Well nothing defined in CS:GO but maybe it's the same as in CS:S}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_match_end_restart ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_match_end_restart|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_pre_restart ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_pre_restart|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== show_freezepanel ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|show_freezepanel|string}}<br />
{{hl2msg|short|victim|endindex of the one who was killed}}<br />
{{hl2msg|short|killer|entindex of the killer entity}}<br />
{{hl2msg|short|hits_taken|}}<br />
{{hl2msg|short|damage_taken|}}<br />
{{hl2msg|short|hits_given|}}<br />
{{hl2msg|short|damage_given|}}<br />
{{end-hl2msg}}<br />
<br />
=== hide_freezepanel ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|hide_freezepanel|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== freezecam_started ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|freezecam_started|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_avenged_teammate ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|player_avenged_teammate|string}}<br />
{{hl2msg|short|avenger_id|}}<br />
{{hl2msg|short|avenged_player_id|}}<br />
{{end-hl2msg}}<br />
<br />
=== achievement_earned ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|achievement_earned|string}}<br />
{{hl2msg|byte|player|entindex of the player}}<br />
{{hl2msg|short|achievement|achievement ID}}<br />
{{end-hl2msg}}<br />
<br />
=== achievement_earned_local ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|achievement_earned_local|string}}<br />
{{hl2msg|short|achievement|achievement ID}}<br />
{{hl2msg|short|splitscreenplayer|splitscreen ID}}<br />
{{end-hl2msg}}<br />
<br />
=== item_found ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|item_found|string}}<br />
{{hl2msg|byte|player|entindex of the player}}<br />
{{hl2msg|byte|quality|quality of the item}}<br />
{{hl2msg|byte|method|method by which we acquired the item}}<br />
{{hl2msg|long|itemdef|the item definition index}}<br />
{{hl2msg|long|itemid|the item id in the players inventory}}<br />
{{end-hl2msg}}<br />
<br />
=== item_gifted ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|item_gifted|string}}<br />
{{hl2msg|byte|player|entindex of the player who sent the gift}}<br />
{{hl2msg|long|itemdef|the item definition index of the gift that was opened}}<br />
{{hl2msg|byte|numgifts|how many recipients got the gifts in this gift batch}}<br />
{{hl2msg|byte|giftidx|index of recipient in this gift batch (0 for the first recipient, 1 for second, and so on...)}}<br />
{{hl2msg|long|accountid|gift recipient's account ID}}<br />
{{end-hl2msg}}<br />
<br />
=== repost_xbox_achievements ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|repost_xbox_achievements|string}}<br />
{{hl2msg|short|splitscreenplayer|splitscreen ID}}<br />
{{end-hl2msg}}<br />
<br />
<br />
=== match_end_conditions ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|match_end_conditions|string}}<br />
{{hl2msg|long|frags|}}<br />
{{hl2msg|long|max_rounds|}}<br />
{{hl2msg|long|win_rounds|}}<br />
{{hl2msg|long|time|}}<br />
{{end-hl2msg}}<br />
<br />
=== round_mvp ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|round_mvp|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|reason|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_decal ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|player_decal|string}}<br />
{{hl2msg|short|userid|}}<br />
{{end-hl2msg}}<br />
<br />
=== teamplay_round_start ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|teamplay_round_start|string}}<br />
{{hl2msg|bool|full_reset|is this a full reset of the map}}<br />
{{end-hl2msg}}<br />
<br />
=== client_disconnect===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|client_disconnect|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_player_levelup ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_player_levelup|string}}<br />
{{hl2msg|short|userid|player who leveled up}}<br />
{{hl2msg|short|weaponrank|}}<br />
{{hl2msg|string|weaponname|name of weapon being awarded}}<br />
{{end-hl2msg}}<br />
<br />
=== ggtr_player_levelup ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|ggtr_player_levelup|string}}<br />
{{hl2msg|short|userid|player who leveled up}}<br />
{{hl2msg|short|weaponrank|}}<br />
{{hl2msg|string|weaponname|name of weapon being awarded}}<br />
{{end-hl2msg}}<br />
<br />
=== ggprogressive_player_levelup ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|ggprogressive_player_levelup|string}}<br />
{{hl2msg|short|userid|player who leveled up}}<br />
{{hl2msg|short|weaponrank|}}<br />
{{hl2msg|string|weaponname|name of weapon being awarded}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_killed_enemy ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_killed_enemy|string}}<br />
{{hl2msg|short|victimid|user ID who died}}<br />
{{hl2msg|short|attackerid|user ID who killed}}<br />
{{hl2msg|short|dominated|did killer dominate victim with this kill}}<br />
{{hl2msg|short|revenge|did killer get revenge on victim with this kill}}<br />
{{hl2msg|bool|bonus|did killer kill with a bonus weapon?}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_final_weapon_achieved ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_final_weapon_achieved|string}}<br />
{{hl2msg|short|playerid|user ID who achieved the final gun game weapon}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_bonus_grenade_achieved ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_bonus_grenade_achieved|string}}<br />
{{hl2msg|short|userid|user ID who achieved the bonus grenade}}<br />
{{end-hl2msg}}<br />
<br />
=== switch_team ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|switch_team|string}}<br />
{{hl2msg|short|numPlayers|number of active players on both T and CT}}<br />
{{hl2msg|short|numSpectators|number of spectators}}<br />
{{hl2msg|short|avg_rank|average rank of human players}}<br />
{{hl2msg|short|numTSlotsFree|}}<br />
{{hl2msg|short|numCTSlotsFree|}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_leader ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_leader|string}}<br />
{{hl2msg|short|playerid|user ID that is currently in the lead}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_player_impending_upgrade ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_player_impending_upgrade|string}}<br />
{{hl2msg|short|userid|player who will be leveling up}}<br />
{{end-hl2msg}}<br />
<br />
=== write_profile_data ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|write_profile_data|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== trial_time_expired ===<br />
{{qnotice|fired when a player runs out of time in trial mode}}<br />
{{begin-hl2msg|trial_time_expired|string}}<br />
{{hl2msg|short|slot|player whose time has expired}}<br />
{{end-hl2msg}}<br />
<br />
=== update_matchmaking_stats ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|update_matchmaking_stats|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_reset_vote ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|player_reset_vote|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|vote|}}<br />
{{end-hl2msg}}<br />
<br />
=== enable_restart_voting ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|enable_restart_voting|string}}<br />
{{hl2msg|bool|enable|}}<br />
{{end-hl2msg}}<br />
<br />
=== sfuievent ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|sfuievent|string}}<br />
{{hl2msg|string|action|}}<br />
{{hl2msg|string|data|}}<br />
{{hl2msg|byte|slot|}}<br />
{{end-hl2msg}}<br />
<br />
=== start_vote ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|start_vote|string}}<br />
{{hl2msg|short|userid|user ID on server}}<br />
{{hl2msg|byte|type|}}<br />
{{hl2msg|short|vote_parameter|}}<br />
{{end-hl2msg}}<br />
<br />
=== player_given_c4 ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|player_given_c4|string}}<br />
{{hl2msg|short|userid|user ID who received the c4}}<br />
{{end-hl2msg}}<br />
<br />
=== gg_reset_round_start_sounds ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|gg_reset_round_start_sounds|string}}<br />
{{hl2msg|short|userid|user ID who should have round start sounds reset}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_player_flashbanged ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_player_flashbanged|string}}<br />
{{hl2msg|short|userid|user ID of the player banged}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_highlight_ammo ===<br />
{{qnotice|not used yet because this relied on vgui panels, scaleform isn't supported yet}}<br />
{{begin-hl2msg|tr_highlight_ammo|string}}<br />
{{hl2msg|short|userid|user ID of the player}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_mark_complete ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_mark_complete|string}}<br />
{{hl2msg|short|complete|}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_mark_best_time ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_mark_best_time|string}}<br />
{{hl2msg|long|time|}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_exit_hint_trigger ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_exit_hint_trigger|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== bot_takeover ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|bot_takeover|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|short|botid|}}<br />
{{hl2msg|short|index|}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_show_finish_msgbox ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_show_finish_msgbox|string}}<br />
{{hl2msg|short|userid|user ID of the player}}<br />
{{end-hl2msg}}<br />
<br />
=== tr_show_exit_msgbox ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tr_show_exit_msgbox|string}}<br />
{{hl2msg|short|userid|user ID of the player}}<br />
{{end-hl2msg}}<br />
<br />
=== reset_player_controls ===<br />
{{qnotice|used for demos}}<br />
{{begin-hl2msg|reset_player_controls|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== jointeam_failed ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|jointeam_failed|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|byte|reason|3 = 0 = team_full}}<br />
{{end-hl2msg}}<br />
<br />
=== teamchange_pending ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|teamchange_pending|string}}<br />
{{hl2msg|short|userid|}}<br />
{{hl2msg|byte|toteam|}}<br />
{{end-hl2msg}}<br />
<br />
=== material_default_complete ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|material_default_complete|string}}<br />
{{hl2msg|''none''|''none''|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_prev_next_spectator ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_prev_next_spectator|string}}<br />
{{hl2msg|bool|next|}}<br />
{{end-hl2msg}}<br />
<br />
=== cs_handle_ime_event ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|cs_handle_ime_event|string}}<br />
{{hl2msg|1|local|}}<br />
{{hl2msg|string|eventtype|}}<br />
{{hl2msg|wstring|eventdata|}}<br />
{{end-hl2msg}}<br />
<br />
=== nextlevel_changed ===<br />
{{qnotice|a game event, name may be 32 characters long}}<br />
{{begin-hl2msg|nextlevel_changed|string}}<br />
{{hl2msg|string|nextlevel|weapon name killer used}}<br />
{{end-hl2msg}}<br />
<br />
=== seasoncoin_levelup ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|seasoncoin_levelup|string}}<br />
{{hl2msg|short|player|}}<br />
{{hl2msg|short|category|}}<br />
{{hl2msg|short|rank|}}<br />
{{end-hl2msg}}<br />
<br />
=== tournament_reward ===<br />
{{qnotice|-}}<br />
{{begin-hl2msg|tournament_reward|string}}<br />
{{hl2msg|long|defindex|}}<br />
{{hl2msg|long|totalrewards|}}<br />
{{hl2msg|long|accountid|}}<br />
{{end-hl2msg}}<br />
<br />
=== start_halftime ===<br />
{{qnotice|}}<br />
{{begin-hl2msg|start_halftime|string}}<br />
{{end-hl2msg}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Introduction_to_SourceMod_Plugins&diff=10091Introduction to SourceMod Plugins2015-12-22T20:07:07Z<p>Fyren: Undo revision 10051 by MrTimcakes (talk) - no, "we" don't recommend it</p>
<hr />
<div>This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.<br />
<br />
For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [http://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++], [http://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio] or any other text editor you're comfortable with to write plugins.<br />
<br />
=Starting from scratch=<br />
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not now about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This it done using <tt>#include</tt> directive. It tells compiler to "paste" the code from another file into yours.<br />
<pawn>#include <sourcemod></pawn><br />
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if compiler doesn't know about existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. Compiler understands that and generate a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].<br />
<br />
=Setting up plugin info=<br />
Now that we got access to SourceMod features, it is time to setup the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin are going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:<br />
<pawn>/**<br />
* Plugin public information.<br />
*/<br />
struct Plugin<br />
{<br />
public const char[] name; /**< Plugin Name */<br />
public const char[] description; /**< Plugin Description */<br />
public const char[] author; /**< Plugin Author */<br />
public const char[] version; /**< Plugin Version */<br />
public const char[] url; /**< Plugin URL */<br />
};</pawn><br />
and this:<br />
<pawn>/**<br />
* Declare this as a struct in your plugin to expose its information.<br />
* Example:<br />
*<br />
* public Plugin myinfo =<br />
* {<br />
* name = "My Plugin",<br />
* //etc<br />
* };<br />
*/<br />
public Plugin myinfo;</pawn><br />
<br />
It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:<br />
<pawn>public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};</pawn><br />
<br />
The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin:</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is preferred way to do when filling out plugin info.<br />
<br />
After that the full code of your plugin should look like this:<br />
<pawn>#include <sourcemod><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};</pawn><br />
<br />
=Getting code to run=<br />
We already include SourceMod features and filled up or plugin info. We now have a perfectly well formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:<br />
<pawn>/**<br />
* Called when the plugin is fully initialized and all known external references <br />
* are resolved. This is only called once in the lifetime of the plugin, and is <br />
* paired with OnPluginEnd().<br />
*<br />
* If any run-time error is thrown during this callback, the plugin will be marked <br />
* as failed.<br />
*<br />
* It is not necessary to close any handles or remove hooks in this function. <br />
* SourceMod guarantees that plugin shutdown automatically and correctly releases <br />
* all resources.<br />
*<br />
* @noreturn<br />
*/<br />
forward void OnPluginStart();</pawn><br />
Empty parentheses tells us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:<br />
<pawn>public void OnPluginStart()<br />
{<br />
}</pawn><br />
<br />
Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.<br />
<pawn>/**<br />
* Sends a message to the server console.<br />
*<br />
* @param format Formatting rules.<br />
* @param ... Variable number of format parameters.<br />
* @noreturn<br />
*/<br />
native int PrintToServer(const char[] format, any ...);</pawn><br />
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:<br />
<pawn>public void OnPluginStart()<br />
{<br />
PrintToServer("Hello world!");<br />
}</pawn><br />
That's it! The full code of your plugin should look like this:<br />
<pawn>#include <sourcemod><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};<br />
<br />
public void OnPluginStart()<br />
{<br />
PrintToServer("Hello world!");<br />
}</pawn><br />
Compile and load your plugin on your server and see for yourself that the message is displayed in server console.<br />
<br />
=Includes=<br />
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:<br />
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.<br />
*'''Extension''' - adds a dependency against a certain extension.<br />
*'''Plugin''' - adds a dependency against a certain plugin.<br />
<br />
Include files are loaded using the <tt>#include</tt> compiler directive.<br />
<br />
=Commands=<br />
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.<br />
<br />
==Declaration==<br />
First, let's look at what an admin command requires. Admin commands are registered using the [https://sm.alliedmods.net/new-api/console/RegAdminCmd RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''. <br />
<br />
The callback function is what's invoked every time the command is used. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:<br />
<br />
<pawn><br />
public void OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
}</pawn><br />
<br />
Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.<br />
<br />
<pawn>public Action Command_MySlap(int client, int args)<br />
{<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.<br />
<br />
==Implementation==<br />
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:<br />
<pre>sm_myslap <name|#userid> [damage]</pre><br />
<br />
To implement this, we'll need a few steps:<br />
*Get the input from the console. For this we use [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].<br />
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].<br />
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.<br />
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand ReplyToCommand()].<br />
<br />
Full example:<br />
<br />
<pawn><br />
#include <sourcemod><br />
#include <sdktools><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0.0.0",<br />
url = "http://www.sourcemod.net/"<br />
}<br />
<br />
public void OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage;<br />
<br />
/* Get the first argument */<br />
GetCmdArg(1, arg1, sizeof(arg1));<br />
<br />
/* If there are 2 or more arguments, and the second argument fetch <br />
* is successful, convert it to an integer.<br />
*/<br />
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))<br />
{<br />
damage = StringToInt(arg2);<br />
}<br />
<br />
/* Try and find a matching player */<br />
int target = FindTarget(client, arg1);<br />
if (target == -1)<br />
{<br />
/* FindTarget() automatically replies with the <br />
* failure reason.<br />
*/<br />
return Plugin_Handled;<br />
}<br />
<br />
SlapPlayer(target, damage);<br />
<br />
char name[MAX_NAME_LENGTH];<br />
<br />
GetClientName(target, name, sizeof(name));<br />
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage);<br />
<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.<br />
<br />
=ConVars=<br />
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).<br />
<br />
The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.<br />
<br />
Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.<br />
<br />
<pawn>ConVar sm_myslap_damage = null;<br />
<br />
public void OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
<br />
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");<br />
AutoExecConfig(true, "plugin_myslap");<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage = GetConVarInt(sm_myslap_damage);<br />
<br />
/* The rest remains unchanged! */<br />
</pawn><br />
<br />
=Showing Activity, Logging=<br />
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.<br />
<br />
For example, let's rewrite the last few lines of our slap command:<br />
<pawn><br />
SlapPlayer(target, damage);<br />
<br />
char name[MAX_NAME_LENGTH];<br />
<br />
GetClientName(target, name, sizeof(name));<br />
<br />
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);<br />
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);<br />
<br />
return Plugin_Handled;<br />
}<br />
</pawn><br />
<br />
=Multiple Targets=<br />
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first. <br />
<br />
The function we use is [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString ProcessTargetString()]. It takes in input from the console, and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.<br />
<br />
This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.<br />
<br />
Full, final example:<br />
<pawn><br />
#include <sourcemod><br />
#include <sdktools><br />
<br />
ConVar sm_myslap_damage = null;<br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0.0.0",<br />
url = "http://www.sourcemod.net/"<br />
}<br />
<br />
public void OnPluginStart()<br />
{<br />
LoadTranslations("common.phrases");<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
<br />
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");<br />
AutoExecConfig(true, "plugin_myslap");<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage = GetConVarInt(sm_myslap_damage);<br />
<br />
/* Get the first argument */<br />
GetCmdArg(1, arg1, sizeof(arg1));<br />
<br />
/* If there are 2 or more arguments, and the second argument fetch <br />
* is successful, convert it to an integer.<br />
*/<br />
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))<br />
{<br />
damage = StringToInt(arg2);<br />
}<br />
<br />
/**<br />
* target_name - stores the noun identifying the target(s)<br />
* target_list - array to store clients<br />
* target_count - variable to store number of clients<br />
* tn_is_ml - stores whether the noun must be translated<br />
*/<br />
char target_name[MAX_TARGET_LENGTH];<br />
int target_list[MAXPLAYERS], target_count;<br />
bool tn_is_ml;<br />
<br />
if ((target_count = ProcessTargetString(<br />
arg1,<br />
client,<br />
target_list,<br />
MAXPLAYERS,<br />
COMMAND_FILTER_ALIVE, /* Only allow alive players */<br />
target_name,<br />
sizeof(target_name),<br />
tn_is_ml)) <= 0)<br />
{<br />
/* This function replies to the admin with a failure message */<br />
ReplyToTargetError(client, target_count);<br />
return Plugin_Handled;<br />
}<br />
<br />
for (int i = 0; i < target_count; i++)<br />
{<br />
SlapPlayer(target_list[i], damage);<br />
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);<br />
}<br />
<br />
if (tn_is_ml)<br />
{<br />
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);<br />
}<br />
else<br />
{<br />
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);<br />
}<br />
<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
=Client and Entity Indexes=<br />
One major point of confusion with Half-Life 2 is the difference between the following things:<br />
*Client index<br />
*Entity index<br />
*Userid<br />
<br />
The first answer is that clients are entities. Thus, a client index and an entity index are the same thing. When a SourceMod function asks for an entity index, a client index can be specified. When a SourceMod function asks for a client index, usually it means only a client index can be specified.<br />
<br />
A fast way to check if an entity index is a client is checking whether it's between 1 and [https://sm.alliedmods.net/new-api/clients/GetMaxClients GetMaxClients()] (inclusive). If a server has N client slots maximum, then entities 1 through N are always reserved for clients. Note that 0 is a valid entity index; it is the world entity (worldspawn).<br />
<br />
A userid, on the other hand, is completely different. The server maintains a global "connection count" number, and it starts at 1. Each time a client connects, the connection count is incremented, and the client receives that new number as their userid.<br />
<br />
For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Although SourceMod fires the OnClientConnected and OnClientDisconnected callbacks every map change, the server tracks players across map changes and does not change their userids or client indexes. To see if a client really connected or disconnected, hook the [[Generic Source Server Events#player_connect|player_connect]] and [[Generic Source Server Events#player_disconnect|player_disconnect]] events instead.<br />
<br />
SourceMod provides two functions for userids: [https://sm.alliedmods.net/new-api/clients/GetClientOfUserId GetClientOfUserId()] and [https://sm.alliedmods.net/new-api/clients/GetClientUserId GetClientUserId()].<br />
<br />
=Events=<br />
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].<br />
<br />
It is important to note a few concepts about events:<br />
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.<br />
*They almost always use userids instead of client indexes.<br />
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious at not properly documenting their event functionality.<br />
<br />
An example of finding when a player dies:<br />
<pawn><br />
public void OnPluginStart()<br />
{<br />
HookEvent("player_death", Event_PlayerDeath);<br />
}<br />
<br />
public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)<br />
{<br />
int victim_id = event.GetInt("userid");<br />
int attacker_id = event.GetInt("attacker");<br />
<br />
int victim = GetClientOfUserId(victim_id);<br />
int attacker = GetClientOfUserId(attacker_id);<br />
<br />
/* CODE */<br />
}</pawn><br />
<br />
=Callback Orders and Pairing=<br />
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which is confusing to users.<br />
<br />
==Pairing==<br />
'''Pairing''' is SourceMod terminology. Examples of it are:<br />
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().<br />
*OnClientConnected(N) for a given client N will only be called once, until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).<br />
<br />
There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:<br />
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.<br />
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.<br />
*Y cannot be invoked with any input A unless X was called first with input A.<br />
*The relationship is described as, "X is paired with Y," and "Y is paired to X."<br />
<br />
==General Callbacks==<br />
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.<br />
<br />
*[https://sm.alliedmods.net/new-api/sourcemod/AskPluginLoad2 AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here. <br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginStart OnPluginStart()] - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnAllPluginsLoaded OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart. <br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapStart OnMapStart()] - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnConfigsExecuted OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''<br />
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapEnd OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginEnd OnPluginEnd()] - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''<br />
<br />
==Client Callbacks==<br />
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.<br />
<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientConnect OnClientConnect()] - Called when a player initiates a connection. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientConnected OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''This is paired with OnClientDisconnect() for successful connections only.'''<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientAuthorized OnClientAuthorized()] - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientPutInServer OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientPostAdminCheck OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect OnClientDisconnect()] - Called when a player's disconnection starts. '''This is paired to OnClientConnected().'''<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect_Post OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''<br />
<br />
=Frequently Asked Questions=<br />
==Are plugins reloaded every mapchange?==<br />
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins. <br />
<br />
==Do I need to call CloseHandle in OnPluginEnd?==<br />
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.<br />
<br />
==Do I need to #include every individual .inc?==<br />
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.<br />
<br />
==Why don't some events fire?==<br />
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.<br />
<br />
==Do I need to CloseHandle timers?==<br />
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.<br />
<br />
==Are clients disconnected on mapchange?==<br />
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.<br />
<br />
If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.<br />
<br />
=Further Reading=<br />
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].<br />
<br />
[[Category:SourceMod Scripting]]<br />
<br />
{{LanguageSwitch}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Introduction_to_SourceMod_Plugins&diff=9939Introduction to SourceMod Plugins2015-07-13T01:19:13Z<p>Fyren: syntax fixes</p>
<hr />
<div>This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.<br />
<br />
For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [http://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++], [http://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio] or any other text editor you're comfortable with to write plugins.<br />
<br />
=Starting from scratch=<br />
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not now about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This it done using <tt>#include</tt> directive. It tells compiler to "paste" the code from another file into yours.<br />
<pawn>#include <sourcemod></pawn><br />
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if compiler doesn't know about existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. Compiler understands that and generate a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].<br />
<br />
=Setting up plugin info=<br />
Now that we got access to SourceMod features, it is time to setup the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin are going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:<br />
<pawn>/**<br />
* Plugin public information.<br />
*/<br />
struct Plugin<br />
{<br />
public const char[] name; /**< Plugin Name */<br />
public const char[] description; /**< Plugin Description */<br />
public const char[] author; /**< Plugin Author */<br />
public const char[] version; /**< Plugin Version */<br />
public const char[] url; /**< Plugin URL */<br />
};</pawn><br />
and this:<br />
<pawn>/**<br />
* Declare this as a struct in your plugin to expose its information.<br />
* Example:<br />
*<br />
* public Plugin myinfo =<br />
* {<br />
* name = "My Plugin",<br />
* //etc<br />
* };<br />
*/<br />
public Plugin myinfo;</pawn><br />
<br />
It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:<br />
<pawn>public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};</pawn><br />
<br />
The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin:</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is preferred way to do when filling out plugin info.<br />
<br />
After that the full code of your plugin should look like this:<br />
<pawn>#include <sourcemod><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};</pawn><br />
<br />
=Getting code to run=<br />
We already include SourceMod features and filled up or plugin info. We now have a perfectly well formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:<br />
<pawn>/**<br />
* Called when the plugin is fully initialized and all known external references <br />
* are resolved. This is only called once in the lifetime of the plugin, and is <br />
* paired with OnPluginEnd().<br />
*<br />
* If any run-time error is thrown during this callback, the plugin will be marked <br />
* as failed.<br />
*<br />
* It is not necessary to close any handles or remove hooks in this function. <br />
* SourceMod guarantees that plugin shutdown automatically and correctly releases <br />
* all resources.<br />
*<br />
* @noreturn<br />
*/<br />
forward void OnPluginStart();</pawn><br />
Empty parentheses tells us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:<br />
<pawn>public void OnPluginStart()<br />
{<br />
}</pawn><br />
<br />
Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.<br />
<pawn>/**<br />
* Sends a message to the server console.<br />
*<br />
* @param format Formatting rules.<br />
* @param ... Variable number of format parameters.<br />
* @noreturn<br />
*/<br />
native int PrintToServer(const char[] format, any ...);</pawn><br />
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:<br />
<pawn>public void OnPluginStart()<br />
{<br />
PrintToServer("Hello world!");<br />
}</pawn><br />
That's it! The full code of your plugin should look like this:<br />
<pawn>#include <sourcemod><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0",<br />
url = "http://www.sourcemod.net/"<br />
};<br />
<br />
public void OnPluginStart()<br />
{<br />
PrintToServer("Hello world!");<br />
}</pawn><br />
Compile and load your plugin on your server and see for yourself that the message is displayed in server console.<br />
<br />
=Includes=<br />
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:<br />
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.<br />
*'''Extension''' - adds a dependency against a certain extension.<br />
*'''Plugin''' - adds a dependency against a certain plugin.<br />
<br />
Include files are loaded using the <tt>#include</tt> compiler directive.<br />
<br />
=Commands=<br />
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.<br />
<br />
==Declaration==<br />
First, let's look at what an admin command requires. Admin commands are registered using the [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''. <br />
<br />
The callback function is what's invoked every time the command is used. [http://docs.sourcemod.net/api/index.php?fastload=show&id=771& Click here] to see its prototype. Example:<br />
<br />
<pawn><br />
public OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
}<br />
<br />
public Action:Command_MySlap(client, args)<br />
{<br />
}</pawn><br />
<br />
Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! The reason is because of the <tt>Action</tt> tag. Any command that you type in the console, even if it's registered by SourceMod, will be sent to the engine to be processed. Because we have not had SourceMod block this functionality yet, the engine replies with "Unknown command" because it is not a valid engine command.<br />
<br />
<pawn>public Action Command_MySlap(int client, int args)<br />
{<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.<br />
<br />
==Implementation==<br />
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:<br />
<pre>sm_myslap <name|#userid> [damage]</pre><br />
<br />
To implement this, we'll need a few steps:<br />
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].<br />
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].<br />
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.<br />
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].<br />
<br />
Full example:<br />
<br />
<pawn><br />
#include <sourcemod><br />
#include <sdktools><br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0.0.0",<br />
url = "http://www.sourcemod.net/"<br />
}<br />
<br />
public void OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage;<br />
<br />
/* Get the first argument */<br />
GetCmdArg(1, arg1, sizeof(arg1));<br />
<br />
/* If there are 2 or more arguments, and the second argument fetch <br />
* is successful, convert it to an integer.<br />
*/<br />
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))<br />
{<br />
damage = StringToInt(arg2);<br />
}<br />
<br />
/* Try and find a matching player */<br />
int target = FindTarget(client, arg1);<br />
if (target == -1)<br />
{<br />
/* FindTarget() automatically replies with the <br />
* failure reason.<br />
*/<br />
return Plugin_Handled;<br />
}<br />
<br />
SlapPlayer(target, damage);<br />
<br />
char name[MAX_NAME_LENGTH];<br />
<br />
GetClientName(target, name, sizeof(name));<br />
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage);<br />
<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.<br />
<br />
=ConVars=<br />
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).<br />
<br />
The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.<br />
<br />
Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.<br />
<br />
<pawn>ConVar sm_myslap_damage = null<br />
<br />
public void OnPluginStart()<br />
{<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
<br />
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");<br />
AutoExecConfig(true, "plugin_myslap");<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage = GetConVarInt(sm_myslap_damage);<br />
<br />
/* The rest remains unchanged! */<br />
</pawn><br />
<br />
=Showing Activity, Logging=<br />
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [http://docs.sourcemod.net/api/index.php?fastload=show&id=599& LogAction()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=466& ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.<br />
<br />
For example, let's rewrite the last few lines of our slap command:<br />
<pawn><br />
SlapPlayer(target, damage);<br />
<br />
char name[MAX_NAME_LENGTH];<br />
<br />
GetClientName(target, name, sizeof(name));<br />
<br />
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);<br />
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);<br />
<br />
return Plugin_Handled;<br />
}<br />
</pawn><br />
<br />
=Multiple Targets=<br />
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first. <br />
<br />
The function we use is [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. It takes in input from the console, and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.<br />
<br />
This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.<br />
<br />
Full, final example:<br />
<pawn><br />
#include <sourcemod><br />
#include <sdktools><br />
<br />
ConVar sm_myslap_damage = INVALID_HANDLE<br />
<br />
public Plugin myinfo =<br />
{<br />
name = "My First Plugin",<br />
author = "Me",<br />
description = "My first plugin ever",<br />
version = "1.0.0.0",<br />
url = "http://www.sourcemod.net/"<br />
}<br />
<br />
public void OnPluginStart()<br />
{<br />
LoadTranslations("common.phrases");<br />
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);<br />
<br />
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");<br />
AutoExecConfig(true, "plugin_myslap");<br />
}<br />
<br />
public Action Command_MySlap(int client, int args)<br />
{<br />
char arg1[32], arg2[32];<br />
int damage = GetConVarInt(sm_myslap_damage);<br />
<br />
/* Get the first argument */<br />
GetCmdArg(1, arg1, sizeof(arg1));<br />
<br />
/* If there are 2 or more arguments, and the second argument fetch <br />
* is successful, convert it to an integer.<br />
*/<br />
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))<br />
{<br />
damage = StringToInt(arg2);<br />
}<br />
<br />
/**<br />
* target_name - stores the noun identifying the target(s)<br />
* target_list - array to store clients<br />
* target_count - variable to store number of clients<br />
* tn_is_ml - stores whether the noun must be translated<br />
*/<br />
char target_name[MAX_TARGET_LENGTH];<br />
int target_list[MAXPLAYERS], target_count;<br />
bool tn_is_ml;<br />
<br />
if ((target_count = ProcessTargetString(<br />
arg1,<br />
client,<br />
target_list,<br />
MAXPLAYERS,<br />
COMMAND_FILTER_ALIVE, /* Only allow alive players */<br />
target_name,<br />
sizeof(target_name),<br />
tn_is_ml)) <= 0)<br />
{<br />
/* This function replies to the admin with a failure message */<br />
ReplyToTargetError(client, target_count);<br />
return Plugin_Handled;<br />
}<br />
<br />
for (int i = 0; i < target_count; i++)<br />
{<br />
SlapPlayer(target_list[i], damage);<br />
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);<br />
}<br />
<br />
if (tn_is_ml)<br />
{<br />
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);<br />
}<br />
else<br />
{<br />
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);<br />
}<br />
<br />
return Plugin_Handled;<br />
}</pawn><br />
<br />
=Client and Entity Indexes=<br />
One major point of confusion with Half-Life 2 is the difference between the following things:<br />
*Client index<br />
*Entity index<br />
*Userid<br />
<br />
The first answer is that clients are entities. Thus, a client index and an entity index are the same thing. When a SourceMod function asks for an entity index, a client index can be specified. When a SourceMod function asks for a client index, usually it means only a client index can be specified.<br />
<br />
A fast way to check if an entity index is a client is checking whether it's between 1 and [http://docs.sourcemod.net/api/index.php?fastload=show&id=397& GetMaxClients()] (inclusive). If a server has N client slots maximum, then entities 1 through N are always reserved for clients. Note that 0 is a valid entity index; it is the world entity (worldspawn).<br />
<br />
A userid, on the other hand, is completely different. The server maintains a global "connection count" number, and it starts at 1. Each time a client connects, the connection count is incremented, and the client receives that new number as their userid.<br />
<br />
For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Although SourceMod fires the OnClientConnected and OnClientDisconnected callbacks every map change, the server tracks players across map changes and does not change their userids or client indexes. To see if a client really connected or disconnected, hook the [[Generic Source Server Events#player_connect|player_connect]] and [[Generic Source Server Events#player_disconnect|player_disconnect]] events instead.<br />
<br />
SourceMod provides two functions for userids: [http://docs.sourcemod.net/api/index.php?fastload=show&id=442& GetClientOfUserId()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=402& GetClientUserId()].<br />
<br />
=Events=<br />
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].<br />
<br />
It is important to note a few concepts about events:<br />
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.<br />
*They almost always use userids instead of client indexes.<br />
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious at not properly documenting their event functionality.<br />
<br />
An example of finding when a player dies:<br />
<pawn><br />
public void OnPluginStart()<br />
{<br />
HookEvent("player_death", Event_PlayerDeath);<br />
}<br />
<br />
public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)<br />
{<br />
int victim_id = GetEventInt(event, "userid");<br />
int attacker_id = GetEventInt(event, "attacker");<br />
<br />
int victim = GetClientOfUserId(victim_id);<br />
int attacker = GetClientOfUserId(attacker_id);<br />
<br />
/* CODE */<br />
}</pawn><br />
<br />
=Callback Orders and Pairing=<br />
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which is confusing to users.<br />
<br />
==Pairing==<br />
'''Pairing''' is SourceMod terminology. Examples of it are:<br />
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().<br />
*OnClientConnected(N) for a given client N will only be called once, until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).<br />
<br />
There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:<br />
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.<br />
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.<br />
*Y cannot be invoked with any input A unless X was called first with input A.<br />
*The relationship is described as, "X is paired with Y," and "Y is paired to X."<br />
<br />
==General Callbacks==<br />
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.<br />
<br />
*[https://sm.alliedmods.net/new-api/sourcemod/AskPluginLoad2 AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here. <br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginStart OnPluginStart()] - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnAllPluginsLoaded OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart. <br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapStart OnMapStart()] - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnConfigsExecuted OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''<br />
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapEnd OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''<br />
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginEnd OnPluginEnd()] - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''<br />
<br />
==Client Callbacks==<br />
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.<br />
<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientConnect OnClientConnect()] - Called when a player initiates a connection. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientConnected OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''This is paired with OnClientDisconnect() for successful connections only.'''<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientAuthorized OnClientAuthorized()] - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientPutInServer OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientPostAdminCheck OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect OnClientDisconnect()] - Called when a player's disconnection starts. '''This is paired to OnClientConnected().'''<br />
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect_Post OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''<br />
<br />
=Frequently Asked Questions=<br />
==Are plugins reloaded every mapchange?==<br />
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins. <br />
<br />
==Do I need to call CloseHandle in OnPluginEnd?==<br />
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.<br />
<br />
==Do I need to #include every individual .inc?==<br />
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.<br />
<br />
==Why don't some events fire?==<br />
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.<br />
<br />
==Do I need to CloseHandle timers?==<br />
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.<br />
<br />
==Are clients disconnected on mapchange?==<br />
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.<br />
<br />
If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.<br />
<br />
=Further Reading=<br />
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].<br />
<br />
[[Category:SourceMod Scripting]]<br />
<br />
{{LanguageSwitch}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Custom_Admin_Menu_(SourceMod)&diff=9542Custom Admin Menu (SourceMod)2014-03-23T19:30:50Z<p>Fyren: /* Example Files */ fix links for CF</p>
<hr />
<div>==Introduction==<br />
The custom menu feature allows server admins to add new items to the SourceMod admin menu. It is designed to be used as a complement to plugins adding themselves to the menu. For more information see [[Admin Menu (SourceMod Scripting)]].<br />
<br />
Admins configure their menu using the config file (sourcemod/configs/adminmenu_custom.txt) and this is generated into a set of items and categories for the admin menu when the server starts.<br />
<br />
==Parameter List==<br />
<br />
These are all the parameters that can be specified to configure your menu. Most are optional and have a default value if they are not found. See the [[#Example Command|Example Command]] and/or the attached [[#Example Files|Example Files]] for information on how to lay out your config file.<br />
<br />
*cmd - command to be executed (#1,#2 etc for parameters - no limit on these) Use @num to have the parameter sent without being surrounded by "quotes"<br />
*admin - admin level required to access the command - see [[#Admin Levels|Admin Levels]]<br />
*execute - 'server' or 'player' - selects whether to execute as a client command or server command - defaults to 'player'<br />
*1 - Information about parameter 1 (#1) - You need as many of these as you have parameters<br />
**type - defaults to 'list' if not provided<br />
***'groupplayer' - List of [[#Group Submenus|Groups]] + connected player <br />
***'group' - List of [[#Group Submenus|Groups]]<br />
***'player' - List of players<br />
***'list' - Custom Defined list of Options<br />
***'mapcycle' - Auto filled with the contents of your mapcycle file<br />
***'onoff' - On or Off menu that sends the numbers 1/0 (good for cvars etc)<br />
**path - Only required for type mapcycle. Path (including file name and extension) to the file containing a list of maps (straight text formatting like mapcycle.txt) - defaults to 'mapcycle.txt'<br />
**method - 'name', 'steamid', 'userid', 'userid2' (doesn't prepend the '#'), 'clientid', 'ip' - only needed for groupplayer/player menus - defaults to name<br />
**title - To be shown for the parameter selection menu (optional)<br />
**1-x - List parameters - only needed for 'list' type parameters<br />
**1.-x. - Text to be shown for parameter - only needed for 'list' type parameters (optional, above will be used as text if ommited)<br />
**1* - x* - Admin level required to see this option (same as the rest of the admin types)<br />
<br />
==Example Command==<br />
<pawn><br />
"Commands"<br />
{<br />
"Fun Commands"<br />
{<br />
"Set Player Speed"<br />
{<br />
"cmd" "sm_speed #1 @2"<br />
"admin" "sm_kick"<br />
"execute" "player"<br />
"1"<br />
{<br />
"type" "groupplayer"<br />
"method" "name"<br />
"title" "Player/Team to Edit"<br />
<br />
}<br />
"2"<br />
{<br />
"type" "list"<br />
"title" "Speed Multiplier"<br />
"1" "1.0"<br />
"1." "Normal"<br />
"2" "0.8"<br />
"2." "80%"<br />
"3" "0.5"<br />
"3." "Half"<br />
"4" "1.5"<br />
"4." "50% Boost"<br />
"5" "2.0"<br />
"5." "Double"<br />
"5*" "sm_ban" <br />
//restrict the double option to admins who have access to the 'sm_ban' override<br />
}<br />
<br />
}<br />
}<br />
}<br />
</pawn><br />
Using the above as the contents of your adminmenu_custom.txt config file would create a new category option in the admin menu called 'Fun Commands'.<br />
*This category would contain an option called : "Set Player Speed".<br />
*Selecting it would prompt another menu titled: "Player/Team to Edit" containing a list of Groups and Player Names.<br />
*Selecting one of these would prompt a second menu titled "Speed Multiplier".<br />
*List of options like "Normal", "80%" etc.<br />
*Example command sent if the user selected "Double" (through the player using FakeClientCommand) - 'sm_speed "@CT" 2.0'<br />
<br />
NB: You can use \ as an escape character. So \" will let you add quotes to your strings.<br />
<br />
==Admin Levels==<br />
<br />
All 'admin' types now require a string command name. This command can be already existing (sm_ban) or completely imaginary (onlycrabscanusethis).<br />
<br />
If the command exists that section (or list option) will require the exact same access level as that command (including any overrides you have specified).<br><br />
E.g. You use sm_ban as the admin level for a submenu, so anyone that can access sm_ban will also be able to access this menu option (By default this is admins with the 'ban' flag). However if you have overridden sm_ban in one of your lower groups ("override" "allow" - in admin_groups.cfg). This group will also have access.<br />
<br />
If the command doesn't exist you will need to add it to your overrides sections as if it was a normal command. This can be done in admin_overrides.cfg (to assign flag letters to this command),<br />
and/or in admin_groups.cfg (to give access to the command to a specified group or remove it from a group even though they have the flag)<br />
<br />
If no admin level is specified for a base command it will default to the first argument of the "cmd" string. For example having<br />
<pawn><br />
"cmd" "sm_ban #1 #2"<br />
</pawn><br />
<br />
would have a default admin override string of 'sm_ban'<br />
<br />
For more information, see [[Overriding Command Access (SourceMod)|Overriding Command Access]]<br />
<br />
==Group Submenus==<br />
<br />
Types 'group' and 'groupplayer' auto-add pre configured options to the menu. These options are configured using sourcemod/configs/adminmenu_grouping.txt<br />
<br />
They are generally used to provide common commands like '@all' , '@t' etc to your menus.<br />
<br />
==Categories==<br />
<br />
If you wish to add items to an existing SourceMod category you will need to specify it’s internal name within the "commands" group. The three categories provided by SourceMod are:<br />
<br />
*PlayerCommands<br />
*ServerCommands<br />
*VotingCommands<br />
<br />
==Sorting==<br />
Categories and items added using the dynamic menu can be sorted in the same way as normal items. For more information, see [[Admin Menu Configuration (SourceMod)|Admin Menu Configuration]]<br />
<br />
You need to specify the name you gave the command in your configuration file. For the provided example:<br />
<pawn><br />
"item" "Set Player Speed"<br />
</pawn><br />
==Extra Uses==<br />
An example of using the dynamic menu to its full potential: Giving admins access to some cvars while not letting them have general 'sm_cvar' access.<br />
<br />
Add the cvar you want to make available using the command directly and set the 'execute' parameter to 'server'<br />
<pawn><br />
"cmd" "mp_friendlyfire #1"<br />
"execute" "server"<br />
"admin" "sm_kick"<br />
</pawn><br />
This fires the command directly through rcon so it bypasses the normal SourceMod admin requirements and only checks what you set using the 'admin' parameter. This method can be used to create a list of commonly used (and low impact) cvars that your lower admins can change at will, without giving them access to everything. The same method works for rcon commands.<br />
<br />
==Example Files==<br />
<br />
Example adminmenu_custom.txt setup with Super Commands examples:<br><br />
[http://users.alliedmods.net/~pred/supercmdsmenu.ini adminmenu_custom.txt]<br><br />
<br><br />
A Full example setup thanks to uE|Tekniqal:<br><br />
[http://users.alliedmods.net/~pred/smsuper.ini adminmenu_custom.txt]<br><br />
[http://users.alliedmods.net/~pred/admin_overrides.cfg admin_overrides.cfg]<br><br />
[http://users.alliedmods.net/~pred/admin_groups.cfg admin_groups.cfg]<br><br />
<br />
<br />
[[Category:SourceMod Documentation]]<br />
<br />
{{LanguageSwitch}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Main_Page&diff=9097Main Page2013-10-15T05:30:07Z<p>Fyren: </p>
<hr />
<div>__NOTOC__<br />
Welcome to the AlliedModders Wiki. This is where you can find documentation about our projects and development.<br />
<br />
=Projects=<br />
{| width="80%" style="text-align: left;"<br />
| style="width: 110px;" | [[Image:Sm_small.gif|left]]<br />
| style="vertical-align: top;" | [[SourceMod]], the optimized and highly extensible scripting and administration environment for [[Half-Life 2]].<br />
* [[:Category:SourceMod Documentation|Documentation]]<br />
* [[:Category:SourceMod Scripting|Scripting]]<br />
* [[:Category:SourceMod Development|Development]]<br />
| style="width: 110px; padding-left: 20px;" | [[Image:Mms.jpg|left]]<br />
| style="vertical-align: top;" | [[Metamod:Source]], the ultimate plugin API for [[Half-Life 2]], featuring interface hooking and a versatile plugin API.<br />
* [[:Category:Metamod:Source Documentation|Documentation]]<br />
* [[:Category:Metamod:Source Development|Development]]<br />
|-<br />
| style="padding-bottom: 20px;" |<br />
| style="padding-bottom: 20px;" |<br />
| style="padding-bottom: 20px;" |<br />
| style="padding-bottom: 20px;" |<br />
|-<br />
| style="width: 110px;" | [[Image:Amxxsmall.gif|left]]<br />
| [[AMX Mod X]], the powerful and flexible scripting environment for [[Half-Life 1]].<br />
* [[:Category:Documentation (AMX Mod X)|Documentation]]<br />
* [[:Category:Scripting (AMX Mod X)|Scripting]]<br />
|}<br />
<br />
==Mercurial Tutorial==<br />
AlliedModders uses Mercurial for source code management. Interested in how it works? Check out the [[Mercurial Tutorial|Mercurial tutorial]]!</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Releasing_Products&diff=8340Releasing Products2011-10-29T03:22:00Z<p>Fyren: </p>
<hr />
<div>This is an internal page for doing AlliedModders product releases.<br />
<br />
=Making Builds=<br />
<ol><br />
<li>Once you are '''absolutely sure''' the product is ready for a release...</li><br />
<li>Jump to a Linux system, check out the source tree.</li><br />
<li>Update the changelog (<tt>changelog.txt</tt> for SourceMod, <tt>support/changelog.txt</tt> for Metamod:Source).</li><br />
<li>Edit the build_type file and change the "dev" string to "rel" (<tt>tools/buildbot/build_type</tt> for SourceMod, <tt>support/buildbot/build_type</tt> for Metamod:Source).<br />
<li>Edit <tt>product.version</tt> to remove the -dev tag.</li><br />
<li>For SourceMod, edit <tt>plugins/include/version.inc</tt> to remove the -dev tag.</li><br />
<li>Commit the changes.</li><br />
<li>Push. Watch the waterfall page until builds are complete.</li><br />
</ol><br />
<br />
=Post-Build Work=<br />
<ol><br />
<li>Grab the binaries from the drop site ([http://metamodsource.net/mmsdrop/ MM:S drop site], [http://sourcemod.net/smdrop/ SourceMod drop site]). It will be the latest package.</li><br />
<li>Install the packages on both Linux and Windows. '''MAKE SURE THE VERSIONS ARE CORRECT. THERE SHOULD BE NO -dev TAG.'''<br />
<br><br><br />
Metamod:Source checks:<br />
<pre><br />
meta version<br />
</pre><br />
SourceMod checks:<br />
<pre><br />
sm plugins list<br />
sm exts list<br />
sm version<br />
</pre></li><br />
<li>If the versions are not correct, do not release.</li><br />
<li>For SourceMod, you need to add the language translation packs. <br />
<br><br><br />
'''If this is a major release (1.X.0), there is no prior pack. Make one:'''<br />
<ol><br />
<li>Extract both the tar.gz and zip files to separate folders.</li><br />
<li>Visit the [http://www.sourcemod.net/translator/?go=translate&op=status translator status page].</li><br />
<li>Click "export languages.cfg" - save the new version to <tt>addons/sourcemod/configs/</tt>, overwriting the old one.</li><br />
<li>Click "export" next to each language that is finished. Extract the folder to <tt>addons/sourcemod/translations/</tt>. For example, if you extract Spanish, you should have <tt>addons/sourcemod/translations/es/</tt> complete with ML files.</li><br />
<li>Repackage thefolders using the correct compression types (.tar.gz for Linux, .zip for Windows).</li><br />
</ol><br />
<b>If this is a minor release (1.X.Y where Y != 0), there is already a prior pack. Add it in:</b><br />
<ol><br />
<li>Extract both the tar.gz and zip files to separate folders.</li><br />
<li>Download the last minor release from the same branch as this release.</li><br />
<li>Copy the <tt>addons/sourcemod/configs/languages.cfg</tt> file from the old release over the new one.</li><br />
<li>Copy the <tt>addons/sourcemod/translations/</tt> sub-folders from the old release over to the new one.</li><br />
<li>Repackage thefolders using the correct compression types (.tar.gz for Linux, .zip for Windows).</li><br />
</ol><br />
<li>The build is done!</li><br />
</ol><br />
<br />
=Releasing to Mirrors=<br />
<ol><br />
<li>Log into iroh as yourself. Upload your final builds to your home directory.</li><br />
<li>Run:<br />
<pre><br />
/scripts/amjump mirror<br />
cd /scripts/mirror<br />
</pre><br />
</li><br />
<li>Copy your final builds from your home directory into the mirror folder. Rename them to release names, for example: <tt>sourcemod-1.1.2-windows.zip</tt> or <tt>mmsource-1.8.0-linux-tar.gz</tt>.</li><br />
<li>Mirror distribution is done with the following command:<br />
<pre><br />
./mirror.pl <projectID> <releaseName> <file><br />
</pre><br />
Metamod:Source's ID is 4, SourceMod's ID is 2. For example, these commands mirrored the Metamod:Source 1.8.7 release:<br />
<pre><br />
./mirror.pl 4 1.8.7 mmsource-1.8.7-linux.zip<br />
./mirror.pl 4 1.8.7 mmsource-1.8.7-windows.tar.gz<br />
./mirror.pl 4 1.8.7 mmsource-1.8.7-mac.tar.gz<br />
</pre><br />
These commands mirrored the SourceMod 1.4.0 release:<br />
<pre><br />
./mirror.pl 2 1.4.0 sourcemod-1.4.0-linux.tar.gz<br />
./mirror.pl 2 1.4.0 sourcemod-1.4.0-windows.zip<br />
./mirror.pl 2 1.4.0 sourcemod-1.4.0-mac.zip<br />
</pre><br />
</li><br />
<li>Type <tt>exit</tt> to get back to your user account. You're done!</li><br />
</ol><br />
<br />
=Cleaning up the Tree=<br />
It's time to make sure the tree is set for future development.<br />
<br />
<ol><br />
<li>Run <tt>hg tag</tt> on the last revision of the release. Usually this is the changeset that bumped versions, and usually this is <tt>tip</tt>. For example, Metamod:Source:<br />
<pre>hg tag mmsource-1.7.2</pre><br />
SourceMod:<br />
<pre>hg tag sourcemod-1.1.2</pre><br />
</li><br />
<li>Bump the minor version in <tt>product.version</tt>. Don't forget to add -dev.</li><br />
<li>Change the <tt>tools/buildbot/build_type</tt> (SourceMod) or <tt>support/buildbot/build_type</tt> (Metamod:Source) contents back to "dev".</li><br />
<li>For SourceMod, bump the two minor versions in <tt>plugins/include/version.inc</tt> and re-add the -dev tag to the version string.</li><br />
<li>Commit and push.</li><br />
</ol><br />
<br />
=Updating the SourceMod Site=<br />
<ol><br />
<li>Visit a [http://wiki.alliedmods.net/SourceMod_Release_Notes Release Notes] page. Copy the contents, make a new one for your specific release. Update the changelog, relnote anything big and important. Link back to it from the "main" relnotes page.</li><br />
<li>Jump to the sourcemod account by logging into iroh as yourself:<br />
<pre><br />
/scripts/amjump sourcemod<br />
cd /groups/sourcemod<br />
</pre><br />
</li><br />
<li>Edit the <tt>public_html/downloads.php</tt> file with your favorite text editor. Edit all instances of the old version with the new one. Make sure to get every link, including relnotes.</li><br />
<li>Update ~/compiler-1.x to the latest minor version, where x is the major version number.</li><br />
<li>Run <tt>~/scripts/purge_old_builds.pl</tt>, then edit its entry for 1.x.y, where x = this major release, and y = the new minor version.</li><br />
<li>Exit out of the sourcemod account.</li><br />
<li>Post news. If you deviate from normal style, don't forget links for downloads, upgrading, and relnotes. It also helps to say "this is backwards compatible" because users will always ask.</li><br />
</ol><br />
<br />
=Updating the Metamod:Source Site=<br />
<ol><br />
<li>Jump to the alliedmodders account by logging into iroh as yourself:<br />
<pre><br />
/scripts/amjump alliedmodders<br />
cd /groups/alliedmodders/hub/amhub<br />
</pre><br />
</li><br />
<li>Edit the <tt>mmsource.py</tt> file with your favorite text editor. Update the <tt>latest</tt> version number in the <tt>downloads</tt> function. If this is a new major release (1.X.0), update the <tt>stable</tt> and <tt>devel</tt> version numbers in the <tt>downloads</tt> and <tt>snapshots</tt> functions.</li><br />
<li>Edit the <tt>templates/mmsource/downloads.html</tt> file and update all Mercurial links with the tagged changeset ID for this release.</li><br />
<li>Edit the <tt>templates/mmsource/navbar.html</tt> file and replace all instances of the old version with the new one.<br />
<li>Run the following command:<br />
<pre><br />
touch ../run/apache.wsgi<br />
</pre><br />
</li><br />
<li>Post news. Do this by making a post in [https://forums.alliedmods.net/forumdisplay.php?f=124 this forum], which is private. LOOK AT OLDER POSTS - you need to write valid XHTML!</li><br />
<li>Exit out of the alliedmodders account.</li><br />
</ol><br />
<br />
=Updating Translations=<br />
This section applies to SourceMod major releases. In order to update the translator tool, shell in as the "sourcemod" user. Find the translation folder. Run the following steps:<br />
* cd sourcemod-central<br />
* hg pull -u<br />
* cd ..<br />
* ./sync_lang_files.pl sourcemod-central/translations<br />
<br />
Any languages with a non-green status will not be exported, so a few weeks before a release it is a good idea to post news asking for translators.</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Timers_(SourceMod_Scripting)&diff=7775Timers (SourceMod Scripting)2010-07-15T01:30:54Z<p>Fyren: a year later and yet...</p>
<hr />
<div>Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.<br />
<br />
=Introduction=<br />
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.<br />
<br />
All timer functions are in <tt>plugins/include/timers.inc</tt>. <br />
<br />
=Basic Usage=<br />
==One-Time Timers==<br />
One-time timers are timers that only execute once. An example of a one-time timer might look like:<br />
<br />
<pawn>public OnPluginStart()<br />
{<br />
CreateTimer(5.0, LoadStuff)<br />
}<br />
<br />
public Action:LoadStuff(Handle:timer)<br />
{<br />
PrintToServer("Loading stuff!")<br />
}</pawn><br />
<br />
This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.<br />
<br />
==Repeatable Timers==<br />
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.<br />
<br />
For example, say you want to display a message five times, once every three seconds:<br />
<pawn><br />
DoMessage()<br />
{<br />
CreateTimer(3.0, PrintMsg, _, TIMER_REPEAT)<br />
}<br />
<br />
public Action:PrintMsg(Handle:timer)<br />
{<br />
static NumPrinted = 0<br />
if (NumPrinted++ >= 5)<br />
{<br />
PrintToServer("Warning! This is a message.")<br />
NumPrinted = 0<br />
<br />
return Plugin_Stop<br />
}<br />
<br />
return Plugin_Continue<br />
}</pawn><br />
<br />
Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.<br />
<br />
=Passing Data=<br />
==Simple Values==<br />
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:<br />
<br />
<pawn>#define MAX_PLAYERS 256<br />
<br />
new Handle:WelcomeTimers[MAX_PLAYERS+1]<br />
<br />
public OnClientPutInServer(client)<br />
{<br />
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client)<br />
}<br />
<br />
public OnClientDisconnect(client)<br />
{<br />
if (WelcomeTimers[client] != INVALID_HANDLE)<br />
{<br />
KillTimer(WelcomeTimers[client])<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}<br />
}<br />
<br />
public Action:WelcomePlayer(Handle:timer, any:client)<br />
{<br />
PrintToConsole(client, "Welcome to the server!")<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}</pawn><br />
<br />
==Handles==<br />
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies. <br />
<br />
==Data Packs==<br />
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.<br />
<br />
The above example could be rewritten as:<br />
<pawn>#define MAX_PLAYERS 256<br />
<br />
new Handle:WelcomeTimers[MAX_PLAYERS+1]<br />
<br />
public OnClientPutInServer(client)<br />
{<br />
new Handle:pack<br />
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)<br />
WritePackCell(pack, client)<br />
WritePackString(pack, "Welcome to the server!")<br />
}<br />
<br />
public OnClientDisconnect(client)<br />
{<br />
if (WelcomeTimers[client] != INVALID_HANDLE)<br />
{<br />
KillTimer(WelcomeTimers[client])<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}<br />
}<br />
<br />
public Action:WelcomePlayer(Handle:timer, Handle:pack)<br />
{<br />
decl String:str[128]<br />
new client<br />
<br />
/* Set to the beginning and unpack it */<br />
ResetPack(pack)<br />
client = ReadPackCell(pack)<br />
ReadPackString(pack, str, sizeof(str))<br />
<br />
PrintToConsole(client, "%s", str)<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}</pawn><br />
<br />
=Notes=<br />
==Accuracy==<br />
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:<br />
*If the server is paused (not ticking), timers will not run.<br />
*The server will not always tick at an exact interval. <br />
<br />
For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.<br />
<br />
==Timer Death==<br />
All timers are guaranteed to die either by:<br />
*<tt>CloseHandle()</tt> being called (or on plugin unload);<br />
*<tt>KillTimer()</tt> being called;<br />
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;<br />
*<tt>TriggerTimer()</tt> being called on a one-time timer;<br />
*Execution of a one-time timer finishes.<br />
<br />
When a timer dies, if <tt>TIMER_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.<br />
<br />
==Changing Intervals==<br />
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.<br />
<br />
==AMX Mod X==<br />
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.<br />
<br />
Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.<br />
<br />
=External Links=<br />
*[http://www.sourcemod.net/devlog/?p=130 On Timer Design, Part 3] (SourceMod DevLog)<br />
*[http://www.sourcemod.net/devlog/?p=119 On Timer Design, Part 2] (SourceMod DevLog)<br />
*[http://www.sourcemod.net/devlog/?p=118 On Timer Design, Part 1] (SourceMod DevLog)<br />
<br />
[[Category:SourceMod Scripting]]<br />
<br />
{{LanguageSwitch}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Building_SourceMod&diff=7476Building SourceMod2009-12-24T05:46:18Z<p>Fyren: </p>
<hr />
<div>Compiling SourceMod is not difficult, but requires a number of prerequisites. This article details the requirements and steps to being able to build working SourceMod binaries. These directions may change any time and may be updated as SourceMod's build process improves.<br />
<br />
'''Note:''' You cannot use MingW to build working SourceMod Windows binaries. It is not ABI compatible with Visual C++ which is what Valve uses for the Source engine. You can only use GCC to build Linux binaries.<br />
<br />
=Requirements=<br />
<br />
==Windows==<br />
*Microsoft Visual C++ 2008 (Express or higher) is supported and used for official builds.<br />
*Microsoft Visual C++ 2005 (Express or higher) is unsupported.<br />
*Microsoft Visual C++ 2003 7.1 or higher may not build out-of-box, but can build compatible binaries.<br />
*Microsoft Visual C++ 2003 7.0 or lower '''cannot''' be used.<br />
<br />
If you are installing Visual C++ 2005 Express, it may not come with Microsoft's Platform SDK installed. If this is the case, you must manually install the Platform SDK. You can find directions on how to do this and test your setup [http://www.microsoft.com/express/2005/platformsdk/default.aspx here]. Visual C++ 2008 "streamlines" the Platform SDK installation according to Microsoft.<br />
<br />
==Linux==<br />
For Linux, SourceMod requires the GNU C/C++ Compiler (from GCC):<br />
*Version 4.1 is used for official binaries and is guaranteed to build.<br />
*Versions 3.4 through 4.2 are guaranteed to be binary (ABI) compatible, although SourceMod may not necessarily build out-of-box against them.<br />
*Any GCC version below 3.4 '''cannot''' be used.<br />
<br />
==CPU==<br />
SourceMod is strictly a 32-bit x86 (IA32) product. You should not try to force a compiler to build 64-bit binaries of SourceMod.<br />
<br />
Your CPU and its compiler must support SSE in order to build SourceMod. To build without needing or having a dependency against SSE, please see the [[Compiling SourceMod#Removing SSE|Removing SSE]] section near the bottom.<br />
<br />
Approximate compiling times for SourceMod's Core are roughly:<br />
*Windows, Core 2 Quad E6600: 30 seconds (using /MP)<br />
*Windows, Core 2 Duo E6600: 75 seconds<br />
*Windows, Centrino 1.8GHz: 5 minutes<br />
*Linux, Core 2 Duo E6600: <= 1 minute<br />
*Linux, P3 Dual 500MHz: >= 7 minutes<br />
<br />
<br />
=Setup=<br />
This section describes how to set up your computer for compiling.<br />
<br />
==Getting the Files==<br />
This section describes which files you must obtain and how to obtain them. Do not worry about where to place them yet -- that will be discussed on a per-platform basis. You can download the files anywhere you'd like.<br />
<br />
The recommended method of getting the required files is via [http://subversion.tigris.org/ Subversion]. We have our own [[Subversion Tutorial]] if you prefer that method. Although you do not need both HL2SDK versions (unless you wish to build binaries against both), you do need both Metamod:Source versions. Extensions don't necessarily require Metamod:Source (or even the Source Engine) but its template library is used extensively in SourceMod.<br />
<br />
*SourceMod. For full download options, see the [http://www.sourcemod.net/downloads.php SourceMod Downloads] page. Obviously, you must download the source code and not a binary package.<br />
*HL2SDK Original. As of this writing (Sep 2008) this engine is used for most Source games, except for TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk hl2sdk]<br />
*HL2SDK OrangeBox. As of this writing (Sep 2008) this engine is used TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk-ob hl2sdk-ob]<br />
*HL2SDK Left4Dead. This engine is used for L4D. Repository: [http://hg.alliedmods.net/hl2sdk-l4d hl2sdk-l4d]<br />
*Metamod:Source Source Code. Visit [http://www.metamodsource.net/?go=downloads Metamod:Source downloads]. Right now SourceMod builds against Metamod:Source 1.7.<br />
<br />
'''Note''' that when we refer to "Metamod:Source" in this article, we are referring to its source code tree, not a binary package.<br />
<br />
If you intend to compile the MySQL extension, you must also download MySQL 5.0. You can use any version. For simplicity, here are the versions we use:<br />
*Linux: We use the 5.0.45 binary from the "[http://dev.mysql.com/downloads/mysql/5.0.html#linux Linux (non RPM packages)]" for "Linux (x86)." You can also use [http://dev.mysql.com/get/Downloads/MySQL-5.0/mysql-5.0.45-linux-i686-glibc23.tar.gz/from/pick this direct link] (may not be valid in the future).<br />
*Windows: Due to a MySQL build change we use 5.0.24a which is an older download. The file name was "mysql-5.0.24a-win32.zip," if you can't find it you can use this [http://www.bailopan.net/mysql-5.0.24a-win32.zip direct link] (may not be valid in the future).<br />
<br />
You can remove all folders from the distribution except for the "lib" and "include" folders which comprise the MySQL SDK.<br />
<br />
==Linux==<br />
As of this writing, SourceMod's Makefiles are hardcoded to use a binary called "gcc-4.1" You can override this, for example:<br />
<pre>make CPP=gcc</pre><br />
<br />
Otherwise, you can also just create a symlink:<br />
<pre>sudo ln -s /usr/bin/gcc /usr/bin/gcc-4.1</pre><br />
<br />
Note that you must use <tt>gcc</tt> and not <tt>g++</tt>.<br />
<br />
SourceMod's Makefiles have strict directory organizational rules. You must have a top-level folder. For this document, we'll assume it is called <tt>sourcemod</tt>, though it can be named anything. The layout of <tt>sourcemod</tt> must be:<br />
*<tt>sourcemod</tt>/<br />
**<tt>hl2sdk</tt> - symlink or folder containing the HL2SDK<br />
**<tt>hl2sdk-ob</tt> - symlink or folder containing the HL2SDK for Orange Box/TF<br />
**<tt>mmsource-1.7</tt> - symlink or folder containing any Metamod:Source version 1.7 or higher.<br />
**<tt>sourcemod-central</tt> - folder containing SourceMod's source code tree. This can be named anything, as long as it's a valid SourceMod tree (like [http://hg.alliedmods.net/sourcemod-central sourcemod-central]). You can also use [http://hg.alliedmods.net/sourcemod-1.1 sourcemod-1.1].<br />
**<tt>mysql-5.0</tt> - symlink or folder containing a MySQL 5.0 distribution<br />
<br />
If you are using a 64-bit version of Linux, you may need to install extra packages to be able to compile SourceMod. On Debian-based distros, these are typically:<br />
<pre><br />
#prerequisites<br />
#apt-get install g++-4.1 gcc-4.1 make subversion<br />
#apt-get instal libz libz-dev<br />
#only needed if you want to use the build tool<br />
#apt-get install mono mono-devel<br />
#32-bit support<br />
apt-get install ia32-libs<br />
apt-get install lib32z1 lib32z1-dev<br />
apt-get install libc6-dev-i386 libc6-i386<br />
</pre><br />
<br />
==Windows==<br />
On Windows we don't require a particular directory layout. Instead, environment variables are used. The directions below apply to Windows XP, and are assumed to be similar for other versions of Windows.<br />
*Open the Control Panel (for example, via Start -> Settings).<br />
*Open the System control. If you don't see it, you may need to switch to "Classic view" (either via the left-hand pane or by going to Tools -> Folder Options).<br />
*Click the Advanced tab.<br />
*Click the Environment Variables button.<br />
<br />
You can add your environment variables to either your User settings or your System settings. Create a new variable for each item in the list below. The item names are in <tt>fixed-width font</tt> and their value descriptions follow.<br />
*<tt>MMSOURCE17</tt> - Path to Metamod:Source 1.7+<br />
*<tt>MMSOURCE18</tt> - Path to Metamod:Source 1.8+<br />
*<tt>HL2SDK</tt> - Path to HL2SDK Ep1/Original<br />
*<tt>HL2SDKOB</tt> - Path to HL2SDK Ep2/OrangeBox for mods<br />
*<tt>HL2SDKOBVALVE</tt> - Path to HL2SDK Ep2/OrangeBox for Valve games (TF2 and DoD:S)<br />
*<tt>HL2SDKL4D</tt> - Path to HL2SDK L4D1<br />
*<tt>HL2SDKL4D2</tt> - Path to HL2SDK L4D2<br />
<br />
=Building=<br />
SourceMod has two types of binaries: those with an engine/MM:S dependence, and those without ("normal" binaries). Normal binaries have two modes:<br />
*<tt>Release</tt> - Optimized binary for release.<br />
*<tt>Debug</tt> - Unoptimized binary with debugging checks.<br />
<br />
Engine/MM:S dependent binaries have three build modes, each paired with either Release or Debug, meaning there are six build options total. They are:<br />
*<tt>Original</tt> - Building against MM:S 1.4 API with HL2SDK<br />
*<tt>Episode2</tt> - Building against MM:S 1.6 API with HL2SDK-OB or higher<br />
<br />
==Linux==<br />
For both Normal and Engine/MM:S dependent binaries, the object files and the final binary are placed in a folder called <tt>Release</tt> or <tt>Debug</tt> (in the same level as the Makefile) depending on which building mechanism you chose.<br />
<br />
'''Note:''' Our Makefiles are not set up to detect changes in header files. If you change a header file, you must clean your build.<br />
<br />
===Normal Binaries===<br />
For normal binaries, you can build simply with:<br />
<br />
<pre>make</pre><br />
<br />
You can clean stale object files with:<br />
<pre>make clean</pre><br />
<br />
Or build debug builds with:<br />
<pre>make DEBUG=true</pre><br />
<br />
===Dependent Binaries===<br />
Binaries that have an Engine or MM:S dependency require one extra parameter, <tt>ENGINE</tt>. It must be either <tt>orangebox</tt> or <tt>original</tt>. For example, to build a TF-compatible binary in debug mode:<br />
<br />
<pre>make ENGINE=orangebox DEBUG=true</pre><br />
<br />
Dependent binaries are dropped into one of the following folders:<br />
*Debug.original<br />
*Debug.orangebox<br />
*Release.original<br />
*Release.orangebox<br />
<br />
==Windows==<br />
Windows project files end with <tt>.vcproj</tt> and are found in an <tt>msvc8</tt> folder that resides inside each binary's main source folder. For example, Core is located in <tt>core/msvc8/sourcemod_mm.vcproj</tt>. <br />
<br />
Once the file is opened, you can select which build to use by going to Build -> Configuration Manager. Normal binaries have simply "Debug" and "Release." Dependent binaries have the following builds:<br />
*Debug - Old Metamod<br />
*Debug - Episode 2 <br />
*Release - Old Metamod<br />
*Release - Episode 2 <br />
<br />
'''Note''' that dependent binaries will have plain "Debug" and "Release" builds. These should not be used as they are not configured.<br />
<br />
Once you have selected a configuration, you can compile by going to Build -> Build Solution. The binaries and object files will be written to a folder inside <tt>msvc8</tt> named after the full configuration name. For example, using "Debug - Old Metamod" with the "sdktools" extension will result in the binary: <tt>extensions/sdktools/msvc8/Debug - Old Metamod/sdktools.ext.dll</tt><br />
<br />
'''Note:''' Visual Studio detects changes to header files intelligently. It is usually not necessary to rebuild a solution.<br />
<br />
<br />
=Binary Organization=<br />
Although SourceMod has a somewhat unified building mechanism, each of the binaries has a different purpose. They can be separated into the following classes:<br />
<br />
*Core-Related: Binaries which are required or loaded intrinsically by Core.<br />
*Extensions: Binaries which are loaded via the extension mechanism.<br />
*External: Binaries which are standalone or unrelated to SourceMod's live operation (for example, the compiler).<br />
<br />
This article is only concerned with the first two types. <br />
<br />
==Core-Related Binaries==<br />
Binaries related to Core are spread throughout the source code tree. They are always placed in <tt>sourcemod/bin</tt> for packaging. The projects files related to Core are:<br />
<br />
*<tt>loader</tt> - This is a very small wrapper binary responsible for detecting the MM:S version and game engine, and deciding which SourceMod version to load. The output binary is <tt>sourcemod_mm_i486.so</tt> or <tt>sourcemod_mm.dll</tt>.<br />
*<tt>core</tt> - This is Core itself, and is a dependent binary. It has three outputs:<br />
**Original: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.1.ep1.dll</tt><br />
**Episode 1: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep1.dll</tt> (unsupported, not packaged)<br />
**Episode 2: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep2.dll</tt><br />
*<tt>sourcepawn/jit/x86</tt> - This is the SourcePawn JIT for generating IA32/x86 instructions from <tt>.smx</tt> files. Currently the source code for this is not made available. It is built as <tt>sourcepawn.jit.x86.so</tt>/<tt>sourcepawn.jit.x86.dll</tt>.<br />
<br />
It is technically not necessary to use the loader. It is provided as a convenience so users do not have to perform extra steps while installing SourceMod. However, it is highly recommend that you do use it in order to maintain similarity with the default SourceMod package.<br />
<br />
==Extensions==<br />
Extensions are found in the <tt>extensions</tt> folder of the source tree. SDKTools, Cstrike, and the upcoming TF extension are engine/MM:S dependent (and the rest are generally not).<br />
<br />
Extensions always are named <tt>name.ext.so</tt> or <tt>name.ext.dll</tt> where <tt>name</tt> is a unique identifier. This is true even of dependent binaries. <br />
<br />
When loading extensions, SourceMod looks in two separate folders. First, it checks the ''dependent extension folder'', which is <tt>extensions/auto.x.y</tt> where <tt>x</tt> is the MM:S version (1 for 1.4, 2 for 1.6) and <tt>y</tt> is the Engine version (1 for Original/Ep1, 2 for Ep2/OrangeBox). If no matching extension is found there, it looks in <tt>extensions</tt>.<br />
<br />
For example, the SDKTools binary on Counter-Strike would be loaded from <tt>extensions/auto.1.ep1</tt>, but the GeoIP binary (which is not dependent) would be loaded from <tt>extensions</tt>.<br />
<br />
<br />
=Removing SSE=<br />
SourceMod binaries are built against SSE by default. SSE is an important set of optimizations, that, according to Valve's hardware survey, are supported on 99.6% percent of respondents' computers. If you are in this 0.4% which does not have SSE support, you should consider buying a newer processor. Only early Pentium 3-grade processors did not have SSE support (for example, the very early Durons), and it is likely your Source server will not perform adequately to support more than few players.<br />
<br />
Nonetheless, SourceMod's binaries can all be recompiled to remove its SSE dependence.<br />
<br />
==Linux==<br />
Edit the Makefile of the binary you are trying to compile. Remove all instances of these flags. They can simply be erased, there is no need to replace them with anything.<br />
*<tt>-msse</tt><br />
*<tt>-mfpmath=sse</tt><br />
<br />
Make sure to clean the build after changing the Makefile.<br />
<br />
==Windows==<br />
Load the project file into Visual Studio. Go to Project -> Properties. Expand "Configuration Properties," and then "C/C++" under it. Select "Code Generation." Change the setting "Enable Enhanced Instruction Set" to "Not Set."<br />
<br />
'''Note:''' You must change this setting '''for each build configuration''' that you wish to use.<br />
<br />
<br />
[[Category:SourceMod Documentation]]<br />
[[Category:SourceMod Development]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Upgrading_SourceMod&diff=7394Upgrading SourceMod2009-08-28T10:31:41Z<p>Fyren: </p>
<hr />
<div>When upgrading SourceMod, backwards compatibility is guaranteed except in rare cases. To completely upgrade, you should:<br />
<br />
*If you are upgrading to a stable release (not a nightly build), check its release notes for any specific instructions.<br />
*Upgrade all <tt>.so</tt>/<tt>.dll</tt> binaries in the following folders:<br />
**<tt>sourcemod/bin</tt><br />
**<tt>sourcemod/extensions</tt><br />
*Upgrade all of the <tt>.txt</tt> files in the <tt>sourcemod/gamedata</tt> folder.<br />
*Upgrade all of the <tt>.txt</tt> files in the <tt>sourcemod/translations</tt> folder.<br />
*Upgrade all of the default <tt>.smx</tt> binaries in the <tt>sourcemod/plugins</tt> folder.<br />
*Read the release notes to see if there were any configuration files that got new features. If so, you should look and see if you want to tweak those new settings. You may want to use a program such as [http://www.scootersoftware.com/ Beyond Compare] or [http://winmerge.org/ WinMerge].<br />
<br />
<br />
'''Note:''' If a plugin stops working due to a SourceMod upgrade, file a bug report and the development team will assess the situation.<br />
<br />
'''Note:''' It is extremely important to update all <tt>gamedata</tt> files, as those specify how SourceMod interacts with mod-specific properties. <br />
<br />
'''Note:''' As of SourceMod 1.2.2, the "auto" folders for SourceMod extensions are no longer used by default. Third party extensions, however, may still use them.<br />
<br />
'''Note:''' If you update your base SourceMod plugins, you must update your translation files (and vice versa). If you absolutely don't want to update your SourceMod base plugins, you should at least update the <tt>core.phrases.txt</tt> translation file.<br />
<br />
'''Note:''' You only need to update the .inc files if you are a plugin developer. If you do update .inc files, you must update the compiler (spcomp.exe for Windows, spcomp for Linux) as well.<br />
<br />
[[Category:SourceMod Documentation]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=SourceMod_1.2.3_Release_Notes&diff=7393SourceMod 1.2.3 Release Notes2009-08-28T10:15:41Z<p>Fyren: Created page with '__FORCETOC__ SourceMod 1.2.3 is a minor bug-fix update. If you need help upgrading, see Upgrading SourceMod. To see the full 1.2 release notes, [[SourceMod 1.2.0 Release No...'</p>
<hr />
<div>__FORCETOC__<br />
SourceMod 1.2.3 is a minor bug-fix update. If you need help upgrading, see [[Upgrading SourceMod]]. To see the full 1.2 release notes, [[SourceMod 1.2.0 Release Notes|click here]].<br />
<br />
*'''This release DOES NOT have configuration changes.'''<br />
*'''This release DOES NOT break compatibility.'''<br />
<br /><br />
=Compatibility=<br />
This release is fully backwards compatible. It is not, however, forwards compatible. Plugins compiled against SourceMod 1.2 will not run on 1.1 or 1.0. If you encounter any compatibility problems, file a bug.<br />
<br />
=Translations=<br />
SourceMod 1.2 comes with the following languages translated, thanks to [http://www.sourcemod.net/translator/?go=translate&op=status community translators]:<br />
*Brazilian Portuguese<br />
*Chinese Simplified<br />
*Danish<br />
*Dutch<br />
*French<br />
*German<br />
*Hungarian<br />
*Italian<br />
*Japanese<br />
*Latvian<br />
*Norwegian<br />
*Polish<br />
*Romanian<br />
*Russian<br />
*Spanish<br />
*Turkish<br />
<br />
=Changelog=<br />
*Fixed extension name lookup. ({{bz|3975}}).</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=SourceMod_Release_Notes&diff=7392SourceMod Release Notes2009-08-28T10:14:25Z<p>Fyren: +1.2.3</p>
<hr />
<div>[[SourceMod]] Release notes for each release:<br />
<br />
*[[SourceMod 1.2.3 Release Notes]]<br />
*[[SourceMod 1.2.2 Release Notes]]<br />
*[[SourceMod 1.2.1 Release Notes]]<br />
*[[SourceMod 1.2.0 Release Notes]]<br />
*[[SourceMod 1.1.2 Release Notes]]<br />
*[[SourceMod 1.1.1 Release Notes]]<br />
*[[SourceMod 1.1.0 Release Notes]]<br />
*[[SourceMod 1.0.4 Release Notes]]<br />
*[[SourceMod 1.0.3 Release Notes]]<br />
*[[SourceMod 1.0.2 Release Notes]]<br />
*[[SourceMod 1.0.1 Release Notes]]<br />
*[[SourceMod 1.0 Release Notes]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Category:Game_Resources&diff=7296Category:Game Resources2009-05-28T11:13:43Z<p>Fyren: </p>
<hr />
<div>In this category you can find resources for specific mods.<br />
<br />
==Left 4 Dead==<br />
[[Left_4_Dead_Events|Events]]<br><br />
[[Left_4_Voting|Voting]]<br><br />
[[Left_4_Dead_Netprops|NetProps]]<br />
<br />
==Team Fortress 2==<br />
[[Team_Fortress_2_Events|Events]]<br><br />
[http://alliedmods.net/~pred/tf2classes.txt Classnames]<br><br />
[http://alliedmods.net/~pred/ctfplayer-vtable-220509.txt CTFPlayer Virtual Functions] - Updated 22/05/09<br><br />
[http://alliedmods.net/~pred/tf-net-220509.txt Entity Properties] - Updated 22/05/09<br><br />
[http://alliedmods.net/~pred/tf-data-220509.txt DataMap Properties] - Updated 22/05/09<br><br />
[[Mod_TempEnt_List_(Source)#Team_Fortress_2|Temp Ents]]<br><br />
<br><br />
[http://alliedmods.net/~pred/CTFKnife%20vtable.txt CTFKnife Virtual Functions]<br><br />
[http://alliedmods.net/~pred/CTFWeaponBase%20Vtable.txt CTFWeaponBase Virtual Functions]<br><br />
[[Achievement IDs]]<br><br />
[[Team_Fortress_2_Weapons|Team Fortress 2 Weapon Entity Names]]<br><br />
<br />
==Counter-Strike: Source==<br />
[[Counter-Strike:_Source_Events|Events]]<br><br />
[http://alliedmods.net/~pred/csclasses.txt Classnames]<br><br />
[[CCSPlayer_offset_list_(SourceMM)|CCSPlayer Virtual Functions]]<br><br />
[[CBaseCombatWeapon_CSS_offset_list_(SourceMM)|CBaseCombatWeapon Virtual Functions]]<br><br />
[http://alliedmods.net/~pred/csdump.txt Entity Properties]<br><br />
[http://alliedmods.net/~pred/csdatamaps.txt DataMap Properties]<br><br />
[[Mod_TempEnt_List_(Source)#Counter-Strike:_Source|Temp Ents]]<br><br />
[[Counter-Strike:_Source_Weapons| Counter-Strike: Source Weapons]]<br><br />
[http://wiki.alliedmods.net/images/Counter-Strike_Source_-_Cvar_List.txt Cvar List]<br></div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Timers_(SourceMod_Scripting)&diff=7295Timers (SourceMod Scripting)2009-05-28T11:11:43Z<p>Fyren: the example is correct as is and won't leak, the edited version will leak</p>
<hr />
<div>Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.<br />
<br />
=Introduction=<br />
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.<br />
<br />
All timer functions are in <tt>plugins/include/timers.inc</tt>. <br />
<br />
=Basic Usage=<br />
==One-Time Timers==<br />
One-time timers are timers that only execute once. An example of a one-time timer might look like:<br />
<br />
<pawn>public OnPluginStart()<br />
{<br />
CreateTimer(5.0, LoadStuff)<br />
}<br />
<br />
public Action:LoadStuff(Handle:timer)<br />
{<br />
PrintToServer("Loading stuff!")<br />
}</pawn><br />
<br />
This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.<br />
<br />
==Repeatable Timers==<br />
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.<br />
<br />
For example, say you want to display a message five times, once every three seconds:<br />
<pawn><br />
DoMessage()<br />
{<br />
CreateTimer(3.0, PrintMsg, _, TIMER_REPEAT)<br />
}<br />
<br />
public Action:PrintMsg(Handle:timer)<br />
{<br />
static NumPrinted = 0<br />
if (NumPrinted++ >= 5)<br />
{<br />
PrintToServer("Warning! This is a message.")<br />
NumPrinted = 0<br />
<br />
return Plugin_Stop<br />
}<br />
<br />
return Plugin_Continue<br />
}</pawn><br />
<br />
Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.<br />
<br />
=Passing Data=<br />
==Simple Values==<br />
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:<br />
<br />
<pawn>#define MAX_PLAYERS 256<br />
<br />
new Handle:WelcomeTimers[MAX_PLAYERS+1]<br />
<br />
public OnClientPutInServer(client)<br />
{<br />
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client)<br />
}<br />
<br />
public OnClientDisconnect(client)<br />
{<br />
if (WelcomeTimers[client] != INVALID_HANDLE)<br />
{<br />
KillTimer(WelcomeTimers[client])<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}<br />
}<br />
<br />
public Action:WelcomePlayer(Handle:timer, any:client)<br />
{<br />
PrintToConsole(client, "Welcome to the server!")<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}</pawn><br />
<br />
==Handles==<br />
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies. <br />
<br />
==Data Packs==<br />
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.<br />
<br />
The above example could be rewritten as:<br />
<pawn>#define MAX_PLAYERS 256<br />
<br />
new Handle:WelcomeTimers[MAX_PLAYERS+1]<br />
<br />
public OnClientPutInServer(client)<br />
{<br />
new Handle:pack<br />
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)<br />
WritePackCell(pack, client)<br />
WritePackString(pack, "Welcome to the server!")<br />
}<br />
<br />
public OnClientDisconnect(client)<br />
{<br />
if (WelcomeTimers[client] != INVALID_HANDLE)<br />
{<br />
KillTimer(WelcomeTimers[client])<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}<br />
}<br />
<br />
public Action:WelcomePlayer(Handle:timer, Handle:pack)<br />
{<br />
decl String:str[128]<br />
new client<br />
<br />
/* Set to the beginning and unpack it */<br />
ResetPack(pack)<br />
client = ReadPackCell(pack)<br />
ReadPackString(pack, str, sizeof(str))<br />
<br />
PrintToConsole(client, "%s", str)<br />
WelcomeTimers[client] = INVALID_HANDLE<br />
}</pawn><br />
<br />
=Notes=<br />
==Accuracy==<br />
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:<br />
*If the server is paused (not ticking), timers will not run.<br />
*The server will not always tick at an exact interval. <br />
<br />
For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.<br />
<br />
==Timer Death==<br />
All timers are guaranteed to die either by:<br />
*<tt>CloseHandle()</tt> being called (or on plugin unload);<br />
*<tt>KillTimer()</tt> being called;<br />
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;<br />
*<tt>TriggerTimer()</tt> being called on a one-time timer;<br />
*Execution of a one-time timer finishes.<br />
<br />
When a timer dies, if <tt>TIMER_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.<br />
<br />
==Changing Intervals==<br />
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.<br />
<br />
==AMX Mod X==<br />
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.<br />
<br />
Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.<br />
<br />
=External Links=<br />
*[http://www.sourcemod.net/devlog/?p=130 On Timer Design, Part 3] (SourceMod DevLog)<br />
*[http://www.sourcemod.net/devlog/?p=119 On Timer Design, Part 2] (SourceMod DevLog)<br />
*[http://www.sourcemod.net/devlog/?p=118 On Timer Design, Part 1] (SourceMod DevLog)<br />
<br />
[[Category:SourceMod Scripting]]<br />
<br />
{{LanguageSwitch}}</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Achievement_IDs&diff=6986Achievement IDs2009-03-05T05:27:40Z<p>Fyren: </p>
<hr />
<div>== Achievement Identification Numbers ==<br />
<br />
VALVe uses :<br />
<br />
'''CTFPlayer::AwardAchievement(int iAchievementID)''' <br />
<br />
in order to award a player an achievement. Each achievement has a specific ID number. The list below is a (hopefully) complete list of ID numbers.<br />
<br />
Format: <ID Number>: <Name><br />
<br />
Special Thanks to '''CShadowRun''' and '''predcrab''' for all their help!<br />
<br />
----<br />
<br />
=== General Achievements ===<br />
<br />
<pre>127: Sentry Gunner<br />
128: Nemesis<br />
129: Hard To Kill<br />
130: Master of Disguise<br />
131: With Friends Like These<br />
132: Dynasty<br />
133: Hardcore<br />
134: Powerhouse Offense<br />
135: Lightning Offense<br />
136: Relentless Offense<br />
137: Impenetrable Defense<br />
138: Impossible Defense<br />
139: Head of the Class<br />
140: World Traveler<br />
141: Team Doctor<br />
142: Flamethrower<br />
145: Grey Matter<br />
</pre><br />
<br />
=== Medic Achievements ===<br />
<pre>1401: First Do No Harm<br />
1402: Quadruple Bypass<br />
1403: Group Health<br />
1404: Surgical Prep<br />
1405: Trauma Queen<br />
1406: Double Blind Trial<br />
1407: Play Doctor<br />
1408: Triage<br />
1409: Preventative Medicine<br />
1410: Consultation<br />
1411: Does It Hurt When I Do This?<br />
1412: Peer Review<br />
1413: Big Pharma<br />
1414: You'll Feel a Little Prick<br />
1415: Autoclave<br />
1416: Blunt Trauma<br />
1417: Medical Breakthrough<br />
1418: Blast Assist<br />
1419: Midwife Crisis<br />
1420: Ubi concordia, ibi victoria<br />
1421: Grand Rounds<br />
1422: Infernal Medicine<br />
1423: Doctor Assisted Homicide<br />
1424: Placebo Effect<br />
1425: Sawbones<br />
1426: Intern<br />
1427: Specialist<br />
1428: Chief of Staff<br />
1429: Hypocritical Oath<br />
1430: Medical Intervention<br />
1431: Second Opinion<br />
1432: Autopsy Report<br />
1433: FYI I am A Medic<br />
1434: Family Practice<br />
1435: House Call<br />
1436: Bedside Manner<br />
1437: Milestone 1<br />
1438: Milestone 2<br />
1439: Milestone 3</pre><br />
<br />
=== Pyro Achievements ===<br />
<pre>1601: Combined Fire<br />
1602: Weenie Roast<br />
1603: Baptism By Fire<br />
1604: Fire and Forget<br />
1605: Firewall<br />
1606: Cooking the Books<br />
1607: Spontaneous Combustion<br />
1608: Trailblazer<br />
1609: Camp Fire<br />
1610: Lumberjack<br />
1611: Clearcutter<br />
1612: Hot on Your Heels<br />
1613: I Fry<br />
1614: Firewatch<br />
1615: Burn Ward<br />
1616: Hot Potato<br />
1617: Makin' Bacon<br />
1618: Plan B<br />
1619: Pyrotechnics<br />
1620: Arsonist<br />
1621: Controlled Burn<br />
1622: Firefighter<br />
1623: Pyromancer<br />
1624: Next of Kindling<br />
1625: OMGWTFBBQ<br />
1626: Second Degree Burn<br />
1627: Got A Light?<br />
1628: BarbeQueQ<br />
1629: Hotshot<br />
1630: Dance Dance Immolation<br />
1631: Dead Heat<br />
1632: Pilot Light<br />
1633: Freezer Burn<br />
1634: Fire Chief<br />
1635: Attention Getter<br />
1637: Milestone 1<br />
1638: Milestone 2<br />
1639: Milestone 3</pre><br />
<br />
===Heavy Achievements===<br />
<pre>1501: Iron Kurtain<br />
1502: Party Loyalty<br />
1503: Division of Labor<br />
1504: Red Oktoberfest<br />
1505: Show Trial<br />
1506: Crime and Punishment<br />
1507: Class Struggle<br />
1508: Soviet Block<br />
1509: Stalin the Kart<br />
1510: Supreme Soviet<br />
1511: Factory Worker<br />
1512: Soviet Union<br />
1513: Own the Means of Production<br />
1514: Krazy Ivan<br />
1515: Rasputin<br />
1516: Icing on the Cake<br />
1517: Crock Block<br />
1518: Kollectivization<br />
1519: Spyalectical Materialism<br />
1520: Permanent Revolution<br />
1521: Heavy Industry<br />
1522: Communist Mani-Fisto<br />
1523: Redistribution of Health<br />
1524: Rationing<br />
1525: Vanguard Party<br />
1527: Pushkin the Kart<br />
1528: Marxman<br />
1529: Gorky Parked<br />
1530: Purge<br />
1531: Lenin A Hand<br />
1532: Five Second Plan<br />
1533: Photostroika<br />
1534: Konspicuous Konsumption<br />
1535: Don't Touch Sandvich<br />
1536: Borscht Belt<br />
1537: Milestone 1<br />
1538: Milestone 2<br />
1539: Milestone 3<br />
</pre><br />
<br />
===Scout Achievements===<br />
<pre>1001: First Blood<br />
1002: First Blood, Part 2<br />
1003: Quick Hook<br />
1004: A Year to Remember<br />
1005: The Cycle<br />
1006: Closer<br />
1007: If You Build it<br />
1008: Gun Down<br />
1009: Butter Up<br />
1010: Doctoring the ball<br />
1011: Dodgers 1, Giants 0<br />
1012: Batting the Doctor<br />
1013: I'm Bat Man<br />
1014: Triple Steal<br />
1015: Pop Fly<br />
1016: Round-Tripper<br />
1017: Artful Dodger<br />
1018: Fall Classic<br />
1019: Strike Zone<br />
1020: Foul Territory<br />
1021: The Big Hurt<br />
1022: Brushback<br />
1023: Moon Shot<br />
1024: Beanball<br />
1025: Retire the Runner<br />
1026: Caught Napping<br />
1027: Side Retired<br />
1028: Triple Play<br />
1029: Stealing Home<br />
1030: Set the Table<br />
1031: Block the Plate<br />
1032: Belittled Beleaguer<br />
1033: No-Hitter<br />
1034: Race for the Pennant<br />
1035: Out of the Park<br />
1036: Milestone 1<br />
1037: Milestone 2<br />
1038: Milestone 3<br />
</pre></div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Metamod:Source&diff=6905Metamod:Source2009-02-15T14:21:41Z<p>Fyren: rv</p>
<hr />
<div>:{{owned_project}}<br />
==Introduction==<br />
Metamod:Source is an API manager and interception handler that sits in between the [[Half-Life_2|Half-Life 2]] Engine (Source) and a subsequent Game Modification (MOD). It can dynamically load "Metamod:Source Plugins", written in C++, to intercept, override, and hook Engine and GameDLL API interfaces. It also allows for inter-plugin communication. As a backend it contains [[SourceHook]], a powerful library for safely manipulating virtual table hooks.<br />
<br />
[[Category:Half-Life 2]]<br />
[[Category:Metamod:Source Documentation]]<br />
<br />
==Where to Download==<br />
Metamod:Source is hosted on [http://sourceforge.net/projects/sourcemm Source Forge] or can be accessed via the [http://www.sourcemm.net/ Metamod:Source Home Page].<br />
<br />
==Naming Conventions==<br />
The name "SourceMM" is no longer used.<br />
<br />
==History==<br />
Metamod:Source is derived from the [[Metamod]] concept of intercepting calls between a game's engine and mod library. While not based on the same code, the API is designed to be similar and familiar to [[Half-Life 1]] programmers.<br />
<br />
====SourceMod Core1====<br />
Initially, the [[SourceMod]] project was started as the next-generation continuation of the [[AMX Mod X]] project. It was designed to be a meta-interface layer for inter-communicating plugins. However, as development continued, it was soon realized that the [[Valve Server Plugin]] interface would not be sufficient to provide proper engine access.<br />
<br />
[[User:PM|Pavol Marko]] (core1 developer) decided to add "SourceHook" to SourceMod core1. It was embedded as a large library for hooking specific virtual table functions. After multiple revisions (see [[SourceHook]] history), it became apparent that 1)SourceHook needed to be game and interface generic, and 2)SourceMod and SourceHook needed to be split into two separate projects. The logic behind this was that SourceHook needed to be a layer above [[Valve Server Plugin]]s, in order to properly manage hooks with the least possibility of conflicts. Furthermore, SourceMod should be a plugin to the SourceHook interface, rather than managing it. This decision can be likened to [[Admin-Mod]]'s early decision to split into the first [[Metamod]] project.<br />
<br />
====SourceHook Finalized====<br />
After four major revisions, [[SourceHook]] was mature enough to be used in a production environment. While [[User:PM|PM]] concentrated on fleshing out [[SourceHook]], [[User:BAILOPAN|BAILOPAN]] and [[User:Damaged Soul|DS]] created the GameDLL wrapper portion.<br />
<br />
====Version 1.0====<br />
On May 6, 2005, Metamod:Source 1.0 was released with SourceHook v4.1 as a backend. GameDLL wrapping was achieved by providing the engine with fake copies of the IServerGame* interfaces. Once the true GameDLL location was known it would be loaded by Metamod:Source. The fake interface then directly wrapped calls to the real GameDLL.<br />
<br />
====Version 1.1====<br />
On October 21, 2005, the first major revision of Metamod:Source was released, featuring SourceHook v4.4, internal event listeners, dropped reliance on STL, and rewritten GameDLL hooking code. The [[Day of Defeat|Day of Defeat:Source]] release by [[VALVe_Software|Valve Software]] revealed that the binary interface between the engine and mod wasn't necessarily public or current, and MM:S's detection was improved for compatibility and speed. Furthermore, Metamod:Source stopped wrapping the GameDLL interfaces and began using SourceHook to hook them.<br />
<br />
====Version 1.2====<br />
On January 7th, 2006, Metamod:Source was updated for SourceHook v4.3, but received no major API changes.<br />
<br />
====Version 1.3====<br />
On August 16th, 2006, Metamod:Source was updated for SourceHook v4.4, minor API changes, bug fixes, and a sync to the latest HL2SDK.<br />
<br />
====Version 1.4====<br />
On April 5th, 2007, Metamod:Source was updated with API for [[Valve Server Plugin]] interface hooking and crash-safe user message enumeration. An experimental gameinfo.txt update tool was also added. No SourceHook changes were made in this release.<br />
<br />
====Version 1.6====<br />
Currently in development, Metamod:Source received a near complete overhaul to abstract engine-specific code to support Orange Box. Additionally, SourceHook received a massive overhaul and is now v5.0, adding global hooks and various major API simplifications. It is the first backwards compatibility break since 1.1.<br />
<br />
==Design Considerations==<br />
====Metamod====<br />
Originally, Metamod:Source was a plugin co-existing with SourceMod. However, there are factories, pointers, and certain capabilities not possible from a [[Valve Server Plugin]]. Furthermore, the [[Half-Life 2]] engine does not properly unload VSPs, making debugging and resource unloading more difficult. Eventually it was decided the added functionality and fine-tuned control outweighed the extra cost of having to configure an intercepting binary.<br />
<br />
====Plugins====<br />
Plugins are specific to Metamod:Source. This means that [[Valve Server Plugin]]s and [[Open_Source_Plugins_for_Metamod:Source|Metamod:Source Plugins]] are entirely separate in the API characteristics. While it is certainly possible to expose the necessary interfaces to VSPs, it creates an added layer of complexity for dealing with things that Metamod:Source might not directly control. For example, when a Metamod:Source plugin is removed at runtime, all of the necessary hooks are also removed. A VSP has no clear callback for detecting this event, therefore it would be more difficult to ensure proper unloading. VSP and MM:S plugins also have different ways of attaching and detaching server [[Cvars|cvars]] and [[Console commands|concmds]].<br />
<br />
By keeping the plugin system isolated, Metamod:Source can also provide a unique set of console commands and API. For example, plugins can listen for certain Metamod:Source-specific events and provide communication channels with other plugins.<br />
<br />
====Hooking====<br />
Metamod:Source is powered by [[SourceHook]], a versatile library for hooking virtual functions. The original [[Half-Life 1]] engine used structs of function pointers which could easily be modified as they passed from one library to another. However, HL2 is comprised almost entirely of pure virtual interfaces. SourceHook was designed for declaring single hooks against a given virtual function and a this pointer, which is not only faster than a blanket hooking system like Metamod's, but more flexible and precise.<br />
<br />
Hooking under Metamod:Source has a number of features that don't exist in a hooking system style like Metamod's, and it achieves something closer to [[Detours|detours]], rather than Metamod, which is hardcoded. For example<br />
*You can change parent parameters during a hooked call<br />
*You can hook member functions, both by a pre-existing declaration or given vtable offset<br />
*You can call the original function and still fire its associated hooks, or you can call it without firing hooks in order to prevent infinite recursion<br />
<br />
==Documentation==<br />
For more information on installing, configuring, and coding for Metamod:Source, see [[:Category:Documentation (SourceMM)|Documentation]].<br />
<br />
==The Future==<br />
While Metamod:Source is a stable/production product, more features are on the horizon. There are distant plans for a [[Detours|detouring]] library and a library for efficiently automated [[Signature Scanning|signature scanning]].<br />
<br />
==License==<br />
Metamod:Source is licensed under the [[zLib/libpng License]]. It is free to use for both open-source and proprietary projects.<br />
<br />
==External Links==<br />
*[http://www.sourcemm.net/ Metamod:Source Website]<br />
*[http://www.metamod.org/ Metamod Website]<br />
*[http://www.sourcemod.net/ SourceMod Website]<br />
*[http://resonus.net/doxygen_sourcemm/ Doxygen of Metamod:Source]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=SourceMod&diff=6904SourceMod2009-02-15T14:19:04Z<p>Fyren: rv</p>
<hr />
<div>:{{owned_project|project=SourceMod|website=www.sourcemod.net}}<br />
=Introduction=<br />
SourceMod is a [[SourceMM|Metamod:Source]] plugin for [[Half-Life 2]]. It provides comprehensive scripting for the Source engine and mods written using the Source SDK. It has features for administration systems, commands, console variables, events, network messages, timed actions, math and string routines, entity modification, and more. It also features a safely versioned, object oriented API usable from "extensions" written in C++. The extension API can be used to add scripting language callbacks and native features.<br />
<br />
SourceMod scripts are written in the SourcePawn language, which is derived from [[Pawn]]. Some of the differences include:<br />
*Passing functions as "objects," instead of by name<br />
*Natively packed and tagged strings<br />
*Dynamic local variables<br />
*A '<tt>decl</tt>' operator for creating uninitialized variables<br />
*A new virtual machine and JIT, both rewritten in C++<br />
*A new file format<br />
<br />
=History=<br />
==Initial Project==<br />
SourceMod was officially announced on October 7th, 2004, as a successor to [[AMX Mod X]] for the Half-Life 1 engine. It was targetted as a complete rewrite of AMX Mod X, with a fundamental changes:<br />
*Use of multiple (pluggable) scripting languages<br />
*JavaScript support<br />
*Unloadability<br />
*An object-oriented module API<br />
<br />
The Source SDK was released on December 1st, 2004. A few weeks later, SourceMod released its source code on December 25th. After this, development began to stagnate. The concept of multiple languages was over-ambitious and improper. The system was largely too complex and too unorganized for developers to understand. Most importantly, the integral calling abstraction layer, designed to let Core talk to plugins without knowing the target scripting layer, was never viable. Because of this and the inherent complexity of MetaEng, scripts were not testable.<br />
<br />
By May of 2005, SourceMod had become completely abandoned. The codebase was scrapped for a rewrite, called "Core 2." This was also quickly abandoned. This timeline and the details therein are explained on the SourceMod [http://www.sourcemod.net/devlog/?p=88 Dev Log]. The remaining members of the SourceMod team went back to AMX Mod X.<br />
<br />
==SourceHook==<br />
By January of 2005, it was apparent that Valve's API would not be sufficient for plugin development in C++. SourceMod and AMX Mod X Developer Pavol "PM OnoTo" Marko started working on an API for safely hooking virtual functions via vtables. <br />
<br />
By March of 2005, it was apparent that this technology would be more useful as a separate project. Thus, SourceHook broke from SourceMod and the [[SourceMM|Metamod:Source]] project was started. Metamod:Source was first released on May 26, 2005.<br />
<br />
==Current Project==<br />
In March of 2006, a public survey was held to determine if the community still wanted SourceMod. Since the response was good, the project was restarted, but in secret, to avoid the same public relations mistakes. From March to September, SourcePawn was written, which included:<br />
*A new JIT, written completely in C++<br />
*A new virtual machine and API, written in C++ with object oriented API<br />
*A new file format<br />
*Various new language features<br />
<br />
During November 2006 to January 2007, SourceMod evolved into a usable scripting platform based on SourcePawn. As of March 16, 2007, it contained enough scripting-level features to be usable, and builds were made available to the public.<br />
<br />
SourceMod remains an ongoing development project which is still in its infancy.<br />
<br />
=Development Team=<br />
*See the [http://www.sourcemod.net/credits.php credits page].<br />
<br />
=Future Plans=<br />
SourceMod will be expanded to have a comprehensive administration plugin set, SQL capatibility, more utility functions, and more Half-Life 2 engine functions.<br />
<br />
=License=<br />
SourceMod is licensed under the [[GNU General Public License]]. The JIT is licensed under its own freeware license.<br />
<br />
=External Links=<br />
*[http://www.sourcemod.net/ SourceMod Website]<br />
*[http://www.metamodsource.net/ Metamod:Source Website]<br />
*[http://www.sourcebans.net/ SourceBans Plugin Website]<br />
*[http://www.n00bsalad.net/sourcemodmirror/ N00bsalad.net Sourcemod Mirror Downloads]<br />
<br />
[[Category:Half-Life_2]]<br />
[[Category:SourceMod]]</div>Fyrenhttps://wiki.alliedmods.net/index.php?title=Installing_SourceMod&diff=6903Installing SourceMod2009-02-15T14:16:09Z<p>Fyren: rv</p>
<hr />
<div>Installing SourceMod is very simple, and it can be added with almost no configuration changes.<br />
<br />
=Prerequisites=<br />
A GUI Web Browser to retrive Metamod and SourceMod compressed archives.<br />
A tool to copy archive to your dedicated server host.<br />
<br />
SourceMod requires [[Metamod:Source]] 1.4.3 or higher. [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM muanually can be found [http://wiki.alliedmods.net/index.php/Installing_Metamod:Source here].<br />
<br />
SourceMod will run on any mod built using the Source SDK. It also supports "The Ship," which uses the Source engine.<br />
<br />
=Uploading/Installing=<br />
==Local Server==<br />
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).<br />
[http://www.sourcemod.net/downloads.php Download Here]<br />
<br />
==Remote Server==<br />
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder. <br />
<br />
Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.<br />
<br />
If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.<br />
<br />
Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:<br />
tar -xzf ../sourcemod-1.1.0.tar.gz<br />
<br />
=Checking the Install=<br />
Your folder layout should look like:<br />
*<tt>[mod]</tt> - Your mod's folder<br />
**<tt>addons</tt><br />
***<tt>metamod</tt> - Metamod:Source<br />
***<tt>sourcemod</tt> - SourceMod<br />
<br />
Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], and most providers will automatically restart your server.<br />
<br />
First, in your [[server console]] (not client console), type:<br />
<pre>meta list</pre><br />
<br />
If the install worked, you will see something like:<br />
<pre>] meta list<br />
Listing 1 plugin:<br />
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre><br />
<br />
You should then be able to use the SourceMod root console command, which can be invoked with simply:<br />
<pre>sm</pre><br />
<br />
For example:<br />
<pre>] sm version<br />
SourceMod Version Information:<br />
SourceMod Version: 1.1.0.2489<br />
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)<br />
SourcePawn API: v1 = 4, v2 = 2<br />
Compiled on: Sep 5 2008 02:02:12<br />
http://www.sourcemod.net/<br />
</pre><br />
<br />
<br />
Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:<br />
<pre>sm_admin</pre><br />
You should see a menu popup with all you options.<br />
<br />
=Troubleshooting=<br />
If the install failed, you will generally see one of four symptoms. <br />
<br />
==Metamod reports NOFILE or FAILED==<br />
If "meta list" replies with something like this:<br />
<pre>] meta list<br />
-Id- Name Version Author Status <br />
[01] - - - NOFILE </pre><br />
<br />
Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):<br />
<pre>meta list 1</pre><br />
<br />
==Metamod lists no plugins==<br />
If "meta list" replies with something like this:<br />
<pre>] meta list<br />
-Id- Name Version Author Status </pre><br />
<br />
You forgot to add SourceMod to the <tt>addons/metamod/metaplugins.ini</tt> file.<br />
Or if that doesn't fix your problem, make sure you are using the correct build of Sourcemod (zip = windows, tar = linux).<br />
<br />
==Metamod says nothing==<br />
If "meta list" has no reply at all, Metamod:Source is not properly installed. [http://wiki.alliedmods.net/index.php/Installing_SourceMM This wiki page] may provide you with clues on how to solve this problem.<br />
<br />
<br />
[[Category:SourceMod Documentation]]</div>Fyren