Stripper:Source

Introduction
Installation
Configuration
New! - Advanced Filtering/Modification
Entity Properties
Screenshots
Credits, License, Acknowledgements
Changelog

1. Introduction

This is a small but flexible plugin which lets you filter and add entities to a map before it loads, much like Stripper2 for Half-Life 1, by botman. You can filter out entities with specific values or regular expressions, or declare new entities to be added. You can also specify per-map configuration options.

2. Installation

First, make sure you have the proper tools installed. You need Metamod:Source 1.8.6 or higher.

Get either Stripper:Source (Linux)
... or Stripper:Source (Windows)
... or Stripper:Source (Mac OS X)
Extract the zip file into your server's mod folder.
You're done!

Note! If you require older versions of Stripper:Source, for example, if you must use an older Metamod:Source version, you can find them by clicking here.

3. Configuration

There are two main configuration files for Stripper:Source. The first is addons/stripper/global_filters.cfg, which is run on every map change. You can also configure per-map files in addons/stripper/maps/.cfg (for example, addons/stripper/maps/de_dust.cfg). These will only be run when that specific map is used.

Stripper:Source configuration files are stored in the following format:

filter:
{
"prop1" "val1"
"prop2" "/val2/"
}
{
"prop3" "val3"
}
add:
{
"prop4" "val4"
"prop5" "val5"
}

Note that the syntax is not flexible - you must declare each item or token on a separate line as shown above. Each block, denoted between the { and } tokens declares an entity. Each line in the block declares a property of the entity. The properties are two quoted strings per line, separated by a space. The first quote is the key, the second quote is the value. For example, this block describes a hostage:

{
"origin" "1376 3168 -112"
"HostageType" "0"
"angles" "0 111 0"
"classname" "hostage_entity"
}

To add an entity, use the "add:" token. Note that you do not need to specify this token for each block -- it will continue until you use another operation token (such as "filter:"). The example below will add the hostage to the map:

add:
{
"origin" "1376 3168 -112"
"HostageType" "0"
"classname" "hostage_entity"
}

To filter an entity from the map, each entity block contains properties that you wish to match against. For example, the following block will remove any entity that is a hostage:

filter:
{
"classname" "hostage_entity"
}

You can also get very specific, for example, this will only filter out the hostage we added earler:

filter:
{
"origin" "1376 3168 -112"
"HostageType" "0"
"classname" "hostage_entity"
}

Lastly, you can also use regular expressions to match entities. To learn more about regular expressions, visit Perl Regex. These let you define patterns to match against. For example, this will remove any entity that is any type of physics prop:

filter:
{
"classname" "/prop_phys.*/"
}

Note that rules are read in order - if add a rule a future rule can filter it out.

4. New! - Advanced Filtering/Modification

Version 1.1 of Stripper:Source adds a powerful new method of filtering entity property blocks. This adds a new directive called "modify." Modification blocks have four sub-blocks: Match, Replace, Delete, Insert. The Match sub-block lets you specify which property blocks to search for. For each matched block, the replace, delete, and insert sub-blocks are processed.

For example:

modify:
{
	match:
	{	
	"model" "models/props_junk/garbage_metalcan002a.mdl"
	"classname" "prop_physics_multiplayer"
	}
	replace:
	{
	"classname" "hostage_entity"
	}
	delete:
	{
	"model" "models/props_junk/garbage_metalcan002a.mdl"
	}
	insert:
	{
	"scale" "0.99"
	}
}

This configuration entry will replace all garbage cans with hostages. How does it work?

match: Matches all entities that have the listed model and classname. You can use regular expressions (//) for any key values here.
replace: Replaces the values of any properties that have the same key name. In this example, "prop_physics_multiplayer" will become "hostage_entity."
delete: Deletes any properties matching both the key name and the value string. The value string may have regular expressions (//). In this example, the model property of the trash can is being removed.
insert: Specifies any additional key value pairs to insert. Here, an arbitrary scaling value is added to the entity.

Although "match" is a required sub-block, replace, delete, and insert are all optional. You can specify the sub-blocks in any order, although they are always processed the same way. Match first, then replace, then delete, and insert last.

5. Entity Properties

Unfortunately, I don't know all of the entity properties. So to help users out, you can use the "stripper_dump" console command (requires rcon or server console access). This will dump a file in addons/stripper/dumps named after your map which contains every single entity and all of its properties that the map initializes on load. This file will be roughly 120-200KB and will provide everything you need for stripping/adding entities.

6. Screenshots

(click to enlarge)

-- Hostage in de_dust spawn.

-- No more props!

-- No more props, part 2!

-- Garbage can replaced by hostage. Spot two more in the background.

7. Credits, License, Acknowledgements

The idea came from Botman's stripper2 (link in Introduction). I got the initial idea of this plugin from Mani, who discovered that by forcing a new entity string through LevelInit, you could change the map's entity list.

Regular Expressions are implemented with PCRE (Perl Compatible Regular Expression Library). Thanks to Freecode for the screenshots, and PM OnoTo for making SourceHook so awesome.

Source code can be found here: http://hg.alliedmods.net/strippersource/

8. Changelog

2011/04/15 - Version 1.2.2
	- Automated builds, updated for latest OB engine.
2009/10/13 - Version 1.2.1
	- Greatly improved map parsing performance.
2009/06/06 - Version 1.2
	- Separated game logic from stripper logic (separate binaries).
	- Removed IStripper interface (this was pretty pointless, I'm sure no one used it).
	- Added L4D support.
	- Cleaned code to use soft tabs.
	- Imported PCRE-7.9.
2007/10/07 - Version 1.1b
	- Now runs on Metamod:Source 1.6 and 1.4, as well as TF2/Orange Box.
2006/10/05 - Version 1.1a
	- Fixed old filters not working correctly.
2006/08/15 - Version 1.1
	- Now requires Metamod:Source 1.3.
	- Added new syntax for more flexible entity modification.
	- Improved load-time performance.
	- Fixed long paths being chopped off.
	- Cleaned up source code and updated to PCRE 6.7.
2006/01/07 - Version 1.01
	- Now requires Metamod:Source 1.2.
	- Supports other stripper-style plugins modifying the map state.
2005/12/10 - Version 1.00
	- Initial Release