AlliedModders Wiki - User contributions [en]

Clients (SourceMod Scripting)

2025-06-02T14:00:44Z

Nosoop: Update documentation to reflect changes in MAXPLAYERS definition

[[SourceMod]] assigns a Client Index number to client in the server. You can use these numbers to refer to specific clients in various SourceMod APIs. In particular, the [Clients APIs https://sm.alliedmods.net/new-api/clients].

The server is given client index 0, and the first connected user will have client index 1.

There are two variables that can be used to talk about the maximum number of clients:

* <tt>MaxClients</tt>: The maximum number of players currently allowed to connect to the server.
** This is set at runtime based on <tt>gpGlobals->maxClients</tt> in the game server.
* <tt>MAXPLAYERS</tt>: The theoretical maximum number of clients allowed on any Source game.
** As of SourceMod 1.12 this number is set to 101 for Team Fortress 2, enough for 100 players + a SourceTV client.

These values represent the '''maximum count of clients'''. Since Client indexing starts at 1, be wary of off-by-one errors here!

It's recommended that you use <tt><= MaxClients</tt> when looping through the client list, and <tt>MAXPLAYERS+1</tt> when initializing an array to contain data for individual clients.

For example:
<sourcepawn>
// Declare static arrays to support the maximum number of clients possible.
new playerVotes[MAXPLAYERS+1];

public void OnPluginStart()
{
RegConsoleCmd("start_vote", Command_StartVote);
RegConsoleCmd("vote", Command_Vote);
}

public Action Command_StartVote(int client, int args)
{
// Loop through all clients based on current number of max clients.
for(int i = 0; i <= MaxClients; i++) {
playerVotes[i] = 0;
}
}

public Action Command_Vote(int client, int args)
{
char arg[128];
if( args > 0)
{
GetCmdArg(i, arg, sizeof(arg));
// Associate data with clients at their client index in an array.
playerVotes[client] = StringToInt(arg);
}

return Plugin_Handled;
}
</sourcepawn>

Other notes:

The game engine's CBaseServer has its own <tt>m_clients</tt> list. You can subtract 1 from a SourceMod client index to get the <tt>CBaseServer::m_clients</tt> index.

User:Nosoop/Guide/Advanced

2025-05-23T13:45:19Z

Nosoop:

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= What is gamedata? =

''Gamedata'', also known as game data, gameconfig, and gameconf, are files used to specify information tied to a specific game.

As the games that SourceMod runs on are updated independently of SourceMod itself, gamedata is used as a unified way to keep plugins and extensions up to date on game changes without needing to recompile them.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>]. (Click those filenames to download the respective scripts.)

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
Address pTest;
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

== Calling via Signature or Offset? ==

If you have a class with a virtual method, you generally should set up the <tt>SDKCall</tt> to take a virtual offset. Doing so allows your plugin to have the expected interactions with other plugin's hooks, covered in the next section.

