[Thrawn2]

In the hopes of reducing some noise in most plugins threads, i've started writing this little guide. It is directed at sourcemod beginners and explains the basic about managing your sourcemod installation.

1. Getting Familiar
1.1 Server console
1.2 Directory Layout
1.3 Adding yourself as an admin
1.4 Try to disable/enable a plugin

2. Installing Plugins
2.1 The basics
2.2 Dependencies
2.3 How to test if your plugin is installed correctly?
2.4 Helping the developer

3. Extensions
3.1 The basics
3.2 Installing an extension
3.3 Troubleshooting extension issues

[Thrawn2]

1.1 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 refresh
• sm plugins unload funvotes
• sm plugins load funvotes
• sm exts list

[Thrawn2]

1.2 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)).

• /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.

[Thrawn2]

1.3 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.

[Thrawn2]

1.4 Try to disable and 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 chapter 2.3 How to test if your plugin is installed correctly?

[Thrawn2]

2.1 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.

[Thrawn2]

2.2 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.

[Thrawn2]

2.3 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:

• 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.

[Thrawn2]

2.4 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 thread. 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 give them as much information as you can.

[Thrawn2]

3.1 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 SDK Hooks), some extensions influence the game directly (like UnlockBlock).