Managing your Sourcemod installation

Getting Familiar

Server console

You've just installed sourcemod and made sure that it's working. For that you did the instructions in the Checking the Install chapter and issued some first commands in the server console.

Get more familiar with the console, either directly or preferably via rcon (e.g. by using HLSW).

Try at least these commands:

• sm
• sm version
• sm plugins
• sm plugins list
• sm plugins reload 1
• sm plugins refresh
• sm plugins unload funvotes
• sm plugins load funvotes
• sm exts list

Directory Layout

Also get to know the directory layout sourcemod is using, this means:

1. look and see what folders are there
2. what files are in them
3. and what's in those files (open them with notepad (better: notepad++ or some other custom text editor)).

Directory	Description
/bin	ignore this folder, it has the actual sourcemod binaries in it
/configs	This is the default place where sourcemod and its plugins put their configuration files. Look at every file in this folder at least once, try to understand them.
/data	ignore this folder for now
/extensions	This is the directory where extensions must be installed. You might notice that many extensions exist multiple times, this is due to the fact that the different game engines each need their own extension based on their SDK. Lets take a look at the bintools extension for example: bintools.ext.dll This is for the original source engine bintools.ext.1.ep1.dll "Old Metamod" (Insurgency, Eternal Silence and other EP1 mods) bintools.ext.2.darkm.dll This is for Dark Messiah. bintools.ext.2.ep2.dll This is for the "OrangeBox"-Engine used by mods, e.g. ZPS, AOC, PVKII etc bintools.ext.2.ep2v.dll This is for the "OrangeBoxValve"-Engine e.g. CSS,TF2,DODS,HL2DM,GMOD. bintools.ext.2.l4d.dll This is for L4D bintools.ext.2.l4d2.dll This is for L4D2 bintools.ext.2.swarm.dll This is for Alien Swarm
/gamedata	If an extension or a plugin is using functionality provided by the game engine, e.g. Respawn a player or equipping a player with a weapon, sourcemod needs to know a few "facts" (to be precise: offsets and signatures) about the function. These can change after valve releases an update. At this point you don't need to know more about this, because sourcemod has an integrated updater, which automatically fetches the new gamedata files for you.
/logs	The holy grail of debugging your actions. Everything will be logged here. If someone asks you what the logfiles are saying or whether you get any errors: reproduce your problem, then take a look at the logfiles and just copy&paste the messages. Don't try to be smart here and post what you think the given errors are saying, just post the lines. Or fix the problem yourself if you understand the error.
/plugins	All plugins (.smx files) in this directory will be loaded automatically when sourcemod starts. Plugins will also be reloaded on mapchange if their file has changed.
/plugins/disabled	Plugins in this sub-folder won't be loaded. Move plugins from the parent directory to this one to disable a plugin and vice-a-versa. You will find some official alliedmods plugins in this directory you might want to install (e.g. rockthevote) and some others you want to disable by moving them here (e.g. funvotes).
/scripting	You can find the sourcecode to plugins in this directory, at least the original alliedmods ones. You don't need to place any files here to install a plugin, but it is highly recommended to not only install the smx files, but also their corresponding sp file.
/translations	Not much to say about this folder, it contains translations for many languages. Plugins are encouraged to provide translation files, so you might need to copy some files in here when installing a plugin.

Adding yourself as an admin

To make things easier from now on, you should add yourself as an root-admin. There are several ways to manage access rights on your server. In this step we do it quick and dirty, but you might want to read the chapter about Adding Admins and Adding Groups, then create a group for system administrators and add yourself to it.

We are using the simple approach and just add one line to the admins_simple.cfg file in your sourcemod/configs/ directory:

"yoursteamid" "99:z"

Then enter sm_reloadadmins in the server console, you should get this as a response: [SM] Admin cache has been refreshed.

Try to disable/enable a plugin

If you've read the subsection about the directory layout you should already know how to do this.

And if you read the subsection about the server console you also know how to test if it worked.

But lets explain this again. We want to enable the mapchooser plugin:

1. Copy plugins/disabled/mapchooser.smx to plugins/mapchooser.smx
2. You can make this change active by either loading the plugin with sm plugins load mapchooser
   or by changing the map.
3. Lets take a look at the plugin list and see if it is being listed. Type sm plugins list.

If not, read the chapter about testing sourcemod plugin installations?

Installing Plugins

The basics

For simple plugins that come only with the source and a binary like Basic AFK Manager installation is pretty straight forward and is basically the same as enabling one of the official plugins (see section 1.4). You copy the .smx to the plugins folder and the .sp to the scripting folder.

For more complex plugins like SM Bot Tools it might also be required to copy translations or gamedata to the corresponding folders, but the smart developer gives you a zip with the correct folder layout anyway, so you just need to copy everything to the sourcemod folder.

