AlliedModders Wiki - User contributions [en]

Releasing Products

2026-04-11T20:02:24Z

Psychonic: Update for GitHub Actions workflow

== Releasing SourceMod ==

'''''Bold italic''''' values should be replaced as appropriate for the release.
* General
** Create a git branch
** Bump product.version and plugins/include/version.inc numbers for manual builds
* GitHub Actions CI
** CI triggers automatically on pushes to <code>master</code> and branches matching <code>[0-9]+.[0-9]+-dev</code>. No manual build forcing is needed.
** On web01, update <code>version_branches</code> in the webhook app's <code>config.yaml</code> (add <code>"'''''1.13'''''"</code><code>: "'''''1.13-dev'''''"</code> for the new stable branch; update the <code>master</code> entry to the new dev version). Then redeploy: <code>systemctl restart sourcemod-github-artifact-webhook</code>
* Downloads
** Run <code>mount -orw /mnt/downloads</code> on web01
** Run <code>mkdir /mnt/downloads/smdrop/'''''1.11'''''</code>, chmod 775 it, fix ownership
** Run <code>mount -oro /mnt/downloads</code>
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch
** Update <code>~sourcemod/public_html/downloads.php</code> — add new stable/dev version objects and update the <code>stable</code>/<code>dev</code> aliases in <code>$branchMap</code>
** Update <code>~sourcemod/public_html/latest.php</code> — add new version to <code>$versionMap</code> and update the <code>stable</code>/<code>dev</code> aliases (must stay in sync with downloads.php)
* Gamedata updater (run commands from inside <code>~sourcemod/update</code>)
** Clone the new branch into <code>'''''1.11-dev'''''</code>
** Create a <code>'''''update-1.11.sh'''''</code> script for the new version
** Run <code>php add_version.php --version '''''1.11.0''''' --path '''''1.11-dev'''''</code>
** Run <code>php update/add_version.php --version '''''1.12.0''''' --path master</code>
** Run <code>./'''''update-1.11.sh'''''</code>
** Run <code>./update-master.sh</code>
* Web compiler and forum
** Create a <code>~sourcemod/'''''compiler-1.11'''''</code> directory, drop spcomp + includes there
** Change the <code>~sourcemod/compiler</code> symlink to the new version
** 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
** Update <code>~sourcemod/public_html/vbcompiler.php</code>
** Update forum's newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull
* SP docs
** Pull and rebuild <code>~sourcemod/scripts/sourcepawn/exp/tools/docparse</code> if needed
** <code>git checkout</code> new branch into <code>~sourcemod/scripts/sourcemod</code>
** From <code>~sourcemod/scripts/sourcepawn/exp/docgen/generate/</code>, run <code>python generate.py</code>

Metamod

2026-04-05T00:45:04Z

Psychonic: Reverted edits by OilFreak (talk) to last revision by Fidora

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

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

{{Stub}}

Required Versions (SourceMod)

2025-04-06T18:07:33Z

Psychonic: Update pass

As Valve updates their games, new fixes get added to Metamod:Source and SourceMod. This page is to document the current ''minimum'' required version for specific games. If a specific snapshot isn't needed, please put Current Stable or Current Development.

Current Stable MM:S version: '''1.12''' 
Current Stable SM version: '''1.12''' builds

Current Development MM:S versions: '''2.0.0''' git builds 
Current Development SM versions: '''1.13''' builds

Specific Metamod:Source versions and Current Development refer to [http://www.sourcemm.net/snapshots Metamod:Source snapshots]. 
For SourceMod, Current Stable builds refer to [http://www.sourcemod.net/downloads.php?branch=stable Stable builds]. Current Development builds refer to [http://sourcemod.net/downloads.php?branch=master Unstable builds].

{| class="wikitable"
|-
! Game
! Metamod:Source Version
! SourceMod Version
! Extras
|-
| Alien Swarm
| Current Stable
| Current Stable
|-
| Black Mesa Source
| Current Stable
| Current Stable
|-
| Blade Symphony
| Current Stable
| Current Stable
|-
| Bloody Good Time
| Current Stable
| Current Stable
|-
| Contagion
| Current Stable
| Current Stable
|-
| Counter-Strike: Source
| Current Stable
| Current Stable
|-
| Counter-Strike: Global Offensive
| Current Stable
| Current Stable
|-
| Counter-Strike 2
| Current Development
| Unsupported
|-
| Dark Messiah of Might & Magic
| Current Stable
| Current Stable
|-
| Day of Defeat: Source
| Current Stable
| Current Stable
|-
| Deadlock
| Current Development
| Unsupported
|-
| Dota 2
| Current Development
| Unsupported
|-
| EYE: Divine Cybermancy
| Current Stable
| Current Stable
|-
| Half-Life 2: DeatchMatch
| Current Stable
| Current Stable
|-
| Insurgency (2014)
| Current Stable
| Current Stable
|-
| Left 4 Dead
| Current Stable
| Current Stable
| [http://www.sourcemm.net/vdf Manually Generated metamod.vdf] Required
|-
| Left 4 Dead 2
| Current Stable
| Current Stable
|-
| Nuclear Dawn
| Current Stable
| Current Stable
|-
| Source 2006 Mods
| Current Stable
| Current Stable
| Mods: Insurgency: Modern Infantry Combat mod version
|-
| Source 2007 Mods
| Current Stable
| Current Stable
|-
| Source 2013 Mods
| Current Stable
| Current Stable
| Mods: Fistful of Frags, No More Room in Hell
|-
| Team Fortress 2
| Current Stable
| Current Stable
| SourceMod was rebuilt for the 2021/09/16 update
|}

Supported Games (Metamod:Source)

2025-04-06T18:03:02Z

Psychonic: Revert list from supported games for API, to unsupported games. Add ConCommandBase calls

[[Metamod:Source]] generally tries to support most Source engine based games and mods. However, some API features may only be supported by some of them.

=== '''[[Introduction to SourceMM Coding#User_Message_Enumeration|User Message API Functions]]''' - <tt>GetUserMessageCount()</tt>, <tt>FindUserMessage()</tt>, <tt>GetUserMessage()</tt> ===

These APIs are not supported on games that use Protobuf-encoded user messages due to changes in how they are registered. Those games include:
* Blade Symphony
* Counter-Strike: Global Offensive
* Counter-Strike 2
* Deadlock
* Dota 2
* Military Conflict: Vietnam

=== ConCommandBase functions - <tt>RegisterConCommandBase()</tt>, <tt>UnregisterConCommandBase</tt> ===

These functions are deprecated, as there is no concept of ConCommandBase in Source 2. As such, they don't function at all on the below games. Use the ConVar or ConCommand registration / unregistration functions instead.

* Counter-Strike 2
* Deadlock
* Dota 2

[[Category:Metamod:Source Documentation]]

Releasing Products

2024-10-20T16:58:58Z

Psychonic: Add product.version to files needing bumpage

== Releasing SourceMod ==

'''''Bold italic''''' values should be replaced as appropriate for the release.
* General
** Create a git branch
** Bump product.version and plugins/include/version.inc numbers for manual builds
* Buildbot
** Update master.cfg in buildbot buildmaster. Don't forget to push the change to github
** Force builds on the new dev and stable branches via pushbuild.txt
* Downloads
** Run <code>mount -orw /mnt/downloads</code> on web01
** Run <code>mkdir /mnt/downloads/smdrop/'''''1.11'''''</code>, chmod 775 it, fix ownership
** Run <code>mount -oro /mnt/downloads</code>
** Fix sm_commit_log by updating last ~N master builds to be the new stable branch
** Update <code>~sourcemod/public_html/downloads.php</code>
** Add an entry to <code>~sourcemod/web-commit-updater/updater.php</code> for the new version
* Gamedata updater (run commands from inside <code>~sourcemod/update</code>)
** Clone the new branch into <code>'''''1.11-dev'''''</code>
** Create a <code>'''''update-1.11.sh'''''</code> script for the new version
** Run <code>php add_version.php --version '''''1.11.0''''' --path '''''1.11-dev'''''</code>
** Run <code>php update/add_version.php --version '''''1.12.0''''' --path master</code>
** Run <code>./'''''update-1.11.sh'''''</code>
** Run <code>./update-master.sh</code>
* Web compiler and forum
** Create a <code>~sourcemod/'''''compiler-1.11'''''</code> directory, drop spcomp + includes there
** Change the <code>~sourcemod/compiler</code> symlink to the new version
** 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
** Update <code>~sourcemod/public_html/vbcompiler.php</code>
** Update forum's newthread.php and editpost.php (search for ccversion). Do this on staging, create a production PR in bitbucket, then pull
* SP docs
** Pull and rebuild <code>~sourcemod/scripts/sourcepawn/exp/tools/docparse</code> if needed
** <code>git checkout</code> new branch into <code>~sourcemod/scripts/sourcemod</code>
** From <code>~sourcemod/scripts/sourcepawn/exp/docgen/generate/</code>, run <code>python generate.py</code>

Porting to x64

2024-05-09T02:19:32Z

Psychonic: Add Windows x64 gamedata key name and format table

== Overview ==

Many plugins are already compatible with the x64 architecture, but many that manipulate game memory (such as with hooks or patches) will require extensive revisions to run under the new 64-bit servers.
Overall, if your plugin:
* Uses the address natives or the Address type,
* Uses dhooks
* Uses sdkcalls or sdktools (''not sdkhooks'')

...you will need to update your plugin for 64 bits.

Extensions may be good to go with just a recompile for 64-bits, but some may need more extensives changes.

== I'm having an issue! ==

In general, '''prototypes need to be exactly correct''' (including class statics like copy/destruct/constructors) as there are now significantly more quirks that will cause ABIs to be laid out differently.

Here are some things to check for that may be tripping you up:

* The type you thought was an ''int'' was actually a ''size_t''!
* The type you put down as an int or pointer was actually a ''float''!
* Handling pointers as ''int''s when they should be ''void*'' or ''size_t'' (why would you do this??)
* '''The calling convention has changed.''' Make sure to account for this in detours and patches. Make sure your prototypes are exactly correct!
* '''In patches:''' Did you forget the 64-bit opcode prefix when assembling your patch? EAX and RAX are accessed using different opcode prefixes!

=== Linux Calling Convention Quirks ===

Linux uses the System-V x64 ABI. There are many great sources of documentation all over the internet: [https://wiki.osdev.org/System_V_ABI OSDev Wiki] [https://en.wikipedia.org/wiki/X86_calling_conventions#x86-64_calling_conventions Wikipedia]
* All calling conventions are now an up to 8-register fastcall depending on the types (!!)
* RCX can be a thisptr, first argument, or stack return pointer depending on the context
* '''Integer arguments and float arguments are passed in different registers!''' (generic for ints, SIMD registers for floats)
* Varargs are now more complex to call when floats are included in the vararg

The exact value of return types with C++ shenanigans (destructors, etc) still needs to be figured out by someone. However, in general.
* The return argument is always passed in RCX, and will bump the thisptr to RDX (todo: confirm this)
* Some return types that are 128-bits will be returned in both RAX and RDX??

=== MSVC Calling Convention Quirks ===
Microsoft has some excellent official documentation [https://learn.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170 in their MSVC docs].

* All calling conventions are now a four-register fastcall
* RCX can be a thisptr OR the first arg! It is not always a thisptr now. RCX can also be the return value (see below), bumping the thisptr to RDX.
* '''Integer arguments and float arguments are passed in different registers!''' (generic for ints, SIMD registers for floats)
* All objects larger than 8 bytes are now passed exclusively by reference (even on the stack??)
* Float arguments passed to varargs need to be put in both the generic and SIMD register for the appropiate argument index. Varargs are still fastcalls... somehow...
* '''setjmp has new behavior''' and destroys objects as if the scope has been exited. (if you ''are'' using setjmp, good luck)

Return types also have their usual obscure shenanigans. More specifically,
* The return argument is always passed in RCX, and will bump the thisptr to RDX (todo: confirm this)
* Returns with all types larger than 8 bytes occur on the stack
* Returns with any type that has a user-defined base classes, virtual methods, constructor, destructor, or copy operation happens on the stack (''regardless of size'')

== Porting Plugins ==

=== Gamedata ===

All signatures will need to be updated, and likely many offsets.

==== Gamedata key names ====

{| class="wikitable"
|-
! scope="row"| Arch/OS
! scope="col"| Linux
! scope="col"| Windows
|-
! scope="row"| x86
| linux
| windows
|-
! scope="row"| x64
| linux64
| windows64
|}

=== Address Natives ===

New address natives that support 64-bits are still under development

=== DHooks ===

DHooks does not support 64-bits at all for the time being. It will need heavy revisions to work under the new architecture, starting with better SourceHook support for the 64-bit architecture (see: hookmangen)

=== SDKCalls ===

SDKCalls will need to be updated to learn how to accept a thisptr. However, all non-raw calls (eg, those to entities or gamerules that does not require a thisptr) should be fine as long as none of the arguments are 64-bits (including 64-bit ints!)

[[Category:SourceMod Documentation]]

Installing Metamod:Source

2023-09-10T15:43:30Z

Psychonic:

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=

''Not applicable for Source 2. See GameInfo section below''

Valve sometimes makes changes in their games that break Metamod:Source between releases. When this happens, you may need to install a snapshot versions of Metamod:Source. You can see if this is required on the [[Required Versions (SourceMod)|Required Versions]] page.

<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <code>cstrike/addons/metamod</code> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCon). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the sections below.</li>
</ol>

When using a Linux server, you may see the following messages:

* An error indicating that it could not be loaded due to "wrong ELF class: ELFCLASS64". If you are using a 32-bit dedicated server installation, this is normal behavior; as long as <code>meta version</code> is recognized, Metamod:Source is installed.
* An error indicating that it could not be loaded because "/path/to/server_install/bin/libgcc_s.so.1: version `GCC_7.0.0` not found (required by /some_system_path_to/libstdc++.so.6". This is because Valve ships their own copies of those libraries. As modern systems will have newer versions, you can safely delete the listed file from the server install. Do not delete the file in the system path (usually <code>lib</code> or <code>lib32</code>).
* If you are running a 64-bit operating system yourself, you may need to install the system's 32-bit libraries.
** On Debian / Ubuntu, you can do this with <code>apt install gcc-multilib</code>.
* You may find more information about any load failures under a <code>metamod-fatal.log</code> in metamod's <code>bin</code> folder.

==Custom VDF File==
'''Note: This is normally not needed - Metamod:Source 1.10.0 and later include a <code>metamod.vdf</code> file for easier installation on most games.'''

If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <code>addons</code> directory.

Known setups that require this step:
<ol>
<li>Left 4 Dead 1</li>
<li>3rd party mods using the Source SDK Base.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: On Source 1, this is normally not needed - if you do not understand what this is, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers. For Source 2, this is, however, the only supported loading method.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <code>gameinfo</code> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <code>gameinfo</code> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt" (Source 1) or "gameinfo.gi" (Source 2). You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <code>gameinfo</code> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

[[Category:Metamod:Source Documentation]]

Template:Alert

2020-03-27T18:52:31Z

Psychonic: Undo revision 10918 by Psychonic (talk)

Template:Alert

2020-03-27T18:52:11Z

Psychonic: Undo revision 10919 by Psychonic (talk)

Template:Alert

2020-03-27T18:48:47Z

Psychonic:

Template:Alert

2020-03-27T18:47:18Z

Psychonic:

Optimizing Plugins (SourceMod Scripting)

2020-03-26T19:51:58Z

Psychonic: pre -> sourcepawn

==Introduction==
This guide contains some general suggestions as to how to improve local performance in your code. However, '''take note'''. Do not use this as a guide to prematurely optimizing your program. You should focus on making your scripts easily readable and maintainable. Premature optimization can make your code more complex, introducing bugs that you otherwise wouldn't have had.

If you do notice performance problems on your server, and you think they are introduced by your plugin, there are a few steps you can take. The best way to start is to get a profiler. You can use the [[SourceMod Profiler]] to tell you how much time is being spent in script functions.

However, if you are worried about your code, you can also try to estimate the cost of operations in your program. Anything that happens repeatedly in a small period of time - the contents of a loop, the body of a timer, an <tt>OnGameFrame</tt> hook - are good targets.

'''DISCLAIMER:''' The units of time in this article are comparative only. We estimate most SourcePawn operations as costing 1-10 cycles, where a cycle is measured in nanoseconds.

=Estimating Cost=

The goal of estimating cost is to figure out two things:
* How expensive an operation is, run only once.
* How many times the operation is repeated.

Let's try this with a simple example loop below. Most syntactic language features have a simple cost. Natives can be trickier.

<sourcepawn>for (new i = 0; i < strlen(string); i++) {
if (string[i] == '"')
return i;
}
</sourcepawn>

First, let's determine how many times this loop will run. If the length of <tt>string</tt> is ''n'', then the loop will run ''n'' times. Next, let's see what each iteration of the loop costs:
* <tt>strlen(string)</tt>: This has to count all of the characters in |string|. Let's say counting a character costs 1 unit of time. Therefore, |strlen(string)| will cost ''n'' units of time.
* <tt>if (string[i] == '"')</tt>: This contains an array load and comparison. Let's say those each cost 1 unit of time, totaling 2.
* <tt>i++</tt>: This increments a local variable. Let's say that costs 1 unit of time.

Therefore, every iteration of the loop costs <tt>n + 3</tt> units of time.

That means this loop may cost up to <tt>(n * (n + 3))</tt> units of time. Now, if we know that <tt>n</tt> is always small - say, under 100 - that might not be a problem. But what happens if the string has 10,000 characters? Now, the loop will take over 100,000,000 units of time! If a "unit of time" is even as small as a nanosecond, that loop will take a whole tenth of a second, delaying the server by multiple frames!

This example is easy to fix. We can identify that <tt>strlen</tt> magnifies the cost of the loop, and rewrite it like this:
<sourcepawn>new length = strlen(string);
for (new i = 0; i < length; i++) {
if (string[i] == '"')
return i;
}
</sourcepawn>

Now the cost of this loop is just: <tt>n</tt> times a very, very small amount of time.

=Decl on Local Arrays=

Here is another example, using OnGameFrame:
<sourcepawn>public OnGameFrame()
{
new String:buffer[4096];
}</sourcepawn>

When you declare an array with <tt>new</tt>, Pawn initializes each slot to 0. Let's say writing to an array slot costs 1 unit of time. Declaring this array therefore costs a fixed 4096 units of time. Is that a problem? Well, the game server ticks at 33 times per second. Therefore this costs about 150,000 units of time per second. If a "unit of time" is a nanosecond, we could estimate this costing around 0.1 milliseconds. That could be a lot depending on what your plugin does. You get about 15ms per frame, of which about half is used by the server. If you use more than this time, you could start delaying frames.

Let's say that you have declared this big array inside a loop, inside OnGameFrame, and you are worried about the cost. The preferred way of solving this is to use <tt>decl</tt> instead of <tt>new</tt>, which does not perform any initialization:

<sourcepawn>public OnGameFrame()
{
decl String:buffer[4096];
}</sourcepawn>

'''NOTE: You must be very careful not to read from uninitialized variables. They will contain garbage, and you could crash the server by attempting to print or operate on garbage strings.'''

You should only use <tt>decl</tt> on performance-critical arrays. It is never needed anywhere else.

=Avoid Large KeyValues=
KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor.

If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well.

If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2020-03-26T19:49:07Z

Psychonic: pawn -> sourcepawn tag

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<sourcepawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native float My_AddNumbers(int num1, int num2);</sourcepawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<sourcepawn>typedef NativeCall = function int (Handle plugin, int numParams);</sourcepawn>

Thus, we have a function like:
<sourcepawn>public int Native_My_AddNumbers(Handle plugin, int numParams)
{
}</sourcepawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<sourcepawn>public int Native_My_AddNumbers(Handle plugin, int numParams)
{
/* Retrieve the first parameter we receive */
int num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
float num2 = view_as<float>(GetNativeCell(2));
/* Add them together */
float value = num1 + num2;
/* Return the value */
return value;
}</sourcepawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<sourcepawn>public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</sourcepawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<sourcepawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool AltCloseHandle(Handle &hndl);</sourcepawn>

An implementation of this would look like:
<sourcepawn>public int Native_AltCloseHandle(Handle plugin, int numParams)
{
Handle hndl = view_as<Handle>(GetNativeCellRef(1));
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</sourcepawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<sourcepawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native void StringToUpper(char[] str);</sourcepawn>

An implementation of this is very easy, because of dynamic arrays:
<sourcepawn>public int Native_StringToUpper(Handle plugin, int numParams)
{
int len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

char[] str = new char[len + 1];
GetNativeString(1, str, len + 1);

for (int i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</sourcepawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<sourcepawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native int SumArray(const int array[], int size);</sourcepawn>

An implementation of this could look like:
<sourcepawn>public int Native_SumArray(Handle plugin, int numParams)
{
int size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

int array[size], total;
GetNativeArray(1, array, size);

for (int i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</sourcepawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<sourcepawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native int SumParams(int num, ...);</sourcepawn>

An implementation of this would look like:
<sourcepawn>public int Native_SumParams(Handle plugin, int numParams)
{
int base = GetNativeCell(1);
for (int i = 2; i <= numParams; i++)
{
base += GetNativeCellRef(i);
}
return base;
}</sourcepawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<sourcepawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native void DebugPrint(const char[] fmt, any ...);</sourcepawn>

This could be easily implemented as:
<sourcepawn>native int DebugPrint(Handle plugin, int numParams)
{
char buffer[1024];
int written;

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
);

PrintToServer("[DEBUG] %s", buffer);
}</sourcepawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<sourcepawn>public int MyFunction(Handle plugin, int numParams)
{
int client = GetNativeCell(1);
if (client < 1 || client > MaxClients)
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client);
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client);
}
/* Code */
}</sourcepawn>

==Creating Natives for Methodmaps==
Declaring natives for methodmaps is similar to other natives, with a few requirements:

# The <tt>CreateNative</tt> string argument is in the format <tt>Tag.Function</tt>.
# The function is declared as a "member" of the methodmap.
# The magic "this" parameter is implicitly passed in first.

Here's an example of a shared plugin and its corresponding include file:

<sourcepawn>/* sharedplugin.sp */
public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max)
{
CreateNative("Number.PrintToClient", Native_PrintNumberToClient);
return APLRes_Success;
}

public int Native_PrintNumberToClient(Handle plugin, int numParams)
{
int number = GetNativeCell(1);
int client = GetNativeCell(2);

PrintToChat(client, "%d", number);
return;
}

/* sharedplugin.inc */
methodmap Number
{
public Number(int number)
{
return view_as<Number>(number);
}
public native void PrintToClient(int client);
}</sourcepawn>

[[Category:SourceMod Scripting]]

Writing Extensions

2020-03-26T19:44:46Z

Psychonic: pawn -> sourcepawn tag

SourceMod's Extension System is a powerful way to greatly enhance the flexibility of your SourceMod plugins. You can take full advantage of SourceMod's Core, using the interfaces it provides, to create C++ plugins, plugin events, plugin native functions, and shared interfaces. Extensions can also hook into Metamod:Source.

This article goes into the details of creating a SourceMod Extension. Knowledge of C++ is required.

=SDK Structure=
First, download the [[SourceMod SDK]] from the [https://github.com/alliedmodders/sourcemod/releases SourceMod github], and one of the SDKs from the [https://github.com/alliedmodders/hl2sdk hl2sdk github]. The directory structure should contain these folders:
<code>
* hl2sdk-something - One of the HL2 SDKs
* sourcemod-version - The sourcemod package
** extensions - Sourcemod Extensions code
*** curl - Source code to the cURL extension
*** geoip - Source code to the GeoIP extension
*** mysql - Source code to the MySQL extension
** plugins - Source code to all of SourceMod's plugins
*** include - The include files which document plugin API
** public - Interface files for SourceMod's Core Interfaces
*** extensions - Interfaces that are provided by extensions
*** '''sample_ext''' - The Sample Extension SDK
**** extension.cpp - Sample C++ plugin
**** extension.h - Sample C++ header file
**** Makefile - Sample C++ plugin compiler
**** smsdk_config.h - Sample C++ plugin settings
** sourcepawn - The include/interface files for SourcePawn
*** compiler - The SourcePawn Compiler
</code>

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. Navigate to <code>extensions/public/sample_ext</code>, and ensure that you can compile your code. If using the command line, <code>make</code> should do this, if using Visual Studio, see [[#Setting up Visual Studio|Setting up Visual Studio]].

The first step of creating your extension is to configure it. Open the <tt>smsdk_config.h</tt> file and edit each of the following defines. Use the information below to guide you.
<code>
*SMEXT_CONF_NAME - The general name for your Extension (should be short).
*SMEXT_CONF_DESCRIPTION - A short description of what your extension does.
*SMEXT_CONF_VERSION - A version number string. By convention, SourceMod uses the four set build number notation, so build 1.2.3.4 means:
**1 is the "Major" release version.
**2 is the "Minor" release version.
**3 is the "Maintenance" or "Revision" version.
**4 is the "Build," usually an internal source control number.
*SMEXT_CONF_AUTHOR - Your name (or whoever/whatever authored the plugin).
*SMEXT_CONF_URL - The URL/homepage of this extension.
*SMEXT_CONF_LOGTAG - The logtag your extension will use for SourceMod logging. By convention, try to keep this under ten characters or so, and to make it all caps.
*SMEXT_CONF_LICENSE - Right now, the SourceMod Dev Team mandates that 3rd party extensions must be under an Open Source license. Putting a license abbreviation or very short message here is appropriate. For more information, see [https://www.sourcemod.net/license.php the SourceMod license].
*SMEXT_CONF_DATESTRING - You do not need to modify this.
</code>
If your plugin requires using SourceHook or Metamod:Source, uncomment this line:
<code>#define SMEXT_CONF_METAMOD</code>

Next, you should change the name of your extension. By convention, your extension's class name should start with a capital letter.
* First, open <code>extension.h</code> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp>
* Next, open <code>extension.cpp</code> change these two lines:
<cpp>Sample g_Sample;
SMEXT_LINK(&g_Sample);</cpp>

==Visual Studio Users==
Make sure you change the name of your <tt>.dll</tt> file. The naming convention for SourceMod extensions is <tt>name.ext.dll</tt>, where <tt>name</tt> is a short name for your extension. You are free to change this, but it is highly recommended that you keep the <tt>.ext.dll</tt> intact.

You can do this by going to <tt>Project</tt> -> <tt>Properties</tt> -> <tt>Configuration Properties</tt> -> <tt>Linker</tt> -> <tt>General</tt>. Set the <tt>Output File</tt> option appropriately.

==Linux Users==
Simply edit the <tt>Makefile</tt> and change the <tt>BINARY</tt> line near the top. Make sure you do not add any trailing spaces at the end of the name, or the build won't come out right.

You should now be able to compile a blank extension!

=Creating Native Functions=
''Main article: [[Natives (SourceMod Development)]]''

Most of the time, an extension exists to add "native functions" to the plugin system. Native functions are simply the functions that plugins can use in SourceMod. They are coded in C++ and have a short prototype declaration in an include file.

==Prototyping==
The first step to creating a native is to <tt>spec it</tt>, or <tt>prototype</tt> it. This is a simple but often time consuming process, but if you get in the habit of it, your documentation will be much better. Let's first create a very simply native. Here is a prototype for it, which we will place in <tt>sample.inc</tt>:
<sourcepawn>/**
* Returns the square of a number.
*
* @param num Number to square.
* @return The square of num.
*/
native int SquareNumber(num);</sourcepawn>

The <tt>native</tt> keyword tells the compiler that this function exists in an outside source. The comment style is similar to [http://www.stack.nl/~dimitri/doxygen/ doxygen] or [http://java.sun.com/j2se/javadoc/ Javadoc], and is preferred by the SourceMod Development Team.

==Implementing==
Now that our function is documented, it's time to create it! Each native function is bound to a C++ function. The prototype for this function looks like:
<cpp>cell_t Function(IPluginContext *pContext, const cell_t *params);</cpp>

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N. This means <tt>params[0]</tt> contains the number of arguments passed to the native.
**For example, if one parameter was passed, and the parameter is 25:
***<tt>params[0]</tt> == 1
***<tt>params[1]</tt> == 25
**Even though it tells you how many parameters are passed, you do not need to verify this number. The compiler will always pass the correct number of parameters in. The only time you need to verify it is for backwards compatibility or variable parameter lists, which will be discussed later.

Now, let's write our native function:
<cpp>cell_t SquareNumber(IPluginContext *pContext, const cell_t *params)
{
cell_t number = params[1];
return number * number;
}</cpp>

==Binding==
Now, the final step is to bind our native. Natives are bound in ''native lists''. Each list must be terminated by a <tt>NULL</tt> bind. Example:
<cpp>const sp_nativeinfo_t MyNatives[] =
{
{"SquareNumber", SquareNumber},
{NULL, NULL},
};</cpp>

The first column/member is a string containing the name you've assigned to the native. The second column/member is the C++ function you're binding to. Here, both contain the same name, but it is certainly possible to bind a function to any valid Pawn function name, and likewise, you can bind one function to more than one name.

Lastly, you must tell Core about your native list. There are two places that are good to do this. Whichever you choose, you must uncomment the function in <tt>extension.h</tt> and implement it in <tt>extension.cpp</tt>.
*<tt>SDK_OnLoad</tt> - This is called when your extension is first loaded. If you do not require any outside interfaces, it is safe to add natives here.
*<tt>SDK_OnAllLoaded</tt> - This is called when all extensions have been loaded. This is generally a better place to add natives.

Let's say we choose <tt>SDK_OnAllLoaded</tt>, we'd then have code like this:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
}</cpp>
''Note: <tt>myself</tt> is a global variable declared in the SDK. It is a pointer that identifies your extension.''

For more information on writing natives, see [[Natives (SourceMod Development)]].

=Creating Events/Forwards=
Events are an integral part to SourceMod. An Event is formally called a ''Forward''. Forwards are functions inside a plugin which are not called by the plugin itself, but are triggered from an external source. For example, <tt>OnClientConnect</tt> is a forward which is triggered when a player connects to a server.

There are two major types of forwards:
*'''Managed''': This forward is global and has a name. To use this forward, the function must be declared as <tt>public</tt> inside the user's script. Any plugin having this public function will receive the event.
*'''Unmanaged''': This forward is private in nature. For example, the <tt>HookUserMessage</tt> native lets users specify a function to be called when a specific user message is sent. This is done with an unmanaged forward, and adding functions to this forward is not automatic. In general, function calls for unmanaged forwards are not public, although they can be.

''Note: To enable the Forward interface, you must uncomment the definition <tt>SMEXT_ENABLE_FORWARDSYS</tt> in smsdk_config.h.''
==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

As we did before, first let's prototype our global forward. In our include file, we add this:
<sourcepawn>/**
* @brief Called whenever a client says something in chat.
*
* @param client Index of the client.
* @param text String containing the say text.
* @return Plugin_Handled to block text from printing, Plugin_Continue otherwise.
*/
forward Action OnPlayerSayChat(int client, const char[] text);</sourcepawn>

The <tt>forward</tt> keyword tells the compiler that any function having this name must be declared exactly the same. In a plugin, this would

The next step is to declare your forward somewhere at the top of your <tt>extension.cpp</tt> file. This will look like:
<cpp>IForward *g_pSayChat = NULL</cpp>

Next, re-using our code from above, let's create this forward in <tt>SDK_OnAllLoaded</tt>:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
g_pSayChat = forwards->CreateForward("OnPlayerSayChat", ET_Event, 2, NULL, Param_Cell, Param_String);
}</cpp>

Explanation of parameters:
*<tt>"OnPlayerSayChat"</tt> - The name of our forward.
*<tt>ET_Event</tt> - Since forwards can execute multiple functions in multiple scripts, this is one of the ways of specifying what to do with the return value of each function. <tt>ET_Event</tt> means "return the highest value, do not allow stops." A stop refers to <tt>Pl_Stop</tt>, which lets a plugin block the rest of the event chain.
*<tt>2</tt> - This is the number of parameters our forward will have.
*<tt>NULL</tt> - Not used in our example. This lets you pass parameters by array rather than variable arguments.
*<tt>Param_Cell</tt> - The first parameter is a cell (integer).
*<tt>Param_String</tt> - The second parameter is a string.

Now, we write a quick function in our module to call this forward:
<cpp>/** Fires the say chat event in plugins. Returns true to allow the text, false to block. */
bool FireChatEvent(int client, const char *text)
{
if (!g_pSayChat)
{
return true;
}

cell_t result = 0;
g_pSayChat->PushCell(client);
g_pSayChat->PushString(text);
g_pSayChat->Execute(&result);

if (result == Pl_Handled)
{
return false;
}

return true;
}</cpp>

As you can see, this was pretty simple. Each parameter is "pushed" one at a time, in ascending order. First we push the client index as a cell, then the text as a string. Once done, we execute, and the value will be returned by reference.

Lastly, there is a caveat. Unlike natives, SourceMod does not automatically clean up forwards for us when are done. We have to make sure we destroy them. Uncomment <tt>SDK_OnUnload</tt> from <tt>extension.h</tt> and implement it like so:
<cpp>void Sample::SDK_OnUnload()
{
forwards->ReleaseForward(g_pSayChat);
}</cpp>

==Unmanaged Forwards==
Now things get a bit more complicated. However, unmanaged forwards are essentially the same -- they just give you more flexibility. Let's consider the managed example with a new twist. We want to let users add and remove hooks from their plugins, rather than having one global forward. The standard way to do this is with ''function IDs''.

Example prototype:
<sourcepawn>typedef SayChatHook = function Action (int client, const char[] text);

native void AddSayChatHook(SayChatHook hook);
native void RemoveSayChatHook(SayChatHook hook);</sourcepawn>

The <tt>funcenum</tt> syntax lets you define all the valid prototypes for your hook. In this example, the only valid method is a function declared like this (only MyHook can be changed):
<sourcepawn>Action MyHook(int client, const char[] text)</sourcepawn>

How do we make such a beast? The first step is setting up our forward.
<cpp>IChangeableForward *g_pSayChat = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
g_pSayChat = forwards->CreateForwardEx(NULL, ET_Hook, 2, NULL, Param_Cell, Param_String);
}</cpp>

Notice two big differences. We now use <tt>IChangeableForward</tt> instead of <tt>IForward</tt>, and we use <tt>CreateForwardEx</tt> instead. The initial first parameter specifies a name for our forward - we're going to ignore this.

Now, we need to create our natives. These will be fairly simple:
<cpp>cell_t AddSayChatHook(IPluginContext *pContext, const cell_t *params)
{
g_pSayChat->AddFunction(pContext, static_cast<funcid_t>(params[1]));
return 1;
}

cell_t RemoveSayChatHook(IPluginContext *pContext, const cell_t *params)
{
IPluginFunction *pFunction = pContext->GetFunctionById(static_cast<funcid_t>(params[1]));
g_pSayChat->RemoveFunction(pFunction);
return 1;
}</cpp>
''Note: These natives must be added -- that step is removed here and explained earlier.''

You do not need to worry about a plugin unloading - Core will automatically remove the functions for you. Since an <tt>IChangeableForward</tt> is also an <tt>IForward</tt>, the <tt>FireChatEvent</tt> function from earlier does not need to change. We're done!

==Creating Interfaces==
Do you want your extension to share an interface? If so, first you should create an ''interface file''. This file should contain everything your interface needs - this way other authors can easily reference it. Your interface must inherit the <tt>SMInterface</tt> class. It must also declare two global macros that uniquely identify your interface. It must also implement two functions: <tt>GetInterfaceName</tt> and <tt>GetInterfaceVersion</tt>.

The two defines must start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt> respectively. The first must be a string and the second must be an unsigned integer. This integer represents your interface's version number. While you are free to use it however you please, by default it should be linearly increased. If you make breaking changes or change the versioning scheme, you must overload the <tt>IsVersionCompat</tt> function in <tt>SMInterface</tt>.

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

class IMyInterface : public SourceMod::SMInterface
{
public:
virtual const char *GetInterfaceName()
{
return SMINTERFACE_MYINTERFACE_NAME;
}
virtual unsigned int GetInterfaceVersion()
{
return SMINTERFACE_MYINTERFACE_VERSION;
}
public:
/**
* @brief This function does nothing.
*/
virtual void DoNothingAtAll() =0;
};

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

Notice, of course, that our interface is ''pure virtual''. This means it must be implemented in the extension. Assuming you know C++, this should be fairly straight forward, so let's skip right to how to add this interface to the SourceMod shared system:
<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddInterface(myself, &g_MyInterface);
return true;
}</cpp>
''Note: We do this in <tt>SDK_OnLoad()</tT> instead of <tt>SDK_OnAllLoaded()</tt>. Otherwise, an extension might try to search for your interface during <tt>SDK_OnAllLoaded()</tt>, and it might fail depending on the load order.''

That simple? Yup! Now other extensions can use your interface.

=Using Interfaces/Other Extensions=
There are a variety of interfaces that are available, but not loaded by default in the Extension SDK. These interfaces can be retrieved and used in your extension.

==Core Interfaces==
If they are provided by Core, getting them is very simple. Many interfaces can simply be uncommented in <tt>smsdk_config.h</tt> and they will become usable. See the "Available Interfaces" list below for the exposure list.

Otherwise, most of the <tt>.h</tt> interface files in the root of the <tt>public</tt> folder in the SDK are Core interfaces. For example, code to use the IPluginManager interface might look like this:
<cpp>#include <IPluginSys.h>

IPluginManager *g_pPlugins = NULL;

bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
SM_GET_IFACE(PLUGINSYSTEM, g_pPlugins);
return true;
}</cpp>

Where did we get <tt>PLUGINSYSTEM</tt> from? Observe the two lines in <tt>IPluginSys.h</tt>:
<cpp>#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
#define SMINTERFACE_PLUGINSYSTEM_VERSION 1</cpp>

The <tt>SM_GET_IFACE</tt> macro uses the text in between the <tt>SMINTERFACE_</tt> and the <tt>_NAME</tt> characters. It also uses the version for compatibility checking. If it can't find the interface, it automatically prints to the error buffer and returns false.

===Default Interfaces===
There are interfaces which are grabbed by the Extension SDK by default. You do not need to query for them on load, or even check if they are valid or not. They are:
*<tt>IShareSys</tt> - Exposed as <tt>sharesys</tt>, found in <tt>IShareSys.h</tt>
*<tt>HANDLESYSTEM</tt> - Exposed as <tt>handlesys</tt>, found in <tt>IHandleSys.h</tt>
*<tt>SOURCEMOD</tt> - Exposed as <tt>g_pSM</tt>, found in <tt>ISourceMod.h</tt>
*<tt>FORWARDMANAGER</tt> - Exposed as <tt>forwards</tt>, found in <tt>IForwardSys.h</tt>

===Available Interfaces===
*<tt>SMEXT_ENABLE_FORWARDSYS</tt>: <tt>forwards</tt>
*<tt>SMEXT_ENABLE_HANDLESYS</tt>: <tt>handlesys</tt>
*<tt>SMEXT_ENABLE_PLAYERHELPERS</tt>: <tt>playerhelpers</tt>
*<tt>SMEXT_ENABLE_DBMANAGER</tt>: <tt>dbi</tt>
*<tt>SMEXT_ENABLE_GAMECONF</tt>: <tt>gameconfs</tt>
*<tt>SMEXT_ENABLE_MEMUTILS</tt>: <tt>memutils</tt>
*<tt>SMEXT_ENABLE_GAMEHELPERS</tt>: <tt>gamehelpers</tt>
*<tt>SMEXT_ENABLE_TIMERSYS</tt>: <tt>timersys</tt>
*<tt>SMEXT_ENABLE_THREADER</tt>: <tt>threader</tt>

==External Interfaces==
The situation changes if your extension requires ''another extension'', since extensions may load in a completely random order. The first step is to mark the other extension as a dependency. Let's say you want to use the <tt>IThreader.h</tt> interfaces from <tt>threader.ext.dll</tt>. First, we declare it as such:

<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddDependency(myself, "thread.ext", true, true);
return true;
}</cpp>

The two boolean parameters to <tt>AddDependency</tt> mean, respectively: "try to automatically load this extension" and "this extension cannot work without the dependency."

Second, we query for the interface in <tt>SDK_OnAllLoaded</tt>. Since we don't know when <tt>thread.ext</tt> will actually be loaded, we have to wait until everything is definitely loaded.
<cpp>IThreader *g_pThreader = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
SM_GET_LATE_IFACE(THREADER, g_pThreader);
}</cpp>

Third, we need to find a way to fail if this interface was never found. The way to do this is by uncommenting <tt>QueryRunning</tt> from <tt>extension.h</tt> and implementing it:
<cpp>bool Sample::QueryRunning(char *error, size_t err_max)
{
SM_CHECK_IFACE(THREADER, g_pThreader);
return true;
}</cpp>

When SourceMod queries your extension, the macro above will either validate the pointer or return false. If it returns false, SourceMod marks your extension as failed.

==Caveats==
===NULL Interfaces===
There are a few ways that external interfaces can make your code complicated. The first is simple but a common oversight. Don't assume interfaces will be okay. For example, say we want to create a thread once we get the <tt>IThreader</tt> interface. Our code should something like this:

<cpp>void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);

if (QueryRunning(NULL, 0))
{
g_pThreader->MakeThread(/* stuff */);
}
}</cpp>

Note that we ''query ourself'' in order to find if it's safe to continue executing code. We could also have simply checked if <tt>g_pThreader</tt> is <tt>NULL</tt>, but self-querying has a bonus: if your extension continues to do things like hook events or add listeners, you will be preventing your extension from entirely initializing itself while one interface is bad. Always make sure you have sanity checks like this where needed.

===Dynamic Unloading===
The second major caveat is that extensions can be dynamically unloaded. If you specified yourself as having a dependency and that each dependency is required, you will have no problem. Your extension will be unloaded before the interface is removed, and you can clean up memory/hooks in your <tt>SDK_OnUnload()</tt> code. There are two situations where this is a different story.

====Optional Interfaces====
The first situation is if you are not requiring an extension that contains an interface. Now, when the extension unloads, your extension will not be unloaded first. This creates a small problem, as you must clean up without being unloaded. There are two functions you can implement in your extension class to resolve this, both documented in <tt>IExtensionSys.h</tt>:
*<tt>QueryInterfaceDrop</tt> - Allows you to request unloading when a specific interface is unloaded. This is the default behavior for all interfaces. If you want to block this functionality, continue reading.
*<tt>NotifyInterfaceDrop</tt> - This is called when an interface is dropped. If your plugin will not be unloaded, you can use this to clean up any resources on a specific interface being removed.

====Circular Dependencies====
The second situation is a bit more complicated. It is possible for two extensions to have circular dependencies. For example:
*Extension "A" requires extension "B."
*Extension "B" requires extension "A."

If either extension is unloaded, the opposite extension is unloaded normally. The first extension then receives the interface drop callbacks. In this situation, it is essential that the <tt>NotifyInterfaceDrop</tt> function be implemented and used with the circular interface. Otherwise, you risk crashing when your extension unloads (or at the very least, leaking memory). Since the actual drop order is undefined, it means both extensions must implement this function to be safe.

=Automatic Loading=
There are two types of automatic loading: Dynamic and Global. Dynamic loading means your extension is only loaded when a plugin requires it. Global loading means your extension loads no matter what.

==Dynamic Autoloading==
Dynamic loading requires that you create an include file for plugins. Plugins that include your file will automatically load your extension. This requires implementing the <tt>Extension</tt> structure found in <tt>core.inc</tt>. You must expose the structure as <tt>public</tt>, and the name must start with "<tt>__ext_</tt>".

<sourcepawn>/**
* Do not edit below this line!
*/
public Extension:__ext_geoip =
{
name = "GeoIP",
file = "geoip.ext",
#if defined AUTOLOAD_EXTENSIONS
autoload = 1,
#else
autoload = 0,
#endif
#if defined REQUIRE_EXTENSIONS
required = 1,
#else
required = 0,
#endif
};
</sourcepawn>

Explanations:
*name: The name of your module as written in <tt>SMEXT_CONF_NAME</tt>.
*file: The platform-inspecific portion of your extension's file name.
*autoload: Specifies that your module should always dynamically autoload by default. You can tweak this to either never autoload or always autoload (without letting the user toggle).
*required: Specifies whether or not this extension is '''required''' by your plugin. If for some reason your extension fails to load (or is not found), the plugin will also fail to load. This is changeable if you wish to override the default behavior.

You can copy and paste this example, but remember to modify the following portions:
*__ext_geoip: Change the "geoip" portion to your own unique variable name.
*"GeoIP: Change the GeoIP portion to your extension's name. This should match the name you chose as <tt>SMEXT_CONF_NAME</tt>.
*"geoip.ext": Change this to your extension's file name, without the .dll/.so portion.

==Global Autoloading==
To have your extension always autoload, you must create a ''.autoload'' file in the <tt>extensions</tt> folder. For example, to have the <tt>threader.ext.dll</tt> or <tt>threader.ext.so</tt> extensions autoload, you'd create the following file in <tt>extensions</tt>: <tt>threader.autoload</tt>.

A few notes:
*This only works for extensions using the .ext.<platform> convention. SourceMod cuts off the ".autoload" portion of the file, then adds the appropriate extension just as if 'sm exts load' was used.
*The file does not need to contain anything, it simply needs to exist.

=Conventions=

==Designing API/Natives==
*Start interface names with the capital letter 'I'.
*Use a consistent naming convention. SourceMod uses [http://msdn2.microsoft.com/en-us/library/ms229002.aspx Microsoft/Pascal] naming. Avoid Java/Camel casing for both API and natives.
*When exposing interfaces, make sure your exposure defines start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt>

==External Naming==
*Logtags (<tt>SMEXT_CONF_LOGTAG</tt>) should be short names (under 10 characters or so) in all capital letters.
*Your extension file name should never have <tt>_i486</tt> or other unnecessary platform-specific notations in its name.
*Your extension file name should always end in <tt>.ext.so</tt> or <tt>.ext.dll</tt> depending on the platform. The <tt>.ext.</tt> is SourceMod convention.

=Setting up Visual Studio=

{{qnotice|It is recommended that you make a copy of the sample_ext project and modify that rather than create your own project, as it will set up most of this for you}} 

== Sample Project ==

Instead of manually creating a project, you can make a copy of the sample_ext project and modify it.

The sample_ext project assumes that it is located in a subdirectory inside the SourceMod public directory. To change this, modify all references to ..\.. to $(SOURCEMOD15)\public and specify the SOURCEMOD15 variable as mentioned in the Optional Environment variables.

The sample_ext projectuses the following environment variables to locate the various source code parts. To set environment variables:

'''Windows XP''': Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables

'''Windows Vista/7''': Start -> Control Panel -> System -> Advanced system properties -> Advanced -> Environment Variables

=== Environment Variables ===

The environment variables used are:

* '''MMSOURCE17''': Path to MetaMod: Source source code for version 1.7 or newer. Used to compile SourceMod itself.
* '''MMSOURCE18''': Path to MetaMod: Source source code for version 1.8 or newer. Used in SourceMod 1.4 projects.
* '''MMSOURCE19''': Path to MetaMod: Source source code for version 1.9 or newer. Used in SourceMod 1.5 projects.
* '''HL2SDK''': Path to the Episode 1 SDK
* '''HL2SDK-SWARM''': Path to the Alien Swarm SDK
* '''HL2SDK-DARKM''': Path to the Dark Messiah SDK
* '''HL2SDKCSGO''': Path to the Counter-Strike: Global Offensive SDK
* '''HL2SDKCSS''': Path to the Counter-Strike: Source SDK
* '''HL2SDKL4D''': Path to the Left 4 Dead SDK
* '''HL2SDKL4D2''': Path to the Left 4 Dead 2 SDK
* '''HL2SDKOB''': Path to the Orange Box SDK (not Source 2009)
* '''HL2SDKOBVALVE''': Path to the Orange Box Valve / Source 2009 SDK (Half-Life 2: Deathmatch, Day of Defeat: Source, Team Fortress 2)

Optional environment variables:

* '''SOURCEMOD15'': Optional path to SourceMod 1.5 or newer source code

==Manually configuring a project==

===Paths===
'''Visual Studio 2003''': Tools -> Options -> Projects, VC++ Directories

'''Visual Studio 2005''': Tools -> Options -> Projects and Solutions -> VC++ Directories

====Include Paths====
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\core
**sourcemm\core\sourcehook
*HL2SDK:
**game\shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public
**dlls

====Link Paths====
*HL2SDK:
**lib\public for version 2005
**lib-vc7\public for version 2003

===Compiler Options===
Note: These options are set by default in the sample Extension SDK. 
Note: These options should be set for every build (Release/Debug/others).

For VS 2005, goto Project->Properties.

*General
**<tt>Character Set</tt>: '''Use Multi-Byte Character Set'''
*C/C++
**General
***<tt>Detect 64-bit Portability Issues</tt>: '''No'''
**Preprocessor
***<tt>Preprocessor Defines</tt>: Add <tt>_CRT_SECURE_NO_DEPRECATE</tt>, <tt>_CRT_NONSTDC_NO_DEPRECATE</tt>, <tt>SOURCEMOD_BUILD</tt> and <tt>WIN32</tt>
**Code Generation
***<tt>Runtime Library</tt>: Multi-threaded or /MT (for Release), Multi-threaded Debug or /MTd (for Debug)
*Linker
**General
***<tt>Output File</tt>: Change <tt>$(ProjectName)</tt> to <tt>$(ProjectName).ext</tt>, or use your own custom string.
**Input
***<tt>Additional Dependencies</tt>: <tt>tier0.lib tier1.lib vstdlib.lib</tt> (for SourceMM attached extensions only)

[[Category:SourceMod]]
[[Category:SourceMod Development]]

Format Class Functions (SourceMod Scripting)

2020-03-26T13:50:30Z

Psychonic:

=Introduction=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<sourcepawn>char buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</sourcepawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<sourcepawn>const char[] fmt, any ...</sourcepawn>

For example, observe the following two natives:
<sourcepawn>native void Format(char[] buffer, int maxlength, const char[] fmt, any ...);
native void PrintToClient(int client, char[] fmt, any ...);</sourcepawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<sourcepawn>PrintToClient(client, "Your name is: %s", userName);</sourcepawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''u''': Unsigned integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<sourcepawn>float fNum = 5.0;
int iNum = 5;
char[] str = "5";

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</sourcepawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

Example:
<sourcepawn>
PrintToServer("Characters: %c %c", 'a', 65);
PrintToServer("Decimals: %d", 1977);
PrintToServer("Preceding with blanks: %10d", 1977);
PrintToServer("Preceding with zeros: %010d", 1977);
PrintToServer("Some different radices: %d %x %X", 26, 26, 0x1A);
PrintToServer("floats: %f %.2f", 3.1416, 3.1416);
char abc[] = "abcdefg...";
PrintToServer("%s %s", "The alphabet:", abc);
PrintToServer("%s %c", abc[3], abc[3]);
</sourcepawn>

Output:
<pre>
Characters: a A
Decimals: 1977
Preceding with blanks: 1977
Preceding with zeros: 0000001977
Some different radices: 26 1a 1A
floats: 3.141599 3.14
The alphabet: abcdefg...
defg... d
</pre>
For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

=Making your function Format-Class=

Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.
Here's an example:

<sourcepawn>public void formatExample(const char[] myString, any ...)
{
int len = strlen(myString) + 255;
char[] myFormattedString = new char[len];
VFormat(myFormattedString, len, myString, 2);

PrintToServer(myFormattedString);
}</sourcepawn>

Using the parameter "any ...", we can pass data(s) to format our string.
Now, in order to replace the Format Specifiers by our data(s), we use the API "VFormat", which documentation can be found here : [https://sm.alliedmods.net/new-api/].

The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.

The 4th parameter indicate the "any ..." parameter position in your function prototype.

[[Category:SourceMod Scripting]]

Format Class Functions (SourceMod Scripting)

2020-03-26T13:24:31Z

Psychonic:

=Introduction=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>char buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const char[] fmt, any ...</pawn>

For example, observe the following two natives:
<pawn>native void Format(char[] buffer, int maxlength, const char[] fmt, any ...);
native void PrintToClient(int client, char[] fmt, any ...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<sourcepawn>PrintToClient(client, "Your name is: %s", userName);</sourcepawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''u''': Unsigned integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>float fNum = 5.0;
int iNum = 5;
char[] str = "5";

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

Example:
<sourcepawn>
PrintToServer("Characters: %c %c", 'a', 65);
PrintToServer("Decimals: %d", 1977);
PrintToServer("Preceding with blanks: %10d", 1977);
PrintToServer("Preceding with zeros: %010d", 1977);
PrintToServer("Some different radices: %d %x %X", 26, 26, 0x1A);
PrintToServer("floats: %f %.2f", 3.1416, 3.1416);
char abc[] = "abcdefg...";
PrintToServer("%s %s", "The alphabet:", abc);
PrintToServer("%s %c", abc[3], abc[3]);
</sourcepawn>

Output:
<pre>
Characters: a A
Decimals: 1977
Preceding with blanks: 1977
Preceding with zeros: 0000001977
Some different radices: 26 1a 1A
floats: 3.141599 3.14
The alphabet: abcdefg...
defg... d
</pre>
For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

=Making your function Format-Class=

Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.
Here's an example:

<pawn>public void formatExample(const char[] myString, any ...)
{
int len = strlen(myString) + 255;
char[] myFormattedString = new char[len];
VFormat(myFormattedString, len, myString, 2);

PrintToServer(myFormattedString);
}</pawn>

Using the parameter "any ...", we can pass data(s) to format our string.
Now, in order to replace the Format Specifiers by our data(s), we use the API "VFormat", which documentation can be found here : [https://sm.alliedmods.net/new-api/].

The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.

The 4th parameter indicate the "any ..." parameter position in your function prototype.

[[Category:SourceMod Scripting]]

Format Class Functions (SourceMod Scripting)

2020-03-26T13:22:49Z

Psychonic:

=Introduction=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>char buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const char[] fmt, any ...</pawn>

For example, observe the following two natives:
<pawn>native void Format(char[] buffer, int maxlength, const char[] fmt, any ...);
native void PrintToClient(int client, char[] fmt, any ...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<sourcepawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''u''': Unsigned integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>float fNum = 5.0;
int iNum = 5;
char[] str = "5";

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

Example:
<pawn>
PrintToServer("Characters: %c %c", 'a', 65);
PrintToServer("Decimals: %d", 1977);
PrintToServer("Preceding with blanks: %10d", 1977);
PrintToServer("Preceding with zeros: %010d", 1977);
PrintToServer("Some different radices: %d %x %X", 26, 26, 0x1A);
PrintToServer("floats: %f %.2f", 3.1416, 3.1416);
char abc[] = "abcdefg...";
PrintToServer("%s %s", "The alphabet:", abc);
PrintToServer("%s %c", abc[3], abc[3]);
</pawn>

Output:
<pre>
Characters: a A
Decimals: 1977
Preceding with blanks: 1977
Preceding with zeros: 0000001977
Some different radices: 26 1a 1A
floats: 3.141599 3.14
The alphabet: abcdefg...
defg... d
</pre>
For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

=Making your function Format-Class=

Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.
Here's an example:

<pawn>public void formatExample(const char[] myString, any ...)
{
int len = strlen(myString) + 255;
char[] myFormattedString = new char[len];
VFormat(myFormattedString, len, myString, 2);

PrintToServer(myFormattedString);
}</pawn>

Using the parameter "any ...", we can pass data(s) to format our string.
Now, in order to replace the Format Specifiers by our data(s), we use the API "VFormat", which documentation can be found here : [https://sm.alliedmods.net/new-api/].

The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.

The 4th parameter indicate the "any ..." parameter position in your function prototype.

[[Category:SourceMod Scripting]]

AMX Mod X 1.9 API Changes

2018-08-26T22:29:23Z

Psychonic: typo fix

{{alert|info|=</nowiki>"vertical-align: super;">[[File:Ambox_content_soft.svg|35px]]{{ns|2}}{{resize|200%|This version is not yet released. The release notes are not final.}}|opt=full-border}}

{{alert|info|Note:|These are just the API changes from AMX Mod X 1.8.2 to AMX Mod X 1.9. Click here for the full [[AMX Mod X 1.9 Release Notes]].|opt=full-border}}

{{alert|info|Hint:|This page includes hidden examples or API reference that you can toggle with {{tt|{{hidden|id=hint|labelonly=yes}}}}.|opt=full-border}}
{{hidden|id=hint|contentonly=yes|content=🙌 Congratulations for understanding the hint!{{margin|10px|}}}}

== Documentation ==

A large part of the scripting documentation has been improved and an online version with searching capability can be found at https://amxmodx.org/api/.

== Gamedata ==

As stated in the Release Notes, we have now gamedata files to avoid to hard code data related to the game or engine. Such files located in the {{tt|amxmodx/data/gamedata/}} directory.

Gamedata files shipped with AMX Mod X can and will be updated at any time, therefore it is strongly discouraged to edit them manually. 
To make custom gamedata changes, please use the custom folder under the gamedata directory. All files under this directory are parsed (in an undefined order) after the main files are loaded. They will never be overwritten.

The files structure is currently arranged this way:

{{tt|
├─ '''common.games'''
│ ├─ entities.games
│ │ └─ ''$mod''
│ │ ├─ offsets-''$class''.txt
│ │ ├─ ...
│ ├─ gamerules.games
│ │ └─ ''$mod''
│ │ ├─ offsets-''$class''.txt
│ │ ├─ ...
│ ├─ hostages.games
│ │ └─ ''$mod''
│ │ ├─ offsets-''$class''.txt
│ │ ├─ ...
│ ├─ others.games
│ │ └─ ''$mod''
│ │ ├─ offsets-''$class''.txt
│ │ ├─ ...
│ ├─ functions.engine.txt
│ ├─ globalvars.engine.txt
│ └─ {{color|#006699|master.games.txt}}
├─ '''modules.games'''
│ ├─ {{color|#006699|master.games.txt}}
│ └─ game.cstrike.txt
|bgcolor=white}}

The main directories are:
* {{tt|'''common.games'''|bgcolor=white}} contains the shared data.
* {{tt|'''modules.games'''|bgcolor=white}} contains the data per module.

In those directories, you will find:
* {{tt|{{color|#006699|master.games.txt|bgcolor=white}}|bgcolor=white}} which references all the files to be loaded by the core/modules.

Inside {{tt|'''common.games'''|bgcolor=white}} directory:
* {{tt|entities.games|bgcolor=white}}, {{tt|entities.games|bgcolor=white}}, {{tt|entities.games|bgcolor=white}} and {{tt|others.games|bgcolor=white}} directories contains the ''$class'' member's offset per-''$mod''. Related to gamerules object but also player, hostage, item and weapons entities.
* {{tt|functions.engine.txt|bgcolor=white}} contains the symbols/signatures of functions in the engine.
* {{tt|globalvars.engine.txt|bgcolor=white}} contains the symbols/signatures of global variables in the engine.

Inside {{tt|'''modules.games'''|bgcolor=white}} directory:
* {{tt|game.cstrike.txt|bgcolor=white}} contains CS-specific data such as the symbol/signatures of functions and others static datas.

{{alert|info|Note:|More details about the file format can be found in the Quick Guide in [[#Game_Config_Parser]].|opt=full-border}}

== Compiler ==

Along a bunch of fixed issues, there are some improvements/features worth to be noted.

=== Emscripten support ===

The AMX Mod X Compiler can now be compiled with [https://kripken.github.io/emscripten-site/ Emscripten] allowing it to run inside of a web browser.

A good example is [https://spider.limetech.io/ Spider], a web-based, entirely client-side, editor and compiler for [Source]Pawn development (by {{user|59029|asherkin}}).

=== Increased Limits ===

Name/function and input line maximum length (in characters) have been increased.

{| class="wikitable"
! style="padding: 0.4em;" | Description
! style="padding: 0.4em;" | Old value
! style="padding: 0.4em;" | New value
|-
| style="padding: 0.4em;" | Name/Function
| style="padding: 0.4em;" | {{tt|31|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|63|bgcolor=white}}
|-
| style="padding: 0.4em;" | Input Line
| style="padding: 0.4em;" | {{tt|511|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|4095|bgcolor=white}}
|}

=== Magic Globals ===

{| class="wikitable"
! style="padding: 0.4em;" | Global
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|__BINARY_NAME__|bgcolor=white}}
| style="padding: 0.4em;" | Name of the compiled plugin. Example: {{tt|admin.amxx|bgcolor=none}}
|-
| style="padding: 0.4em;" | {{tt|__BINARY_PATH__|bgcolor=white}}
| style="padding: 0.4em;" | Absolute path to the compiled plugin. Example: {{tt|/home/hlds/cstrike/addons/amxmodx/plugins/admin.amxx|bgcolor=none}}
|-
| style="padding: 0.4em;" | {{tt|__LINE__|bgcolor=white}}
| style="padding: 0.4em;" | Current line from the plugin's source code.
|}

Note: Values are populated at compile time.

=== Pragma ===

A new {{tt|<nowiki>#</nowiki>pragma deprecated}} has been added to tell the compiler that this specific {{tt|native|bgcolor=none}}/{{tt|stock|bgcolor=none}} is deprecated. 
This will issue a warning upon the compilation.

{{alert|success|Example:|{{hidden|id=pragma_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=pragma_example|contentonly=yes|content=
<pawn>
#pragma deprecated Some comment here.
native foo();
</pawn>

At compilation:

<pawn>
[...] warning 233: symbol "foo" is marked as deprecated: Some comment here.
</pawn>
}}

=== String Literal Contatenation ===

This basically allows you to concatenate literal strings and stringizing a parameter in macro substitution ''only'' (so possible breakage is very limited).

{| class="wikitable"
! style="padding: 0.4em;" | Description
! style="padding: 0.4em;" | Symbol
|-
| style="padding: 0.4em;" | To concatenate
| style="padding: 0.4em;" | {{tt|+|bgcolor=white}}
|-
| style="padding: 0.4em;" | To Stringize
| style="padding: 0.4em;" | {{tt|<nowiki>#</nowiki>|bgcolor=white}}
|}

{{alert|success|Example:|{{hidden|id=concat_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=concat_example|contentonly=yes|content=
<pawn>
#define PROJECT_AUTHOR "AMX Mod X"
#define PROJECT_COPYRIGHT "Copyright (C) 2017 " + PROJECT_AUTHOR

#define VERSION_MAJOR "1"
#define VERSION_MINOR "9"
#define VERSION_RELEASE "0"
#define VERSION VERSION_MAJOR + "." + VERSION_MINOR + "." + VERSION_RELEASE

#define log(%1) "logging: " + #%1 + "\n"

foo()
{
server_print(log(hello));
}
</pawn>
}}

== Internal Core Changes ==

=== String Buffer ===

The buffer size AMX Mod X uses internally to retrieve strings has been increased from {{tt|3k}} to {{tt|16k}}. 

{{alert|info|Note:|A {{tt|MAX_STRING_LENGTH}} define has been added in {{tt|amxconst.inc}}.|opt=full-border}}
{{alert|info|Note:|By default plugins don't have enough memory available to allocate an array of this size. You probably should not use this define to actually declare a buffer unless you ''absolutely'' have to. Look at {{tt|<nowiki>#pragma dynamic</nowiki>}} to increase a plugins available memory.|opt=full-border}}

== New Core APIs ==

=== Automatic Config File ===

This provides a system for plugins to automatically generate config files with plugin's cvars which get executed on load. 
This is done via the {{tt|AutoExecConfig}} native.

Once all configuration files are executed, {{tt|OnConfigsExecuted}} is called. This forward will always be called, even if your plugin had no configs or if it was loaded late.

{| class="wikitable"
! Native
! Description
|-
| style="padding: 0.4em;" | {{tt|AutoExecConfig|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=AutoExecConfig|header=Specifies that the given config file should be executed after plugin load.|labelpos=left|labelonly=yes}}
{{hidden|id=AutoExecConfig|contentonly=yes|content=
<pawn>
/**
* Specifies that the given config file should be executed after plugin load.
*
* @note OnConfigsExecuted() will not be called until the config file has executed,
* but it will be called if the execution fails.
* @note The name parameter should not contain dots, otherwise file will not be executed.
*
* @param autoCreate If true, and the config file does not exist, such a config
* file will be automatically created and populated with
* information from the plugin's registered cvars.
* @param name Name of the config file, excluding the .cfg extension.
* If empty, <plugin.filename.cfg> is assumed.
* @param folder Folder under plugins/ to use.
*
* @noreturn
*/
native AutoExecConfig(bool:autoCreate = true, const name[] = "", const folder[] = "");
</pawn>
}}
|}

{| class="wikitable"
! Forward
! Description
|-
| style="padding: 0.4em;" | {{tt|OnConfigsExecuted|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=OnConfigsExecuted|header=Called when the map has loaded, and all configs are done executing.|labelpos=left|labelonly=yes}}
{{hidden|id=OnConfigsExecuted|contentonly=yes|content=
<pawn>
/**
* Called when the map has loaded, and all configs are done executing.
* This includes servercfgfile (server.cfg), amxx.cfg, plugin's config, and
* per-map config.
*
* @note This is best place to initialize plugin functions which are based on cvar data.
* @note This will always be called once and only once per map. It will be
* called few seconds after plugin_cfg().
*
* @noreturn
*/
forward OnConfigsExecuted();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|OnAutoConfigsBuffered|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=OnAutoConfigsBuffered|header=Called when the map has loaded, right after {{tt|plugin_cfg}} but any time before {{tt|OnConfigsExecuted}}.|labelpos=left|labelonly=yes}}
{{hidden|id=OnAutoConfigsBuffered|contentonly=yes|content=
<pawn>
/**
* Called when the map has loaded, right after plugin_cfg() but any time
* before OnConfigsExecuted. It's called after amxx.cfg and all
* AutoExecConfig() exec commands have been added to the server command buffer.
*
* @note This will always be called once and only once per map.
*
* @noreturn
*/
forward OnAutoConfigsBuffered();
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=autoexecconfig_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=autoexecconfig_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
register_plugin("Hat", "User", "1.0");

create_cvar("mysqlk_database", "", .description = "MySQL database");
create_cvar("mysqlk_host", "localhost", .description = "MySQL host, use this to configure various^nthings for your server.");

AutoExecConfig();
}
</pawn>

That would export a config file that looks like this:
<c>
// This file was auto-generated by AMX Mod X (v1.9)
// Cvars for plugin "Hat" by "User" (hat.amxx, v1.0)

// MySQL database
// -
// Default: ""
mysqlk_database ""

// MySQL host, use this to configure various
// things for your server.
// -
// Default: "localhost"
mysqlk_host "localhost"
</c>
}}

=== DataPack ===

This offers you a way to dynamically store and move around various types of data.

Datapacks provide a way to store and move around arbitrary amounts (and types) of data in AMX Mox X, available from {{tt|datapack.inc}}. 
Data is packed into a single cell value - the {{tt|DataPack}} handle. This handle can be passed around more easily, can be returned by functions and can simulate advanced concepts like string consummation.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Creating & Disposing}}
|-
| style="padding: 0.4em;" | {{tt|CreateDataPack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CreateDataPack|header=Creates a new datapack.|labelpos=left|content=
<pawn>
/**
* Creates a new datapack.
*
* @return New datapack handle, which must be freed via DestroyDataPack().
*/
native DataPack:CreateDataPack();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|DestroyDataPack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=DestroyDataPack|header=Destroys the datapack and frees its memory.|labelpos=left|content=
<pawn>
/**
* Destroys the datapack and frees its memory.
*
* @param pack Datapack handle
*
* @return True if disposed, false otherwise
*/
native DestroyDataPack(&DataPack:pack);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Resetting}}
|-
| style="padding: 0.4em;" | {{tt|ResetPack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ResetPack|header=Resets the datapack read/write position to the start.|labelpos=left|content=
<pawn>
/**
* Resets the datapack read/write position to the start.
*
* @param pack Datapack handle
* @param clear If true, clears the contained data
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native ResetPack(DataPack:pack, bool:clear = false);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Writing data}}
|-
| style="padding: 0.4em;" | {{tt|WritePackCell|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=WritePackCell|header=Packs a cell value into a datapack.|labelpos=left|content=
<pawn>
/**
* Packs a cell value into a datapack.
*
* @param pack Datapack handle
* @param cell Cell value to pack
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native WritePackCell(DataPack:pack, any:cell);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|WritePackFloat|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=WritePackFloat|header=Packs a float value into a datapack.|labelpos=left|content=
<pawn>
/**
* Packs a float value into a datapack.
*
* @param pack Datapack handle
* @param val Float value to pack
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native WritePackFloat(DataPack:pack, Float:val);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|WritePackString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=WritePackString|header=Packs a string into a datapack.|labelpos=left|content=
<pawn>
/**
* Packs a string into a datapack.
*
* @param pack Datapack handle
* @param str String to pack
*
* @return Length of copied string
* @error If an invalid handle is provided, an error will be thrown.
*/
native WritePackString(DataPack:pack, const str[]);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Reading data}}
|-
| style="padding: 0.4em;" | {{tt|ReadPackCell|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ReadPackCell|header=Reads a cell from a Datapack.|labelpos=left|content=
<pawn>
/**
* Reads a cell from a Datapack.
*
* @param pack Datapack handle
*
* @return Cell value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/
native any:ReadPackCell(DataPack:pack);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|ReadPackFloat|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ReadPackFloat|header=Reads a float from a Datapack.|labelpos=left|content=
<pawn>
/**
* Reads a float from a datapack.
*
* @param pack Datapack handle
*
* @return Float value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/
native Float:ReadPackFloat(DataPack:pack);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|ReadPackString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ReadPackString|header=Reads a string from a Datapack.|labelpos=left|content=
<pawn>
/**
* Reads a string from a Datapack.
*
* @param pack Datapack handle
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of buffer
*
* @return Number of cells written to buffer
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/
native ReadPackString(DataPack:pack, buffer[], maxlen);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Managing position}}
|-
| style="padding: 0.4em;" | {{tt|GetPackPosition|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GetPackPosition|header=Returns the datapack read/write position.|labelpos=left|content=
<pawn>
/**
* Returns the datapack read/write position.
*
* @param pack Datapack handle
*
* @return Position in the datapack, only usable with calls to SetPackPosition
* @error If an invalid handle is provided, an error will be thrown.
*/
native DataPackPos:GetPackPosition(DataPack:pack);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SetPackPosition|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SetPackPosition|header=Sets the datapack read/write position.|labelpos=left|content=
<pawn>
/**
* Sets the datapack read/write position.
*
* @note This should only ever be used with (known to be valid) positions
* returned by GetPackPosition(). It is not possible for plugins to safely
* compute datapack positions.
*
* @param pack Datapack handle
* @param position New position to set
*
* @noreturn
* @error If an invalid handle is provided, or the new position is
* out of datapack bounds, an error will be thrown.
*/
native SetPackPosition(DataPack:pack, DataPackPos:position);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=datapack_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=datapack_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
// Creating
new const DataPack:pack = CreateDataPack();

// Writing
WritePackCell(pack, refCell);
WritePackFloat(pack, refFloat);
WritePackString(pack, refString);

// Reset before reading
ResetPack(pack);
server_print("Datapack is readable: %s", !IsPackEnded(pack) ? "yes" : "no");

// Reading
new cellValue = ReadPackCell(pack);
new Float:floatValue = ReadPackFloat(pack);
new buffer[32];
ReadPackString(pack, buffer, charsmax(buffer));
server_print("cellValue = %d, floatValue = %f, buffer = %s", cellValue, floatValue, buffer)
server_print("Datapack is no more readable: %s", IsPackEnded(pack) ? "yes" : "no");

// Clear all data
ResetPack(pack, .clear = true);
server_print("Datapack is empty: %s", IsPackEnded(pack) ? "yes" : "no");

// Disposing
DestroyDataPack(pack);
}
</pawn>
}}

=== Game Config Parser ===

Now we have gamedata files, we strongly encourage any plugins which hardcode static game datas to use the following API.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Loading & Closing file}}
|-
| style="padding: 0.4em;" | {{tt|LoadGameConfigFile|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=LoadGameConfigFile|header=Loads a game config file.|labelpos=left|content=
<pawn>
/**
* Loads a game config file.
*
* @note The file path must be relative to the 'gamedata' folder under the data folder
* and the extension should be omitted.
*
* @param file File to load
*
* @return A handle to the game config file
*/
native GameConfig:LoadGameConfigFile(const file[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|CloseGameConfigFile|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CloseGameConfigFile|header=Destroys a game config and frees its memory.|labelpos=left|content=
<pawn>
/**
* Destroys a game config and frees its memory.
*
* @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
*
* @param handle Game config handle
*
* @return 1 on success, 0 if an invalid handle was passed in
*/
native CloseGameConfigFile(&GameConfig:handle);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Getting value}}
|-
| style="padding: 0.4em;" | {{tt|GameConfGetOffset|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GameConfGetOffset|header=Returns an offset value.|labelpos=left|content=
<pawn>
/**
*
*
* @param handle Game config handle
* @param key Key to retrieve from the offset section
*
* @return An offset, or -1 on failure
* @error Invalid game config handle
*/
native GameConfGetOffset(GameConfig:handle, const key[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|GameConfGetClassOffset|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GameConfGetClassOffset|header=Returns an offset value given a classname.|labelpos=left|content=
<pawn>
/**
* Returns an offset value given a classname.
*
* @param handle Game config handle
* @param classname Class name to match from the offset section
* @param key Key to retrieve from the offset section
*
* @return An offset, or -1 on failure
* @error Invalid game config handle
*/
native GameConfGetClassOffset(GameConfig:handle, const classname[], const key[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|GameConfGetKeyValue|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GameConfGetKeyValue|header=Gets the value of a key from the "Keys" section.|labelpos=left|content=
<pawn>
/**
* Gets the value of a key from the "Keys" section.
*
* @param handle Game config handle
* @param key Key to retrieve from the Keys section
* @param buffer Destination string buffer
* @param maxlen Maximum length of output string buffer
*
* @return True if key existed, false otherwise
* @error Invalid game config handle
*/
native bool:GameConfGetKeyValue(GameConfig:handle, const key[], buffer[], maxlen);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|GameConfGetAddress|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GameConfGetAddress|header=Finds an address calculation in a GameConfig file.|labelpos=left|content=
<pawn>
/**
* Finds an address calculation in a GameConfig file.
*
* @param handle Game config handle
* @param name Name of the property to find
*
* @return An address calculated on success, otherwise 0 on failure.
* @error Invalid game config handle
*/
native GameConfGetAddress(GameConfig:handle, const name[]);
</pawn>
}}
|}

{{alert|success|Quick guide:|{{hidden|id=gameconfguide|labelonly=yes}}|opt=full-border}}
{{hidden|id=gameconfguide|contentonly=yes|content=

{{color|steelblue|'''Config location'''}}

Any default and new gamedata files must be located in {{tt|/amxmodx/data/gamedata/}} directory. 
You can create your own directories inside as well.

{{color|steelblue|'''Filename format'''}}

The file name must end with {{tt|.txt}} extension, e.g. {{tt|myfile.txt}}

{{color|steelblue|'''Loading a specific file'''}}

The right way to load a file is to provide the filename without {{tt|.txt}} extension. 
E.g. {{tt|LoadGameConfigFile("myfile")}} will try to load {{tt|/data/gamedata/myfile.txt}}.

{{color|steelblue|'''Loading multiple files'''}}

You are able to load several at once via a master file, named {{tt|master.game.txt}}. 
A master file is basically a way to tell the parser to load any files listed inside and nothing else. 
You can also specify whether a file should be loaded depending the mod name (such as {{tt|cstrike}}) or engine (dedicated server: {{tt|engine_ds}} or listen server: {{tt|engine_ls}}). 

For example:

<text>
├─ gamedata
│ └─ myfolder
│ ├─ myfile1.txt
│ ├─ myfile2.txt
│ ├─ myfile3.txt
│ └─ master.game.txt
</text>

{{tt|master.game.txt}}:
<text>
"Game Master" // Must start with this.
{
"myfile1.txt" // No option, will be loaded all the time
{
}

"myfile2.txt" // Will be loaded for both servers
{
"engine" "engine_ds"
"engine" "engine_ls"
}

"myfile3.txt" // Will be loaded only if the mod is Counter-Strike.
{
"game" "cstrike"
}
}
</text>

Then to load, you only need to provide your directory, e.g. {{tt|LoadGameConfigFile("myfolder")}}. 
This will looks at the {{tt|/gamedata/myfolder/master.game.txt}} file and will load the listed files from there.

{{color|darkblue|'''Config file format'''}}

The config file has a specific format as well.
This must to start with:
<text>
"Games"
{

}
</text>

Then, you need to tell on what game the date will be loaded. 
There are different values:
* {{tt|"<game name>"}}, such as {{tt|cstrike}}
* {{tt|"*"}} or {{tt|"#default"}} to match any game
<text>
"Games"
{
"cstrike"
{
// Counter-Strike only
}

"#default"
{
// Any game
// Note you can create multiple game blocks.
}
}
</text>

If you need to create a block which inherit multiple games or engine, you can achieve it with {{tt|<nowiki>#supported</nowiki>}} key.
<text>
"Games"
{
"#default" // Must start with this
{
"#supported"
{
"game" "cstrike"
"game" "czero"

"engine" "engine_ds" // you can specify the engine as well.
}

// Data
}
}
</text>

{{color|darkblue|'''Data Type'''}}

There are 5 different types of datas that you are allowed to store:
* ''Signature'':
: Retrieves an address from either a symbol or bytes. E.g. {{tt|@g_pGameRules}} or {{tt|\xDC\x2A\x2A\x2A\x2A\x2A\xA1\x2A\x2A\x2A\x2A\x56}}
: Symbol must start with {{tt|@}}.
: For use with {{tt|GameConfGetAddress}} native.
* ''Address'':
: Reads a value from a given address (usually from signature reference)
: For use with {{tt|GameConfGetAddress}} native.
* ''Offset'':
: A platform-dependent value (windows, linux or mac)
: For use with {{tt|GameConfGetOffset}} native.
* ''Class Offset'':
: Same as Offset but can be grouped into a classname
: For use with {{tt|GameConfGetClassOffset}} native.
* ''Keyvalue'':
: simple key associated to a value.
: For use with {{tt|GameConfGetKeyValue}} native.
<text>
"Games"
{
"#default"
{
"Signatures"
{
"SV_DropClient"
{
"library" "engine" // This can be either "server" (mod), "engine_ds" (dedicated server) or "engine_ls' (listen server)
"windows" "\x55\x8B\x2A\x81\x2A\x2A\x2A\x2A\x2A\x8B\x2A\x2A\x53\x56\x8D"
"linux" "@SV_DropClient"
"mac" "@SV_DropClient" // Note: A symbol must start always with '@'
}

"g_pGameRules"
{
"library" "server"
"windows" "\x8B\x2A\x2A\x2A\x2A\x2A\x85\x2A\x74\x2A\x8B\x2A\xFF\x2A\x2A\xA1" // StartFrame()
"linux" "@g_pGameRules"
"mac" "@g_pGameRules"
}
}

"Offsets"
{
"something"
{
"windows" "4"
"linux" "2"
"mac" "0"
}
}

"Classes"
{
"CSomething"
{
"Offsets"
{
"windows" "4"
"linux" "2"
"mac" "0"
}
}
}

"Addresses"
{
"GameRulesPointer" // Gets the address of "g_pGameRules", adds 2 bytes on windows and 0 byte on linux/mac.
{
"signature" "g_pGameRules"

"windows"
{
"read" "2"
}

"read" "0"
}

"Something" // Gets the address of "SV_DropClient" and adds 5 bytes, on linux platform only.
{
"linux"
{
signature "SV_DropClient"
"read" "5"
}
}
}

"Keys"
{
"key1" "value1"
"Key2" "value2"
}
}
}
</text>

}}

=== Hasher ===

Supports several new hash types: CRC32, MD5, SHA*, Keccak*.

{{alert|info|Note:|The following API deprecates {{tt|md5}} and {{tt|md5_file}} natives.|opt=full-border}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|hash_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=hash_string|header=Generates a hash value (message digest).|labelpos=left|content=
<pawn>
/**
* Generates a hash value (message digest)
*
* @param string String to be hashed.
* @param type Type of selected hashing algorithm. See Hash_* constants in amxconst.inc file.
* @param output Output string to store hash in.
* @param outputSize The maximum size of the output string to store hash in.
*
* @return Number of written bytes.
*/
native hash_string(const string[], const HashType:type, output[], const outputSize);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|hash_file|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=hash_file|header=Generates a hash value using the contents of a given file.|labelpos=left|content=
<pawn>
/**
* Generates a hash value using the contents of a given file
*
* @param fileName Path of file to be hashed.
* @param type Type of selected hashing algorithm. See Hash_* constants in amxconst.inc file.
* @param output Output string to store hash in.
* @param outputSize The maximum size of the output string to store hash in.
*
* @return Number of written bytes.
* @error If the file couldn't be opened, an error is thrown.
*/
native hash_file(const fileName[], const HashType:type, output[], const outputSize);
</pawn>
}}
|}

The available {{tt|HashType}} constants are:

* {{tt|Hash_Crc32}}
* {{tt|Hash_Md5}}
* {{tt|Hash_Sha1}}
* {{tt|Hash_Sha256}}
* {{tt|Hash_Sha3_224}}
* {{tt|Hash_Sha3_256}}
* {{tt|Hash_Sha3_384}}
* {{tt|Hash_Sha3_512}}
* {{tt|Hash_Keccak_224}}
* {{tt|Hash_Keccak_256}}
* {{tt|Hash_Keccak_384}}
* {{tt|Hash_Keccak_512}}

{{alert|success|Example:|{{hidden|id=hasher_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=hasher_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new hash1[32];
new const message[] = "Hello World!";
new const length = hash_string(message, Hash_Md5, hash1, charsmax(hash1));

server_print("hash1 = %s", hash1);

new hash2[32];
new const fileName[] = "server.cfg";
new const length = hash_file(message, Hash_Md5, hash2, charsmax(hash2));

server_print("hash2 = %s", hash2);
}
</pawn>
}}

=== Stack Structure ===

A stack is a LIFO (last in, first out) dynamic vector of of items.

Stacks provide only two operations:
* Push, adding an item to the top.
* Pop, removing an item from the top, in reverse-push order.

{{alert|info|Note:|An example is available in the {{tt|testsuite}} directory, see [https://github.com/alliedmodders/amxmodx/blob/master/plugins/testsuite/stacktest.sma stacktest.sma].|opt=full-border}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Creating & Destroying}}
|-
| style="padding: 0.4em;" | {{tt|CreateStack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CreateStack|header=Creates a stack structure.|labelpos=left|content=
<pawn>
/**
* Creates a stack structure. A stack is a LIFO (last in, first out) vector of
* of items. It has O(1) insertion and O(1) removal.
*
* @note Stacks provide only two operations: Push (adding an item to the top)
* and Pop (remove an item from the top, in reverse-push order).
* @note The contents of the stack are uniform; i.e. storing a string and then
* retrieving it as an integer is NOT the same as str_to_num()!
* @note The "blocksize" determines how many cells each stack slot has, it can
* not be changed after creation.
*
* @param blocksize The number of cells each entry in the stack can hold
*
* @return New stack Handle, which must be freed via DestroyStack()
* @error If an invalid blocksize is provided an error will be
* thrown.
*/
native Stack:CreateStack(blocksize = 1);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|DestroyStack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=DestroyStack|header=Destroys a stack and frees its memory.|labelpos=left|content=
<pawn>
/**
* Destroys a stack and frees its memory.
*
* @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
*
* @param handle Stack to destroy
*
* @return 1 if the Stack was destroyed, 0 if nothing had to be
* destroyed (invalid handle)
*/
native DestroyStack(&Stack:handle);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Pushing Data}}
|-
| style="padding: 0.4em;" | {{tt|PushStackCell|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PushStackCell|header=Pushes a value onto the end of the stack, adding a new index.|labelpos=left|content=
<pawn>
/**
* Pushes a value onto the end of the stack, adding a new index.
*
* @note This may safely be used even if the stack has a blocksize greater than
* 1.
*
* @param handle Stack handle
* @param value Value to push
*
* @noreturn
* @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/
native PushStackCell(Stack:handle, any:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|PushStackString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PushStackString|header=Pushes a string onto the end of a stack, truncating it if it is too long.|labelpos=left|content=
<pawn>
/**
* Pushes a string onto the end of a stack, truncating it if it is too long.
*
* @param handle Stack handle
* @param value String to push
*
* @noreturn
* @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/
native PushStackString(Stack:handle, const value[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|PushStackArray|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PushStackArray|header=Pushes an array of cells onto the end of a stack.|labelpos=left|content=
<pawn>
/**
* Pushes an array of cells onto the end of a stack. The cells are pushed as a
* block (i.e. the entire array takes up one stack slot), rather than pushing
* each cell individually.
*
* @param handle Stack handle
* @param values Block of values to copy
* @param size If not set, the number of elements copied from the array
* will be equal to the blocksize, if set higher than the
* blocksize, the operation will be truncated,
*
* @noreturn
* @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/
native PushStackArray(Stack:handle, const any:values[], size= -1);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Poping Data}}
|-
| style="padding: 0.4em;" | {{tt|PopStackCell|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PopStackCell|header=Pops a cell value from a stack.|labelpos=left|content=
<pawn>
/**
* Pops a cell value from a stack.
*
* @param handle Stack handle
* @param value Variable to store the value in
* @param block Optionally specify which block to read from (useful if the
* blocksize is > 0)
* @param asChar Optionally read as a byte instead of a cell
*
* @return True on success, false if the stack is empty.
* @error If an invalid handle, invalid block or invalid byte is
* provided, an error will be thrown.
*/
native bool:PopStackCell(Stack:handle, &any:value, block = 0, bool:asChar = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|PopStackString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PopStackString|header=Pops a string value from a stack.|labelpos=left|content=
<pawn>
/**
* Pops a string value from a stack.
*
* @param handle Stack handle
* @param buffer Buffer to copy string to
* @param maxlength Maximum size of the buffer
* @param written Variable to store number of characters copied to
*
* @return True on success, false if the stack is empty
* @error If an invalid handle is provided an error will be thrown.
*/
native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|PopStackArray|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PopStackArray|header=Pops an array of cells from a stack.|labelpos=left|content=
<pawn>
/**
* Pops an array of cells from a stack.
*
* @param handle Stack handle
* @param buffer Array to copy value to
* @param size Size of buffer, if not set (-1) assumes the size is equal to
* the stack blocksize
*
* @return True on success, false if the stack is empty
* @error If an invalid handle is provided an error will be thrown.
*/
native bool:PopStackArray(Stack:handle, any:buffer[], size = -1);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Others}}
|-
| style="padding: 0.4em;" | {{tt|IsStackEmpty|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=IsStackEmpty|header=Returns if a stack is empty.|labelpos=left|content=
<pawn>
/**
* Returns if a stack is empty.
*
* @param handle Stack handle
*
* @return True if empty, false if not empty
* @error If an invalid handle is provided an error will be thrown.
*/
native bool:IsStackEmpty(Stack:handle);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|PopStack|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=PopStack|header=Pops a value off a stack, ignoring it completely.|labelpos=left|content=
<pawn>
/**
* Pops a value off a stack, ignoring it completely.
*
* @param handle Stack handle
*
* @return True if a value was popped, false if stack is empty
* @error If an invalid handle is provided an error will be thrown.
*/
stock PopStack(Stack:handle)
{
new value;
return PopStackCell(handle, value);
}
</pawn>
}}
|}

=== Text Parser INI/SMC ===

Event-based text parser to read data in an unified way. It supports INI and SMC (similar to VTF) formats.

{{alert|info|Note:|An example is available in the {{tt|testsuite}} directory, see [https://github.com/alliedmodders/amxmodx/blob/master/plugins/testsuite/textparse_test.sma textparse.sma].|opt=full-border}}

'''SMC Format'''

{{alert|success|Technical format detail:|{{hidden|id=smc-format|labelonly=yes}}|opt=full-border}}
{{hidden|id=smc-format|contentonly=yes|content=
<text>
/**
* The SMC file format is defined as:
* WHITESPACE: 0x20, \n, \t, \r
* IDENTIFIER: Any ASCII character EXCLUDING ", {, }, ;, //, / *, or WHITESPACE.
* STRING : Any set of symbols enclosed in quotes.
*
* Note: if a STRING does not have quotes, it is parsed as an IDENTIFIER.
*
* Basic syntax is comprised of SECTIONBLOCKs.
* A SECTIONBLOCK defined as:
*
* SECTIONNAME
* {
* OPTION
* }
*
* OPTION can be repeated any number of times inside a SECTIONBLOCK.
* A new line will terminate an OPTION, but there can be more than one OPTION per line.
* OPTION is defined any of:
* "KEY" "VALUE"
* SECTIONBLOCK
*
* SECTIONNAME, KEY, VALUE, and SINGLEKEY are strings
* SECTIONNAME cannot have trailing characters if quoted, but the quotes can be optionally removed.
* If SECTIONNAME is not enclosed in quotes, the entire sectionname string is used (minus surrounding whitespace).
* If KEY is not enclosed in quotes, the key is terminated at first whitespace.
* If VALUE is not properly enclosed in quotes, the entire value string is used (minus surrounding whitespace).
* The VALUE may have inner quotes, but the key string may not.
*
* WHITESPACE should be ignored.
* Comments are text occurring inside the following tokens, and should be stripped
* unless they are inside literal strings:
* ;<TEXT>
* //<TEXT>
* / *<TEXT> * /
*
* Example file below:
* "SomeSection"
* {
* /**
* * Some comment
* */
* "Key" "value"
* }
*/
</text>
}}

{| class="wikitable"
! Native
! Description
|-
| style="padding: 0.4em;" | {{tt|SMC_CreateParser|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_CreateParser|header=Creates a new SMC parser.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_CreateParser|contentonly=yes|content=
<pawn>
/**
* Parser invalid code.
*/
enum SMCParser
{
Invalid_SMCParser = 0
};

/**
* Parse result directive.
*/
enum SMCResult
{
SMCParse_Continue, /* Continue parsing */
SMCParse_Halt, /* Stop parsing here */
SMCParse_HaltFail /* Stop parsing and return failure */
};

/**
* Creates a new SMC parser.
* This is used to set parse hooks.
*
* @return A new handle to an SMC Parse structure.
*/
native SMCParser:SMC_CreateParser();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_DestroyParser|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_DestroyParser|header=Disposes of an SMC parser.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_DestroyParser|contentonly=yes|content=
<pawn>
/**
* Disposes of an SMC parser.
*
* @param handle Handle to an SMC Parse structure.
*
* @return True if disposed, false otherwise.
*/
native SMC_DestroyParser(&SMCParser:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_ParseFile|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_ParseFile|header=Parses a config file.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_ParseFile|contentonly=yes|content=
<pawn>
/**
* Parses a config file.
*
* @param handle A handle to an SMC Parse structure.
* @param file A string containing the file path.
* @param line An optional by reference cell to store the last line number read.
* @param col An optional by reference cell to store the last column number read.
* @param data An optional handle or value to pass through to callback functions
*
* @return An SMCParseError result.
* @error Invalid or corrupt handle.
*/
native SMCError:SMC_ParseFile(SMCParser:handle, const file[], &line = 0, &col = 0, any:data = 0);
</pawn>
<pawn>
/**
* Parse error codes.
*/
enum SMCError
{
SMCError_Okay = 0, /* No error */
SMCError_StreamOpen, /* Stream failed to open */
SMCError_StreamError, /* The stream died... somehow */
SMCError_Custom, /* A custom handler threw an error */
SMCError_InvalidSection1, /* A section was declared without quotes, and had extra tokens */
SMCError_InvalidSection2, /* A section was declared without any header */
SMCError_InvalidSection3, /* A section ending was declared with too many unknown tokens */
SMCError_InvalidSection4, /* A section ending has no matching beginning */
SMCError_InvalidSection5, /* A section beginning has no matching ending */
SMCError_InvalidTokens, /* There were too many unidentifiable strings on one line */
SMCError_TokenOverflow, /* The token buffer overflowed */
SMCError_InvalidProperty1, /* A property was declared outside of any section */
};
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_SetParseStart|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_SetParseStart|header=Sets the SMC_ParseStart function of a parse handle.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_SetParseStart|contentonly=yes|content=
<pawn>
/**
* Sets the SMC_ParseStart function of a parse handle.
*
* @note Below is the prototype of callback:
* -
* Called when parsing is started.
*
* @param handle Handle to an SMC Parse structure.
* @param data Handle or value passed in SMC_ParseFile
*
* @noreturn
*
* public OnParseStart(SMCParser:handle, any:data)
* -
* @param handle Handle to an SMC Parse structure.
* @param func A ParseStart callback.
*
* @noreturn
* @error Invalid or corrupt handle.
*/
native SMC_SetParseStart(SMCParser:handle, const func[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_SetParseEnd|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_SetParseEnd|header=Sets the SMC_ParseEnd function of a parse handle.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_SetParseEnd|contentonly=yes|content=
<pawn>
/**
* Sets the SMC_ParseEnd function of a parse handle.
*
* @note Below is the prototype of callback:
* -
* Called when parsing is halted.
*
* @param handle Handle to an SMC Parse structure.
* @param halted True if abnormally halted, false otherwise.
* @param failed True if parsing failed, false otherwise.
* @param data Handle or value passed in SMC_ParseFile
*
* @noreturn
*
* public OnParseEnd(SMCParser:handle, bool:halted, bool:failed, any:data)
* -
* @param handle Handle to an SMC Parse structure.
* @param func A ParseEnd callback.
*
* @noreturn
* @error Invalid or corrupt handle.
*/
native SMC_SetParseEnd(SMCParser:handle, const func[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_SetReaders|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_SetReaders|header=Sets the three main reader functions.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_SetReaders|contentonly=yes|content=
<pawn>
/**
* Sets the three main reader functions.
*
* @note Enclosing quotes are always stripped.
* @note Below is the prototype of callbacks:
* -
* NewSection:
* Called when the parser finds a new section or sub-section.
*
* @param handle Handle to an SMC Parse structure.
* @param name String containing section name.
* @param data Handle or value passed in SMC_ParseFile
*
* @return An SMCResult action to take.
*
* public SMCResult:OnNewSection(SMCParser:handle, const name[], any:data)
*
* KeyValue:
* Called when the parser finds a new key/value pair.
*
* @param handle Handle to an SMC Parse structure.
* @param key String containing key name.
* @param value String containing value name.
* @param data Handle or value passed in SMC_ParseFile
*
* @return An SMCResult action to take.
*
* public SMCResult:OnKeyValue(SMCParser:handle, const key[], const value[], any:data)
*
* EndSection:
* Called when the parser finds the end of the current section.
*
* @param handle Handle to an SMC Parse structure.
* @param data Handle or value passed in SMC_ParseFile
*
* @return An SMCResult action to take.
*
* public SMCResult:OnEndSection(SMCParser:handle, any:data)
* -
* @param handle Handle to an SMC Parse structure.
* @param kv A KeyValue callback.
* @param ns An optional NewSection callback.
* @param es An optional EndSection callback.
*
* @noreturn
*/
native SMC_SetReaders(SMCParser:smc, const kvFunc[], const nsFunc[] = "", const esFunc[] = "");
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_SetRawLine|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_SetRawLine|header=Sets a raw line reader on an text parser handle.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_SetRawLine|contentonly=yes|content=
<pawn>
/**
* Sets a raw line reader on an text parser handle.
*
* @note Below is the prototype of callbacks:
* -
* Called whenever a raw line is read.
*
* @param handle Handle to an SMC Parse structure.
* @param line A string containing the raw line from the file.
* @param lineno The line number it occurs on.
* @param data Handle or value passed in SMC_ParseFile
*
* @return An SMCResult action to take.
*
* public SMCResult:SMC_RawLine(SMCParser:handle, const line[], lineno, any:data)
* -
* @param handle Handle to an SMC Parse structure.
* @param func A RawLine callback.
*
* @noreturn
*/
native SMC_SetRawLine(SMCParser:handle, const func[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SMC_GetErrorString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SMC_GetErrorString|header=Gets an error string for an SMCError code.|labelpos=left|labelonly=yes}}
{{hidden|id=SMC_GetErrorString|contentonly=yes|content=
<pawn>
/**
* Gets an error string for an SMCError code.
*
* @note SMCError_Okay returns false.
* @note SMCError_Custom (which is thrown on SMCParse_HaltFail) returns false.
*
* @param error The SMCParseError code.
* @param buffer A string buffer for the error (contents undefined on failure).
* @param buf_max The maximum size of the buffer.
*
* @return True on success, false otherwise.
*/
native bool:SMC_GetErrorString(SMCError:error, buffer[], buf_max);
</pawn>
}}
|}

'''INI Format'''

{{alert|success|Technical format detail:|{{hidden|id=ini-format|labelonly=yes}}|opt=full-border}}
{{hidden|id=ini-format|contentonly=yes|content=
<text>
/**
* The INI file format is defined as:
* WHITESPACE: 0x20, \n, \t, \r
* IDENTIFIER: A-Z a-z 0-9 _ - , + . $ ? /
* STRING : Any set of symbols
*
* Basic syntax is comprised of SECTIONs.
* A SECTION is defined as:
* [SECTIONNAME]
* OPTION
* OPTION
* OPTION...
*
* SECTIONNAME is an IDENTIFIER.
* OPTION can be repeated any number of times, once per line.
* OPTION is defined as one of:
* KEY = "VALUE"
* KEY = VALUE
* KEY
* Where KEY is an IDENTIFIER and VALUE is a STRING.
*
* WHITESPACE should always be omitted.
* COMMENTS should be stripped, and are defined as text occurring in:
* ;<TEXT>
*
* Example file below. Note that the second line is technically invalid.
* The event handler must decide whether this should be allowed.
* --FILE BELOW--
* [gaben]
* hi = clams
* bye = "NO CLAMS"
*
* [valve]
* cannot
* maintain
* products
*/
</text>
}}

{| class="wikitable"
! Native
! Description
|-
| style="padding: 0.4em;" | {{tt|INI_CreateParser|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_CreateParser|header=Creates a new SMC parser.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_CreateParser|contentonly=yes|content=
<pawn>
/**
* Parser invalid code.
*/
enum INIParser
{
Invalid_INIParser = 0
};

/**
* Creates a new INI parser.
* This is used to set parse hooks.
*
* @return A new handle to an INI Parse structure.
*/
native INIParser:INI_CreateParser();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_DestroyParser|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_DestroyParser|header=Disposes of an INI parser.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_DestroyParser|contentonly=yes|content=
<pawn>
/**
* Disposes of an INI parser.
*
* @param handle Handle to an INI Parse structure.
*
* @return True if disposed, false otherwise.
*/
native INI_DestroyParser(&INIParser:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_ParseFile|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_ParseFile|header=Parses an INI config file.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_ParseFile|contentonly=yes|content=
<pawn>
/**
* Parses an INI config file.
*
* @param handle A handle to an INI Parse structure.
* @param file A string containing the file path.
* @param line An optional by reference cell to store the last line number read.
* @param col An optional by reference cell to store the last column number read.
* @param data An optional handle or value to pass through to callback functions
*
* @return An SMCParseError result.
* @error Invalid or corrupt handle.
*/
native bool:INI_ParseFile(INIParser:handle, const file[], &line = 0, &col = 0, any:data = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_ParseStart|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_ParseStart|header=Sets the INI_ParseStart function of a parse handle.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_ParseStart|contentonly=yes|content=
<pawn>
/**
* Sets the INI_ParseStart function of a parse handle.
*
* @note Below is the prototype of callback:
* -
* Called when parsing is started.
*
* @param handle A handle to an INI Parse structure.
* @param data Handle or value passed in INI_ParseFile
*
* @noreturn
*
* public OnParseStart(INIParser:handle, any:data)
* -
* @param handle Handle to an INI Parse structure.
* @param func A ParseStart callback.
*
* @noreturn
* @error Invalid or corrupt handle.
*/
native INI_SetParseStart(INIParser:handle, const func[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_SetParseEnd|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_SetParseEnd|header=Sets the INI_ParseEnd function of a parse handle.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_SetParseEnd|contentonly=yes|content=
<pawn>
/**
* Sets the INI_ParseEnd function of a parse handle.
*
* @note Below is the prototype of callback:
* -
* Called when parsing is halted.
*
* @param handle A handle to an INI Parse structure.
* @param halted True if abnormally halted, false otherwise.
* @param data Handle or value passed in INI_ParseFile
*
* @noreturn
*
* public OnParseEnd(INIParser:handle, bool:halted, any:data)
* -
* @param handle Handle to an INI Parse structure.
* @param func A ParseEnd callback.
*
* @noreturn
* @error Invalid or corrupt handle.
*/
native INI_SetParseEnd(INIParser:handle, const func[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_SetReaders|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_SetReaders|header=Sets the two main reader functions.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_SetReaders|contentonly=yes|content=
<pawn>
/**
* Sets the two main reader functions.
*
* @note Below is the prototype of callback:
* -
* NewSection:
* Called when the parser finds a new section.
*
* @param handle Handle to an INI Parse structure.
* @param section Name of section in between the [ and ] characters.
* @param invalid_tokens True if invalid tokens were detected in the name.
* @param close_bracket True if a closing bracket was detected, false otherwise.
* @param extra_tokens True if extra tokens were detected on the line.
* @param curtok Contains current token in the line where the section name starts.
* You can add to this offset when failing to point to a token.
* @param data Handle or value passed in INI_ParseFile
*
* @return True to keep parsing, false otherwise.
*
* public bool:OnNewSection(INIParser:handle, const section[], bool:invalid_tokens, bool:close_bracket, bool:extra_tokens, curtok, any:data)
*
* KeyValue:
* Called when the parser finds a new key/value pair.
*
* @param handle Handle to an INI Parse structure.
* @param key Name of key.
* @param value String containing value (with quotes stripped, if any).
* @param invalid_tokens Whether or not the key contained invalid tokens.
* @param equal_token There was an '=' sign present (in case the value is missing).
* @param quotes Whether value was enclosed in quotes.
* @param curtok Contains the token index of the start of the value string.
* This can be changed when returning false.
* @param data Handle or value passed in INI_ParseFile
*
* @return True to keep parsing, false otherwise.
*
* public bool:OnKeyValue(INIParser:handle, const key[], const value[], bool:invalid_tokens, bool:equal_token, bool:quotes, curtok, any:data)
* -
* @param handle Handle to an INI Parse structure.
* @param kv A KeyValue callback.
* @param ns An optional NewSection callback.
*
* @noreturn
*/
native INI_SetReaders(INIParser:smc, const kvFunc[], const nsFunc[] = "" );
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|INI_SetRawLine|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=INI_SetRawLine|header=Sets a raw line reader on an INI parser handle.|labelpos=left|labelonly=yes}}
{{hidden|id=INI_SetRawLine|contentonly=yes|content=
<pawn>
/**
* Sets a raw line reader on an INI parser handle.
*
* @note Below is the prototype of callback:
* -
* Called whenever a raw line is read.
*
* @param handle The INI Parse handle.
* @param line Contents of line.
* @param lineno The line number it occurs on.
* @param curtok Pointer to optionally store failed position in string.
* @param data Handle or value passed in INI_ParseFile
*
* @return True to keep parsing, false otherwise.
*
* public bool:OnRawLine(INIParser:smc, const line[], lineno, curtok, any:data)
*
* @param handle Handle to an INI Parse structure.
* @param func A RawLine callback.
*
* @noreturn
*/
native INI_SetRawLine(INIParser:handle, const func[]);
</pawn>
}}
|}

== Existing core APIs additions ==

=== Client ===

''' Behavior changes '''

* The following natives can now be used on connecting players: {{tt|find_player}}, {{tt|get_players}} and {{tt|engclient_print}} (console only).
* {{tt|set_user_rendering}} default {{tt|color}} and {{tt|amount}} are now set to 0 to follow game behavior.

''' (Dis)connection '''

{{alert|info|Note:|The {{tt|client_disconnect}} forward is deprecated in favor of {{tt|client_disconnected}}. This will be called in some additional cases that {{tt|client_disconnect}} doesn't cover, most notably when a client aborts the connection process. It is guaranteed to pair with the {{tt|client_connect}} forward.|opt=full-border}}

{| class="wikitable"
! Forward
! Description
|-
| style="padding: 0.4em;" | {{tt|client_connectex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_connectex|header=Called when a client is connecting.|labelpos=left||content=
<pawn>
/**
* Called when a client is connecting.
*
* @note This forward is called too early to do anything that directly affects
* the client.
*
* @param id Client index
* @param name Client name
* @param ip Client ip address with port
* @param reason A reason that will be displayed when player gets rejected (can be overwritten)
*
* @return PLUGIN_CONTINUE to let a client join to the server
* PLUGIN_HANDLED or higher to prevent a client to join
*/
forward client_connectex(id, const name[], const ip[], reason[128]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|client_disconnected|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_disconnected|header=Called when a client is disconnected from the server.|labelpos=left||content=
<pawn>
/**
* Called when a client is disconnected from the server.
*
* @note This will be called in some additional cases that client_disconnect doesn't cover,
* most notably when a client aborts the connection process. It is guaranteed to pair
* with the client_connect() forward.
* @note When this fires the player entity is still valid (e.g. is_user_connected(id) will
* return true), but no networked commands will reach the client.
*
* @param id Client index
* @param drop If true, the game has explicitly dropped the client
* @param message If drop is true, a writable buffer containing the disconnect info message
* @param maxlen Maximum size of buffer
*
* @noreturn
*/
forward client_disconnected(id, bool:drop, message[], maxlen);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|client_remove|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_remove|header=Called when a client entity has been removed from the server.|labelpos=left||content=
<pawn>
/**
* Called when a client entity has been removed from the server.
*
* @note This fires after the client_disconnected() forward, when the player entity has been
* removed (e.g. is_user_connected(id) will return false).
*
* @param id Client index
* @param drop If true, the game has explicitly dropped the client
* @param message If drop is true, contains the disconnect info message
*
* @noreturn
*/
forward client_remove(id, bool:drop, const message[]);
</pawn>
}}
|}

''' New Natives & Stocks '''

For the sake of better understanding and readability, {{tt|find_player}} and {{tt|get_players}} have now their counterparts which use the flags {{hidden|id=find-get-players|labelonly=yes}} as name constants instead of letter. It is encouraged to use them instead.

{{hidden|id=find-get-players|contentonly=yes|content=
<c>
/**
* FindPlayerFlags constants for find_player_ex()
*/
enum FindPlayerFlags (<<= 1)
{
FindPlayer_None = 0, // None
FindPlayer_MatchName = 1, // Match with name
FindPlayer_MatchNameSubstring, // Match with name substring
FindPlayer_MatchAuthId, // Match with authid
FindPlayer_MatchIP, // Match with ip
FindPlayer_MatchTeam, // Match with team name
FindPlayer_ExcludeDead, // Do not include dead clients
FindPlayer_ExcludeAlive, // Do not include alive clients
FindPlayer_ExcludeBots, // Do not include bots
FindPlayer_ExcludeHuman, // Do not include human clients
FindPlayer_LastMatched, // Return last matched client instead of the first
FindPlayer_MatchUserId, // Match with userid
FindPlayer_CaseInsensitive, // Match case insensitively
FindPlayer_IncludeConnecting // Include connecting clients
}
</c>
}}

{| class="wikitable"
! Native & Stock
! Description
|-
| style="padding: 0.4em;" | {{tt|find_player_ex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=find_player_ex|header=Finds a player given a filter.|labelpos=left||content=
<pawn>
/**
* Find a player given a filter.
*
* @note If matching by userid, do not also specify FindPlayer_MatchName, FindPlayer_MatchNameSubstring
* or FindPlayer_MatchAuthId, or the function may not return a correct result.
*
* @param flags Filtering flags (enum FindPlayerFlags); valid flags are:
* FindPlayer_MatchName - match with name
* FindPlayer_MatchNameSubstring - match with name substring
* FindPlayer_MatchAuthId - match with authid
* FindPlayer_MatchIP - match with ip
* FindPlayer_MatchTeam - match with team name
* FindPlayer_ExcludeDead - do not include dead clients
* FindPlayer_ExcludeAlive - do not include alive clients
* FindPlayer_ExcludeBots - do not include bots
* FindPlayer_ExcludeHuman - do not include human clients
* FindPlayer_LastMatched - return last matched client instead of the first
* FindPlayer_MatchUserId - match with userid
* FindPlayer_CaseInsensitive - match case insensitively
* FindPlayer_IncludeConnecting - include connecting clients
* @param ... String to match against (integer if FindPlayer_MatchUserId is specified)
*
* @return Client index, or 0 if no client was found
*/
native find_player_ex(FindPlayerFlags:flags, ...);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_players_ex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_players_ex|header=Stores a filtered list of client indexes to an array.|labelpos=left||content=
<pawn>
/**
* Stores a filtered list of client indexes to an array.
*
* @note Example retrieving all alive CTs:
* get_players_ex(players, num, GetPlayers_ExcludeDead | GetPlayers_MatchTeam, "CT")
*
* @param players Array to store indexes to
* @param num Variable to store number of indexes to
* @param flags Optional filtering flags (enum GetPlayersFlags); valid flags are:
* GetPlayers_None - No filter (Default)
* GetPlayers_ExcludeDead - do not include dead clients
* GetPlayers_ExcludeAlive - do not include alive clients
* GetPlayers_ExcludeBots - do not include bots
* GetPlayers_ExcludeHuman - do not include human clients
* GetPlayers_MatchTeam - match with team
* GetPlayers_MatchNameSubstring - match with part of name
* GetPlayers_CaseInsensitive - match case insensitive
* GetPlayers_ExcludeHLTV - do not include HLTV proxies
* GetPlayers_IncludeConnecting - include connecting clients
* @param team String to match against if the "e" or "f" flag is specified
*
* @noreturn
*/
stock get_players_ex(players[MAX_PLAYERS], &num, GetPlayersFlags:flags = GetPlayers_None, const team[] = "")
{
new strFlags[10];
get_flags(_:flags, strFlags, charsmax(strFlags));
get_players(players, num, strFlags, team);
}
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=cvar_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=cvar_example|contentonly=yes|content=
<pawn>
findPlayer()
{
new const dead_player = find_player_ex(FindPlayer_MatchName | FindPlayer_ExcludeAlive, "egg");
}

getPlayer()
{
new playersList[MAX_PLAYERS], playersCount;
get_players_ex(playersList, playersCount, GetPlayers_ExcludeDead | GetPlayers_MatchTeam, "CT");
}
</pawn>
}}

''' New params '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|user_silentkill|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|flag|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=user_silentkill|header=If nonzero, the death will not affect the client's score.|labelpos=left|content=
<pawn>
stock user_silentkill(index, flag = 1)
{
static msgid = 0;
new msgblock;
if (!msgid)
{
msgid = get_user_msgid("DeathMsg");
}
msgblock = get_msg_block(msgid);
set_msg_block(msgid, BLOCK_ONCE);
user_kill(index, flag);
set_msg_block(msgid, msgblock);

return 1;
}
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Forward
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|client_authorized|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|authid|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_authorized|header=Client auth|labelpos=left|content=
<pawn>
forward client_authorized(id, const authid[]);
</pawn>
}}
|}

=== Command ===

''' Callback '''

{| class="wikitable"
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|amxclient_cmd|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=amxclient_cmd|header=Executes a command from the client without actually sending it to the client's DLL. Similar to {{tt|engclient_cmd|bgcolor=white}} with the difference this triggers plugin command hooks.|labelpos=left|labelonly=yes}}
{{hidden|id=amxclient_cmd|contentonly=yes|content=
<pawn>
/**
* Execute a command from the client without actually sending it to the client's
* DLL. This triggers plugin command hooks.
*
* @note This emulates a client command on the server side, and is an excellent
* tool to force a client to do certain actions related to the game.
* @note The command has to stand alone in the command parameter, only add
* arguments using the designated parameters.
* @note Commands emulated using this function will trigger other plugin's
* command hooks. For an alternative that doesn't, see engclient_cmd()
*
* @param index Client index, use 0 to execute from all clients
* @param command Client command to execute on
* @param arg1 Optional command arguments
* @param arg2 Optional command arguments
*
* @noreturn
* @error If a single client is specified and the index is not within
* the range of 1 to MaxClients, an error will be thrown.
*/
native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
</pawn>
}}
|}

''' Arguments conversion'''

Convenient natives to convert directly from a string to an integer or float value.

{| class="wikitable"
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|read_argv_int|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=read_argv_int|header=Retrieves argument of client command as integer value.|labelpos=left|labelonly=yes}}
{{hidden|id=read_argv_int|contentonly=yes|content=
<pawn>
/**
* Retrieves argument of client command as integer value.
*
* @note Should only be used inside of the client_command() forward.
*
* @param id Argument index starting from 1
*
* @return Integer value
*/
native read_argv_int(id);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|read_argv_float|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=read_argv_float|header=Retrieves argument of client command as float value.|labelpos=left|labelonly=yes}}
{{hidden|id=read_argv_float|contentonly=yes|content=
<pawn>
/**
* Retrieves argument of client command as float value.
*
* @note Should only be used inside of the client_command() forward.
*
* @param id Argument index starting from 1
*
* @return Float value
*/
native Float:read_argv_float(id);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=read_argv_int-ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=read_argv_int-ex|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
register_clcmd("set_level", "@OnSetLevel", .info = "<value> - Sets a custom level");
}

@OnSetLevel(const client, const command_level, const command_id)
{
new const value = read_argv_int(1);
}
</pawn>
}}

''' Translatable description '''

In order to encourage the translations of command's description, a new parameter is available. 
This is useful for use with the {{tt|amx_help}} client command for example.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|register_clcmd|bgcolor=white}} {{tt|register_concmd|bgcolor=white}} {{tt|register_srvcmd|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|info_ml|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=register_cmd|header=If true, the parameter {{tt|info|bgcolor=white}} will be looked up as multilingual key.|labelpos=left|content=
<pawn>
/**
* Registers a callback to be called when the client executes a command from the
* console.
*
* @note For a list of possible access flags, see the ADMIN_* constants in
* amxconst.inc
* @note Opting in to FlagManager enables the admin privileges to be overwritten
* by the end user via the cmdaccess.ini config file.
* @note Automatic detection for FlagManager will only include a command if it
* has required privileges (flags is not -1) and it is not a command
* starting with "say".
*
* @param client_cmd Command to register
* @param function Callback function
* @param flags Admin privilege flags required
* @param info Command description
* @param FlagManager 0 opts out of flag manager, 1 opts in, -1 selects
* automatically
* @param info_ml If true, the parameter "info" will be looked up as multilingual key
*
* @return Command id, 0 on failure
* @error If an invalid callback function is specified, an error
* will be thrown.
*/
native register_clcmd(const client_cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1, bool:info_ml = false);

/**
* Registers a callback to be called when the client or server executes a
* command from the console.
*
* @note For a list of possible access flags, see the ADMIN_* constants in
* amxconst.inc
* @note Opting in to FlagManager enables the admin privileges to be overwritten
* by the end user via the cmdaccess.ini config file.
* @note Automatic detection for FlagManager will only include a command if it
* has required privileges (flags is not -1) and it is not a command
* starting with "say".
*
* @param client_cmd Command to register
* @param function Callback function
* @param flags Admin privilege flags required
* @param info Command description
* @param FlagManager 0 opts out of flag manager, 1 opts in, -1 selects
* automatically
* @param info_ml If true, the parameter "info" will be looked up as multilingual key
*
* @return Command id, 0 on failure
* @error If an invalid callback function is specified, an error
* will be thrown.
*/
native register_concmd(const cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1, bool:info_ml = false);

/**
* Registers a callback to be called when the server executes a command from the
* console.
*
* @note For a list of possible access flags, see the ADMIN_* constants in
* amxconst.inc
*
* @param client_cmd Command to register
* @param function Callback function
* @param flags Admin privilege flags required
* @param info Command description
* @param info_ml If true, the parameter "info" will be looked up as multilingual key
*
* @return Command id, 0 on failure
* @error If an invalid callback function is specified, an error
* will be thrown.
*/
native register_srvcmd(const server_cmd[], const function[], flags = -1, const info[] = "", bool:info_ml = false);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=trans-cmd|labelonly=yes}}|opt=full-border}}
{{hidden|id=trans-cmd|contentonly=yes|content=
<text>
[en]
MY_KEY = Hello world!
</text>

<pawn>
#include <amxmodx>

public plugin_init()
{
register_clcmd("my_command", "OnMyCommand", ADMIN_CFG, "MY_KEY", .info_ml = true);
}
</pawn>
}}

=== Cvar ===

In order to manage cvars more easily, several new cvar features have been added. 

{{alert|info|Note:|A cvar managed at least once is now cached internally, for faster lookup, that's it.|opt=full-border}}
{{alert|info|Note:|The cvar API is now moved to its own {{tt|cvars.inc|bgcolor=none}} include file.|opt=full-border}}

''' Hooking '''

You can now hook when a cvar value has changed. This allows plugins to react to cases where other plugins or clients change a cvar's value.

{| class="wikitable"
! Native
! Description
|-
| style="padding: 0.4em;" | {{tt|hook_cvar_change|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=hook_cvar_change|header=To create a hook|labelpos=left|labelonly=yes}}
{{hidden|id=hook_cvar_change|contentonly=yes|content=
<pawn>
/**
* Creates a hook for when a cvar's value is changed.
*
* @note Changing the cvar value from within this forward can lead to infinite
* recursion and should be avoided.
* @note The callback will be called in the following manner:
*
* public cvar_change_callback(pcvar, const old_value[], const new_value[])
*
* pcvar - Pointer to cvar that was changed
* old_value - Buffer containing the previous value of the cvar
* new_value - Buffer containing the new value of the cvar
*
* The return value is ignored
*
* @param pcvar Pointer to cvar
* @param callback Name of callback function
*
* @return Callback handle that can be used with
* [disable|enable]_cvar_hook
* @error If an invalid cvar pointer or callback function is provided,
* an error will be thrown.
*/
native cvarhook:hook_cvar_change(pcvar, const callback[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|disable_cvar_hook|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=disable_cvar_hook|header=To disable a hook|labelpos=left|labelonly=yes}}
{{hidden|id=disable_cvar_hook|contentonly=yes|content=
<pawn>
/**
* Disables a cvar hook, stopping it from being called.
*
* @note Use the handle returned by hook_cvar_change as the parameter here.
*
* @param handle Forward to disable
* @error If an invalid hook handle is provided, an error will be
* thrown.
*/
native disable_cvar_hook(cvarhook:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|enable_cvar_hook|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=enable_cvar_hook|header=To enable a hook|labelpos=left||content=
<pawn>
/**
* Enables a cvar hook, restoring it to being called.
*
* @note Use the handle returned by hook_cvar_change as the parameter here.
*
* @param handle Forward to enable
* @error If an invalid hook handle is provided, an error will be
* thrown.
*/
native enable_cvar_hook(cvarhook:handle);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=cvar_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=cvar_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

new cvarhook:CvarHandle;

public plugin_init()
{
CvarHandle = hook_cvar_change(get_cvar_pointer("mp_timelimit"), "@OnTimelimitChange");

register_concmd("enable_hook" , "@OnConsoleCommand_EnableHook");
register_concmd("disable_hook", "@OnConsoleCommand_DisableHook");
}

@OnTimelimitChange(const pointer, const old_value[], const new_value[])
{
server_print("mp_timelimit: %s -> %s", old_value, new_value);
}

@OnClientCommand_EnableHook()
{
enable_cvar_hook(CvarHandle);
}

@OnClientCommand_DisableHook()
{
disable_cvar_hook(CvarHandle);
}
</pawn>
}}

''' Binding '''

There are situations where you don't need to hook/manage a cvar value and you would wish to not deal with cvar pointers. 
You can now bind a cvar's value to a global variable. This means that variable value will be always up to date.

{| class="wikitable"
! Native
! Description
|-
| style="padding: 0.4em;" | {{tt|bind_pcvar_num|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=bind_pcvar_num|header=To bind an integer|labelpos=left||content=
<pawn>
/**
* Binds a cvar's integer value to a global variable. The variable will then
* always contain the current cvar value as it is automatically kept up to date.
*
* @note The variable *has* to be a global or a static variable. Local variables
* created within functions can not be used for technical reasons.
* @note Variables can not be bound to multiple cvars.
*
* @param pcvar Pointer to cvar
* @param var Global variable to keep updated
*
* @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/
native bind_pcvar_num(pcvar, &any:var);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|bind_pcvar_float|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=bind_pcvar_float|header=To bind a float|labelpos=left||content=
<pawn>
/**
* Binds a cvar's float value to a global variable. The variable will then
* always contain the current cvar value as it is automatically kept up to date.
*
* @note The variable *has* to be a global or a static variable. Local variables
* created within functions can not be used for technical reasons.
* @note Variables can not be bound to multiple cvars.
*
* @param pcvar Pointer to cvar
* @param var Global variable to keep updated
*
* @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/
native bind_pcvar_float(pcvar, &Float:var);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|bind_pcvar_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=bind_pcvar_string|header=To bind a string|labelpos=left||content=
<pawn>
/**
* Binds a cvar's string value to a global array. The array will then
* always contain the current cvar value as it is automatically kept up to date.
*
* @note The array *has* to be a global or a static array. Local arrays
* created within functions can not be used for technical reasons.
* @note Arrays can not be bound to multiple cvars.
*
* @param pcvar Pointer to cvar
* @param var Global array to keep updated
* @param varlen Maximum length of string array
*
* @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/
native bind_pcvar_string(pcvar, any:var[], varlen);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=bind_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=bind_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

new CvarTimelimit;
new Float:CvarBuyTime;
new CvarSomething[32];

public plugin_init()
{
bind_pcvar_num(get_cvar_pointer("mp_timelimit"), CvarTimelimit);
bind_pcvar_float(get_cvar_pointer("mp_buytime"), CvarBuyTime);
bind_pcvar_string(register_cvar("amx_something", "something"), CvarSomething, charsmax(CvarSomething));

server_print("mp_timelimit current value: %d", CvarTimelimit);
server_print("mp_buytime current value: %f", CvarBuyTime);
server_print("amx_something current value: %s", CvarSomething);
}
</pawn>
}}

''' Boundary '''

Having a better control over a cvar's value, we can enforce the value to be in a defined boundary.

{| class=wikitable
! Description
! Native
|-
| style="padding: 0.4em;" | {{tt|get_pcvar_bounds|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pcvar_bounds|header=To get a boundary|labelpos=left|content=
<pawn>
/**
* Retrieves the specified value boundary of a cvar.
*
* @param pcvar Pointer to cvar
* @param type Type of boundary to retrieve
* @param value Variable to store the specified boundary to
*
* @return True if the cvar has a boundary set, false otherwise
* @error If an invalid cvar pointer or boundary type is provided,
* an error will be thrown.
*/
native bool:get_pcvar_bounds(pcvar, CvarBounds:type, &Float:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|set_pcvar_bounds|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=set_pcvar_bounds|header=To set a boundary|labelpos=left|content=
<pawn>
/**
* Sets the specified boundary of a cvar.
*
* @param pcvar Pointer to cvar
* @param type Type of boundary to set
* @param set If true the cvar boundary will be set, otherwise it will be
* removed (value is ignored)
* @param value Floating point value to use as the boundary
*
* @noreturn
* @error If an invalid cvar pointer or boundary type is provided, an
* error will be thrown.
*/
native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0);
</pawn>
}}
|}

{{alert|info|Note:|{{tt|CvarBounds|bgcolor=none}} has the following values:
* {{tt|CvarBound_Upper}}
* {{tt|CvarBound_Lower}}|opt=full-border}}

{{alert|success|Example:|{{hidden|id=bounds_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=bounds_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new const pointer = register_cvar("amx_leet", "1337");

// Defines min and max value
set_pcvar_bounds(pointer, CvarBound_Lower, .set = true, 0.0);
set_pcvar_bounds(pointer, CvarBound_Upper, .set = true, 42.0);

// Current value should be "42".
server_print("amx_something current value: %f", get_pcvar_float(pointer));

// Removes the lower bound.
set_pcvar_bounds(pointer, CvarBound_Lower, .set = false);

new Float:value;

if (get_pcvar_bounds(pointer, CvarBound_Upper, value))
{
server_print("amx_something should have an upper bound: %f", value);
}

if (!get_pcvar_bounds(pointer, CvarBound_Upper, value))
{
server_print("amx_something should not have an lower bound);
}
}
</pawn>
}}

''' Constant '''

A missing {{tt|FCVAR_NOEXTRAWHITEPACE}} flag has been added. 
It automatically strips trailing/leading white space from the string value.

''' Creating '''

A new {{tt|create_cvar}} {{hidden|id=create_cvar|labelonly=yes}} native has been added, similar to {{tt|register_cvar|bgcolor=none}} but with two new features:
{{hidden|id=create_cvar|contentonly=yes|content=
<pawn>
/**
* Creates a new cvar for the engine.
*
* @note This has the same effect as register_cvar() but provides more options.
* @note For a list of possible cvar flags see FCVAR_* constants above.
* @note If an already existing cvar is registered it will not be duplicated.
* The default value is only set when the cvar is registered for the very
* first time since the server was started. Cvar bounds are overwritten
* by the create_cvar() call just as if they were re-set using
* set_pcvar_bounds().
* @note The returned cvar pointer should be used with the get_pcvar_* and
* set_pcvar_* set of functions.
*
* @param name Cvar name
* @param string Default cvar value
* @param flags Optional bitsum of flags specifying cvar behavior
* @param description Optional description of the cvar
* @param has_min Optional boolean that specifies if the cvar has a
* minimum value
* @param min_val Minimum floating point value
* @param has_max Optional boolean that specifies if the cvar has a
* maximum value
* @param max_val Maximum floating point value
*
* @return Unique cvar pointer
* @error If invalid bounds are provided (min_val > max_val or
* vice versa), an error will be thrown.
*/
native create_cvar(const name[], const string[], flags = FCVAR_NONE, const description[] = "", bool:has_min = false, Float:min_val = 0.0, bool:has_max = false, Float:max_val = 0.0);
</pawn>
}}

{| class=wikitable
| style="padding: 0.4em;" | ''Description''
| style="padding: 0.4em;" | Similar to command, you can explain shorlty what does the cvar. The message can be retrieved with {{tt|get_plugins_cvar|bgcolor=white}} and can be read from {{tt|amxx cvars|bgcolor=white}} detailed output. The description is used with {{tt|AutoExecConfig|bgcolor=white}} for example.
|-
| style="padding: 0.4em;" | ''Boudary''
| style="padding: 0.4em;" | You can set directly a boudary, either a minimum value, a maximum value or both.
|}

{{alert|success|Example:|{{hidden|id=creeate_cvar_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=creeate_cvar_example|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
create_cvar("amx_something1", "1", FCVAR_NONE, "My description here", true, 1.0, true, 42.0);
create_cvar("amx_something2", "2", .description = "My description here", .has_min = true, min_val = 1.0, .has_max = true, .max_val = 42.0);
create_cvar("amx_something3", "3", .has_min = true, min_val = 1.0);
create_cvar("amx_something4", "4", .has_max = true, max_val = 42.0);
}
</pawn>
}}

''' Command '''

The {{tt|amxx cvars}} shows now more informations about a cvar state.
Here an example of output:

<text>
Managed cvars:
NAME VALUE PLUGIN HOOKED MIN MAX
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[ 1] amx_mode 1 admin.amxx no - -
[ 2] amx_password_field _pw admin.amxx no - -
[ 3] amx_default_access z admin.amxx no - -
[ 4] amx_vote_ratio 0.02 admin.amxx no - -
[ 5] amx_something something test-hook.amxx yes - -
[ 6] amx_leet 42 test-bounds.amxx no 0.00 42.00
...
</text>

It can show further details if you specify a cvar or index from the table: {{tt|amxx cvars <index or cvar name>}}

<text>
amxx cvars 6

Cvar details :

Cvar name : amx_leet
Value : 42
Def. value : 1337
Description :
Flags : FCVAR_EXTDLL

STATUS PLUGIN INFOS
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Registered test-bounds.amxx -
Min value test-bounds.amxx 0.000000
Max value test-bounds.amxx 42.000000
</text>

''' Others '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_pcvar_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pcvar_bool|header=Returns an boolean value from a cvar via direct pointer access.|labelpos=left||content=
<pawn>
/**
* Returns an boolean value from a cvar via direct pointer access.
*
* @param pcvar Pointer to cvar to retrieve value from
*
* @return Cvar value, converted to bool
* @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/
native bool:get_pcvar_bool(pcvar);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|set_pcvar_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=set_pcvar_bool|header=Sets a boolean value to a cvar via direct pointer access.|labelpos=left||content=
<pawn>
/**
* Sets a boolean value to a cvar via direct pointer access.
*
* @param pcvar Pointer to cvar to set value of
* @param num Value to set cvar to
*
* @noreturn
* @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/
native set_pcvar_bool(pcvar, bool:num);
</pawn>
}}
|}

=== CellArray ===

A bunch of natives have been added to complete the existing API. You are now able to:
* Clone an array
* Resize an array
* Find a value or string inside an array
* Control more precisely how the data is retrieved/saved

{{alert|info|Note:|Arrays are heterogeneous. This means you can save different data types into a list. A good example is the Stack Structure API which is actually based on Array (internal library, that's it).|opt=full-border}}
{{alert|info|Note:|Initially the {{tt|reserved|bgcolor=none}} parameter in {{tt|ArrayCreate|bgcolor=none}} was intended to create blank entries that would immediately be usable with {{tt|ArrayGet/Set|bgcolor=white}} functions. This functionality was never working as intended, and can now be achieved using {{tt|ArrayResize|bgcolor=none}}.|opt=full-border}}

''' Cloning '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|ArrayClone|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ArrayClone|header=Clones an array.|labelpos=left||content=
<pawn>
/**
* Clones an array, returning a new handle with the same size and data.
*
* @param which Array handle
*
* @return Handle to the cloned array on success, 0 otherwise
* @error If an invalid handle is provided an error will be
* thrown.
*/
native Array:ArrayClone(Array:which);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=array_cloning_ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=array_cloning_ex|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new Array:list = ArrayCreate();

ArrayPushCell(list, 1);
ArrayPushCell(list, 2);
ArrayPushCell(list, 3);

new Array:clone_list = ArrayClone(list);

//

ArrayDestroy(clone_list);
ArrayDestroy(list);
}
</pawn>
}}

''' Resizing '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|ArrayResize|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ArrayResize|header=Resizes an array.|labelpos=left||content=
<pawn>
/**
* Resizes an array.
*
* @note If the size is smaller than the current array size the array is
* truncated and data lost.
*
* @param which Array handle
* @param newsize New size
*
* @noreturn
* @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/
native bool:ArrayResize(Array:which, newsize);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=array_resize_ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=array_resize_ex|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new Array:list = ArrayCreate(.cellsize = 1, .reserved = 3);

ArrayPushCell(list, 1);
ArrayPushCell(list, 2);
ArrayPushCell(list, 3);

new const count = ArraySize(list);

ArrayResize( list, count + 1); // Add a new allocated and available slot
ArraySetCell(list, count, 4); // Notice you can use directly ArraySet

server_print("Last value = %d, Cloned list size = %d", ArrayGetCell(list, count), ArraySize(list)); // Should be 4.

ArrayDestroy(list);
}
</pawn>
}}

''' Finding a value '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|ArrayFindValue|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ArrayFindValue|header=Searches through the array and returns the index of the first occurence of the specified value.|labelpos=left||content=
<pawn>
/**
* Searches through the array and returns the index of the first occurence of
* the specified value.
*
* @param which Array handle
* @param item Value to search for
*
* @return Array index on success, -1 if the value can't be found
* @error If an invalid handle is provided an error will be
* thrown.
*/
native ArrayFindValue(Array:which, any:item);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|ArrayFindString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ArrayFindString|header= Searches through the array and returns the index of the first occurence of the specified string.|labelpos=left||content=
<pawn>
/**
* Searches through the array and returns the index of the first occurence of
* the specified string.
*
* @param which Array handle
* @param item String to search for
*
* @return Array index on success, -1 if the string can't be found
* @error Invalid handle.
*/
native ArrayFindString(Array:which, const item[]);
</pawn>
}}
|}

{{alert|success|Example:|{{hidden|id=array_find_ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=array_find_ex|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new Array:list = ArrayCreate(.cellsize = 16);

ArrayPushString(list, "something");
ArrayPushString(list, "is");
ArrayPushCell(list, 42);
ArrayPushString(list, "hidden");

new index = ArrayFindValue(list, 42);
server_print("Cell index = %d", index); // should be 2

index = ArrayFindString(list, "hidden");
server_print("String index = %d", index); // should be 3

ArrayDestroy(list);
}
</pawn>
}}

''' Sorting '''

Along two new {{tt|ArraySort}} and {{tt|SortADTArray}} natives, there is also a new {{tt|Sort_Random}} method.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|ArraySortEx|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=ArraySortEx|header=A faster version of {{tt|ArraySort|bgcolor=none}}.|labelpos=left||content=
<pawn>
/**
* A faster version of ArraySort, the sorting algorithm then uses the custom
* comparison function to sort the data.
*
* @note The advantage of this function is that the data of the elements being
* compared is directly passed to the function, instead of the item
* indexes that are passed by ArraySort. This removes the need for calling
* ArrayGet[Cell|String|Array] every time before being able to compare the
* elements.
*
* @note For Arrays with a cellsize of 1 (used for storing integers and floats),
* the function is called in the following manner:
*
* public MySortFunc(Array:array, elem1, elem2, const data[], data_size)
*
* array - Array handle in its current un-sorted state
* elem1, elem2 - Current element pair being compared
* data[] - Extra data array passed to the sort func
* data_size - Size of extra data
*
* @note For Arrays with a cellsize larger than 1 (used for storing arrays and
* strings), the function is called in the following manner:
*
* public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size)
*
* array - Array handle in its current un-sorted state
* elem1[], elem2[] - Current element pair being compared
* data[] - Extra data array passed to the sort func
* data_size - Size of extra data
*
*
* @note The comparison function should return:
* -1 if elem1 should go before elem2
* 0 if elem1 and elem2 are equal
* 1 if elem1 should go after elem2
*
* @note All parameters after item2 are optional and do not need to be specified
* and used.
* @note Unlike the sorting.inc version, the array passed to the callback is not
* in mid-sorted state.
*
* @param array Array handle
* @param comparefunc Callback function used for comparison
* @param data Extra data that is passed through to the callback
* @param data_size Size of extra data
*
* @noreturn
* @error If an invalid handle or an invalid callback is provided
* an error will be thrown.
*/
native ArraySortEx(Array:array, const comparefunc[], data[]="", data_size=0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SortADTArray|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SortADTArray|header=To sort directly with a sort method.|labelpos=left||content=
<pawn>
/**
* Sort an ADT Array. Specify the type as Integer, Float, or String.
*
* @param array Array Handle to sort
* @param order Sort order to use, same as other sorts.
* @param type Data type stored in the ADT Array
* @noreturn
*/
native SortADTArray(Array:array, SortMethod:order, SortType:type);
</pawn>
{{alert|info|Note:|{{tt|SortMethod|bgcolor=none}} has the following values:
* {{tt|Sort_Ascending}}
* {{tt|Sort_Descending}}
* {{tt|Sort_Random}}|opt=full-border}}
}}
|}

''' New params '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|ArrayGetArray|bgcolor=white}} {{tt|ArraySetArray|bgcolor=white}} {{tt|ArrayPushArray|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|size|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=new_size_param|header=Controls the number of elements to use.|labelpos=left|content=
<pawn>
/**
* @param size If not set, assumes the buffer size is equal to the
* cellsize. Otherwise, the specified size is used.
*/
native ArrayGetArray(Array:which, item, any:output[], size = -1);
native ArraySetArray(Array:which, item, const any:input[], size =-1);
native ArrayPushArray(Array:which, const any:input[], size = -1);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|ArrayGetCell|bgcolor=white}} {{tt|ArraySetCell|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|achar|bgcolor=white}} {{tt|block|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=new_blockaschar_param|header=Specifies which block and retrieves a value as byte.|labelpos=left|content=
<pawn>
/**
* @param block If the array has a cellsize >1 this optionally specifies
* which block to read from
* @param asChar If true reads the value as a byte instead of a cell
*/
native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false);
</pawn>
}}
|}

=== CellTrie ===

The word "''Trie''" in this API is historical. As of AMX Mod X 1.9, tries have been internally replaced with hash tables, which have {{tt|O(1)|bgcolor=none}} insertion time instead of {{tt|O(n)|bgcolor=none}}. 
As consequence, the API has been completed and you can now:
* Get a trie size
* Control more precisely the data on insertion/retrieval
* Iterate over a trie

{{alert|info|Note:|Tries are heterogeneous. This means you can save different data types into a list.|opt=full-border}}

''' Getting size '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|TrieGetSize|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieGetSize|header=Returns the number of entries in a hash map.|labelpos=left|content=
<pawn>
/**
* Returns the number of entries in a hash map.
*
* @param handle Map handle
*
* @return Number of elements in the hash map
* @error If an invalid handle is provided an error will be
* thrown.
*/
native TrieGetSize(Trie:handle);
</pawn>
}}
|}

''' Iterating '''

There are two ways to iterate over a trie:
* ''Snapshots''
: As the name suggested, it will duplicate the whole set of keys (only) into a separate list. Any changes to the original list will not affect the snapshot. It's an expensive operation, but can be stored.

:{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|TrieSnapshotCreate|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieSnapshotCreate|header=Creates a snapshot of all keys in a hash map.|labelpos=left|content=
<pawn>
/**
* Creates a snapshot of all keys in a hash map. If the map is changed
* afterwards, the changes are not reflected in the snapshot.
* Keys are not sorted.
*
* @param handle Map handle
*
* @return New map snapshot handle, which must be freed via
* TrieSnapshotDestroy()
* @error If an invalid handle is provided an error will be
* thrown.
*/
native Snapshot:TrieSnapshotCreate(Trie:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieSnapshotLength|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieSnapshotLength|header=Returns the number of keys in a map snapshot.|labelpos=left|content=
<pawn>
/**
* Returns the number of keys in a map snapshot. Note that this may be
* different from the size of the map, since the map can change after the
* snapshot of its keys was taken.
*
* @param handle Map snapshot handle
*
* @return Number of keys
* @error If an invalid handle is provided an error will be
* thrown.
*/
native TrieSnapshotLength(Snapshot:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieSnapshotGetKey|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieSnapshotGetKey|header= Retrieves the key string of a given key in a map snapshot.|labelpos=left|content=
<pawn>
/**
* Retrieves the key string of a given key in a map snapshot.
*
* @param handle Map snapshot handle
* @param index Key index (starting from 0)
* @param buffer String buffer
* @param maxlength Maximum buffer length
*
* @return Number of bytes written to the buffer
* @error If an invalid handle is provided an error will be
* thrown. or index out of range
*/
native TrieSnapshotGetKey(Snapshot:handle, index, buffer[], maxlength);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieSnapshotDestroy|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieSnapshotDestroy|header= Retrieves the key string of a given key in a map snapshot.|labelpos=left|content=
<pawn>
/**
* Destroys a map snapshot and frees its memory.
*
* @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
*
* @param handle Map snapshot handle
*
* @return 1 on success, 0 if an invalid handle was passed in
*/
native TrieSnapshotDestroy(&Snapshot:handle);
</pawn>
}}
|}

:{{alert|info|Note:|The keys are not sorted.|opt=full-border}}
:{{alert|success|Example:|{{hidden|id=trie_example_snap|labelonly=yes}}|opt=full-border}}
{{hidden|id=trie_example_snap|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new Trie:list = TrieCreate();
{
TrieSetString(list, "adventure", "time!");
TrieSetString(list, "butterflies", "bees");
TrieSetString(list, "egg", "egg");
}

new Snapshot:keys = TrieSnapshotCreate(list);
{
new const length = TrieSnapshotLength(keys);
new key[32];

for (new const i = 0; i < length; ++i)
{
TrieSnapshotGetKey(keys, i, buffer, charmax(buffer));
server_print("buffer = %s", buffer);
}
}

TrieSnapshotDestroy(keys);
}
</pawn>
}}

* ''Iterator''
: A contrario, Iterators are designed to be short-lived and not stored, and creating them is very cheap. Reading data from an iterator is just as fast as reading directly from the map. This is useful if you just need to iterate (or eventually updating values of existing keys, which is allowed)

:{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|TrieIterCreate|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterCreate|header=Creates an iterator for a map.|labelpos=left|content=
<pawn>
/**
* Creates an iterator for a map. It provides iterative read-only access to the
* maps contents.
*
* @note Removing or adding keys to the underlying map will invalidate all its
* iterators. Updating values of existing keys is allowed and the changes
* will be immediately reflected in the iterator.
* @note Iterators are designed to be short-lived and not stored, and creating
* them is very cheap. Reading data from an iterator is just as fast as
* reading directly from the map.
* @note Just like in snapshots the keys are not sorted.
*
* @return New iterator handle, which must be freed via TrieIterDestroy().
* @error Invalid Handle
*/
native TrieIter:TrieIterCreate(Trie:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterEnded|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterEnded|header= Returns if the iterator has reached its end and no more data can be read.|labelpos=left|content=
<pawn>
/**
* Returns if the iterator has reached its end and no more data can be read.
*
* @param handle Iterator handle
*
* @return True if iterator has reached the end, false otherwise
* @error Invalid Handle
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native bool:TrieIterEnded(TrieIter:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterNext|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterNext|header=Advances the iterator to the next key/value pair if one is available.|labelpos=left|content=
<pawn>
/**
* Advances the iterator to the next key/value pair if one is available.
*
* @param handle Iterator handle
*
* @error Invalid Handle
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native TrieIterNext(TrieIter:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterGetKey|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterGetKey|header=Retrieves the key the iterator currently points to.|labelpos=left|content=
<pawn>
/**
* Retrieves the key the iterator currently points to.
*
* @param handle Iterator handle.
* @param key Buffer to store the current key in.
* @param outputsize Maximum size of string buffer.
*
* @return Nnumber of bytes written to the buffer
* @error Invalid handle
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native TrieIterGetKey(TrieIter:handle, key[], outputsize);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterGetSize|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterGetSize|header=Retrieves the number of elements in the underlying map.|labelpos=left|content=
<pawn>
/**
* Retrieves the number of elements in the underlying map.
*
* @note When used on a valid iterator this is exactly the same as calling TrieGetSize on the map directly.
*
* @param handle Iterator handle
*
* @return Number of elements in the map
* @error Invalid handle
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native TrieIterGetSize(TrieIter:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterGetCell|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterGetCell|header=Retrieves a value at the current position of the iterator.|labelpos=left|content=
<pawn>
/**
* Retrieves a value at the current position of the iterator.
*
* @param handle Iterator handle
* @param value Variable to store value in
*
* @return True on success, false if the iterator is empty or the current
* value is an array or a string.
* @error Invalid handle
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native bool:TrieIterGetCell(TrieIter:handle, &any:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterGetString|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterGetString|header=Retrieves a string at the current position of the iterator.|labelpos=left|content=
<pawn>
/**
* Retrieves a string at the current position of the iterator.
*
* @param handle Iterator handle
* @param buffer Buffer to store the string in
* @param outputsize Maximum size of string buffer
* @param size Optional parameter to store the number of bytes written to the buffer.
*
* @return True on success, false if the iterator is empty or the current value
* is not a string.
* @error Invalid handle
* Invalid buffer size
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native bool:TrieIterGetString(TrieIter:handle, buffer[], outputsize, &size = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterGetArray|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterGetArray|header=Retrieves an array at the current position of the iterator.|labelpos=left|content=
<pawn>
/**
* Retrieves an array at the current position of the iterator.
*
* @param handle Iterator handle
* @param buffer Buffer to store the array
* @param outputsize Maximum size of buffer
* @param size Optional parameter to store the number of bytes written to the buffer
*
* @return True on success, false if the iterator is empty or the current
* value is not an array.
* @error Invalid handle
* Invalid buffer size
* Iterator has been closed (underlying map destroyed)
* Iterator is outdated
*/
native bool:TrieIterGetArray(TrieIter:handle, any:array[], outputsize, &size = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieIterDestroy|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=TrieIterDestroy|header=Destroys an iterator handle.|labelpos=left|content=
<pawn>
/**
* Destroys an iterator handle.
*
* @param handle Iterator handle.
*
* @return True on success, false if the value was never set.
*/
native TrieIterDestroy(&TrieIter:handle);
</pawn>
}}
|}

:{{alert|info|Note:|The keys are not sorted.|opt=full-border}}
:{{alert|success|Example:|{{hidden|id=trie_example_iter|labelonly=yes}}|opt=full-border}}
{{hidden|id=trie_example_iter|contentonly=yes|content=
<pawn>
#include <amxmodx>

public plugin_init()
{
new Trie:list = TrieCreate();
{
TrieSetString(list, "adventure", "time!");
TrieSetString(list, "butterflies", "bees");
TrieSetString(list, "hello", "world!");
}

new TrieIter:iter = TrieIterCreate(list);
{
new key[32], key_length;
new value[32], value_length;

while (!TrieIterEnded(iter))
{
key_length = TrieIterGetKey(iter, key, charsmax(key));
TrieIterGetString(iter, value, charsmax(value), value_length);

server_print("%s (%d) -> %s (%d)", key, key_length, value, value_length);

// Should throw an error
// TrieSetString(t, "monkey", "island");
// TrieDeleteKey(t, "full");
// TrieClear(t);

TrieIterNext(iter);
}
}
TrieIterDestroy(iter);

TrieDestroy(list);
}
</pawn>
}}

''' New params '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|TrieSetString|bgcolor=white}} {{tt|TrieSetArray|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|replace|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=trie_new_replace_param|header=Makes operation fail if key already set.|labelpos=left|content=
<pawn>
/**
* @param replace If false the operation will fail if the key is already set
*/
native TrieSetCell(Trie:handle, const key[], any:value, bool:replace = true);
native TrieSetString(Trie:handle, const key[], const value[], bool:replace = true);
native TrieSetArray(Trie:handle, const key[], const any:buffer[], size, bool:replace = true);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|TrieGetString|bgcolor=white}} {{tt|TrieGetArray|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|size|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=trie_new_size_param|header=Returns the number of bytes written in the buffer.|labelpos=left|content=
<pawn>
/**
* @param size Optional variable to store the number of cells written
* to the array in
*/
native bool:TrieGetString(Trie:handle, const key[], output[], outputsize, &size = 0);
native bool:TrieGetArray(Trie:handle, const key[], any:output[], outputsize, &size = 0);
</pawn>
}}
|}

=== Event ===

''' New natives '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|register_event_ex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=register_event_ex|header=Registers a function to be called on a given game event. A wrapper of {{tt|register_event|bgcolor=whit}} using flags as strings.|labelpos=left|content=
<pawn>
/**
* Registers a function to be called on a given game event.
*
* @note Examples for event conditions:
* "2=c4" - Second parameter of message must be the string "c4"
* "3>10" - Third parameter of message must be greater than 10
* "3!4" - Third parameter of message must not be equal to 4
* "2&Buy" - Second parameter of message must contain "Buy" substring
* "2!Buy" - Second parameter of message must not equal "Buy"
* @note Due to a long-standing bug that would break compatibility with older
* plugins, the client id should be checked for alive/dead state if using
* flags "d" or "e".
* @note If multiple conditions are specified for a single parameter, only one
* of them has to hold true for the event function to be called.
*
* @param event Name of event that should be hooked
* @param function Name of callback function
* @param flags Flags used for filtering events (enum RegisterEventFlags); the valid flags are:
* RegisterEvent_Global - Global event (sent to every client)
* RegisterEvent_Single - Event sent to single client
* RegisterEvent_OnceForMultiple - Call only once when repeated to multiple clients
* RegisterEvent_OnlyDead - Call only if sent to dead client
* RegisterEvent_OnlyAlive - Call only if sent to alive client
* RegisterEvent_OnlyHuman - Call only if sent to human client (RegisterEvent_Single required)
* RegisterEvent_OnlyBots - Call only if sent to bot (RegisterEvent_Single required)
* @param cond Condition string used for filtering events, built as:
* "<argument number><comparison operator><value>"
* Argument number is the argument position to be filtered
* The comparison operator may be:
* "=" for equality comparison (all argument types)
* "!" for inequality comparison (all argument types)
* "&" for bitwise and (int argument) or substring
* comparison (string argument)
* "<" for less than comparison (int/float arguments)
* ">" for greater than comparison (int/float arguments)
* The argument is compared to the specified value accordingly
* @param ... Any number of additional conditions
*
* @return Event handle
* @error If an invalid event name or callback function is provided,
* an error will be thrown.
*/
native register_event_ex(const event[], const function[], RegisterEventFlags:flags, const cond[] = "", ...);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|enable_event|bgcolor=white}} {{tt|disable_event|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=enable_event|header=Enables a function hook of a game event which has been previously registered with {{tt|register_event|bgcolor=white}} or {{tt|register_event_ex|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Enables a function hook of a game event which has been previously registered with register_event and register_event_ex().
*
* @param handle Value returned from register_event() or register_event_ex()
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native enable_event(handle);
</pawn>
}}
{{hidden|id=enable-disable_event|header=Disables a function hook of a game event which has been previously registered with {{tt|register_event|bgcolor=white}} or {{tt|register_event_ex|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Disables a function hook of a game event which has been previously registered with register_event and register_event_ex().
*
* @param handle Value returned from register_event() or register_event_ex()
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native disable_event(handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|enable_logevent|bgcolor=white}} {{tt|disable_logevent|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=enable_logevent|header=Enables a function hook of a game log event which has been previously registered with {{tt|register_logevent|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Enables a function hook of a game log event which has been previously registered with register_logevent().
*
* @param handle Value returned from register_logevent()
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native enable_logevent(handle);
</pawn>
}}
{{hidden|id=enable-disable_logevent|header=Disables a function hook of a game log event which has been previously registered with {{tt|register_logevent|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Disables a function hook of a game log event which has been previously registered with register_logevent().
*
* @param handle Value returned from register_logevent()
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
*/
native disable_logevent(handle);
</pawn>
}}
|}

''' New flags '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | flags
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|register_event|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|"f"|bgcolor=white}} {{tt|"g"|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=register_event_flags|header=Call only if sent to human client ("b" flag required) Call only if sent to bot ("b" flag required).|labelpos=left|content=
<pawn>
/**
* Registers a function to be called on a given game event.
*
* @note Please consider using register_event_ex() instead which allows you to
* use named constants for flags instead of letters.
* @note Examples for event conditions:
* "2=c4" - Second parameter of message must be the string "c4"
* "3>10" - Third parameter of message must be greater than 10
* "3!4" - Third parameter of message must not be equal to 4
* "2&Buy" - Second parameter of message must contain "Buy" substring
* "2!Buy" - Second parameter of message must not equal "Buy"
* @note Due to a long-standing bug that would break compatibility with older
* plugins, the client id should be checked for alive/dead state if using
* flags "d" or "e".
* @note If multiple conditions are specified for a single parameter, only one
* of them has to hold true for the event function to be called.
*
* @param event Name of event that should be hooked
* @param function Name of callback function
* @param flags Flags used for filtering events, the valid flags are:
* "a" - Global event (sent to every client)
* "b" - Event sent to single client
* "c" - Call only once when repeated to multiple clients
* "d" - Call only if sent to dead client
* "e" - Call only if sent to alive client
* "f" - Call only if sent to human client ("b" flag required)
* "g" - Call only if sent to bot ("b" flag required)
* @param cond Condition string used for filtering events, built as:
* "<argument number><comparison operator><value>"
* Argument number is the argument position to be filtered
* The comparison operator may be:
* - "=" for equality comparison (all argument types)
* - "!" for inequality comparison (all argument types)
* - "&" for bitwise and (int argument) or substring
* comparison (string argument)
* - "<" for less than comparison (int/float arguments)
* - ">" for greater than comparison (int/float arguments)
* The argument is compared to the specified value accordingly
* @param ... Any number of additional conditions
*
* @return Event handle
* @error If an invalid event name or callback function is provided,
* an error will be thrown.
*/
native register_event(const event[], const function[], const flags[], const cond[] = "", ...);
</pawn>
}}
|}

=== File ===

'''Valve FileSystems '''

Thanks to the [https://github.com/alliedmodders/hlsdk/blob/master/public/FileSystem.h IFileSystem] interface from HLSDK, we are now able to make more operations possible with files via Valve File System through Valve search paths (example: download directory). 
This is handy when you want to deal with files which are not necessary existing directly in the game directory.

Not all natives are concerned. This features some new natives and enhanced others existing ones with small quality of life changes.

''' Valve Paths '''

{| class=wikitable
! style="padding: 0.4em;" | Path ID
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|GAME|bgcolor=white}}
| style="padding: 0.4em;" | All paths related to current mod, including fallback. Depending settings, it includes: {{tt|<gamedir>_lv|bgcolor=none}}/{{tt|_addon|bgcolor=none}}/{{tt|_language|bgcolor=none}}/{{tt|_hd|bgcolor=none}} and {{tt|<gamedir>|bgcolor=none}} itself.
|-
| style="padding: 0.4em;" | {{tt|GAMECONFIG|bgcolor=white}}
| style="padding: 0.4em;" | The default writable directory: {{tt|<gamedir>|bgcolor=none}}.
|-
| style="padding: 0.4em;" | {{tt|GAMEDOWNLOAD|bgcolor=white}}
| style="padding: 0.4em;" | The download directory: {{tt|<gamedir>_download|bgcolor=none}}.
|-
| style="padding: 0.4em;" | {{tt|GAME_FALLBACK|bgcolor=white}}
| style="padding: 0.4em;" | All paths related to fallback game, same as {{tt|GAME|bgcolor=none}} (example: {{tt|czero|bgcolor=none}} has {{tt|cstrike|bgcolor=none}} as fallback. Others mods have usually the default game {{tt|valve|bgcolor=none}}, including {{tt|cstrike|bgcolor=none}}).
|-
| style="padding: 0.4em;" | {{tt|DEFAULTGAME|bgcolor=white}}
| style="padding: 0.4em;" | All paths related to the default game which is ''valve'', same as {{tt|GAME|bgcolor=none}}.
|-
| style="padding: 0.4em;" | {{tt|BASE|bgcolor=white}}
| style="padding: 0.4em;" | The base path where server is installed.
|}

''' Native Support '''

Some natives supports partially Valve FS, where a path ID can't be provided and this will search in all paths instead.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|delete_file|bgcolor=white}} {{tt|unlink|bgcolor=white}} {{tt|file_exists|bgcolor=white}} ''partially'' {{tt|dir_exists|bgcolor=white}} ''partially'' {{tt|file_size|bgcolor=white}} {{tt|fopen|bgcolor=white}} {{tt|mkdir|bgcolor=white}} {{tt|open_dir|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|use_valve_fs|bgcolor=white}} {{tt|valve_path_id|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=native_fs|header=Uses the Valve file system via a search path from gameinfo.|labelpos=left|content=
<pawn>
/**
* @note Registered paths ID are (in priority order) :
* GAME All paths related to current mod, including fallback
* Depending settings, it includes: <gamedir>_lv/_addon/_<language>/_hd
* and <gamedir> itself
* GAMECONFIG The default writable directory (<gamedir>)
* GAMEDOWNLOAD The download directory (<gamedir>_download)
* GAME_FALLBACK All paths related to fallback game, same as GAME
* DEFAULTGAME All paths related to the default game which is "valve", same as GAME
* BASE The base path where server is installed
*
* Note that some paths are non-writable. It includes all <gamedir>_* (expect _download)
* and DEFAULTGAME. Any file inside a non-writable path will be ignored if you try to open
* it in writing mode.
*
* @param use_valve_fs If true, the Valve file system will be used instead
* This can be used to finred files existing in valve
* search paths, rather than solely files existing directly
* in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
*/
</pawn>
}}
|}

Some natives are not adjusted because not exposed by Valve FS:
* {{tt|rename_file}}
* {{tt|rmdir}}

''' New Natives '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|FileReadInt8|bgcolor=white}} {{tt|FileReadUint8|bgcolor=white}} {{tt|FileReadInt16|bgcolor=white}} {{tt|FileReadUint16|bgcolor=white}} {{tt|FileReadInt32|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=FileRead|header=Reads a single value from a file. More sane and better designed natives to read a single value (proper type, unsigned byte/short support and returns 1 or 0).|labelpos=left|content=
<pawn>
/**
* Reads a single int8 (byte) from a file. The returned value is sign-
* extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt8(file, &any:data);

/**
* Reads a single uint8 (unsigned byte) from a file. The returned value is
* zero-extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadUint8(file, &any:data);

/**
* Reads a single int16 (short) from a file. The value is sign-extended to
* an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt16(file, &any:data);

/**
* Reads a single unt16 (unsigned short) from a file. The value is zero-
* extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadUint16(file, &any:data);

/**
* Reads a single int32 (int/cell) from a file.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt32(file, &any:data);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|FileWriteInt8|bgcolor=white}} {{tt|FileWriteInt16|bgcolor=white}} {{tt|FileWriteInt32|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=FileWrite|header=Writes a single value from a file. More sane and better designed natives to write a single value (proper type, unsigned byte/short support and returns 1 or 0).|labelpos=left|content=
<pawn>
/**
* Writes a single int8 (byte) to a file.
*
* @param file Handle to the file
* @param data Data to write (truncated to an int8)
*
* @return True on success, false on failure
*/
native bool:FileWriteInt8(file, any:data);

/**
* Writes a single int16 (short) to a file.
*
* @param file Handle to the file
* @param data Data to write (truncated to an int16)
*
* @return True on success, false on failure
*/
native bool:FileWriteInt16(file, any:data);

/**
* Writes a single int32 (int/cell) to a file.
*
* @param file Handle to the file
* @param data Data to write
*
* @return True on success, false on failure
*/
native bool:FileWriteInt32(file, any:data);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|GetFileTime|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GetFileTime|header=Returns a file timestamp as a unix timestamp. |labelpos=left|content=
<pawn>
/**
* File time modes for use with GetFileTime().
*/
enum FileTimeType
{
FileTime_LastAccess, /* Last access (not available on FAT) */
FileTime_Created, /* Creation (not available on FAT) */
FileTime_LastChange, /* Last modification */
};

/**
* Returns a file timestamp as a unix timestamp.
*
* @param file File name
* @param tmode Time mode, see FileTime_* constants
*
* @return Returns a file timestamp as a unix timestamp
*/
native GetFileTime(const file[], FileTimeType:tmode);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SetFilePermissions|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SetFilePermissions|header=Changes a file or directories permissions.|labelpos=left|content=
<pawn>
/**
* Changes a file or directories permissions.
*
* @param path Path to the file
* @param mode Permissions to set, see FPERM_* constants
*
* @return True on success, false otherwise
*/
native bool:SetFilePermissions(const path[], mode);
</pawn>
}}
|}

'''New params'''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|fputs|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|null_term|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=fputs|header=True to append NULL terminator, false otherwise.|labelpos=left|content=
<pawn>
/**
* Writes a line of text to a text file.
*
* @param file Handle to the file
* @param text String to write
* @param null_term True to append NULL terminator, false otherwise
*
* @return 0 on success, -1 otherwise
*/
native fputs(file, const text[], bool:null_term = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|mkdir|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|mode |bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=mkdir|header=Permissions (default is o=rx,g=rx,u=rwx). Note that folders must have the execute bit set on Linux. On Windows, the mode is ignored.|labelpos=left|content=
<pawn>
/**
* Creates a directory.
*
* @param path Path to create
* @param mode Permissions (default is o=rx,g=rx,u=rwx). Note that folders must have
* the execute bit set on Linux. On Windows, the mode is ignored.
* @param use_valve_fs If true, the Valve file system will be used instead
* This can be used to create folders in the game's
* Valve search paths, rather than directly in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for default
* In this case, mode is ignored
*
* @return 0 on success, -1 otherwise
*/
native mkdir(const dirname[], mode = FPERM_DIR_DEFAULT, bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|open_dir|bgcolor=white}} {{tt|next_file|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|type|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=open_dir-next_file|header=Optional variable to store the file type.|labelpos=left|content=
<pawn>
/**
* Opens a directory/folder for contents enumeration.
*
* @note Directories are closed with close_dir().
*
* @param dir Path to open.
* @param firstfile String buffer to hold first file name
* @param length Maximum size of the string buffer
* @param type Optional variable to store the file type
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to find files existing in any of
* the Valve search paths, rather than solely files
* existing directly in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths.
*
* @return Handle to the directory, 0 otherwise
*/
native open_dir(dir[], firstfile[], length, &FileType:type = FileType_Unknown, bool:use_valve_fs = false, const valve_path_id[] = "GAME");

/**
* Reads the next directory entry as a local filename.
*
* @note Contents of buffers are undefined when returning false.
* @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
*
* @param dirh Handle to a directory
* @param buffer String buffer to hold directory name
* @param length Maximum size of string buffer
* @param type Optional variable to store the file type. FileType_* constants
*
* @return 1 on success, 0 if there are no more files to read.
*/
native next_file(dirh, buffer[], length, &FileType:type = FileType_Unknown);
</pawn>
}}
|}

''' Others '''

There are as well some minor additions or changes:

* Added a new define {{tt|PLATFORM_MAX_PATH}} {{hidden|id=platform_max_path|labelonly=yes}} to represent a maximum path length.
{{hidden|id=platform_max_path|contentonly=yes|content=
<pawn>
/**
* Maximum path length.
*/
#define PLATFORM_MAX_PATH 256
</pawn>
}}
* Added {{tt|any:}} tag to some natives.
* {{tt|read_dir}}: {{tt|outlen|bgcolor=none}} parameter is now optional.
* {{tt|read_file}}: {{tt|txtlen|bgcolor=none}} parameter is now optional. Adjusted as well buffer to 2048 to match buffer size in {{tt|write_file|bgcolor=none}}.
* {{tt|file_size}}: Fixed potential issue with old compiled plugin which doesn't have the flag parameter. Added {{tt|FSOPT_*|bgcolor=none}} {{hidden|id=fsopt_constants|labelonly=yes}} constants as well for use with this flag parameter.
{{hidden|id=fsopt_constants|contentonly=yes|content=
<pawn>
/**
* Options for use with file_size() flag parameter.
*/
#define FSOPT_BYTES_COUNT 0 /* Returns the file size in number of bytes */
#define FSOPT_LINES_COUNT 1 /* Returns how many lines there are in this file */
#define FSOPT_END_WITH_LF 2 /* Returns whether the last line is '\n' */
</pawn>
}}

=== General ===

''' Constant '''

* Added {{tt|DMG_GRENADE}} constant (Counter-Strike only)
* Added missing {{tt|SVC_}} messages ({{pr|amxx|223}})
** {{tt|SVC_RESOURCELOCATION}}
** {{tt|SVC_SENDCVARVALUE}}
** {{tt|SVC_SENDCVARVALUE2}}

''' Forward '''

* Added {{tt|FP_VAL_BYREF}} to pass values by reference in forwards.
* {{tt|ExecuteForward}} can now be called without the need to create variable for returned value.

''' Others '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|has_map_ent_class|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=has_map_ent_class|header=Returns if a map contains at least one entity with the provided class name.|labelpos=left|content=
<pawn>
/**
* Returns if a map contains at least one entity with the provided class name.
*
* @param classname Entity classname to match
*
* @return True if an entity is found, false otherwise
*/
native bool:has_map_ent_class(const classname[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|engine_changelevel|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=engine_changelevel|header=Changes the map.

{{alert|info|Note:|This has the same behavior as using the "changelevel" server command, but will also trigger the {{tt|server_changelevel|bgcolor=white}} forward in AMXX plugins. 
It will also notify any Metamod plugins that are hooking the {{tt|pfnChangeLevel|bgcolor=white}} function.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Changes the map.
*
* @note This calls the pfnChangelLevel engine function.
* @note This has the same behavior as using the "changelevel" server command,
* but will also trigger the server_changelevel() forward in AMXX
* plugins. It will also notify any Metamod plugins that are hooking
* the pfnChangeLevel function.
*
* @param map Map name to change to
*
* @noreturn
*/
native engine_changelevel(const map[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|RequestFrame|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=RequestFrame|header=Creates a single use hook for the next frame.|labelpos=left|content=
<pawn>
/**
* Creates a single use hook for the next frame.
*
* @param callback Function to be executed on the next frame.
* @param data Optional data to be passed to the callback function.
*
* @note Callback function prototype:
* public function(data)
*
* @noreturn
*/
native RequestFrame(const callback[], any:data = 0);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|set_task_ex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=set_task_ex|header=Calls a function after a specified time has elapsed.

{{alert|info|Note:|Similar to {{tt|set_task|bgcolor=white}} but it allows you to use named constants for flags instead of letters.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* SetTaskFlags constants for set_task_ex()
*/
enum SetTaskFlags (<<= 1)
{
SetTask_Once = 0, // None; execute callback after the specified amount of time (Default)
SetTask_RepeatTimes = 1, // Repeat timer a set amount of times
SetTask_Repeat, // Loop indefinitely until timer is stopped
SetTask_AfterMapStart, // Time interval is treated as absolute time after map start
SetTask_BeforeMapChange // Time interval is treated as absolute time before map change
};

/**
* Calls a function after a specified time has elapsed.
*
* @param time Time interval to assign
* @param function Function to execute
* @param id Task id to assign
* @param parameter Data to pass through to callback
* @param len Size of data
* @param flags Optional flags (enum SetTaskFlags); valid flags are:
* SetTask_Once - Execute callback once (Default)
* SetTask_RepeatTimes - repeat timer a set amount of times
* SetTask_Repeat - loop indefinitely until timer is stopped
* SetTask_AfterMapStart - time interval is treated as absolute
* time after map start
* SetTask_BeforeMapChange - time interval is treated as absolute
* time before map change
* @param repeat If the SetTask_RepeatTimes flag is set, the task will be repeated this
* many times
*
* @noreturn
* @error If an invalid callback function is provided, an error is
* thrown.
*/
stock set_task_ex(Float:time, const function[], id = 0, const any:parameter[] = "", len = 0, SetTaskFlags:flags = SetTask_Once, repeat = 0)
{
new strFlags[2]; // There should never be a need to set more than 1 flag
get_flags(_:flags, strFlags, charsmax(strFlags));
set_task(time, function, id, parameter, len, strFlags, repeat);
}
</pawn>
}}
|}

''' XS '''

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|xs_vec_len_2d|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=xs_vec_len_2d|header=Computes the length of a 2D vector.|labelpos=left|content=
<pawn>
/**
* Computes the length of a 2D vector.
*
* @param vec The vector to compute the length of.
*
* @return The length of the input vector.
*/
stock Float:xs_vec_len_2d(const Float:vec[])
{
return xs_sqrt(vec[0]*vec[0] + vec[1]*vec[1]);
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|xs_vec_distance|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=xs_vec_distance|header=Computes the distance between two vectors (points).|labelpos=left|content=
<pawn>
/**
* Computes the distance between two vectors (points).
*
* @param vec1 First vector.
* @param vec2 Second vector.
*
* @return The distance between two vectors.
*/
stock Float:xs_vec_distance(const Float:vec1[], const Float:vec2[])
{
return xs_sqrt((vec1[0]-vec2[0]) * (vec1[0]-vec2[0]) +
(vec1[1]-vec2[1]) * (vec1[1]-vec2[1]) +
(vec1[2]-vec2[2]) * (vec1[2]-vec2[2]));
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|xs_vec_distance_2d|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=xs_vec_distance_2d|header=Computes the distance between two 2D vectors (points).|labelpos=left|content=
<pawn>
/**
* Computes the distance between two 2D vectors (points).
*
* @param vec1 First vector.
* @param vec2 Second vector.
*
* @return The distance between two vectors.
*/
stock Float:xs_vec_distance_2d(const Float:vec1[], const Float:vec2[])
{
return xs_sqrt((vec1[0]-vec2[0]) * (vec1[0]-vec2[0]) +
(vec1[1]-vec2[1]) * (vec1[1]-vec2[1]));
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|xs_vec_add_scaled|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=xs_vec_add_scaled|header=Adds the second vector scaled by a scalar to the first.|labelpos=left|content=
<pawn>
/**
* Adds the second vector scaled by a scalar to the first.
*
* @param in1 Vector to add to.
* @param in2 Vector to scale and add.
* @param scalar Scalar to scale the second vector with.
* @param out The output vector. Can be one of the input vectors.
*
* @noreturn
*/
stock xs_vec_add_scaled(const Float:in1[], const Float:in2[], Float:scalar, Float:out[])
{
out[0] = in1[0] + in2[0] * scalar;
out[1] = in1[1] + in2[1] * scalar;
out[2] = in1[2] + in2[2] * scalar;
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|xs_vec_sub_scaled|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=xs_vec_sub_scaled|header=Subtracts the second vector scaled by a scalar from the first one.|labelpos=left|content=
<pawn>
/**
* Subtracts the second vector scaled by a scalar from the first one.
*
* @param in1 Vector to subtract from.
* @param in2 Vector to scale and subtract.
* @param scalar Scalar to scale the second vector with.
* @param out The output vector. Can be one of the input vectors.
*
* @noreturn
*/
stock xs_vec_sub_scaled(const Float:in1[], const Float:in2[], Float:scalar, Float:out[])
{
out[0] = in1[0] - in2[0] * scalar;
out[1] = in1[1] - in2[1] * scalar;
out[2] = in1[2] - in2[2] * scalar;
}
</pawn>
}}
|}

=== Menu ===

''' Timeout '''

Timeout is now added to newmenus, working similar to those of {{tt|show_menu}}. 

When a menu is acted upon after the specified timeout has run out it will pass a new {{tt|MENU_TIMEOUT}} status code into the menu handler. 
Actions are:
* player disconnect
* selecting an item,
* cancelling/destroying the menu in the plugin,
* sending a different menu or using {{tt|get_user_menu}} on a player with an open menu.

Just like with the old menus timeouts are not actively polled, and {{tt|MENU_TIMEOUT}} is not guaranteed to fire directly after the time has run out. 
Also {{tt|get_user_menu}} will detect timeouts and reset the menu flags, which is why it also has to trigger the callback.

{{alert|info|Note:|An example is available at {{pr|amxx|21}}.|opt=full-border}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|menu_display|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|time|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=menu_display|header=If >=0 menu will timeout after this many seconds.|labelpos=left|content=
<pawn>
/**
* Displays a menu to one client. This should never be called from a handler
* when the item is less than 0 (i.e. calling this from a cancelled menu will
* result in an error).
*
* Starting with 1.8.3 this allows to specify a menu timeout similar to the
* show_menu native. If the menu exists on the client past the timeout *any*
* further action will send the MENU_TIMEOUT status code to the menu handler.
* That includes actions which would otherwise send MENU_EXIT, such as the
* client selecting an item or disconnecting and calling menu_cancel or
* menu_destroy on a live menu.
*
* @param id Client index.
* @param menu Menu resource identifier.
* @param page Page to start from (starting from 0).
* @param time If >=0 menu will timeout after this many seconds
* @noreturn
* @error Invalid menu resource or client index.
*/
native menu_display(id, menu, page=0, time=-1);
</pawn>
}}
|}

''' New native & stock '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|menu_addblank2|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=menu_addblank2|header=Adds a blank line to a menu, always shifting the numbering down. 

{{alert|info|Note:|This fixes an unexpected behavior with the original ones when slot param is set to 1|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Adds a blank line to a menu, always shifting the numbering down.
*
* This will add a special item to create a blank line. It will affect the menu
* item count and pagination. These items can be modified later but will ignore
* access and item callback results.
*
* Only available in 1.8.3 and above.
*
* @param menu Menu resource identifier.
*
* @return 1 on success, 0 on failure.
* @error Invalid menu resource.
* Too many items on non-paginated menu (max is 10)
*/
native menu_addblank2( menu );
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|reset_menu|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=reset_menu|header=Resets the client's menu.
|labelpos=left|content=
<pawn>
/**
* Resets the client's menu.
*
* @note This is a wrapper around show_menu() for the sake of readability.
*
* @param index Client to reset menu of, 0 to reset all clients
*
* @noreturn
*/
stock reset_menu(index)
{
show_menu(index, 0, "", 0);
}
</pawn>
}}
|}

''' New properties '''

{| class=wikitable
! style="padding: 0.4em;" | Property
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|MEXIT_FORCE|bgcolor=white}}
| style="padding: 0.4em;" | Forces a proper exit button on unpaginated menus
|-
| style="padding: 0.4em;" | {{tt|MPROP_SHOWPAGE|bgcolor=white}}
| style="padding: 0.4em;" | Whether to show the page number in menu title
|-
| style="padding: 0.4em;" | {{tt|MEXIT_FORCE|bgcolor=white}}
| style="padding: 0.4em;" | Function to be called on Back and Next

Prototype of callback:
<pawn>
Called when parsing is halted.

@param id Playeer's index
@param status Either MENU_BACK or MENU_MORE

public function(id, status);
</pawn>
{{alert|info|Note:|An example is available in the {{tt|testsuite}} directory, see [https://github.com/alliedmodders/amxmodx/blob/master/plugins/testsuite/menu_page_callback_test.sma menu_page_callback_test.sma].|opt=full-border}}
|}

''' Others '''

* {{tt|menu_item_getinfo}}'s arguments are now optional
* {{tt|show_menu]}} native is allowed to send empty text

=== Message ===

''' New natives '''

The float version of {{tt|message_begin}}, {{tt|write_angle}}, {{tt|write_coord_f}}, {{tt|emessage_begin}}, {{tt|ewrite_coord}} and {{tt|ewrite_angle}}:

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|message_begin_f|bgcolor=white}} {{tt|write_angle_f|bgcolor=white}} {{tt|write_coord_f|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=message_begin_f|header=Marks the beginning of a client message.|labelpos=left|content=
<pawn>
/**
* Marks the beginning of a client message.
*
* @note You may generate menus, smoke, shockwaves, thunderlights,
* intermission and many other messages.
* @note For a list of HL game events, visit https://wiki.alliedmods.net/Half-Life_1_Game_Events
* @note For a list of HL engine messages, visit https://wiki.alliedmods.net/Half-Life_1_Engine_Messages
* @note You may also refer to the messages_const.inc file for examples.
* @note This function is the same as message_begin(), but the origin
* argument accepts only float values in this one.
* @note Each message starts with a message_begin() or message_begin_f() function
* and ends with message_end(). The specific message arguments go in between
* these two by using the write_*() functions found in messages.inc.
*
* @param dest Destination type (see MSG_* constants in messages_const.inc)
* @param msg_type Message id
* @param origin Message origin
* @param player Client index receiving the message or 0 for all clients
*
* @noreturn
* @error If an invalid message id is specified or an invalid number
* of parameters is passed, an error will be thrown.
*/
native message_begin_f(dest, msg_type, const Float:origin[3] = {0.0,0.0,0.0}, player = 0);
</pawn>
}}
{{hidden|id=write_angle_f|header=Writes an angle entry to a message using a float value.|labelpos=left|content=
<pawn>
/**
* Writes an angle entry to a message using a float value.
*
* @note This function should only be used in between a message_begin()
* or message_begin_f() and a message_end() function. Trying to use
* it outside of these functions will crash the server immediately.
*
* @param x Angle to write
*
* @noreturn
*/
native write_angle_f(Float:x);
</pawn>
}}
{{hidden|id=write_coord_f|header=Writes a coordinate entry to a message using a float value.|labelpos=left|content=
<pawn>
/**
* Writes a coordinate entry to a message using a float value.
*
* @note This function should only be used in between a message_begin()
* or message_begin_f() and a message_end() function. Trying to use
* it outside of these functions will crash the server immediately.
*
* @param x Coordinate to write
*
* @noreturn
*/
native write_coord_f(Float:x);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|zmessage_begin_f|bgcolor=white}} {{tt|ewrite_coord_f|bgcolor=white}} {{tt|ewrite_angle_f|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=emessage_begin_f|header=Marks the beginning of a client message.|labelpos=left|content=
/**
* Marks the beginning of a client message.
*
* @note You may generate menus, smoke, shockwaves, thunderlights,
* intermission and many other messages.
* @note For a list of HL game events, visit https://wiki.alliedmods.net/Half-Life_1_Game_Events
* @note For a list of HL engine messages, visit https://wiki.alliedmods.net/Half-Life_1_Engine_Messages
* @note You may also refer to the messages_const.inc file for examples.
* @note This function is the same as message_begin_f(), except that the messages
* sent with this one are also sent to all other AMXX and Metamod plugins.
* This means that if you send one of these messages, other plugins will
* be notified of that message, which was previously impossible.
* @note BE CAREFUL! Using this incorrectly, or not for its intended purpose,
* could cause infinite recursion or something just as bad!
* @note This function is the same as emessage_begin(), but the origin
* argument accepts only float values in this one.
* @note Each message starts with a emessage_begin() or emessage_begin_f() function
* and ends with emessage_end(). The specific message arguments go in between
* these two by using the ewrite_*() functions found in messages.inc.
*
* @param dest Destination type (see MSG_* constants in messages_const.inc)
* @param msg_type Message id
* @param origin Message origin
* @param player Client index receiving the message or 0 for all clients
*
* @noreturn
* @error If an invalid message id is specified or an invalid number
* of parameters is passed, an error will be thrown.
*/
native emessage_begin_f(dest, msg_type, const Float:origin[3] = {0.0,0.0,0.0}, player = 0);
</pawn>
}}
{{hidden|id=ewrite_coord_f|header=Writes a coordinate entry to a message using a float value.|labelpos=left|content=
<pawn>
/**
* Writes a coordinate entry to a message using a float value.
*
* @note This function should only be used in between a emessage_begin()
* or emessage_begin_f() and a emessage_end() function. Trying to use
* it outside of these functions will crash the server immediately.
*
* @param x Coordinate to write
*
* @noreturn
*/
native ewrite_coord_f(Float:x);
</pawn>
}}
{{hidden|id=ewrite_angle_f|header=Writes an angle entry to a message using a float value.|labelpos=left|content=
<pawn>
/**
* Writes an angle entry to a message using a float value.
*
* @note This function should only be used in between a emessage_begin()
* or emessage_begin_f() and a emessage_end() function. Trying to use
* it outside of these functions will crash the server immediately.
*
* @param x Angle to write
*
* @noreturn
*/
native ewrite_angle_f(Float:x);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|client_print_color|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_print_color|header=Sends colored chat messages to clients.
{{alert|info|Note:|Counter-strike only.|opt=full-border}}|labelpos=left|content=
<pawn>
/**
* Sends colored chat messages to clients.
*
* @note This only works in Counter-Strike 1.6 and Condition Zero.
* @note The colors can be modified inside of the format string using special
* characters. These characters can be included using the escape character
* green x04 ; use location color from this point forward
* red/blue/grey x03 ; use team color from this point forward
* red/blue/grey x02 ; use team color to the end of the client name
* ; This only works at the start of the string,
* ; and precludes using other control characters
* default x01 ; use default color from this point forward
* @note The team color is defined by the sender's index. Alternatively, a
* specific team color can be enforced using the print_team_* constants in
* amxconst.inc
* @note Usage examples:
* client_print_color(id, print_team_red, "^4Green ^3Red ^1Default")
* client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default")
* @note Including colors in ML can be done using the same escaping method:
* EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default
* @note This functions return value behaves differently depending on what is
* used as the client index: If 0 is specified, then the function will
* return 0 if nothing has been sent (no client connected). If either a
* single client is specified, or there is at least one client connected,
* the number of printed characters will refer to the message that is sent
* last, to the client with the highest index.
*
* @param index Client index, use 0 to display to all clients
* @param sender Client index used as the message sender
* @param fmt Formatting rules
* @param ... Variable number of formatting parameters
*
* @return Number of printed characters
* @error If a single client is specified and the index is not within
* the range of 1 to MaxClients, an error will be thrown.
*/
native client_print_color(index, sender, const message[], any:...);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|set_dhudmessage|bgcolor=white}} {{tt|show_dhudmessage|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=set_dhudmessage|header= Sets display parameters for director hudmessages.|labelpos=left|content=
<pawn>
/**
* Sets display parameters for director hudmessages.
*
* @note For the hudmessage coordinates x and y, -1.0 will center the message
* on the respective axis.
* @note These parameters stay until the next call to set_dhudmessage overwrites
* them. Multiple calls to show_dhudmessage will therefore re-use the same
* parameters. The parameters are not stored per-plugin, so other plugins
* can overwrite them.
*
* @param red Red component of hudmessage color
* @param green Green component of hudmessage color
* @param blue Blue component of hudmessage color
* @param x Location of the message on the x axis in percent
* @param y Location of the message on the y axis in percent
* @param effects Display effect
* @param fxtime Duration of the effect
* @param holdtime Time the message stays on screen
* @param fadeintime Time it takes the message to fully appear (fade-in)
* @param fadeouttime Time it takes the message to fully disappear (fade-out)
*
* @noreturn
*/
native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y = 0.35, effects = 0, Float:fxtime = 6.0, Float:holdtime = 12.0, Float:fadeintime = 0.1, Float:fadeouttime = 0.2);
</pawn>
}}
{{hidden|id=show_dhudmessage|header=Displays a director message on the client HUD.|labelpos=left|content=
<pawn>
/**
* Displays a director message on the client HUD.
*
* @note Use set_dhudmessage to define how the message should look on screen.
* @note Unlike the classic HUD message, which is channel-based, director
* messages are stack-based. You can have up to 8 messages displaying at
* once. If more are added, they will be overwritten in the order they were
* sent. There is no way to clear a specific message.
* @note The message has a maximum length of 128 characters which this function
* will automatically enforce.
* @note This functions return value behaves differently depending on what is
* used as the client index: If 0 is specified, then the function will
* return 0 if nothing has been sent (no client connected). If either a
* single client is specified, or there is at least one client connected,
* the number of printed characters will refer to the message that is sent
* last, to the client with the highest index.
*
* @param index Client index, use 0 to display to all clients
* @param message Formatting rules
* @param ... Variable number of formatting parameters
*
* @return Number of printed characters
* @error If a single client is specified and the index is not within
* the range of 1 to MaxClients, an error will be thrown.
*/
native show_dhudmessage(index, const message[], any:...);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|elog_message|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=elog_message|header=Logs a message hookable by plugins to the current server log file.|labelpos=left|content=
<pawn>
/**
* Logs a message hookable by plugins to the current server log file.
*
* @note The log will include a timestamp with the message.
* @note The message can be hooked using "register_logevent".
*
* @param string Formatting rules
* @param ... Variable number of formatting parameters
*
* @return Number of printed characters
*/
native elog_message(const message[], any:...);</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|client_printex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_printex|header=Sends a predefined text message to player.|labelpos=left|content=
<pawn>
/**
* Sends a predefined text message to player.
* Predefined texts are default game messages which will be translated
* to player's game language, e.g. #Game_join_ct.
*
* @note Set index to 0 to send text globally.
*
* @note There does not necessarily have to be a total of 6 arguments.
* It will depend if message takes arguments, e.g.:
* client_printex(id, print_chat, "#Game_join_ct", "Pimp Daddy")
* client_printex(id, print_chat, "1", "#Game_radio", "Pimp Daddy", "Hello world!")
*
* @param index Index of the player, use 0 to send to all players.
* @param type The message destination. See print_* constants.
* @param msg_name The custom or predefined message to send.
* @param msg_param1 Optional message argument.
* @param msg_param2 Optional message argument.
* @param msg_param3 Optional message argument.
* @param msg_param4 Optional message argument.
*
* @noreturn
*/
stock client_printex(index, type, const msg_name[], const msg_param1[] = "", const msg_param2[] = "", const msg_param3[] = "", const msg_param4[] = "")
{
new ch = msg_name[0];

// If not a predefined message, we don't care about it and forward directly to client_print.
// Special case for radio message. msg_name is an index, msg_param1 #Game_radio*, etc. Checking index should be enough.
if (ch != '#' && (type != print_radio || !strtol(msg_name)))
{
return client_print(index, type, msg_name, msg_param1, msg_param2, msg_param3, msg_param4);
}

// Even if message starts with '#', we should check its length for safety.
new length = strlen(msg_name);

// If string is larger than expected, we forward to client_print which will cut message properly.
// This means also this can't be a predefined game message.
// Max console length: 128 = \n (126) + \0 (127)
// Max SayText length: 192 = \n (190) + \0 (191)
if ((length > 126 && (print_notify <= type <= print_console))
|| ( length > 190 && (print_chat <= type <= print_radio)))
{
return client_print(index, type, msg_name, msg_param1, msg_param2, msg_param3, msg_param4);
}

static msgTextMsg;
if (!msgTextMsg)
{
msgTextMsg = get_user_msgid("TextMsg");
}

message_begin(index > 0 ? MSG_ONE_UNRELIABLE : MSG_BROADCAST, msgTextMsg, {0,0,0}, index);
write_byte(type);
write_string(msg_name);
if (msg_param1[0]) { write_string(msg_param1); }
if (msg_param2[0]) { write_string(msg_param2); }
if (msg_param3[0]) { write_string(msg_param3); }
if (msg_param4[0]) { write_string(msg_param4); }
message_end();

return 1;
}
</pawn>
}}
|}

''' Others '''

* Added {{tt|MSG_INIT}} support in {{tt|message_begin}} native
* Set {{tt|set_hudmessage}} default channel to {{tt|-1}} to reflect auto-channeling support

=== String ===

* Constants and stocks from {{tt|string.inc}} have been moved in their own files {{tt|string_const.inc}} and {{tt|string_stocks.inc}}.
* {{tt|strlen}} has been moved from {{tt|core.inc}} to {{tt|string.inc}}.
* {{tt|strbreak}} is now replaced by a backwards compatibility stock.

''' Conversion '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|strtol|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=strtol|header=Parses the {{tt|string|bgcolor=white}} interpreting its content as an integral number of the specified {{tt|base|bgcolor=white}}, which is returned as integer value. The function also sets the value of {{tt|endPos|bgcolor=white}} to point to the position of the first character after the number.|labelpos=left|content=
<pawn>
/**
* Parses the 'string' interpreting its content as an integral number of the specified 'base',
* which is returned as integer value. The function also sets the value of 'endPos' to point
* to the position of the first character after the number.
*
* This is the same as C++ strtol function with a difference on second param.
*
* The function first discards as many whitespace characters as necessary until the first
* non-whitespace character is found. Then, starting from this character, takes as many
* characters as possible that are valid following a syntax that depends on the 'base' parameter,
* and interprets them as a numerical value. Finally, a position of the first character following
* the integer representation in 'string' is stored in 'endPos'.
*
* If the value of 'base' is zero, the syntax expected is similar to that of integer constants,
* which is formed by a succession of :
* An optional sign character (+ or -)
* An optional prefix indicating octal or hexadecimal base ("0" or "0x"/"0X" respectively)
* A sequence of decimal digits (if no base prefix was specified) or either octal or hexadecimal digits if a specific prefix is present
*
* If the 'base' value is between 2 and 36, the format expected for the integral number is a succession
* of any of the valid digits and/or letters needed to represent integers of the specified radix
* (starting from '0' and up to 'z'/'Z' for radix 36). The sequence may optionally be preceded by
* a sign (either + or -) and, if base is 16, an optional "0x" or "0X" prefix.
*
* If the first sequence of non-whitespace characters in 'string' is not a valid integral number
* as defined above, or if no such sequence exists because either 'string' is empty or it contains
* only whitespace characters, no conversion is performed.
*
* @param string The string to parse.
* @param endPos The position of the first character following the number.
* On success and when containing only numbers, position is at the end of string, meaning equal to 'string' length.
* On failure, position is sets always to 0.
* @param base The numerical base (radix) that determines the valid characters and their interpretation.
* If this is 0, the base used is determined by the format in the sequence.
* @return On success, the function returns the converted integral number as integer value.
* If no valid conversion could be performed, a zero value is returned.
* If the value read is out of the range of representable values by a cell,
* the function returns 'cellmin' or 'cellmax'.
*/
native strtol(const string[], &endPos = 0, base = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|strtof|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=strtof|header=Parses the {{tt|string|bgcolor=white}} interpreting its content as an floating point number and returns its value as a float. The function also sets the value of {{tt|endPos|bgcolor=white}} to point to the position of the first character after the number.|labelpos=left|content=
<pawn>
/**
* Parses the 'string' interpreting its content as an floating point number and returns its value as a float.
* The function also sets the value of 'endPos' to point to the position of the first character after the number.
*
* This is the same as C++ strtod function with a difference on second param.
*
* The function first discards as many whitespace characters as necessary until the first
* non-whitespace character is found. Then, starting from this character, takes as many
* characters as possible that are valid and interprets them as a numerical value.
* Finally, a position of the first character following the float representation in 'string'
* is stored in 'endPos'.
*
* If the first sequence of non-whitespace characters in 'string' is not a valid float number
* as defined above, or if no such sequence exists because either 'string' is empty or it contains
* only whitespace characters, no conversion is performed.
*
* @param string The string to parse.
* @param endPos The position of the first character following the number.
* On success and when containing only numbers, position is at the end of string, meaning equal to 'string' length.
* On failure, position is sets always to 0.
* @return On success, the function returns the converted floating point number as float value.
* If no valid conversion could be performed, a zero value is returned.
*/
native Float:strtof(const string[], &endPos = 0);
</pawn>
}}
|}

''' Format specifier '''

{| class=wikitable
! style="padding: 0.4em;" | Specifier
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|%b|bgcolor=white}}
| style="padding: 0.4em;" | Binary digits in the value
|-
| style="padding: 0.4em;" | {{tt|%n|bgcolor=white}}
| style="padding: 0.4em;" | Requires a client index. Expands to a string containing the player's name. If the client index is 0, the string will be: {{tt|Console}}
|-
| style="padding: 0.4em;" | {{tt|%N|bgcolor=white}}
| style="padding: 0.4em;" | Requires a client index. Expands to {{tt|1<2><3><4>}} where {{tt|1}} is the player's name, {{tt|2}} is the player's userid, {{tt|3}} is the player's SteamID, and {{tt|4}} the player's team name. If the client index is 0, the string will be: {{tt|Console<0><Console><Console>}}
|-
| style="padding: 0.4em;" | {{tt|%l|bgcolor=white}}
| style="padding: 0.4em;" | Translates a phrase from a key. Similar to {{tt|%L}} with the difference it will use the client's index set internally by the function. This is only allowed in functions which act directly on one or more clients.

{{alert|info|Note:|To complement this, a new {{hidden|id=SetGlobalTransTarget|labelonly=yes}} {{tt|SetGlobalTransTarget|bgcolor=white}} native to set the current index has been added. 
This is useful to be used before with natives which are not player-oriented", like a bunch of {{tt|formatex|bgcolor=whitet}}.|opt=full-border}}
{{hidden|id=SetGlobalTransTarget|contentonly=yes|content=
<pawn>
/**
* Sets the global language target.
*
* @note This is useful for creating functions
* that will be compatible with the %l format specifier. Note that invalid
* indexes can be specified but the error will occur during translation,
* not during this function call.
*
* @param client Client index or LANG_SERVER
* @noreturn
*/
native SetGlobalTransTarget(client);
</pawn>
}}

{{alert|success|Example:|{{hidden|id=trans-l|labelonly=yes}}|opt=full-border}}
{{hidden|id=trans-l|contentonly=yes|content=
<pawn>
client_print(index, print_chat, "%L", index, "EGG");
</pawn>
can be now
<pawn>
client_print(index, print_chat, "%l", "EGG");
</pawn>
}}
|}

''' Formatting '''

* {{tt|set_fail_state}} has now the ability to format a text.
* A new native for simple inline formatting:
:{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|fmt|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=fmt|header=Formats and returns a string according to the AMX Mod X format rules.

{{alert|info|Note:|This should only be used for simple inline formatting like in the above example. Avoid using this function to store strings into variables as an additional copying step is required.|opt=full-border}}
{{alert|info|Note:|The buffer size is defined by {{tt|MAX_FMT_LENGTH}}.|opt=full-border}}
{{alert|success|Example:|{{hidden|id=menu_additem-ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=menu_additem-ex|contentonly=yes|content=
<pawn>
menu_additem(menu, fmt("My first %s", "item"))
</pawn>
}}
|labelpos=left|content=
<pawn>
/**
* Formats and returns a string according to the AMX Mod X format rules
* (see documentation).
*
* @note Example: menu_additem(menu, fmt("My first %s", "item")).
* @note This should only be used for simple inline formatting like in the above example.
* Avoid using this function to store strings into variables as an additional
* copying step is required.
* @note The buffer size is defined by MAX_FMT_LENGTH.
*
* @param format Formatting rules.
* @param ... Variable number of format parameters.
*
* @return Formatted string
*/
native [MAX_FMT_LENGTH]fmt(const format[], any:...);
</pawn>
}}
|}

''' Others '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|strtok2|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=strtok2|header=Breaks a string in two by token.

{{alert|info|Note:|This function has been added due to {{tt|strtok}} being buggy in some situations.|opt=full-border}}

|labelpos=left|content=
{{alert|info|Trim flags:|{{hidden|id=trim-flags|labelonly=yes}}|opt=full-border}}
{{hidden|id=trim-flags|contentonly=yes|content=
<pawn>
/**
* Below are the trim flags for strtok2
*
* You can specify how the left and right buffers will
* be trimmed by strtok2. LTRIM trims spaces from the
* left side. RTRIM trims from the right side.
*
* The defines TRIM_INNER, TRIM_OUTER and TRIM_FULL are
* shorthands for commonly used flag combinations.
*
* When the initial string is trimmed, using TRIM_INNER
* for all subsequent strtok2 calls will ensure that left
* and right are always trimmed from both sides.
*
* Examples:
* str1[] = " This is * some text "
* strtok2(str1, left, 24, right, 24, '*', TRIM_FULL)
* left will be "This is", right will be "some text"
*
* str2[] = " Here is | an | example "
* trim(str2)
* strtok2(str2, left, 24, right, 24, '|', TRIM_INNER)
* left will be "Here is", right will be "an | example"
* strtok2(right, left, 24, right, 24, '|', TRIM_INNER)
* left will be "an", right will be "example"
*
* str3[] = " One - more "
* strtok2(str3, left, 24, right, 24, '-', TRIM_OUTER)
* left will be "One ", right will be " more"
*
* str4[] = " Final . example "
* strtok2(str4, left, 24, right, 24, '.', LTRIM_LEFT|LTRIM_RIGHT)
* left will be "Final ", right will be "example "
*/
#define LTRIM_LEFT (1<<0)
#define RTRIM_LEFT (1<<1)
#define LTRIM_RIGHT (1<<2)
#define RTRIM_RIGHT (1<<3)

#define TRIM_INNER RTRIM_LEFT|LTRIM_RIGHT
#define TRIM_OUTER LTRIM_LEFT|RTRIM_RIGHT
#define TRIM_FULL TRIM_OUTER|TRIM_INNER
</pawn>
}}
<pawn>
/**
* Breaks a string in two by token.
*
* @note Only available in 1.8.3 and above.
*
* @param text String to tokenize
* @param left Buffer to store left half
* @param llen Size of left buffer
* @param right Buffer to store right half
* @param rlen Size of right buffer
* @param token Token to split by
* @param trim Flags for trimming behavior, see above
*
* @return Returns position of token in string if found,
* -1 if token was not found
*/
native strtok2(const text[], left[], const llen, right[], const rlen, const token = ' ', const trim = 0);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|explode_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=explode_string|header=Breaks a string into pieces and stores each piece into an array of buffers.|labelpos=left|content=
<pawn>
/**
* Breaks a string into pieces and stores each piece into an array of buffers.
*
* @param text The string to split.
* @param split The string to use as a split delimiter.
* @param buffers An array of string buffers (2D array).
* @param maxStrings Number of string buffers (first dimension size).
* @param maxStringLength Maximum length of each string buffer.
* @param copyRemainder False (default) discard excess pieces, true to ignore
* delimiters after last piece.
* @return Number of strings retrieved.
*/
stock explode_string(const text[], const split[], buffers[][], maxStrings, maxStringLength, bool:copyRemainder = false)
{
new reloc_idx, idx, total;

if (maxStrings < 1 || !split[0])
{
return 0;
}

while ((idx = split_string(text[reloc_idx], split, buffers[total], maxStringLength)) != -1)
{
reloc_idx += idx;
if (++total == maxStrings)
{
if (copyRemainder)
{
copy(buffers[total-1], maxStringLength, text[reloc_idx-idx]);
}
return total;
}
}

copy(buffers[total++], maxStringLength, text[reloc_idx]);

return total;
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|implode_strings|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=implode_strings|header=Joins an array of strings into one string, with a {{tt|join|bgcolor=white}} string inserted in between each given string. This function complements {{tt|explode_string|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Joins an array of strings into one string, with a "join" string inserted in
* between each given string. This function complements ExplodeString.
*
* @param strings An array of strings.
* @param numStrings Number of strings in the array.
* @param join The join string to insert between each string.
* @param buffer Output buffer to write the joined string to.
* @param maxLength Maximum length of the output buffer.
* @return Number of bytes written to the output buffer.
*/
stock implode_strings(const strings[][], numStrings, const join[], buffer[], maxLength)
{
new total, length, part_length;
new join_length = strlen(join);

for (new i=0; i<numStrings; i++)
{
length = copy(buffer[total], maxLength-total, strings[i]);
total += length;

if (length < part_length)
{
break;
}

if (i != numStrings - 1)
{
length = copy(buffer[total], maxLength-total, join);
total += length;

if (length < join_length)
{
break;
}
}
}

return total;
}
</pawn>
}}
|}

''' UTF-8 '''

An effort has been made to provide UTF-8 safety for formatting-capable functions.
This includes precision with {{tt|%s}} e.g. {{tt|%.12s}}.

Few specific functions have been updated as well:

* {{tt|console_print}}
* {{tt|client_print}}, {{tt|client_print_color}}
* {{tt|get_user_name}}
* {{tt|get_concmd}}, {{tt|get_clcmd}}, {{tt|get_srvcmd}}
* {{tt|get_cvar_string}}, {{tt|get_pcvar_string}}
* {{tt|format_time}}
* {{tt|read_data}}
* {{tt|get_localinfo}}
* {{tt|read_argv}}, {{tt|read_args}}
* {{tt|read_logdata}}, {{tt|read_logargv}}
* {{tt|get_module}}
* {{tt|read_file}}
* {{tt|fgets}}
* {{tt|ReadPackString}}
* {{tt|ArrayGetString}}
* {{tt|TrieGetString}}
* {{tt|strtok}}, {{tt|strtok2}}
* {{tt|strbreak}}
* {{tt|isdigit}}, {{tt|isalnum}}, {{tt|isspace}}, {{tt|isalpha}}

UTF-8 support has been added in the following functions:

* {{tt|containi}}
* {{tt|strfind}} (with ignorecase set)
* {{tt|strcmp}} (with ignorecase set)
* {{tt|strncmp}} (with ignorecase set)
* {{tt|equali}}
* {{tt|replace_string}} (with ignorecase set)
* {{tt|replace_stringex}} (with ignorecase set)
* {{tt|get_players}} (with name and ignorecase flags set)
* {{tt|find_player}} (with name and ignorecase flags set)

New natives have been added:

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|is_char_upper|bgcolor=white}} {{tt|is_char_lower|bgcolor=white}} {{tt|is_char_mb|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=is_char_upper|header=Returns whether an alphabetic character is uppercase.|labelpos=left|content=
<pawn>
/**
* Returns whether an alphabetic character is uppercase.
*
* @note Only available in 1.8.3 and above.
* @note Multi-byte characters will always return false.
*
* @param ch Character to test.
* @return True if character is uppercase, otherwise false.
*/
native bool:is_char_upper(ch);
</pawn>
}}
{{hidden|id=is_char_lower|header=Returns whether an alphabetic character is lowercase.|labelpos=left|content=
<pawn>
/**
* Returns whether an alphabetic character is lowercase.
*
* @note Only available in 1.8.3 and above.
* @note Multi-byte characters will always return false.
*
* @param ch Character to test.
* @return True if character is lowercase, otherwise false.
*/
native bool:is_char_lower(ch);
</pawn>
}}
{{hidden|id=is_char_mb|header=Returns if a character is multi-byte or not.|labelpos=left|content=
<pawn>
/**
* Returns if a character is multi-byte or not.
*
* @note Only available in 1.8.3 and above.
*
* @param ch Character to test.
* @return 0 for a normal 7-bit ASCII character,
* otherwise number of bytes in multi-byte character.
*/
native is_char_mb(ch);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|is_string_category|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=is_string_category|header=Checks if the input string conforms to the category specified by the flags.|labelpos=left|content=
<pawn>
/**
* Checks if the input string conforms to the category specified by the flags.
*
* @note This function can be used to check if the code points in a string are part
* of a category. Valid flags are part of the UTF8C_* list of defines.
* The category for a code point is defined as part of the entry in
* UnicodeData.txt, the data file for the Unicode code point database.
* @note Flags parameter must be a combination of UTF8C_* flags or a single UTF8C_IS* flag.
* In order to main backwards compatibility with POSIX functions like `isdigit`
* and `isspace`, compatibility flags have been provided. Note, however, that
* the result is only guaranteed to be correct for code points in the Basic
* Latin range, between U+0000 and 0+007F. Combining a compatibility flag with
* a regular category flag will result in undefined behavior.
* @note The function is greedy. This means it will try to match as many code
* points with the matching category flags as possible and return the offset in
* the input in bytes.
*
* @param input The string to check
* @param input_size Size of the string, use 1 to check one character regardless its size
* @param flags Requested category, see UTF8C_* flags
* @param output_size Number of bytes in the input that conform to the specified
* category flags
* @return True if the whole input of `input_size` conforms to the specified
* category flags, false otherwise
*/
native bool:is_string_category(const input[], input_size, flags, &output_size = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_char_bytes|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_char_bytes|header=Returns the number of bytes a character is using.|labelpos=left|content=
<pawn>
/**
* Returns the number of bytes a character is using. This is
* for multi-byte characters (UTF-8). For normal ASCII characters,
* this will return 1.
*
* @note Only available in 1.8.3 and above.
*
* @param source Source input string.
* @return Number of bytes the current character uses.
*/
native get_char_bytes(const source[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|mb_strotolower|bgcolor=white}} {{tt|mb_strtoupper|bgcolor=white}} {{tt|mb_ucfirst|bgcolor=white}} {{tt|mb_strtotitle|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=mb_strotolower|header=Performs a multi-byte safe (UTF-8) conversion of all chars in string to lower case.|labelpos=left|content=
<pawn>
/**
* Performs a multi-byte safe (UTF-8) conversion of all chars in string to lower case.
*
* @note Although most code points can be converted in-place, there are notable
* exceptions and the final length can vary.
* @note Case mapping is not reversible. That is, toUpper(toLower(x)) != toLower(toUpper(x)).
*
* @param string The string to convert.
* @param maxlength Optional size of the buffer. If 0, the length of the original string
* will be used instead.
*
* @return Number of bytes written.
*/
native mb_strtolower(string[], maxlength = 0);
</pawn>
}}
{{hidden|id=mb_strtoupper|header=Performs a multi-byte safe (UTF-8) conversion of all chars in string to upper case.|labelpos=left|content=
<pawn>
/**
* Performs a multi-byte safe (UTF-8) conversion of all chars in string to upper case.
*
* @note Although most code points can be converted in-place, there are notable
* exceptions and the final length can vary.
* @note Case mapping is not reversible. That is, toUpper(toLower(x)) != toLower(toUpper(x)).
*
* @param string The string to convert.
* @param maxlength Optional size of the buffer. If 0, the length of the original string
* will be used instead.
*
* @return Number of bytes written.
*/
native mb_strtoupper(string[], maxlength = 0);
</pawn>
}}
{{hidden|id=mb_ucfirst|header=Performs a multi-byte safe (UTF-8) conversion of a string's first character to upper case.|labelpos=left|content=
<pawn>
/**
* Performs a multi-byte safe (UTF-8) conversion of a string's first character to upper case.
*
* @note Although most code points can be converted in-place, there are notable
* exceptions and the final length can vary.
*
* @param string The string to convert.
* @param maxlength Optional size of the buffer. If 0, the length of the original string
* will be used instead.
*
* @return Number of bytes written.
*/
native mb_ucfirst(string[], maxlength = 0);
</pawn>
}}
{{hidden|id=mb_strtotitle|header=Performs a multi-byte safe (UTF-8) conversion of all chars in string to title case.|labelpos=left|content=
<pawn>
/**
* Performs a multi-byte safe (UTF-8) conversion of all chars in string to title case.
*
* @note Although most code points can be converted in-place, there are notable
* exceptions and the final length can vary.
* @note Any type of punctuation can break up a word, even if this is
* not grammatically valid. This happens because the titlecasing algorithm
* does not and cannot take grammar rules into account.
* @note Examples:
* The running man | The Running Man
* NATO Alliance | Nato Alliance
* You're amazing at building libraries | You'Re Amazing At Building Libraries
*
* @param string The string to convert.
* @param maxlength Optional size of the buffer. If 0, the length of the original string
* will be used instead.
*
* @return Number of bytes written.
*/
native mb_strtotitle(string[], maxlength = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|replace_string|bgcolor=white}} {{tt|replace_stringex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=replace_string|header=Given a string, replaces all occurrences of a search string with a replacement string.

{{alert|info|Note:|Similar to {{tt|replace_all|bgcolor=white}} stock, but implemented as native and with different algorithm. 
This native doesn't error on bad buffer size and will smartly cut off the string in a way that pushes old data out.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Given a string, replaces all occurrences of a search string with a
* replacement string.
*
* @note Similar to replace_all() stock, but implemented as native and
* with different algorithm. This native doesn't error on bad
* buffer size and will smartly cut off the string in a way
* that pushes old data out.
*
* @note Only available in 1.8.3 and above.
* @note This supports multi-byte characters (UTF-8) on case insensitive comparison.
*
* @param text String to perform search and replacements on.
* @param maxlength Maximum length of the string buffer.
* @param search String to search for.
* @param replace String to replace the search string with.
* @param caseSensitive If true (default), search is case sensitive.
*
* @return Number of replacements that were performed.
*/
native replace_string(text[], maxlength, const search[], const replace[], bool:caseSensitive = true);
</pawn>
}}
{{hidden|id=replace_string|header=Given a string, replaces the first occurrence of a search string with a replacement string.

{{alert|info|Note:|Similar to {{tt|replace|bgcolor=white}} native, but implemented as native and with different algorithm. 
This native doesn't error on bad buffer size and will smartly cut off the string in a way that pushes old data out.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Given a string, replaces the first occurrence of a search string with a
* replacement string.
*
* @note Similar to replace() native, but implemented with more options and
* with different algorithm. This native doesn't error on bad
* buffer size and will smartly cut off the string in a way
* that pushes old data out.
*
* @note Only available in 1.8.3 and above.
* @note This supports multi-byte characters (UTF-8) on case insensitive comparison.
*
* @param text String to perform search and replacements on.
* @param maxlength Maximum length of the string buffer.
* @param search String to search for.
* @param replace String to replace the search string with.
* @param searchLen If higher than -1, its value will be used instead of
* a strlen() call on the search parameter.
* @param replaceLen If higher than -1, its value will be used instead of
* a strlen() call on the replace parameter.
* @param caseSensitive If true (default), search is case sensitive.
*
* @return Index into the buffer (relative to the start) from where
* the last replacement ended, or -1 if no replacements were
* made.
*/
native replace_stringex(text[], maxlength, const search[], const replace[], searchLen = -1, replaceLen = -1, bool:caseSensitive = true);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|strncmp|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=strncmp|header=Compares two strings parts lexographically.|labelpos=left|content=
<pawn>
/**
* Compares two strings parts lexographically.
*
* @note Only available in 1.8.3 and above.
* @note This supports multi-byte characters (UTF-8) on case insensitive comparison.
*
* @param string1 First string (left).
* @param string2 Second string (right).
* @param num Number of characters to compare.
* @param ignorecase If true, comparison is case insensitive.
* If false (default), comparison is case sensitive.
* @return -1 if string1 < string2
* 0 if string1 == string2
* 1 if string1 > string2
*/
native strncmp(const string1[], const string2[], num, bool:ignorecase = false);
</pawn>
}}
|}

New stocks:

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|char_to_upper|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=char_to_upper|header=Returns an uppercase character to a lowercase character.|labelpos=left|content=
<pawn>
/**
* Returns an uppercase character to a lowercase character.
*
* @note Only available in 1.8.3 and above.
*
* @param chr Characer to convert.
* @return Lowercase character on success,
* no change on failure.
*/
stock char_to_upper(chr)
{
if (is_char_lower(chr))
{
return (chr & ~(1<<5));
}

return chr;
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|char_to_lower|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=char_to_lower|header=Returns a lowercase character to an uppercase character.|labelpos=left|content=
<pawn>
/**
* Returns a lowercase character to an uppercase character.
*
* @note Only available in 1.8.3 and above.
*
* @param chr Characer to convert.
* @return Uppercase character on success,
* no change on failure.
*/
stock char_to_lower(chr)
{
if (is_char_upper(chr))
{
return (chr | (1<<5));
}

return chr;
}
</pawn>
}}
|}

== Existing module APIs additions ==

=== AMXX SDK ===

the following functions have been added:

{| class=wikitable
! style="padding: 0.4em;" | Function
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|MF_SetAmxStringUTF8Char}}
| style="padding: 0.4em;" | Sets UTF-8 string from char* input
|-
| style="padding: 0.4em;" | {{tt|MF_SetAmxStringUTF8Cell}}
| style="padding: 0.4em;" | Sets UTF-8 string from cell* input
|-
| style="padding: 0.4em;" | {{tt|MF_GetAmxStringNull}}
| style="padding: 0.4em;" | Gets string with {{tt|NULL_STRING}} support
|-
| style="padding: 0.4em;" | {{tt|MF_GetAmxVectorNull}}
| style="padding: 0.4em;" | Gets a vector with {{tt|NULL_VECTOR}} support
|-
| style="padding: 0.4em;" | {{tt|MF_GetConfigManager}}
| style="padding: 0.4em;" | Gets the config manager for use with gamedata files
|}

=== CStrike ===

All hardcoded game datas are now moved to its own gamedata file located in {{tt|data/gamedata/modules.games/game.cstrike.txt}}. 
See [[AMX_Mod_X_1.9_Release_Notes#Gamedata]] for more information.

''' Constant '''

Numerous constants from the game have added. See the [https://github.com/alliedmodders/amxmodx/blob/master/plugins/include/cstrike_const.inc cstrike_const.inc].

Additionally for two natives:
* {{tt|CS_NORESET}} constant for use with {{tt|cs_set_user_team}} for skipping the model reset
* {{tt|TRAIN_*}} {{hidden|id=constants_cs|labelonly=yes}} constants for use with {{tt|cs_get_user_driving}}

{{hidden|id=constants_cs|contentonly=yes|content=
<pawn>
/**
* Train status values
*/
#define TRAIN_ACTIVE 0x80
#define TRAIN_NEW 0xc0

#define TRAIN_OFF 0x00
#define TRAIN_NEUTRAL 0x01
#define TRAIN_SLOW 0x02
#define TRAIN_MEDIUM 0x03
#define TRAIN_FAST 0x04
#define TRAIN_BACK 0x05
</pawn>
}}

''' Entity '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|cs_create_entity|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_create_entity|header=Creates an entity using Counter-Strike's custom CreateNamedEntity wrapper.

{{alert|info|Note:|Unlike other mods CS keeps track of entities using a custom hashtable. 
This function adds entities to this hashtable, providing benefits over the default CreateNamedEntity (used by {{tt|create_entity|bgcolor=white}} for example):
* Storing entities in a hashtable allows CS to improve classname lookup performance compared to functions like FindEntityByString (used by {{tt|find_ent_by_class|bgcolor=white}} for example) that usually have to loop through all entities incrementally.
* As CS exclusively uses the hashtable for classname lookup, entities created using the default engine functions will not be found by the game. For example "weaponbox" entities are supposed to be automatically cleaned up on round restart but are not considered if they have not been added to the hashtable.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Creates an entity using Counter-Strike's custom CreateNamedEntity wrapper.
*
* @note Unlike other mods CS keeps track of entities using a custom hashtable.
* This function adds entities to this hashtable, providing benefits over
* the default CreateNamedEntity (used by create_entity() for example):
* - Storing entities in a hashtable allows CS to improve classname lookup
* performance compared to functions like FindEntityByString (used by
* find_ent_by_class() for example) that usually have to loop
* through all entities incrementally.
* - As CS exclusively uses the hashtable for classname lookup, entities
* created using the default engine functions will not be found by the
* game. For example "weaponbox" entities are supposed to be
* automatically cleaned up on round restart but are not considered if
* they have not been added to the hashtable.
* @note The faster hashtable lookup can be utilized with cs_find_ent_by_class()
* @note When creating an entity the classname has to be valid in the mod, as
* the engine needs to link the entity to an existing class internally.
* The classname string that is stored in the entvar struct
* (EV_SZ_classname) is separate from this association and can later be
* freely changed to serve other purposes.
*
* @param classname Entity class name
*
* @return Index of the created entity (> 0), 0 otherwise
*/
native cs_create_entity(const classname[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_find_ent_by_class|bgcolor=white}} {{tt|cs_find_ent_by_owner|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_find_ent_by_class|header=Finds an entity in the world using Counter-Strike's custom FindEntityByString wrapper.|labelpos=left|content=
<pawn>
/**
* Finds an entity in the world using Counter-Strike's custom FindEntityByString
* wrapper.
*
* @note Unlike other mods CS keeps track of entities using a custom hashtable.
* This function utilizes the hasthable and allows for considerably faster
* classname lookup compared to the default FindEntityByString (used by
* find_ent_by_class() for example).
* @note This exclusively considers entities in the hashtable, created by the
* game itself, using cs_create_entity(), or added via cs_set_ent_class().
*
* @param start_index Entity index to start searching from. -1 to start from
* the first entity
* @param classname Classname to search for
*
* @return Entity index > 0 if found, 0 otherwise
*/
native cs_find_ent_by_class(start_index, const classname[]);
</pawn>
}}
{{hidden|id=cs_find_ent_by_owner|header=Finds an entity in the world using Counter-Strike's custom FindEntityByString wrapper, matching by owner. |labelpos=left|content=
<pawn>
/**
* Finds an entity in the world using Counter-Strike's custom FindEntityByString
* wrapper, matching by owner.
*
* @note Unlike other mods CS keeps track of entities using a custom hashtable.
* This function utilizes the hasthable and allows for considerably faster
* classname lookup compared to the default FindEntityByString (used by
* find_ent_by_owner() for example).
* @note This exclusively considers entities in the hashtable, created by the
* game itself, using cs_create_entity(), or added via cs_set_ent_class().
*
* @param start_index Entity index to start searching from. -1 to start from
* the first entity
* @param classname Classname to search for
* @param owner Entity index to search for entity's owner
*
* @return Entity index > 0 if found, 0 otherwise
*/
native cs_find_ent_by_owner(start_index, const classname[], owner);
</pawn>
}}
{{alert|info|Note:|Those functions utilize the hasthable and allows for considerably faster classname lookup compared to the default FindEntityByString (used by {{tt|find_ent_by_class|bgcolor=white}} for example). 
This exclusively considers entities in the hashtable, created by the game itself, using {{tt|cs_create_entity|bgcolor=white}}, or added via {{tt|cs_set_ent_class|bgcolor=white}}).|opt=full-border}}
|-
| style="padding: 0.4em;" | {{tt|cs_set_ent_class|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_set_ent_class|header=Sets a custom classname of an entity.

{{alert|info|Note:|This function adds or updates the classname in the hasthable as well. This is useful for use with {{tt|cs_find_ent_by_class|bgcolor=white}} and {{tt|cs_find_ent_by_owner|bgcolor=white}}.|opt=full-border}}
|labelpos=left|content=
<pawn>
/**
* Sets a custom classname of an entity.
*
* @note Unlike other mods CS keeps track of entities using a custom hashtable.
* This function adds or updates the classname in the hasthable as well.
* This is useful for use with cs_find_ent_by_class() and cs_find_ent_by_owner().
*
* @param index Entity index
* @param classname Classname to update for
*
* @noreturn
*/
native cs_set_ent_class(index, const classname[]);
</pawn>
}}
|}

''' Buying '''

You can now easily detect when an item is being purchased.

{| class=wikitable
! style="padding: 0.4em;" | Forward
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|CS_OnBuyAttempt|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CS_OnBuyAttempt|header=Called when a client attempts to purchase an item.

{{alert|info|Note:|This is called immediately when the client issues a buy command. The game has not yet checked if the client can actually buy the weapon.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Called when a client attempts to purchase an item.
*
* @note This is called immediately when the client issues a buy command. The
* game has not yet checked if the client can actually buy the weapon.
* @note For a list of possible item ids see the CSI_* constants.
*
* @param index Client index
* @param item Item id
*
* @return PLUGIN_CONTINUE to let the buy attempt continue
* PLUGIN_HANDLED to block the buy attempt
*/
forward CS_OnBuyAttempt(index, item);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|CS_OnBuy|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CS_OnBuy|header=Called when a client purchases an item.

{{alert|info|Note:|This is called right before the user receives the item and before the money is deducted from their cash reserves.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Called when a client purchases an item.
*
* @note This is called right before the user receives the item and before the
* money is deducted from their cash reserves.
* @note For a list of possible item ids see the CSI_* constants.
*
* @param index Client index
* @param item Item id
*
* @return PLUGIN_CONTINUE to let the buy continue
* PLUGIN_HANDLED to block the buy
*/
forward CS_OnBuy(index, item);
</pawn>
}}
|}

{{alert|info|Note:|For a list of possible item ids see the {{tt|CSI_*}} {{hidden|id=csi_|labelonly=yes}} constants|opt=full-border}}
{{hidden|id=csi_|contentonly=yes|content=
<c>
/**
* Constants used for the CS_OnBuy() and CS_OnBuyAttempt() forwards.
*
* @note While these mostly overlap with the CSW_* constants the CSI_* constants
* contain custom AMXX values that do not correspond to any real value in
* the game. The CSI_* constants should therefore be used for consistency.
*/
#define CSI_NONE CSW_NONE
#define CSI_P228 CSW_P228
#define CSI_GLOCK CSW_GLOCK // Unused by game, See CSI_GLOCK18.
#define CSI_SCOUT CSW_SCOUT
#define CSI_HEGRENADE CSW_HEGRENADE
#define CSI_XM1014 CSW_XM1014
#define CSI_C4 CSW_C4
#define CSI_MAC10 CSW_MAC10
#define CSI_AUG CSW_AUG
#define CSI_SMOKEGRENADE CSW_SMOKEGRENADE
#define CSI_ELITE CSW_ELITE
#define CSI_FIVESEVEN CSW_FIVESEVEN
#define CSI_UMP45 CSW_UMP45
#define CSI_SG550 CSW_SG550
#define CSI_GALIL CSW_GALIL
#define CSI_FAMAS CSW_FAMAS
#define CSI_USP CSW_USP
#define CSI_GLOCK18 CSW_GLOCK18
#define CSI_P228 CSW_AWP
#define CSI_MP5NAVY CSW_MP5NAVY
#define CSI_M249 CSW_M249
#define CSI_M3 CSW_M3
#define CSI_M4A1 CSW_M4A1
#define CSI_TMP CSW_TMP
#define CSI_G3SG1 CSW_G3SG1
#define CSI_FLASHBANG CSW_FLASHBANG
#define CSI_DEAGLE CSW_DEAGLE
#define CSI_SG552 CSW_SG552
#define CSI_AK47 CSW_AK47
#define CSI_KNIFE CSW_KNIFE
#define CSI_P90 CSW_P90
#define CSI_SHIELDGUN CSW_SHIELDGUN // The real CS value, use CSI_SHELD instead.
#define CSI_VEST CSW_VEST // Custom
#define CSI_VESTHELM CSW_VESTHELM // Custom
#define CSI_DEFUSER 33 // Custom
#define CSI_NVGS 34 // Custom
#define CSI_SHIELD 35 // Custom - The value passed by the forward, more convenient for plugins.
#define CSI_PRIAMMO 36 // Custom
#define CSI_SECAMMO 37 // Custom
#define CSI_MAX_COUNT 38
#define CSI_LAST_WEAPON CSW_LAST_WEAPON

#define CSI_ALL_WEAPONS CSW_ALL_WEAPONS
#define CSI_ALL_PISTOLS CSW_ALL_PISTOLS
#define CSI_ALL_SHOTGUNS CSW_ALL_SHOTGUNS
#define CSI_ALL_SMGS CSW_ALL_SMGS
#define CSI_ALL_RIFLES CSW_ALL_RIFLES
#define CSI_ALL_SNIPERRIFLES CSW_ALL_SNIPERRIFLES
#define CSI_ALL_MACHINEGUNS CSW_ALL_MACHINEGUNS
#define CSI_ALL_GRENADES CSW_ALL_GRENADES
#define CSI_ALL_ARMORS CSW_ALL_ARMORS
#define CSI_ALL_GUNS CSW_ALL_GUNS
</c>
}}

{{alert|success|Example:|{{hidden|id=array_cloning_ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=array_cloning_ex|contentonly=yes|content=
<pawn>
#include <amxmodx>
#include <cstrike>

public CS_OnBuyAttempt(index, item)
{
if (item == CSI_AWP)
{
client_print(index, print_chat, "You tried to buy an AWP.");

return PLUGIN_HANDLED; // <-- Use this to block a buying
}
}

public CS_OnBuy(index, item)
{
if (item == CSI_DEAGLE)
{
client_print(index, print_chat, "You just bought a deagle and you're about to receive it.");
}
}

</pawn>
}}

''' Items info '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|cs_get_user_weapon_entity|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_user_weapon_entity|header=Returns active weapon entity.|labelpos=left|content=
<pawn>
/**
* Returns active weapon entity.
*
* @param playerIndex Player index
*
* @return Weapon entity index on success or 0 if there is no active weapon
* @error If the client index is not within the range of 1 to
* maxClients, or the client is not connected, an error will be
* thrown.
*/
native cs_get_user_weapon_entity(playerIndex);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_user_weapon|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_user_weapon_entity|header=Returns weapon index of the active weapon.

{{alert|info|Note:|More reliable than {{tt|get_user_weapon|bgcolor=white}}.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Returns weapon index of the active weapon.
*
* @note More reliable than get_user_weapon.
*
* @param playerIndex Player index
* @param clip Optional variable to store clip ammo to
* @param ammo Optional variable to store backpack ammo to
*
* @return Weapon index on success or 0 if there is no active weapon
* @error If the client index is not within the range of 1 to
* maxClients, or the client is not connected, an error will be
* thrown.
*/
native cs_get_user_weapon(playerIndex, &clip = 0, &ammo = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_item_id|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_item_id|header=Returns the item id associated with an item name and its aliases.

{{alert|info|Note:|The item name is case sensitive an can be with or without {{tt|weapon_|bgcolor=white}} and {{tt|item_|bgcolor=white}} prefixes. This can be a command alias as well. 
Values examples: {{tt|ak47|bgcolor=white}}, {{tt|weapon_ak47|bgcolor=white}}, {{tt|kevlar|bgcolor=white}}, {{tt|item_kevlar|bgcolor=white}}, {{tt|vest|bgcolor=white}}, {{tt|bullpup|bgcolor=white}}, ...|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Returns the item id associated with an item name and its aliases.
*
* @note The item name is case sensitive an can be with or without
* weapon_ and item_ prefixes. This can be a command alias as well.
* Values examples: ak47, weapon_ak47, kevlar, item_kevlar, vest, bullpup, ...
*
* @param name Alias or classname
* @param classid If item is a weapon, variable to store the associated
* weapon class id in (CS_WEAPONCLASS_* constants)
*
* @return Item id (CSI_* constants)
*/
native any:cs_get_item_id(const name[], &CsWeaponClassType:classid = CS_WEAPONCLASS_NONE);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_translated_item_alias|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_translated_item_alias|header=Returns an item name associated with a command alias.

{{alert|info|Note:|The alias is case sensitive.|opt=full-border}}
{{alert|info|Note:|If not an alias to a weapon, buffer will be set with the original alias.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Returns an item name associated with a command alias.
*
* @note The alias is case sensitive.
* @note If not an alias to a weapon, buffer will be set with the original alias.
*
* @param alias Alias name
* @param itemname Buffer to store item name to
* @param maxlength Maximum buffer size
*
* @return True if alias is translated, false otherwise
*/
native bool:cs_get_translated_item_alias(const alias[], itemname[], maxlength);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_item_alias|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_item_alias|header=Returns the alias name associated with an item index.|labelpos=left|content=
<pawn>
/**
* Returns the alias name associated with an item index.
*
* @param itemid Item id (CSI_* constants)
* @param name Buffer to store alias name to
* @param name_maxlen Maximum buffer size
* @param altname Optional buffer to store if available alternative alias name to
* @param altname_maxlen Maximum buffer size
*
* @return True if alias is found, false otherwise
*/
native bool:cs_get_item_alias(itemid, name[], name_maxlen, altname[] = "", altname_maxlen = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_weapon_info|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_weapon_info|header=Returns some information about a weapon.

{{alert|info|Note:|The alias is case sensitive.|opt=full-border}}
{{alert|info|Note:|If not an alias to a weapon, buffer will be set with the original alias.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Weapon info types for use with cs_get_weapon_info().
*/
enum CsWeaponInfo
{
CS_WEAPONINFO_COST = 0,
CS_WEAPONINFO_CLIP_COST = 1,
CS_WEAPONINFO_BUY_CLIP_SIZE = 2,
CS_WEAPONINFO_GUN_CLIP_SIZE = 3,
CS_WEAPONINFO_MAX_ROUNDS = 4,
CS_WEAPONINFO_AMMO_TYPE = 5,
};

/**
* Returns some information about a weapon.
*
* @param weapon_id Weapon id, see CSW_* constants
* @param type Info type, see CS_WEAPONINFO_* constants
*
* @return Weapon information value
* @error If weapon_id and type are out of bound, an error will be thrown.
*/
native any:cs_get_weapon_info(weapon_id, CsWeaponInfo:type);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|cs_get_weapon_class|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_get_weapon_class|header=Returns a weapon class id associated with a weapon id.|labelpos=left|content=
<pawn>
/**
* Returns a weapon class id associated with a weapon id.
*
* @param weapon_id Weapon id (CSI_* constants)
*
* @return Weapon class id (CS_WEAPONCLASS_* constants)
*/
stock CsWeaponClassType:cs_get_weapon_class(weapon_id)
{
new CsWeaponClassType:type = CS_WEAPONCLASS_NONE;

if (cs_is_valid_itemid(weapon_id, .weapon_only = true) || weapon_id == CSI_SHIELD)
{
switch (weapon_id)
{
case CSI_SHIELDGUN, CSI_SHIELD:
{
type = CS_WEAPONCLASS_PISTOL;
}
case CSI_KNIFE:
{
type = CS_WEAPONCLASS_KNIFE;
}
default:
{
new const bits = (1 << weapon_id);

if(bits & CSI_ALL_PISTOLS)
{
type = CS_WEAPONCLASS_PISTOL;
}
else if(bits & CSI_ALL_GRENADES)
{
type = CS_WEAPONCLASS_GRENADE;
}
else if(bits & CSI_ALL_SMGS)
{
type = CS_WEAPONCLASS_SUBMACHINEGUN;
}
else if(bits & CSI_ALL_SHOTGUNS)
{
type = CS_WEAPONCLASS_SHOTGUN;
}
else if(bits & CSI_ALL_MACHINEGUNS)
{
type = CS_WEAPONCLASS_MACHINEGUN;
}
else if(bits & CSI_ALL_RIFLES)
{
type = CS_WEAPONCLASS_RIFLE;
}
else if(bits & CSI_ALL_SNIPERRIFLES)
{
type = CS_WEAPONCLASS_SNIPERRIFLE;
}
}
}
}

return type;
}
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_is_valid_itemid|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_is_valid_itemid|header=Checks whether an item id is not out of bounds.|labelpos=left|content=
<pawn>
/**
* Checks whether an item id is not out of bounds.
*
* @param id Item id (CSI_* constants)
* @param weapon_only If true, only the real weapon ids will be checked,
* including shield as well
*
* @return True if item id is valid, false otherwise
*/
stock bool:cs_is_valid_itemid(id, bool:weapon_only = false)
{
if (id <= CSI_NONE)
{
return false;
}

if (id > CSI_LAST_WEAPON && id != CSI_SHIELDGUN && weapon_only)
{
return false;
}

if (id >= CSI_MAX_COUNT)
{
return false;
}

return true;
}
</pawn>
}}
|}

''' New params '''

{| class=wikitable
! style="padding: 0.4em;" | Forward
! style="padding: 0.4em;" | Parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|cs_set_user_deaths|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|scoreboard|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CS_OnBuyAttempt|header=If true the scoreboard will be updated to reflect the new value.|labelpos=left|content=
<pawn>
/**
* Sets client's deaths.
*
* @param index Client index
* @param newdeaths New value to set
* @param scoreboard If true the scoreboard will be updated to reflect the new value.
*
* @noreturn
* @error If the client index is not within the range of 1 to
* MaxClients, or the client is not connected, an error
* will be thrown.
*/
native cs_set_user_deaths(index, newdeaths, bool:scoreboard = true);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_get_armoury_type|bgcolor=white}} {{tt|cs_set_armoury_type|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|count|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_getset_armoury_type|header=Optional variable to store in the number of times that an item can be retrieved from the same entity before being hidden.|labelpos=left|content=
<pawn>
/**
* Returns the armoury entity's weapon id.
*
* @note Not all weapon ids are supported by Counter-Strike, an armoury entity
* can not be a pistol, a knife or a bomb for exmaple. The full list is:
* CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG,
* CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1,
* CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG,
* CSW_SG552, CSW_AK47, CSW_P90
*
* @param index Armoury entity index
* @param count Optional variable to store in the number of times that an item can be retrieved
* from the same entity before being hidden
*
* @return Weapon id
* @error If a non-armoury entity is provided, an error will be
* thrown.
*/
native cs_get_armoury_type(index, &count = 1);

/**
* Sets the amoury entity type.
*
* @note Not all weapon ids are supported by Counter-Strike, an armoury entity
* can not be a pistol, a knife or a bomb for exmaple. The full list is:
* CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG,
* CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1,
* CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG,
* CSW_SG552, CSW_AK47, CSW_P90
* @note This does not update the entity model.
* @note On restart, entity is always unhidden and the count is restored (this can not be below 1).
*
* @param index Armoury entity index
* @param type Weapon id
* @param count Number of times that an item can be retrieved from
* the same entity before being hidden
* If zero, the entity is hidden
* If below zero, nothing is set
* @noreturn
* @error If a non-armoury entity is provided, an error will be
* thrown.
*/
native cs_set_armoury_type(index, type, count = -1);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|cs_set_user_model|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|update_index|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=cs_set_user_model|header= If true, the modelindex is updated as well.

{{alert|info|Note:|Updating modelindex is useful for custom models which don't have the same structure as the default ones (hitbox, etc..). Model must be precached before|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Sets the client's player model.
*
* @note This is not a one-time set. The CStrike module will remember the
* selected model and try to prevent attempts at changing the player
* model, or immediately re-apply it if necessary.
* @note Updating modelindex is useful for custom models which don't have
* the same structure as the default ones (hitbox, etc..). Model must
* be precached before.
*
* @param index Client index
* @param model Model name
* @param update_index If true, the modelindex is updated as well
*
* @noreturn
* @error If the client index is not within the range of 1 to
* MaxClients, the client is not connected, the provided
* model is empty, or if modeindex is updated and the
* provided model is not precached, an error will be thrown.
*/
native cs_set_user_model(index, const model[], bool:update_index = false);
</pawn>
}}
|}

''' Others '''

* Hostage natives will work now with {{tt|monster_scientist}} entity (alias of {{tt|hostage_entity}})
* {{tt|cs_get_user_armor}} {{armortype}} parameter is now optional
* {{tt|cs_set_weapon_silen}} {{draw_animation}} has a new value of 2 which follows game behavior to properly draw the animation

=== Engine ===

''' Entity '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|entity_intersects|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=entity_intersects|header=Returns if two entities bounding boxes intersect by comparing their absolute minimum and maximum origins.|labelpos=left|content=
<pawn>
/**
* Returns if two entities bounding boxes intersect by comparing their absolute
* minimum and maximum origins.
*
* @param entity Entity index 1
* @param other Entity index 2
*
* @return True if entities intersect, false otherwise
* @error If an invalid entity index is provided, an error will be
* thrown.
*/
native bool:entity_intersects(entity, other);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|set_ent_rendering|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=set_ent_rendering|header=Sets rendering options of an entity.|labelpos=left|content=
<pawn>
/**
* Sets rendering options of an entity.
*
* @note For a list of valid rendering effects see the kRenderFx* constants in
* amxconst.inc
* @note For a list of valid rendering modes see the kRender* constants in
* amxconst.inc
* @note Rendering amount has different meanings depending on the rendering
* effect and mode used on the entity.
*
* @param index Entity index
* @param fx Rendering effect
* @param r Red component of rendering color
* @param g Green component of rendering color
* @param b Blue component of rendering color
* @param render Rendering mode
* @param amount Rendering amount
*
* @noreturn
* @error If an invalid entity index is provided, an error will be
* thrown.
*/
native set_ent_rendering(index, fx = kRenderFxNone, r = 0, g = 0, b = 0, render = kRenderNormal, amount = 0);
</pawn>
}}
|}

''' Hook '''

You can now unregister hooks from: {{tt|register_impulse}}, {{tt|register_think}} and {{tt|register_touch}}.

{| class=wikitable
! style="padding: 0.4em;" | Forward
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|unregister_impulse|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=unregister_impulse|header=Removes a previously registered impulse hook.|labelpos=left|content=
<pawn>
/**
* Removes a previously registered impulse hook.
*
* @param registerid Impulse forward id
*
* @return 1 on success, 0 if nothing was removed
*/
native unregister_impulse(registerid);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|unregister_think|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=unregister_think|header=Removes a previously registered think hook.|labelpos=left|content=
<pawn>
/**
* Removes a previously registered think hook.
*
* @param registerid Think forward id
*
* @return 1 on success, 0 if nothing was removed
*/
native unregister_think(registerid);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|unregister_touch|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=unregister_touch|header=Removes a previously registered touch hook.|labelpos=left|content=
<pawn>
/**
* Removes a previously registered touch hook.
*
* @param registerid Touch forward id
*
* @return 1 on success, 0 if nothing was removed
*/
native unregister_touch(registerid);
</pawn>
}}
|}

''' Miscellaneous '''

* {{tt|is_visible}} is now working on player.
* {{tt|set_ent_rendering}} is new working on non-players entities.
* {{tt|get_info_keybuffer}} can now retrieve local key buffer (i.e. using {{tt|-1}}).
* {{tt|trace_hull}} gets a new {{tt|end}} destination parameter to make it useful.

''' Safer Natives '''

Safer natives which returns {{tt|-1}} if not entity found instead of {{tt|0}}0 which is a valid value (worldspawn).

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_global_edict2|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_global_edict2|header=Safe version of {{tt|get_global_edict}}. Returns a edict type value from the server globals.|labelpos=left|content=
<pawn>
/**
* Returns a edict type value from the server globals.
*
* @note For a list of valid edict type entries, see the GL_* constants in
* engine_const.inc under the "Edict" section.
* @note This native returns -1 as a safe error value if the edict retrieved is
* an invalid entity. Otherwise it is identical to get_global_edict().
*
* @param variable Entry to retrieve from
*
* @return Value of specified entry
* @error If an invalid entry is provided, an error will be thrown.
*/
native get_global_edict2(variable);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|entity_get_edict2|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=entity_get_edict2|header=Safe version of {{tt|entity_get_edict}}. Returns an edict type value from an entities entvar struct.|labelpos=left|content=
<pawn>
/**
* Returns an edict type value from an entities entvar struct.
*
* @note For a list of valid edict type entries, see the EV_ENT_* constants in
* engine_const.inc
* @note This native returns -1 as a safe error value if the edict retrieved
* from the entvar is an invalid entity. Otherwise it is identical to
* entity_get_edict().
*
* @param iIndex Entity index
* @param iKey Entry to retrieve from
*
* @return Entity index in specified entry, -1 if the edict in the
* entvar is not a valid entity or an invalid entry was
* specified
* @error If an invalid entity index is provided, an error will be
* thrown.
*/
native entity_get_edict2(iIndex, iKey);
</pawn>
}}
|}

''' Usercmd '''

* {{tt|get_usercmd}} and {{tt|set_usercmd}} are now working and can be used in {{tt|client_cmdStart}} forward.

:{| class=wikitable
! style="padding: 0.4em;" | Forward
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|client_cmdStart|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=client_cmdStart|header=Called for CmdStart() on a client.|labelpos=left|content=
<pawn>
/**
* Called for CmdStart() on a client.
*
* @note Use [get|set]_usercmd() to read and modify information in the usercmd
* struct.
*
* @param id Client index
*
* @return PLUGIN_CONTINUE to ignore, PLUGIN_HANDLED or higher to block
*/
forward client_cmdStart(id);
</pawn>
}}
|}

=== Fakemeta ===

''' KVD '''

This allows the creation of new KVD structures that can be used with Hamsandwich ({{tt|Ham_Keyvalue}}).

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|create_kvd|bgcolor=white}} {{tt|free_kvd|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=create_kvd|header=Creates a {{tt|KeyValueData}} handle.|labelpos=left|content=
<pawn>
/**
* Creates a KeyValueData handle.
*
* @note Handles should be freed using free_kvd().
*
* @return New KeyValueData handle
*/
native create_kvd();
</pawn>
}}
{{hidden|id=free_kvd|header=Frees a {{tt|KeyValueData}} handle.|labelpos=left|content=
<pawn>
/**
* Frees a KeyValueData handle.
*
* @param kvd_handle KeyValueData handle
*
* @noreturn
*/
native free_kvd(kvd_handle);
</pawn>
}}
|}

''' Entity's Private Data (gamedata)'''

This is now possible to manage value from an entity's private data based off a class and member name. 
The related gamedata files are located in {{tt|data/gamedata/common.games/entities.games}} directory.

{{alert|success|Example:|{{hidden|id=get_gamerules_int-ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=get_gamerules_int-ex|contentonly=yes|content=
<pawn>
foo()
{
new const item = get_ent_data_entity("CBasePlayer", "m_pActiveItem");
}
</pawn>
}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_ent_data|bgcolor=white}} {{tt|set_ent_data|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data|header=Retrieves an integer value from an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves an integer value from an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* integer, boolean, short, character, pointer, structure, class,
* stringint and function. Unsigned variants (if applicable) are supported
* and will be converted automatically.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Integer value
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native any:get_ent_data(entity, const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_ent_data|header=Sets an integer value to an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets an integer value to an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* integer, boolean, short, character, pointer, stringint and function.
* Unsigned variants (if applicable) are supported and will be converted
* automatically.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Value to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native set_ent_data(entity, const class[], const member[], any:value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_ent_data_float|bgcolor=white}} {{tt|set_ent_data_float|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data_float|header=Retrieves an float value from an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a float value from an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Float value
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native Float:get_ent_data_float(entity, const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_ent_data_float|header=Sets an float value to an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a float value to an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Value to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native set_ent_data_float(entity, const class[], const member[], Float:value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_ent_data_vector|bgcolor=white}} {{tt|set_ent_data_vector|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data_vector|header=Retrieves a vector from an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a vector from an entity's private data based off a class and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Vector buffer to store data in
* @param element Element to retrieve (starting from 0) if member is an array
*
* @noreturn
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native get_ent_data_vector(entity, const class[], const member[], Float:value[3], element = 0);
</pawn>
}}
{{hidden|id=set_ent_data_vector|header=Sets a vector to an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a vector to an entity's private data based off a class and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Vector to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native set_ent_data_vector(entity, const class[], const member[], Float:value[3], element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_ent_data_entity|bgcolor=white}} {{tt|set_ent_data_entity|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data_entity|header=Retrieves an entity index from an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves an entity index from an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* classptr, entvars, edict and ehandle.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Entity index if found, -1 otherwise
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native get_ent_data_entity(entity, const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_ent_data_entity|header=Sets an entity index to an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets an entity index to an entity's private data based off a class
* and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* classptr, entvars, edict and ehandle.
* @note Pass -1 as value to act as C++ NULL.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Entity index to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If an invalid entity or value is provided, either class or member
* is empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native set_ent_data_entity(entity, const class[], const member[], value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_ent_data_string|bgcolor=white}} {{tt|set_ent_data_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data_string|header=Retrieves a string from an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a string from an entity's private data based off a class and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* string, stringptr.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value Buffer to store data in
* @param maxlen Maximum size of the buffer
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Number of cells written to buffer
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native get_ent_data_string(entity, const class[], const member[], value[], maxlen, element = 0);
</pawn>
}}
{{hidden|id=set_ent_data_string|header=Sets a string to an entity's private data based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a string to an entity's private data based off a class and member name.
*
* @note Unlike the [get|set]_pdata_* natives that require compiling the class
* member offset into the plugin, this native instead retrieves the
* necessary offset from the AMXX gamedata files at runtime, based on the
* provided class and member name.
* @note This native is safer than [get|set]_pdata_* as it can perform stricter
* offset and typing checks.
* @note This native is used to access the following (C++/engine) data types:
* string, stringptr.
*
* @param entity Entity index
* @param class Class name
* @param member Member name
* @param value String to set
* @param element Element to set (starting from 0) if member is an array
*
* @return Number of cells written to buffer
* @error If an invalid entity is provided, either class or member is
* empty, no offset is found or an invalid offset is retrieved,
* or the data type does not match, an error will be thrown.
*/
native set_ent_data_string(entity, const class[], const member[], const value[], element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_ent_data_size|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_ent_data_size|header=Retrieves the size of array of n entity class member.|labelpos=left|content=
<pawn>
/**
* Retrieves the size of array of n entity class member.
*
* @param class Class name
* @param member Member name
*
* @return Size of array (in elements), otherwise 1 if member is not an array
* @error If either class or member is empty, no offset is found or an invalid
* offset is retrieved, an error will be thrown.
*/
native get_ent_data_size(const class[], const member[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|find_ent_data_info|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=find_ent_data_info|header=Finds a offset based off an entity class and member name.|labelpos=left|content=
<pawn>
/**
* Finds a offset based off an entity class and member name.
*
* @param class Class name
* @param member Member name
* @param type Optional variable to store member type in (FIELD_* constants)
* @param arraysize Optional variable to store array size in, if member is an array
* @param unsigned Optional variable to store whether member is unsigned (short and char types only)
*
* @return Class member offset
* @error If either class or member is empty, no offset is found or an invalid
* offset is retrieved, an error will be thrown.
*/
native find_ent_data_info(const class[], const member[], &FieldType:type = FIELD_NONE, &arraysize = 0, &bool:unsigned = false);
</pawn>
}}
|}

''' Entity's Private Data '''

While it's encouraged to use the new natives based off gamedata, this completes the list with new data types supported: edict, bool, byte, short and ehandle.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_pdata_ent|bgcolor=white}} {{tt|set_pdata_ent|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_ent|header=Tries to retrieve an edict pointer from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Tries to retrieve an edict pointer from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_ent searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _Offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return -2 if an invalid entity was found.
* -1 if an empty entity was found.
* Otherwise, an entity index is returned.
*/
native get_pdata_ent(_index, _offset, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_ent|header=Sets an edict pointer to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets an edict pointer to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_ent searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _value Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_ent(_index, _offset, _value, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_pdata_bool|bgcolor=white}} {{tt|set_pdata_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_bool|header=Returns a boolean from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Returns a boolean from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_bool searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return An boolean value is returned.
*/
native bool:get_pdata_bool(_index, _offset, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_bool|header=Sets a boolean to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets a boolean to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_bool searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _value Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_bool(_index, _offset, bool:_value, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_pdata_byte|bgcolor=white}} {{tt|set_pdata_byte|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_byte|header=Returns a byte value from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Returns a byte value from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_byte searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return A byte value is returned.
*/
native get_pdata_byte(_index, _offset, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_byte|header=Sets a byte value to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets a byte value to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_byte searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _value Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_byte(_index, _offset, _value, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_pdata_short|bgcolor=white}} {{tt|set_pdata_short|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_short|header=Returns a short value from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Returns a short value from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_short searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return A short value is returned.
*/
native get_pdata_short(_index, _offset, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_short|header=Sets a short value to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets a short value to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_short searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _value Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_short(_index, _offset, _value, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_pdata_vector|bgcolor=white}} {{tt|set_pdata_vector|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_vector|header=Returns a vector from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Returns a vector from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_vector searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _output Vector returned by reference.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native get_pdata_vector(_index, _offset, Float:_output[3], _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_vector|header=Sets a vector to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets a vector to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_vector searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _Offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _origin Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_vector(_index, _offset, Float:_origin[3], _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_pdata_ehandle|bgcolor=white}} {{tt|set_pdata_ehandle|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_pdata_ehandle|header=Tries to retrieve an edict (entity encapsulation) pointer from an entity's private data.|labelpos=left|content=
<pawn>
/**
* Tries to retrieve an edict (entity encapsulation) pointer from an entity's private data.
*
* This function is byte-addressable. Unlike get_pdata_int() which searches in byte increments of 4,
* get_pdata_ehandle searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return -2 if an invalid entity was found.
* -1 if an empty entity was found.
* 0 if serialnumber is not matching.
* Otherwise, an entity index is returned.
*/
native get_pdata_ehandle(_index, _offset, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
{{hidden|id=set_pdata_ehandle|header=Sets an edict (entity encapsulation) pointer to an entity's private data.|labelpos=left|content=
<pawn>
/**
* Sets an edict (entity encapsulation) pointer to an entity's private data.
*
* This function is byte-addressable. Unlike set_pdata_int() which searches in byte increments of 4,
* set_pdata_ehandle searches in increments of 1.
*
* _linuxdiff value is what to add to the _offset for linux servers.
* _macdiff value is what to add to the _offset for os x servers.
*
* A log error is thrown on invalid _index and _Offset.
*
* @param _index Entity index.
* @param _offset Offset to search.
* @param _value Value to set.
* @param _linuxdiff Linux difference.
* @param _macdiff Mac OS X difference.
* @return 1 on success.
*/
native set_pdata_ehandle(_index, _offset, _value, _linuxdiff = 20, _macdiff = 20);
</pawn>
}}
|}

''' Gamerules '''

You have now the ability to manage a value using the gamerules object based off a class and member name. 
The gamedata files are located in {{tt|/data/gamedata/common.games/gamerules.games}} directory.

{{alert|success|Example:|{{hidden|id=get_gamerules_int-ex|labelonly=yes}}|opt=full-border}}
{{hidden|id=get_gamerules_int-ex|contentonly=yes|content=
<pawn>
foo()
{
new const score = get_gamerules_int("CHalfLifeMultiplay", "m_iNumCTWins");
}
</pawn>
}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_int|bgcolor=white}} {{tt|set_gamerules_int|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_int|header=Retrieves an integer value from the gamerules object based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves an integer value from the gamerules object based off a class
* and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* integer, boolean, short, character, pointer, structure, class,
* stringint and function. Unsigned variants (if applicable) are supported
* and will be converted automatically.
*
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Integer value
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native any:get_gamerules_int(const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_gamerules_int|header=Sets an integer value to the gamerules objecta based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets an integer value to the gamerules objecta based off a class
* and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* integer, boolean, short, character, pointer, stringint and function.
* Unsigned variants (if applicable) are supported and will be converted
* automatically.
*
* @param class Class name
* @param member Member name
* @param value Value to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native set_gamerules_int(const class[], const member[], any:value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_float|bgcolor=white}} {{tt|set_gamerules_float|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_float|header=Retrieves a float value from the gamerules object based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a float value from the gamerules object based off a class
* and member name.
*
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Float value
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native Float:get_gamerules_float(const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_gamerules_float|header=Sets an float value to the gamerules objecta based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a float value to the gamerules object based off a class
* and member name.
*
* @param class Class name
* @param member Member name
* @param value Value to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native set_gamerules_float(const class[], const member[], Float:value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_vector|bgcolor=white}} {{tt|set_gamerules_vector|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_vector|header=Retrieves a vector from the gamerules object based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a vector from the gamerules object based off a class and member name.
*
* @param class Class name
* @param member Member name
* @param value Vector buffer to store data in
* @param element Element to retrieve (starting from 0) if member is an array
*
* @noreturn
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native get_gamerules_vector(const class[], const member[], Float:value[3], element = 0);
</pawn>
}}
{{hidden|id=set_gamerules_vector|header=Sets a vector to the gamerules objecta based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a vector to the gamerules object based off a class and member name.
*
* @param class Class name
* @param member Member name
* @param value Vector to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native set_gamerules_vector(const class[], const member[], Float:value[3], element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_entity|bgcolor=white}} {{tt|set_gamerules_entity|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_entity|header=Retrieves an entity index from the gamerules object based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves an entity index from the gamerules object based off a class
* and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* classptr, entvars, edict and ehandle.
*
* @param class Class name
* @param member Member name
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Entity index if found, -1 otherwise
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native get_gamerules_entity(const class[], const member[], element = 0);
</pawn>
}}
{{hidden|id=set_gamerules_entity|header=Sets an entity index to the gamerules objecta based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets an entity index to the gamerules object based off a class
* and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* classptr, entvars, edict and ehandle.
* @note Pass -1 as value to act as C++ NULL.
*
* @param class Class name
* @param member Member name
* @param value Entity index to set
* @param element Element to set (starting from 0) if member is an array
*
* @noreturn
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native set_gamerules_entity(const class[], const member[], value, element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_string|bgcolor=white}} {{tt|set_gamerules_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_string|header=Retrieves a string from the gamerules object based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Retrieves a string from the gamerules object based off a class and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* string, stringptr.
*
* @param class Class name
* @param member Member name
* @param value Buffer to store data in
* @param maxlen Maximum size of the buffer
* @param element Element to retrieve (starting from 0) if member is an array
*
* @return Number of cells written to buffer
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native get_gamerules_string(const class[], const member[], value[], maxlen, element = 0);
</pawn>
}}
{{hidden|id=set_gamerules_string|header=Sets a string to the gamerules objecta based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Sets a string to the gamerules object based off a class and member name.
*
* @note This native is used to access the following (C++/engine) data types:
* string, stringptr.
*
* @param class Class name
* @param member Member name
* @param value String to set
* @param element Element to set (starting from 0) if member is an array
*
* @return Number of cells written to buffer
* @error If member is empty, no offset is found or an invalid offset
* is retrieved, or the data type does not match, an error will
* be thrown.
*/
native set_gamerules_string(const class[], const member[], const value[], element = 0);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|get_gamerules_size|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_gamerules_size|header=Retrieves the size of array of a gamerules class member.|labelpos=left|content=
<pawn>
/**
* Retrieves the size of array of a gamerules class member.
*
* @param class Class name
* @param member Member name
*
* @return Size of array (in elements), otherwise 1 if member is not an array
* @error If either class or member is empty, no offset is found or an invalid
* offset is retrieved, an error will be thrown.
*/
native get_gamerules_size(const class[], const member[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|find_gamerules_info|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=find_gamerules_info|header=Finds a gamerules offset based off a class and member name.|labelpos=left|content=
<pawn>
/**
* Finds a gamerules offset based off a class and member name.
*
* @param class Class name
* @param member Member name
* @param type Optional variable to store member type in (FIELD_* constants)
* @param arraysize Optional variable to store array size in, if member is an array
* @param unsigned Optional variable to store whether member is unsigned (short and char types only)
*
* @return Class member offset
* @error If either class or member is empty, no offset is found or an invalid
* offset is retrieved, an error will be thrown.
*/
native find_gamerules_info(const class[], const member[], &FieldType:type = FIELD_NONE, &arraysize = 0, &bool:unsigned = false);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|get_field_basetype|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=get_field_basetype|header=Returns the data field base type based off a specific field type.|labelpos=left|content=
<pawn>
/**
* Returns the data field base type based off a specific field type.
*
* @note From an AMXX plugin perspective, the (C++/engine) data types can be grouped
* in five base types: integer, float, vector, entity and string. This stock is
* essentially for convenience and debug purpose.
*
* @param type Class member type (FIELD_* constants)
* @param type_name Optional buffer to store base type name in
* @param maxlen Maximum size of the buffer
*
* @return Base field type (BASEFIELD_* constants)
*/
stock BaseFieldType:get_field_basetype(FieldType:type, type_name[] = "", maxlen = 0)
{
static const baseFieldTypeNames[BaseFieldType][] =
{
"none",
"integer",
"float",
"vector",
"entity",
"string",
};

new BaseFieldType:baseType = BASEFIELD_NONE;

switch (type)
{
case FIELD_INTEGER, FIELD_STRINGINT, FIELD_SHORT , FIELD_CHARACTER,
FIELD_CLASS , FIELD_STRUCTURE, FIELD_POINTER, FIELD_FUNCTION,
FIELD_BOOLEAN:
{
baseType = BASEFIELD_INTEGER;
}
case FIELD_FLOAT:
{
baseType = BASEFIELD_FLOAT;
}
case FIELD_VECTOR:
{
baseType = BASEFIELD_VECTOR;
}
case FIELD_CLASSPTR, FIELD_ENTVARS, FIELD_EDICT, FIELD_EHANDLE:
{
baseType = BASEFIELD_ENTITY;
}
case FIELD_STRINGPTR, FIELD_STRING:
{
baseType = BASEFIELD_STRING;
}
}

if (maxlen > 0)
{
copy(type_name, maxlen, baseFieldTypeNames[baseType]);
}

return baseType;
}
</pawn>
}}
|}

''' Miscellaneous '''

* {{tt|get/set_pdata_cbase}} can now be used at map end whereas player's private datas are still valid.
* {{tt|EngFunc_PlayBackEvent}} can now receive a null invoker.
* {{tt|KeyValueData}} usage is now compatible with Hamsandwich module.

=== GeoIP ===

''' Library '''

The module uses the new {{tt|MaxMind GeoIP2 API|bgcolor=none}}. The relevant advantages are:
* Should be more precise
* Data is localized (current supported languages: {{tt|de}}, {{tt|en}}, {{tt|es}}, {{tt|fr}}, {{tt|ja}}, {{tt|ru}}, {{tt|pt-BR}}, {{tt|zh-CN}})

If you want further information, see [https://dev.maxmind.com/geoip/geoip2/whats-new-in-geoip2/ What’s New in GeoIP2].

{{alert|info|Note:|{{TT|GeoIP.dat}} is replaced with {{TT|GeoLite2-Country.mmdb}} (default, [http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.tar.gz downloadable]) or {{TT|GeoLite2-City.mmdb}} ([http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz downloadable]).|opt=full-border}}

''' Command '''

A {{tt|geoip}} command is available for troubleshooting: {{tt|geoip <command> [argument]}}

{| class=wikitable
! style="padding: 0.4em;" | Command
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|version|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=geoip-version|header=Displays the geoip database metadata such as the current loaded database and its version.|labelpos=left|content=
<text>
Database metadata
Node count: 3998109
Record size: 28 bits
IP version: IPv6
Binary format: 2.0
Build epoch: 1501721259 (2017-08-03 00:47:39 UTC)
Type: GeoLite2-City
Languages: de en es fr ja pt-BR ru zh-CN
Description:
en: GeoLite2 City database
</text>
}}
|-
| style="padding: 0.4em;" | {{tt|dump <ip> [output file]|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=geoip-dump||header=Dumps all data from an IP address formatted in a JSON-ish fashion. An output file is mod-based and if not provided, it will print in the console.||labelpos=left|content=
<c>
/**
* GEOIP2 DATA EXAMPLE:
*
* {
* "city": {
* "confidence": 25,
* "geoname_id": 54321,
* "names": {
* "de": "Los Angeles",
* "en": "Los Angeles",
* "es": "Los Ýngeles",
* "fr": "Los Angeles",
* "ja": "ロサンゼルス市",
* "pt-BR": "Los Angeles",
* "ru": "Лоѝ-Ннджелеѝ",
* "zh-CN": "洛杉矶"
* }
* },
* "continent": {
* "code": "NA",
* "geoname_id": 123456,
* "names": {
* "de": "Nordamerika",
* "en": "North America",
* "es": "América del Norte",
* "fr": "Amérique du Nord",
* "ja": "北アメリカ",
* "pt-BR": "América do Norte",
* "ru": "Севернаѝ Нмерика",
* "zh-CN": "北美洲"
*
* }
* },
* "country": {
* "confidence": 75,
* "geoname_id": "6252001",
* "iso_code": "US",
* "names": {
* "de": "USA",
* "en": "United States",
* "es": "Estados Unidos",
* "fr": "États-Unis",
* "ja": "アメリカ坈衆国",
* "pt-BR": "Estados Unidos",
* "ru": "СШН",
* "zh-CN": "美国"
* }
* },
* "location": {
* "accuracy_radius": 20,
* "latitude": 37.6293,
* "longitude": -122.1163,
* "metro_code": 807,
* "time_zone": "America/Los_Angeles"
* },
* "postal": {
* "code": "90001",
* "confidence": 10
* },
* "registered_country": {
* "geoname_id": "6252001",
* "iso_code": "US",
* "names": {
* "de": "USA",
* "en": "United States",
* "es": "Estados Unidos",
* "fr": "États-Unis",
* "ja": "アメリカ坈衆国",
* "pt-BR": "Estados Unidos",
* "ru": "СШН",
* "zh-CN": "美国"
* }
* },
* "represented_country": {
* "geoname_id": "6252001",
* "iso_code": "US",
* "names": {
* "de": "USA",
* "en": "United States",
* "es": "Estados Unidos",
* "fr": "États-Unis",
* "ja": "アメリカ坈衆国",
* "pt-BR": "Estados Unidos",
* "ru": "СШН",
* "zh-CN": "美国"
* },
* "type": "military"
* },
* "subdivisions": [
* {
* "confidence": 50,
* "geoname_id": 5332921,
* "iso_code": "CA",
* "names": {
* "de": "Kalifornien",
* "en": "California",
* "es": "California",
* "fr": "Californie",
* "ja": "カリフォルニア",
* "ru": "Калифорниѝ",
* "zh-CN": "加州"
* }
* }
* ],
* "traits": {
* "autonomous_system_number": "1239",
* "autonomous_system_organization": "Linkem IR WiMax Network",
* "domain": "example.com",
* "is_anonymous_proxy": true,
* "is_transparent_proxy": true,
* "isp": "Linkem spa",
* "ip_address": "1.2.3.4",
* "organization": "Linkem IR WiMax Network",
* "user_type": "traveler",
* },
* "maxmind": {
* "queries_remaining": "54321"
* }
* }
*/
</c>
}}
|}

''' Deprecated natives '''

{{tt|geoip_country}} has been marked as deprecated in favor of {{tt|geoip_country_ex}}. 
Hardcoding the maximum buffer length and returning "error" if nothing is found, were not quite the good idea.

''' New natives '''

The natives which can output localized data, have a new {{tt|id}} {{hidden|id=new_id_param|labelonly=yes}} parameter in order to retrieve data into the player's language.
{{hidden|id=new_id_param|contentonly=yes|content=
<pawn>
/**
* @param id An optional player's index in order to return the result
* in the player's language, if supported.
* -1: the default language, which is english.
* 0: the server language. You can use LANG_SERVER define.
* >=1: the player's language.
*/
</pawn>
}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Database
! style="padding: 0.4em;" | Localized
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|geoip_country_ex|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | Country / City
| style="padding: 0.4em; text-align:center;" | ✓
| style="padding: 0.4em;" | {{hidden|id=geoip_country_ex|labelonly=yes}} Looks up the full country name.
{{hidden|id=geoip_country_ex|contentonly=yes|content=
<pawn>
/**
* Looks up the full country name for the given IP address.
*
* @param ip The IP address to lookup.
* @param result The result of the geoip lookup.
* @param len The maximum length of the result buffer.
* @param id An optional player's index in order to return the result
* in the player's language, if supported.
* -1: the default language, which is english.
* 0: the server language. You can use LANG_SERVER define.
* >=1: the player's language.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_country_ex(const ip[], result[], len, id = -1);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|geoip_city|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✓
| style="padding: 0.4em;" | {{hidden|id=geoip_city|labelonly=yes}} Returns the (localized) city name.
{{hidden|id=geoip_city|contentonly=yes|content=
<pawn>
/**
* Look up the full city name for the given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
* @param len The maximum length of the result buffer.
* @param id An optional player's index in order to return the result
* in the player's language, if supported.
* -1: the default language, which is english.
* 0: the server language. You can use LANG_SERVER define.
* >=1: the player's language.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_city(const ip[], result[], len, id = -1);
</pawn>
}}
|-
| colspan=2 style="padding: 0;" |
|-
| style="padding: 0.4em;" | {{tt|geoip_continent_code|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_continent_code|labelonly=yes}} Returns the continent code. Example: {{tt|EU}} (Europe)
{{hidden|id=geoip_continent_code|contentonly=yes|content=
<pawn>
/**
* Looks up the continent code for a given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
* @note The code can be retrieved as integer (See CONTINENT_* constants.) or string (2 characters).
* @note Possible continent codes are AF, AN, AS, EU, NA, OC, SA for
* Africa(1), Antarctica(2), Asia(3), Europe(4), North America(5), Oceania(6), South America(7).
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
*
* @return The continent id on successful lookup, 0 otherwise.
*/
enum Continent
{
CONTINENT_UNKNOWN = 0,
CONTINENT_AFRICA,
CONTINENT_ANTARCTICA,
CONTINENT_ASIA,
CONTINENT_EUROPE,
CONTINENT_NORTH_AMERICA,
CONTINENT_OCEANIA,
CONTINENT_SOUTH_AMERICA,
};
native Continent:geoip_continent_code(const ip[], result[3]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|geoip_continent_name|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✓
| style="padding: 0.4em;" | {{hidden|id=geoip_continent_name|labelonly=yes}} Returns the (localized) continent name. Example: {{tt|Europe}}
{{hidden|id=geoip_continent_name|contentonly=yes|content=
<pawn>
/**
* Look up the full continent name for the given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
* @param len The maximum length of the result buffer.
* @param id An optional player's index in order to return the result
* in the player's language, if supported.
* -1: the default language, which is english.
* 0: the server language. You can use LANG_SERVER define.
* >=1: the player's language.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_continent_name(const ip[], result[], len, id = -1);
</pawn>
}}
|-
| colspan=2 style="padding: 0;" |
|-
| style="padding: 0.4em;" | {{tt|geoip_region_code|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_region_code|labelonly=yes}} Returns a region code.
{{hidden|id=geoip_region_code|contentonly=yes|content=
<pawn>
/**
* Look up the region/state code for the given IP address.
* e.g. "US-OH", "DE-HH", IT-82, "FR-U", etc.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
* @param len The maximum length of the result buffer.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_region_code(const ip[], result[], len);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|geoip_region_name|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✓
| style="padding: 0.4em;" | {{hidden|id=geoip_region_name|labelonly=yes}} Returns a (localized) region name.
{{hidden|id=geoip_region_name|contentonly=yes|content=
<pawn>
/**
* Look up the full region/state name for the given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
* @param len The maximum length of the result buffer.
* @param id An optional player's index in order to return the result
* in the player's language, if supported.
* -1: the default language, which is english.
* 0: the server language. You can use LANG_SERVER define.
* >=1: the player's language.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_region_name(const ip[], result[], len, id = -1);
</pawn>
}}
|-
| colspan=2 style="padding: 0;" |
|-
| style="padding: 0.4em;" | {{tt|geoip_latitude|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_latitude|labelonly=yes}} Returns a city's latitude.
{{hidden|id=geoip_latitude|contentonly=yes|content=
<pawn>
/**
* Look up the city's latitude for the given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
*
* @return The result of the geoip look up, 0 if latitude is not found.
*/
native Float:geoip_latitude(const ip[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|geoip_longitude|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_longitude|labelonly=yes}} Returns a city's longitude.
{{hidden|id=geoip_longitude|contentonly=yes|content=
<pawn>
/**
* Look up the city's longitude for the given IP address.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
*
* @return The result of the geoip look up, 0 if longitude is not found.
*/
native Float:geoip_longitude(const ip[]);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|geoip_distance|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_distance|labelonly=yes}} Calculates the distance between geographical coordinates.
{{hidden|id=geoip_distance|contentonly=yes|content=
<pawn>
/**
* Calculate the distance between geographical coordinates, latitude and longitude.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param lat1 The first IP latitude.
* @param lon1 The first IP longitude.
* @param lat2 The second IP latitude.
* @param lon2 The second IP longitude.
* @param system The system of measurement, 0 = Metric(kilometers) or 1 = English(miles).
*
* @return The distance as result in specified system of measurement.
*/
#define SYSTEM_METRIC 0 // kilometers
#define SYSTEM_IMPERIAL 1 // statute miles

native Float:geoip_distance(Float:lat1, Float:lon1, Float:lat2, Float:lon2, system = SYSTEM_METRIC);
</pawn>
}}
|-
| colspan=2 style="padding: 0;" |
|-
| style="padding: 0.4em;" | {{tt|geoip_timezone|bgcolor=white}}
| style="padding: 0.4em; text-align:center;" | City
| style="padding: 0.4em; text-align:center;" | ✗
| style="padding: 0.4em;" | {{hidden|id=geoip_timezone|labelonly=yes}} Returns a full time zone. Example: {{tt|Europe/Paris}}
{{hidden|id=geoip_timezone|contentonly=yes|content=
<pawn>
/**
* Look up the full time zone for the given IP address.
* e.g. America/Los_Angeles, Europe/Paris.
*
* @note This native requires GeoIP City database, which can be retrieved from:
* http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary)
*
* @param ip The IP address to look up.
* @param result The result of the geoip look up.
* @param len The maximum length of the result buffer.
*
* @return The result length on successful lookup, 0 otherwise.
*/
native geoip_timezone(const ip[], result[], len);
</pawn>
}}
|}

=== Hamsandwich ===

''' Games support '''

The following games are now supported:
* Deathmatch Classic
* Adrenaline Gamer
* Opposing Forces

The following games have been updated to their latest version:
* Sven Coop v5.13

''' ItemInfo structure '''

A new set of functions have added to manage the {{{tt|ItemInfo}} structure.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|CreateHamItemInfo|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=CreateHamItemInfo|header=Creates an ItemInfo handle. The handle can be used in {{tt|GetHamItemInfo|bgcolor=white}} and {{tt|SetHamItemInfo|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Creates an ItemInfo handle. This value should never be altered.
* The handle can be used in Get/SetHamItemInfo.
*
* NOTE: You must call FreeHamItemInfo() on every handle made with CreateHamItemInfo().
*
* @return A new ItemInfo handle.
*/
native CreateHamItemInfo();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|FreeHamItemInfo|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=FreeHamItemInfo|header=Frees an ItemIndo handle created with {{tt|CreateHamItemInfo|bgcolor=white}}.|labelpos=left|content=
<pawn>
/**
* Frees an ItemIndo handle created with CreateHamItemInfo(). Do not call
* this more than once per handle, or on handles not created through
* CreateHamItemInfo().
*
* @param itemInfo_handle ItemInfo handle created via CreateHamItemInfo().
* @noreturn
*/
native FreeHamItemInfo(itemInfo_handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|GetHamItemInfo|bgcolor=white}} {{tt|SetHamItemInfo|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=GetHamItemInfo|header=Gets a parameter on the fly of the current hook.|labelpos=left|content=
<pawn>
/**
* Gets a parameter on the fly of the current hook.
* Use this on parameters that are iteminfo result handles.
*
* @param iteminfo_handle Item info handle.
* @param type Item info type. See HamItemInfo constants.
*/
native GetHamItemInfo(iteminfo_handle, HamItemInfo:type, any:...);
</pawn>
}}
{{hidden|id=SetHamItemInfo|header=Sets a parameter on the fly of the current hook.|labelpos=left|content=
<pawn>
/**
* Sets a parameter on the fly of the current hook.
* Use this on parameters that are iteminfo result handles.
*
* @param iteminfo_handle Item info handle.
* @param type Item info type. See HamItemInfo_ constants.
*/
native SetHamItemInfo(iteminfo_handle, HamItemInfo:type, any:...);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|SetHamParamItemInfo|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SetHamParamItemInfo|header=Sets a parameter on the fly of the current hook. This has no effect in post hooks.|labelpos=left|content=
<pawn>
/**
* Sets a parameter on the fly of the current hook. This has no effect in post hooks.
* Use this on parameters that are trace result handles.
*
* @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
* @param iteminfo_handle The value to change it to.
*/
native SetHamParamItemInfo(which, iteminfo_handle);
</pawn>
}}
|}

''' Miscellaneous '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|SetParamEntity2|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SetParamEntity2|header=Sets a parameter on the fly of the current hook. This has no effect in post hooks
{{alert|info|Note:| Same as {{tt|SetHamParamEntity|bgcolor=white}} except the changes made by this native are reflected in the corresponding post forward.|opt=full-border}}
.|labelpos=left|content=
<pawn>
/**
* Sets a parameter on the fly of the current hook. This has no effect in post hooks.
* Use this on parameters that are entities.
*
* @note Same as SetHamParamEntity except the changes made by this native are reflected in the corresponding post forward.
*
* @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
* @param value The value to change it to.
*/
native SetHamParamEntity2(which, value);
</pawn>
}}
|}

''' Special bot '''

{{tt|RegisterHam}} has now the ability to register a bot without {{tt|player}} classname.

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|RegisterHam|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|specialbot|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=RegisterHam|header=Whether or not to enable support for bot without "player" classname.|labelpos=left|content=
<pawn>
/**
* Hooks the virtual table for the specified entity class.
* An example would be: RegisterHam(Ham_TakeDamage, "player", "player_hurt");
* Look at the Ham enum for parameter lists.
*
* @param function The function to hook.
* @param EntityClass The entity classname to hook.
* @param callback The forward to call.
* @param post Whether or not to forward this in post.
* @param specialbot Whether or not to enable support for bot without "player" classname.
* @return Returns a handle to the forward. Use EnableHamForward/DisableHamForward to toggle the forward on or off.
*/
native HamHook:RegisterHam(Ham:function, const EntityClass[], const Callback[], Post=0, bool:specialbot = false);
</pawn>
}}
|}

For convenience a stock to make more intuitive registering a function on "player":

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|RegisterHamPlayer|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=RegisterHamPlayer|header=Hooks the virtual table for the player class.|labelpos=left|content=
<pawn>
/**
* Hooks the virtual table for the player class.
* An example would be: RegisterHam(Ham_TakeDamage, "player_hurt");
* Look at the Ham enum for parameter lists.
*
* @param function The function to hook.
* @param callback The forward to call.
* @param post Whether or not to forward this in post.
* @return Returns a handle to the forward. Use EnableHamForward/DisableHamForward to toggle the forward on or off.
*/
stock HamHook:RegisterHamPlayer(Ham:function, const Callback[], Post=0)
{
return RegisterHam(function, "player", Callback, Post, true);
}
</pawn>
}}
|}

''' Virtual function '''

A lot of missing virtual functions have been added for all games. 
Some of the existing common functions have been renamed because they are mod-dependent.

Short overview:
* {{hidden|id=v-common|labelonly=yes}} Common
{{hidden|id=v-common|contentonly=yes|content=
<text>
Ham_ChangeYaw
Ham_HasHumanGibs
Ham_HasAlienGibs
Ham_FadeMonster
Ham_GibMonster
Ham_BecomeDead
Ham_IRelationship
Ham_PainSound
Ham_ReportAIState
Ham_MonsterInitDead
Ham_Look
Ham_BestVisibleEnemy
Ham_FInViewCone
Ham_FVecInViewCone
Ham_GetDeathActivity
Ham_Item_GetItemInfo
</text>
}}
* {{hidden|id=v-common-2|labelonly=yes}} Common (not supported by Counter-Strike, The Specialists and Natural Selection mods)
{{hidden|id=v-common-2|contentonly=yes|content=
<text>
Ham_RunAI,
Ham_MonsterThink,
Ham_MonsterInit,
Ham_CheckLocalMove,
Ham_Move,
Ham_MoveExecute,
Ham_ShouldAdvanceRoute,
Ham_GetStoppedActivity,
Ham_Stop,
Ham_CheckRangeAttack1,
Ham_CheckRangeAttack2,
Ham_CheckMeleeAttack1,
Ham_CheckMeleeAttack2,
Ham_ScheduleChange,
Ham_CanPlaySequence,
Ham_CanPlaySentence,
Ham_PlaySentence,
Ham_PlayScriptedSentence,
Ham_SentenceStop,
Ham_GetIdealState,
Ham_SetActivity,
Ham_CheckEnemy,
Ham_FTriangulate,
Ham_SetYawSpeed,
Ham_BuildNearestRoute,
Ham_FindCover,
Ham_CoverRadius,
Ham_FCanCheckAttacks,
Ham_CheckAmmo,
Ham_IgnoreConditions,
Ham_FValidateHintType,
Ham_FCanActiveIdle,
Ham_ISoundMask,
Ham_HearingSensitivity,
Ham_BarnacleVictimBitten,
Ham_BarnacleVictimReleased,
Ham_PrescheduleThink,
Ham_DeathSound,
Ham_AlertSound,
Ham_IdleSound,
Ham_StopFollowing,
</text>
}}
* {{hidden|id=v-cs|labelonly=yes}} Specific to Counter-Strike
{{hidden|id=v-cs|contentonly=yes|content=
<text>
Ham_CS_Item_IsWeapon
Ham_CS_Weapon_SendWeaponAnim
Ham_CS_Player_ResetMaxSpeed
Ham_CS_Player_IsBot
Ham_CS_Player_GetAutoaimVector
Ham_CS_Player_Blind
Ham_CS_Player_OnTouchingWeapon
</text>
}}
* {{hidden|id=v-dod|labelonly=yes}} Specific to Day Of Defeat
{{hidden|id=v-dod|contentonly=yes|content=
<text>
Ham_DOD_SetScriptReset
Ham_DOD_Item_SpawnDeploy
Ham_DOD_Item_SetDmgTime
Ham_DOD_Item_DropGren
Ham_DOD_Weapon_IsUseable
Ham_DOD_Weapon_Aim
Ham_DOD_Weapon_flAim
Ham_DOD_Weapon_RemoveStamina
Ham_DOD_Weapon_ChangeFOV
Ham_DOD_Weapon_ZoomOut
Ham_DOD_Weapon_ZoomIn
Ham_DOD_Weapon_GetFOV
Ham_DOD_Weapon_PlayerIsWaterSniping
Ham_DOD_Weapon_UpdateZoomSpeed
Ham_DOD_Weapon_Special
Ham_DOD_Weapon_SendWeaponAnim
</text>
}}
* {{hidden|id=v-esf|labelonly=yes}} Specific to Earth's Special Forces
{{hidden|id=v-esf|contentonly=yes|content=
<text>
Ham_ESF_IsFighter
Ham_ESF_IsBuddy
Ham_ESF_EmitSound
Ham_ESF_EmitNullSound
Ham_ESF_IncreaseStrength
Ham_ESF_IncreasePL
Ham_ESF_SetPowerLevel
Ham_ESF_SetMaxPowerLevel
Ham_ESF_StopAniTrigger
Ham_ESF_StopFly
Ham_ESF_HideWeapon
Ham_ESF_ClientRemoveWeapon
Ham_ESF_SendClientsCustomModel
Ham_ESF_CanTurbo
Ham_ESF_CanPrimaryFire
Ham_ESF_CanSecondaryFire
Ham_ESF_CanStopFly
Ham_ESF_CanBlock
Ham_ESF_CanRaiseKi
Ham_ESF_CanRaiseStamina
Ham_ESF_CanTeleport
Ham_ESF_CanStartFly
Ham_ESF_CanStartPowerup
Ham_ESF_CanJump
Ham_ESF_CanWallJump
Ham_ESF_IsSuperJump
Ham_ESF_IsMoveBack
Ham_ESF_CheckWallJump
Ham_ESF_EnableWallJump
Ham_ESF_DisableWallJump
Ham_ESF_ResetWallJumpVars
Ham_ESF_GetWallJumpAnim
Ham_ESF_GetWallJumpAnim2
Ham_ESF_SetWallJumpAnimation
Ham_ESF_SetFlyMoveType
Ham_ESF_IsFlyMoveType
Ham_ESF_IsWalkMoveType
Ham_ESF_SetWalkMoveType
Ham_ESF_DrawChargeBar
Ham_ESF_StartBlock
Ham_ESF_StopBlock
Ham_ESF_StartFly
Ham_ESF_GetMaxSpeed
Ham_ESF_SetAnimation
Ham_ESF_PlayAnimation
Ham_ESF_GetMoveForward
Ham_ESF_GetMoveRight
Ham_ESF_GetMoveUp
Ham_ESF_AddBlindFX
Ham_ESF_RemoveBlindFX
Ham_ESF_DisablePSBar
Ham_ESF_AddBeamBoxCrosshair
Ham_ESF_RemoveBeamBoxCrosshair
Ham_ESF_DrawPSWinBonus
Ham_ESF_DrawPSBar
Ham_ESF_LockCrosshair
Ham_ESF_UnLockCrosshair
Ham_ESF_RotateCrosshair
Ham_ESF_UnRotateCrosshair
Ham_ESF_WaterMove
Ham_ESF_CheckTimeBasedDamage
Ham_ESF_DoesSecondaryAttack
Ham_ESF_DoesPrimaryAttack
Ham_ESF_RemoveSpecialModes
Ham_ESF_StopTurbo
Ham_ESF_TakeBean
Ham_ESF_GetPowerLevel
Ham_ESF_RemoveAllOtherWeapons
Ham_ESF_StopSwoop
Ham_ESF_SetDeathAnimation
Ham_ESF_SetModel
Ham_ESF_AddAttacks
Ham_ESF_EmitClassSound
Ham_ESF_CheckLightning
Ham_ESF_FreezeControls
Ham_ESF_UnFreezeControls
Ham_ESF_UpdateKi
Ham_ESF_UpdateHealth
Ham_ESF_GetTeleportDir
Ham_ESF_Weapon_HolsterWhenMeleed
</text>
}}
* {{hidden|id=v-ns|labelonly=yes}} Specific to Natural Selection
{{hidden|id=v-ns|contentonly=yes|content=
<text>
Ham_NS_SetBoneController
Ham_NS_SaveDataForReset
Ham_NS_GetHull
Ham_NS_GetMaxWalkSpeed
Ham_NS_SetTeamID
Ham_NS_GetEffectivePlayerClass
Ham_NS_GetAuthenticationMask
Ham_NS_EffectivePlayerClassChanged
Ham_NS_NeedsTeamUpdate
Ham_NS_SendTeamUpdate
Ham_NS_SendWeaponUpdate
Ham_NS_InitPlayerFromSpawn
Ham_NS_PackDeadPlayerItems
Ham_NS_GetAnimationForActivity
Ham_NS_StartObserver
Ham_NS_StopObserver
Ham_NS_GetAdrenalineFactor
Ham_NS_GiveNamedItem
Ham_NS_Suicide
Ham_NS_GetCanUseWeapon
Ham_NS_Weapon_GetWeaponPrimeTime
Ham_NS_Weapon_PrimeWeapon
Ham_NS_Weapon_GetIsWeaponPrimed
Ham_NS_Weapon_GetIsWeaponPriming
Ham_NS_Weapon_DefaultDeploy
Ham_NS_Weapon_DefaultReload
Ham_NS_Weapon_GetDeployTime
</text>
}}
* {{hidden|id=v-sc|labelonly=yes}} Specific to Sven Coop
{{hidden|id=v-sc|contentonly=yes|content=
<text>
Ham_SC_GetClassification
Ham_SC_IsMonster
Ham_SC_IsPhysX
Ham_SC_IsPointEntity
Ham_SC_IsMachine
Ham_SC_CriticalRemove
Ham_SC_UpdateOnRemove
Ham_SC_FVisible
Ham_SC_FVisibleFromPos
Ham_SC_IsFacing
Ham_SC_GetPointsForDamage
Ham_SC_GetDamagePoints
Ham_SC_OnCreate
Ham_SC_OnDestroy
Ham_SC_IsValidEntity
Ham_SC_ShouldFadeOnDeath
Ham_SC_SetupFriendly
Ham_SC_ReviveThink
Ham_SC_Revive
Ham_SC_StartMonster
Ham_SC_CheckRangeAttack1_Move
Ham_SC_CheckRangeAttack2_Move
Ham_SC_CheckMeleeAttack1_Move
Ham_SC_CheckMeleeAttack2_Move
Ham_SC_CheckTankUsage
Ham_SC_SetGaitActivity
Ham_SC_FTriangulate
Ham_SC_FTriangulateExtension
Ham_SC_FindCoverGrenade
Ham_SC_FindCoverDistance
Ham_SC_FindAttackPoint
Ham_SC_FValidateCover
Ham_SC_NoFriendlyFire1
Ham_SC_NoFriendlyFire2
Ham_SC_NoFriendlyFire3
Ham_SC_NoFriendlyFireToPos
Ham_SC_FVisibleGunPos
Ham_SC_FInBulletCone
Ham_SC_CallGibMonster
Ham_SC_CheckTimeBasedDamage
Ham_SC_IsMoving
Ham_SC_IsPlayerFollowing
Ham_SC_StartPlayerFollowing
Ham_SC_StopPlayerFollowing
Ham_SC_UseSound
Ham_SC_UnUseSound
Ham_SC_RideMonster
Ham_SC_CheckAndApplyGenericAttacks
Ham_SC_CheckScared
Ham_SC_CheckCreatureDanger
Ham_SC_CheckFallDamage
Ham_SC_CheckRevival
Ham_SC_MedicCallSound
Ham_SC_TakeHealth,
Ham_SC_TakeArmor,
Ham_SC_GiveAmmo,
Ham_SC_CheckAttacker,
Ham_SC_Player_IsConnected,
Ham_SC_Player_MenuInputPerformed
Ham_SC_Player_IsMenuInputDone
Ham_SC_Player_SpecialSpawn
Ham_SC_Player_IsValidInfoEntity
Ham_SC_Player_LevelEnd
Ham_SC_Player_VoteStarted
Ham_SC_Player_CanStartNextVote
Ham_SC_Player_Vote
Ham_SC_Player_HasVoted
Ham_SC_Player_ResetVote
Ham_SC_Player_LastVoteInput
Ham_SC_Player_InitVote
Ham_SC_Player_TimeToStartNextVote
Ham_SC_Player_ResetView
Ham_SC_Player_GetLogFrequency
Ham_SC_Player_LogPlayerStats
Ham_SC_Player_DisableCollisionWithPlayer
Ham_SC_Player_EnableCollisionWithPlayer
Ham_SC_Player_CanTouchPlayer
Ham_SC_Item_Materialize
Ham_SC_Weapon_BulletAccuracy
Ham_SC_Weapon_TertiaryAttack
Ham_SC_Weapon_BurstSupplement
Ham_SC_Weapon_GetP_Model
Ham_SC_Weapon_GetW_Model
Ham_SC_Weapon_GetV_Model
Ham_SC_Weapon_PrecacheCustomModels
Ham_SC_Weapon_IsMultiplayer
Ham_SC_Weapon_FRunfuncs
Ham_SC_Weapon_SetFOV
Ham_SC_Weapon_FCanRun
Ham_SC_Weapon_CustomDecrement
Ham_SC_Weapon_SetV_Model
Ham_SC_Weapon_SetP_Model
Ham_SC_Weapon_ChangeWeaponSkin
</text>
}}
* {{hidden|id=v-opf|labelonly=yes}} Specific to Opposing Force
{{hidden|id=v-opf|contentonly=yes|content=
<text>
Ham_OPF_MySquadTalkMonsterPointer
Ham_OPF_WeaponTimeBase
</text>
}}
* {{hidden|id=v-tfc|labelonly=yes}} Specific to Team Fortress Classic
{{hidden|id=v-tfc|contentonly=yes|content=
<text>
Ham_TFC_DB_GetItemName
Ham_TFC_IsTriggered
Ham_TFC_Killed
Ham_TFC_RadiusDamage
Ham_TFC_RadiusDamage2
Ham_TFC_Weapon_GetNextAttackDelay
Ham_TFC_Weapon_SendWeaponAnim
</text>
}}
* {{hidden|id=v-ts|labelonly=yes}} Specific to The Specialists
{{hidden|id=v-ts|contentonly=yes|content=
<text>
Ham_TS_Weapon_AlternateAttack
</text>
}}

See [https://github.com/alliedmodders/amxmodx/blob/master/plugins/include/ham_const.inc#L1182 ham_const.inc] for a full list (it starts from line 1182).

=== MySQL ===

''' Connectivity '''

To improve the connectivity, few features have been added.

{| class=wikitable
! style="padding: 0.4em;" | Feature
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | ''Reconnection''
| style="padding: 0.4em;" | This has MySQL automatically reconnects if times out or loses connection through {{tt|MYSQL_OPT_RECONNECT|bgcolor=white}} option. This should prevent "MySQL server has gone away" errors after a while.
|-
| style="padding: 0.4em;" | ''Timeout''
| style="padding: 0.4em;" | This establishes a default read/write timeout for MySQL connectivity through {{tt|MYSQL_OPT_CONNECT_TIMEOUT|bgcolor=white}} option. A new option to set globally the timeout (60s by default) can be found in {{tt|core.ini|bgcolor=white}} {{hidden|id=mysql_timeout|labelonly=yes}} and a new {{tt|amx_sql_timeout|bgcolor=white}} cvar in {{tt|sql.cfg|bgcolor=white}} {{hidden|id=cvar_timeout|labelonly=yes}}.
{{hidden|id=mysql_timeout|contentonly=yes|content=
<pawn>
; MySQL default timeout
mysql_timeout 60
</pawn>
}}
{{hidden|id=cvar_timeout|contentonly=yes|content=
<pawn>
amx_sql_timeout "60"
</pawn>
}}
|}

''' Miscellaneous '''

* Module threading has been updated to be more responsive. This should help in reducing potential hang up in situations such as on change map or lost connection.

''' Character Set '''

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|MySQL_SetCharset|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=MySQL_SetCharset|header=Sets the character set of the current connection.|labelpos=left||content=
<pawn>
/**
* Sets the character set of the current connection.
* Like SET NAMES .. in mysql, but stays after connection problems.
*
* If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery.
* Also note the change will remain until you call this function with another value.
* This native does nothing in SQLite.
*
* Example: "utf8", "latin1"
*
* @param h Database or connection tuple Handle.
* @param charset The character set string to change to.
* @return True, if character set was changed, false otherwise.
*/
native bool:SQL_SetCharset(Handle:h, const charset[]);
</pawn>
}}
|}

=== RegEx ===

''' Library '''

The internal {{texttip|PCRE|Perl Compatible Regular Expressions}} library version has been updated from {{tt|6.4|bgcolor=none}} to {{tt|8.35|bgcolor=none}} and has been compiled with UTF-8 support. 
If you are interested, see the [https://github.com/alliedmodders/amxmodx/blob/master/tools/pcre/ChangeLog changelog].

''' Miscellaneous '''

* {{tt|regex_subtr}}: The internal static buffer has been increased to match the same size as core and has been made UTF-8 safe.
* The maximum number of sub-patterns has been increased from {{tt|30|bgcolor=none}} to {{tt|150|bgcolor=none}}.

''' New Natives & Stocks '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|regex_compile_ex|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=regex_compile_ex|header=Precompiles a regular expression.

{{alert|info|Note:|Similar as {{tt|regex_compile/_c|bgcolor=white}} but with the differences that you can use directly {{tt|PCRE_*|bgcolor=white}} {{hidden|id=pcre_flags|labelonly=yes}} flags and the error parameter is an integer associated to {{tt|REGEX_ERROR_*|bgcolor=white}} {{hidden|id=regex_errors|labelonly=yes}} flags.|opt=full-border}}

|labelpos=left||content=
<pawn>
/**
* Precompiles a regular expression.
*
* @note Use this if you intend on using the same expression multiple times.
* Pass the regex handle returned here to regex_match_c() to check for matches.
*
* @note Unlike regex_compile(), this allows you to use PCRE flags directly.
*
* @param pattern The regular expression pattern.
* @param flags General flags for the regular expression, see PCRE_* defines.
* @param error Error message encountered, if applicable.
* @param maxLen Maximum string length of the error buffer.
* @param errcode Regex type error code encountered, if applicable. See REGEX_ERROR_* defines.
*
* @return Valid regex handle (> 0) on success, or -1 on failure.
*/
native Regex:regex_compile_ex(const pattern[], flags = 0, error[]= "", maxLen = 0, &errcode = 0);
</pawn>
}}
{{hidden|id=pcre_flags|contentonly=yes|content=
<c>
/**
* Flags for compiling regex expressions.
* These come directly from the pcre library and can be used in regex_compile_ex.
*/
#define PCRE_CASELESS 0x00000001 /* Ignore Case */
#define PCRE_MULTILINE 0x00000002 /* Multilines (affects ^ and $ so that they match the start/end of a line rather than matching the start/end of the string). */
#define PCRE_DOTALL 0x00000004 /* Single line (affects . so that it matches any character, even new line characters). */
#define PCRE_EXTENDED 0x00000008 /* Pattern extension (ignore whitespace and # comments). */
#define PCRE_ANCHORED 0x00000010 /* Force pattern anchoring. */
#define PCRE_DOLLAR_ENDONLY 0x00000020 /* $ not to match newline at end. */
#define PCRE_UNGREEDY 0x00000200 /* Invert greediness of quantifiers */
#define PCRE_NOTEMPTY 0x00000400 /* An empty string is not a valid match. */
#define PCRE_UTF8 0x00000800 /* Use UTF-8 Chars */
#define PCRE_NO_UTF8_CHECK 0x00002000 /* Do not check the pattern for UTF-8 validity (only relevant if PCRE_UTF8 is set) */
#define PCRE_NEVER_UTF 0x00010000 /* Lock out interpretation of the pattern as UTF-8 */
#define PCRE_FIRSTLINE 0x00040000 /* Force matching to be before newline */
#define PCRE_DUPNAMES 0x00080000 /* Allow duplicate names for subpattern */
#define PCRE_NEWLINE_CR 0x00100000 /* Specify that a newline is indicated by a single character CR ) */
#define PCRE_NEWLINE_CRLF 0x00300000 /* specify that a newline is indicated by the two-character CRLF sequence ) Overrides the default */
#define PCRE_NEWLINE_ANY 0x00400000 /* Specify that any Unicode newline sequence should be recognized. ) newline definition (LF) */
#define PCRE_NEWLINE_ANYCRLF 0x00500000 /* Specify that any of CR, LF and CRLF sequences should be recognized ) */
#define PCRE_UCP 0x20000000 /* Change the way PCRE processes \B, \b, \D, \d, \S, \s, \W, \w etc. to use Unicode properties */
</c>
}}
{{hidden|id=regex_errors|contentonly=yes|content=
<c>
/**
* Regex expression error codes.
* This can be used with regex_compile_ex and regex_match_ex.
*/
enum /*RegexError*/
{
REGEX_ERROR_NONE = 0, /* No error */
REGEX_ERROR_NOMATCH = -1, /* No match was found */
REGEX_ERROR_NULL = -2,
REGEX_ERROR_BADOPTION = -3,
REGEX_ERROR_BADMAGIC = -4,
REGEX_ERROR_UNKNOWN_OPCODE = -5,
REGEX_ERROR_NOMEMORY = -6,
REGEX_ERROR_NOSUBSTRING = -7,
REGEX_ERROR_MATCHLIMIT = -8,
REGEX_ERROR_CALLOUT = -9, /* Never used by PCRE itself */
REGEX_ERROR_BADUTF8 = -10,
REGEX_ERROR_BADUTF8_OFFSET = -11,
REGEX_ERROR_PARTIAL = -12,
REGEX_ERROR_BADPARTIAL = -13,
REGEX_ERROR_INTERNAL = -14,
REGEX_ERROR_BADCOUNT = -15,
REGEX_ERROR_DFA_UITEM = -16,
REGEX_ERROR_DFA_UCOND = -17,
REGEX_ERROR_DFA_UMLIMIT = -18,
REGEX_ERROR_DFA_WSSIZE = -19,
REGEX_ERROR_DFA_RECURSE = -20,
REGEX_ERROR_RECURSIONLIMIT = -21,
REGEX_ERROR_NULLWSLIMIT = -22, /* No longer actually used */
REGEX_ERROR_BADNEWLINE = -23,
REGEX_ERROR_BADOFFSET = -24,
REGEX_ERROR_SHORTUTF8 = -25,
REGEX_ERROR_RECURSELOOP = -26,
REGEX_ERROR_JIT_STACKLIMIT = -27,
REGEX_ERROR_BADMODE = -28,
REGEX_ERROR_BADENDIANNESS = -29,
REGEX_ERROR_DFA_BADRESTART = -30,
REGEX_ERROR_JIT_BADOPTION = -31,
REGEX_ERROR_BADLENGTH = -32,
REGEX_ERROR_UNSET = -33
};
</c>
}}
|-
| style="padding: 0.4em;" | {{tt|regex_match_all|bgcolor=white}} {{tt|regex_match_all_c|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=regex_match_all|header=Matches a string against a regular (compiled) expression pattern, matching all occurrences of the pattern inside the string.

{{alert|info|Note:|This is similar to using the {{tt|g|bgcolor=white}} flag in perl regex.|opt=full-border}}

|labelpos=left||content=
<pawn>
/**
* Matches a string against a regular expression pattern, matching all occurrences of the
* pattern inside the string. This is similar to using the "g" flag in perl regex.
*
* @note If you intend on using the same regular expression pattern
* multiple times, consider using regex_compile and regex_match_ex
* instead of making this function reparse the expression each time.
*
* @note Flags only exist in amxmodx 1.8 and later.
*
* @note You should free the returned handle with regex_free()
* when you are done extracting all of the substrings.
*
* @param string The string to check.
* @param pattern The regular expression pattern.
* @param flags General flags for the regular expression, see PCRE_* defines.
* @param error Error message encountered, if applicable.
* @param maxLen Maximum string length of the error buffer.
* @param errcode Regex type error code encountered, if applicable. See REGEX_ERROR_* defines.
*
* @return -2 = Matching error (error code is stored in ret)
* -1 = Error in pattern (error message and offset # in error and ret)
* 0 = No match.
* >1 = Handle for getting more information (via regex_substr)
*/
native Regex:regex_match_all(const string[], const pattern[], flags = 0, error[]= "", maxLen = 0, &errcode = 0);

/**
* Matches a string against a pre-compiled regular expression pattern, matching all
* occurrences of the pattern inside the string. This is similar to using the "g" flag
* in perl regex.
*
* @note You should free the returned handle (with regex_free())
* when you are done with this pattern.
*
* @note Use the regex handle passed to this function to extract
* matches with regex_substr().
*
* @param pattern The regular expression pattern.
* @param string The string to check.
* @param ret Error code, if applicable, or number of results on success.
* See REGEX_ERROR_* defines.
*
* @return -2 = Matching error (error code is stored in ret)
* 0 = No match.
* >1 = Number of results.
*/
native regex_match_all_c(const string[], Regex:pattern, &ret = 0);
</pawn>
}}
|}

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|regex_match_simple|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=regex_match_simple|header=Matches a string against a regular expression pattern. Useful if you need to use the pattern one time.}|labelpos=left||content=
<pawn>
/**
* Matches a string against a regular expression pattern.
*
* @note If you intend on using the same regular expression pattern
* multiple times, consider using compile regex_compile_ex and regex_match*
* instead of making this function reparse the expression each time.
*
* @param str The string to check.
* @param pattern The regular expression pattern.
* @param flags General flags for the regular expression.
* @param error Error message, if applicable.
* @param maxLen Maximum length of the error buffer.
* @param errcode Regex type error code encountered, if applicable. See REGEX_ERROR_* defines.
*
* @return -2 = Matching error (error code is stored in ret)
* -1 = Pattern error (error code is stored in ret)
* 0 = No match.
* >1 = Number of results.
*/
stock regex_match_simple(const str[], const pattern[], flags = 0, error[]= "", maxLen = 0, &errcode = 0)
{
new Regex:regex = regex_compile_ex(pattern, flags, error, maxLen, errcode);
if (regex < REGEX_OK)
{
return -1;
}
new substrings = regex_match_c(str, regex);
regex_free(regex);
return substrings;
}
</pawn>
}}
|}

=== Socket ===

* WinSock is now update from version {{tt|1.1|bgcolor=white}} to {{tt|2.2|bgcolor=white}}
* Natives won't be registered if WinSock can't be started

''' Improvements '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Parameter
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{hidden|id=socket_open|labelonly=yes}} {{tt|socket_open|bgcolor=white}}
| style="padding: 0.4em;" | {{tt|_flags|bgcolor=white}}
| style="padding: 0.4em;" |
The following flags are additive:
* {{tt|SOCK_NON_BLOCKING|bgcolor=white}}: if set, the socket will be on nonblocking mode
* {{tt|SOCK_LIBC_ERRORS|bgcolor=white}}: f set, the new libc errors will be seen on {{tt|_error|bgcolor=white}}

{{hidden|id=socket_open|contentonly=yes|content=
<pawn>
/**
* Error reporting
*/
#define SOCK_ERROR_OK 0 /* No error */
#define SOCK_ERROR_CREATE_SOCKET 1 /* Couldn't create a socket */
#define SOCK_ERROR_SERVER_UNKNOWN 2 /* Server unknown */
#define SOCK_ERROR_WHILE_CONNECTING 3 /* Error while connecting */

/**
* Connects to the given node and service via TCP/UDP.
*
* @note There's 2 types of error reporting on this function that you can use.
* @note Default error codes:
* 0 - No error
* 1 - Error while creating socket
* 2 - Couldn't resolve hostname
* 3 - Couldn't connect
* @note New, more expressive libc error codes:
* https://www.gnu.org/software/libc/manual/html_node/Error-Codes.html
* https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno.h
* https://msdn.microsoft.com/en-us/library/ms740668.aspx
*
* @note The currently available bit flags are:
* - SOCK_NON_BLOCKING : if set, the socket will be on nonblocking mode
* - SOCK_LIBC_ERRORS : if set, the new libc errors will be seen on _error
*
* @note If no flags are set, the behaviour of the function will not be modified.
*
* @note Multiple flags may be set at the same time using the | operator.
* For example, SOCK_NON_BLOCKING|SOCK_LIBC_ERRORS will create a nonblocking socket with libc error codes.
*
* @note If you're creating a new nonblocking socket, _hostname should be numeric to avoid calling the
* name resolution server and potentially blocking the call.
*
* @note If the socket is a nonblocking one, the returned socket descriptor may be still connecting and
* further checks should be done with socket_is_writable() before trying to send data.
*
* @param _hostname Node to connect to
* @param _port Service to connect to
* @param _protocol Connect via SOCKET_TCP or SOCKET_UDP
* @param _error Set an error code here if anything goes wrong
* @param _flags Optional bit flags that change the behaviour of the function
*
* @return A socket descriptor (a positive integer) on success
* -1 on failure
*/
native socket_open(const _hostname[], _port, _protocol = SOCKET_TCP, &_error, _flags = 0);
</pawn>
}}
|}

{{alert|info|Note:|An example is available at [https://github.com/alliedmodders/amxmodx/pull/301#issuecomment-204794080 PR 301]|opt=full-border}}

''' New natives '''

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|socket_is_writable|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=socket_is_writable|header=Checks if a socket is marked as writable.|labelpos=left|content=
<pawn>
/**
* Checks if a socket is marked as writable.
*
* @note Use this function to check if a nonblocking socket is ready to be used.
* @note Set _timeout to 0 avoid blocking the call.
* @note An UDP socket is always writable.
*
* @param _socket Socket descriptor
* @param _timeout Amount of time to block the call waiting for the socket to be marked as writable or
* for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
*
* @return 1 if the socket is marked as writable
* 0 otherwise
*/
native socket_is_writable(_socket, _timeout = 100000);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|socket_is_readable|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=socket_is_readable|header=Checks if a socket is marked as readable.

{{alert|info|Note:|This function is an alias of {{tt|socket_change}} which is now deprecated.|opt=full-border}}

|labelpos=left|content=
<pawn>
/**
* Checks if a socket is marked as readable.
*
* @note You can use this function to make sure there's something on the socket and avoid a blocking call.
* @note Set _timeout to 0 avoid blocking the call.
* @note A socket will become readable if there's any data or an EOF.
*
* @param _socket Socket descriptor
* @param _timeout Amount of time to block the call waiting for the socket to be marked as readable or
* for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
*
* @return 1 if the socket is marked as readable
* 0 otherwise
*/
native socket_is_readable(_socket, _timeout = 100000);
</pawn>
}}
|}

=== SQLite ===

''' Library '''

The SQLite library version has been updated from {{tt|3.3.13|bgcolor=none}} to {{tt|3.8.8.2|bgcolor=none}}. 
If you are interested, see the [https://www.sqlite.org/changes.html changelog].

''' Character Set '''

{| class=wikitable
! style="padding: 0.4em;" | Stock
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em;" | {{tt|SQL_SetCharset|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=SQL_SetCharset|header=Sets the character set of the current connection.|labelpos=left||content=
<pawn>
/**
* Sets the character set of the current connection.
* Like SET NAMES .. in mysql, but stays after connection problems.
*
* If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery.
* Also note the change will remain until you call this function with another value.
* This native does nothing in SQLite.
*
* Example: "utf8", "latin1"
*
* @param h Database or connection tuple Handle.
* @param charset The character set string to change to.
* @return True, if character set was changed, false otherwise.
*/
native bool:SQL_SetCharset(Handle:h, const charset[]);
</pawn>
}}
|}

''' Miscellaneous '''

* The {{tt|queuetime}} value is now properly passed to the {{tt|SQL_ThreadQuery|bgcolor=none}} callback.

== New module ==

=== JSON ===

A JSON module is now part of the official AMX Mod X package.

Essentially:
* Supports decoding and encoding (also with pretty format)
* Relies on Parson, which is lighweight and simple JSON library written in C
* Supports dot notation (Values can be accessed by typing objectA.objectB.value)
* Allows us to iterate through arrays and objects

{{alert|info|Note:|Examples are available on [https://github.com/alliedmodders/amxmodx/pull/379 Github] an in the {{tt|testsuite}} directory, see [https://github.com/alliedmodders/amxmodx/blob/master/plugins/testsuite/textparse_test.sma textparse.sma].|opt=full-border}}

{| class=wikitable
! style="padding: 0.4em;" | Native
! style="padding: 0.4em;" | Description
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|General}}
|-
| style="padding: 0.4em;" | {{tt|json_parse|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_parse|header=Parses JSON string or a file that contains JSON.|labelpos=left|content=
<pawn>
/**
* Parses JSON string or a file that contains JSON.
*
* @note Needs to be freed using json_free() native.
*
* @param string String to parse
* @param is_file True to treat string param as filename, false otherwise
* @param with_comments True if parsing JSON includes comments (it will ignore them), false otherwise
*
* @return JSON handle, Invalid_JSONValue if error occurred
*/
native JSON:json_parse(const string[], bool:is_file = false, bool:with_comments = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_equals|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_equals|header=Checks if the first value is the same as the second one.|labelpos=left|content=
<pawn>
/**
* Checks if the first value is the same as the second one.
*
* @param value1 JSON handle
* @param value2 JSON handle
*
* @return True if they are the same, false otherwise
* @error If passed value is not a valid handle
*/
native bool:json_equals(const JSON:value1, const JSON:value2);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_validate|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_validate|header=Validates json by checking if object have identically named fields with matching types.|labelpos=left|content=
<pawn>
/**
* Validates json by checking if object have identically named
* fields with matching types.
*
* @note Schema {"name":"", "age":0} will validate
* {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"},
* but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}.
*
* @note In case of arrays, only first value in schema
* is checked against all values in tested array.
*
* @note Empty objects ({}) validate all objects,
* empty arrays ([]) validate all arrays,
* null validates values of every type.
*
* @param schema JSON handle
* @param value JSON handle
*
* @return True if passed value is valid, false otherwise
* @error If a schema handle or value handle is invalid
*/
native bool:json_validate(const JSON:schema, const JSON:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_get_parent|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_get_parent|header=Gets value's parent handle.|labelpos=left|content=
<pawn>
/**
* Gets value's parent handle.
*
* @note Parent's handle needs to be freed using json_free() native.
*
* @param value JSON handle
*
* @return Parent's handle
*/
native JSON:json_get_parent(const JSON:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_get_type|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_get_type|header=Gets JSON type of passed value.|labelpos=left|content=
<pawn>
/**
* Gets JSON type of passed value.
*
* @param value JSON handle
*
* @return JSON type (JSONType constants)
* @error If a value handle is invalid
*/
native JSONType:json_get_type(const JSON:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_init_object|bgcolor=white}} {{tt|json_init_array|bgcolor=white}} {{tt|json_init_string|bgcolor=white}} {{tt|json_init_number|bgcolor=white}} {{tt|json_init_real|bgcolor=white}} {{tt|json_init_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_init_object|header=Inits an empty object.|labelpos=left|content=
<pawn>
/**
* Inits an empty object.
*
* @note Needs to be freed using json_free() native.
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_object();
</pawn>
}}
{{hidden|id=json_init_array|header=Inits an empty array.|labelpos=left|content=
<pawn>
/**
* Inits an empty array.
*
* @note Needs to be freed using json_free() native.
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_array();
</pawn>
}}
{{hidden|id=json_init_string|header=Inits string data.|labelpos=left|content=
<pawn>
/**
* Inits string data.
*
* @note Needs to be freed using json_free() native.
*
* @param value String that the handle will be initialized with
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_string(const value[]);
</pawn>
}}
{{hidden|id=json_init_number|header=Inits a number.|labelpos=left|content=
<pawn>
/**
* Inits a number.
*
* @note Needs to be freed using json_free() native.
*
* @param value Integer number that the handle will be initialized with
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_number(value);
</pawn>
}}
{{hidden|id=json_init_real|header=Inits a real number.|labelpos=left|content=
<pawn>
/**
* Inits a real number.
*
* @note Needs to be freed using json_free() native.
*
* @param value Real number that the handle will be initialized with
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_real(Float:value);
</pawn>
}}
{{hidden|id=json_init_bool|header=Inits a boolean value.|labelpos=left|content=
<pawn>
/**
* Inits a boolean value.
*
* @note Needs to be freed using json_free() native.
*
* @param value Boolean value that the handle will be initialized with
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_bool(bool:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_init_null|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_init_null|header=Inits a null.|labelpos=left|content=
<pawn>
/**
* Inits a null.
*
* @note Needs to be freed using json_free() native.
*
* @return JSON handle, Invalid_JSON if error occurred
*/
native JSON:json_init_null();
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_deep_copy|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_deep_copy|header=Creates deep copy of passed value.|labelpos=left|content=
<pawn>
/**
* Creates deep copy of passed value.
*
* @note Needs to be freed using json_free() native.
*
* @param value JSON handle to be copied
*
* @return JSON handle, Invalid_JSON if error occurred
* @error If passed value is not a valid handle
*/
native JSON:json_deep_copy(const JSON:value);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_free|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_free|header=Frees handle.|labelpos=left|content=
<pawn>
/**
* Frees handle.
*
* @param handle JSON handle to be freed
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid handle
*/
native bool:json_free(&JSON:handle);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_get_string|bgcolor=white}} {{tt|json_get_number|bgcolor=white}} {{tt|json_get_real|bgcolor=white}} {{tt|json_get_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_get_string|header=Gets string data.|labelpos=left|content=
<pawn>
/**
* Gets string data.
*
* @param value JSON handle
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
*
* @return The number of cells written to the buffer
* @error If passed value is not a valid handle
*/
native json_get_string(const JSON:value, buffer[], maxlen);
</pawn>
}}
{{hidden|id=json_get_number|header=Gets a number.|labelpos=left|content=
<pawn>
/**
* Gets a number.
*
* @param value JSON handle
*
* @return Number
* @error If passed value is not a valid handle
*/
native json_get_number(const JSON:value);
</pawn>
}}
{{hidden|id=json_get_real|header=Gets a real number.|labelpos=left|content=
<pawn>
/**
* Gets a real number.
*
* @param value JSON handle
*
* @return Real number
* @error If passed value is not a valid handle
*/
native Float:json_get_real(const JSON:value);
</pawn>
}}
{{hidden|id=json_get_bool|header=Gets a boolean value.|labelpos=left|content=
<pawn>
/**
* Gets a boolean value.
*
* @param value JSON handle
*
* @return Boolean value
* @error If passed value is not a valid handle
*/
native bool:json_get_bool(const JSON:value);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Array}}
|-
| style="padding: 0.4em;" | {{tt|json_array_get_value|bgcolor=white}} {{tt|json_array_get_string|bgcolor=white}} {{tt|json_array_get_number|bgcolor=white}} {{tt|json_array_get_real|bgcolor=white}} {{tt|json_array_get_bool|bgcolor=white}} {{tt|json_array_get_count|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_array_get_value|header=Gets a value from the array.|labelpos=left|content=
<pawn>
/**
* Gets a value from the array.
*
* @note Needs to be freed using json_free() native.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
*
* @return JSON handle, Invalid_JSON if error occurred
* @error If passed handle is not a valid array
*/
native JSON:json_array_get_value(const JSON:array, index);
</pawn>
}}
{{hidden|id=json_array_get_string|header=Gets string data from the array.|labelpos=left|content=
<pawn>
/**
* Gets string data from the array.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
*
* @return The number of cells written to the buffer
* @error If passed handle is not a valid array
*/
native json_array_get_string(const JSON:array, index, buffer[], maxlen);
</pawn>
}}
{{hidden|id=json_array_get_number|header=Gets a number from the array.|labelpos=left|content=
<pawn>
/**
* Gets a number from the array.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
*
* @return The number as integer
* @error If passed handle is not a valid array
*/
native json_array_get_number(const JSON:array, index);
</pawn>
}}
{{hidden|id=json_array_get_real|header=Gets a real number from the array.|labelpos=left|content=
<pawn>
/**
* Gets a real number from the array.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
*
* @return The number as float
* @error If passed handle is not a valid array
*/
native Float:json_array_get_real(const JSON:array, index);
</pawn>
}}
{{hidden|id=json_array_get_bool|header=Gets a boolean value from the array.|labelpos=left|content=
<pawn>
/**
* Gets a boolean value from the array.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
*
* @return Boolean value
* @error If passed handle is not a valid array
*/
native bool:json_array_get_bool(const JSON:array, index);
</pawn>
}}
{{hidden|id=json_array_get_count|header=Gets count of the elements in the array.|labelpos=left|content=
<pawn>
/**
* Gets count of the elements in the array.
*
* @param array Array handle
*
* @return Number of elements in the array
* @error If passed handle is not a valid array
*/
native json_array_get_count(const JSON:array);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_array_replace_value|bgcolor=white}} {{tt|json_array_replace_string|bgcolor=white}} {{tt|json_array_replace_number|bgcolor=white}} {{tt|json_array_replace_real|bgcolor=white}} {{tt|json_array_replace_bool|bgcolor=white}} {{tt|json_array_replace_null|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_array_replace_value|header=Replaces an element in the array with value.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with value.
*
* @param array Array handle
* @param index Position in the array to be replaced
* @param value JSON handle to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_value(JSON:array, index, const JSON:value);
</pawn>
}}
{{hidden|id=json_array_replace_string|header=Replaces an element in the array with string data.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with string data.
*
* @param array Array handle
* @param index Position in the array to be replaced
* @param string String to copy
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_string(JSON:array, index, const string[]);
</pawn>
}}
{{hidden|id=json_array_replace_number|header=Replaces an element in the array with number.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with number.
*
* @param array Array handle
* @param index Position in the array to be replaced
* @param number Number to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_number(JSON:array, index, number);
</pawn>
}}
{{hidden|id=json_array_replace_real|header=Replaces an element in the array with real number.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with real number.
*
* @param array Array handle
* @param index Position in the array to be replaced
* @param number Real number to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_real(JSON:array, index, Float:number);
</pawn>
}}
{{hidden|id=json_array_replace_bool|header=Replaces an element in the array with boolean value.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with boolean value.
*
* @param array Array handle
* @param index Position in the array to be replaced
* @param boolean Boolean value to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_bool(JSON:array, index, bool:boolean);
</pawn>
}}
{{hidden|id=json_array_replace_null|header=Replaces an element in the array with null.|labelpos=left|content=
<pawn>
/**
* Replaces an element in the array with null.
*
* @param array Array handle
* @param index Position in the array to be replaced
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_replace_null(JSON:array, index);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_array_append_value|bgcolor=white}} {{tt|json_array_append_string|bgcolor=white}} {{tt|json_array_append_number|bgcolor=white}} {{tt|json_array_append_real|bgcolor=white}} {{tt|json_array_append_bool|bgcolor=white}} {{tt|json_array_append_null|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_arrayjson_array_append_value_replace_null|header=Appends a value in the array.|labelpos=left|content=
<pawn>
/**
* Appends a value in the array.
*
* @param array Array handle
* @param value JSON handle to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_value(JSON:array, const JSON:value);
</pawn>
}}
{{hidden|id=json_array_append_string|header=Appends string data in the array.|labelpos=left|content=
<pawn>
/**
* Appends string data in the array.
*
* @param array Array handle
* @param string String to copy
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_string(JSON:array, const string[]);
</pawn>
}}
{{hidden|id=json_array_append_number|header=Appends a number in the array.|labelpos=left|content=
<pawn>
/**
* Appends a number in the array.
*
* @param array Array handle
* @param number Number to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_number(JSON:array, number);
</pawn>
}}
{{hidden|id=json_array_append_real|header=Appends a real number in the array.|labelpos=left|content=
<pawn>
/**
* Appends a real number in the array.
*
* @param array Array handle
* @param number Real number to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_real(JSON:array, Float:number);
</pawn>
}}
{{hidden|id=json_array_append_bool|header=Appends a boolean value in the array.|labelpos=left|content=
<pawn>
/**
* Appends a boolean value in the array.Appends a boolean value in the array.
*
* @param array Array handle
* @param boolean Boolean value to set
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_bool(JSON:array, bool:boolean);
</pawn>
}}
{{hidden|id=json_array_append_null|header=Appends a null in the array.|labelpos=left|content=
<pawn>
/**
* Appends a null in the array.
*
* @param array Array handle
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_append_null(JSON:array);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_array_remove|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_array_remove|header=Removes an element from the array.|labelpos=left|content=
<pawn>
/**
* Removes an element from the array.
*
* @note Order of values in array may change during execution.
*
* @param array Array handle
* @param index Position in the array (starting from 0)
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_remove(JSON:array, index);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_array_clear|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_array_clear|header=Removes all elements from the array.|labelpos=left|content=
<pawn>
/**
* Removes all elements from the array.
*
* @param array Array handle
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid array
*/
native bool:json_array_clear(JSON:array);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Object}}
|-
| style="padding: 0.4em;" | {{tt|json_object_get_value|bgcolor=white}} {{tt|json_object_get_string|bgcolor=white}} {{tt|json_object_get_number|bgcolor=white}} {{tt|json_object_get_real|bgcolor=white}} {{tt|json_object_get_bool|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_get_value|header=Gets a value from the object.|labelpos=left|content=
<pawn>
/**
* Gets a value from the object.
*
* @note Needs to be freed using json_free() native.
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return JSON handle, Invalid_JSON if error occurred
* @error If passed handle is not a valid object
*/
native JSON:json_object_get_value(const JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_get_string|header=Gets string data from the object.|labelpos=left|content=
<pawn>
/**
* Gets string data from the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
* @param dot_not True to use dot notation, false to not
*
* @return The number of cells written to the buffer
* @error If passed handle is not a valid object
*/
native json_object_get_string(const JSON:object, const name[], buffer[], maxlen, bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_get_number|header=Gets a number from the object.|labelpos=left|content=
<pawn>
/**
* Gets a number from the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return Number
* @error If passed handle is not a valid object
*/
native json_object_get_number(const JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_get_real|header=Gets a real number from the object.|labelpos=left|content=
<pawn>
/**
* Gets a real number from the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return Real number
* @error If passed handle is not a valid object
*/
native Float:json_object_get_real(const JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_get_bool|header=Gets a boolean value from the object.|labelpos=left|content=
<pawn>
/**
* Gets a boolean value from the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return Boolean value
* @error If passed handle is not a valid object
*/
native bool:json_object_get_bool(const JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_get_count|bgcolor=white}} {{tt|json_object_get_name|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_get_count|header=Gets count of the keys in the object.|labelpos=left|content=
<pawn>
/**
* Gets count of the keys in the object.
*
* @param object Object handle
*
* @return Keys count
* @error If passed handle is not a valid object
*/
native json_object_get_count(const JSON:object);
</pawn>
}}
{{hidden|id=json_object_get_name|header=Gets name of the object's key.|labelpos=left|content=
<pawn>
/**
* Gets name of the object's key.
*
* @param object Object handle
* @param index Position from which get key name
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
*
* @return The number of cells written to the buffer
* @error If passed handle is not a valid object
*/
native json_object_get_name(const JSON:object, index, buffer[], maxlen);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_get_value_at|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_get_value_at|header=Gets a value at the specified position from the object.|labelpos=left|content=
<pawn>
/**
* Gets a value at the specified position from the object.
*
* @note Needs to be freed using json_free() native.
*
* @param object Object handle
* @param index Position from which get key name
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
*
* @return The number of cells written to the buffer
* @error If passed handle is not a valid object
*/
native JSON:json_object_get_value_at(const JSON:object, index);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_has_value|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_has_value|header=Checks if the object has a value with a specific name and type.|labelpos=left|content=
<pawn>
/**
* Checks if the object has a value with a specific name and type.
*
* @param object Object handle
* @param name Key name
* @param type Type of value, if JSONError type will not be checked
* @param dot_not True to use dot notation, false to not
*
* @return True if has, false if not
* @error If passed handle is not a valid object
*/
native bool:json_object_has_value(const JSON:object, const name[], JSONType:type = JSONError, bool:dot_not = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_set_value|bgcolor=white}} {{tt|json_object_set_string|bgcolor=white}} {{tt|json_object_set_number|bgcolor=white}} {{tt|json_object_set_real|bgcolor=white}} {{tt|json_object_set_bool|bgcolor=white}} {{tt|json_object_set_null|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_set_value|header=Sets a value in the object.|labelpos=left|content=
<pawn>
/**
* Sets a value in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param value JSON handle to set
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_value(JSON:object, const name[], const JSON:value, bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_set_string|header=Sets string data in the object.|labelpos=left|content=
<pawn>
/**
* Sets string data in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param string String to copy
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_string(JSON:object, const name[], const string[], bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_set_number|header=Sets a number in the object.|labelpos=left|content=
<pawn>
/**
* Sets a number in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param number Number to set
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_number(JSON:object, const name[], number, bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_set_real|header=Sets a real number in the object.|labelpos=left|content=
<pawn>
/**
* Sets a real number in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param number Real number to set
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_real(JSON:object, const name[], Float:number, bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_set_bool|header=Sets a boolean value in the object.|labelpos=left|content=
<pawn>
/**
* Sets a boolean value in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param boolean Boolean value to set
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_bool(JSON:object, const name[], bool:boolean, bool:dot_not = false);
</pawn>
}}
{{hidden|id=json_object_set_null|header=Sets a null in the object.|labelpos=left|content=
<pawn>
/**
* Sets a null in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
* @note It also removes the old value if any.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_set_null(JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_remove|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_remove|header=Removes a key and its value in the object.|labelpos=left|content=
<pawn>
/**
* Removes a key and its value in the object.
*
* @note If dot notation is used some values may be inaccessible
* because valid names in JSON can contain dots.
*
* @param object Object handle
* @param name Key name
* @param dot_not True to use dot notation, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_remove(JSON:object, const name[], bool:dot_not = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_object_clear|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_object_clear|header=Removes all keys and their values in the object.|labelpos=left|content=
<pawn>
/**
* Removes all keys and their values in the object.
*
* @param object Object handle
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid object
*/
native bool:json_object_clear(JSON:object);
</pawn>
}}
|-
| style="padding: 0.4em; text-align: center; background-color: white;" colspan="2" | {{color|steelblue|Serialization}}
|-
| style="padding: 0.4em;" | {{tt|json_serial_size|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_serial_size|header=Gets size of serialization.|labelpos=left|content=
<pawn>
/**
* Gets size of serialization.
*
* @param value JSON handle
* @param pretty True to count size for pretty format, false to not
* @param null_byte True to include null byte, false to not
*
* @return Size of serialized string
* @error If passed handle is not a valid value
*/
native json_serial_size(const JSON:value, bool:pretty = false, bool:null_byte = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_serial_to_string|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_serial_to_string|header=Copies serialized string to the buffer.|labelpos=left|content=
<pawn>
/**
* Copies serialized string to the buffer.
*
* @param value JSON handle
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of the buffer
* @param pretty True to format pretty JSON string, false to not
*
* @return The number of cells written to the buffer
* @error If passed handle is not a valid value
*/
native json_serial_to_string(const JSON:value, buffer[], maxlen, bool:pretty = false);
</pawn>
}}
|-
| style="padding: 0.4em;" | {{tt|json_serial_to_file|bgcolor=white}}
| style="padding: 0.4em;" | {{hidden|id=json_serial_to_file|header=Copies serialized string to the file.|labelpos=left|content=
<pawn>
/**
* Copies serialized string to the file.
*
* @param value JSON handle
* @param file Path to the file
* @param pretty True to format pretty JSON string, false to not
*
* @return True if succeed, false otherwise
* @error If passed handle is not a valid value
*/
native bool:json_serial_to_file(const JSON:value, const file[], bool:pretty = false);
</pawn>
}}
|}

{{alert|success|Constants & Macros:|{{hidden|id=json_example|labelonly=yes}}|opt=full-border}}
{{hidden|id=json_example|contentonly=yes|content=
<pawn>
/*
* JSON types
*/
enum JSONType
{
JSONError = -1,
JSONNull = 1,
JSONString = 2,
JSONNumber = 3,
JSONObject = 4,
JSONArray = 5,
JSONBoolean = 6
};

/*
* JSON invalid handle
*/
enum JSON
{
Invalid_JSON = -1
}

/**
* Helper macros for checking type
*/
#define json_is_object(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONObject)
#define json_is_array(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONArray)
#define json_is_string(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONString)
#define json_is_number(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONNumber)
#define json_is_bool(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONBoolean)
#define json_is_null(%1) (%1 != Invalid_JSON && json_get_type(%1) == JSONNull)
#define json_is_true(%1) (%1 != Invalid_JSON && json_is_bool(%1) && json_get_bool(%1))
#define json_is_false(%1) (%1 != Invalid_JSON && json_is_bool(%1) && !json_get_bool(%1))
</pawn>
}}

Events (SourceMod Scripting)

2016-05-05T23:00:55Z

Psychonic: /* Rewriting Events */

:''To view all the events, click [[Game Events (Source)|here]].''

Events are short, named messages sent by the server. Although they are used for internal message passing, they are also networked to clients.

All event natives are found in <tt>scripting/include/events.inc</tt>.

=Introduction=
Events are documented in <tt>.res</tt> files under a mod's <tt>resource</tt> folder. The "default" events are located in <tt>hl2/resource/gameevents.res</tt> and <tt>hl2/resource/serverevents.res</tt>. Mods can extend these events with their own.

For example, let's look at <tt>player_death</tt> from <tt>hl2/resource/gameevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
}</pre>

Counter-Strike:Source extends this definition in <tt>cstrike/resource/modevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
"weapon" "string" // weapon name killer used
"headshot" "bool" // signals a headshot
}</pre>

Note that the event is structured in the following format:
<pre>"name"
{
"key1" "valueType1"
"key2" "valueType2"
...
}</pre>

=Sending Events=
Events are very easy to send. For example, let's say we want to send a death message using the <tt>player_death</tt> event from above. For Counter-Strike:Source, this would look like:

<pawn>void SendDeathMessage(int attacker, int victim, const char[] weapon, bool headshot)
{
Event event = CreateEvent("player_death");
if (event == null)
{
return;
}

event.SetInt("userid", GetClientUserId(victim));
event.SetInt("attacker", GetClientUserId(attacker));
event.SetString("weapon", weapon);
event.SetBool("headshot", headshot);
event.Fire();
}</pawn>

Notes:
*You don't need to call <tt>CloseHandle()</tt>, <tt>FireEvent()</tt> does this for us.
*Even though "userid" and "attacker" are shorts, we set them as ints. The term "short" is only used to tell the engine how many bytes of the integer are needed to be networked.
*It is possible for event creation to fail; this can happen if the event does not exist, or nothing is hooking the event. Thus, you should always make sure <tt>CreateEvent</tt> calls return a valid Event handle.
*Most events use client userids instead of client indexes.
*By default, <tt>FireEvent()</tt> broadcasts messages to clients. This can be prevented by passing <tt>dontBroadcast</tt> as true.

=Hooking Events=
When hooking an event, there are three modes to choose from:
*<tt>Pre</tt> - Hook the event before it is fired.
*<tt>Post</tt> - Hook the event after it is fired.
*<tt>Post_NoCopy</tt> - Hook the event, but do not save any of its information (special optimization).

Hooking an event is usually done for one of the following goals. To get an idea of which mode to use, see the list below each goal:
*Blocking the event (preventing it from being fired)
**'''Always <tt>Pre</tt>'''
*Rewriting the event (changing its parameters)
**'''Always <tt>Pre</tt>'''
*Acting upon the event (doing something once the event is completed)
**'''<tt>Pre</tt>''' if your action must come before the mod's action.
**'''<tt>Post</tt>''' if your action must come after the mod's action.
**'''<tt>PostNoCopy</tt>''' if your action is <tt>Post</tt> and only requires the event name.

As always, you do not need to unhook events when your plugin unloads. They are automatically removed.

==Blocking Events==
Blocking events is the easiest thing to do. Let's say we want to block death events that are headshots:

<pawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre);
}

public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
if (event.GetBool("headshot"))
{
return Plugin_Handled;
}
return Plugin_Continue;
}</pawn>

'''Note:''' Blocking events does not necessarily block actions like damaging players.

==Rewriting Events==
Rewriting events is just as easy -- events can be modified in pre hooks. For example, say we want to remove headshots from all events:

<pawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre);
}

public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
event.SetBool("headshot", false);
return Plugin_Continue;
}</pawn>

==Post Hooks==
Post hooks are default, and will usually be the most common usage. For example, say we want to print a message to every client that dies:

<pawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
char weapon[64];
int victimId = event.GetInt("userid");
int attackerId = event.GetInt("attacker");
bool headshot = event.GetBool("headshot");
event.GetString("weapon", weapon, sizeof(weapon));

char name[64];
int victim = GetClientOfUserId(victimId);
int attacker = GetClientOfUserId(attackerId);
GetClientName(attacker, name, sizeof(name));

PrintToConsole(victim,
"You were killed by \"%s\" (weapon \"%s\") (headshot \"%d\")",
name,
weapon,
headshot);
}</pawn>

This will print a message to a player's console telling them who killed them, with what weapon, and whether it was a headshot or not.

Note that the return value for post hooks is ignored, so the <tt>Action</tt> tag is not needed.

==PostNoCopy Hooks==
Lastly, there are some hooks where the only piece of information needed is the name of the event. <tt>PostNoCopy</tt> is a special optimization for this case. When transitioning from <tt>Pre</tt> to <tt>Post</tt>, SourceMod must duplicate the event and all of its key/value pairs. <tt>PostNoCopy</tt> prevents that sequence from happening.

For example, let's say we want to find when a certain sequence of events is called.

<pawn>public void OnPluginStart()
{
HookEvent("game_newmap", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_start", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_end", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_message", GameEvents, EventHookMode_PostNoCopy);
}

public void GameEvents(Event event, const char[] name, bool dontBroadcast)
{
PrintToServer("Event has been fired (event \"%s\") (nobcast \"%d\")", name, dontBroadcast);
}</pawn>

Note that like normal <tt>Post</tt> hooks, there is no return value needed. However, the <tt>event</tt> parameter for <tt>PostNoCopy</tt> will '''always''' be equal to <tt>null</tt>. Thus, the <tt>name</tt> parameter must be used instead of <tt>event.GetName</tt>.

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Compiling libprotobuf

2016-01-09T14:47:12Z

Psychonic: Undo revision 10097 by Psychonic (talk)

Examples for compiling a 32-bit libprotobuf and other protobuf libraries using the protobuf-2.5.0 source.

''For Dota 2, replace version 2.5.0 with 2.6.1.''

''Also note that the Protobuf source has moved to [http://www.github.com/google/protobuf GitHub]. Some of the below links may be outdated.''

==Windows==
The following was tested on Windows 8.1 with Visual Studio 2013. Not all projects built after conversion, but only libprotobuf and dependencies were necessary.

* Download protobuf-2.5.0.zip from https://code.google.com/p/protobuf/downloads/list
* Extract and navigate to protobuf-2.5.0/vsprojects/
* Open protobuf.sln in the version of Visual Studio corresponding with the VC abi version that you wish to compile for.
* Walk through project conversion steps if necessary.
* Right-click the libprotobuf project and choose properties.
* In Configuration Properties > C/C++ -> Code Generation, set Runtime Library to /MT for Release or /MTd for Debug.
* If building the Debug configuration, also add _ITERATOR_DEBUG_LEVEL=0 in Configuration Properties > C/C++ > Preprocessor > Preprocessor Defintions
* Right-click the libprotobuf project and choose Build.

libprotobuf.lib will be in Release/ or Debug/, depending on build configuration.

==Linux (32-bit host)==
The following was tested on Debian 6 (Lenny) 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure CXXFLAGS="-g3 -ggdb3"
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Linux (64-bit host)==
This hasn't been tested, but ''should'' work on most or all 64-bit distributions.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=i686-pc-linux-gnu CFLAGS="-m32 -DNDEBUG" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=i686-pc-linux-gnu CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Mac==
The following was tested on OS X 10.7 (Lion) and ensures that the outputted binaries are 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-DNDEBUG -m32" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

Compiling libprotobuf

2016-01-08T13:37:37Z

Psychonic:

Examples for compiling a 32-bit libprotobuf and other protobuf libraries using the protobuf-2.5.0 source.

''For Dota 2, replace version 2.5.0 with 2.6.1.''

''Also note that the Protobuf source has moved to [http://www.github.com/google/protobuf GitHub]. Some of the below links may be outdated.''

==Windows==
The following was tested on Windows 8.1 with Visual Studio 2013. Not all projects built after conversion, but only libprotobuf and dependencies were necessary.

* Download protobuf-2.5.0.zip from https://code.google.com/p/protobuf/downloads/list
* Extract and navigate to protobuf-2.5.0/vsprojects/
* Open protobuf.sln in the version of Visual Studio corresponding with the VC abi version that you wish to compile for.
* Walk through project conversion steps if necessary.
* Right-click the libprotobuf project and choose properties.
* In Configuration Properties > C/C++ -> Code Generation, set Runtime Library to /MT for Release or /MTd for Debug.
* If building the Debug configuration, also add _ITERATOR_DEBUG_LEVEL=0 in Configuration Properties > C/C++ > Preprocessor > Preprocessor Defintions
* Right-click the libprotobuf project and choose Build.

libprotobuf.lib will be in Release/ or Debug/, depending on build configuration.

==Linux (32-bit host)==
The following was tested on Debian 6 (Lenny) 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure CFLAGS="-fvisibility=hidden" CXXFLAGS="-g3 -ggdb3"
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Linux (64-bit host)==
This hasn't been tested, but ''should'' work on most or all 64-bit distributions.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=i686-pc-linux-gnu CFLAGS="-m32 -DNDEBUG -fvisibility=hidden" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=i686-pc-linux-gnu CFLAGS="-m32 -fvisibility=hidden" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Mac==
The following was tested on OS X 10.7 (Lion) and ensures that the outputted binaries are 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-DNDEBUG -m32" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-m32 -fvisibility=hidden" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

Writing Multi-Game SourceMod Plugins

2015-11-22T13:25:23Z

Psychonic: /* Detecting Fake Deaths */

Different Source games tend to have different quirks. This page discusses the more common quirks you'll run into.

== Detecting the current game ==

In order to use what you learn from this document, you will need to detect which game the plugin is running on.

To detect the current game, use the GetEngineVersion() function, like this:

<pawn>new EngineVersion:g_EngineVersion;

// In OnPluginStart
g_EngineVersion = GetEngineVersion();
</pawn>

This isn't always necessary for games that use different events, but it's still a good idea.

== Round Start ==

Most plugin writers assume that hooking [[Generic Source Events#round_start|round_start]] will make things work on all games. Those plugin writers would be wrong.

Several games use other events instead or have behavior that needs to be taken into account.

{| border="1"
|-
! Game
! Fires round_start?
! Alternate Event
| Extra Quirks
|-
| Half-Life 2: DeathMatch
| Yes
| [[Half-Life 2: Deathmatch Events#teamplay_round_start|teamplay_round_start]]
| teamplay_round_start is only fired for Team Deathmatch
|-
| Day of Defeat: Source
| No
| [[Day of Defeat: Source Events#dod_round_start|dod_round_start]]
|
|-
| Team Fortress 2
| No
| [[Team Fortress 2 Events#teamplay_round_start|teamplay_round_start]]
| '''full_reset''' will be false if this is not the first round of a multi-round map. In Arena mode, the [[Team Fortress 2 Events#arena_round_start|arena_round_start]] event fires when players can start moving.
|-
| Counter-Strike: Global Offensive
| Yes
|
| round_start is fired during warmup round
|}

== Round End ==

[[Generic Source Events#round_end|round_end]], like round_start, isn't the same across all games.

Most of the time, '''winner''' is the team ID of the winning team: 0 for stalemate, 2 for team 1 (Combine, Allies, Terrorists, RED, or Survivors), or 3 for team 2 (Rebels, Axis, Counter-Terrorists, BLU, or Infected).

{| border="1"
|-
! Game
! Fires round_end?
! Alternate Event
! Extra Quirks
|-
| Half-Life 2: DeathMatch
| Yes
|
| winner is a userid for Deathmatch or a team ID for Team Deathmatch
|-
| Day of Defeat: Source
| No
| [[Day of Defeat: Source Events#dod_round_win|dod_round_win]]
| '''team''' is the winning team.
|-
| Team Fortress 2
| No
| See next section
| See next section
|-
| Nuclear Dawn
| No
| [[Nuclear Dawn Events#round_win|round_win]]
| '''team''' is the winning team. '''type''' is the win reason.
|}

=== Team Fortress 2 ===

Round End is so complicated in Team Fortress 2 that I'm giving it its own section. TF2 has not just one, but ''four'' different events for round end.

{| border="1"
|-
! Game Mode
! Event
| Quirks
|-
| All
| [[Team Fortress 2 Events#teamplay_round_win|teamplay_round_win]]
| '''team''' is the winning team. '''winreason''' was only [https://github.com/ValveSoftware/Source-1-Games/issues/1269#issuecomment-24618786 recently fixed] and its meaning depends on the game mode.
|-
| All but Arena or MvM
| [[Team Fortress 2 Events#teamplay_win_panel|teamplay_win_panel]]
| Win Panel screen, includes each team's score and the scores of the top 3 players. '''winning_team''' is the winning team. '''winreason''' includes captured all points, time ran out, captured flags, etc...
|-
| Arena
| [[Team Fortress 2 Events#arena_win_panel|arena_win_panel]]
| Arena Win Panel screen, includes each team's score and the scores of the top 3 players for each team. '''winning_team''' is the winning team. '''winreason''' can ''only'' be killed all players on the other team and captured point.
|-
| MvM
| [[Team Fortress 2 Events#pve_win_panel|pve_win_panel]]
| MvM Win Panel screen. '''winning_team''' is the winning team. Most data is not present in this event and is instead interpolated from the CTFPlayerResource netprops.
|}

== player_death ==
All games appear to use the player_death event, but the fields available to each game vary radically.

The quirks you need to know about are:

=== Detecting Fake Deaths ===

Team Fortress 2 introduced the concept of fake deaths. In order to detect if a death was fake, you need to do something like this:

<pawn>
// At top of file
#include <tf2_stocks>

// in player_death hook
new bool:bFake = g_EngineVersion == Engine_TF2 && (GetEventInt(event, "death_flags") & TF_DEATHFLAG_DEADRINGER);
// if bFake is true, the it was a fake death
</pawn>

== Detecting Headshots ==

Not all games support headshots, but those that do have them done differently.

=== player_death ===

Headshots can be detected in player_death similarly to this:

<pawn>
// At top of file
#include <tf2_stocks>

// in player_death hook
new bool:bHeadshot;

switch (g_EngineVersion)
{
case Engine_CSS, Engine_CSGO, Engine_L4D, Engine_L4D2:
{
bHeadshot = GetEventBool(event, "headshot");
}

case Engine_TF2:
{
bHeadshot = GetEventInt(event, "customkill") == TF_CUSTOM_HEADSHOT;
}
}

if (bHeadshot)
{
// This was a headshot, do something
}
</pawn>

Unfortunately, some games don't appear to track headshots for death (Half-Life 2: DeathMatch for example).

=== player_hurt ===
player_hurt is a bit trickier.

<pawn>

// At top of file
#include <tf2_stocks>

#define HITGROUP_HEAD 1

// in player_hurt hook
new bool:bHeadshot;

switch (g_EngineVersion)
{
case Engine_CSS, Engine_CSGO, Engine_DODS, Engine_L4D, Engine_L4D2:
{
bHeadshot = GetEventInt(event, "hitgroup") == HITGROUP_HEAD;
}

case Engine_TF2:
{
bHeadshot = GetEventInt(event, "custom") == TF_CUSTOM_HEADSHOT;
}
}

if (bHeadshot)
{
// This was a headshot, do something
}
</pawn>

As you can see, more games support detecting if a shot was a headshot in player_hurt than player_death.

=== SDKHooks TraceAttack and OnTakeDamage ===

Headshots can be detected by TraceAttack or OnTakeDamage depending on the game.

Note: Changing damage and returning Plugin_Changed for either event will change the damage the player takes.

<pawn>
// At top of file
#include <sdkhooks>
#define HITGROUP_HEAD 1

public OnClientPutInServer(client)
{
switch (g_EngineVersion)
{
case Engine_CSS, Engine_CSGO, Engine_DODS, Engine_L4D, Engine_L4D2:
{
SDKHook(client, SDKHook_TraceAttack, TraceAttack);
}

case Engine_TF2:
{
SDKHook(client, SDKHook_OnTakeDamage, OnTakeDamage);
}
}

}

public Action:TraceAttack(victim, &attacker, &inflictor, &Float:damage, &damagetype, &ammotype, hitbox, hitgroup)
{
new bool:bHeadshot = hitgroup == HITGROUP_HEAD;

if (bHeadshot)
{
// This was a headshot, do something.
}

return Plugin_Continue;
}

public Action:OnTakeDamage(victim, &attacker, &inflictor, &Float:damage, &damagetype, &weapon,
Float:damageForce[3], Float:damagePosition[3], damagecustom)

new bool:bHeadshot = damagecustom == TF_CUSTOM_HEADSHOT;

if (bHeadshot)
{
// This was a headshot, do something
}

return Plugin_Continue;
}</pawn>

SourceMod 1.7.2 Release Notes

2015-05-30T13:19:36Z

Psychonic:

SourceMod 1.7.2 is a bugfix release, further stabilizing the 1.7 branch.

For the full SourceMod 1.7 release notes, [[SourceMod 1.7.0 Release Notes|click here]].

=Changelog=

User Changes:

*Updated game compatibility for the latest CS:GO updates.
*Fixed potential crash when using SDKTools GameRules_* natives. ({{pr|330}}) (yed).
*Fixed regression in v1.7.0 causing admin-sql-threaded plugin to not properly load admins. ({{bz|6365}}) ({{pr|342}}).
*Fixed leak in plugin heap memory that could lead to "Not enough space on the heap" error. ({{bz|6370}}).

SourceMod 1.7.2 Release Notes

2015-05-30T13:18:53Z

Psychonic: Created page with "SourceMod 1.7.2 is a bugfix release, further stabilizing the 1.7 branch. For the full SourceMod 1.7 release notes, click here. =Changelog=..."

SourceMod 1.7.2 is a bugfix release, further stabilizing the 1.7 branch.

For the full SourceMod 1.7 release notes, [[SourceMod 1.7.0 Release Notes|click here]].

=Changelog=

User Changes:

*Updated game compatibility for the latest CS:GO updates.
*Fixed potential crash when using SDKTools GameRules_* natives. (PR 330) (yed).
*Fixed regression in v1.7.0 causing admin-sql-threaded plugin to not properly load admins. (bug 6365) (PR 342).
*Fixed leak in plugin heap memory that could lead to "Not enough space on the heap" error. (bug 6370).

SourceMod Release Notes

2015-05-30T13:18:02Z

Psychonic:

[[SourceMod]] Release notes for each release:

*[[SourceMod 1.7.2 Release Notes]]
*[[SourceMod 1.7.1 Release Notes]]
*[[SourceMod 1.7.0 Release Notes]]
*[[SourceMod 1.6.3 Release Notes]]
*[[SourceMod 1.6.2 Release Notes]]
*[[SourceMod 1.6.1 Release Notes]]
*[[SourceMod 1.6.0 Release Notes]]
*[[SourceMod 1.5.3 Release Notes]]
*[[SourceMod 1.5.2 Release Notes]]
*[[SourceMod 1.5.1 Release Notes]]
*[[SourceMod 1.5.0 Release Notes]]
*[[SourceMod 1.4.7 Release Notes]]
*[[SourceMod 1.4.6 Release Notes]]
*[[SourceMod 1.4.5 Release Notes]]
*[[SourceMod 1.4.4 Release Notes]]
*[[SourceMod 1.4.3 Release Notes]]
*[[SourceMod 1.4.2 Release Notes]]
*[[SourceMod 1.4.1 Release Notes]]
*[[SourceMod 1.4.0 Release Notes]]
*[[SourceMod 1.3.8 Release Notes]]
*[[SourceMod 1.3.7 Release Notes]]
*[[SourceMod 1.3.6 Release Notes]]
*[[SourceMod 1.3.5 Release Notes]]
*[[SourceMod 1.3.4 Release Notes]]
*[[SourceMod 1.3.3 Release Notes]]
*[[SourceMod 1.3.2 Release Notes]]
*[[SourceMod 1.3.1 Release Notes]]
*[[SourceMod 1.3.0 Release Notes]]
*[[SourceMod 1.2.4 Release Notes]]
*[[SourceMod 1.2.3 Release Notes]]
*[[SourceMod 1.2.2 Release Notes]]
*[[SourceMod 1.2.1 Release Notes]]
*[[SourceMod 1.2.0 Release Notes]]
*[[SourceMod 1.1.2 Release Notes]]
*[[SourceMod 1.1.1 Release Notes]]
*[[SourceMod 1.1.0 Release Notes]]
*[[SourceMod 1.0.4 Release Notes]]
*[[SourceMod 1.0.3 Release Notes]]
*[[SourceMod 1.0.2 Release Notes]]
*[[SourceMod 1.0.1 Release Notes]]
*[[SourceMod 1.0.0 Release Notes]]

Required Versions (SourceMod)

2015-05-21T22:17:18Z

Psychonic: ur

As Valve updates their games, new fixes get added to Metamod:Source and SourceMod. This page is to document the current ''minimum'' required version for specific games. If a specific snapshot isn't needed, please put Current Stable (for MM:S 1.10.x or SM 1.6.x releases) or Current Development (for MM:S 1.11.0 or 1.7.0 snapshots).

Current Stable MM:S version: '''1.10.4''' 
Current Stable SM version: '''1.7.1'''

Current Development MM:S versions: '''1.11.0''' git builds 
Current Development SM versions: '''1.8.0''' git builds

Specific Metamod:Source versions and Current Development refer to [http://www.sourcemm.net/snapshots Metamod:Source snapshots]. 
Specific SourceMod versions and Current Development refer to [http://www.sourcemod.net/snapshots.php SourceMod snapshots].

{| class="wikitable"
|-
! Game
! Metamod:Source Version
! SourceMod Version
! Extras
|-
| Alien Swarm
| Current Stable
| Current Stable
|-
| Black Mesa Source
| 1.10.5-git934
| 1.8.0-git5424
|-
| Blade Symphony
| Current Stable
| Current Stable
|-
| Bloody Good Time
| Current Stable
| Current Stable
|-
| Contagion
| Current Stable
| Current Stable
|-
| Counter-Strike: Source
| Current Stable
| Current Stable
|-
| Counter-Strike: Global Offensive
| 1.10.5-git937
| 1.7.1-git5200
| As of 2015/05/15, all SourceMod extensions need to be recompiled against the latest hl2sdk-csgo (and libstdc++).
|-
| Dark Messiah of Might & Magic
| Current Stable
| Current Stable
|-
| Day of Defeat: Source
| Current Stable
| Current Stable
|-
| DOTA 2
| Current Stable
| Current Stable
| [https://forums.alliedmods.net/showthread.php?t=209965 Dota 2 Fixups] 2.1.3 Required
|-
| EYE: Divine Cybermancy
| Current Stable
| Current Stable
|-
| Half-Life 2: DeatchMatch
| Current Stable
| Current Stable
|-
| Insurgency (2014)
| Current Stable
| Current Stable
|-
| Left 4 Dead
| Current Stable
| Current Stable
| [http://www.sourcemm.net/vdf Manually Generated metamod.vdf] Required
|-
| Left 4 Dead 2
| Current Stable
| Current Stable
|-
| Nuclear Dawn
| Current Stable
| Current Stable
|-
| Source 2006 Mods
| Current Stable
| Current Stable
| Mods: Insurgency: Modern Infantry Combat mod version
|-
| Source 2007 Mods
| Current Stable
| Current Stable
|-
| Source 2013 Mods
| Current Stable
| Current Stable
| Mods: Fistful of Frags, No More Room in Hell
|-
| Team Fortress 2
| Current Stable
| Current Stable
|}

SourceMod 1.7.1 Release Notes

2015-04-18T20:02:24Z

Psychonic:

SourceMod 1.7.1 has a few additions but is mostly a bugfix release, further stabilizing the 1.7 branch.

'''Due to some logic errors, for any plugins that were compiled with the 1.7.0 SourcePawn compiler, it is highly recommended to recompile them with the new 1.7.1 compiler.'''

For the full SourceMod 1.7 release notes, [[SourceMod 1.7.0 Release Notes|click here]].

=Changelog=

User Changes:

*Updated game compatibility for CS:GO, TF2, Dota 2, Insurgency, and Fortress Forever.
*Fixed regression causing crash in games that do not support radio menus (PR 286) (Peace-Maker).
*Fixed sm_rename not working on some games, including CS:S and CS:GO (PR 313).
*Fixed some core.cfg values being ignored on start (PR 322).
*Fixed crash when plugins close a menu handle during menu draw (PR 268)

Developer Changes:

*Added tagged TF2_SetClientTeam to provide symmetry to TF2_GetClientTeam (PR 267) (Wliu).
*Added block parameter to FindValueInArray native (PR 213) (splewis).
*Added explicit return types to forwards missing them to avoid future compatibility issues (PR 294).
*Added new SetClientName native to reliably change a player's name on any game (PR 313).
*Fixed tag mismatch warning when using SQLite_UseDatabase (bug 6310) (PR 262) (VoiDeD).
*Fixed not actually being able to block CS_OnCSWeaponDrop (bug 6334) (PR 316).
*Fixed DirExists to throw an error when passed empty string (PR 315).
*Fixed ReadUint16 on File methodmap throwing "not bound" error (PR 265).
*Fixed various include docs (PR 288) (PR 290) (PR 295).
*Fixed issues with declaring variable on same line after array (SP PR 7) (Peace-Maker).
*Fixed debug info for multidimensional strings not being written to smx (SP PR 8) (Peace-Maker).
*Fixed issues with nesting methodmap calls (bug 6329) (SP PR 11) (SP PR 13).
*Improved diagnostic given when function prototype doesn't match an existing definition (PR 291) (VoiDeD).

SourceMod 1.7.1 Release Notes

2015-04-18T20:00:56Z

Psychonic:

SourceMod 1.7.1 has a few additions but is mostly a bugfix release, further stabilizing the 1.7 branch.

'''Due to some logic errors in the 1.7.0 SourcePawn compiler, it is highly recommend to recompile any plugins compiled with it with the new 1.7.1 compiler.'''

For the full SourceMod 1.7 release notes, [[SourceMod 1.7.0 Release Notes|click here]].

=Changelog=

User Changes:

*Updated game compatibility for CS:GO, TF2, Dota 2, Insurgency, and Fortress Forever.
*Fixed regression causing crash in games that do not support radio menus (PR 286) (Peace-Maker).
*Fixed sm_rename not working on some games, including CS:S and CS:GO (PR 313).
*Fixed some core.cfg values being ignored on start (PR 322).
*Fixed crash when plugins close a menu handle during menu draw (PR 268)

Developer Changes:

*Added tagged TF2_SetClientTeam to provide symmetry to TF2_GetClientTeam (PR 267) (Wliu).
*Added block parameter to FindValueInArray native (PR 213) (splewis).
*Added explicit return types to forwards missing them to avoid future compatibility issues (PR 294).
*Added new SetClientName native to reliably change a player's name on any game (PR 313).
*Fixed tag mismatch warning when using SQLite_UseDatabase (bug 6310) (PR 262) (VoiDeD).
*Fixed not actually being able to block CS_OnCSWeaponDrop (bug 6334) (PR 316).
*Fixed DirExists to throw an error when passed empty string (PR 315).
*Fixed ReadUint16 on File methodmap throwing "not bound" error (PR 265).
*Fixed various include docs (PR 288) (PR 290) (PR 295).
*Fixed issues with declaring variable on same line after array (SP PR 7) (Peace-Maker).
*Fixed debug info for multidimensional strings not being written to smx (SP PR 8) (Peace-Maker).
*Fixed issues with nesting methodmap calls (bug 6329) (SP PR 11) (SP PR 13).
*Improved diagnostic given when function prototype doesn't match an existing definition (PR 291) (VoiDeD).

SourceMod 1.7.1 Release Notes

2015-04-18T19:52:08Z

Psychonic: Created page with "SourceMod 1.7.1 has a few additions but is mostly a minor bugfix release, quashing regressions from 1.7.0. '''Due to some logic errors in the 1.7.0 SourcePawn compiler, it is..."

SourceMod 1.7.1 has a few additions but is mostly a minor bugfix release, quashing regressions from 1.7.0.

'''Due to some logic errors in the 1.7.0 SourcePawn compiler, it is highly recommend to recompile any plugins compiled with it with the new 1.7.1 compiler.'''

For the full SourceMod 1.7 release notes, [[SourceMod 1.7.0 Release Notes|click here]].

=Changelog=

User Changes:

*Updated game compatibility for CS:GO, TF2, Dota 2, Insurgency, and Fortress Forever.
*Fixed regression causing crash in games that do not support radio menus (PR 286) (Peace-Maker).
*Fixed sm_rename not working on some games, including CS:S and CS:GO (PR 313).
*Fixed some core.cfg values being ignored on start (PR 322).
*Fixed crash when plugins close a menu handle during menu draw (PR 268)

Developer Changes:

*Added tagged TF2_SetClientTeam to provide symmetry to TF2_GetClientTeam (PR 267) (Wliu).
*Added block parameter to FindValueInArray native (PR 213) (splewis).
*Added explicit return types to forwards missing them to avoid future compatibility issues (PR 294).
*Added new SetClientName native to reliably change a player's name on any game (PR 313).
*Fixed tag mismatch warning when using SQLite_UseDatabase (bug 6310) (PR 262) (VoiDeD).
*Fixed not actually being able to block CS_OnCSWeaponDrop (bug 6334) (PR 316).
*Fixed DirExists to throw an error when passed empty string (PR 315).
*Fixed ReadUint16 on File methodmap throwing "not bound" error (PR 265).
*Fixed various include docs (PR 288) (PR 290) (PR 295).
*Fixed issues with declaring variable on same line after array (SP PR 7) (Peace-Maker).
*Fixed debug info for multidimensional strings not being written to smx (SP PR 8) (Peace-Maker).
*Fixed issues with nesting methodmap calls (bug 6329) (SP PR 11) (SP PR 13).
*Improved diagnostic given when function prototype doesn't match an existing definition (PR 291) (VoiDeD).

SourceMod Release Notes

2015-04-18T19:49:23Z

Psychonic:

[[SourceMod]] Release notes for each release:

*[[SourceMod 1.7.1 Release Notes]]
*[[SourceMod 1.7.0 Release Notes]]
*[[SourceMod 1.6.3 Release Notes]]
*[[SourceMod 1.6.2 Release Notes]]
*[[SourceMod 1.6.1 Release Notes]]
*[[SourceMod 1.6.0 Release Notes]]
*[[SourceMod 1.5.3 Release Notes]]
*[[SourceMod 1.5.2 Release Notes]]
*[[SourceMod 1.5.1 Release Notes]]
*[[SourceMod 1.5.0 Release Notes]]
*[[SourceMod 1.4.7 Release Notes]]
*[[SourceMod 1.4.6 Release Notes]]
*[[SourceMod 1.4.5 Release Notes]]
*[[SourceMod 1.4.4 Release Notes]]
*[[SourceMod 1.4.3 Release Notes]]
*[[SourceMod 1.4.2 Release Notes]]
*[[SourceMod 1.4.1 Release Notes]]
*[[SourceMod 1.4.0 Release Notes]]
*[[SourceMod 1.3.8 Release Notes]]
*[[SourceMod 1.3.7 Release Notes]]
*[[SourceMod 1.3.6 Release Notes]]
*[[SourceMod 1.3.5 Release Notes]]
*[[SourceMod 1.3.4 Release Notes]]
*[[SourceMod 1.3.3 Release Notes]]
*[[SourceMod 1.3.2 Release Notes]]
*[[SourceMod 1.3.1 Release Notes]]
*[[SourceMod 1.3.0 Release Notes]]
*[[SourceMod 1.2.4 Release Notes]]
*[[SourceMod 1.2.3 Release Notes]]
*[[SourceMod 1.2.2 Release Notes]]
*[[SourceMod 1.2.1 Release Notes]]
*[[SourceMod 1.2.0 Release Notes]]
*[[SourceMod 1.1.2 Release Notes]]
*[[SourceMod 1.1.1 Release Notes]]
*[[SourceMod 1.1.0 Release Notes]]
*[[SourceMod 1.0.4 Release Notes]]
*[[SourceMod 1.0.3 Release Notes]]
*[[SourceMod 1.0.2 Release Notes]]
*[[SourceMod 1.0.1 Release Notes]]
*[[SourceMod 1.0.0 Release Notes]]

Releasing Products

2015-04-04T13:45:41Z

Psychonic: /* Updating the SourceMod Site */

This is an internal page for doing AlliedModders product releases.

=Making Builds=
<ol>
<li>Once you are '''absolutely sure''' the product is ready for a release...</li>
<li>Jump to a Linux system, check out the source tree.</li>
<li>Update the changelog (<tt>changelog.txt</tt> for SourceMod, <tt>support/changelog.txt</tt> for Metamod:Source).</li>
<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).
<li>Edit <tt>product.version</tt> to remove the -dev tag.</li>
<li>Commit and push the changes.</li>
<li>Push. Watch the waterfall page until builds are complete.</li>
</ol>

=Post-Build Work=
<ol>
<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>
<li>Install the packages on both Linux and Windows. '''MAKE SURE THE VERSIONS ARE CORRECT. THERE SHOULD BE NO -dev TAG.'''
 
Metamod:Source checks:
<pre>
meta version
</pre>
SourceMod checks:
<pre>
sm plugins list
sm exts list
sm version
</pre></li>
<li>If the versions are not correct, do not release.</li>
<li>For SourceMod, you need to add the language translation packs and update the GeoLite Country data file.
 
'''If this is a major release (1.X.0), there is no prior pack. Make one:'''
<ol>
<li>Extract both the tar.gz and zip files to separate folders.</li>
<li>Visit the [http://www.sourcemod.net/translator/?go=translate&op=status translator status page].</li>
<li>Click "export languages.cfg" - save the new version to <tt>addons/sourcemod/configs/</tt>, overwriting the old one.</li>
<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>
<li>Download the latest GeoLite Country binary file from http://dev.maxmind.com/geoip/geolite</li>
<li>Extract the GeoIP.dat and replace the existing copy in addons/sourcemod/configs/geoip</li>
<li>Repackage the folders using the correct compression types (.tar.gz for Linux, .zip for Windows and Mac).</li>
</ol>
If this is a minor release (1.X.Y where Y != 0), there is already a prior pack. Add it in:
<ol>
<li>Extract both the tar.gz and zip files to separate folders.</li>
<li>Download the last major release from the same branch as this release.</li>
<li>Copy the <tt>addons/sourcemod/configs/languages.cfg</tt> file from the old release over the new one.</li>
<li>Copy the <tt>addons/sourcemod/translations/</tt> sub-folders from the old release over to the new one.</li>
<li>Download the latest GeoLite Country binary file from http://dev.maxmind.com/geoip/geolite</li>
<li>Extract the GeoIP.dat and replace the existing copy in addons/sourcemod/configs/geoip</li>
<li>Repackage the folders using the correct compression types (.tar.gz for Linux, .zip for Windows).</li>
</ol>
<li>The build is done!</li>
</ol>

=Releasing to Mirrors=
<ol>
<li>Log into web01 as yourself. Upload your final builds to your home directory.</li>
<li>Run:
<pre>
/scripts/amjump mirror
cd /scripts/mirror
</pre>
</li>
<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>
<li>Mirror distribution is done with the following command:
<pre>
./mirror.pl <projectID> <releaseName> <file>
</pre>
Metamod:Source's ID is 4, SourceMod's ID is 2. For example, these commands mirrored the Metamod:Source 1.8.7 release:
<pre>
./mirror.pl 4 1.8.7 mmsource-1.8.7-linux.tar.gz
./mirror.pl 4 1.8.7 mmsource-1.8.7-windows.zip
./mirror.pl 4 1.8.7 mmsource-1.8.7-mac.zip
</pre>
These commands mirrored the SourceMod 1.4.0 release:
<pre>
./mirror.pl 2 1.4.0 sourcemod-1.4.0-linux.tar.gz
./mirror.pl 2 1.4.0 sourcemod-1.4.0-windows.zip
./mirror.pl 2 1.4.0 sourcemod-1.4.0-mac.zip
</pre>
</li>
<li>Type <tt>exit</tt> to get back to your user account. You're done!</li>
</ol>

=Cleaning up the Tree=
It's time to make sure the tree is set for future development.

<ol>
<li>Run <tt>git tag</tt> on the last revision of the release. Usually this is the changeset that bumped versions, and usually this is the branch <tt>tip</tt>. After you have tagged the changeset, push the tag upstream. For example, Metamod:Source:
<pre>git tag -a mmsource-1.7.2 -m "Metamod:Source 1.7.2"
git push origin mmsource-1.7.2</pre>
SourceMod:
<pre>git tag -a sourcemod-1.1.2 -m "SourceMod 1.1.2"
git push origin sourcemod-1.1.2</pre>
</li>
<li>Bump the minor version in <tt>product.version</tt>. Don't forget to add -dev.</li>
<li>Change the <tt>tools/buildbot/build_type</tt> (SourceMod) or <tt>support/buildbot/build_type</tt> (Metamod:Source) contents back to "dev".</li>
<li>Commit and push.</li>
</ol>

=Updating the SourceMod Site=
<ol>
<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>
<li>Jump to the sourcemod account by logging into web01 as yourself:
<pre>
/scripts/amjump sourcemod
cd /groups/sourcemod
</pre>
</li>
<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>
<li>Update ~/compiler-1.x to the latest minor version, where x is the major version number.</li>
<li>If a new major version, update vbcompiler.php on the SourceMod site to set the new default and as an explicit check to allow the former default version.</li>
<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>
<li>Exit out of the sourcemod account.</li>
<li>If a new major version, find someone with access to edit the forums if not yourself, and have the new compiler version added to editpost.php and newthread.php for the dropdown when editing plugin posts.</li>
<li><s>Find someone with access to the smdocs user if not yourself, and have the api docs updated by logging in as smdocs, navigating to ~/scripts/sync_api, replace the contents of the build directory with the new SM release, and run the run.sh script.</s> TODO: How do we update new api site?</li>
<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>
</ol>

=Updating the Metamod:Source Site=
<ol>
<li>Jump to the alliedmodders account by logging into web01 as yourself:
<pre>
/scripts/amjump alliedmodders
cd /groups/alliedmodders/hub/amhub
</pre>
</li>
<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>
<li>Edit the <tt>templates/mmsource/navbar.html</tt> file and replace all instances of the old version with the new one.
<li>Run the following command:
<pre>
touch ../run/apache.wsgi
</pre>
</li>
<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>
<li>Exit out of the alliedmodders account.</li>
</ol>

=Updating Translations=
This section applies to SourceMod major releases. In order to update the translator tool, shell in as the "sourcemod" user. Find the /scripts/translation folder in the sourcemod group homedir. Run the following steps:
* cd sourcemod
* git pull
* cd ..
* ./sync_lang_files.pl sourcemod/translations

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.

SourcePawn Transitional Syntax

2015-03-22T12:43:44Z

Psychonic: /* Constructors and Destructors */

__FORCETOC__
We would like to give our users a more modern language. Pawn is showing its age; manual memory management, buffers, tags, and lack of object-oriented API are very frustrating. We can't solve everything all at once, but we can begin to take steps in the right direction.

SourceMod 1.7 introduces a ''Transitional API''. It is built on a new ''Transitional Syntax'' in SourcePawn, which is a set of language tools to make Pawn feel more modern. In particular, it allows developers to use older APIs in an object-oriented manner, without breaking compatibility. Someday, if and when SourcePawn can become a full-fledged modern language, the transitional API will making porting efforts very minimal.

The transitional API has the following major features and changes:
* New Declarators - A cleaner way of declaring variables, similar to Java and C#.
* Methodmaps - Object-oriented wrappers around older APIs.
* Real Types - SourcePawn now has "int", "float", "bool", "void", and "char" as real types.
* <tt>null</tt> - A new, general keyword to replace <tt>INVALID_HANDLE</tt>.

=New Declarators=
Developers familiar with pawn will recognize Pawn's original declaration style:
<pawn>
new Float:x = 5.0;
new y = 7;
</pawn>

In the transitional syntax, this can be reworded as:
<pawn>
float x = 5.0;
int y = 7;
</pawn>

The following builtin tags now have types:
* <tt>Float:</tt> is <tt>float</tt>.
* <tt>bool:</tt> is <tt>bool</tt>.
* <tt>_:</tt> (or no tag) is <tt>int</tt>.
* <tt>String:</tt> is <tt>char</tt>.
* <tt>void</tt> can now be used as a return type for functions.

===Rationale===
In the old style, tagged variables are not real types. <tt>Float:x</tt> does not indicate a float-typed variable, it indicates a 32-bit "cell" tagged as a float. It is possible to remove the tag or change the tag, which while flexible, is dangerous and confusing. The syntax itself is also problematic. The parser does not have the ability to identify characters in between the tag name and the colon. Internally, the compiler cannot represent values that are not exactly 32-bit.

The takeaway message is: there is no sensible way to represent a concept like "int64" or "X is a type that represents an array of floats". The tagging grammar makes it too awkward, and the compiler itself is incapable of attaching such information to a tag. We can't fix that right away, but we can begin to deprecate the tag system via a more normal declaration syntax.

An easy example to see why this is necessary, is the weirdness in expressing something like this with tags:
<pawn>
native float[3] GetEntOrigin();
</pawn>

''Note on the <tt>String</tt> tag:'' The introduction of <tt>char</tt> might initially seem confusing. The reason for this is that in the future, we would like to introduce a true "string" type that acts as an object, like strings in most other languages. The existing behavior in Pawn is an array of characters, which is much lower-level. The renaming clarifies what the type really is, and leaves the door open for better types in the future.

==Arrays==
The new style of declaration disambiguates between two kinds of arrays. Pawn has ''indeterminate arrays'', where the size is not known, and ''determinate arrays'', where the size is known. We refer to these as "dynamic" and "fixed-length" arrays, respectively.

'''A fixed-length array is declared by placing brackets after a variable name'''. For example:
<pawn>
int CachedStuff[1000];
int PlayerData[MAXPLAYERS + 1] = { 0, ... };
int Weapons[] = { WEAPON_AK47, WEAPON_GLOCK, WEAPON_KNIFE };
</pawn>

In these examples, the array size is fixed. The size is known ahead of time and cannot change. When using brackets in this position, the array size must be specified, either via an explicit size or inferred from an initial value.

A dynamic-length array has the brackets '''before the variable name''', that is, '''after the type'''. The most common case is when specifying functions that take an array as input:
<pawn>
native void SetPlayerName(int player, const char[] name);
</pawn>

Here, we are specifying that the length of <tt>name</tt> is not always known - it could be anything.

Dynamic arrays can also be created in local scopes. For example,
<pawn>
void FindPlayers()
{
int[] players = new int[MaxClients + 1];
}
</pawn>

This allocates a new array of the given size and places a reference in <tt>players</tt>. The memory is automatically freed when no longer in use.

It is illegal to initialize a fixed-length array with an indeterminate array, and it is illegal to initialize a dynamic array with a fixed-array. It is also illegal to specify a fixed size on a dynamic length array.

For the most part, this does not change existing Pawn semantics. It is simply new syntax intended to clarify the way arrays work.

===Rationale===
In the original syntax, there was a subtle difference in array declaration:
<tt>
new array1[MAXPLAYERS + 1];
new array2[MaxClents + 1];
</tt>

Here, <tt>array1</tt> and <tt>array2</tt> are very different types: the first is an <tt>int[65]</tt> and the latter is an <tt>int[]</tt>. However, there is no syntactic difference: the compiler has to deduce whether the size expression is constant to determine the type. The new syntax clearly and explicitly disambiguates these cases, so in the future when we introduce fully dynamic and flexible arrays, we're less likely to break existing code.

This may result in some confusion. Hopefully won't matter long term, as once we have true dynamic arrays, fixed arrays will become much less useful and more obscure.

The rationale for restricting initializers is similar. Once we have true dynamic arrays, the restrictions will be lifted. In the meantime, we need to make sure we're limited to semantics that won't have subtle differences in the future.

==Examples==
<pawn>
float x = 5.0; // Replacement for Float
int y = 4; // Replacement for new
char name[32]; // Replacement for String

void DoStuff(float x, int y, char[] name, int length) {
Format(name, length, "%f %d", x, y);
}
</pawn>

==View As==
A new operator is available for reinterpreting the bits in a value as another type. This operator is called <tt>view_as</tt>. It is not a safe cast, in that, it can transform one type to another even if the actual value does not conform to either.

In pre-transitional syntax, this was called "retagging". Retagging does not support new-style types, which is why this operator has been introduced. Example of before and after code:

<pawn>
// Before:
float x = Float:array.Get(i);

// After:
float y = view_as<float>(array.Get(i));
</pawn>

It is worth reiterating that this is not a cast. If the value in the array is not a float, then when "viewed as" a float it will probably look very odd.

==Grammar==
The new and old declaration grammar is below.

<pre>
return-type ::= return-old | return-new
return-new ::= type-expr new-dims? // Note, dims not yet supported.
return-old ::= old-dims? label?

argdecl ::= arg-old | arg-new
arg-new ::= "const"? type-expr '&'? symbol old-dims? ('=' arg-init)?
arg-old ::= "const"? tags? '&'? symbol old-dims? ('=' arg-init)?

vardecl ::= var-old | var-new
var-new ::= var-new-prefix type-expr symbol old-dims?
var-new-prefix ::= "static" | "const"
var-old ::= var-old-prefix tag? symbol old-dims?
var-old-prefix ::= "new" | "decl" | "static" | "const"

global ::= global-old | global-new
global-new ::= storage-class* type-expr symbol old-dims?
global-old ::= storage-class* tag? symbol old-dims?

storage-class ::= "public" | "static" | "const" | "stock"

type-expr ::= (builtin-type | symbol) new-dims?
builtin-type ::= "void"
| "int"
| "float"
| "char"
| "bool"

tags ::= tag-vector | tag
tag-vector ::= '{' symbol (',' symbol)* '}' ':'
tag ::= label

new-dims ::= ('[' ']')*
old-dims ::= ('[' expr? ']')+

label ::= symbol ':'
symbol ::= [A-Za-z_]([A-Za-z0-9_]*)
</pre>

Also note, there is no equivalent of <tt>decl</tt> in the new declarator syntax. <tt>decl</tt> is considered to be dangerous and unnecessary. If an array's zero initialization is too costly, consider making it static or global.

=Methodmaps=
==Introduction==
Methodmaps are simple: they attach methods onto an enum. For example, here is our legacy API for Handles:

<pawn>
native CloneHandle(Handle handle);
native CloseHandle(Handle handle);
</pawn>

This is a good example of our legacy API. Using it generally looks something like:
<pawn>
Handle array = CreateAdtArray();
PushArrayCell(array, 4);
CloseHandle(array);
</pawn>

Gross! A Methodmap can clean it up by attaching functions to the <tt>Handle</tt> tag, like this:
<pawn>
methodmap Handle {
public Clone() = CloneHandle;
public Close() = CloseHandle;
};
</pawn>

Now, our earlier array code can start to look object-oriented:
<pawn>
Handle array = CreateAdtArray();
PushArrayCell(array, 4);
array.Close();
</pawn>

With a full methodmap for Arrays, for example,
<pawn>
methodmap ArrayList < Handle
{
public native ArrayList(); // constructor
public native void Push(any value);
};
</pawn>

We can write even more object-like code:
<pawn>
ArrayList array = new ArrayList();
array.Push(4);
delete array;
</pawn>

(Note: the official API does not expose methods on raw Handles.)

==Inheritance==
The Handle system has a "weak" hierarchy. All handles can be passed to <tt>CloseHandle</tt>, but only AdtArray handles can be passed to functions like <tt>PushArrayCell</tt>. This hierarchy is not enforced via tags (unfortunately), but instead by run-time checks. Methodmaps allow us to make individual handle types object-oriented, while also moving type-checks into the compiler.

For example, here is a transitional API for arrays:

<pawn>
native AdtArray CreateAdtArray();

methodmap AdtArray < Handle {
public PushCell() = PushArrayCell;
};
</pawn>

Note that <tt>CreateAdtArray</tt> now returns <tt>AdtArray</tt> instead of <tt>Handle</tt>. Normally that would break older code, but since <tt>AdtArray</tt> inherits from <tt>Handle</tt>, there is a special rule in the type system that allows coercing an <tt>AdtArray</tt> to a <tt>Handle</tt> (but not vice versa).

Now, the API looks much more object-oriented:
<pawn>
AdtArray array = CreateAdtArray();
array.PushCell(4);
array.Close();
</pawn>

==Inline Methods==
Methodmaps can declare inline methods and accessors. Inline methods can be either natives or Pawn functions. For example:

<pawn>
methodmap AdtArray {
public native void PushCell(value);
};
</pawn>

This example requires that an "AdtArray.PushCell" native exists somewhere in SourceMod. It has a magic initial parameter called "this", so the signature will look something like:
<pawn>
native void AdtArray.PushCell(AdtArray this, value);
</pawn>

(Of course, this exact signature will not appear in an include file - it's the signature that the C++ implementation should expect, however.)

It's also possible to define new functions without a native:
<pawn>
methodmap AdtArray {
public native void PushCell(value);

public void PushCells(list[], count) {
for (int i = 0; i < count; i++) {
this.PushCell(i);
}
}
};
</pawn>

Lastly, we can also define accessors. or example,
<pawn>
methodmap AdtArray {
property int Size {
public get() = GetArraySize;
}
property bool Empty {
public get() {
return this.Size == 0;
}
}
property int Capacity {
public native get();
}
};
</pawn>

The first accessor simply assigns an existing function as an accessor for "Size". The second accessor is an inline method with an implicit "this" parameter. The third accessor will bind to a native with the following name and signature:

<pawn>
native int AdtArray.Capacity.get(AdtArray this);
</pawn>

Setters are also supported. For example:

<pawn>
methodmap Player {
property int Health {
public native get();
public native set(int health);
}
}
</pawn>

==Custom Tags==
Methodmaps don't have to be used with Handles. It is possible to define custom methodmaps on new or existing tags. For example:

<pawn>
methodmap AdminId {
public int Rights() {
return GetAdminFlags(this);
}
};
</pawn>

Now, for example, it is possible to do:

<pawn>GetPlayerAdmin(id).Rights()</pawn>

==Constructors and Destructors==
Methodmaps can also define constructors and destructors, which is useful if they are intended to behave like actual objects. For example,

<pawn>
methodmap AdtArray {
public AdtArray(blocksize = 1);
public ~AdtArray();
public void PushCell(value);
};
</pawn>

Now AdtArrays can be used in a fully object-oriented style:
<pawn>
AdtArray array = new AdtArray();
array.PushCell(10);
array.PushCell(20);
array.PushCell(30);
delete array;
</pawn>

==Caveats==
There are a few caveats to methodmaps:
<ol>
<li>CloseHandle() is not yet gone. It is required to call <tt>delete</tt> on any object that previously would have required CloseHandle().</li>
<li>There can be only one methodmap for a tag.</li>
<li>When using existing natives, the first parameter of the native must coerce to the tag of the methodmap. Tag mismatches of the "this" parameter will result in an error. Not a warning!</li>
<li>Methodmaps can only be defined on tags. Pawn has some ways of creating actual types (like via <tt>struct</tt> or <tt>class</tt>). Methodmaps cannot be created on those types.</li>
<li>Methodmaps do not have strong typing. For example, it is still possible to perform "illegal" casts like <tt>Float:CreateAdtArray()</tt>. This is necessary for backwards compatibility, so methodmap values can flow into natives like <tt>PrintToServer</tt> or <tt>CreateTimer</tt>.</li>
<li>It is not possible to inherit from anything other than another previously declared methodmap.</li>
<li>Methodmaps can only be defined over scalars - that is, the "this" parameter can never be an array. This means they cannot be used for enum-structs.</li>
<li>Destructors can only be native. When we are able to achieve garbage collection, destructors will be removed.</li>
<li>The signatures of methodmaps must use the new declaration syntax.</li>
<li>Methodmaps must be declared before they are used.</li>
</ol>

==Grammar==
The grammar for methodmaps is:
<pre>
visibility ::= "public"
method-args ::= arg-new* "..."?

methodmap ::= "methodmap" symbol? { methodmap-item* } term
methodmap-item ::=
visibility "~"? symbol "(" ")" "=" symbol term
| visibility "native" type-expr "~"? symbol methodmap-symbol "(" method-args ")" term
| visibility type-expr symbol "(" method-args ")" func-body term
| "property" type-expr symbol { property-decl } term
property-func ::= "get" | "set"
property-decl ::= visibility property-impl
property-impl ::=
"native" property-func "(" ")" term
| property-func "(" ")" func-body term
| property-func "(" ")" "=" symbol
</pre>

=Typedefs=

Function tags and function enums have been deprecated in favor of a more modern syntax. Currently, they can still only create tag names for functions. Future versions will support arbitrary types. The syntax is:

<pre>
typedef ::= "typedef" symbol "=" full-type-expr term
full-type-expr ::= "(" type-expr ")"
| type-expr
type-expr ::= "function" type-name "(" typedef-args? ")"
typedef-args ::= "..."
| typedef-arg (", " "...")?
</pre>

Note that typedefs only support new-style types. For example,

<pawn>
functag public Action:SrvCmd(args);
</pawn>

Becomes...

<pawn>
typedef SrvCmd = function Action (int args);
</pawn>

=Enforcing new syntax=

You can enforce the new syntax in 1.7 by using <pawn>#pragma newdecls required</pawn> ontop of your code, after the includes (or else current 1.7 includes which contain old syntax will be read with new-syntax rules).

SourceMod 1.7.0 Release Notes

2015-02-04T23:52:22Z

Psychonic:

=Overview=

For users, SourceMod 1.7.0 is not much difference from an incremental release. Game compatibility is updated, some bugs are fixed, etc. Additionally, as some games switch to a newer Steam Id format, both the old and new can be used interchangeably in admin configs and commands.

For plugin developers, SourceMod 1.7.0 is a huge first step toward improving the SourcePawn language. A new, backwards-compatible [[SourcePawn Transitional Syntax]] has been added. With it come many new API additions and improvements. See the notes below for the full scoop.

=Changelog=

===User Changes===
* Updated game compatibility for TF2, CS:GO, and Dota 2.*
* Fixed regression in SM 1.6.3 causing load failure on games older than Orangebox. ({{pr|237}})*
* Rewrote internal Steam auth ID handling ({{pr|147}}, {{pr|153}}, {{pr|155}}, {{pr|162}}, {{pr|204}}, {{pr|210}}, {{pr|222}}, {{pr|246}}).
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* Added default timeout for MySQL connections to avoid hangs. ({{pr|248}}).
* Fixed <tt>sm plugins refresh</tt> not actually refreshing updated plugins like map change does ({{pr|257}}).
* SDKTools' gamerules gamedata is now far less likely to break on updates ({{pr|220}}).
* Fixed crash with sm_dump_admcache on Windows ({{pr|163}}).
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing ({{pr|236}}).
* Changed default sm_trigger_show ConVar value to 0 / disabled.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* Added Blocked hook type to SDKHooks ({{pr|119}}) ({{user|49537|VoiDeD}}).
* Added OnTakeDamage_Alive hook type to SDKHooks ({{pr|149}}).
* Many more File natives now support Valve FS ({{pr|120}}, {{pr|169}}, {{pr|178}}).
* Added SetFilePermissions native ({{pr|43}}) ({{user|9967|hlstriker}}).
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters ({{pr|164}}) ({{user|49537|VoiDeD}}).
* Exposed engine Message_DetermineMulticastRecipients as GetClientsInRange native. ({{pr|234}}).
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error ({{pr|74}}).
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface ({{pr|127}}).
* Fixed IThreader threads leaking if they're not joined. ({{bz|3460}}, {{pr|241}})
* TFHoliday updates no longer require a plugin recompile ({{pr|217}}).
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}, {{pr|203}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt ({{pr|83}}).
* Doubled maximum handle count per plugin to 32,768 ({{pr|215}}), (Thordin).
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields ({{pr|157}}) ({{user|49537|VoiDeD}}).
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf) ({{pr|54}}).
* Added command to dump profiler output ({{pr|128}}) ({{user|49537|VoiDeD}}).
* Fixed ICommandLine and related features being reported as unavailable on Dark Messiah.*
* Fixed OnPlayerRunCommand forward in SDKTools being unavailable on Dark Messiah.*
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

<nowiki>*</nowiki> These items are still new since SourceMod 1.6.3, but also exist in the unreleased 1.6.4-dev version.

=Developer Notes=

The biggest change for developers in SourceMod 1.7 is the new [[SourcePawn Transitional Syntax]], which adds some object-oriented capabilities to our API. The documentation on the transitional syntax has a comprehensive specification for all the changes, including examples.

If you want a very brief takeaway, here are the four new features to keep in mind:
# Declarations can now be written like in C# or Java. This is the new preferred syntax and will allow us to improve the language faster in the future. In newer declarations, <tt>String</tt> is renamed to <tt>char</tt> and <tt>Float</tt> is renamed to <tt>float</tt>.
# Instead of <tt>INVALID_HANDLE</tt>, there is a new <tt>null</tt> keyword.
# Instead of explicit tags, there is now a <tt>view_as<Tag></tt> expression that is preferred.
# Instead of <tt>CloseHandle</tt>, you can now use the new <tt>delete</tt> keyword.

We also note here some specific cases where compatibility with older scripts has been broken. These are source-level compatibility changes only - SourceMod will continue to run scripts compiled with SourceMod 1.6 and earlier.

# '''Coercing function types is now a warning.''' For example, passing a <tt>Function</tt>-tagged value to <tt>any</tt>, and then returning it as an <tt>int</tt>. The ability to coerce function types to plain values is a serious impediment to future improvements to SourcePawn. It is now a warning, and will be an error in a future version of SourcePawn.
# '''decl is deprecated'''. For new-style declarations, the <tt>decl</tt> keyword is not (and never will be) available. New-style declarations are always zeroed. For huge arrays in a critical path (such as a player loop in <tt>OnGameFrame</tt>), users should first estimate the time spent per-frame zeroing such arrays and then decide if they need to be hoisted outside the loop or made to be static.
# '''Multiple tag support has been removed.''' Previously, it was possible to specify multiple tags on an argument. For example, <tt>{Float,bool}:param</tt>. This syntax is no longer available.
# '''<tt>sizeof</tt> can no longer be used on indeterminate arrays.''' Previously, <tt>sizeof</tt> on an indeterminate array (an array whose size is not statically known) was a warning. It is now an error.
# '''Reserved keywords'''. We have taken the opportunity to reserve a number of keywords for future versions of SourcePawn. They don't do anything, and they have no semantics. They are only reserved now to mitigate any potential problems if we do need them in the future. They are: <tt>acquire</tt>, <tt>as</tt>, <tt>builtin</tt>, <tt>catch</tt>, <tt>cast_to</tt>, <tt>double</tt>, <tt>explicit</tt>, <tt>finally</tt>, <tt>foreach</tt>, <tt>implicit</tt>, <tt>import</tt>, <tt>in</tt>, <tt>int8</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>, <tt>intn</tt>, <tt>let</tt>, <tt>namespace</tt>, <tt>object</tt>, <tt>package</tt>, <tt>private</tt>, <tt>protected</tt>, <tt>readonly</tt>, <tt>sealed</tt>, <tt>throw</tt>, <tt>try</tt>, <tt>typeof</tt>, <tt>uint8</tt>, <tt>uint16</tt>, <tt>uint32</tt>, <tt>uint64</tt>, <tt>uintn</tt>, <tt>union</tt>, <tt>var</tt>, <tt>variant</tt>, <tt>volatile</tt>, <tt>with</tt>.
# '''<tt>sizeof</tt> no longer has magic meaning as a default argument expression.''' Previously, <tt>sizeof</tt> as a default argument expression would bind to the variable at its callsite, rather than the argument in parameter scope. This allowed users to create functions that did not seem to require an explicit size parameter alongside an array. This feature was buggy, so it has been removed, alongside similar magic binding for <tt>tagof</tt> and <tt>cellsof</tt> in default argument expressions.
# '''<tt>String[]</tt> and <tt>any</tt> no longer coerce'''. Previously, it was possible to coerce a character array to an <tt>any</tt> array, or vice-versa. This cast was unsafe because the storage widths of each array value are different (one normal array is four bytes per slot, and a character is one byte per slot). This coercion is now illegal.
# '''Using <tt>int</tt> or <tt>void</tt> as a tag is now a warning.'''
# '''Enums cannot be retagged.''' Previously, enums could be retagged - for example, <tt>enum X:Y { ...</tt>. This is no longer allowed.
# '''The implicit-int tag cannot be used as an enum tag.''' It is now illegal to use <tt>_</tt> as an enum name or label.
# '''Dynamically sized arrays are now indeterminate.''' Previously, an array could be declared as a mix of fixed-size and dynamic-sized dimensions. Now, all dimensions are considered indeterminate if any one dimension is dynamic-sized. This means <tt>sizeof</tt> may not work in complex array use.

SourceMod 1.7.0 Release Notes

2015-02-04T22:50:30Z

Psychonic: /* User Changes */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Overview=

For users, SourceMod 1.7.0 is not much difference from an incremental release. Game compatibility is updated, some bugs are fixed, etc. Additionally, as some games switch to a newer Steam Id format, both the old and new can be used interchangeably in admin configs and commands.

For plugin developers, SourceMod 1.7.0 is a huge first step toward improving the SourcePawn language. A new, backwards-compatible [[SourcePawn Transitional Syntax]] has been added. With it come many new API additions and improvements. See the notes below for the full scoop.

=Changelog=

===User Changes===
* Updated game compatibility for TF2, CS:GO, and Dota 2.*
* Fixed regression in SM 1.6.3 causing load failure on games older than Orangebox. ({{pr|237}})*
* Rewrote internal Steam auth ID handling ({{pr|147}}, {{pr|153}}, {{pr|155}}, {{pr|162}}, {{pr|204}}, {{pr|210}}, {{pr|222}}, {{pr|246}}).
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* Added default timeout for MySQL connections to avoid hangs. ({{pr|248}}).
* Fixed <tt>sm plugins refresh</tt> not actually refreshing updated plugins like map change does ({{pr|257}}).
* SDKTools' gamerules gamedata is now far less likely to break on updates ({{pr|220}}).
* Fixed crash with sm_dump_admcache on Windows ({{pr|163}}).
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing ({{pr|236}}).
* Changed default sm_trigger_show ConVar value to 0 / disabled.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* Added Blocked hook type to SDKHooks ({{pr|119}}) ({{user|49537|VoiDeD}}).
* Added OnTakeDamage_Alive hook type to SDKHooks ({{pr|149}}).
* Many more File natives now support Valve FS ({{pr|120}}, {{pr|169}}, {{pr|178}}).
* Added SetFilePermissions native ({{pr|43}}) ({{user|9967|hlstriker}}).
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters ({{pr|164}}) ({{user|49537|VoiDeD}}).
* Exposed engine Message_DetermineMulticastRecipients as GetClientsInRange native. ({{pr|234}}).
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error ({{pr|74}}).
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface ({{pr|127}}).
* Fixed IThreader threads leaking if they're not joined. ({{bz|3460}}, {{pr|241}})
* TFHoliday updates no longer require a plugin recompile ({{pr|217}}).
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}, {{pr|203}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt ({{pr|83}}).
* Doubled maximum handle count per plugin to 32,768 ({{pr|215}}), (Thordin).
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields ({{pr|157}}) ({{user|49537|VoiDeD}}).
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf) ({{pr|54}}).
* Added command to dump profiler output ({{pr|128}}) ({{user|49537|VoiDeD}}).
* Fixed ICommandLine and related features being reported as unavailable on Dark Messiah.*
* Fixed OnPlayerRunCommand forward in SDKTools being unavailable on Dark Messiah.*
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

<nowiki>*</nowiki> These items are still new since SourceMod 1.6.3, but also exist in the unreleased 1.6.4-dev version.

=Developer Notes=

The biggest change for developers in SourceMod 1.7 is the new [[SourcePawn Transitional Syntax]], which adds some object-oriented capabilities to our API. The documentation on the transitional syntax has a comprehensive specification for all the changes, including examples.

If you want a very brief takeaway, here are the four new features to keep in mind:
# Declarations can now be written like in C# or Java. This is the new preferred syntax and will allow us to improve the language faster in the future. In newer declarations, <tt>String</tt> is renamed to <tt>char</tt> and <tt>Float</tt> is renamed to <tt>float</tt>.
# Instead of <tt>INVALID_HANDLE</tt>, there is a new <tt>null</tt> keyword.
# Instead of explicit tags, there is now a <tt>view_as<Tag></tt> expression that is preferred.
# Instead of <tt>CloseHandle</tt>, you can now use the new <tt>delete</tt> keyword.

We also note here some specific cases where compatibility with older scripts has been broken. These are source-level compatibility changes only - SourceMod will continue to run scripts compiled with SourceMod 1.6 and earlier.

# '''Coercing function types is now a warning.''' For example, passing a <tt>Function</tt>-tagged value to <tt>any</tt>, and then returning it as an <tt>int</tt>. The ability to coerce function types to plain values is a serious impediment to future improvements to SourcePawn. It is now a warning, and will be an error in a future version of SourcePawn.
# '''decl is deprecated'''. For new-style declarations, the <tt>decl</tt> keyword is not (and never will be) available. New-style declarations are always zeroed. For huge arrays in a critical path (such as a player loop in <tt>OnGameFrame</tt>), users should first estimate the time spent per-frame zeroing such arrays and then decide if they need to be hoisted outside the loop or made to be static.
# '''Multiple tag support has been removed.''' Previously, it was possible to specify multiple tags on an argument. For example, <tt>{Float,bool}:param</tt>. This syntax is no longer available.
# '''<tt>sizeof</tt> can no longer be used on indeterminate arrays.''' Previously, <tt>sizeof</tt> on an indeterminate array (an array whose size is not statically known) was a warning. It is now an error.
# '''Reserved keywords'''. We have taken the opportunity to reserve a number of keywords for future versions of SourcePawn. They don't do anything, and they have no semantics. They are only reserved now to mitigate any potential problems if we do need them in the future. They are: <tt>acquire</tt>, <tt>as</tt>, <tt>builtin</tt>, <tt>catch</tt>, <tt>cast_to</tt>, <tt>double</tt>, <tt>explicit</tt>, <tt>finally</tt>, <tt>foreach</tt>, <tt>implicit</tt>, <tt>import</tt>, <tt>in</tt>, <tt>int8</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>, <tt>intn</tt>, <tt>let</tt>, <tt>namespace</tt>, <tt>object</tt>, <tt>package</tt>, <tt>private</tt>, <tt>protected</tt>, <tt>readonly</tt>, <tt>sealed</tt>, <tt>throw</tt>, <tt>try</tt>, <tt>typeof</tt>, <tt>uint8</tt>, <tt>uint16</tt>, <tt>uint32</tt>, <tt>uint64</tt>, <tt>uintn</tt>, <tt>union</tt>, <tt>var</tt>, <tt>variant</tt>, <tt>volatile</tt>, <tt>with</tt>.
# '''<tt>sizeof</tt> no longer has magic meaning as a default argument expression.''' Previously, <tt>sizeof</tt> as a default argument expression would bind to the variable at its callsite, rather than the argument in parameter scope. This allowed users to create functions that did not seem to require an explicit size parameter alongside an array. This feature was buggy, so it has been removed, alongside similar magic binding for <tt>tagof</tt> and <tt>cellsof</tt> in default argument expressions.
# '''<tt>String[]</tt> and <tt>any</tt> no longer coerce'''. Previously, it was possible to coerce a character array to an <tt>any</tt> array, or vice-versa. This cast was unsafe because the storage widths of each array value are different (one normal array is four bytes per slot, and a character is one byte per slot). This coercion is now illegal.
# '''Using <tt>int</tt> or <tt>void</tt> as a tag is now a warning.'''
# '''Enums cannot be retagged.''' Previously, enums could be retagged - for example, <tt>enum X:Y { ...</tt>. This is no longer allowed.
# '''The implicit-int tag cannot be used as an enum tag.''' It is now illegal to use <tt>_</tt> as an enum name or label.
# '''Dynamically sized arrays are now indeterminate.''' Previously, an array could be declared as a mix of fixed-size and dynamic-sized dimensions. Now, all dimensions are considered indeterminate if any one dimension is dynamic-sized. This means <tt>sizeof</tt> may not work in complex array use.

SourceMod 1.7.0 Release Notes

2015-02-03T20:34:11Z

Psychonic:

SourceMod 1.7.0 Release Notes

2015-02-03T20:33:55Z

Psychonic: /* Overview */

SourceMod 1.7.0 Release Notes

2015-02-03T20:33:19Z

Psychonic:

SourceMod 1.7.0 Release Notes

2015-02-03T20:16:23Z

Psychonic: /* Changelog */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Updated game compatibility for TF2, CS:GO, and Dota 2.*
* Fixed regression in SM 1.6.3 causing load failure on games older than Orangebox. ({{pr|237}})*
* Rewrote internal Steam auth ID handling ({{pr|147}}, {{pr|153}}, {{pr|155}}, {{pr|162}}, {{pr|204}}, {{pr|210}}, {{pr|222}}, {{pr|246}}).
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* Added default timeout for MySQL connections to avoid hangs. ({{pr|248}}).
* SDKTools' gamerules gamedata is now far less likely to break on updates ({{pr|220}}).
* Fixed crash with sm_dump_admcache on Windows ({{pr|163}}).
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing ({{pr|236}}).
* Changed default sm_trigger_show ConVar value to 0 / disabled.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* Added Blocked hook type to SDKHooks ({{pr|119}}) ({{user|49537|VoiDeD}}).
* Added OnTakeDamage_Alive hook type to SDKHooks ({{pr|149}}).
* Many more File natives now support Valve FS ({{pr|120}}, {{pr|169}}, {{pr|178}}).
* Added SetFilePermissions native ({{pr|43}}) ({{user|9967|hlstriker}}).
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters ({{pr|164}}) ({{user|49537|VoiDeD}}).
* Exposed engine Message_DetermineMulticastRecipients as GetClientsInRange native. ({{pr|234}}).
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error ({{pr|74}}).
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface ({{pr|127}}).
* Fixed IThreader threads leaking if they're not joined. ({{bz|3460}}, {{pr|241}})
* TFHoliday updates no longer require a plugin recompile ({{pr|217}}).
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}, {{pr|203}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt ({{pr|83}}).
* Doubled maximum handle count per plugin to 32,768 ({{pr|215}}), (Thordin).
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields ({{pr|157}}) ({{user|49537|VoiDeD}}).
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf) ({{pr|54}}).
* Added command to dump profiler output ({{pr|128}}) ({{user|49537|VoiDeD}}).
* Fixed ICommandLine and related features being reported as unavailable on Dark Messiah.*
* Fixed OnPlayerRunCommand forward in SDKTools being unavailable on Dark Messiah.*
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

<nowiki>*</nowiki> These items are still new since SourceMod 1.6.3, but also exist in the unreleased 1.6.4-dev version.

SourceMod 1.7.0 Release Notes

2015-02-03T20:07:44Z

Psychonic: /* Changelog */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Updated game compatibility for TF2, CS:GO, and Dota 2.*
* Fixed regression in SM 1.6.3 causing load failure on games older than Orangebox. ({{pr|237}})*
* Rewrote internal Steam auth ID handling ({{pr|147}}, {{pr|153}}, {{pr|155}}, {{pr|162}}, {{pr|204}}, {{pr|210}}, {{pr|222}}, {{pr|246}}).
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now far less likely to break on updates ({{pr|220}}).
* Fixed crash with sm_dump_admcache on Windows ({{pr|163}}).
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing ({{pr|236}}).

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* Added Blocked hook type to SDKHooks ({{pr|119}}) ({{user|49537|VoiDeD}}).
* Added OnTakeDamage_Alive hook type to SDKHooks ({{pr|149}}).
* Many more File natives now support Valve FS ({{pr|120}}, {{pr|169}}, {{pr|178}}).
* Added SetFilePermissions native ({{pr|43}}) ({{user|9967|hlstriker}}).
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters ({{pr|164}}) ({{user|49537|VoiDeD}}).
* Exposed engine Message_DetermineMulticastRecipients as GetClientsInRange native. ({{pr|234}}).
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error ({{pr|74}}).
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface ({{pr|127}}).
* Fixed IThreader threads leaking if they're not joined. ({{bz|3460}}, {{pr|241}})
* TFHoliday updates no longer require a plugin recompile ({{pr|217}}).
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}, {{pr|203}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt ({{pr|83}}).
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields ({{pr|157}}) ({{user|49537|VoiDeD}}).
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf) ({{pr|54}}).
* Added command to dump profiler output ({{pr|128}}) ({{user|49537|VoiDeD}}).
* Fixed ICommandLine and related features being reported as unavailable on Dark Messiah.*
* Fixed OnPlayerRunCommand forward in SDKTools being unavailable on Dark Messiah.*
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

<nowiki>*</nowiki> These items are still new since SourceMod 1.6.3, but also exist in the unreleased 1.6.4-dev version.

SourceMod 1.7.0 Release Notes

2015-02-03T19:24:43Z

Psychonic: /* Developer Changes */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now far less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}, {{pr|203}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

SourceMod 1.7.0 Release Notes

2015-02-03T19:22:53Z

Psychonic: /* Developer Changes */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now far less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Fixed FindFlagChar returning false when passing AdminFlag_Custom6 ({{bz|6248}}).
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

SourceMod 1.7.0 Release Notes

2015-01-23T20:45:38Z

Psychonic: /* User Changes */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now far less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

SourceMod 1.7.0 Release Notes

2015-01-23T20:43:57Z

Psychonic: /* Developer Changes */

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** New methodmap-based APIs have been added for many existing functions and handle types.
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

SourceMod 1.7.0 Release Notes

2015-01-23T20:42:24Z

Psychonic:

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]]!
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

SourceMod 1.7.0 Release Notes

2015-01-23T20:40:27Z

Psychonic: Created page with "''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet'' =Changelog= ===User Changes=== * Rewrote internal Steam a..."

''This page is still a work-in-progress, incomplete and barely edited, as SourceMod 1.7 has not been released yet''

=Changelog=

===User Changes===
* Rewrote internal Steam auth ID handling
** <tt>admins.cfg</tt> now supports Steam2, Steam3, and SteamID 64 formats for the Steam auth provider.
** <tt>admins-simple.ini</tt> now supports Steam3 auth IDs in addition to Steam2 IDs.
** Command targeting now supports both Steam3 auth IDs in addition to Steam2 IDs.
* SDKTools' gamerules gamedata is now less likely to break on updates.
* Fixed crash with sm_dump_admcache on Windows.
* Fixed SDKHooks causing crash on player join/leave or plugin load/unload if gamedata missing.

===Developer Changes===

* Added new [[SourcePawn Transitional Syntax]].
** [https://sm.alliedmods.net/new-api New work-in-progress API doc page].
* SDKHooks - Added Blocked and OnTakeDamage_Alive hook types.
* Many more File natives now support Valve FS.
* Added SetFilePermissions native.
* Added API for iterating StringMaps (formerly "tries").
* Added natives for accessing command line parameters.
* CloseHandle (or delete) on INVALID_HANDLE is now a no-op, instead of an error.
* GetClientAuthString is now deprecated. Use [https://sm.alliedmods.net/new-api/clients/GetClientAuthId GetClientAuthId] instead.
* Added OnCoreMapEnd to extension interface.
* TFHoliday updates no longer require a plugin recompile.
* Added support for (entity) CLASSPTR and EDICT Prop_Data fields with GetEntPropEnt and SetEntPropEnt.
* Added support for custom default values with GetEvent* natives, rather than using ""/0 for unset fields.
* Removed old profiler, and added new, pluggable profiler (with hooks to VProf).
* SourceMod now uses some C++11 and has newer compiler requirements.
* Added --disable-auto-versioning option to ambuild configure script.

Building AMX Mod X

2015-01-23T14:50:43Z

Psychonic: Fix path to configure.py

AMX Mod X is a large project, but we've tried to make it as easy to build as possible. The directions here will step you through the entire process.

=Requirements=

==Windows==
<ol>
<li>Install Visual Studio or Visual C++ 2010 or higher. Express editions should work fine. If you use 2013 or higher, make sure to get the "Desktop" version: [http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop Visual Studio Express 2013 for Desktop].</li>
<li>Install [http://git-scm.com/ Git]. Make sure that you select the option that adds Git to PATH.</li>
<li>Next, you will need to start an environment capable of running Python and interacting with the Visual Studio compiler. There are two ways to do this.
<ul>
<li>Use [https://wiki.mozilla.org/MozillaBuild MozillaBuild]. MozillaBuild comes with Python, Mercurial, and a unix-like shell.
<ol>
<li>Install MozillaBuild.</li>
<li>Navigate to <tt>C:\mozilla-build</tt> and run the batch file corresponding to your Visual Studio version. For example, <tt>start-msvc10.bat</tt> for Visual Studio 2010 (10.0). Do not run an x64 version.</li>
<li>Add Git to MozillaBuild's <tt>PATH</tt>. The easiest way to do this is to enter the following commands:
<pre>
echo "export PATH=\$PATH:/c/Program\ Files\ $x86$/Git/bin" >> ~/.profile
source ~/.profile
</pre>
</li>
</ol>
</li>
<li>Or, you can manually set up a shell.
<ol>
<li>Install [http://mercurial.selenic.com/ Mercurial].</li>
<li>Install [http://python.org/ Python] 2.7. It will install to C:\Python27 by default. (Version 3.4 will work, but is not recommended for compatibility with other tools).</li>
<li>Add Python to your <tt>PATH</tt> variable. Go to Control Panel, System, Advanced, Environment Variables. Add <tt>C:\Python27;C:\Python27\Scripts</tt> to <tt>PATH</tt> (or wherever your Python install is).</li>
<li>Under Start, Programs, Microsoft Visual Studio, select the "Visual Studio Tools" folder and run "Visual Studio Command Prompt". Alternately, open a normal command prompt and run <tt>"C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars.bat"</tt>. Substitute your Visual Studio version if needed.</li>
</ol>
</li>
</ul>
</ol>

Note that AMX Mod X also has Visual Studio project files. These can be used for local development, however, they are not maintained nor are they used for official builds.

==Linux==
<ol>
<li>Install Git, via either system packages or from the [http://git-scm.com/ Git] distribution.</li>
<li>Install either the GNU C Compiler or the Clang compiler. On Debian/Ubuntu, the following commands will give you everything:
<pre>
sudo apt-get install gcc g++ clang
</pre>
</li>
<li>If building on a 64-bit system, a few additional packages may be required. For example on Debian/Ubuntu they are:
<pre>
sudo apt-get install ia32-libs
sudo apt-get install lib32z1 lib32z1-dev
sudo apt-get install libc6-dev-i386 libc6-i386
sudo apt-get install gcc-multilib g++-multilib
</pre>
</li>
</ol>

==Mac OS X==
Mac OS X 10.7 or higher is required to build, however, AMX Mod X will work on versions as early as 10.5.

<ol>
<li>Install the Xcode Command Line Tools.
<ul>
<li>For OS X 10.9 or higher, run the command below in Terminal and click the Install button in the window that appears.
<pre>
xcode-select --install
</pre>
</li>
<li>For earlier versions of OS X, download and install Xcode from the App Store. Launch Xcode and then navigate to Preferences -> Downloads -> Components -> Command Line Tools -> Install. If you have recently upgraded Xcode, you will need to perform this step again. AMX Mod X cannot build without Xcode's command line tools.</li>
</ul>
</ol>

=Dependencies=
Building AMX Mod X requires AMBuild, Metamod, the Half-Life SDK, and optionally MySQL 5. If you're using Linux, OS X, or Windows with MozillaBuild, you download and run the following script to get everything:

<pre>
wget https://raw2.github.com/alliedmodders/amxmodx/master/support/checkout-deps.sh
bash checkout-deps.sh
</pre>

This will download everything required into <tt>amxmodx</tt>, <tt>hlsdk</tt>, and <tt>metamod-am</tt>. If AMBuild is not installed, it will also download it into <tt>ambuild</tt>, and prompt you for your password to install it.

If for some reason this script doesn't work, or you can't use it, you can get AMX Mod X and its dependencies like so:
<pre>
git clone https://github.com/alliedmodders/ambuild
git clone https://github.com/alliedmodders/metamod-hl1
git clone https://github.com/alliedmodders/hlsdk
git clone https://github.com/alliedmodders/amxmodx
cd ambuild
python setup.py install # May need sudo or root on Linux/OS X
</pre>

=Configuring=

The first time you are building AMX Mod X, you must ''configure'' the build. First create a build folder, and then run <tt>configure.py</tt>. For example:
<pre>
mkdir build
cd build
python ../configure.py
</pre>

It is safe to reconfigure over an old build. However, it's probably a bad idea to configure inside a random, non-empty folder.

There are a few extra options you can pass to <tt>configure</tt>:
*--enable-debug - Compile with symbols and debug checks/assertions.
*--enable-optimize - Compile with optimizations.
*--no-mysql - If you didn't install MySQL, you can choose not to build the extension.

=Building=

To build AMX Mod X, simply navigate to your build folder and type <tt>ambuild</tt>:
<pre>
cd build
ambuild
</pre>

Alternately, you can specify the path of the build folder:
<pre>
ambuild build
</pre>

The full package layouts that would be shipped for release are in the <tt>package</tt> folder of the build.

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

Compiling libprotobuf

2015-01-21T14:07:20Z

Psychonic:

Compiling libprotobuf

2015-01-21T14:07:09Z

Psychonic: GRAMMAR

Examples for compiling a 32-bit libprotobuf and other protobuf libraries using the protobuf-2.5.0 source.

''For Dota 2, replace version 2.5.0 with 2.6.1.''

''Also note that the Protobuf source has moved to [http://www.github.com/google/protobuf link GitHub]. Some of the below links may be outdated.''

==Windows==
The following was tested on Windows 8.1 with Visual Studio 2013. Not all projects built after conversion, but only libprotobuf and dependencies were necessary.

* Download protobuf-2.5.0.zip from https://code.google.com/p/protobuf/downloads/list
* Extract and navigate to protobuf-2.5.0/vsprojects/
* Open protobuf.sln in the version of Visual Studio corresponding with the VC abi version that you wish to compile for.
* Walk through project conversion steps if necessary.
* Right-click the libprotobuf project and choose properties.
* In Configuration Properties > C/C++ -> Code Generation, set Runtime Library to /MT for Release or /MTd for Debug.
* If building the Debug configuration, also add _ITERATOR_DEBUG_LEVEL=0 in Configuration Properties > C/C++ > Preprocessor > Preprocessor Defintions
* Right-click the libprotobuf project and choose Build.

libprotobuf.lib will be in Release/ or Debug/, depending on build configuration.

==Linux (32-bit host)==
The following was tested on Debian 6 (Lenny) 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure CXXFLAGS="-g3 -ggdb3"
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Linux (64-bit host)==
This hasn't been tested, but ''should'' work on most or all 64-bit distributions.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=i686-pc-linux-gnu CFLAGS="-m32 -DNDEBUG" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=i686-pc-linux-gnu CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Mac==
The following was tested on OS X 10.7 (Lion) and ensures that the outputted binaries are 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-DNDEBUG -m32" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

Compiling libprotobuf

2015-01-21T14:06:51Z

Psychonic:

Examples for compiling a 32-bit libprotobuf and other protobuf libraries using the protobuf-2.5.0 source.

''For Dota 2, replacing version 2.5.0 with 2.6.1.''

''Also note that the Protobuf source has moved to [http://www.github.com/google/protobuf link GitHub]. Some of the below links may be outdated.''

==Windows==
The following was tested on Windows 8.1 with Visual Studio 2013. Not all projects built after conversion, but only libprotobuf and dependencies were necessary.

* Download protobuf-2.5.0.zip from https://code.google.com/p/protobuf/downloads/list
* Extract and navigate to protobuf-2.5.0/vsprojects/
* Open protobuf.sln in the version of Visual Studio corresponding with the VC abi version that you wish to compile for.
* Walk through project conversion steps if necessary.
* Right-click the libprotobuf project and choose properties.
* In Configuration Properties > C/C++ -> Code Generation, set Runtime Library to /MT for Release or /MTd for Debug.
* If building the Debug configuration, also add _ITERATOR_DEBUG_LEVEL=0 in Configuration Properties > C/C++ > Preprocessor > Preprocessor Defintions
* Right-click the libprotobuf project and choose Build.

libprotobuf.lib will be in Release/ or Debug/, depending on build configuration.

==Linux (32-bit host)==
The following was tested on Debian 6 (Lenny) 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure CXXFLAGS="-g3 -ggdb3"
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Linux (64-bit host)==
This hasn't been tested, but ''should'' work on most or all 64-bit distributions.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=i686-pc-linux-gnu CFLAGS="-m32 -DNDEBUG" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=i686-pc-linux-gnu CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

==Mac==
The following was tested on OS X 10.7 (Lion) and ensures that the outputted binaries are 32-bit.

<pre>
wget https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
tar -xvzf protobuf-2.5.0.tar.gz
cd protobuf-2.5.0
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-DNDEBUG -m32" CXXFLAGS="-m32 -DNDEBUG" LDFLAGS=-m32
make
</pre>

For a debug build, replace <tt>./configure</tt> with:
<pre>
./configure --build=x86-apple-darwin ABI=standard CFLAGS="-m32" CXXFLAGS="-m32 -g3 -ggdb3" LDFLAGS=-m32
</pre>
This will also override protobuf's default CXXFLAGS of <tt>-DNDEBUG</tt>

The library will be in src/.libs/

Releasing Products

2014-11-25T17:56:59Z

Psychonic: /* Post-Build Work */

This is an internal page for doing AlliedModders product releases.

=Making Builds=
<ol>
<li>Once you are '''absolutely sure''' the product is ready for a release...</li>
<li>Jump to a Linux system, check out the source tree.</li>
<li>Update the changelog (<tt>changelog.txt</tt> for SourceMod, <tt>support/changelog.txt</tt> for Metamod:Source).</li>
<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).
<li>Edit <tt>product.version</tt> to remove the -dev tag.</li>
<li>Commit and push the changes.</li>
<li>Push. Watch the waterfall page until builds are complete.</li>
</ol>

=Post-Build Work=
<ol>
<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>
<li>Install the packages on both Linux and Windows. '''MAKE SURE THE VERSIONS ARE CORRECT. THERE SHOULD BE NO -dev TAG.'''
 
Metamod:Source checks:
<pre>
meta version
</pre>
SourceMod checks:
<pre>
sm plugins list
sm exts list
sm version
</pre></li>
<li>If the versions are not correct, do not release.</li>
<li>For SourceMod, you need to add the language translation packs and update the GeoLite Country data file.
 
'''If this is a major release (1.X.0), there is no prior pack. Make one:'''
<ol>
<li>Extract both the tar.gz and zip files to separate folders.</li>
<li>Visit the [http://www.sourcemod.net/translator/?go=translate&op=status translator status page].</li>
<li>Click "export languages.cfg" - save the new version to <tt>addons/sourcemod/configs/</tt>, overwriting the old one.</li>
<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>
<li>Download the latest GeoLite Country binary file from http://dev.maxmind.com/geoip/geolite</li>
<li>Extract the GeoIP.dat and replace the existing copy in addons/sourcemod/configs/geoip</li>
<li>Repackage the folders using the correct compression types (.tar.gz for Linux, .zip for Windows and Mac).</li>
</ol>
If this is a minor release (1.X.Y where Y != 0), there is already a prior pack. Add it in:
<ol>
<li>Extract both the tar.gz and zip files to separate folders.</li>
<li>Download the last major release from the same branch as this release.</li>
<li>Copy the <tt>addons/sourcemod/configs/languages.cfg</tt> file from the old release over the new one.</li>
<li>Copy the <tt>addons/sourcemod/translations/</tt> sub-folders from the old release over to the new one.</li>
<li>Download the latest GeoLite Country binary file from http://dev.maxmind.com/geoip/geolite</li>
<li>Extract the GeoIP.dat and replace the existing copy in addons/sourcemod/configs/geoip</li>
<li>Repackage the folders using the correct compression types (.tar.gz for Linux, .zip for Windows).</li>
</ol>
<li>The build is done!</li>
</ol>

=Releasing to Mirrors=
<ol>
<li>Log into web01 as yourself. Upload your final builds to your home directory.</li>
<li>Run:
<pre>
/scripts/amjump mirror
cd /scripts/mirror
</pre>
</li>
<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>
<li>Mirror distribution is done with the following command:
<pre>
./mirror.pl <projectID> <releaseName> <file>
</pre>
Metamod:Source's ID is 4, SourceMod's ID is 2. For example, these commands mirrored the Metamod:Source 1.8.7 release:
<pre>
./mirror.pl 4 1.8.7 mmsource-1.8.7-linux.tar.gz
./mirror.pl 4 1.8.7 mmsource-1.8.7-windows.zip
./mirror.pl 4 1.8.7 mmsource-1.8.7-mac.zip
</pre>
These commands mirrored the SourceMod 1.4.0 release:
<pre>
./mirror.pl 2 1.4.0 sourcemod-1.4.0-linux.tar.gz
./mirror.pl 2 1.4.0 sourcemod-1.4.0-windows.zip
./mirror.pl 2 1.4.0 sourcemod-1.4.0-mac.zip
</pre>
</li>
<li>Type <tt>exit</tt> to get back to your user account. You're done!</li>
</ol>

=Cleaning up the Tree=
It's time to make sure the tree is set for future development.

<ol>
<li>Run <tt>git tag</tt> on the last revision of the release. Usually this is the changeset that bumped versions, and usually this is the branch <tt>tip</tt>. After you have tagged the changeset, push the tag upstream. For example, Metamod:Source:
<pre>git tag -a mmsource-1.7.2 -m "Metamod:Source 1.7.2"
git push origin mmsource-1.7.2</pre>
SourceMod:
<pre>git tag -a sourcemod-1.1.2 -m "SourceMod 1.1.2"
git push origin sourcemod-1.1.2</pre>
</li>
<li>Bump the minor version in <tt>product.version</tt>. Don't forget to add -dev.</li>
<li>Change the <tt>tools/buildbot/build_type</tt> (SourceMod) or <tt>support/buildbot/build_type</tt> (Metamod:Source) contents back to "dev".</li>
<li>Commit and push.</li>
</ol>

=Updating the SourceMod Site=
<ol>
<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>
<li>Jump to the sourcemod account by logging into web01 as yourself:
<pre>
/scripts/amjump sourcemod
cd /groups/sourcemod
</pre>
</li>
<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>
<li>Update ~/compiler-1.x to the latest minor version, where x is the major version number.</li>
<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>
<li>Exit out of the sourcemod account.</li>
<li>If a new major version, find someone with access to edit the forums if not yourself, and have the new compiler version added to editpost.php and newthread.php for the dropdown when editing plugin posts.</li>
<li>Find someone with access to the smdocs user if not yourself, and have the api docs updated by logging in as smdocs, navigating to ~/scripts/sync_api, replace the contents of the build directory with the new SM release, and run the run.sh script.</li>
<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>
</ol>

=Updating the Metamod:Source Site=
<ol>
<li>Jump to the alliedmodders account by logging into web01 as yourself:
<pre>
/scripts/amjump alliedmodders
cd /groups/alliedmodders/hub/amhub
</pre>
</li>
<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>
<li>Edit the <tt>templates/mmsource/navbar.html</tt> file and replace all instances of the old version with the new one.
<li>Run the following command:
<pre>
touch ../run/apache.wsgi
</pre>
</li>
<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>
<li>Exit out of the alliedmodders account.</li>
</ol>

=Updating Translations=
This section applies to SourceMod major releases. In order to update the translator tool, shell in as the "sourcemod" user. Find the /scripts/translation folder in the sourcemod group homedir. Run the following steps:
* cd sourcemod
* git pull
* cd ..
* ./sync_lang_files.pl sourcemod/translations

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.