Current Version: 1.0.1
With this guide, you will learn all about Saints Row 2's NPC files.
You will learn how to change the colours of the items an NPC wears, change their gameplay voice, filter in-game appearance by gender/race/character type, force specific outfit variants, change a character's model, change a character's animation set, set which gang the character belongs to, change spawning conditions, change a character's height and height variability, fix a prop to a character's left hand, and much more!
Version 1.0.0 of this guide is available as a series of .txt files attached to this post. However, any future updates will be made to this post directly.
I am open to suggestions on how this guide can be improved. There are things here and there I'm not entirely certain on (like <MetaGame>). If you feel you can contribute, then feel free to let me know below in this thread.
"NPC Cruncher Stuff" contains the "tables" folder and "Run SR2 NPC Table Crunch.bat" required to use Volition's NPC Table Cruncher. Place both in the same location as "sr2_npc_table_crunch.exe".
Resources:
"Shaundi's Secret Stash - NPC Table Cruncher" by Volition
"SR2PegTool" by Masamaru - For extracting/repacking textures from .peg_pc files.
"Editing .sim_pc files." by Moff - I've no experience with Blender, but this might be useful for those who do. Bear in mind, this was made for SR4, and might not work for SR2's .sim_pc files.
With this guide, you will learn all about Saints Row 2's NPC files.
You will learn how to change the colours of the items an NPC wears, change their gameplay voice, filter in-game appearance by gender/race/character type, force specific outfit variants, change a character's model, change a character's animation set, set which gang the character belongs to, change spawning conditions, change a character's height and height variability, fix a prop to a character's left hand, and much more!
Version 1.0.0 of this guide is available as a series of .txt files attached to this post. However, any future updates will be made to this post directly.
1. PC/NPC/SNPC/CNPC/CS - What's The Difference?
PC:
NPC:
SNPC:
CNPC:
CS:
PC:
PC is a Playable Character. A Character a player controls. It may refer to the Character you control, or the Characters controlled by other players for Multiplayer and Co-op. Files referring to a Playable Character are usually named "StyleTest_PC".
NPC:
NPCs are used during Open-World gameplay (Free-Roam, Missions, Activities, etc.). They contain fewer polygons and less facial animation structure, meaning they use less of the game's memory than an SNPC or CNPC. An NPC can only open and close it's mouth like Pac-man while talking.
SNPC:
SNPCs are used for cinematic Story Cutscenes. They are made of more polygons, use higher quality textures, and are capable of more complex facial animation than NPCs or CNPCs.
CNPC:
CNPCs are used for Activity Cutscenes. These Cutscenes are much more basic than Story Cutscenes, using simpler animations with less complex facial movements. CNPCs are essentially the same as NPCs, but are capable of slightly more complex facial animations. A CNPC can make more mouth shapes than an NPC.
CS:
CS stands for Cutscene. These are Cutscene Props. Cutscene Props utilize the same animation rigging system as human characters. For example; When the roses fall to the ground in the "House Party" cutscene, it utilizes a specialized animation rig to allow each rose to be animated to fall independently, while still being one prop.
2. FILES OVERVIEW - All files which relate to a specific character.
npc_name.xtbl:
npc_name.cvtf:
npc_name_pre.xtbl:
npc_name_cha.xtbl:
npc_name_des.xtbl:
npc_name.cmesh_pc:
npc_name.g_cmesh_pc:
npc_name.peg_pc:
npc_name.g_peg_pc:
npc_name.morph_pc:
npc_name.pcm_pc:
npc_name.sim_pc:
npc_name.xtbl:
This file contains information pertaining to the customization variables of a character.
You can change the likelihood that a character will spawn with a specific clothing/hair item, or clothing/hair colour. You cannot, however, make a character wear an item which is not included in their character mesh.
This file also controls the character's gameplay voice and character morph, though the morphs a character can use are dictated by it's .morph_pc file, which cannot be edited at the time of writing.
A character's .xtbl file must be converted into a .cvtf in order to be read by the game. This is achieved with Volition's "NPC Cruncher", included with "Shaundi's Secret Stash" mod tools. (More on this later.)
npc_name.cvtf:
"CVTF" is believed to stand for something along the lines of: "Character Variant Table File".
As mentioned above, this is the filetype read by the game to determine a character's customizable parameters (clothing colours, etc.).
npc_name_pre.xtbl:
"_pre" stands for "Preset".
The Preset ties together elements of other files to create the final character. It determines which Character file (npc_name_cha.xtbl) is used, it's spawn_info_rank (health pool and weapon load-out), which Team the character is on, it's AI controlled behaviours, and more.
npc_name_cha.xtbl:
"_cha" stands for "Character".
The Character file contains physical information about the character. It determines which Character Model (.cmesh) is used, which Animation Set it uses, it's Animation Rig (skeleton), Height (overall size), Blink Rates (though I've never been able to get this to do anything), and more.
npc_name_des.xtbl:
"_des" stands for "Design".
This file merely determines a character's Stream Category. That is; What should the game spawn them as? Civilian, Gang Member, or Cop? If a Gang Member, then are they a Male or Female Soldier, or a Male or Female Lieutenant?
Note: This is not the same thing as which "Team" they belong to. It's whom they spawn alongside.
npc_name.cmesh_pc:
".cmesh" stands for "Character Mesh".
These are meshes which can support an Animation Rig (as opposed to Static Meshes [.smesh_pc], which cannot).
You may notice Cutscene Props also use Character Meshes. This is because they use the same rigging system as human characters to enable their animations.
For example, when Shaundi smashes the Lightbulb in "Pipes Are For Suckers", or when Playa kicks down the Courtroom Door in "Courtroom Drama".
npc_name.g_cmesh_pc:
Contains geometry data for the .cmesh.
npc_name.peg_pc:
Contains textures for the character. These files can be unpacked using Masamaru's sr2PegTool.
npc_name.g_peg_pc:
Contains geometry data for the character's textures. This file is required in order to unpack the .peg file using sr2PegTool.
npc_name.morph_pc:
Contains presets for Face and Body morph data (similar to that which is adjustable via the in-game Character Creation for the Player Character).
These Morph Presets can be assigned to a character via their .xtbl/.cvtf files.
It is not possible to edit this file at the time of writing.
npc_name.pcm_pc:
Unknown. I believe this may stand for "Player Creation Morph". Ie: What Morph Keys can be used with this .cmesh. (Unverified).
npc_name.sim_pc:
This file contains data for Cloth Physics simulation.
Of the four Saints Row games, Saints Row 2 is the only game in the series not to make use of Cloth Physics. But it was clearly intended during development, and these files are remnants of that.
I don't know if Saints Row 2's .sim_pc files can be modified. Though a tool does exist for exporting/importing .sim_pc files from Saints Row IV. (Credit: Moff)
3. PRESET FILES
Here you will learn about all the possible functions of a character's Preset file (npc_name_pre.xtbl).
Most of everything included here is translated into an easier-to-read format from the <TableDescription> found in character_presets_complete.xtbl.
There may be more functions which aren't included in the <TableDescription>. I will add these as and when I encounter them.
<Name>:
<Character>:
<ForcedVariant>:
<Filters>:
<Persona_Override>:
<Spawn_Info_Rank>:
<Team>:
<AI_Personality>:
<Melee_Style>:
<Cash>:
<Flags>:
<AnimSets>: (Not found in <TableDescription>.)
<MetaGame>: (Not found in <TableDescription>.)
Here you will learn about all the possible functions of a character's Preset file (npc_name_pre.xtbl).
Most of everything included here is translated into an easier-to-read format from the <TableDescription> found in character_presets_complete.xtbl.
There may be more functions which aren't included in the <TableDescription>. I will add these as and when I encounter them.
<Name>:
This should match the name of the file.
Example: npc_maero_pre.xtbl should have:
Code:
<Name>npc_Maero</Name><Character>:
References: characters.xtbl.
Changing this is the easiest way to change the Character Model for a character.
This will specify the Character file (npc_name_cha.xtbl) to be used for the character.
Example: If you wanted to replace Maero with Jessica, then in npc_maero_pre.xtbl, you would have:
Code:
<Character>npc_jessica</Character><ForcedVariant>:
Force a variant of the character model. This references the .cvtf/.xtbl.
Example: If you wanted to force Maero's Shirt variant, you would find the name of the <variant> in npc_maero.xtbl ("shirt"), then in npc_maero_pre.xtbl you would have:
Code:
<ForcedVariant>shirt</ForcedVariant>Now whenever npc_maero appears in-game, he will be wearing his shirt variant.
<Filters>:
Filters allow you to specify the variants you want to use from the .cvtf/.xtbl by specific attributes.
Options:
CharacterType (References the Variant Table for names found in character_types.xtbl)
Gender (Male/Female)
Race (Asian, Black, Hispanic, White)
Look through the .xtbl file to find what you want to filter.
Examples:
If I wanted only Female cops to spawn, in npc_cop_pre.xtbl I would have:
Code:
<Filters>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] <Gender>Female</Gender>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] </Filters>
But if I wanted specifically Hispanic Female Biker Cops to spawn in place of regular cops, in npc_cop_pre.xtbl I would have:
Code:
<Filter>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] <CharacterType>bike_cop</CharacterType>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] <Gender>Female</Gender>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] <Race>Hispanic</Race>[/INDENT][/INDENT][/INDENT]
[INDENT=2][INDENT=2][INDENT=2] </Filter><Persona_Override>:
References: Persona.xtbl
This will allow you to force the character to use a specific gameplay voice.
You can change the Persona voice for individual variants in the .xtbl/.cvtf, But this <Persona_Override> will override it for all Variants.
Personas also control what an NPC's default Radio Station is when spawned in a car, and what their follower icon will be if recruited as a Homie.
Example: If I wanted Gat to sound like Aisha, in npc_gat_pre.xtbl I would have:
Code:
<Persona_Override>SP_AISHA</Persona_Override><Spawn_Info_Rank>:
References: spawn_info_ranks.xtbl
This determines weapon load-out, health pool, and how much damage the character can take before ragdolling.
Browse through spawn_info_ranks.xtbl until you find a rank appropriate for the character.
If you want to be more specific, you'll have to edit spawn_info_ranks.xtbl itself.
Example:
Code:
<Spawn_Info_Rank>Homie - Gat</Spawn_Info_Rank><Team>:
References: Teams.xtbl
Sets which Team the character is on:
Playas (Saints)
Ultor
Police
Civilian
Neutral Gang (Pimps)
Brotherhood
Samedi
Ronin
Example:
Code:
<Team>Brotherhood</Team><AI_Personality>:
Reference: ai_personalities.xtbl
AI Personalities determine the behaviour of AI controlled characters in given situations.
To get a better understanding of what each AI Personality does, have a browse through ai_personalities.xtbl.
Example:
Code:
<AI_Personality>civilian cowardly</AI_Personality><Melee_Style>:
Reference: melee_styles.xtbl
Assign a specific Melee Style to a character.
Options:
Brotherhood
Ronin
Samedi
Not using this function will default melee animations to whatever the character's Animation Set (or parent Animation Set) assigns.
Example:
Code:
<Melee_Style>Brotherhood</Melee_Style><Cash>:
Determines the minimum and maximum worth of coins and dollar bills that are dropped upon the character's death.
Worth is randomised between minimum and maximum.
Coins cannot be worth less than 1 or more than 12.
Dollar Bill Minimum cannot be less than 0, but can go as high as you like.
Dollar Bill Maximum cannot be less than 1, but can go as high as you like.
Example:
Code:
<Cash>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Coin>8</Coin>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Dollar>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Min>10</Min>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Max>20</Min>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Dollar>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Cash><Flags>:
Note: I have not tested most of these.
Apply flags to the character to give the game specific information on how to use them.
Options:
zombie = Moves the character as if it would a Zombie in Zombie Uprising, including using the biting minigame.
pimp = Treats the character as a Pimp.
ho = Treats the character as a Ho.
never_use_walk_variants = Character only uses the default walking animation assigned in it's animation set.
no_special_spawn = Character will not spawn in Action Nodes? (Unverified.)
no_sitting = Character will not use sitting action nodes (such as benches, etc.).
special_movement = (Unverified.).
no_ambient_spawning = Character will not spawn as a pedestrian or as a driver in traffic.
medic = Character can arrive in an ambulance when it is called, and will attempt to revive dead pedestrians. (Unverified.).
use_gang_color_scheme = Colours the character's dot on the mini map according to the Team they are on. (Not found in <TableDescription>.) (Unverified.)
zombie_voice_only = Forces the character to use a Zombie voice. (Not found in <TableDescription>.) (Unverified.)
Example:
Code:
<Flags>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Flag>never_use_walk_variants</Flag>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Flag>no_ambient_spawning</Flag>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Flags><AnimSets>: (Not found in <TableDescription>.)
Assigns an Animation Set to the character.
You can find a full list of Animation Sets in anim_set_filenames.xtbl.
Ordinarily, Animation Sets are assigned via the Character file (npc_name_cha.xtbl). But the Preset file (npc_name_pre.xtbl) takes precedence over the Character file. I therefore recommend assigning Animation Sets via the Preset file, instead of the Character file.
Example:
Code:
<AnimSets>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <AnimSet>0.0<Filename>GML1.xtbl</Filename>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <PercentChance>100</PercentChance>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </AnimSet>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </AnimSets><MetaGame>: (Not found in <TableDescription>.)
I've no idea what this does, and it isn't in any <TableDecription>. There are also Localization Strings which relate to METAGAME. I've seen it used in npc_samedi_gabby_pre.xtbl, as shown below.
Example:
Code:
<MetaGame>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Value>150</Value>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Name>METAGAME_GANG_LIEUTENANT</Name>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </MetaGame>4. CHARACTER FILES
Here you will learn about all the possible functions of a character's Character file (npc_name_cha.xtbl).
Most of everything included here is translated into an easier-to-read format from the <TableDescription> found in character_complete.xtbl.
There may be more functions which aren't included in the <TableDescription>. I will add these as and when I encounter them.
<Name>:
<Approved>:
<Model>:
<Model_Alt>:
<Morph>:
<Pcm>:
<Cloth_Sim>:
<Height_Class>:
<Height>:
<Variation>:
<Base_Height_Offset>:
<LOD_Distance>:
<Min_Blink>:
<Max_Blink>:
<Anim_Set>:
<Rig>:
<Left_Hand_Item>:
Here you will learn about all the possible functions of a character's Character file (npc_name_cha.xtbl).
Most of everything included here is translated into an easier-to-read format from the <TableDescription> found in character_complete.xtbl.
There may be more functions which aren't included in the <TableDescription>. I will add these as and when I encounter them.
<Name>:
This should match the name of the file.
Example: npc_maero_cha.xtbl should have:
Code:
<Name>npc_Maero</Name><Approved>:
I assume this was used by developers to help track development progress of Saints Row 2.
<Model>:
Which Character Mesh (.cmesh) does this character use?
Bear in mind, things such as Height and Morphs are determined elsewhere in this Character file.
For this reason, I instead recommend assigning an already existing Character file (npc_name_cha.xtbl) to a desired Preset file (npc_name_pre.xtbl) if all you want to do is swap characters.
But if you want to do it this way, here's an example:
Example: If I want to replace Maero's Model with Jessica's Model, in npc_maero_cha.xtbl I would have:
Code:
<Model>npc_jessica.cmeshx</Model>
If I want the model to display properly, I would have to change the Morph, PCM, and Cloth Sim (more info below) to match npc_jessica.
(Note: The "x" in ".cmeshx" simply allows this Character file to be used for Xbox 360, which uses ".cmesh_xbox2" instead of ".cmesh_pc". The same concept applies to many other files in Saints Row 2.)
<Model_Alt>:
The <TableDescription> describes this as: "for localizing strippers". This is likely why npc_stripper_female_b exists unused in the files. It was supposed to be used by <Model_Alt>. However, as of yet, I have not been able to get this to work.
Example: It would look like this:
Code:
<Model_Alt>npc_stripper_female_b.cmeshx</Model_Alt><Morph>:
Which Morph file (.morph) file does this character use?
This needs to match the name of the .cmesh.
Example:
Code:
<Morph>npc_jessica.morphx</Morph><Pcm>:
Which .pcm file does this character use?
As mentioned earlier in this guide, I'm not certain what this file is. But it is required.
Example:
Code:
<Pcm>npc_jessica.pcmx</Pcm><Cloth_Sim>:
Which Cloth Simulation file (.sim) does this character use?
Cloth simulation is rarely used in Saints Row 2, if at all. But to be safe, the name of this file should match the .cmesh.
Example:
Code:
<Cloth_Sim>npc_jessica.simx</Cloth_Sim><Height_Class>:
References: character_height.xtbl
I think this is more for reference purposes, rather than having any physical effect in-game. If it does have a physical effect in-game, it would only do so if no other Height modifiers exist in the same Character file.
Options:
Small
Large
Medium
Example:
Code:
<Height_Class>Medium</Height_Class><Height>:
How tall is the character? This will change the character's overall size.
Here are the maths for working out accurate character heights:
6ft = 1.0
Using a calculator;
Divide that by 6 to get the value equivalent to 1 foot.
Divide that by 12 to get the value equivalent to 1 inch.
Cheat Sheet:
6ft = 1.0
1ft = 0.1666666666666667
1in = 0.0138888888888889
1/2in = 0.0069444444444444
You can add/multiply these values with a calculator to achieve the height you desire!:
Example:
5 x 0.1666666666666667 = the value equivalent to 5ft
Example:
Code:
<Height>1.0</Height>
You can even invert a character's height by putting a minus in front of the height value!
This will invert the character's overall size, essentially turning them inside-out, meaning you will be able to see inside the character from whatever angle you view them from.
Example: Inverted 6ft:
Code:
<Height>-1.0</Height><Variation>:
With each instance of the character that is spawned, how far from the base height can they differ? It is recommended to only use this with NPCs.
Example: If I want npc_prisoner to be able to spawn at any height between 5'11" and 6'1", in npc_prisoner_cha.xtbl I would have:
Code:
<Height>1.0</Height>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Variation>0.0138888888888889</Variation><Base_Height_Offset>:
How high off the ground is the base (soles of the feet) of the character?
This is used for characters who wear high-heels, but the effect might already be applied via <Shoe_Heel_Height> in the character's .xtbl/.cvtf.
Example: You can make a character hover in the air (6ft).
Code:
<Base_Height_Offset>1.0</Base_Height_Offset>(You will want to do this if you are messing with inverting a character's <Height> value, or they will be standing below the ground.)
Example: Or you can make a character sink through the ground (-3ft).
Code:
<Base_Height_Offset>-0.5</Base_Height_Offset><LOD_Distance>:
The distance (in meters) from the camera at which this character switches between the low and high Level Of Detail (LOD) character models and textures.
Example: (Default)
Code:
<LOD_Distance>15.0</LOD_Distance>
Example: For performance reasons, I want to switch to the low LOD model while the character is closer to the camera:
Code:
<LOD_Distance>7.5</LOD_Distance><Min_Blink>:
The minimum interval (in milliseconds) between blinks for this character.
I have never been able to get this to work.
Example:
Code:
<Min_Blink>1000</Min_Blink><Max_Blink>:
The maximum interval (in milliseconds) between blinks for this character.
I have never been able to get this to work.
Example:
Code:
<Max_Blink>4000</Max_Blink><Anim_Set>:
Which Animation Set does this character use?
You can find a full list of Animation Sets in anim_set_filenames.xtbl.
I personally prefer to assign an Animation Set via a character's Preset file (npc_name_pre.xtbl), since that file takes precedence over the Character file (npc_name_cha.xtbl).
Example:
Code:
<Anim_Set>GML1</Anim_Set>
Fun Fact: The <TableDescription> sets the Default Animation Set name as "Bob!", but no one named "Bob" or "Robert" is listed in credits_full.xtbl.
<Rig>:
Which Animation Rig (.rig) does this character use?
The Animation Rig is the skeleton which animations are applied to.
The Animation Rig for humans in Saints Row 2 is "sr2_main_rig.rig".
Cutscene Props (CS) tend to have their own specific rigs. If not, it might use "sr2_onebone_rig.rig".
Vehicles also have their own Animation Rigs.
Example:
Code:
<Rig>SR2_Main_Rig.rigx</Rig><Left_Hand_Item>:
References: items_3d.xtbl
I have no idea why this is even here, but it's cool nonetheless!
This permanently adds any Item listed in items_3d.xtbl to the left hand of any character, so long as they aren't ragdolling.
It even works for Playable Characters (PCs)!
Example:
Code:
<Left_Hand_Item>40oz<Left_Hand_Item>5. DESIGN FILES
Here you will learn about the functions of a character's Design file (npc_name_des.xtbl).
Everything included here is translated into an easier-to-read format from the <TableDescription> found in character_design_complete.xtbl.
A Design file (npc_name_des.xtbl) handles streaming/spawn information for a character.
<Name>:
<StreamCategory>:
<SpawnableGangInfo>:
<Flags>:
Here you will learn about the functions of a character's Design file (npc_name_des.xtbl).
Everything included here is translated into an easier-to-read format from the <TableDescription> found in character_design_complete.xtbl.
A Design file (npc_name_des.xtbl) handles streaming/spawn information for a character.
<Name>:
This should match the name of the file.
Example: npc_maero_des.xtbl should have:
Code:
<Name>npc_maero</Name><StreamCategory>:
What should the game spawn this character as? Ie; Who should they spawn alongside? Cops? Gangs? Civilians?
Note: This is not the same as assigning a character's Team.
For example; You could have the game spawn Brotherhood members alongside Ronin members with Ronin notoriety, but they would fight each other.
Options:
Spawnable Civilian
Non Ambiently Spawnable
Spawnable Police
Spawnable Saint
Spawnable Ronin
Spawnable Samedi
Spawnable Brotherhood
Spawnable Ultor
Example:
Code:
<StreamCategory>Spawnable Civilian</StreamCategory><SpawnableGangInfo>:
If the character is set to spawn as a gang member, which rank of gang member should the game spawn them with?
Each gang is made up of four generic types: Male Lieutenent, Female Lieutenent, Male Soldier, Female Soldier.
(This is why there are four Saints gang members shown in the in-game Gang Customization menu.)
Options:
Male Soldier
Female Soldier
Male Lieutenent
Female Lieutenent
Example:
Code:
<SpawnableGangInfo>Male Lieutenent</SpawnableGangInfo><Flags>:
These unrequired Flags give the game more information about how the character should be spawned.
Options:
player_character
item_character <--This is for Cutscene Props.
Example:
Code:
<Flags>player_character</Flags>6. VARIANT TABLES
Here you will learn about a character's Variant Table file (npc_name.xtbl).
These files allow you to customize various existing physical elements of a character, including clothing, skin, and hair colours and materials.
This .xtbl file cannot be read by the game, and will need to be converted to a .cvtf file in order to work.
This process is not covered here, but is covered in the next section of this guide.
Everything included here is translated into an easier-to-read format from the <TableDescription> found in a character's Variant Table file.
<Name>:
<Variants>:
<Variant>:
<Name>:
<Weight>:
<ParkingWeight>:
<Character_Type>:
<Gender>:
<Race>:
<Variant_IDs>:
<Vid_group>:
<Name>:
<Vid_chances>:
<Vid_chance>:
<Description>:
<VID_list>:
<Obscured_VID_List>:
<Shoe_Heel_Angle>:
<Shoe_Heel_Height>:
<Fat_Bones_Arm>:
<Fat_Bones_Leg>:
<Chance>:
<Props>:
<Materials>:
<Material_Group>:
<Name>:
<Material_Chances>:
<Material_Chance>:
<Name>:
<Chance>:
<Color_Scheme_Chances>:
<Color_Scheme_Chance>:
<Name>:
<Chance>:
<Color_Values>:
<Color_Value>:
<Variable_Name>:
<Color>:
<Texture_Chances>:
<Texture_Chance>:
<Chance>:
<Texture_Entries>:
<Texture_Entry>:
<Texture_Name>:
<Texture_Filename>:
<Morph_Sets>:
<Morph_Set>:
<Name>:
<Weight>:
<Personas>:
<Persona>:
<Name>:
<Weight>:
Here you will learn about a character's Variant Table file (npc_name.xtbl).
These files allow you to customize various existing physical elements of a character, including clothing, skin, and hair colours and materials.
This .xtbl file cannot be read by the game, and will need to be converted to a .cvtf file in order to work.
This process is not covered here, but is covered in the next section of this guide.
Everything included here is translated into an easier-to-read format from the <TableDescription> found in a character's Variant Table file.
<Name>:
The internal name of the character.
This is important for converting the .xtbl file into a .cvtf file.
This will be covered in the next section.
<Variants>:
This refers collectively to all Variants listed in the .xtbl file.
<Variant>:
This refers to a single Variant in the .xtbl file.
Everything from here on out applies to a single variant.
<Name>:
This is the name of the Variant.
It is referenced by other files throughout Saints Row 2, so it is not recommended to change this at all.
<Weight>:
This is NOT the physical weight of the character!
Rather; It is the percentile chance that this Variant will spawn over other Variants listed in the same .xtbl file.
The combined total of the <Weight> value for each Variant should equal 100.
<ParkingWeight>:
Vehicles also have their own Variant Table files. <ParkingWeight> is to be used for those files.
What is the percentile chance that this Vehicle Variant will spawn over other Variants listed in the same .xtbl file in a Parking Space?
The combined total of the <ParkingWeight> value for each Variant should equal 100.
<Character_Type>:
References: character_types.xtbl
This must use a name from character_types.xtbl.
It is used for Filtering purposes by various files throughout Saints Row 2, including the character's Preset file (npc_name_pre.xtbl).
Example:
Code:
<Character_Type>beat_cop</Character_Type><Gender>:
Is this Variant Male or Female?
This is used for Filtering purposes by various files throughout Saints Row 2, including the character's Preset file (npc_name_pre.xtbl).
Options:
Male
Female
Example:
Code:
<Gender>Female</Gender><Race>:
What is the Race of this Variant?
This is used for Filtering purposes by various files throughout Saints Row 2, including the character's Preset file (npc_name_pre.xtbl).
Options:
Asian
Black
Hispanic
White
Example:
Code:
<Race>Asian</Race><Variant_IDs>:
Variant Identifiers (or VIDs) refer to numbers which represent the various pieces of the .cmesh that make up a character, vehicle, or clothing item.
For this guide, we will be focusing on NPCs.
Each NPC in Saints Row 2 is made up of multiple pieces.
Many of these pieces you will recognize as customization items you can apply to your own character in-game!
(One of the many cool things that Saints Row 2 does better than any other game.)
These range from basic human things like; Human Body, Eyes, Eyelashes, Hair, Eyebrows, and Facial Hair,
to clothing items such as; Headwear, Underwear, Undershirts, Overshirts, Coats, Pants, Socks and Shoes, Jewelry, Tattoos, etc..
Items specific to story characters also have VID numbers, such as Mr. Sunshine's severed ear, or Maero's face burn.
VID Numbers are tied to specific items within each character's Variant Table.
These VID Numbers are unique for each character. They are not universal.
ie: These VID Numbers are not the same as those found in customization_items.xtbl
For example;
Maero's Mullet has the VID number of "15" in his .cmesh.
Removing that number from the .xtbl means the game can no longer recognize that part of the .cmesh, and so won't render it.
<Vid_group>:
This is the group that the VID item(s) belongs to.
In the in-game Wardrobe for the Player Character, you'll notice there are groups of clothing items.
For example; "Undershirts" houses the "Basic T-Shirt" item.
This is the same system.
For an NPC wearing "Basic T-Shirt", it will appear under "<Vid_group><Name>undershirts</Name>".
Multiple items within the same <Vid_group> will never be worn at the same time as eachother.
<Name>:
As above. This is the name of the <Vid_group>.
<Vid_chances>:
A collection of VID items for a specific VID Group. There may be one or several of <Vid_chance> under <Vid_chances>.
<Vid_chance>:
An individual VID item.
<Description>:
What is the item this VID represents?
Example: If the NPC is wearing "Basic T-Shirt":
Code:
<Description>basic t-shirt</Description><VID_list>:
Which VID numbers are used by this item?
Without a VID number(s) to tell the game which part of the character should be rendered, the item would appear invisible.
VIDs tend to be numbered sequentially from the top of the file downwards.
It is not recommended to change these.
Example:
Code:
<VID_list>10</VID_list><Obscured_VID_List>:
Which VIDs are hidden when this item appears?
For example; If the character is wearing a t-shirt, the character's torso and shoulders would be obscured (invisible/not rendered) underneath.
Example:
Code:
<Obscured_VID_List>3</Obscured_VID_List><Shoe_Heel_Angle>:
Used for High-Heels.
When the heel is raised with <Shoe_Heel_Height>, what is the downward angle of the foot relative to the ankle?
Example: (npc_stripper_female.xtbl)
Code:
<Shoe_Heel_Angle>40.000</Shoe_Heel_Angle><Shoe_Heel_Height>:
Used for Shoes.
How high from the ground does the sole of the shoe raise the character?
Example: (npc_stripper_female.xtbl)
Code:
<Shoe_Heel_Height>0.071</Shoe_Heel_Height><Fat_Bones_Arm>:
Fat-Bones are used in Saints Row 2 to prevent clipping for fat characters using animations intended for average body types.
This adjusts the resting position of the character's arms outwards to prevent clipping with the body.
You can see the effects of Fat-Bones when you adjust the "Fatness" slider for your character in the Plastic Surgeon.
Using this will only apply the effect to the VID item it is listed under. If the item doesn't appear, neither will Fat-Bones be applied.
Example:
Code:
<Fat_Bones_Arm>5</Fat_Bones_Arm><Fat_Bones_Leg>:
Fat-Bones are used in Saints Row 2 to prevent clipping for fat characters using animations intended for average body types.
This adjusts the resting position of the character's legs outwards to prevent clipping with the thighs.
You can see the effects of Fat-Bones when you adjust the "Fatness" slider for your character in the Plastic Surgeon.
Using this will only apply the effect to the VID item it is listed under. If the item doesn't appear, neither will Fat-Bones be applied.
Example:
Code:
<Fat_Bones_Leg>5</Fat_Bones_Leg><Chance>:
What are the chances of this <Vid_chance> appearing on the NPC when spawned?
Values should total 100 when there are multiple VID items under one <Vid_group>.
If you wish to remove an item from an NPC, set this value to 0.
Example:
Code:
<Chance>100</Chance><Props>:
I have never seen these strings used, and have yet to try using them myself, so I cannot elaborate on how they work.
However, information on these strings can be found in the <TableDescription>.
<Materials>:
A collection of Materials for each of the clothing, hair, jewelry, and tattoo items a character wears.
<Material_Group>:
Contains information relating to Material properties of an item.
Here you will be able to change the colors of an item.
<Name>:
Which item is this Material Group for?
Example:
Code:
<Name>basic t-shirt</Name><Material_Chances>:
A collection of possible Material sets for the game to choose from for an individual item when spawning the character.
Only Materials already used in the NPC's .cmesh can be used.
There are some NPCs which lack Materials for certain parts (such as "Women's Platform Shoes" in "npc_stripper_female"). These were likely a developer mistakes. It means the affected part cannot be recolored. This cannot be fixed.
<Material_Chance>:
An individual set of Material properties for a specific item.
<Name>:
This must match material names associated with that item's mesh.
They are the patterns you will find on clothing items. eg: Stripes or Polka Dots.
Material names for items can be found under "<Variants>" for an item in customization_items.xtbl.
But bear in mind; The character's .peg files might not contain the textures required for the material you are trying to apply.
I do not recommend changing this setting, as any other material may require textures which do not exist for that character anyway.
Example:
Code:
<Material_chances>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Material_chance>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Name>skin_1</Name>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Chance>100.000</Chance>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Material_chance><Chance>:
As shown in the above example, controls the percentile chance of a Material being used.
If there is more than one material assigned to an item, these values should total 100.
<Color_Scheme_Chances>:
Sets of colours for this item to spawn with.
<Color_Scheme_Chance>:
A set of colours for this item to spawn with.
<Name>:
Name of the colour scheme.
<Chance>:
The percentile chance of this colour scheme spawning instead of the others for this item only.
These Values should total 100.
<Color_Values>:
The colors themselves.
<Color_Value>:
An individual colour.
<Variable_Name>:
What type of colour is this? Clothing, Hair, Tattoo, Make-Up, Skintone?
These are specific to a Material, meaning a cloth material should use clothing colours, hair should use hair colours, etc..
Options:
Skin:
Pigment_Color
Specular_Color
Hair:
Primary_Gradient_Color_A
Primary_Gradient_Color_B
Primary_Gradient_Color_C
Primary_Gradient_Color_D
Specular_Color
Secondary_Gradient_Color_A
Secondary_Gradient_Color_B
Secondary_Gradient_Color_C
Secondary_Gradient_Color_D
Clothing:
Diffuse_Color_R
Diffuse_Color_G
Diffuse_Color_B
Decal_Map_2_Color
Make-Up:
Primary_Color
Scondary_Color
These are the commonly used colors. For more information, see customization_materials.xtbl.
Example:
Code:
<Color_Value>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Variable_Name>Diffuse_Color_R</Variable_Name>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Color>Saint's Purple</Color>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Color_Value><Color>:
The colour pigment.
Depending on the item's material, this references either:
character_color_pool.xtbl
hair_color_pool.xtbl
makeup_color_pool.xtbl.
skin_color_pool.xtbl
tattoo_color_pool.xtbl
It is recommended to only use colors from the Vanilla game for compatibility with other mods.
Bear in mind; Changing colours does not always work 100% of the time. But it should work most of the time.
(This seems to be dependent on information in the character's .cmesh.)
Example:
Code:
<Color_Value>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Variable_Name>Diffuse_Color_R</Variable_Name>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] <Color>Saint's Purple</Color>[/INDENT][/INDENT][/INDENT]
[INDENT][INDENT][INDENT] </Color_Value><Texture_Chances>:
These are Logos which may be applied to an item, such as the Ultor badge on the sleeves of Masako Soldiers.
It's the same Logo system as is used when customizing your character.
This is a collection of Logo options.
<Texture_Chance>:
A single spawn chance for a number of Logos.
<Chance>:
The percentile chance of this Logo(s) spawning on the character.
These values should total 100.
<Texture_Entries>:
The Logos under this spawn chance.
<Texture_Entry>:
An individual Logo.
<Texture_Name>:
This is not the name of the Logo itself, but of it's <VariableName>.
This shouldn't ever need to be changed.
Example:
Code:
<Texture_Name>Decal_Map_2</Texture_Name><Texture_Filename>:
This is the filename of the Texture for the Logo.
This references the character's .peg files, so the name of this texture must be in those .peg files.
This is not the recommended way of changing a Logo on an NPC.
The recommended way is to edit the texture image directly (preferably upscaling x2, for preference in the game's memory) without renaming the file.
Example:
Code:
<Texture_Filename>LOG_256x128_POLICE.tga</Texture_Filename><Morph_Sets>:
A collection of preset Morphs this character can use.
Morphs are essentially what you're changing when you morph your character in the Plastic Surgeon.
NPCs were built with a similar system during SR2's development.
The names of the Morphs that can be used are dictated by the character's .morph file (which cannot be edited).
Therefore, typically, all the character's Morphs are already listed and in use by the character's .xtbl file, and shouldn't need to be changed.
However, there's no harm in editing the chances of these morphs spawning.
<Morph_Set>:
An individual Morph.
<Name>:
The name of the Morph. This string refers to the character's .morph file.
Therefore, only names in that file (which can't be accessed) can be used.
It should be noted that for Cutscene Characters (SNPC) used in Cutscenes, the Morphs are chosen by the Cutscene's file itself.
This means switching Characters in a Cutscene can be complicated, as the Cutscene file would also have to be changed to assign the correct Morph to the Character.
A similar issue is present in regards to Missions which spawn specific characters with specific meshes.
In the event that the game cannot determine which Morph should be used, it will use a "Neutral" Morph,
which makes male characters look feminine, and female characters look masculine.
Example: (npc_cop.xtbl)
Code:
<Name>asian/hispanic male average</Name><Weight>:
The percentile chance of this Morph spawning instead of the others listed.
Values for all Morphs for a Variant should total 100.
<Personas>:
A collection of Persona options for the character.
Personas are the character's gameplay voice. They also decide which radio station the character listens to when spawned driving a car.
<Persona>:
An individual Persona.
<Name>:
The name of the Persona. This references persona.xtbl.
The names in persona.xtbl are structured like this: (Race/Gender/Character) "WM_COP" (White Male Cop)
Special characters instead have the SP prefix: "SP_GAT"
Example:
Code:
<Name>WM_COP</Name><Weight>:
The percentile chance of this Persona being used instead of the others.
Values for all Personas for a Variant should total 100.
7. HOW TO USE VOLITION'S NPC TABLE FILE CRUNCHER
Volition's "NPC Table File Cruncher" is part of "Shaundi's Secret Stash" available from Volition's GitHub.
It converts a character's XML Variant Table (.xtbl) (cannot be read by the game) into a "Customization Variation Table File" (.cvtf) (can be read by the game).
How to use Volition's NPC Table Cruncher:
If the new .cvtf does not appear, there is an error in the .xtbl file.
Go back and check that the <Name> at the top of the file is correct, then check back through what you changed for any mistakes.
Once you have your new .cvtf, install it to your patch.vpp_pc as you would any other mod.
Since the game will not read the .xtbl, you do not need to install it to your game.
Volition's "NPC Table File Cruncher" is part of "Shaundi's Secret Stash" available from Volition's GitHub.
It converts a character's XML Variant Table (.xtbl) (cannot be read by the game) into a "Customization Variation Table File" (.cvtf) (can be read by the game).
How to use Volition's NPC Table Cruncher:
Step 1.
Edit the .xtbl file of any character however you wish.
The name at the top of the file must match the name of the .cvtf you wish to produce from the .xtbl.
Step 2.
COPY and PASTE your edited .xtbl into the "tables" folder.
Open "Run SR2 NPC Table Crunch.bat" with a text editor (Notepad).
Make sure "output_name" is followed by the name of the .cvtf you wish to produce. (Again, this must match the name at the top of the .xtbl file.)
Make sure "variant_table" is followed by "tables\" and the name of the .xtbl you copied into the "tables" folder.
Example:
npc_maero.xtbl has "<name>npc_maero</name>" at the top of the file.
The contents of "Run SR2 NPC Table Crunch.bat" should look like this:
Code:
"sr2_npc_table_crunch.exe -output_name npc_maero.cvtf -variant_table tables\npc_maero.xtbl"Step 3.
SAVE "Run SR2 NPC Table Crunch.bat".
RUN "Run SR2 NPC Table Crunch.bat".
You new .cvtf should appear in the same folder as "Run SR2 NPC Table Crunch.bat".
If the new .cvtf does not appear, there is an error in the .xtbl file.
Go back and check that the <Name> at the top of the file is correct, then check back through what you changed for any mistakes.
Once you have your new .cvtf, install it to your patch.vpp_pc as you would any other mod.
Since the game will not read the .xtbl, you do not need to install it to your game.
8. TEXTURE EDITING
Texture editing is, of course, applicable to more than just human characters. But for characters,
you could be forgiven for thinking editing the texture for an individual clothing item would also change it for an NPC.
This is both true and false.
Every NPC contains a duplicate of the textures for the clothing items they are wearing.
For example; Changing the texture of Tobias' Pants would only change it for the version of Tobias' Pants you can select for your character (GotR).
For the change to apply to Tobias, you would need to edit the same texture in npc_Tobias's .peg files.
Bear in mind; The game can only load one instance of a texture of the same name at one time, and will prefer larger scale textures.
For this reason, I always recommend upscaling modified textures at least once if possible.
".peg" and ".g_peg" files contain textures, normal maps and specular maps for a mesh of the same filename.
eg: npc_Tobias.cmesh uses textures from npc_Tobias.peg and npc_Tobias.g_peg. (The "g" in ".g_peg" stands for geometry.)
To extract textures from these files, you need sr2PegTool (Credit: Masamaru).
(Instructions on how to use this are included with the download.)
Texture editing is, of course, applicable to more than just human characters. But for characters,
you could be forgiven for thinking editing the texture for an individual clothing item would also change it for an NPC.
This is both true and false.
Every NPC contains a duplicate of the textures for the clothing items they are wearing.
For example; Changing the texture of Tobias' Pants would only change it for the version of Tobias' Pants you can select for your character (GotR).
For the change to apply to Tobias, you would need to edit the same texture in npc_Tobias's .peg files.
Bear in mind; The game can only load one instance of a texture of the same name at one time, and will prefer larger scale textures.
For this reason, I always recommend upscaling modified textures at least once if possible.
".peg" and ".g_peg" files contain textures, normal maps and specular maps for a mesh of the same filename.
eg: npc_Tobias.cmesh uses textures from npc_Tobias.peg and npc_Tobias.g_peg. (The "g" in ".g_peg" stands for geometry.)
To extract textures from these files, you need sr2PegTool (Credit: Masamaru).
(Instructions on how to use this are included with the download.)
I am open to suggestions on how this guide can be improved. There are things here and there I'm not entirely certain on (like <MetaGame>). If you feel you can contribute, then feel free to let me know below in this thread.
"NPC Cruncher Stuff" contains the "tables" folder and "Run SR2 NPC Table Crunch.bat" required to use Volition's NPC Table Cruncher. Place both in the same location as "sr2_npc_table_crunch.exe".
Resources:
"Shaundi's Secret Stash - NPC Table Cruncher" by Volition
"SR2PegTool" by Masamaru - For extracting/repacking textures from .peg_pc files.
"Editing .sim_pc files." by Moff - I've no experience with Blender, but this might be useful for those who do. Bear in mind, this was made for SR4, and might not work for SR2's .sim_pc files.
Last edited:
