Left 4 Dead 2 addons and SourceMod

A Left 4 Dead 2 dedicated server loads addons from .vpk files in left4dead2/addons/, and every player needs the same campaign VPK installed or they cannot play it - the server cannot send a campaign to a client. Server-side features are a different stack: Metamod:Source, SourceMod on top, and for nearly every modern L4D2 plugin the left4dhooks extension underneath. More than four survivors needs L4DToolZ to lift the engine's player cap plus a multi-slot plugin to spawn and equip the extra survivors. Each of those layers is reliable on its own. What goes wrong is the interaction: two addons shipping the same script file, a plugin built for an older left4dhooks, a game update that breaks gamedata. This guide covers the addon system, the plugin stack, the more-players setup and the conflicts you will meet.

Addons, plugins and what lives where#

L4D2 mixes two completely different kinds of "mod", and confusing them is the root of most setup problems.

The VPK addons and the SourceMod stack both live under left4dead2/addons/, which looks messy but works: the engine mounts the .vpk files and ignores folders it does not understand, and Metamod finds its own metamod.vdf file in the same place.

If the base server is not set up yet - the install, server.cfg, the lobby and sv_search_key - start with the Left 4 Dead 2 server guide, which this post builds on.

Installing VPK addons and custom campaigns#

A campaign is one or more .vpk files containing maps, a mission file, and often custom models, sounds and scripts. Installing one on the server is a file copy:

1. Stop the server.
2. Upload the .vpk files to left4dead2/addons/ with the file manager or SFTP. SFTP and the file manager has the details.
3. Start the server and check the console for the addon mounting without errors.
4. Find the campaign's first map name - it is in the mission file inside the VPK, or in the author's notes - and test it with changelevel <map>.

For Workshop campaigns, SteamCMD fetches the item against the game's app id:

$ steamcmd +force_install_dir /home/l4d2/server +login anonymous \    +workshop_download_item 550 <workshop_id> +quit

The download lands under SteamCMD's own steamapps/workshop/content/550/<workshop_id>/ folder rather than in the game's addons folder, so copy the .vpk across and give it a sensible name. Steam Workshop mods on dedicated servers explains how that cache works in general.

Players must have the identical campaign. They subscribe to the same Workshop item - or install the same VPK by hand - and restart the game so it mounts. If the server and a player have different versions, the player is kicked or crashes on the map load. Post the collection link where your group talks and say which version the server runs.

Mutations and custom game modes

Mutation addons define a game mode in a modes/<name>.txt file inside the VPK, usually with VScripts that change the Director. Once the addon is mounted, the mode is selected with mp_gamemode:

mp_gamemode coop// or a stock mutation or an addon mode by its name// mp_gamemode realism// mp_gamemode versus

The stock values include coop, realism, versus, survival and scavenge, plus Valve's numbered mutations. An addon mode uses whatever name its modes/ file declares - check the addon's description. Setting a mode the server does not know falls back to co-op silently, which looks like "the mutation does nothing".

Addon conflicts and the director script problem#

L4D2 addons do not fail loudly when they conflict. They overwrite each other, and the last one mounted wins. Two kinds of conflict cause almost everything:

• The same script file. Many addons change the AI Director by shipping scripts/vscripts/director_base_addon.nut. Only one copy can win, so two addons that both ship it mean one of them is silently disabled. The symptom is "this addon stopped working when I installed that one".
• The same model or sound path. Two weapon reskins for the same gun, two survivor model replacements. One wins, and which one depends on load order.

The routine that finds the culprit:

1. Move everything out of addons/ except the campaign you are testing and the SourceMod stack.
2. Add the remaining VPKs back two or three at a time, testing each time.
3. When something breaks, open the newest pair with a VPK tool and look for overlapping file paths.

A server-only addon that changes the Director is better replaced by a SourceMod plugin that does the same thing through left4dhooks, because plugins can coexist and VScript files with the same name cannot.

