View source for Managing your Sourcemod installation

{{Languages|Managing your Sourcemod installation}}
== Getting Familiar ==
=== Server console ===
You've just [[Installing_SourceMod|installed sourcemod]] and made sure that it's working. For that you did the instructions in the [[Installing_SourceMod#Checking_the_Install|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 [http://www.hlsw.org/ 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:
# look and see what folders are there
# what files are in them
# and what's in those files <span style="font-size:80%">(open them with notepad (better: notepad++ or some other custom text editor)).</span>

{| style="width:600px;" cellpadding="5"
 !Directory
 !Description
 |- class="t2td"
 | '''/bin'''
 | ignore this folder, it has the actual sourcemod binaries in it
 |- class="t2td"
 | '''/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.
 |- class="t2td"
 | '''/data'''
 | ignore this folder for now
 |- class="t2td"
 | '''/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:
{| style="width:450px;" cellpadding="5"
 |- class="t1td"
 | '''bintools.ext.dll'''
 | This is for the original source engine
 |- class="t1td"
 | '''bintools.ext.1.ep1.dll'''
 | "Old Metamod" (Insurgency, Eternal Silence and other EP1 mods)
 |- class="t1td"
 | '''bintools.ext.2.darkm.dll'''
 | This is for Dark Messiah.
 |- class="t1td"
 | '''bintools.ext.2.ep2.dll'''
 | This is for the "OrangeBox"-Engine used by mods, e.g. ZPS, AOC, PVKII etc
 |- class="t1td"
 | '''bintools.ext.2.ep2v.dll'''
 | This is for the "OrangeBoxValve"-Engine e.g. CSS,TF2,DODS,HL2DM,GMOD.
 |- class="t1td"
 | '''bintools.ext.2.l4d.dll'''
 | This is for L4D
 |- class="t1td"
 | '''bintools.ext.2.l4d2.dll'''
 | This is for L4D2
 |- class="t1td"
 | '''bintools.ext.2.swarm.dll'''
 | This is for Alien Swarm
|}
 |- class="t2td"
 | '''/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.
 |- class="t2td"
 | '''/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.
 |- class="t2td"
 | '''/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.
 |- class="t2td"
 | '''/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).
 |- class="t2td"
 | '''/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.
 |- class="t2td"
 | '''/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_(SourceMod)|Adding Admins]] and [[Adding_Groups_(SourceMod)|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 <tt>admins_simple.cfg</tt> file in your <tt>sourcemod/configs/</tt> directory:
<pre>"yoursteamid" "99:z"</pre>
Then enter '''sm_reloadadmins''' in the server console, you should get this as a response: <tt>[SM] Admin cache has been refreshed.</tt>


=== 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:
# Copy <tt>plugins/disabled/mapchooser.smx</tt> to <tt>plugins/mapchooser.smx</tt>
# You can make this change active by either loading the plugin with <tt>sm plugins load mapchooser</tt><br>or by changing the map.
# Lets take a look at the plugin list and see if it is being listed. Type <tt>sm plugins list</tt>.

If not, read the chapter [[#How to test if your plugin is installed correctly|about testing sourcemod plugin installations]]?



== Installing Plugins ==
=== The basics ===
For simple plugins that come only with the source and a binary like [http://forums.alliedmods.net/showthread.php?t=74531 Basic AFK Manager] installation is pretty straight forward and is basically the same as enabling one of the official plugins (see section [[#Try to disable/enable a plugin|1.4]]). You copy the <tt>.smx</tt> to the <tt>plugins</tt> folder and the <tt>.sp</tt> to the <tt>scripting</tt> folder.

For more complex plugins like [http://forums.alliedmods.net/showthread.php?t=59147 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 [[#Installing an extension|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 <tt>sm plugins list</tt> 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 <tt>.smx</tt> file) in the <tt>/plugins</tt> directory of your sourcemod installation.

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

{| style="width:600px;" cellpadding="5"
! scope="col" width="80" | 
! scope="col" width="180" |
 |- class="t2th"
 |Error || Description
 |- class="t2td"
 | '''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.
 |- class="t2td"
 | '''Native 'xyz' was not found'''<br>or<br>'''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.
 |- class="t2td"
 | '''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 <tt>sm exts list</tt>.

Some extensions provide features for other plugins to use (like [http://forums.alliedmods.net/showthread.php?t=106748 SDKHooks]), some extensions influence the game directly (like [http://forums.alliedmods.net/showthread.php?t=145218 UnlockBlock]).

=== Extension versions and filenames ===
Some extensions will have just one version for all Source games.  These will have filenames like <tt>bintools.ext.dll</tt> for Windows, <tt>bintools.ext.so</tt> for Linux, or <tt>bintools.ext.dylib</tt> for OSX.

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

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

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

=== 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 <tt>/extensions</tt> 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 <tt>sm exts load <name of your extension></tt> 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 <tt>.autoload</tt>.
* Example:
** extension file name is <tt>extensions/sdkhooks.ext.2.ep2v.dll</tt>
** to autoload this extension create an empty file <tt>extensions/sdkhooks.autoload</tt>

'''Note:''' You can't update a running extension, you need to disable it first via <tt>sm unload <extensionname></tt> 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|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.


[[Category:SourceMod Documentation]]