You should use a signature either when the function is not virtual or if you need to bypass the virtual override on an entity (e.g. calling the parent class's function). In those instances, only detours will take effect.

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.
* On some binaries (especially with more aggressive optimizations in place), multiple function symbols may map to the same place in memory if they output the same code. As a result, detours may be called when you don't expect them to be.

User:Nosoop/Guide/Setup

2025-05-08T10:31:51Z

Nosoop: /* Installing the Server */ Add note on Linux listen servers

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a Windows game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.

Additionally, Linux game clients use stripped server binaries, which are not supported by SourceMod.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game server. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{{note|Be sure to write down the commands you used when installing the game server! You will need to issue those commands again whenever the game is updated.}}

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
* With the release of Counter-Strike 2, CS:GO no longer has first-class Steam support, and the existing Game Coordinator system will not allow players to connect to vanilla installations. However, the last version of CS:GO is officially available through the Steam "beta" branch system, and is currently supported by SourceMod. You may use [https://github.com/eldoradoel/NoLobbyReservation the NoLobbyReservation plugin] to allow players to connect.
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Setup

2025-03-02T08:55:40Z

Nosoop: /* Installing the Server */ Add note on CS:GO

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game server. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{{note|Be sure to write down the commands you used when installing the game server! You will need to issue those commands again whenever the game is updated.}}

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
* With the release of Counter-Strike 2, CS:GO no longer has first-class Steam support, and the existing Game Coordinator system will not allow players to connect to vanilla installations. However, the last version of CS:GO is officially available through the Steam "beta" branch system, and is currently supported by SourceMod. You may use [https://github.com/eldoradoel/NoLobbyReservation the NoLobbyReservation plugin] to allow players to connect.
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

Installing Metamod:Source

2024-09-05T14:07:50Z

Nosoop: please stop modifying your gameinfos. god is weeping

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 you see this, you are done. 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.'''

You really, really do not need to do this.

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>

If you are running any of the above, then yes, you probably do need it. But you probably aren't, so you probably don't, and plenty of people have fallen into the trap of doing these steps unnecessarily and have had to be told otherwise.

So again, if you followed the normal installation process above and <code>meta version</code> was recognized, ''do not do this''.

Otherwise, if you have trouble getting Metamod:Source 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.

=Adjust gameinfo file=

'''Adjusting gameinfo for Source 1 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. See [[#Source_2|Source 2]] for more info.'''

==Source 1==
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 <code>gameinfo.txt</code>. 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 <code>{</code> sign but before all of the <code>Game</code> 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 <code>meta version</code> in the server console. You should see a line that says <code>Loaded as: GameDLL (gameinfo.txt)</code>.
If it doesn't recognize the command, the installation probably failed. If the <code>Loaded as:</code> 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>

==Source 2==
Source 2 does not have server plugins, so you will need to load Metamod the old-fashioned way: replacing the server library with Metamod's stub loader.

{{Sad|You will need to redo these changes every time a developer pushes a change that modifies gameinfo.gi}}

<ul>
<li>Open the file in the mod folder called <code>gameinfo.gi</code>. In CS2 this is <code>csgo/gameinfo.gi</code>.
<li>Note that even though it says <code>DO NOT EDIT THIS FILE DIRECTLY</code> and advises to edit <code>csgo_core/gameinfo.gi</code>, editing that file does not correctly load Metamod.
<li>Look for the <code>SearchPaths</code> section of code.
<li>Add a line after the <code>{</code> sign but before all of the <code>Game</code> entries that looks like this, replacing <code>csgo</code> (for CS2) with your game name found in lines beneath it:
<pre>Game csgo/addons/metamod</pre>
{{CommonMistake|Make sure the Metamod entry is the '''first''' in the searchpaths list! This list is ordered and placing it anywhere else will prevent Metamod from loading}}
<li>Using <code>GameBin</code> instead of <code>Game</code> does not work.
<li>In Windows, the backslash is no longer required for paths.</li>
<li>You're done! To test whether it worked, restart your game server and type <code>meta version</code> in the server console. You should see a line that says <code>Metamod:Source version 2.x.x</code>.
If it doesn't recognize the command, the installation probably failed. Try updating your game to the latest version and using the latest version of Source 2.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

[[Category:Metamod:Source Documentation]]

Porting to x64

2024-08-01T14:19:37Z

Nosoop: /* Recompiling Extensions */ Mention usage of --targets

== 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!)

== Recompiling Extensions ==

The short version is that, assuming your target project uses AMBuild, pull in [https://github.com/alliedmodders/sourcemod/pull/2107 a modern revision of the build scripts], then specify the <code>--targets</code> argument to build the extension for one or more supported architectures.

Beyond that, as long as the code isn't architecture-specific, most extensions should compile fine with 64-bit support with slight adjustments at most. If you are using detours, you may need to [https://github.com/alliedmodders/sourcemod/blob/96727a7610a2690b20670264edb737a42f9da110/AMBuildScript#L583-L591 make further adjustments to build the new safetyhook dependency].

[[Category:SourceMod Documentation]]

Porting to x64

2024-08-01T14:13:03Z

Nosoop: /* Recompiling Extensions */ Reword "just update AMBuild", add safetyhook

== 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!)

== Recompiling Extensions ==

The short version is that, assuming your target project uses AMBuild, pull in [https://github.com/alliedmodders/sourcemod/pull/2107 a modern revision of the build scripts].

Beyond that, as long as the code isn't architecture-specific, most extensions should compile fine with 64-bit support with slight adjustments at most. If you are using detours, you may need to [https://github.com/alliedmodders/sourcemod/blob/96727a7610a2690b20670264edb737a42f9da110/AMBuildScript#L583-L591 make further adjustments to build the new safetyhook dependency].

[[Category:SourceMod Documentation]]

Porting to x64

2024-08-01T14:03:57Z

Nosoop: Add section on recompiling extensions

== 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!)

== Recompiling Extensions ==

The short version is to pull in [https://github.com/alliedmodders/sourcemod/pull/2107 a modern revision of the build scripts], assuming the target project is using that build tooling.

Beyond that, as long as the code isn't architecture-specific, most extensions should compile fine with 64-bit support with slight adjustments at most.

[[Category:SourceMod Documentation]]

User:Nosoop/Guide/Advanced

2024-06-11T04:19:22Z

Nosoop: /* Virtual Hook or Detour? */ Add note on symbol aliasing

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= What is gamedata? =

''Gamedata'', also known as game data, gameconfig, and gameconf, are files used to specify information tied to a specific game.

As the games that SourceMod runs on are updated independently of SourceMod itself, gamedata is used as a unified way to keep plugins and extensions up to date on game changes without needing to recompile them.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>].

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
Address pTest;
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

== Calling via Signature or Offset? ==

If you have a class with a virtual method, you generally should set up the <tt>SDKCall</tt> to take a virtual offset. Doing so allows your plugin to have the expected interactions with other plugin's hooks, covered in the next section.

You should use a signature either when the function is not virtual or if you need to bypass the virtual override on an entity (e.g. calling the parent class's function). In those instances, only detours will take effect.

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.
* On some binaries (especially with more aggressive optimizations in place), multiple function symbols may map to the same place in memory if they output the same code. As a result, detours may be called when you don't expect them to be.

User:Nosoop/Guide/Setup

2024-04-27T22:35:46Z

Nosoop: Fix spacing

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game server. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{{note|Be sure to write down the commands you used when installing the game server! You will need to issue those commands again whenever the game is updated.}}

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Setup

2024-04-27T22:35:23Z

Nosoop: /* Installing the Server */ Add reminder to note install commands

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game server. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{{note|Be sure to write down the commands you used when installing the game server! You will need to issue those commands again whenever the game is updated.}}

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

Client Preferences API (SourceMod)

2024-01-01T00:33:07Z

Nosoop: Add note for multiple server handling

The Client Preferences extension is bundled with SourceMod 1.1 and higher. It lets you associate key/value pairs with clients who connect to servers. This information persists across client connections, and therefore across map changes and server restarts, and even servers.

{{note|For information to be synchronized across multiple servers, the extension must be configured on each server to access settings on a shared database (most commonly running MySQL). By default, settings are saved in a standalone SQLite database unique to each server.}}

==Cookies==
The basic unit of information is a "cookie". Cookies are unique keys registered by plugins, similar to ConVars. Cookie names should always be reasonably descriptive to avoid clashes.

Cookies are registered using RegClientCookie, usually in OnPluginStart. Each cookie has a permission associated with it. A "public" cookie means a client can see and change the value they have for this cookie. A "protected" cookie means the client can only read it. A "private" cookie is completely hidden from the user.

The value of a cookie for a given client can be set using SetClientCookie, or retrieved using GetClientCookie. The default value of a Cookie is an empty string. Cookies are always stored as Strings, so if you want to store or retrieve cells/bools/Handles or Floats, you will need to convert them. This can be done using the StringToInt, IntToString, StringToFloat, and FloatToString functions.

==Asynchronicity==
When a client connects, their cookie information is retrieved asynchronously. This means their data is not immediately available.

Use the AreClientCookiesCached native to detect whether a user's cookies are available yet. If not, you will have to wait until OnClientCookiesCached is called for that client. There is no guarantee that these will succeed. For example, a player could connect and leave before a MySQL server responds.

==Cookie Menus==
The original intent of Client Preferences was to abstract preferences. For example, you might want to keep track whether a client wants to see a particular message or not.

To assist this type of code, there is a unified "cookie menu" system. The API is similar to TopMenus with the benefit that prefab menu formats are available. Prefab cookie menus are created using SetCookiePrefabMenu. The available prefabs are "Yes / No" and "On / Off". Fully custom menus can be created via SetCookieMenuItem.

==Client Commands==
The <tt>sm_cookies</tt> command allows users to view and set cookies.
The <tt>sm_settings</tt> command displays the cookie menu.

== Example ==
<pawn>#include <clientprefs>

Handle g_hMyCookie;

public void OnPluginStart()
{
g_hMyCookie = RegClientCookie("myplugin_mycookie", "MyPlugin MyCookie", CookieAccess_Protected);
}

public void SomeActionThatUsesCookie(int client)
{
if (AreClientCookiesCached(client))
{
// Get cookie and add 1 to it
char sCookieValue[12];
GetClientCookie(client, g_hMyCookie, sCookieValue, sizeof(sCookieValue));
int cookieValue = StringToInt(sCookieValue);
cookieValue++;

IntToString(cookieValue, sCookieValue, sizeof(sCookieValue));

SetClientCookie(client, g_hMyCookie, sCookieValue);
}
}</pawn>

[[Category:SourceMod Development]]

Compiling SourceMod Plugins

2023-11-25T16:27:07Z

Nosoop: Recommend Spider before the web compiler

Okay, so you've read the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] and now you want to actually compile a plugin.

The simplest way to compile a plugin that doesn't rely on any custom include files is using [https://spider.limetech.io/ Spider] or [http://www.sourcemod.net/compiler.php the web compiler].

Alternatively, you can use the executable compiler distributed with SourceMod. You can use this simply if you like compiling locally rather than using the web compiler. You have to use the local compiler if your plugin relies on custom include files. The compiler is included in the sourcemod/scripting/ folder of the [http://www.sourcemod.net/downloads.php SourceMod distribution].

Windows: open up a command prompt (Start->Run or WindowsKey+R, then "cmd"):
cd <sourcemod>\scripting
spcomp myplugin.sp
[http://www.computerhope.com/cdhlp.htm cd command reference]

Alternatively, you can simply drag the .sp file on top of spcomp.exe, which will compile the plugin for you.

Linux: Depending on your Linux flavour you need to install the libc6 and libstdc++6 32bit libraries before you start to compile

Example for Ubuntu:
apt-get install libc6:i386 lib32stdc++6

Then use:
./compile.sh myplugin.sp

Now simply move the .smx (not .sp) file from sourcemod/scripting/compiled/ to the sourcemod/plugins/ folder.

'''Note:''' When compiling preexisting plugins it is easiest to move the included from the plugin source folder to the include folder in your sourcemod/scripting/include. Please see [[Spcomp_switches]] specifically the ''-i'' parameter for specifying a different folder for includes.

[http://forums.alliedmods.net/showthread.php?t=52664 Reference Source]

See Also: [http://forums.alliedmods.net/forumdisplay.php?f=107 Scripting Forum]

User:Nosoop/Guide/Setup

2023-11-16T07:58:14Z

Nosoop: /* Installing Metamod:Source */ Reduce nesting in upload failure notes

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Setup

2023-11-16T07:57:46Z

Nosoop: /* Installing Metamod:Source */ Add note on potential issue with remote file uploads

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
#*** You should verify that the files were transmitted properly to the server; there have been reports of upload failures, zero-length files, and files that were mistakenly sent in text form and corrupted as a result.
# After installing, you should verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Setup

2023-11-10T16:25:23Z

Nosoop: /* Picking an IDE */ Directly link to Sarrus's extension

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
# You may want to verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://marketplace.visualstudio.com/items?itemName=Sarrus.sourcepawn-vscode Sarrus's VSCode extension] [https://github.com/Sarrus1/sourcepawn-vscode (source code)]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

Entity Lumps (SourceMod Scripting)

2023-10-09T05:03:44Z

Nosoop: Add notes on release and describe what the entity lump is

Source Engine maps store entity data in [https://developer.valvesoftware.com/wiki/Source_BSP_File_Format#Entity an entity lump], which is a plain text file containing a list of key / value pairs describing each entity.

SourceMod implements functionality to manipulate this data in <tt>entitylump.inc</tt>. This functionality was added to the development branch in 1.12.0.6922, then backported to the stable branch in 1.11.0.6919 (after its release).

=Introduction=

The global EntityLump methodmap contains functions to access individual entity entries. Below is an example lump that will be used throughout the rest of this page:

<pre>{
"world_maxs" "2624 4720 1728"
"world_mins" "-3536 -4720 -560"
"skyname" "sky_tf2_04"
"minoccluderarea_x360" "110"
"maxpropscreenwidth" "-1"
"detailvbsp" "detail_2fort.vbsp"
"detailmaterial" "detail/detailsprites_2fort"
"classname" "worldspawn"
"mapversion" "4067"
"hammerid" "4396"
}
{
"origin" "212.201 1784.53 259.256"
"fademindist" "-1"
"AutoMaterialize" "1"
"angles" "0 180 0"
"classname" "item_ammopack_small"
"hammerid" "5314720"
}
{
"origin" "-48 84 617"
"spawnflags" "1"
"classname" "logic_auto"
"hammerid" "741865"
"OnMapSpawn" "tonemap_global,SetAutoExposureMin,.8,0,-1"
"OnMapSpawn" "tonemap_global,SetAutoExposureMax,1.1,0,-1"
"OnMapSpawn" "tonemap_global,SetBloomScale,.5,0,-1"
"OnMapSpawn" "tf_gamerules,SetBlueTeamGoalString,#2fort_blue_setup_goal,0,-1"
"OnMapSpawn" "tf_gamerules,SetRedTeamGoalString,#2fort_red_setup_goal,0,-1"
"OnMapSpawn" "tf_gamerules,SetStalemateOnTimelimit,1,0,-1"
}</pre>

Plugins must modify the entity lump during the <tt>OnMapInit</tt> forward. Attempting to use non-read operations (such as update, insert, append, and erase) outside of that forward will raise a runtime error.

=Entity Lump=

The global <tt>EntityLump</tt> behaves like an {{SourceMod API|file=adt_array|function=ArrayList}}; to get a specific entity lump entry you must call its <tt>Get</tt> function:

<sourcepawn>
// get the worldspawn entity from the list
EntityLumpEntry entry = EntityLump.Get(0);

// release our handle to it when we are done
delete entry;
</sourcepawn>

If you don't know where your desired entity is, you must iterate over the list:

<sourcepawn>
for (int i, n = EntityLump.Length(); i < n; i++)
{
EntityLumpEntry entry = EntityLump.Get(i);
if (entry.FindKey("AutoMaterialize") != -1)
{
// this item has at least one 'AutoMaterialize' key
}
delete entry;
}
</sourcepawn>

=Entity Lump Entry=

<tt>EntityLumpEntry</tt> handles contains a list of key / value pairs.

You can modify an entry's values:

<sourcepawn>
// get the item_ammopack_small entity from the list
EntityLumpEntry entry = EntityLump.Get(1);

// find the 'classname' key in the list, then modify it
int icname = entry.FindKey("classname");
if (icname != -1)
{
// keep the name as 'classname', but change the value to 'item_ammopack_full'
entry.Update(icname, NULL_STRING, "item_ammopack_full");
}
delete entry;
</sourcepawn>

Keys do not have a one-to-one mapping with values; there may be duplicates. You can iterate over the available key / value pairs matching the key name with <tt>EntityLumpEntry.GetNextKey()</tt>:

<sourcepawn>
// get the 'logic_auto' from the list
EntityLumpEntry entry = EntityLump.Get(2);
char outputString[256];
for (int i = -1; (i = entry.GetNextKey("OnMapSpawn", outputString, sizeof(outputString), i)) != -1;)
{
// print all of the logic_auto's OnMapSpawn outputs
LogMessage("OnMapSpawn output: %s", outputString);
}
delete entry;
</sourcepawn>

[[Category:SourceMod Scripting]]

User:Nosoop/Guide/Game Server Configuration

2023-09-22T03:45:13Z

Nosoop: /* General */ Add section on profiling

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

== Profiling ==

In some cases you will run into server hitches. If you have a general idea of when it happens, you can start the Source Engine's profiler:

<pre>
sm prof start vprof
</pre>

Continue playing, then once you think you've gathered enough data, you can stop profiling and have it dumped out to a file:

<pre>
sm prof stop
con_logfile "vproflog.txt"
sm prof dump vprof
con_logfile ""
</pre>

The profiler results will be in <tt>vproflog.txt</tt> in your game directory.

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

{{note|This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.}}

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the latest version of the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands (including <tt>+map</tt> as a launch option), as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins and integrations (game server providers / panels and other software) may or may not support this functionality.

'''Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers.''' That is often repeated, yet bad advice, as:

* Players will download the map from your download server instead of through Steam
* You will need to manually update the map whenever the Workshop version is updated
* Players may receive map mismatch errors and fail to connect if the non-Workshop release differs from the Workshop version

Keep things simple and use the Valve-documented method. If you insist on using a non-Workshop version, get it from the correct sources.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-22T15:24:20Z

Nosoop: /* Using Workshop maps */ Add note on +map

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

{{note|This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.}}

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the latest version of the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands (including <tt>+map</tt> as a launch option), as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins and integrations (game server providers / panels and other software) may or may not support this functionality.

'''Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers.''' That is often repeated, yet bad advice, as:

* Players will download the map from your download server instead of through Steam
* You will need to manually update the map whenever the Workshop version is updated
* Players may receive map mismatch errors and fail to connect if the non-Workshop release differs from the Workshop version

Keep things simple and use the Valve-documented method. If you insist on using a non-Workshop version, get it from the correct sources.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-22T15:22:58Z

Nosoop: /* Using Workshop maps */

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

{{note|This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.}}

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the latest version of the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands, as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins and integrations (game server providers / panels and other software) may or may not support this functionality.

'''Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers.''' That is often repeated, yet bad advice, as:

* Players will download the map from your download server instead of through Steam
* You will need to manually update the map whenever the Workshop version is updated
* Players may receive map mismatch errors and fail to connect if the non-Workshop release differs from the Workshop version

Keep things simple and use the Valve-documented method. If you insist on using a non-Workshop version, get it from the correct sources.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-22T15:15:26Z

Nosoop: /* Using Workshop maps */ Next person to suggest subscribing dies

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

{{note|This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.}}

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins may or may not support this functionality.

'''Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers.''' That is often repeated, yet bad advice.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-15T05:31:16Z

Nosoop: /* Using Workshop maps */ Convert heading to use note

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

{{note|This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.}}

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins may or may not support this functionality.

Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers. That is often repeated, yet bad advice.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-15T05:29:35Z

Nosoop: /* Using Workshop maps */ Reword TF2-specific heading

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

(This section has instructions specific to Team Fortress 2, and will likely not carry over to other games such as Counter-Strike: Global Offensive.)

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins may or may not support this functionality.

Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers. That is often repeated, yet bad advice.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-15T05:27:44Z

Nosoop: /* Using Workshop maps */ Add note that this is TF2-specific

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

(This are instructions specific to Team Fortress 2; other games such as Counter-Strike: Global Offensive may have different instructions.)

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins may or may not support this functionality.

Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers. That is often repeated, yet bad advice.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-07-15T05:26:16Z

Nosoop: /* Team Fortress 2 */ Add section on using Workshop maps

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Using Workshop maps ===

[https://www.teamfortress.com/post.php?id=17214 As described in the patch notes shortly after the feature was added], Valve's intent is for server operators to use map names in the form <tt>workshop/${mapid}</tt>, where <tt>${mapid}</tt> is the ID of the map in the Workshop. For example, [https://steamcommunity.com/sharedfiles/filedetails/?id=619869471 Sulfur] has an ID of 619869471, so you would specify it as <tt>workshop/619869471</tt>.

This allows both the game server and any connected clients to retrieve the map through Steam.

You can use that form in any place that accepts maps, such as the <tt>map</tt>, <tt>changelevel</tt>, and <tt>nextlevel</tt> commands as well as the mapcycle file. SourceMod itself has support to translate the names to their display forms and will do so in first-party plugins; third-party plugins may or may not support this functionality.

Disregard any suggestions to subscribe to the map and copy the file to your game / fast download servers. That is often repeated, yet bad advice.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide

2023-07-15T05:14:59Z

Nosoop: /* Introduction */ Fix heading level

= About =

This was born out of a desire to create a detailed, yet approachable step-by-step on how to get started in SourceMod.

= Pages =

== Introduction ==

* [[/Setup/]] provides a step-by-step on installing a Source Engine dedicated server, Metamod:Source, and SourceMod.

== SourceMod ==

* [[/Basics/]] is a walkthrough on writing one's first plugins.
* [[/How to X/]] is a reference page on performing common operations in SourcePawn.
* [[/Advanced/]] is a page with information on advanced operations (finding and calling game functions, looking up addresses, etc.).
* [[/Development Environments/]] has a list of common editors and instructions on configuring them to compile plugins.

== Non-SourceMod ==

* [[/Game Server Configuration/]] has info on configuring a server.

User:Nosoop/Guide

2023-07-15T05:13:46Z

Nosoop: /* Pages */ Categorize by section

= About =

This was born out of a desire to create a detailed, yet approachable step-by-step on how to get started in SourceMod.

= Introduction =

* [[/Setup/]] provides a step-by-step on installing a Source Engine dedicated server, Metamod:Source, and SourceMod.

== SourceMod ==

* [[/Basics/]] is a walkthrough on writing one's first plugins.
* [[/How to X/]] is a reference page on performing common operations.
* [[/Advanced/]] is a page with information on advanced operations (finding and calling game functions, looking up addresses, etc.).
* [[/Development Environments/]] has a list of common editors and instructions on configuring them to compile plugins.

== Non-SourceMod ==

* [[/Game Server Configuration/]] has info on configuring a server.

User:Nosoop/Guide/Advanced

2023-06-01T08:30:42Z

Nosoop: /* SDKCall Order */ Add missing variable in example

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= What is gamedata? =

''Gamedata'', also known as game data, gameconfig, and gameconf, are files used to specify information tied to a specific game.

As the games that SourceMod runs on are updated independently of SourceMod itself, gamedata is used as a unified way to keep plugins and extensions up to date on game changes without needing to recompile them.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>].

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
Address pTest;
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

== Calling via Signature or Offset? ==

If you have a class with a virtual method, you generally should set up the <tt>SDKCall</tt> to take a virtual offset. Doing so allows your plugin to have the expected interactions with other plugin's hooks, covered in the next section.

You should use a signature either when the function is not virtual or if you need to bypass the virtual override on an entity (e.g. calling the parent class's function). In those instances, only detours will take effect.

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.

User:Nosoop/Guide/Advanced

2023-06-01T08:28:05Z

Nosoop: /* Calling Game Functions */ Add section on whether to set up function calls using signatures or offsets

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= What is gamedata? =

''Gamedata'', also known as game data, gameconfig, and gameconf, are files used to specify information tied to a specific game.

As the games that SourceMod runs on are updated independently of SourceMod itself, gamedata is used as a unified way to keep plugins and extensions up to date on game changes without needing to recompile them.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>].

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

== Calling via Signature or Offset? ==

If you have a class with a virtual method, you generally should set up the <tt>SDKCall</tt> to take a virtual offset. Doing so allows your plugin to have the expected interactions with other plugin's hooks, covered in the next section.

You should use a signature either when the function is not virtual or if you need to bypass the virtual override on an entity (e.g. calling the parent class's function). In those instances, only detours will take effect.

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.

User:Nosoop/Guide/Game Server Configuration

2023-05-26T11:05:22Z

Nosoop: /* 64-bit Linux systems and 32-bit executables */ Add zlib

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib lib32z1</tt>
* Arch: <tt>pacman -S lib32-gcc-libs lib32-zlib</tt>
* Fedora: <tt>yum -y install glibc.i686 zlib.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Game Server Configuration

2023-05-12T05:48:27Z

Nosoop: /* General */ Add section on RCON

Source Engine games often differ in configuration; here are some basic suggestions on how to set them up for either testing or production use.

= General =

The following section(s) apply to most, if not all games.

== Fast Downloads ==

The Source Engine normally provides downloads over the same channel as gameplay, which is rather slow.

"Fast" downloads are downloads served out-of-band over HTTP, and as such you will need to have a web (HTTP) server up and running to take advantage of this functionality. This is highly recommended if you are running a server with any amount of custom content that a player needs to download (models, sounds, maps).

If you're using a game server provider, you may already have access to a web server for fast download purposes; check with your provider to confirm.

Examples of web servers include: [https://www.nginx.com/ nginx], [https://caddyserver.com/ Caddy], [https://httpd.apache.org/ Apache], [https://www.rejetto.com/hfs/ HFS], and [https://en.wikipedia.org/wiki/Comparison_of_web_server_software many others] (and many more not included in that list).

Once you have an HTTP server running, configure <tt>sv_downloadurl</tt> as follows:

<pre>sv_downloadurl "http://{your_server_location}/{path}";
</pre>

The URL must be quoted, as <tt>//</tt> is treated as the start of a comment and if left unquoted, the rest of the line will be ignored. Do not include a trailing slash — the game client adds one when making the request; web servers are not guaranteed to collapse double slashes in the path.

<tt>{path}</tt> should be the path on your server that would translate to the root of your game server.

For example, if you have a file <tt>sound/my_server/fart.mp3</tt> and an <tt>sv_downloadurl</tt> value of <tt><nowiki>http://example.com/gameserverdownloads</nowiki></tt>, the client will request <tt><nowiki>http://example.com/gameserverdownloads/sound/my_server/fart.mp3</nowiki></tt> (and its BZip2-compressed equivalent).

You will need to also copy the files from the game server to the web server.

== SourceMod extension not loading ==

By default, if no plugin depends on an extension, it won't be loaded automatically, nor will it show up in <tt>sm exts list</tt>.

Use <tt>sm exts load ${extension}</tt> if you'd like to test if it loads and to see if it fails, or add an <tt>${extension}.autoload</tt> file (empty or not) in the extensions directory if you always want it to load.

== RCON ==

The [https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON Protocol] allows users to remotely issue console commands to dedicated server instances.

You likely won't need this, because you can issue console commands through

* running the server instance in a terminal multiplexer session (with <tt>screen</tt> or <tt>tmux</tt>)
* your game server provider providing a web interface that provides real-time console input and output

If you have full access to the machine that your server runs on, you can block RCON packets by dropping TCP packets going to the game port entirely.

Note that doing so will also prevent use of third-party extensions that process TCP connections on the game port, such as [https://forums.alliedmods.net/showthread.php?t=270962 Conplex].

You can use the following on Linux, if you are using iptables:

<pre>
# the following commands append rules to the firewall; the order here is important
# change 27015 to the game port

# accept RCON traffic that comes from the same machine, for things like SourceBans
# if you know you aren't using anything else that relies on RCON you may omit this
# if legitimate RCON traffic may come from elsewhere, change the source network (-s 127.0.0.1/8),
# or append additional rules for addresses that should be allowed
iptables -A INPUT -p tcp --dport 27015 -s 127.0.0.1/8 -j ACCEPT

# drop everything else going to the game port
iptables -A INPUT -p tcp --dport 27015 -j DROP
</pre>

= Platform-specific =

== Linux extension failing to load on outdated <tt>GLIBCXX_*</tt> version ==

Various Source Engine games (Counter Strike: Source, Day of Defeat: Source, Counter Strike: Global Offensive, third-party games using the Source SDK modding system, possibly others) bundle standard libraries that are older than what current operating systems ship with, but newer than those that Valve ships as a baseline.

Software that depends on new versions of libraries will fail to load. This includes Metamod:Source, SourceMod, and other native code / plugins / extension.

You can choose to do one of the following:

* Remove any existing copies of <tt>bin/libstdc++.so.6</tt> and <tt>bin/libgcc_s.so.1</tt> relative to your game install directory (not the root of the filesytem); this will let the game load the system libraries.
** If you are on a 64-bit system, continue to the [[#64-bit_Linux_systems_and_32-bit_executables|next section]] to ensure the system's 32-bit libraries are actually available after removing the Valve-bundled copies.
* If your operating system is also dated, you will need rebuild the extension using an older build environment, or upgrade to a newer one. If you plan on recompiling the extension, the [https://github.com/ValveSoftware/steam-runtime Steam Runtime SDK] is considered the baseline of support.

== 64-bit Linux systems and 32-bit executables ==

[https://sporks.space/2022/02/27/win32-is-the-stable-linux-userland-abi-and-the-consequences/ Unlike Windows], 64-bit Linux systems are not guaranteed to ship with full compatibility for 32-bit executables by default.

Depending on your distribution, you will need to run one of the following commands as root to install the required packages / libraries:

* Debian / Ubuntu: <tt>apt install gcc-multilib</tt>
* Arch: <tt>pacman -S lib32-gcc-libs</tt>
* Fedora: <tt>yum -y install glibc.i686</tt>

= Game Specific =

== Team Fortress 2 ==

The [https://wiki.teamfortress.com/wiki/Dedicated_server_configuration Dedicated server configuration] section on the Team Fortress 2 Official Wiki provides general configuration instructions. Depending on the platform you're working on, you may also be interested in the sections for [https://wiki.teamfortress.com/wiki/Linux_dedicated_server Linux] and [https://wiki.teamfortress.com/wiki/Windows_dedicated_server Windows].

=== Mann vs. Machine ===

Set <tt>tf_mvm_min_players_to_start</tt> to 1 to only require one player to ready up and start the mission.

=== Steam Datagram Relay ===

The Steam Datagram Relay routes both server and client connections through the Steam network, hiding the IP address of each from the other.

Pass <tt>-enablefakeip</tt> in the server's launch options to enable. The server will then report "FakeIP allocation succeeded" at the end of startup; use that IP address / port combination in your game client to connect to the server. This allocation will change on every server startup.

=== Games that aren't ===

Non-exhaustive list of Source Engine class-based shooters with a cartoon-like visual style based on the art of Dean Cornwell, J. C. Leyendecker, and Norman Rockwell, that aren't [https://store.steampowered.com/app/440/Team_Fortress_2/ Team Fortress 2]:

* Team Fortress 2 Classic
* Open Fortress

If you're developing plugins and asking questions about one of those games, please specifically name them. These games are not guaranteed to behave the same as "retail" Team Fortress 2, and solutions that work for retail aren't guaranteed to work on third-party mods.

== Counter-Strike: Global Offensive ==

The [https://developer.valvesoftware.com/wiki/Counter-Strike:_Global_Offensive_Dedicated_Servers#Advanced_Configuration Advanced Configuration] section on the Valve Developer Wiki describes server configuration unique to CS:GO. It's different from most other mods.

=== Responsive server console when hibernating ===

Set <code>sv_hibernate_ms</code> to 0 to make the server console more responsive when no players are online.

== Left 4 Dead 2 ==

=== Disabling lobby system ===

While developing plugins, you generally don't want players being connected through Steam's lobby system. Add the following to <code>server.cfg</code>:

<pre>sv_allow_lobby_connect_only "0";
sv_password "password_to_connect_with";
</pre>

= Virtual Server Configuration =

As a developer, you may need to test on multiple platforms. To avoid having another physical machine to work on, you can use virtualization to run an operating system on your desktop.

== Virtualbox ==

=== Networking ===

==== Network Address Translation ====

With NAT plus port forwarding, the minimum would be to forward UDP from one of the host's loopback IP addresses to the server port on the VM's address. Forwarding TCP isn't necessary unless you are interested in using the RCON protocol.

For example, given a virtual machine with an IP address of <tt>10.0.2.15</tt> and the server listening on port 27015, you should configure NAT as follows:

* <tt>127.0.2.15:27015</tt> (host) → <tt>10.0.2.15:27015</tt> (guest)

You can then connect to the server from the host OS by connecting to <tt>127.0.2.15:27015</tt>.

Any loopback IP address on the host portion is acceptable to use (that is, any address starting with <tt>127.*.*.*</tt>).

==== Host-Only Adapter ====

Enable the Host-Only Adapter on your VM and statically assign the address to be in the same network as your host operating system's adapter. This allows you to connect to the server without any additional networking complexities.

User:Nosoop/Guide/Advanced

2023-05-08T09:18:50Z

Nosoop: Add primer on gamedata

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= What is gamedata? =

''Gamedata'', also known as game data, gameconfig, and gameconf, are files used to specify information tied to a specific game.

As the games that SourceMod runs on are updated independently of SourceMod itself, gamedata is used as a unified way to keep plugins and extensions up to date on game changes without needing to recompile them.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>].

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.

User:Nosoop/Guide/Advanced

2023-04-16T10:39:25Z

Nosoop: /* SDKCall Order */ Put return buffer items into a list; add notes on string return

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

= Finding Functions =

* TODO refer to public SDK if you don't know what you're looking for
* TODO explain what to do in a game with symbols
* TODO suggest opening IDA's options and enabling opcode bytes
* TODO inlined functions
* TODO debugging

= Finding VTable Offsets =

In C++, a ''virtual method table'' (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual <code>::DoThing()</code> method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

== The Hard Way ==

Once you have the virtual call, jump to its reference in <tt>.rodata</tt> and make a note of that address. Scroll up until you see an offset reference (<tt>off_*</tt> in IDA, <tt>PTR_*</tt> in Ghidra); that is likely the first entry in the vtable (index 0). This reference is created by disassemblers as this is the address that is stored in class instances.

Get the difference between your virtual call's address and that of the first entry, then divide by the pointer size (4 on 32-bit platforms, 8 on 64-bit).

For example, given a 32-bit function pointer located at <tt>011AE84Ch</tt> and the start at <tt>011AE3C8h</tt>, you do <tt>(0x011AE84C-0x011AE3C8) / 4</tt>, resulting in the index 289.

Alternatively, if you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

<pre>
; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03 mov eax, [ebx]

; push the class instance as a parameter
89 1C 24 mov [esp], ebx

; call the fourth entry (at index 3) in the vtable: 0xC / sizeof(void*) = 0x3
FF 50 0C call dword ptr [eax+0Ch]
</pre>

== The Easy Way ==

If the game isn't stripped of debugging symbols, use [https://asherkin.github.io/vtable/ asherkin's VTable Dumper]. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct, so you may need to be careful in those cases. Known cases include:

* [https://github.com/asherkin/vtable/issues/7 Classes that have discontinuous overloaded functions]
* Possibly multiple inheritance

Aside - the layout of vtables is not the same across platforms. Notable differences are:

# Linux may have multiple virtual destructors; Windows appears to only have up to one.
# Linux overloads are in the same order as they are initially defined in the original code. On Windows, this is the same, except that overloaded functions (those with the same name that accept different parameters) are grouped together and emitted in reverse order.

= Creating Signatures =

== The Hard Way ==

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a ''signature''.

{{Note|If you're using IDA and only see the mnemonics in the "IDA View" tab, make sure to set the number of opcode bytes in IDA options to a non-zero number. 8 is sufficient in most cases.}}

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the ''instructions'' might be the same for "move X to Y", but the ''data'' might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

<pre>
; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary in little-endian format (0x0125B33B)
C7 04 24 3B B3 25 01 mov dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00 call _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08 mov eax, [ebp+arg_0]
</pre>

The naive signature for that would be <code>\xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08</code>. However, you can't rely on those bytes mentioned to be constant at all:

* The offsets of <code>aString</code> and <code>UTIL_VarArgs</code> might be located somewhere else after a game update
* Relocations may be performed such that the data bytes are different in memory from its on-disk representation

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence <code>\x2A</code> indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as <code>??</code>:

<pre>
C7 04 24 ?? ?? ?? ?? mov dword ptr [esp], offset aString
E8 ?? ?? ?? ?? call _Z12UTIL_VarArgsPKcz
8B 45 08 mov eax, [ebp+arg_0]
</pre>

A masked signature would then be <code>\xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08</code>.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

{{Note|This is no longer the case as of SourceMod 1.11, which stores a copy of the original data for scanning purposes. However, it's noted here for historical / implementation detail reasons.}}

For an extended lesson, you can look at the following material:

* [https://wiki.alliedmods.net/Signature_Scanning Signature Scanning] on the AlliedModders wiki

== The Easy Way ==

If you're using IDA (including Free), use the [https://github.com/alliedmodders/sourcemod/blob/master/tools/ida_scripts/makesig7.idc <code>makesig7.idc</code>] script. If you're using Ghidra, use [https://github.com/alliedmodders/sourcemod/blob/master/tools/ghidra_scripts/makesig.py <code>makesig.py</code>].

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

Both scripts may produce different byte signatures for the same function due to using different methods to determine if a given byte should be masked.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

If two copies of a function seem to exist, be sure to look at the disassembly to make sure that the functions are indeed the same.

= Finding Addresses =

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

<code>read</code> keys indicate an offset to load / dereference relative to the previous address, and <code>offset</code> means to shift the previous address without any dereference. These key / value pairs are processed in the order you specify them in the file; <code>offset</code> is only valid as the last "operation".

For a C++-like example:

<pre class="cpp">// start from an address
// "FindLocation" would return the location of either a named symbol reference or the start of a byte signature
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"
</pre>

{{Note|This section is a work-in-progress.}}

= Calling Game Functions =

{{Note|This section is a work-in-progress.}}

== SDKCall Order ==

When performing an {{SourceMod API|file=sdktools|function=SDKCall}}, the parameters need to be passed in the following order:

# The SDKCall handle received from {{SourceMod API|file=sdktools|function=EndPrepSDKCall}}.
# The <tt>this</tt> instance. <tt>this</tt> may be omitted in the following cases:
#* The function was declared as static, where there is no <tt>this</tt> to pass in.
#* The function was declared with the <tt>SDKCall_GameRules</tt> or <tt>SDKCall_EntityList</tt> call types; SDKTools itself will provide the appropriate global instance.
# The return buffer, if applicable.
#* If the function returns a <tt>Vector</tt> or <tt>QAngle</tt>, the parameter is a <tt>float[3]</tt>.
#* If the function returns a <tt>char*</tt>, the parameters should be a <tt>char[]</tt> buffer and an <tt>int</tt> specifying the size of the buffer. The return value of the SDKCall will be the number of characters written, or -1 if the function returned a null pointer (to differentiate between an empty string).
#* If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
# Any remaining parameters for the function.

Examples:
<pre class="cpp">// Vector CBaseCombatCharacter::Weapon_ShootPosition() -- has 'this' and 'Vector' return
float vecShootPosition[3];
SDKCall(g_hSDKCall, client, vecShootPosition);

// const char *CBaseAnimating::GetSequenceName(int iSequence) -- has 'this', 'char*' return, and parameter
char sequenceName[64];
SDKCall(g_hSDKCall, entity, sequenceName, sizeof(sequenceName), iSequence);

// bool CGlobalEntityList::IsEntityPtr(void* pTest) -- SDKCall_EntityList is used, so no 'this' explicitly needed
// SDKCall passes the return value from the called function as its return value, so use an assignment operator
bool result = SDKCall(g_hSDKCall, pTest);
</pre>

= Hooking Game Functions (with DHooks) =

DHooks is an extension bundled with SourceMod that enables plugins to hook functions of their choosing (currently restricted to those accessible via server / engine binaries). You may use its functionality by including {{SourceMod API|file=dhooks}}.

As with {{SourceMod API|file=sdktools|function=SDKCall}}s, you must ensure that your hook setup is declared with the same parameter and return types to ensure the server continues to operate as you'd expect.

{{Note|This section is a work-in-progress.}}

== Virtual Hook or Detour? ==

A virtual hook is mainly used for hooking virtual methods of a class; a detour is used for hooking any function.

While detours can be used to hook the function a virtual table calls into, virtual hooks still have the merit of hooking specific classes / instances. More specifically:

* DHooks provides the bookkeeping on which instances are and aren't hooked, so for virtual hooks the callback will only be invoked on those you specifically hook. On detours, you have to filter on instances yourself.
* On chained inheritance, a virtual hook will only act on the exact class and not any parent nor subclasses, even if they all point to the same virtual function. Detours will, again, be called on any invocation of the function, including calls to it made by its subclass.

User:Nosoop/Guide/Basics

2023-04-16T10:30:48Z

Nosoop: Insert notes on comments

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

// this is a comment

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>// this is a comment</pre>

Two forward slashes (<code>//</code>) indicate the start of a start of a single-line comment. Single-line comments start from those forward slashes and continue up until the end of the line of text. Comments are not compiled into the actual code, but serve as informational pieces of text for the reader. These will be used later in the guide to streamline reading.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network and intended to ensure the server and connected clients have the correct information.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means; probably related to either snapshots or game saves. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class that need to be kept track of in some way.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code> files. This will provide you with a list of properties associated with each entity class.

{{Note|Some names are listed as both netprops and dataprops on the same class. In that situation, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_no_clip", RemoveClip);
}

Action RemoveClip(int client, int argc) {
if (client == 0) {
// this command is being run by the server console, not an actual player; we can't work with that
return Plugin_Handled;
}

// client is an entity index - we perform a lookup to get the entity assigned to m_hActiveWeapon, if one exists
int weapon = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");
if (IsValidEntity(weapon)) {
// the client has an active weapon - zero out its clip
SetEntProp(weapon, Prop_Send, "m_iClip1", 0);
}
return Plugin_Handled;
}
</pre>

There are many ways to get entities depending on what you are doing. Some of them are passed directly as a callback argument, others you need to call a function to get one, and others you enumerate over a known allocated space to check.

{{Note|Some properties may not work when set directly.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Basics

2023-04-16T10:22:30Z

Nosoop: /* Entity Properties */ Reword some bits

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network and intended to ensure the server and connected clients have the correct information.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means; probably related to either snapshots or game saves. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class that need to be kept track of in some way.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code> files. This will provide you with a list of properties associated with each entity class.

{{Note|Some names are listed as both netprops and dataprops on the same class. In that situation, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_no_clip", RemoveClip);
}

Action RemoveClip(int client, int argc) {
if (client == 0) {
// this command is being run by the server console, not an actual player; we can't work with that
return Plugin_Handled;
}

// client is an entity index - we perform a lookup to get the entity assigned to m_hActiveWeapon, if one exists
int weapon = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");
if (IsValidEntity(weapon)) {
// the client has an active weapon - zero out its clip
SetEntProp(weapon, Prop_Send, "m_iClip1", 0);
}
return Plugin_Handled;
}
</pre>

There are many ways to get entities depending on what you are doing. Some of them are passed directly as a callback argument, others you need to call a function to get one, and others you enumerate over a known allocated space to check.

{{Note|Some properties may not work when set directly.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Setup

2023-04-04T16:35:53Z

Nosoop: /* Picking an IDE */ Raise VSCode due to popularity, remove version number for Sublime Text

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
# You may want to verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider — recommended when starting out due to it being zero-install; once you are doing more than one-off plugins, move on to one of the non-web text editors
* Visual Studio Code (VSCode) — an increasingly popular choice combined with [https://github.com/Sarrus1/sourcepawn-vscode Sarrus's VSCode extension]
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Basics

2023-04-04T15:58:05Z

Nosoop: /* Entity Properties */ Phrasing!

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code> files. This will provide you with a list of properties associated with each entity class.

{{Note|Some names are listed as both netprops and dataprops on the same class. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_no_clip", RemoveClip);
}

Action RemoveClip(int client, int argc) {
if (client == 0) {
// this command is being run by the server console, not an actual player; we can't work with that
return Plugin_Handled;
}

// client is an entity index - we perform a lookup to get the entity assigned to m_hActiveWeapon, if one exists
int weapon = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");
if (IsValidEntity(weapon)) {
// the client has an active weapon - zero out its clip
SetEntProp(weapon, Prop_Send, "m_iClip1", 0);
}
return Plugin_Handled;
}
</pre>

There are many ways to get entities depending on what you are doing. Some of them are passed directly as a callback argument, others you need to call a function to get one, and others you enumerate over a known allocated space to check.

{{Note|Some properties may not work when set directly.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Basics

2023-04-04T14:37:35Z

Nosoop: /* Entity Properties */ Add example of working with entity properties

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code>. This will provide you with a list of properties associated with each entity class.

{{Note|Some names refer to both netprops and dataprops. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_no_clip", RemoveClip);
}

Action RemoveClip(int client, int argc) {
if (client == 0) {
// this command is being run by the server console, not an actual player; we can't work with that
return Plugin_Handled;
}

// client is an entity index - we perform a lookup to get the entity assigned to m_hActiveWeapon, if one exists
int weapon = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");
if (IsValidEntity(weapon)) {
// the client has an active weapon - zero out its clip
SetEntProp(weapon, Prop_Send, "m_iClip1", 0);
}
return Plugin_Handled;
}
</pre>

There are many ways to get entities depending on what you are doing. Some of them are passed directly as a callback argument, others you need to call a function to get one, and others you enumerate over a known allocated space to check.

{{Note|Some properties may not work when set directly.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Basics

2023-04-04T14:17:58Z

Nosoop: /* Entity Properties */ Describe what an entity is

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code>. This will provide you with a list of properties associated with each entity class.

{{Note|Some names refer to both netprops and dataprops. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Basics

2023-04-04T10:52:10Z

Nosoop: /* What's in a Plugin */ Add notes to include, clarify 'forward' functions

At this point you should have a server to test plugins on and a full development environment to write plugins with.

= Hello! =

As is tradition with other programming languages, we'll start with something that outputs <code>Hello, world!</code> in some form. In this case, you'll install the plugin on your server and load it; the message will be printed in the server console.

Open up your editor, and enter the following code:

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
PrintToServer("Hello, world!");
}
</pre>
Save this file as <code>01_hello.sp</code>. SourcePawn scripts always contain the <code>.sp</code> extension.

Compile your code. Refer to your [[../Development Environments|IDE-specific documentation]] for this.

On a successful compile, you should see the following:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

Code size: 2960 bytes
Data size: 2240 bytes
Stack/heap size: 16384 bytes
Total requirements: 21584 bytes
</pre>

The first few lines may be slightly different between SourceMod compiler versions, but as long as you see the four "bytes" lines, you've successfully compiled the plugin, and you should have a <code>01_hello.smx</code> file.

If there was an error in compilation, you'll see something like this instead:

<pre>
SourcePawn Compiler 1.9
Copyright (c) 1997-2006 ITB CompuPhase
Copyright (c) 2004-2017 AlliedModders LLC

01_hello.sp(4 -- 5) : error 001: expected token: ",", but found "}"

1 Error.
</pre>

You'll need to be able to read these sorts of error messages and understand the common ones, because no developer is immune to writing code without any errors all the time.

In this case, the compiler tells us that my <code>01_hello.sp</code> (intentionally made to fail - the code above should compile correctly) has an error around lines 4 and 5, and gives us information about what caused it to not compile the code.

{{Note|Warnings are not errors.
Learn to differentiate between the two. If you get a lot of messages when compiling a large plugin, prioritize resolving the errors. It's possible that some syntax error is causing all sorts of warnings down the line.}}

== Running the Plugin ==

Copy the <code>01_hello.smx</code> file to your game server's <code>addons/sourcemod/plugins/</code> directory.

If the server is already running, get to the server console and type <code>sm plugins load 01_hello</code> to load the plugin. You should see the following:

<pre>
Hello, world!
[SM] Loaded plugin 01_hello.smx successfully.
</pre>

If so, congratulations! You just wrote your first plugin.

== What's in a Plugin ==

Adding text to a file, compiling it, and running the resulting plugin is one thing; it's much more important to understand what the text you're writing actually does.

We'll start from the top:

<pre class="sourcepawn">#include <sourcemod>
</pre>
This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include <sourcemod></code> tells the preprocessor to include the files that make up SourceMod's standard library. There are other first- and third-party libraries that you may want to include later on.

Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.

<pre>public void OnPluginStart() {
</pre>
This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.

SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets. If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.

<pre> PrintToServer("Hello, world!");
</pre>
This line tells SourceMod to tell the game to print text to the server console. <code>PrintToServer</code> is a function defined in SourceMod's standard library. The <code>"Hello, world!"</code> string is passed as an ''argument'' to <code>PrintToServer</code>.

The semicolon (<code>;</code>) indicates the end of the statement.

The <code>}</code> on the following line closes the function body and indicates the end of the <code>OnPluginStart</code> function.

= Listening to Commands =

Continuing with saying hello to things, we'll now get the server to display a message in response to a player command. In doing so, we'll implement a ''callback'' function ourselves.

<pre class="sourcepawn">#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_hello", SayHello);
}

Action SayHello(int client, int argc) {
ReplyToCommand(client, "Hello, %N!", client);
return Plugin_Handled;
}
</pre>
Save the above code as <code>02_helloclient.sp</code>, compile, copy, and load. This time you'll only see the following:

<pre>
[SM] Loaded plugin 02_helloclient.smx successfully.
</pre>

Now, connect to your server and type <code>sm_hello</code> in the client's developer console. You should get:

<pre>
] sm_hello
Hello, (your Steam name)!
</pre>

You can also type <code>/hello</code> or <code>!hello</code> in text chat, and get the response back there. SourceMod automatically registers text chat commands with the <code>sm_</code> prefix stripped.

We'll go a little faster here:

<pre> RegConsoleCmd("sm_hello", SayHello);
</pre>

When the plugin is loaded, {{SourceMod API|file=console|function=RegConsoleCmd}} is called. That function registers a console command <code>sm_hello</code> — when that command is invoked, it invokes the <code>SayHello</code> callback function. The function is internal to the plugin, so it does not need to be marked as <code>public</code> like <code>OnPluginStart</code> is.

<pre>Action SayHello(int client, int argc) {
</pre>
<code>SayHello</code> is a user-defined function that follows the ''prototype'' defined by {{SourceMod API|file=console|function=ConCmd}} . A prototype defines the return type and the parameter types of the function. It must follow that prototype exactly; failure to do so will cause the error "function prototypes do not match", which, to most newer developers, is a familiar compilation error message with words that don't have any sense to them.

In this case, the <code>SayHello</code> function receives a value named <code>client</code> of type <code>int</code>, and one named <code>argc</code>, also of type <code>int</code>; it returns a value of type <code>Action</code>. Refer to the link to <code>ConCmd</code> above for what those parameters mean.

{{Note|If the prototype specifies <code>any</code> as one of the parameter types, the function can substitute that parameter type with any different non-array parameter. If the prototype specifies <code>Handle</code>, the function can substitute the parameter with a <code>Handle</code>-derived type.}}

Next line:

<pre> ReplyToCommand(client, "Hello, %N!", client);
</pre>
<code>ReplyToCommand</code> is a function that tells us to respond to a client (by console or text chat, depending on how the client invoked the command). It takes a minimum of two arguments, the client to respond to, a format string, and optionally a list of format parameters.

In format strings, the <code>%</code> character is special — it indicates a [[Format_Class_Functions_(SourceMod_Scripting)#Format_Specifiers|''format specifier'']]. The link has more information on what specifiers do, but for now just know that <code>%N</code> means that it takes the one of the later format parameters (in this case, the second <code>client</code> parameter that was passed in to the <code>SayHello</code> function) and outputs the player's name.

<pre> return Plugin_Handled;
</pre>
<code>return</code> is a keyword that indicates a value that should be given back to the calling function. The calling function is internal to SourceMod in this case. For a command callback, this is an {{SourceMod API|file=core|function=Action}} enumeration, and we use <code>Plugin_Handled</code> to tell the server that we acknowledge the command. It'll still work without it, but the server console will report "Unknown command" if you don't return with that value.

= Marking Your Territory =

In this section we will discuss the <code>Plugin</code> struct, which lets you provide plugin information when displayed in the plugin list.

{{Note|This section is a work-in-progress.}}

= Entity Properties =

Entity properties are one of the core aspects of game modding.

In this section we will talk about entity send / data properties, and some examples on how to use them.

Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

* sendprops / netprops are properties that are sent over the network.
* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means. Someone should edit this with a better explanation, because this is a wiki.)

While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class.

Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:

<pre>
sm_dump_netprops netprops.txt
sm_dump_datamaps datamaps.txt
</pre>

Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code>. This will provide you with a list of properties associated with each entity class.

{{Note|Some names refer to both netprops and dataprops. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}

= Timers =

In this section we'll talk about timers and how the <code>any data</code> parameter works. We should also talk about passing ephemeral data asynchronously (entities and clients).

{{Note|This section is a work-in-progress.}}

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedhello", DelayedHello);
}

Action DelayedHello(int client, int argc) {
CreateTimer(5.0, DelayedHelloResponse, GetClientSerial(client));
return Plugin_Handled;
}

Action DelayedHelloResponse(Handle timer, int clientserial) {
int client = GetClientFromSerial(clientserial);
if (client) {
PrintToChat(client, "... hello, %N.", client);
}
return Plugin_Handled;
}
</pre>

One coding mistake that leads to confusion down the line is directly passing indices of clients or entities through a callback function. '''Don't do this!''' Such indices aren't unique, and there's no guarantee that you'll act on the same entity once the timer is done — the index may be occupied by a different entity or client (or none at all!), and it may have unexpected consequences.

Don't pass client or entity indices.

''Don't pass client or entity indices.''

What you want to do in these cases is convert the index to a reference or serial value before sending it through the timer, then possibly unwrapping it on the other side. The following function pairs handle common cases:

* {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
* {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
** If you're testing for entity equality e.g. with the result of {{SourceMod API|file=entity|function=GetEntPropEnt}}, ensure that the reference was converted back to an index, or that both values are references.
* {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

= Handles =

A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.

When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.

We'll expand on the timer example above by storing a few more values. You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around. Take a look at the following code:

<pre>#include <sourcemod>

public void OnPluginStart() {
RegConsoleCmd("sm_delayedecho", DelayedEcho);
}

Action DelayedEcho(int client, int argc) {
char message[64];
GetCmdArgString(message, sizeof(message));

// CreateDataTimer instantiates a DataPack instance; normally you would create a handle with "new DataPack()"
DataPack pack;
CreateDataTimer(5.0, EchoResponse, pack);

pack.WriteCell(GetClientSerial(client));
pack.WriteString(message);
return Plugin_Handled;
}

Action EchoResponse(Handle timer, DataPack pack) {
pack.Reset();
int client = GetClientFromSerial(pack.ReadCell());
char message[64];
pack.ReadString(message, sizeof(message));

if (client) {
PrintToChat(client, "Echo! %s", message);
}
return Plugin_Handled;
}

</pre>

{{Note|This section is a work-in-progress. Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}

For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.

= SDKHooks =

SDKHooks is a first-party SourceMod extension that provides a number of useful entity function hooks.

We'll cover SDKHooks here. Maybe. This should probably be shifted over to the quickref.

{{Note|This section is a work-in-progress.}}

If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29|hook a specific function of your choosing with DHooks]].

= Debugging =

As SourceMod is a third-party framework that is bolted on to a game engine, there's very little debug tooling to test plugins at runtime.

Most, if not all plugin authors use {{SourceMod API|file=console|function=PrintToServer}} to print debug their code of runtime errors. Some tips:

* Print the ''exact'' values that are being shown if they're relevant. It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.

= Further Reading =

I'm hoping to have further lessons on writing code here, but for now, you can take a look at the [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]] wiki entries.

Information on SourceMod's standard library is available in the [https://sm.alliedmods.net/new-api/ Scripting API Reference].

User:Nosoop/Guide/Game Server Configuration

2023-04-02T18:08:34Z

Nosoop: /* SourceMod extension not loading */

User:Nosoop/Guide/Setup

2023-04-01T15:19:00Z

Nosoop: /* Installing Metamod:Source */ Enforce spacing consistency between list identifiers

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#* You may need to extract the archive on, or upload the contents to a remote server.
#** If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#** If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
# You may want to verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider (highly recommended when starting out due to it being zero-install; once you have multiple projects, move on to one of the non-web text editors)
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text 3
* Visual Studio Code (VSCode)

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

Building SourceMod

2023-03-26T02:05:59Z

Nosoop: /* Configuring */ Add note on running Python 3

Compiling SourceMod is not difficult, but requires a number of prerequisites. This article details the requirements and steps to being able to build working SourceMod binaries.

Note that specific compiler versions are required to maintain ABI compatibility with Source engine binaries.

=Requirements=

==Windows==

# Install Visual Studio or Visual C++. VS/VC 2010 or above is required for SourceMod 1.6.x and earlier. VS/VC 2013 Update 2 or above is required for SourceMod 1.7.x and later (Express editions should work fine). VS/VC 2015 is required for SourceMod 1.10.x or later.
#* 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].
#* With VS/VC 2017, you may use [https://download.visualstudio.microsoft.com/download/pr/b8d403d9-01a4-45a0-9229-db5572fd5e4e/997600ae09705dfc6d069d8ad2cfad1962d8ff6fedd6c9fe5abee36c7c919f34/vs_BuildTools.exe the build tools installer] to install the minimal set of packages.
#** You will want to install the following: .NET 4.6.1 SDK and corrresponding targeting pack, C++/CLI support, VC++2015.3 v14.00 toolset for desktop, Visual C++ Build Tools core features, Windows 8.1 SDK, and Windows Universal C Runtime.
#** When attempting to configure and build, use the "VS2015 x86 Native Tools Command Prompt" Start Menu option to have the build tools available in the current Command Prompt's PATH.
#* With [https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019 Build Tools for Visual Studio 2019], you can install the following individual components: MSVC v140 - VS 2015 C++ build tools (v14.00), Windows Universal CRT SDK, and Windows 10 SDK.
# Install [http://git-scm.com/ Git]. Make sure that you select the option that adds Git to PATH.
# Next, you will need to start an environment capable of running Python and interacting with the Visual Studio compiler.
#* Install [http://python.org/ Python]. Versions newer than 3.3 are supported; at the time of writing the latest available version is 3.11.
#* 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).
#* 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.

==Linux==
<ol>
<li>Install Git, via either system packages or from the [http://git-scm.com/ Git] distribution.</li>
<li>Install a C++ compiler and dependencies. SourceMod officially supports clang. For example, on Ubuntu/Debian:
<pre>
sudo apt-get install clang lib32stdc++-7-dev lib32z1-dev libc6-dev-i386 linux-libc-dev:i386
</pre>
<li>If building on a 64-bit system, you must install the 32-bit libraries for the compiler; e.g.:
<pre>
sudo apt-get install g++-multilib
</pre>
</ol>

==Archlinux==

# Enable multilib repository as described in the [https://wiki.archlinux.org/index.php/multilib Archlinux wiki page].
# Install the following packages:
#:<pre>pacman -S git python2 gcc-multilib lib32-glibc lib32-libstdc++5 lib32-zlib</pre>

==Mac OS X==
Mac OS X 10.7 to 10.14 is required to build, however, SourceMod will work on 10.5. SourceMod will neither build nor run on older PPC Macs.
Newer versions are unsupported due to the removal of 32 bit support from MacOS.

<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. SourceMod cannot build without Xcode's command line tools.</li>
</ul>
</ol>

=Downloading Source and Dependencies=

First, grab the SourceMod source tree. We recommend placing it inside its own folder, since we'll also need to download its dependencies.

'''You should do a recursive checkout of the git repo since the sourcepawn repo is a submodule of sourcemod now, see https://stackoverflow.com/questions/3796927/how-to-git-clone-including-submodules to do that.'''
<pre>
mkdir -p alliedmodders
cd alliedmodders
git clone --recursive https://github.com/alliedmodders/sourcemod
</pre>

Next, run the <tt>checkout-deps.sh</tt> script. This will download all dependencies and attempt to install AMBuild. If you are using Linux or OS X, it may prompt you for your sudo password at the very end. If you want to skip this and install AMBuild manually, just Ctrl+C. (Do not run the checkout script with sudo.)
<pre>
bash sourcemod/tools/checkout-deps.sh
</pre>

After it's done, you should see a large number of hl2sdk folders and other assorted dependencies, like MySQL, Metamod:Source, and AMBuild.

If you are on Windows, you can use 'checkout-deps' PowerShell script (if it exists), you just may need to swap ExecutionPolicy to a less restrictive one. (See: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies).

Otherwise, you can manually download the dependencies with the commands below:
<pre>
git clone --mirror https://github.com/alliedmodders/hl2sdk hl2sdk-proxy-repo
# For each SDK you want to build with:
# git clone hl2sdk-proxy-repo hl2sdk-<SDK> -b <SDK>
# e.g. git clone hl2sdk-proxy-repo hl2sdk-csgo -b csgo

git clone https://github.com/alliedmodders/metamod-source mmsource-1.10 -b 1.10-dev

# If building version 1.10 of SourceMod, use MySQL 5.5
wget https://cdn.mysql.com/archives/mysql-5.5/mysql-5.5.54-win32.zip mysql-5.5

# If building < version 1.10 of SourceMod, use MySQL 5.0
wget https://cdn.mysql.com/archives/mysql-5.0/mysql-noinstall-5.0.24a-win32.zip mysql-5.0

# Install AMBuild
git clone https://github.com/alliedmodders/ambuild
pip install ./ambuild
</pre>

Note that you can skip MySQL and SDK versions you don't plan to build.

=Configuring=

The first time you are building a SourceMod tree, you must ''configure'' the build. This step initializes some basic information and allows some customization around how things get compiled.

First create a build folder within your sourcemod folder, and then run <tt>configure.py</tt>. For example:
<pre>
cd sourcemod
mkdir build
cd build
python ../configure.py
</pre>

'''Note:''' If it complains about <tt>Could not find a source copy of Metamod:Source</tt>, rename the <tt>mmsource-11</tt> folder to <tt>metamod-source</tt>. See https://github.com/alliedmodders/sourcemod/blob/master/AMBuildScript#L186-L193 for the valid folder names it looks for

You may also need to run Python as <tt>python3</tt> instead of <tt>python</tt>, depending on your operating system's installed Python version(s).

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-sse - Disable floating point optimizations (if you have a very, very old CPU).
*--no-mysql - Don't build the MySQL database module.
*--sdks css - Only build css.

See configure.py for all the options.

=Building=

To build SourceMod, simply type:
<pre>
ambuild
</pre>

In your build folder. Alternately, you can specify the path of the build folder:
<pre>
ambuild debug-build
</pre>

The full package layout that would be shipped for release is in the <tt>package</tt> folder of the build.

=Deprecated Tools=
==Visual Studio Project Files==
In the future, we will use AMBuild to automatically generate project files, and the existing project files will be removed from the SourceMod tree. In the meantime however, it is possible to use these files. Unfortunately, they require a bit of extra work to use.

First, make sure you've downloaded all necessary dependencies (SDKs, Metamod:Source source code, and MySQL) via the <tt>checkout-windows-deps.bat</tt> script. Next,
#Open the Control Panel (for example, via Start -> Settings).
#Open the System control. If you don't see it, you may need to switch to "Classic view" (either via the left-hand pane or by going to Tools -> Folder Options).
#Click the Advanced tab.
#Click the Environment Variables button.

Now, add your environment variables to either your User settings or your System settings. Create a new variable for each item in the list below. You may omit SDKs that you do not plan to build against. The item names are in <tt>fixed-width font</tt> and their value descriptions follow.
*<tt>MMSOURCE19</tt> - Path to Metamod:Source 1.10+
*<tt>MMSOURCE18</tt> - Path to Metamod:Source 1.10+
*<tt>HL2SDK</tt> - Path to HL2SDK Ep1/Original
*<tt>HL2SDKOB</tt> - Path to HL2SDK Ep2/OrangeBox for mods
*<tt>HL2SDKOBVALVE</tt> - Path to HL2SDK Source 2009 (HL2:DM, DoD:S, TF2)
*<tt>HL2SDK-SWARM</tt> - Path to HL2SDK Alien Swarm
*<tt>HL2SDK-BGT</tt> - Path to HL2SDK for Bloody Good Time
*<tt>HL2SDKCSGO</tt> - Path to HL2SDK CS:GO
*<tt>HL2SDKCSS</tt> - Path to HL2SDK CS:S
*<tt>HL2SDK-DARKM</tt> - Path to HL2SDK Dark Messiah
*<tt>HL2SDK-EYE</tt> - Path to HL2SDK E.Y.E.: Divine Cybermancy
*<tt>HL2SDKL4D</tt> - Path to HL2SDK L4D1
*<tt>HL2SDKL4D2</tt> - Path to HL2SDK L4D2
*<tt>HL2SDK-DOTA</tt> - Path to HL2SDK DOTA 2
*<tt>MYSQL5</tt> - Path to the folder that contains MySQL's <tt>include</tt> and <tt>lib</tt> folders.

==Makefiles==
Makefiles are deprecated and will be removed from the tree soon.

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

User:Nosoop/Guide/Setup

2023-03-25T16:10:16Z

Nosoop: /* Installing the Server */ Link the relevant SteamCMD sections

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to [https://developer.valvesoftware.com/wiki/SteamCMD the SteamCMD entry] in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to [https://developer.valvesoftware.com/wiki/SteamCMD#Running_SteamCMD run the application], [https://developer.valvesoftware.com/wiki/SteamCMD#SteamCMD_Login sign in (anonymously)], and [https://developer.valvesoftware.com/wiki/SteamCMD#Downloading_an_App download your game server].

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#*You may need to extract the archive on, or upload the contents to a remote server.
#**If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#**If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
# You may want to verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider (highly recommended when starting out due to it being zero-install; once you have multiple projects, move on to one of the non-web text editors)
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text 3
* Visual Studio Code (VSCode)

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

User:Nosoop/Guide/Setup

2023-03-25T11:10:15Z

Nosoop: /* Installing the Server */ Convert the dedicated server list to a table

This section assumes that you're starting out with nothing besides a desktop computer, an internet connection, and a drive to program some SourceMod plugins. No programming experience; no problem.

This page will walk you through manually installing the dedicated server software for your desired game, installing SourceMod, and selecting a text editor to use for development.

There are a number of third-party tools that can automate most of these steps, but we'll stick to the first-party approach here to avoid abstractions from breaking under you.

If you are using a third-party tool to manage your server installation, refer to the tool's documentation for their instructions, then skip to [[#Installing SourceMod|Installing SourceMod]] to download the scripting toolchain for your desktop operating system.

= Installing the Server =

{{note|While officially unsupported, SourceMod may be loaded on a game client (the game you launch); the server a game client creates is known as a listen server. However, there are many behavioral quirks that can only be reproduced on a listen server, and you likely won't receive any solutions to those issues that aren't "use a dedicated server".

This guide does not provide instructions to load SourceMod on a game client. It's highly recommended to stick to installing SourceMod on dedicated game server instances to ensure that any plugins you write will have the correct behavior.}}

To install the dedicated server software for the game of your choice, we will use <code>steamcmd</code>. If a game server provider (GSP) is hosting the server for you, skip this step as your provider has already provided you with an installation; if you are using a self-hosted game server management panel, refer to the instructions for your software of choice to install your game server in place of this step.

<code>steamcmd</code> is Valve's command-line Steam client. It is used to install and update dedicated game servers.

Refer to the [https://developer.valvesoftware.com/wiki/SteamCMD SteamCMD] section in the Valve Developer Wiki for download instructions. This varies on the operating system you're running the software on; you can either work on your own desktop or have a hosted (physical or virtual) machine off-premises.

Once <code>steamcmd</code> is extracted, you will need to install a game. Continue reading the above wiki page to run the application, sign in (anonymously), and download your game server.

You will need the AppID of the game's dedicated server to install it; note that it is different from the game client AppIDs. See the below table for that and additional related information for some of the supported games.

{| class="wikitable"
|+ Dedicated Server Information
|-
! Game
! AppID
! Mod Directory
! Notes
|-
| Day of Defeat: Source
| <code>232290</code>
| <code>dod</code>
|-
| Team Fortress 2
| <code>232250</code>
| <code>tf</code>
|-
| Counter-Strike: Source
| <code>232330</code>
| <code>cstrike</code>
|-
| Counter-Strike: Global Offensive
| <code>740</code>
| <code>csgo</code>
|
* As of 1.38.5.2 (2023-02-02), servers running under Linux will need to have a relatively modern libstdc++ installed. [https://www.mail-archive.com/csgo_servers@list.valvesoftware.com/msg14291.html See this mailing list entry for further details.]
* [[Introduction to SourceMod Plugins#Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported?|See the current state of Counter-Strike 2 here.]]
|-
| Left 4 Dead
| <code>222840</code>
| <code>left4dead</code>
|
* This is the one first-party game that requires a [https://www.metamodsource.net/?go=vdf custom VDF file for Metamod:Source].
|-
| Left 4 Dead 2
| <code>222860</code>
| <code>left4dead2</code>
|-
| Half-Life 2: Deathmatch
| <code>232370</code>
| <code>hl2mp</code>
|-
| No More Room in Hell
| <code>317670</code>
| <code>nmrih</code>
|-
| Zombie Panic! Source
| <code>17505</code>
| <code>zps</code>
|-
| Pirates, Vikings & Knights II
| <code>17575</code>
| <code>pvkii</code>
|}

For post-install server configuration, take a look at the [[../Game Server Configuration|Game Server Configuration]] page.

= Installing Metamod:Source =

Before you can install SourceMod on your server, you must first download and install Metamod:Source. Metamod:Source (MM:S) acts as a middleware for different Source Engine games, providing a unified interface for plugins to operate on the game.

SourceMod itself is an MM:S plugin.

# Download [http://www.metamodsource.net/ Metamod:Source]. In most cases, you want a stable release. Use the download package according to your server's operating system.
#* If the latest download is unavailable, go down the "Latest 20 Builds" until you get to one that is.
#* Again, make sure you're downloading the correct package for your server; if you're using a hosted instance, it may not be using the same operating system as your personal desktop.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).
#*You may need to extract the archive on, or upload the contents to a remote server.
#**If you are on Windows, the recommended software to use for extracting Linux (<tt>.tar.gz</tt>) archives is [https://www.7-zip.org/download.html 7-zip]; to upload files remotely via FTP, use [https://winscp.net/eng/index.php WinSCP].
#**If you are using a GSP, refer to their control panel. Most provide FTP access, and some also allow for uploads directly via browser.
# You may want to verify that the installation was successful by starting your server and running <tt>meta version</tt>. It should be treated as a known command at this stage.
#* Most games should work without further configuration, but if you find that MM:S isn't loading, you will want to [https://www.metamodsource.net/?go=vdf generate a custom VDF file]. Known games that require custom VDF files are:
#** Left 4 Dead 1
#** Third-party mods using the Source SDK base
#* Metamod:Source is known to fail to load on CS:GO servers running under Linux by default. You will want to delete <tt>bin/libgcc_s.so.1</tt> relative to the installation directory, plus read the information in the next bullet point.
#* If you are using a Linux server you have full control over, read over the [[User:Nosoop/Guide/Game Server Configuration#Platform-specific|Platform-specific setup]] information.
#* Additional diagnostic information about load failures is available under <tt>metamod-fatal.log</tt>.

{{Note|On server startup, you may see an error message <tt>Unable to load plugin "addons/metamod/bin/${platform}64/server"</tt>. This is normal behavior; the game server will always attempt to load both 32-bit and 64-bit binaries and fail on the one that doesn't match. If you're sure that you're not running a 64-bit game server instance, you can delete <tt>addons/metamod_x64.vdf</tt> to only load the 32-bit version, or the other way around.}}

= Installing SourceMod =

The following is mostly lifted from the [[Installing SourceMod]] page.

# Download [https://www.sourcemod.net/ SourceMod]. Same as before; latest available stable release for your server's operating system.
# Copy the contents of the archive into your game's mod directory (one level below <code>srcds.exe</code> or <code>srcds_run</code>; the mod directory should contain <code>steam.inf</code>).

If you plan on creating new plugins, you will also want to download SourceMod for your ''desktop'' operating system and extract the <code>addons/sourcemod/scripting/</code> folder to a location on your computer.

In the future, you may need to follow [[Upgrading SourceMod|these instructions to upgrade SourceMod]] on your server because of:
* game updates requiring SourceMod to be rebuilt against a new revision of the Source SDK
* plugins compiled against newer versions of SourceMod to take advantage of added functionality

= Picking an IDE =

Now that you have the dedicated game server, Metamod:Source, and SourceMod installed, you have most of the tools you need.

If you've never done any programming, you'll need a text editor. It's completely possible to write code in plain old Notepad and invoke the compiler directly, but having a proper development environment makes it much easier to work with code.

The following editors are known to have good support for SourceMod plugins:

* Spider (highly recommended when starting out due to it being zero-install; once you have multiple projects, move on to one of the non-web text editors)
* BasicPawn
* Notepad++
* SPEdit
* Sublime Text 3
* Visual Studio Code (VSCode)

For more details on each editor and, if necessary, how to set it up for writing SourceMod plugins, look at the [[../Development Environments|Development Environments]] section of the guide.

Once you've settled on a development environment, you can start learning how to create plugins — head over to the [[../Basics|Basics]] section of the guide to get started.

Scripting FAQ (SourceMod)

2023-03-23T15:45:07Z

Nosoop: /* How do I learn SourcePawn? */ Remove underscores from cross-page link

[[Image:Yak.gif]]
yak wuz heer

=How do I learn SourcePawn?=
A good start is on the [[Introduction to SourcePawn 1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.

=Where can I find all the SourcePawn functions and other information?=
All SourceMod plug-ins have this line:

<pawn>#include <sourcemod></pawn>

This line instructs the compiler to retrieve the file <tt>sourcemod.inc</tt> from the <tt>sourcemod/scripting/include</tt> folder. Every function, variable, and definition can be found in the <tt>.inc</tt> files inside the <tt>sourcemod/scripting/include</tt> folder.

But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]

Also, if you are in the AlliedMods Discord server (https://discord.gg/HUc67zN), you can use the <tt>/docs</tt> command to search the API.

=How do I find the classname of an entity? (e.g., "<tt>weapon_knife</tt>" or "<tt>prop_physics</tt>")=
The classname of an entity (not to be confused with a netclass such as <tt>CCSPlayer</tt>) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:

<pawn>char classname[128];
GetEdictClassname(myentity, classname, sizeof(classname));

PrintToServer("myentity classname: %s", classname);
// myentity classname: weapon_knife</pawn>

=How do I block regular commands, such as <tt>kill</tt> and <tt>say</tt>?=
As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.

Here's how to use it to block the <tt>say</tt> command:

<pawn>public void OnPluginStart()
{
AddCommandListener(SayCallback, "say");
}

public Action SayCallback(int client, const char[] command, int argc)
{
return Plugin_Handled;
}</pawn>

=How do I hook +commands, such as <tt>+zoom</tt> and <tt>+attack</tt>?=
Unlike regular commands, <tt>+commands</tt> are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook <tt>+commands</tt>. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a <tt>+command</tt>, you'll first have to find out its proper <tt>IN_</tt> constant (see <tt>[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]</tt>).

Here's how to use it to block crouching when attacking:

<pawn>public Action OnPlayerRunCmd(int client, int &buttons, int &impulse, float vel[3], float angles[3], int &weapon)
{
// Check if the player is attacking (+attack)
if ((buttons & IN_ATTACK) == IN_ATTACK)
{
// If so, block their crouching (+duck)
buttons &= ~IN_DUCK;
}

// We must return Plugin_Continue to let the changes be processed.
// Otherwise, we can return Plugin_Handled to block the commands
return Plugin_Continue;
}</pawn>

=How do I get rid of loose indentation warnings?=
<pre>myplugin.sp(#) : warning 217: loose indentation</pre>

Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.

Good:

<pawn>public void OnPluginStart()
{
int myvar = 5;
if (myvar == (2 + 3))
PrintToServer("myvar is %d", myvar);
}</pawn>

Bad:

<pawn>public voidOnPluginStart()
{
int myvar = 5;
if (myvar == (2 + 3))
PrintToServer("myvar is %d", myvar);
}</pawn>

=How do I get rid of tag mismatch warnings?=
Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are <tt>_</tt> (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), <tt>float</tt>, <tt>bool</tt>, and <tt>char</tt>. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.

Functions wear these tags on their parameters so you can tell what needs to be passed to the function:
<pawn>native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)</pawn>

This function calls for '''<tt>entity</tt>''', a cell with the implied tag '''''<tt>int</tt>'''''; '''<tt>type</tt>''', with the developer-defined tag '''''<tt>PropType</tt>'''''; '''<tt>prop</tt>''', with the built-in tag '''''<tt>char</tt>'''''; and '''<tt>value</tt>''', with the built-in tag '''''<tt>float</tt>'''''.
To call this function, then, you must pass values with the specified tags. For example:
<pawn>SetEntPropFloat(1234, Prop_Send, "m_fNumber", 1.0);</pawn>

This calls the function correctly: <tt>1234</tt> is a regular cell ('''''<tt>_</tt>'''''), <tt>Prop_Send</tt> is a variable defined in the enum '''''<tt>PropType</tt>''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], <tt>"m_fNumber"</tt> is a '''''<tt>char</tt>''''', and <tt>1.0</tt> is a '''''<tt>float</tt>'''''. For a nonexample:
<pawn>SetEntPropFloat(1234.0, 1, "m_fNumber", 1337);</pawn>

This is incorrect! <tt>1234.0</tt> is a '''''<tt>float</tt>''''' that should be a regular cell ('''''<tt>int</tt>'''''); <tt>1</tt> is a regular cell ('''''<tt>int</tt>''''') that should be a '''''<tt>PropType</tt>'''''; and <tt>1337</tt> is a regular cell ('''''<tt>int</tt>''''') that should be a '''''<tt>float</tt>'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''<tt>PropType</tt>''''') can be found in the same file where a function uses them (you can find '''''<tt>PropType</tt>''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).

=How do I add color to my messages?=
Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters <tt>0x01</tt> to <tt>0x08</tt>. For example:
<pawn>PrintToChatAll ("\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8");</pawn>

Example output from Left 4 Dead:

[[Image:Left_4_Dead_Colors.png]]

With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:

* <tt style="color: blue;">0x01</tt> = Normal color
* <tt style="color: blue;">0x02</tt> = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.
* <tt style="color: blue;">0x03</tt> = Team color
* <tt style="color: blue;">0x04</tt> = Location color

This data comes from Counter-Strike: Source.

For CS:GO, here are some colors:
<pawn>PrintToChat("\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF");</pawn>

Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:

<pawn>Handle hBf;
hBf = StartMessageOne("SayText2", player_to); // To send the message to all players, use StartMessageAll("SayText2");
if (hBf != null)
{
BfWriteByte(hBf, player_from);
BfWriteByte(hBf, 0);
BfWriteString(hBf, "<\x03player_from team color\x01> My message");
EndMessage();
}</pawn>

<tt>player_to</tt> is the client index to send the message to (or use [https://sm.alliedmods.net/new-api/usermessages/StartMessageAll StartMessageAll()] instead of [https://sm.alliedmods.net/new-api/usermessages/StartMessageOne StartMessageOne()] to send the message to all players). <tt>player_from</tt> is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming <tt>player_from</tt> is on the RED team):

<player_from team color> My message

There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.

Additionally, CS:S, TF2, HL2:DM, and DoD:S all support RGB(A) hex values in chat messages with <tt style="color: blue;">0x07</tt> and <tt style="color: blue;">0x08</tt>, followed by a 6- or 8- char hex value (e.g., <tt>\x07ABCDEF</tt>, <tt>\x0801234567</tt>).

==Color Libraries==
There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:

===exvel's Colors===
This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as <tt>{default}</tt>, <tt>{green}</tt>, or <tt>{blue}</tt>.

Here's some example usage. Note that this code assumes client 1 is in game and on the BLU team:

<pawn>#include <colors>

public void OnPluginStart()
{
CPrintToChatAll("{green}Hello {red}World! {default}Test 1 concluded.");

int client_on_blu_team = 1;
CPrintToChatAllEx(client_on_blu_team, "{teamcolor}BLU team {default}says {green}hi!");
}</pawn>

Hello World! Test 1 concluded.
BLU team says hi!

Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to <tt>{green}</tt>.

===SMLib===
[http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as <tt>{N}</tt> and <tt>{G}</tt>, and all colors are supported in its <tt>Client_PrintToChat()</tt> function.

Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the BLU team:

<pawn>#include <smlib>

public void OnPluginStart()
{
Client_PrintToChatAll("{G}Hello {R}World! {N}Test 1 concluded.");

int client_on_blu_team = 1;
Client_PrintToChatAll(client_on_blu_team, "{T}BLU team {N}says {G}hi!");
}</pawn>

Hello World! Test 1 concluded.
BLU team says hi!

=Why do I get an "unknown symbol" error when using an SDKTools native?=
None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include <sourcemod> to use SourceMod's functions, you need to:
<pawn>#include <sdktools></pawn>
to use an SDKTools native.

=Why is Source telling me my command is an "Unknown command"?=
This is because you're not returning <tt>Plugin_Handled</tt> in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.

<pawn>public Action MyCommand(int client, int args)
{
// Do something...

return Plugin_Handled;
}</pawn>

Introduction to SourceMod Plugins

2023-03-23T13:14:42Z

Nosoop: /* Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? */ Add answers for ongoing development

This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.

For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [https://forums.alliedmods.net/showthread.php?p=2693577 SPCode], [https://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [https://notepad-plus-plus.org/ Notepad++], [https://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio], [https://forums.alliedmods.net/showthread.php?t=289127 BasicPawn] or any other text editor you're comfortable with to write plugins.

=Starting from scratch=
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not know about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This is done using <tt>#include</tt> directive. It tells the compiler to "paste" the code from another file into yours.
<pawn>#include <sourcemod></pawn>
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice, however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if the compiler doesn't know about the existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. The compiler understands that and generates a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].

=Setting up plugin info=
Now that we got access to SourceMod features, it is time to set up the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin is going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:
<sourcepawn>/**
* Plugin public information.
*/
struct Plugin
{
public const char[] name; /**< Plugin Name */
public const char[] description; /**< Plugin Description */
public const char[] author; /**< Plugin Author */
public const char[] version; /**< Plugin Version */
public const char[] url; /**< Plugin URL */
};</sourcepawn>
and this:
<sourcepawn>/**
* Declare this as a struct in your plugin to expose its information.
* Example:
*
* public Plugin myinfo =
* {
* name = "My Plugin",
* //etc
* };
*/
public Plugin myinfo;</sourcepawn>

It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:
<sourcepawn>public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is the preferable way to fill out plugin info.

After that the full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

=Getting code to run=
We already include SourceMod features and filled up or plugin info. We now have a perfectly well-formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason, we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:
<sourcepawn>/**
* Called when the plugin is fully initialized and all known external references
* are resolved. This is only called once in the lifetime of the plugin, and is
* paired with OnPluginEnd().
*
* If any run-time error is thrown during this callback, the plugin will be marked
* as failed.
*
* It is not necessary to close any handles or remove hooks in this function.
* SourceMod guarantees that plugin shutdown automatically and correctly releases
* all resources.
*
* @noreturn
*/
forward void OnPluginStart();</sourcepawn>
Empty parentheses tell us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:
<sourcepawn>public void OnPluginStart()
{
}</sourcepawn>

Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.
<sourcepawn>/**
* Sends a message to the server console.
*
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @noreturn
*/
native int PrintToServer(const char[] format, any ...);</sourcepawn>
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:
<sourcepawn>public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
That's it! The full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};

public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
Compile and load your plugin on your server and see for yourself that the message is displayed in the server console.

=Includes=
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.
*'''Extension''' - adds a dependency against a certain extension.
*'''Plugin''' - adds a dependency against a certain plugin.

Include files are loaded using the <tt>#include</tt> compiler directive.

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [https://sm.alliedmods.net/new-api/console/RegAdminCmd RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

<sourcepawn>
public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action Command_MySlap(int client, int args)
{
}</sourcepawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<sourcepawn>public Action Command_MySlap(int client, int args)
{
return Plugin_Handled;
}</sourcepawn>

Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand ReplyToCommand()].

Full example:

<sourcepawn>
#include <sourcemod>
#include <sdktools>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt"); // Required for FindTarget fail reply
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];

/* By default, we set damage = 0 */
int damage = 0;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, we set damage to
* what the user specified. If a damage isn't specified
* then it will stay zero. */
if (args >= 2)
{
GetCmdArg(2, arg2, sizeof(arg2));
damage = StringToInt(arg2);
}

/* Try and find a matching player */
int target = FindTarget(client, arg1);
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason and returns -1 so we know not
* to continue
*/
return Plugin_Handled;
}

SlapPlayer(target, damage);
ReplyToCommand(client, "[SM] You slapped %N for %d damage!", target, damage);

return Plugin_Handled;
}</sourcepawn>

For more information on what %N and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommended that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>g_cvarMySlapDamage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<sourcepawn>ConVar g_cvarMySlapDamage = null;

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* The rest remains unchanged! */
</sourcepawn>

=Showing Activity, Logging=
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.

For example, let's rewrite the last few lines of our slap command:
<sourcepawn>
SlapPlayer(target, damage);

char name[MAX_NAME_LENGTH];

GetClientName(target, name, sizeof(name));

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);

return Plugin_Handled;
}
</sourcepawn>

=Multiple Targets=
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first.

The function we use is [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString ProcessTargetString()]. It takes in input from the console and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.

This method of target processing is used for almost every admin command in SourceMod, and in fact, FindTarget() is just a simplified version.

Full, final example:
<sourcepawn>
#include <sourcemod>
#include <sdktools>

ConVar g_cvarMySlapDamage = null;

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt");

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2);
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
char target_name[MAX_TARGET_LENGTH];
int target_list[MAXPLAYERS], target_count;
bool tn_is_ml;

if ((target_count = ProcessTargetString(
arg1,
client,
target_list,
MAXPLAYERS,
COMMAND_FILTER_ALIVE, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
ReplyToTargetError(client, target_count);
return Plugin_Handled;
}

for (int i = 0; i < target_count; i++)
{
SlapPlayer(target_list[i], damage);
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);
}

if (tn_is_ml)
{
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);
}
else
{
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);
}

return Plugin_Handled;
}</sourcepawn>

=Events=
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].

It is important to note a few concepts about events:
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.
*They almost always use userids instead of client indexes.
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious for not properly documenting their event functionality.

An example of finding when a player dies:
<sourcepawn>
public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
int victim_id = event.GetInt("userid");
int attacker_id = event.GetInt("attacker");

int victim = GetClientOfUserId(victim_id);
int attacker = GetClientOfUserId(attacker_id);

/* CODE */
}</sourcepawn>

=Callback Orders and Pairing=
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which can confuse users.

==Pairing==
'''Pairing''' is SourceMod terminology. Examples of it are:
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().
*OnClientConnected(N) for a given client N will only be called once until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).

There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.
*Y cannot be invoked with any input A unless X was called first with input A.
*The relationship is described as, "X is paired with Y," and "Y is paired to X."

==General Callbacks==
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.

* {{SourceMod API|file=sourcemod|function=AskPluginLoad2}} - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
* {{SourceMod API|file=sourcemod|function=OnPluginStart}} - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
* {{SourceMod API|file=sourcemod|function=OnAllPluginsLoaded}} - Called once, after all non-late loaded plugins have called OnPluginStart.
* {{SourceMod API|file=sourcemod|function=OnMapStart}} - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
* {{SourceMod API|file=sourcemod|function=OnConfigsExecuted}} - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
* {{SourceMod API|file=sourcemod|function=OnMapEnd}} - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
* {{SourceMod API|file=sourcemod|function=OnPluginEnd}} - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

==Client Callbacks==
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.

* {{SourceMod API|file=clients|function=OnClientConnect}} - Called when a player initiates a connection. You can block a player from connecting by returning <code>Plugin_Stop</code> and setting rejectmsg to an error message.
* {{SourceMod API|file=clients|function=OnClientConnected}} - Called after a player connects. Signifies that the player is connected and {{SourceMod API|file=clients|function=IsClientConnected}} will return true. '''This is paired with <code>OnClientDisconnect</code> for successful connections only.'''
*{{SourceMod API|file=clients|function=OnClientAuthorized}} - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between <code>OnClientConnected</code> and <code>OnClientPreAdminCheck</code>/<code>OnClientDisconnect</code>. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use <code>OnClientPostAdminCheck</code>.
* {{SourceMod API|file=clients|function=OnClientPutInServer}} - Signifies that the player is fully in-game and {{SourceMod API|file=clients|function=IsClientInGame}} will return true.
** If you want to check if the player is in-game, you just need to call this; {{SourceMod API|file=clients|function=IsClientConnected}} will also be true if this is (but not the other way around - a player may be connected but not in-game yet).
* {{SourceMod API|file=clients|function=OnClientPostAdminCheck}} - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.
* {{SourceMod API|file=clients|function=OnClientDisconnect}} - Called when a player's disconnection starts. '''This is paired to <code>OnClientConnected</code>.'''
* {{SourceMod API|file=clients|function=OnClientDisconnect_Post}} - Called when a player's disconnection ends. '''This is paired to <code>OnClientConnected</code>.'''

=Frequently Asked Questions=
==Are plugins reloaded every mapchange?==
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins.

==Do I need to call CloseHandle in OnPluginEnd?==
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.

==Do I need to #include every individual .inc?==
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.

==Why don't some events fire?==
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.

==Do I need to CloseHandle timers?==
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.

==Are clients disconnected on mapchange?==
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

==Why am I getting "function prototypes do not match" errors?==
When you see this error, you'll most likely find that the issue comes from any callback functions referenced in the line(s) that are causing the error.

When you call a function that takes another function as a callback, the callback function must be declared with the correct number of parameter and return types.

For example, [https://sm.alliedmods.net/new-api/console/RegConsoleCmd <tt>RegConsoleCommand</tt>] must be called with a callback that has with the exact arguments and return type as specified by the [https://sm.alliedmods.net/new-api/console/ConCmd <tt>ConCmd</tt>] definition.

==When do I need to manually unhook things?==
You only need to do so when you do not want the callback to fire anymore while the plugin is running. SourceMod itself, as well as extensions such as SDKHooks, unhooks entities and players when they are removed and disconnected, respectively. Everything a plugin hooks is unhooked when it is unloaded.

== Why am I seeing references to <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>? ==
When {{SourceMod API|file=clients|function=GetClientAuthId}} is called and returns <tt>false</tt>, the buffer that should have the client's auth id is populated with <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>, both to clear the previous contents of the buffer (thereby preventing accidental reuse of old values) and to inform the developer to stop ignoring the return value of the <code>GetClientAuthId</code> call.

== Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? ==
The engine already exists; Metamod:Source works to some extent. Further reverse engineering efforts are required to get Metamod:Source in a stable state before work can even start on SourceMod.

No decision has been made yet on if development will be focused on bringing SourceMod to Source 2, on creating a successor scripting ecosystem much like SourceMod was to [[AMX Mod X]], or on extending VScript functionality.

It's safe to say that SourceMod will currently not work on the day of release for any games powered by Source 2.

Notes as of the initial limited testing phase for Counter-Strike 2:

* <code>-dedicated</code> allows for the creation of listen servers.
* The VSP plugin / VDF loading capabilities have been removed. [[Installing_Metamod:Source#GameInfo|Metamod:Source needs to be loaded as a GameDLL.]]

Keep in mind that this is an ongoing development; nothing is ready for public use yet.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation], as well as [https://wiki.alliedmods.net/Scripting_FAQ_(SourceMod) Yak's FAQs on Scripting].

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2023-03-13T16:54:03Z

Nosoop: /* Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? */ S2 is already released; reword to specifically mention game releases

This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.

For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [https://forums.alliedmods.net/showthread.php?p=2693577 SPCode], [https://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [https://notepad-plus-plus.org/ Notepad++], [https://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio], [https://forums.alliedmods.net/showthread.php?t=289127 BasicPawn] or any other text editor you're comfortable with to write plugins.

=Starting from scratch=
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not know about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This is done using <tt>#include</tt> directive. It tells the compiler to "paste" the code from another file into yours.
<pawn>#include <sourcemod></pawn>
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice, however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if the compiler doesn't know about the existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. The compiler understands that and generates a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].

=Setting up plugin info=
Now that we got access to SourceMod features, it is time to set up the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin is going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:
<sourcepawn>/**
* Plugin public information.
*/
struct Plugin
{
public const char[] name; /**< Plugin Name */
public const char[] description; /**< Plugin Description */
public const char[] author; /**< Plugin Author */
public const char[] version; /**< Plugin Version */
public const char[] url; /**< Plugin URL */
};</sourcepawn>
and this:
<sourcepawn>/**
* Declare this as a struct in your plugin to expose its information.
* Example:
*
* public Plugin myinfo =
* {
* name = "My Plugin",
* //etc
* };
*/
public Plugin myinfo;</sourcepawn>

It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:
<sourcepawn>public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is the preferable way to fill out plugin info.

After that the full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

=Getting code to run=
We already include SourceMod features and filled up or plugin info. We now have a perfectly well-formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason, we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:
<sourcepawn>/**
* Called when the plugin is fully initialized and all known external references
* are resolved. This is only called once in the lifetime of the plugin, and is
* paired with OnPluginEnd().
*
* If any run-time error is thrown during this callback, the plugin will be marked
* as failed.
*
* It is not necessary to close any handles or remove hooks in this function.
* SourceMod guarantees that plugin shutdown automatically and correctly releases
* all resources.
*
* @noreturn
*/
forward void OnPluginStart();</sourcepawn>
Empty parentheses tell us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:
<sourcepawn>public void OnPluginStart()
{
}</sourcepawn>

Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.
<sourcepawn>/**
* Sends a message to the server console.
*
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @noreturn
*/
native int PrintToServer(const char[] format, any ...);</sourcepawn>
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:
<sourcepawn>public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
That's it! The full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};

public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
Compile and load your plugin on your server and see for yourself that the message is displayed in the server console.

=Includes=
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.
*'''Extension''' - adds a dependency against a certain extension.
*'''Plugin''' - adds a dependency against a certain plugin.

Include files are loaded using the <tt>#include</tt> compiler directive.

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [https://sm.alliedmods.net/new-api/console/RegAdminCmd RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

<sourcepawn>
public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action Command_MySlap(int client, int args)
{
}</sourcepawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<sourcepawn>public Action Command_MySlap(int client, int args)
{
return Plugin_Handled;
}</sourcepawn>

Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand ReplyToCommand()].

Full example:

<sourcepawn>
#include <sourcemod>
#include <sdktools>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt"); // Required for FindTarget fail reply
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];

/* By default, we set damage = 0 */
int damage = 0;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, we set damage to
* what the user specified. If a damage isn't specified
* then it will stay zero. */
if (args >= 2)
{
GetCmdArg(2, arg2, sizeof(arg2));
damage = StringToInt(arg2);
}

/* Try and find a matching player */
int target = FindTarget(client, arg1);
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason and returns -1 so we know not
* to continue
*/
return Plugin_Handled;
}

SlapPlayer(target, damage);
ReplyToCommand(client, "[SM] You slapped %N for %d damage!", target, damage);

return Plugin_Handled;
}</sourcepawn>

For more information on what %N and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommended that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>g_cvarMySlapDamage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<sourcepawn>ConVar g_cvarMySlapDamage = null;

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* The rest remains unchanged! */
</sourcepawn>

=Showing Activity, Logging=
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.

For example, let's rewrite the last few lines of our slap command:
<sourcepawn>
SlapPlayer(target, damage);

char name[MAX_NAME_LENGTH];

GetClientName(target, name, sizeof(name));

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);

return Plugin_Handled;
}
</sourcepawn>

=Multiple Targets=
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first.

The function we use is [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString ProcessTargetString()]. It takes in input from the console and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.

This method of target processing is used for almost every admin command in SourceMod, and in fact, FindTarget() is just a simplified version.

Full, final example:
<sourcepawn>
#include <sourcemod>
#include <sdktools>

ConVar g_cvarMySlapDamage = null;

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt");

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2);
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
char target_name[MAX_TARGET_LENGTH];
int target_list[MAXPLAYERS], target_count;
bool tn_is_ml;

if ((target_count = ProcessTargetString(
arg1,
client,
target_list,
MAXPLAYERS,
COMMAND_FILTER_ALIVE, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
ReplyToTargetError(client, target_count);
return Plugin_Handled;
}

for (int i = 0; i < target_count; i++)
{
SlapPlayer(target_list[i], damage);
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);
}

if (tn_is_ml)
{
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);
}
else
{
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);
}

return Plugin_Handled;
}</sourcepawn>

=Events=
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].

It is important to note a few concepts about events:
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.
*They almost always use userids instead of client indexes.
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious for not properly documenting their event functionality.

An example of finding when a player dies:
<sourcepawn>
public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
int victim_id = event.GetInt("userid");
int attacker_id = event.GetInt("attacker");

int victim = GetClientOfUserId(victim_id);
int attacker = GetClientOfUserId(attacker_id);

/* CODE */
}</sourcepawn>

=Callback Orders and Pairing=
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which can confuse users.

==Pairing==
'''Pairing''' is SourceMod terminology. Examples of it are:
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().
*OnClientConnected(N) for a given client N will only be called once until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).

There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.
*Y cannot be invoked with any input A unless X was called first with input A.
*The relationship is described as, "X is paired with Y," and "Y is paired to X."

==General Callbacks==
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.

* {{SourceMod API|file=sourcemod|function=AskPluginLoad2}} - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
* {{SourceMod API|file=sourcemod|function=OnPluginStart}} - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
* {{SourceMod API|file=sourcemod|function=OnAllPluginsLoaded}} - Called once, after all non-late loaded plugins have called OnPluginStart.
* {{SourceMod API|file=sourcemod|function=OnMapStart}} - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
* {{SourceMod API|file=sourcemod|function=OnConfigsExecuted}} - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
* {{SourceMod API|file=sourcemod|function=OnMapEnd}} - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
* {{SourceMod API|file=sourcemod|function=OnPluginEnd}} - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

==Client Callbacks==
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.

* {{SourceMod API|file=clients|function=OnClientConnect}} - Called when a player initiates a connection. You can block a player from connecting by returning <code>Plugin_Stop</code> and setting rejectmsg to an error message.
* {{SourceMod API|file=clients|function=OnClientConnected}} - Called after a player connects. Signifies that the player is connected and {{SourceMod API|file=clients|function=IsClientConnected}} will return true. '''This is paired with <code>OnClientDisconnect</code> for successful connections only.'''
*{{SourceMod API|file=clients|function=OnClientAuthorized}} - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between <code>OnClientConnected</code> and <code>OnClientPreAdminCheck</code>/<code>OnClientDisconnect</code>. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use <code>OnClientPostAdminCheck</code>.
* {{SourceMod API|file=clients|function=OnClientPutInServer}} - Signifies that the player is fully in-game and {{SourceMod API|file=clients|function=IsClientInGame}} will return true.
** If you want to check if the player is in-game, you just need to call this; {{SourceMod API|file=clients|function=IsClientConnected}} will also be true if this is (but not the other way around - a player may be connected but not in-game yet).
* {{SourceMod API|file=clients|function=OnClientPostAdminCheck}} - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.
* {{SourceMod API|file=clients|function=OnClientDisconnect}} - Called when a player's disconnection starts. '''This is paired to <code>OnClientConnected</code>.'''
* {{SourceMod API|file=clients|function=OnClientDisconnect_Post}} - Called when a player's disconnection ends. '''This is paired to <code>OnClientConnected</code>.'''

=Frequently Asked Questions=
==Are plugins reloaded every mapchange?==
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins.

==Do I need to call CloseHandle in OnPluginEnd?==
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.

==Do I need to #include every individual .inc?==
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.

==Why don't some events fire?==
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.

==Do I need to CloseHandle timers?==
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.

==Are clients disconnected on mapchange?==
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

==Why am I getting "function prototypes do not match" errors?==
When you see this error, you'll most likely find that the issue comes from any callback functions referenced in the line(s) that are causing the error.

When you call a function that takes another function as a callback, the callback function must be declared with the correct number of parameter and return types.

For example, [https://sm.alliedmods.net/new-api/console/RegConsoleCmd <tt>RegConsoleCommand</tt>] must be called with a callback that has with the exact arguments and return type as specified by the [https://sm.alliedmods.net/new-api/console/ConCmd <tt>ConCmd</tt>] definition.

==When do I need to manually unhook things?==
You only need to do so when you do not want the callback to fire anymore while the plugin is running. SourceMod itself, as well as extensions such as SDKHooks, unhooks entities and players when they are removed and disconnected, respectively. Everything a plugin hooks is unhooked when it is unloaded.

== Why am I seeing references to <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>? ==
When {{SourceMod API|file=clients|function=GetClientAuthId}} is called and returns <tt>false</tt>, the buffer that should have the client's auth id is populated with <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>, both to clear the previous contents of the buffer (thereby preventing accidental reuse of old values) and to inform the developer to stop ignoring the return value of the <code>GetClientAuthId</code> call.

== Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? ==
The engine already exists; Metamod:Source works to some extent. Further reverse engineering efforts are required to get Metamod:Source in a stable state before work can even start on SourceMod.

No decision has been made yet on if development will be focused on bringing SourceMod to Source 2, on creating a successor scripting ecosystem much like SourceMod was to [[AMX Mod X]], or on extending VScript functionality.

It's safe to say that SourceMod will currently not work on the day of release for any games powered by Source 2.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation], as well as [https://wiki.alliedmods.net/Scripting_FAQ_(SourceMod) Yak's FAQs on Scripting].

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2023-03-13T15:34:32Z

Nosoop: /* Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? */ Bring response up to date; thx duck

This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.

For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [https://forums.alliedmods.net/showthread.php?p=2693577 SPCode], [https://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [https://notepad-plus-plus.org/ Notepad++], [https://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio], [https://forums.alliedmods.net/showthread.php?t=289127 BasicPawn] or any other text editor you're comfortable with to write plugins.

=Starting from scratch=
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not know about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This is done using <tt>#include</tt> directive. It tells the compiler to "paste" the code from another file into yours.
<pawn>#include <sourcemod></pawn>
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice, however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if the compiler doesn't know about the existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. The compiler understands that and generates a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].

=Setting up plugin info=
Now that we got access to SourceMod features, it is time to set up the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin is going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:
<sourcepawn>/**
* Plugin public information.
*/
struct Plugin
{
public const char[] name; /**< Plugin Name */
public const char[] description; /**< Plugin Description */
public const char[] author; /**< Plugin Author */
public const char[] version; /**< Plugin Version */
public const char[] url; /**< Plugin URL */
};</sourcepawn>
and this:
<sourcepawn>/**
* Declare this as a struct in your plugin to expose its information.
* Example:
*
* public Plugin myinfo =
* {
* name = "My Plugin",
* //etc
* };
*/
public Plugin myinfo;</sourcepawn>

It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:
<sourcepawn>public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is the preferable way to fill out plugin info.

After that the full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</sourcepawn>

=Getting code to run=
We already include SourceMod features and filled up or plugin info. We now have a perfectly well-formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason, we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:
<sourcepawn>/**
* Called when the plugin is fully initialized and all known external references
* are resolved. This is only called once in the lifetime of the plugin, and is
* paired with OnPluginEnd().
*
* If any run-time error is thrown during this callback, the plugin will be marked
* as failed.
*
* It is not necessary to close any handles or remove hooks in this function.
* SourceMod guarantees that plugin shutdown automatically and correctly releases
* all resources.
*
* @noreturn
*/
forward void OnPluginStart();</sourcepawn>
Empty parentheses tell us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:
<sourcepawn>public void OnPluginStart()
{
}</sourcepawn>

Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.
<sourcepawn>/**
* Sends a message to the server console.
*
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @noreturn
*/
native int PrintToServer(const char[] format, any ...);</sourcepawn>
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:
<sourcepawn>public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
That's it! The full code of your plugin should look like this:
<sourcepawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};

public void OnPluginStart()
{
PrintToServer("Hello world!");
}</sourcepawn>
Compile and load your plugin on your server and see for yourself that the message is displayed in the server console.

=Includes=
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.
*'''Extension''' - adds a dependency against a certain extension.
*'''Plugin''' - adds a dependency against a certain plugin.

Include files are loaded using the <tt>#include</tt> compiler directive.

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [https://sm.alliedmods.net/new-api/console/RegAdminCmd RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

<sourcepawn>
public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action Command_MySlap(int client, int args)
{
}</sourcepawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<sourcepawn>public Action Command_MySlap(int client, int args)
{
return Plugin_Handled;
}</sourcepawn>

Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand ReplyToCommand()].

Full example:

<sourcepawn>
#include <sourcemod>
#include <sdktools>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt"); // Required for FindTarget fail reply
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];

/* By default, we set damage = 0 */
int damage = 0;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, we set damage to
* what the user specified. If a damage isn't specified
* then it will stay zero. */
if (args >= 2)
{
GetCmdArg(2, arg2, sizeof(arg2));
damage = StringToInt(arg2);
}

/* Try and find a matching player */
int target = FindTarget(client, arg1);
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason and returns -1 so we know not
* to continue
*/
return Plugin_Handled;
}

SlapPlayer(target, damage);
ReplyToCommand(client, "[SM] You slapped %N for %d damage!", target, damage);

return Plugin_Handled;
}</sourcepawn>

For more information on what %N and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommended that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>g_cvarMySlapDamage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<sourcepawn>ConVar g_cvarMySlapDamage = null;

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* The rest remains unchanged! */
</sourcepawn>

=Showing Activity, Logging=
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.

For example, let's rewrite the last few lines of our slap command:
<sourcepawn>
SlapPlayer(target, damage);

char name[MAX_NAME_LENGTH];

GetClientName(target, name, sizeof(name));

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);

return Plugin_Handled;
}
</sourcepawn>

=Multiple Targets=
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first.

The function we use is [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString ProcessTargetString()]. It takes in input from the console and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.

This method of target processing is used for almost every admin command in SourceMod, and in fact, FindTarget() is just a simplified version.

Full, final example:
<sourcepawn>
#include <sourcemod>
#include <sdktools>

ConVar g_cvarMySlapDamage = null;

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
LoadTranslations("common.phrases.txt");

g_cvarMySlapDamage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int damage = g_cvarMySlapDamage.IntValue;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2);
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
char target_name[MAX_TARGET_LENGTH];
int target_list[MAXPLAYERS], target_count;
bool tn_is_ml;

if ((target_count = ProcessTargetString(
arg1,
client,
target_list,
MAXPLAYERS,
COMMAND_FILTER_ALIVE, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
ReplyToTargetError(client, target_count);
return Plugin_Handled;
}

for (int i = 0; i < target_count; i++)
{
SlapPlayer(target_list[i], damage);
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);
}

if (tn_is_ml)
{
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);
}
else
{
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);
}

return Plugin_Handled;
}</sourcepawn>

=Events=
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].

It is important to note a few concepts about events:
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.
*They almost always use userids instead of client indexes.
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious for not properly documenting their event functionality.

An example of finding when a player dies:
<sourcepawn>
public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
int victim_id = event.GetInt("userid");
int attacker_id = event.GetInt("attacker");

int victim = GetClientOfUserId(victim_id);
int attacker = GetClientOfUserId(attacker_id);

/* CODE */
}</sourcepawn>

=Callback Orders and Pairing=
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which can confuse users.

==Pairing==
'''Pairing''' is SourceMod terminology. Examples of it are:
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().
*OnClientConnected(N) for a given client N will only be called once until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).

There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.
*Y cannot be invoked with any input A unless X was called first with input A.
*The relationship is described as, "X is paired with Y," and "Y is paired to X."

==General Callbacks==
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.

* {{SourceMod API|file=sourcemod|function=AskPluginLoad2}} - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
* {{SourceMod API|file=sourcemod|function=OnPluginStart}} - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
* {{SourceMod API|file=sourcemod|function=OnAllPluginsLoaded}} - Called once, after all non-late loaded plugins have called OnPluginStart.
* {{SourceMod API|file=sourcemod|function=OnMapStart}} - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
* {{SourceMod API|file=sourcemod|function=OnConfigsExecuted}} - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
* {{SourceMod API|file=sourcemod|function=OnMapEnd}} - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
* {{SourceMod API|file=sourcemod|function=OnPluginEnd}} - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

==Client Callbacks==
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.

* {{SourceMod API|file=clients|function=OnClientConnect}} - Called when a player initiates a connection. You can block a player from connecting by returning <code>Plugin_Stop</code> and setting rejectmsg to an error message.
* {{SourceMod API|file=clients|function=OnClientConnected}} - Called after a player connects. Signifies that the player is connected and {{SourceMod API|file=clients|function=IsClientConnected}} will return true. '''This is paired with <code>OnClientDisconnect</code> for successful connections only.'''
*{{SourceMod API|file=clients|function=OnClientAuthorized}} - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between <code>OnClientConnected</code> and <code>OnClientPreAdminCheck</code>/<code>OnClientDisconnect</code>. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use <code>OnClientPostAdminCheck</code>.
* {{SourceMod API|file=clients|function=OnClientPutInServer}} - Signifies that the player is fully in-game and {{SourceMod API|file=clients|function=IsClientInGame}} will return true.
** If you want to check if the player is in-game, you just need to call this; {{SourceMod API|file=clients|function=IsClientConnected}} will also be true if this is (but not the other way around - a player may be connected but not in-game yet).
* {{SourceMod API|file=clients|function=OnClientPostAdminCheck}} - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.
* {{SourceMod API|file=clients|function=OnClientDisconnect}} - Called when a player's disconnection starts. '''This is paired to <code>OnClientConnected</code>.'''
* {{SourceMod API|file=clients|function=OnClientDisconnect_Post}} - Called when a player's disconnection ends. '''This is paired to <code>OnClientConnected</code>.'''

=Frequently Asked Questions=
==Are plugins reloaded every mapchange?==
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins.

==Do I need to call CloseHandle in OnPluginEnd?==
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.

==Do I need to #include every individual .inc?==
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.

==Why don't some events fire?==
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.

==Do I need to CloseHandle timers?==
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.

==Are clients disconnected on mapchange?==
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

==Why am I getting "function prototypes do not match" errors?==
When you see this error, you'll most likely find that the issue comes from any callback functions referenced in the line(s) that are causing the error.

When you call a function that takes another function as a callback, the callback function must be declared with the correct number of parameter and return types.

For example, [https://sm.alliedmods.net/new-api/console/RegConsoleCmd <tt>RegConsoleCommand</tt>] must be called with a callback that has with the exact arguments and return type as specified by the [https://sm.alliedmods.net/new-api/console/ConCmd <tt>ConCmd</tt>] definition.

==When do I need to manually unhook things?==
You only need to do so when you do not want the callback to fire anymore while the plugin is running. SourceMod itself, as well as extensions such as SDKHooks, unhooks entities and players when they are removed and disconnected, respectively. Everything a plugin hooks is unhooked when it is unloaded.

== Why am I seeing references to <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>? ==
When {{SourceMod API|file=clients|function=GetClientAuthId}} is called and returns <tt>false</tt>, the buffer that should have the client's auth id is populated with <tt>STEAM_ID_STOP_IGNORING_RETVALS</tt>, both to clear the previous contents of the buffer (thereby preventing accidental reuse of old values) and to inform the developer to stop ignoring the return value of the <code>GetClientAuthId</code> call.

== Will SourceMod support Source 2? Will plugins for existing games continue to work if they are ported? ==
The engine already exists; Metamod:Source works to some extent. Further reverse engineering efforts are required to get Metamod:Source in a stable state before work can even start on SourceMod.

No decision has been made yet on if development will be focused on bringing SourceMod to Source 2, on creating a successor scripting ecosystem much like SourceMod was to [[AMX Mod X]], or on extending VScript functionality.

It's likely safe to say that SourceMod will not work on day 1 of the release of Source 2.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation], as well as [https://wiki.alliedmods.net/Scripting_FAQ_(SourceMod) Yak's FAQs on Scripting].

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

User:Nosoop/Guide/How to X

2023-03-04T16:53:27Z

Nosoop: /* Proper Unicode handling in MySQL */ Add note on converting existing data

This is a page on how to do things that are common in plugins.
These are intended to be best practices.

= Determine if a client has access to something =

Use the admin overrides system with the {{SourceMod API|file=console|function=CheckCommandAccess}} function.
For example, if you want to determine if a client has access to the <code>sm_ban</code> command:

<pre class="sourcepawn">
if (CheckCommandAccess(client, "sm_ban", ADMFLAG_BAN)) {
// client has access to the "sm_ban" command
}
</pre>

The <code>command</code> parameter can be an arbitrary string; it does not have to point to a valid command:

<pre class="sourcepawn">
if (CheckCommandAccess(client, "has_fancy_color_trails", ADMFLAG_CUSTOM1, true)) {
// client has access to the "has_fancy_color_trails" override;
// if an override entry isn't set it falls back to ADMFLAG_CUSTOM1.
// ignores the privileges set on a command of that name if it exists
}
</pre>

Under no circumstance should you leave the <code>command</code> parameter blank; even if you want to check access based on existing admin flags, you should provide a unique "command" string to allow server operators to override access themselves.

To assign access levels for specific strings, modify <tt>configs/admin_overrides.cfg</tt>.

For more detailed information, see [[Overriding_Command_Access_(SourceMod)|this page on overriding command access]].

= Declare methodmap natives =

Methodmap natives are the same as any other native, except that the <code>this</code> value is passed in as the first parameter, and any additional parameters follow it.

= Pass enum structs through natives =

In short, you don't. Enum structs do not (at the time of writing) have a standardized in-memory representation, so they should not be passed across plugin boundaries. There's also no way to guarantee that two plugins were compiled with the same definition, let alone implementation (though checking the offset / sizes of each member would lower the risk).

The safest approach is to serialize / deserialize the data through a standard container ({{SourceMod API|file=adt_trie|function=StringMap}}, {{SourceMod API|file=datapack|function=DataPack}}). That is then exposed to other plugins as an [https://en.wikipedia.org/wiki/Opaque_pointer opaque handle] (the methodmap definition would inherit from <tt>Handle</tt>, and read / write operations are handled indirectly through natives registered by the originating plugin).

= Add linebreaks in CS:GO chat messages =

CS:GO uses the newline character <code>\n</code> as a text color. Use the paragraph separator character instead: <code>\xE2\x80\xA9</code>

= Proper Unicode handling in MySQL =

MySQL defaults to using the <tt>latin1</tt> character encoding, which isn't good if you need to store non-ASCII text.

* Ensure columns are created with the <tt>utf8mb4</tt> collation, ''not'' <tt>utf8</tt> (which aliases to <tt>utf8mb3</tt>).
* After connecting to the database, call {{SourceMod API|file=dbi|class=Database|function=SetCharset}} with <tt>utf8</tt>.

If you have previous entries that were encoded as <tt>latin1</tt>, refer to [https://stackoverflow.com/a/9407998 this StackOverflow answer] to convert it. Do note that the outermost <code>convert</code> operation should use <tt>utf8mb4</tt> instead.