sv_consistency 1 makes file mismatches announce themselves as a kick with a file name rather than a crash, and sv_pure controls whether players may use custom versions of game files. L4D2's pure settings are looser than newer Source games, and many community servers leave sv_pure 0 so players can keep cosmetic mods. Competitive servers usually enforce consistency to stop model swaps that make infected easier to see.

Installing Metamod:Source and SourceMod#

SourceMod is how an L4D2 server gets admins, votes, stats, extra slots and every competitive config. The order is fixed: Metamod:Source first, then SourceMod, then extensions, then plugins.

left4dead2/addons/  metamod.vdf                  tells the engine to load Metamod  metamod/  sourcemod/    configs/admins_simple.ini  admins    extensions/                left4dhooks and friends    gamedata/                  offsets that break on updates    plugins/                   .smx files    logs/                      errors live here  campaign_one.vpk             addons share the folder

Download the Metamod:Source and SourceMod builds for Linux from their official sites - the stable branch unless a plugin requires dev - and extract both into left4dead2/. Restart, then check from the server console:

meta listsm versionsm plugins listsm exts list

meta list showing SourceMod and sm exts list showing no failed extensions is a working stack. Admins go in addons/sourcemod/configs/admins_simple.ini; the flag model is covered in SourceMod admin flags and immunity, and the same file and flags are used on every Source game.

"STEAM_1:1:12345678"  "99:z""STEAM_1:0:87654321"  "bcdefjk"

left4dhooks: the extension everything needs

Almost every modern L4D2 plugin depends on left4dhooks, an extension and plugin pair that exposes the game's internals - the Director, tank and witch spawns, survivor state, infected behaviour - to SourceMod. It replaced the older Left 4 Downtown extensions. Install it from its official thread or repository, with its gamedata files, and keep it updated: when an L4D2 update moves something, left4dhooks gamedata is usually fixed first and everything built on it recovers.

Check a plugin's requirements before installing it. A plugin written for left4dhooks will not load without it, and the error in addons/sourcemod/logs/ names the missing native.

Plugins worth running on a co-op server

A private co-op server for a group of friends needs very little. SourceMod's own bundled plugins already cover most of it: basecommands and adminmenu for kicks, map changes and cvars from the sm_admin menu, basevotes for vote kicks when no admin is around, and nominations with rockthevote if your group likes to vote on the next campaign. Those ship with SourceMod and only need to be left enabled.

On top of that, the additions people actually use fall into a few groups:

• Campaign rotation. Plugins that move the server to the next campaign after a finale and let players vote on which one, so the server does not sit on a finished map waiting for an admin.
• Admin spawn tools. Menus that let an admin spawn a tank, a witch or a horde, which turns a quiet evening into a story. All4Dead is the long-standing example.
• Quality of life. Ready-up before the saferoom door opens, AFK handling, kick-on-idle for the player who alt-tabbed, and a message when a player joins mid-campaign.
• Stats. Kills, revives and friendly fire per player. Fun, and occasionally useful when one person keeps blaming the bots.

Add them one at a time and play a chapter after each. A co-op server with forty plugins is a server where nobody can tell which one made the witch spawn inside the saferoom. Keep a short text file next to the server listing what is installed and why; the person who has to fix it after an update will probably be you, six months from now, having forgotten.

More than four survivors#

The four-survivor limit is compiled into the game. Lifting it takes two separate pieces:

1. L4DToolZ, a Metamod plugin, unlocks the server's player limit and adds the cvars that control it - sv_maxplayers, sv_removehumanlimit and friends, covered in the server guide.
2. A multi-slot plugin, such as SuperVersus or one of the MultiSlots variants, which spawns extra survivor bots for new players to take over, gives them starting kits, and adjusts team sizes. Without it, extra players join as spectators with nothing to control.

sv_maxplayers 8sv_visiblemaxplayers 8sv_removehumanlimit 1sv_force_unreserved 1

