Why doesn't my mod work?

SWAT3's modding system is quite complex, which means that you can achieve some pretty cool things. Guns that launch CS canisters, flashlights that look like lasers and characters with semi-transparent skins are all examples of the sort of effects you can get with a little creativity. Unfortunately, the downside of this complexity is that there are loads of ways your mod can go wrong. Add in the fact that Sierra's error messages aren't always as helpful as you'd want and the potential for frustration is high.

I've seen most of the problems that can happen with mods, and I'm sharing them here in the hope that my experiences can save you from tearing your hair out as much as I did.

The questions

Character mods

• Why doesn't a picture of my skin show up in Ops?
• Why doesn't a picture of my character show up in the debrief?
• Why can't I select my character in Ops?

Weapon mods

• Why doesn't the flashlight on my weapon work?
• Why does the game crash when I turn on my weapon's flashlight?
• Why doesn't my gun show up in Ops?
• Why does my gun shoot out sparks when I fire it?

The answers

Character mods

• Why doesn't a picture of my skin show up in Ops?


You must make a "DEF_UI" bitmap image whose name is based on your character's modmpmodels.dat identifier. If your modmpmodels.dat has a line like this:

swatdude	1	My new SWAT officer

then you must make a .bmp called swatdude_DEF_UI.bmp. The image MUST be 124 pixels wide by 198 pixels high.

Please note that if your character's name is too long, SWAT will fail to load the character image!


---

• Why doesn't a picture of my character show up in the debrief?


You must make a "DEF_UI" bitmap image whose name is based on your character's modmpmodels.dat identifier. If your modmpmodels.dat has a line like this:

swatdude	1	My new SWAT officer

then you must make a .bmp called swatdude_DEBRIEF_UI.bmp. The image MUST be 48 by 48 pixels.


Please note that if your character's name is too long, SWAT will fail to load the debrief image!

---

• Why can't I select my character in Ops?

Your character must appear in both modmpmodels.dat and modskins.dat to be usable in the game. A minimal modmpmodels.dat file would be:

MPModels
{
	swatdude	1	My new SWAT officer
}

and a minimal modskins.dat would be:

Skins
{
	swatdude	SWT_DUDE	0	sneaker 0
}

Of course, the game will crash if you don't include SWT_DUDE.GSM in your mod.

• Another answer

The second column in modmpmodels.dat determines whether the character can be used as a SWAT officer. If it is set to 0, the character will only be available in deathmatch or team deathmatch, and only on the tangos' side in the latter case.

Weapon mods

• Why doesn't the flashlight on my weapon work?

You need to tell the game about the weapon's flashlight by editing modguns.dat. The field three from the end determines whether the flashlight works or not. It should be set to 1 for weapons with flashlights.

---

• Why does the game crash when I turn on my weapon's flashlight?

You need to assign a material called FLASHLIGHT to one of the triangles in the weapon mesh. If you're creating the weapon from scratch using 3D Studio MAX, create a sub-material called FLASHLIGHT, create a single polygon just in front of the "light" and set its material ID to match the new sub-material. Don't forget to attach the new polygon to the mesh!

For step-by-step instructions on assigning materials to polygons, see the 3D Studio MAX weapons tutorial.

If you're reskinning an existing weapon, or want to convert a weapon that doesn't have a flashlight, you can use gsmhacking to create a fake flashlight material, using the --add-flashlight command. Read the gsmhacking documentation for more details.

---

• Why doesn't my gun show up in Ops?

Weapons will not be available for selection if the game cannot find the ammo they are supposed to use. Imagine you have the following modguns.dat:

Guns
{
	newgun	36	1	0.075	[...]	(556,10,30)	(556,10,30)	[...]
}

Here we've set the ammo to 556, the 5.56mm NATO round. This is of course the exact same round as the .223 so you could create entries in modammodefs.dat which simply duplicated the 223 ammo type. However, if your ammodefs file is missing or broken, SWAT won't know about the ammo and will refuse to parse your weapon.

Of course you don't need to add a modammodefs.dat entry to use existing ammo. (223,10,30) would work fine.

• Another answer

One gotcha with modguns.dat is that once the game finds a broken entry it will stop parsing the file, which means that if you have four guns listed but the first one is broken - because the ammo is undefined, for example - then the other three weapons will not show up either, even if their entries are fine!

• Another answer

The 13th field of modguns.dat, class determines whether the weapon is a secondary (class=0) or primary (class=1 or class=2). Make sure you look for your gun in the right place!

• Another answer

swatguysel is the last but one field in modguns.dat. If it is 0, only tangos can use the weapon.

---

• Why does my gun shoot out sparks when I fire it?

All guns listed in modguns.dat need corresponding entries in modeffects.dat. First you must make a gunsmoke_ entry. If your weapon uses a new ammo type (defined by you in modammodefs.dat) you will need a shell_ entry as well.

gunsmoke_

The gunsmoke_ effect describes the sprite that represents smoke coming from the barrel of your gun as it is fired. The effect name must match the name of the gun. So if your gun is called newgun then you must make a modeffects.dat entry called gunsmoke_newgun. For example:

Effects
{
	gunsmoke_newgun	SpriteExp	(sprite=gunsmoke_lg,count=3,minrange=3,maxrange=6,minlife=0.5,maxlife=2.0,factor=0.5,drift=0 2 0,spread=45)
}

shell_

The shell_ effect describes the model representing the empty casings that are ejected from the side of the gun when it is fired. You need one effect for each new ammo type you create - with matching names. If your gun uses the new 556 ammo, you will need a modeffects.dat entry like this:

Effects
{
	shell_556	ShellCasing	(skin=223_brass,Elasticity=0.4,BoundRadius=1.0,LifeTime=60,BounceSound=shell_bounce*)
}

If you include both a new gun and new ammunition in your mod, you must include both types of effects in modeffects.dat:

Effects
{
	gunsmoke_newgun	SpriteExp	(sprite=gunsmoke_lg,count=3,minrange=3,maxrange=6,minlife=0.5,maxlife=2.0,factor=0.5,drift=0 2 0,spread=45)
	shell_556	ShellCasing	(skin=9mm_brass,Elasticity=0.4,BoundRadius=1.0,LifeTime=60,BounceSound=shell_bounce*)
}

If these effects are missing, SWAT will substitute the default effect, which is the infamous sparks sprite!

• Another answer

A big, bad and ugly gotcha with modeffects.dat is that you can't put any comments before the first Effects line. Quite why this is, I don't know. You can put comments anywhere in other files but the effects file is picky. It's fine to put comments after the opening brace but not before.

This means that your perfectly correct modeffects.dat file may in fact not work in the game even though there is nothing syntactically wrong with it! Answers on a postcard.

Links

For more details on some of the topics mentioned above, check out my guides. More relevant ones include:

• gsmhacking: command line tool for editing GSM model files.
• Uniform tutorial: a beginner's guide to making skin mods.
• 3D Studio MAX weapon modding: Step-by-step beginners' guide to exporting a weapon for SWAT3.