Always follow instructions on the plugins page.

Dependencies

Rarely plugins have dependencies on other plugins, but it's quite common for a plugin to require one or more extensions. Extensions usually provide features that enable plugins to do stuff they couldnt otherwise. If a plugin has any dependencies it has to be noted somewhere in the plugin description. Look for it.

Learn in chapter 3 how to install an extension.

How to test if your plugin is installed correctly

When you are troubleshooting plugin and/or extension issues always use the server console. Forget the client console. SourceMod is a server-side addon after all.

Just change the map after the installation and type sm plugins list in the server console. You should see the changes you've made. If the plugin you've installed is not listed, then it is not installed correctly (aka its not the plugins fault, but yours) and you need to figure out what you did wrong. Basically it has to be this: you didn't put the compiled plugin (the .smx file) in the /plugins directory of your sourcemod installation.

If it is listed but prefixed with a <Failed>, something else went wrong. To get details what exactly was the problem type sm plugins info <plugin id>, replace <plugin id> with the number of the plugin you've got in the list. It will probably say something like this:

Error	Description
Could not find translation file	You've forgot to put the translation files on the server or placed them in the wrong directory. Check the plugins thread again, check the provided zip again. If it is really missing from either of those, report it, otherwise: place them in the correct directory.
Native 'xyz' was not found or Required extension "xyz" file("xyz.ext") not running.	You've installed an old version of an extension or did not install a required extension in the first place. Check the installed version (by typing sm exts list) against the version on alliedmods and update if possible.
Wrong game	The plugin you are trying to use is not made for your game, but for another (e.g. [TF2] tHeadshotOnly is obviously only working on TF2). Disable the plugin to get rid of the error message.

Helping the developer

Ok, so you've tried everything to get a plugin to work, but it still won't load. This is pretty unusual. The plugin developer will think you did something wrong installing it and link you to this page. Prevent this from happening. Give them proof that you've reached a point where it is out of your hand to fix the problem. Tell them what you've tried, give them the console log (via screenshot if you can't copy+paste) and provide them with as much information as you can.

Installing Extensions

The basics

Extensions are like plugins, just more powerful. They load if required by a plugin and stay dormant if not. This means extensions that are not required by any of your plugins won't even load - you won't see them when typing sm exts list.

Some extensions provide features for other plugins to use (like SDKHooks), some extensions influence the game directly (like UnlockBlock).

Extension versions and filenames

Some extensions will have just one version for all Source games. These will have filenames like bintools.ext.dll for Windows, bintools.ext.so for Linux, or bintools.ext.dylib for OSX.

Other extensions will have multiple versions depending on the game engine being used. These filenames are generally named like this: [extension name].ext.[MetaMod: Source API version].[Game engine string].[extension].

For example, SDKTools has the following files in the Windows SourceMod release

Games	filename
Alien Swarm	sdktools.ext.2.swarm.dll
Bloody Good Time	sdktools.ext.2.bgt.dll
Dark Messiah	sdktools.ext.2.darkm.dll
Episode 1 / Generic non-OB mods	sdktools.ext.1.ep1.dll
Episode 2 / Orange Box / Source 2007 / Generic OB mods	sdktools.ext.2.ep2.dll
E.Y.E: Divine Cybermancy	sdktools.ext.2.eye.dll
Left 4 Dead	sdktools.ext.2.l4d.dll
Left 4 Dead 2	sdktools.ext.2.l4d2.dll
Source 2009 / Half-Life 2: DeathMatch / Day of Defeat: Source / Counter-Strike: Source / Team Fortress 2	sdktools.ext.2.ep2v.dll

Installing an extension

This is pretty much the same as installing plugins, so it does not seem necessary to list the required steps, but i will do it anyway. To install an extension you just copy it to the /extensions directory. Extensions can require gamedata and translations like plugins, so don't forget to install them too.

To actually load the extension just change the map or type sm exts load <name of your extension> in the server console. Remember that extensions wont load automatically if they are not required in the first place.

To force an extension to always load, just create an empty file with the name of the extension itself and the file-extension .autoload.

• Example:
  • extension file name is extensions/sdkhooks.ext.2.ep2v.dll
  • to autoload this extension create an empty file extensions/sdkhooks.autoload

Note: You can't update a running extension, you need to disable it first via sm unload <extensionname> or stop your server. Otherwise your server will most likely crash if you're on linux and block you from doing so on windows.

Troubleshooting extension issues

Again, this is pretty much the same procedure that you've learned already.

How to test if it is loaded or failed while loading? sm exts list How to load an extension at runtime? sm exts load <extension name>

Both should give you an output why it failed. Those can be the same reasons as in chapter How to test if your plugin is installed correctly, so make sure to read that if you haven't done already. At the very least they should give you an indication on how to proceed.