Clothing and 3D models in Project Zomboid mods

Clothing is one of the most satisfying things to mod, because you see it on your character and on the zombies. It's also the area with the most pitfalls. This guide comes from making Catimbas (89 sneakers), Jockies (46 caps), Buzitos (tracksuits) and Telezombies.

The three pieces of a clothing item

1. The item (.txt script), with ItemType = base:clothing, where it's worn (BodyLocation) and which visual clothing item it uses (ClothingItem):

item Nike_AirForce1_White
{
    DisplayCategory = Clothing,
    ItemType = base:clothing,
    BodyLocation = base:shoes,
    BloodLocation = Shoes,
    ClothingItem = Nike_AirForce1_White,
    Icon = Nike_AirForce1_White,
    WorldStaticModel = Nike_AirForce1_White_Ground,
}

The possible BodyLocation values are in the BodyLocations reference.

2. The visual clothing item, an XML file in media/clothing/clothingItems/ that says which model and which texture to use.
3. The GUID entry in media/fileGuidTable.xml, which ties the XML to a unique identifier.

3D model or painted onto the body?

Not all clothing in the game is a 3D model. This determines how much work your mod is:

Reusing a game model and swapping its texture is by far the fastest route.

The holes bug: m_MasksFolder

Symptom: the item looks perfect on the ground and in the inventory, but when worn it's missing chunks, like sheets that don't close up. It's worse with pants on top.

Cause: the game clips each clothing item with "masks" so whatever is covered by the layers on top doesn't poke through. Those masks are drawn for the body UV. If your model has its own UV (a sneaker, a helmet), the cutouts land in random places.

Fix: in the clothing item's XML:

<m_MasksFolder>none</m_MasksFolder>

Before we figured this out, we tried flipping the faces and making the mesh double-sided. Neither was the problem.

Textures: textureChoices or m_BaseTextures

In the clothing item's XML:

• If the item has a model, the texture goes in <textureChoices>. If you put it in <m_BaseTextures> and someone drops the item on the ground, the console fills up with errors.
• <m_BaseTextures> is only for clothing without a model that gets painted onto the body (like a T-shirt or a full suit).

Rigid 3D models

• Format: the game reads .x (text) and .fbx. We generate .x with Python or export from Blender.
• Skeleton weights: for a rigid object (shoe, helmet), have it follow a single bone. If you copy the skin weights, it stretches like rubber when the ankle bends.
• Test it worn in-game. Blender renders don't apply the masks or the real poses, so a lot of problems only show up inside the game.

Dressing the zombies

To make your clothing show up on zombies, you define an outfit in media/clothing/clothing.xml and register it in ZombiesZoneDefinition. That's how we did Telezombies and Fútbol Chileno Z.