The cvar names for the multi-slot plugin itself differ between plugins, and some also change survivor_limit and, for versus, z_max_player_zombies. Use the plugin's own config file rather than copying cvars from a forum post for a different plugin.

Expect side effects. The game has four survivor characters, so the extra survivors reuse their models and voice lines. Some campaigns' finales and scripted events assume four, and occasionally a rescue vehicle leaves without the fifth to eighth survivors. Balance plugins that scale common and special infected to the survivor count exist, and without one an eight-survivor game on Expert is easier than a four-survivor one on Advanced. Each extra survivor also costs CPU: bot pathing, more infected spawned by scaling plugins, more physics.

Competitive configs and tick rate#

Competitive versus communities run config packs - the Confogl lineage and its successors, such as ZoneMod in the L4D2 Competitive Rework project - which bundle dozens of plugins, ready-up, pause handling and balance changes. They are large, opinionated and well maintained. Install one as a whole from its repository rather than assembling the parts, and expect it to replace your server.cfg habits with its own config system.

L4D2 servers run at 30 tick by default. Competitive configs usually raise it with a tickrate enabler extension and the -tickrate launch argument, which also needs the rate cvars raised to match - sv_maxupdaterate, sv_maxcmdrate, sv_minrate and sv_maxrate - or the higher tick rate changes nothing for the players. A 100 tick server costs roughly three times the CPU of a 30 tick one. For a co-op group of friends it is rarely worth it; what tick rate actually means explains why.

Updates and keeping it working#

L4D2 updates are rare now, which is good news, but each one can break gamedata for SourceMod, left4dhooks and L4DToolZ at once. The defensive routine:

• Backup before updating. The whole addons folder and your cfg files. Keeping a known-good copy in a backup slot means a broken update costs a restore, not an evening.
• Update in order. Metamod, SourceMod, left4dhooks, then plugins.
• Watch the logs. addons/sourcemod/logs/errors_<date>.log names every plugin that failed and why.
• Keep a vanilla fallback. A copy of server.cfg that runs plain co-op with no plugins gets your group playing while the stack catches up.

What to do when a mod update breaks covers the general version of this routine.

Troubleshooting#

Players crash or get kicked loading a custom campaign. They do not have it, or have a different version. Have them unsubscribe and resubscribe, restart Steam, and check the version against the server's file.

A mutation does nothing. mp_gamemode does not match the mode name in the addon, or another addon's director_base_addon.nut is overriding it.

SourceMod plugins fail with "native not found". left4dhooks is missing or older than the plugin expects. Update it with its gamedata.

More than four players can join but the extras spectate. L4DToolZ is working but there is no multi-slot plugin, or it failed to load. Check sm plugins list.

The lobby keeps sending the group to an official server. A lobby problem, not an addon one: sv_allow_lobby_connect_only 0 and a matching sv_search_key. The server guide covers it.

Everything broke after an update. Gamedata. Check meta list and sm exts list, then update in order.

FAQ#

Do players need to download my server's addons?

For campaigns and gameplay mods, yes - the server cannot send them, so every player installs the same VPK or subscribes to the same Workshop item. Server-only SourceMod plugins need nothing on the player's side.

Can I run more than eight players in co-op?

Technically, with L4DToolZ and a multi-slot plugin, yes. In practice the game breaks down past about eight survivors: characters repeat, finales misbehave and the Director's pacing falls apart.

Is left4dhooks required for SourceMod on L4D2?

Not for SourceMod itself, but nearly every useful L4D2 plugin written in recent years depends on it. Install it with SourceMod as a matter of course.

Why does one addon stop working when I install another?

Both ship the same file, usually director_base_addon.nut or a model replacement, and the last one mounted wins. Remove one, or replace a script addon with a SourceMod plugin that does the same job.

Can I use client-side mods on a server?

Cosmetic mods on a player's own machine generally work if the server allows them. Servers with stricter sv_pure and sv_consistency settings will kick players whose files differ, which competitive servers do deliberately.