Welcome to the Customization Items Encyclopedia for Saints Row 2!
Here you will learn all about Saints Row 2's customization system, and how the files interact with one another.
This guide is part of a three-part series:
Customization Items: The Encyclopedia | Customization Items: Asset Filename Structure Explained | "WTF are VIDs": Full VID List and Explanation.
Here you will learn all about Saints Row 2's customization system, and how the files interact with one another.
This guide is part of a three-part series:
Customization Items: The Encyclopedia | Customization Items: Asset Filename Structure Explained | "WTF are VIDs": Full VID List and Explanation.
There are 7 files which will be covered in this guide:
customization_items.xtbl
customization_slots.xtbl
customization_categories.xtbl
customization_icons.xtbl
customization_flags.xtbl
customization_outfits.xtbl
customization_stores.xtbl
This tree represents how all these files reference each other:
CUSTOMIZATION_ITEMS.xtbl:
This file handles information for the Customization Items themselves.
ID Types:
<Name>:
<Display_Name>:
<Wear_Option>:
<Name>:
<Disabled>:
<Particle_Systems>:
<Mesh_Information>:
<MeshID>:
<Mesh_Filename>:
<Morph_Filename>:
<Cloth_Sim_Filename>:
<Cutscene_Only>:
<VID_List>:
<Obscured_VID>:
<Obscured_slot>:
<Texture_Infos>:
<Variant>:
<Price>/<Respect_Bonus>:
<Variant_Name>:
<VariantID>:
<Material>:
<Shader_Type>:
<Default_Colors_Grid>:
<ID>:
<Default_Colors_Grid>:
<Fat_Bone_Arm>/<Fat_Bone_Leg>:
<Heel_Angle>/<Heel_Height>:
<UV_Data>:
<Logo_Set>:
<Logo_Default_Color>:
<Slot>:
<Multi_Slot>:
<Base_Respect_Bonus>:
<Base_Price>:
<Flags>:
<ID>:
<VariantID>:
<MeshID>:
This is the number of the Item. This must be unique for every Item entry in customization_items.xtbl. The highest number used in both the Vanilla and GotR versions of the file is 1173
<VariantID>:
This is the number representing a Variant. This should match every instance in which the Variant is used. For example; The "Gold" Variant is used for most Jewelry Items. It would use the same Variant_ID number whenever it is used with a Jewelry Item. The highest number used in both the Vanilla and GotR versions of the file is 715.
<MeshID>:
This is the number representing <Mesh_Information>. Every block of Mesh_Information must have a unique Mesh_ID or else the game will get confused. However, the same Mesh_Information block can be used for multiple Wear_Options across different Items while using the same Mesh_ID, so long as the information in that Mesh_Information block is identical, and it cannot be worn at the same time as the other identical Mesh_Information block. In M2M, this can be seen in effect between "Basketball Jersey" and "Basketball Jersey w/Logo" (Different Logo types can be applied because that information is outside of the Mesh_Information block). The highest number used in both the Vanilla and GotR versions of the file is 1822
<Name>:
This is the Internal Name of the Customization Item. This not intended to be seen in-game. But if the Display_Name doesn't match up with any Localization Strings listed in CustItem.xtbl, the Internal Name will be displayed in-game instead.
<Display_Name>:
As mentioned above, this is intended to use Localization Strings listed in CustItem.xtbl. But if the information is incorrect or empty (empty is better for memory), the Internal Name will display in-game instead.
<Wear_Option>:
This is an instance of a mesh for the Item, and accompanying information. You can have as many Wear_Options as you like per Item, but there is a limit on how many Wear_Options specifically you can have active in the file. Wear_Options for an Item will appear in-game in the order they are in in this file.
<Name>:
This must match Localization Strings found in CustWear.xtbl. Not using one of these will instead display the filename of the .cmesh being used for that Wear_Option.
<Disabled>:
"no" allows the Wear_Option to be available for selection in game. "yes" makes the Wear_Option unavailable, as if it were not in the file. Disabling all Wear_Options for an Item will not hide the Item, but a message will appear on screen saying it can't be worn.
Flag Types: Flags reference customization_flags.xtbl. They don't tend to have any special properties (except "flasher coat"). They are just labels used by the game to know how specific Wear_Options throughout the file should interact with each other. You can even add your own Flag entries in customization_flags.xtbl, and use them here.
<Active_Flags>:
<Required_Flags>:
<Incompatible_Flags>:
<Active_Flags>:
"This Wear_Option is [_]."
<Required_Flags>:
"This Wear_Option can only be worn when another Item's Wear_Option's [_] Active_Flag is also being worn."
<Incompatible_Flags>:
"This Wear_Option cannot be worn while another Item's Wear_Option's [_] Active_Flag is also being worn."
<Particle_Systems>:
There is no information on this in the TableDescription, but it is an empty field applied to every Wear_Option in the file. Presumably it was used to enable Particle Effects on Items (eg: dusty boots).
<Mesh_Information>:
Everything pertaining to the mesh used for this Wear_Option can be found within this Mesh_Information container.
<MeshID>:
This is the number representing <Mesh_Information>. Every block of Mesh_Information must have a unique Mesh_ID or else the game will get confused. However, the same Mesh_Information block can be used for multiple Wear_Options across different Items while using the same Mesh_ID, so long as the information in that Mesh_Information block is identical, and it cannot be worn at the same time as the other identical Mesh_Information block. In M2M, this can be seen in effect between "Basketball Jersey" and "Basketball Jersey w/Logo" (Different Logo types can be applied because that information is outside of the Mesh_Information block). The highest number used in the Vanilla file is 000, while in GotR it's 000.
<Mesh_Filename>:
This is the filename of the .cmesh you wish to use for this Wear_Option. ANY .cmesh can be used, including Cutscene Props and NPCs! (There must be enough room in memory to allow for such larger .cmeshes.)
<Morph_Filename>:
This is the filename of the .morph file for the .cmesh (if one is available for that Item). This is often used for Items in Player Creation like Head Hair and Make-Up. It can also be used to squash tall hats (like "Traffic Cone hat") when using a vehicle (instead of using the "big hat" Flag, which entirely removes the Item in vehicles).
<Cloth_Sim_Filename>:
This is the .sim file used for the .cmesh. These are used for Long Head Hair and Skirts.
<Cutscene_Only>:
Is the .morph only used in Cutscenes?
<VID_List>:
Every Customization Item .cmesh is divided up into sections and given a number. These sections are called "Visual Identifiers" (VID), and are used by the game to hide/show different parts of the .cmesh. This is primarily used to hide visual clipping issues, but as seen in M2M, it can be used to alter the appearance of existing Items. VID_List is the list of VIDs for the .cmesh which the game will render. If a number is removed from this list, that part of the .cmesh will not render. You can reference my VID List to see which VID numbers represent which sections of customization Item.
<Obscured_VID>:
Which common VID numbers will this Item obscure when worn? For example; If a Wear_Option obscures VID "127", the Chest-Height Front section of ALL undershirts will be obscured when this Wear_Option is worn.
A full list of VID numbers can be found here.
<Obscured_slot>:
Which Slots will be hidden when this Wear_Option is worn? For example; If a Hoodie is being worn, Undershirts, Overshirts and Bras will not be seen, so there's no need to waste resources rendering them. So it makes sense to obscure those Slots while a Hoodie Wear_Option is being worn.
<Texture_Infos>:
This is not used in customization_items.xtbl, but it is an empty field applied to every Wear_Option in the file. There is information on this in the TableDescription.
<Variant>:
A Variant is the Material/Pattern for a .cmesh. In-Game this is called "Style". These can be pattern color maps (see the Item's .peg file to see what's available for it), or Jewelry metals like Steel, Bronze, Silver, Gold. While most do, not all .cmesh files require a Variant in order to render, but there must be at least one Variant entry for the Customization_Item.
<Price>/<Respect_Bonus>:
These will overwrite Base_Price and Base_Respect_Bonus. They must be higher than those values. This is used to set different prices/respect bonuses for different Variants of the Item. For example; Jewelry has a Base_Price of 50. But this will increase to 100 for Bronze, 250 for Silver and 500 for Gold.
<Variant_Name>:
This is the in-game display name for the Variant. This can be whatever you want it to be. But if you want to use localization strings, you must use a name from CustVar.xtbl.
<VariantID>:
This is the number representing a Variant. This should match every instance in which the Variant is used. For example; The "Gold" Variant is used for most Jewelry Items. It would use the same Variant_ID number whenever it is used with a Jewelry Item. The highest number used in the Vanilla file is 000, while in GotR it's 000.
<Material>:
This is the name of the material used within the .cmesh file itself. It is not always possible to find out what that name might be for an Item. Your best bet is looking through NPC .xtbl files for the Material used for an Item they wear. But for now, The simplest way to explain is with BarrelA015, which is a Prop Item available in M2M. I found the name of the Material for CS_Oildrum in CS_Oildrum.xtbl under Material_Name ("BarrelA015"). This is required for this .cmesh so that only the barrel itself gets colored, and not the warning sticker. (The other Prop .cmeshes didn't require a Variant, and so were not impacted by this being the sole Variant.)
<Shader_Type>:
This references customization_materials.xtbl. This determines how an Item will have color applied. Most Variants use "SR2Cloth", which allows up to three colors to be customized. Hair Items use "SR2Hair2", which allows 9 colors (because Hair colors in customization_hair_color.xtbl are made up of 4 pigments each for Primary and Secondary, with a Specular color on top). "BBCloth1" is an older shader which only allows simple coloring via one color, but it can be used to color some .cmeshes, like Luz's Hair Flower, which cannot ordinarily be colored.
<Default_Colors_Grid>:
This feature does not work for Variants, despite containing information, even in the Vanilla customization_items.xtbl.
<ID>:
This is the number of the Item. This must be unique for every Customization_Item entry in customization_items.xtbl. The highest number used in the Vanilla file is 000, while in GotR it's 000.
<Default_Colors_Grid>:
What are the default colors this Item will be loaded with in Stores? These can be Clothing_Color (ref: character_color_pool.xtbl), Tattoo_Color (ref: tattoo_color_pool.xtbl), or Makeup_Color (ref: makeup_color_pool.xtbl).
<Fat_Bone_Arm>/<Fat_Bone_Leg>:
"Fat Bones" is the sytem for moving limbs further away from the body of characters who are overweight. You can see this in action when you move the Fatness slider in the Plastic Surgeon. Here, you can force Fat Bones to a specific angle while wearing a specific Customization_Item. Numeric values represent degrees, but you cannot use minus values. Instead, to move limbs closer to the body, you must set the angle to be almost a complete circle. This will cause visually strange issues with animations which disable Fat Bones (such as getting into a car), as the limbs will revert backwards from say 358 degrees back to 0 degrees. Using angles which are too extreme can cause weapons not to function properly.
<Heel_Angle>/<Heel_Height>:
These will only work with Items in the "shoes" Slot. Heel angle adjusts the angle of the foot while wearing high-heeled shoes. Heel Height adjusts the height of the character from the floor while wearing this Item.
<UV_Data>:
This is not used anywhere in customization_items.xtbl, but the is an entry in th TableDescription for it.
<Logo_Set>:
This references customization_logo_sets.xtbl. What is the image quality of the logo set you want to use? You can use 128x128 Logos/Numbers, 128x256 Logos or 256x256 Logos/Numbers. The actual logo images that will be available to you when assigning one of these is decided by customization_logo_sets.xtbl.
<Logo_Default_Color>:
When you first assign a Logo to an Item in a Store, what color will it be initially? (ref: character_color_pool.xtbl)
<Slot>:
This is the Slot (or Category) that the Item will be used in. This references customization_slots.xtbl. It's worth noting that whatever you do, "Body Hair" Slots do not function. They will just crash your game. Other Slots need to have enough memory allotted to them to load the .cmeshes for the Items it contains. New Slots can be added to the game via customization_categories.xtbl and customization_icons.xtbl. More on this in a later section.
<Multi_Slot>:
This is used primarily for the "suit" Slot, since by default, it doesn't have any memory allotted to it. Instead, it shares memory between two other Slots, to essentially double it's memory pool without penalty. The only drawback is that Suits cannot be worn with Items which are in the Multi_Slots it is using. There is a First_Slot and a Last_Slot. Other Slots may also be affected, depending on your combination of Slots. It is unclear whether it was intended to work like this, or what the logic is behind which other Slots are affected.
<Base_Respect_Bonus>:
How much of a Respect Bonus does the player recieve for purchasing this Item? Leaving this at 0 uses the first digit of the Base_Price value as the Base_Respect_Bonus.
<Base_Price>:
How much in dollars is this Item worth in Stores (before sales discounts)? "0" is not a valid value. You can use negative values though, which will give the player a specified amount of money when the Item is "purchased". (eg: "-1".)
<Flags>:
These Flags are not like the Active_Flags, Required_Flags and Incompatible_Flags. These relate to the whole Customization_Item. There are three options: 1. "use hair length slider" (this is a redundant leftover), 2. "not ready" (this removes the Item, as if were not in the file. It will not appear in game, and it will make room for another Item if you're short for space in memory), 3. "big hat" (this is used to remove the Item upon entering a vehicle to avoid visual clipping). Only so many of these Flags can be used throughout customization_items.xtbl.
CUSTOMIZATION_FLAGS.xtbl
This file is the source of Flag Names used for Active_Flags, Required_Flags and Incompatible_Flags in customization_items.xtbl. You can add your own Flag entries here.
For the most part, these Flags do not have any special properties. They are nothing more than labels (except "flasher coat", which enables "flasher coat with morphs" for the "Flashing" Diversion).
<Name>:
The name of the Flag. To be used for Active_Flags, Required_Flags and Incompatible_Flags in customization_items.xtbl.
CUSTOMIZATION_SLOTS.xtbl:
This file determines how much memory is allotted to each Slot.
For larger Items, you may need to increase the allotted memory for the Slot it is using in order for the Item to load. There is only so much memory the game will allow you to use across all Slots. Exceeding this will cause the game to crash. So it's a good idea to try to "trim the fat" for Slots which use more memory than they need.
New Slots cannot be added, and existing Slots cannot be removed.
"armpit hair", "chest hair", "arm hair", "leg hair" and "back hair" Slots do not work. They will crash the game when used, no matter how much memory you assign to them.
Clothing Slots use the Clothing Color Pool, Tattoo Slots use the Tattoo Color Pool, Make-Up Slots use the Make_Up Color Pool. (RGB values for pigments can be found in character_color_pool.xtbl, tattoo_color_pool.xtbl and makeup_color_pool.xtbl respectively.)
The "5 o-clock shadow" and "eyelashes" Slots enable you to use Hair Colors for any Items which use it. (You cannot set Hair Colors as Default Colors in customization_items.xtbl though, so I recommend using Tattoo Colors as Defaults for Items in these Slots.) RGB values for Hair color pigments can be found in hair_color_pool.xtbl.
<Name>:
<CPU_Size>/<GPU_Size>:
<PS3_CPU_Size>/<PS3_GPU_Size>:
<Flags>:
<Render_Order>:
<Default_Material>:
<Default_Variable>:
<NULL_Component>:
The internal name of this Slot. This cannot be changed.
<CPU_Size>/<GPU_Size>:
It seems these are only for Xbox 360. For PC modding, you can set these to 0. These change the allotted memory for the CPU and GPU respectively. The value here represents bytes. It's best to use a value which is a multiple of 8, since 1 byte is made up of 8 bits.
<PS3_CPU_Size>/<PS3_GPU_Size>:
These are for PS3 and PC. For PC modding, you'll want to edit these. These change the allotted memory for the CPU and GPU respectively. The value here represents bytes. It's best to use a value which is divisible by 8, since 1 byte is made up of 8 bits.
<Flags>:
How should the game handle this Slot? Options are: "required" (Prevents the Slot from being removed in Player Creation/Plastic Surgeon), "npc only" (Unknown: Possibly a leftover fron Volition's NPC builder tool), and "remove on outfit" (Unknown. Might not work).
<Render_Order>:
When the game needs to load in a bunch of Slots at once (eg; For an Outfit), it does not load everything at once because that would strain the system too much and too suddenly, and possibly cause the game to get confused and crash. Therefore, everything loads in a sequence of 3 stages. Here, you can choose to have a slot spawn first ("1"), second ("2") or third ("3") in this sequence.
<Default_Material>:
Unused.
<Default_Variable>:
Unused.
<NULL_Component>:
Unused. Contains elements for texture information.
CUSTOMIZATION_CATEGORIES.xtbl:
Categories are the menu sections for a Slot (in vertical menus). For example; "Undershirts", "Socks", etc..
<Name>:
<Display_Name>:
<Slots_Grid><Slot_Element><Slot>:
<Obscure_Grid><Slot>:
<Obscure_Grid><Flag>:
<Camera_Settings>:
<Male_Animations>/<Female_Animations>:
<No_Wear_String>:
The internal name of the Category. If the Display_Name has incorrect information or is left empty, this will show in-game instead. This will be referenced by customization_icons.xtbl. There is a limit to how many characters you can use here when not using Localization Strings for the Display_Name.
<Display_Name>:
As mentioned above, if this is left incorrect or empty, the internal Name will be used in-game instead. For it to be used correctly, it needs an applicable Localization String. Localization Strings can be found in CustCat.xtbl.
<Slots_Grid><Slot_Element><Slot>:
This is the Slot which will be used for this Category. It references customization_slots.xtbl.
<Obscure_Grid><Slot>:
This is a list of all other Slots which will be hidden while previewing Items in this Category. For example, While browsing Nose Piercings, you'd want to hide Slots which contain Items which cover the Nose, like the Ski Mask.
<Obscure_Grid><Flag>:
You can also obscure Items by the Active_Flag they have assigned to them in customization_items.xtbl, if you wanted to be more specific. This is only used by the Hair Category in the unmodded customization_categories.xtbl to obscure the Hoodie when the Hood is worn up. But since you can't wear the Hoodie in the Plastic Surgeon anyway, it never actually gets used.
<Camera_Settings>:
The positioning of the camera when previewing Items in this Category. There is also a setting for this in customization_icons.xtbl. They don't always play nicely together. For example; M2M fixes some issues with some Category Cameras being positioned slightly differently depending on which Store you're in. This is due to differences in Camera_Settings between these two files (as well as map geometry getting in the way).
<Male_Animations>/<Female_Animations>:
Whichever of these gets used is dependent on which Sex Template was used to create the character. <State> is the looped State animation used while previewing this Category. <Animation> is the single-use Action animation used when purchasing an Item from this Category. Names for both States and Actions can be found in anim_states.xtbl and anim_actions.xtbl respectively. The actual animation used depends on what is assigned to the State/Action in the youngest child animation set currently being used by the Playa. This is GML1.xtbl for Males, and GFL1.xtbl for Females, but could also be a parent animation set, if the State/Action is not present in those files. The animation file itself must also be present in Anim_Files.xtbl and preload_anim.tbl.
<No_Wear_String>:
The message that is displayed when this Item can be purchased but not worn. In the unmodded customization_categories.xtbl, this is only used for Belts, Medallions and Pendants. You can find the Localization Strings in LooksStores_text.xtbl.
CUSTOMIZATION_ICONS.xtbl:
Icons are the horizontal tabs at the top of the screen. For example; "Head", "Upper Body", "Lower Body" etc.. Icons contain the vertical menus where Categories are displayed. The order in which Icons - and the Categories within them - are listed in this file is the order they will be displayed in in-game.
<Name>:
<Display_Name>:
<Angle>/<Distance>/<Offset>:
<Categories>:
<Outfits_Only>(yes/no):
The internal name of the Icon. As with Categories, if the Display_Name has incorrect information or is left empty, this will show in-game instead.
<Display_Name>:
As with Categories, if this is left incorrect or empty, the internal Name will be used in-game instead. For it to be used correctly, it needs an applicable Localization String. Localization Strings can be found in StoreExports.xtbl.
<Angle>/<Distance>/<Offset>:
These are the parameters for default camera positioning mentioned in the Categories section of this guide.
<Categories>:
These are the internal names of the Categories from customization_categories.xtbl. Putting a Category here is the last step in enabling a Slot for the game. Wherever you choose to put this is the order it will be displayed in the in-game menus.
<Outfits_Only>(yes/no):
Are Outfits stored in this Category? Outfits don't use a Slot, since they themselves are made up of multiple Slots. They are therefore treated differently.
CUSTOMIZATION_OUTFITS.xtbl:
Here you can assemble Outfits which can be purchased from Stores (customization_stores.xtbl) or unlocked through gameplay (unlockables.xtbl).
It is recommended to stick to around 10 Items per Outfit as a rule of thumb, since there is a limit on how many Items can be used in this file, and more Items means the Outfit will take longer to load.
<Name>:
<Display_Name>:
<Content_Grid>:
<Content_Element>:
<Item>:
<Default_Wear_Option>:
<Primary_Color>:
<Secondary_Color>:
<Tertiary_Color>:
<Logo>:
<Logo_Color>:
<Variant_Grid>:
<Variant_Element>:
<Variant>:
<Cost>:
<Style>:
Unlike other files, this internal name will NOT be seen in-game. But it is referenced by many other files throughout the game, including; customization_stores.xtbl, unlockables.xtbl and various Missions, Activities and Cutscenes. It is therefore recommended to keep these names as they are in Vanilla or GotR to maintain compatibility (even if they don't match up with what the Outfits actually look like).
<Display_Name>:
Unlike other files, whatever is typed here will show in-game. It is intended for Localization Strings though, which can be found in CustItem.xtbl (this is not mentioned in the TableDescription).
<Content_Grid>:
The list of Items used for this Outfit.
<Content_Element>:
An individual Item used in this Outfit.
<Item>:
The internal name of the Item in customization_items.xtbl.
<Default_Wear_Option>:
This is decided by the .cmesh used for that Wear_Option for that Item. In the event that an Item uses the same .cmesh for two of it's Wear_Options, the first Wear_Option will always be used.
<Primary_Color>:
The first customizable color used for this Item. This is required, whether it is visible on the Item or not. References character_color_pool.xtbl.
<Secondary_Color>:
The second customizable color used for this Item. This is required, whether it is visible on the Item or not. References character_color_pool.xtbl.
<Tertiary_Color>:
The third customizable color used for this Item. This is required, whether it is visible on the Item or not. References character_color_pool.xtbl.
<Logo>:
What Logo do you want to be applied to the Item (if any)? This references customization_logos.xtbl. There are three sizes (126x126, 256x126, 256x256) which will all display differently on the Item, and you can choose from a library of Logos or Numbers. It can take a little detective work to figure out which Logo is which, especially in GotR.
<Logo_Color>:
The color of the Logo (if one is applied). References character_color_pool.xtbl.
<Variant_Grid>:
The list of Variants (ref: customization_items.xtbl) for all the Items used for this Outfit. If an Item has multiple Variants, you can choose which one is used here. Every element in this list must match the order of the Items in the Content_Grid.
<Variant_Element>:
An individual Variant for an Individual Item. The position of this in the Variant_Grid list must match the order of it's Content_Element in the Content_Grid.
<Variant>:
References s Variant's Name in customization_items.xtbl.
<Cost>:
How much will this Outfit cost in dollars from Stores? (in customization_items.xtbl, this is called "Base_Price".) Unlike in customization_items.xtbl, "0" is a valid value.
<Style>:
How much Respect Bonus will be awarded for purchasing this Outfit from Stores? (in customization_items.xtbl, this is called "Base_Respect_Bonus".) Unlike in customization_items.xtbl, "0" will just set the Respect Bonus to 0.
CUSTOMIZATION_STORES.xtbl:
This file controls which Items and Outfits are sold in which Stores.
<Store>:
<Name>:
<Display_Name>:
<Flags>:
<Shops>:
<Store_Item>:
<Item>:
<Variants>:
<Outfits>:
A Store chain. Stocked Items and Outfits will apply to all Stores in a Chain.
<Name>:
The internal name of the Store. Don't change this.
<Display_Name>:
The for the Store which is Shown in-game. These use Localization_Strings found in LooksStores_text.xtbl.
<Flags>:
There is only one option available here: "allow_wardrobe". This allows you to enter your Wardrobe while in the Store.
<Shops>:
The Stores within this Chain. Don't change this. References shops_sr2_city.xtbl.
<Store_Item>:
This is information relating to a single Item added to a Store.
<Item>:
The internal name of the Item you wish to appear in this Store. References customization_items.xtbl.
<Variants>:
You can choose to only sell specific Variants of an Item in a Store. This is a little buggy, as the first available Variant will always be applied by default when selecting the Item in-game. But once you change the "Style" (Variant) in-game, it will only use the Variants made available to that Store. Leaving this blank allows all Variants to be sold. References a Variant's Name customization_items.xtbl.
<Outfits>:
Which Outfits should be sold in this Store? References the internal Names of Outfits in customization_outfits.xtbl. (This is why it's best not to change internal Names for Outfits in customization_outfits.xtbl.)
Last edited:
