[Modding] RTW: Guide for Traits/Ancillaries

[jimkatalanos]

Author: Squid
Original Thread: Guide: The complete traits/ancillaries guide

Guide: The complete traits/ancillaries guide

Title: The Complete EDCT/EDA Guide for RTW (inc. BI)
Posted by: Squid
Modding area: Characters (traits, ancillaries)
Required programmes: Notepad (or other text editor)
Recommended programs: ATVTW (trait/ancillary validtor)
Summary: An in-depth explanation of the export_descr_character_traits, export_descr_ancillaries files, which is the primary base for all traits and ancillaries in the game.

The Complete EDCT/EDA Guide for Rome: Total War:


Understanding & Coding Export_Descr_Character_Traits.Txt (EDCT) and Export_Descr_Ancillaries (EDA) files

by Squid

THIS IS A WORK IN PROGRESS AND WILL UPDATED AS NEEDED

Last update: 02/11/2008

CONTENTS

• Introduction
• EDCT Breakdown
• EDA Breakdown

Introduction:

This post is a reproduction of the article I originally posted at the org. The original article is located here and in case of discrepency, the original article should be taken as the definitive version.

When I started to work for the Roma Surrectum team on the traits and ancillaries files, I went to all the resources both here at totalwar.org, and at twcenter.net, and sadly found them incomplete, not giving complete details on what could be done within the files. I found this disappointing as traits and ancillaries can add a huge amount of depth to any mod and yet without a more complete resource available every modder who tries their hand at the traits and ancillaries has no complete resource to refer to. I'm hoping that with this guide I can fill in many of the gaps that the current information available has. As you read through this guide you will notice Bug Alert, and CTD Alert starting paragraphs at various points, these paragraphs are there to bring two kinds of issues to a modders attention, Bug Alert highlights areas where the game engine allows certain things to go through but that actually cause problems in the game or cause things not to work as expected. CTD Alert highlights CTDs that I've bumped into. For each CTD Alert, where the solution isn't obvious I've listed the solution if I've found it.

Comments in EDCT/EDA

In both files a line with comment on it must begin with a ; (semi-colon)

EDCT Breakdown

EDCT contains all the information about traits and how they can be acquired. The file is split into 2 sections. The first section is the Trait Section, this section contains the information about the individual traits, including which characters types can acquire a trait, which cultures are precluded from acquiring a trait, if the trait can be seen, which traits are mutually exclusive (i.e. both traits can't be had on the same character), what effects the trait has at its various levels, as well it lists which text entries from the related export_VnVs.txt file are to be used when displaying the trait.

Some of the lines are optional lines and aren't present in every trait, those optional lines will have OPTIONAL at the beginning of the description of what the lines do.

Each trait is broken into two distict sections the header section, and the levels section. First we'll go through the header section.

Trait Header:

Sample Trait Header:

Trait Trait_Name
    Characters Character_Type
    Hidden
    ExcludeCultures Excluded_Culture(s)
    NoGoingBackLevel  No_Going_Back_Level
    AntiTraits Anti_Trait(s)

So let's examine the Trait Header line by line:

Trait Trait_Name

This is the name of the trait, it must be unique, no two traits can share the same name. The name of the trait can be used in the AntiTraits line below, in an Affects line in the trigger section, or as part of a condition for a trigger in either EDCT or EDA, the one other place where Trait_Name will be used is in descr_stat.txt to specifiy the starting traits for the various characters.

    Characters Character_Type(s)

This line specifies which character type(s) are able to acquire a trait. The current character types are: spy, assassin, diplomat, admiral, family and all. The current docudemon files show general and named character as additional character types, but I haven't tested these or seen them in an existing trait.

Note: Recruited generals are considered the family character type and can acquire traits limited to family members.

Bug Alert: Although the game engine allows you to specifiy a comma seperated list of character types only the first character type from your list will be able to acquire the trait. There are two workarounds for this bug, one is to create additional traits for each character type that you want to acquire this trait, the second it to use character type all and use the triggers to limit which characters can acquire the trait. I prefer the second method but both will work.

CTD Alert: If the second line of the trait is not the Characters line you will get the following CTD.

Script Error in data/export_descr_character_traits.txt, at line X, column Y

Unknown identifier for trait(Trait_Name) level (Trait_Name) when expecting characters.

    Hidden

Optional, this line is added when you don't want the trait to be listed on the character information screen (i.e. recruitment screen, right-click character portrait, etc).

    ExcludeCultures Excluded_Culture(s)

Optional, this line is added when you want to exclude certain culture group(s) from being able to acquire a trait. The cultures on the list should be taken from the descr_sm_cultures.txt file. If listing more than one culture they must be listed as a comma seperated list of cultures.

    NoGoingBackLevel  No_Going_Back_Level

Optional, the line NoGoingBackLevel No_Going_Back_Level means that once you hit the level No_Going_Back_Level, you can only gain points for the trait, points towards any antitraits will no longer reduce your points for the trait.

NoGoingBackLevel should be used whenever a trait has an antitrait and you expect the trait to actually acquire points of its own and not just reduce the points of its' AntiTraits, see the bug alert below for details. In other words if you have trait that is an antitrait to second trait for the purpose of reducing the second trait to 0 points then a NoGoingBackLevel is not needed.

Example: If you have a trait A with an antitrait B and A has a NoGoingBackLevel of 2, then once you get enough points to get the second level of trait A, points you acquire towards trait B will no longer reduce your points in trait A, but any points you get towards trait A will continue to accumulate.

Bug Alert:There is a nasty bug with AntiTraits, I'd explain it, but Player1's explanation is much better, so I'm just going to quote it from his BUG-FIXER:

AntiTraits Anti_Trait(s)

Optional, this list should include those traits where it doesn't make sense for one character to have both traits (e.g. Pious & Atheist should be antitraits because it doesn't make sense for someone to be both Pious & Atheist). There is a hard-coded limit of 10 antitraits(1.2)/20(1.5/1.6). Listing too many antitraits will cause a CTD.

Note: Although not a hard and fast rule, your antitraits should go both ways, so using the example above Pious should have Atheist as an antitrait and Atheist should have Pious as an antitrait.

Bug Alert: The game engine does not check for the validity of your anti-traits list, so an undefined or misspelt antitrait will still let the game load. Misspelt traits will obviously cause problems as both traits can be acquired by one character. I do not know if undefined trait in the antitraits list causes any issues.

CTD Alert: One CTD in the header that gave me fits trying to solve was that I'd inadvertantly misordered the lines in the header section. I got the following error from -show_err:

Script Error in data/export_descr_character_traits.txt, at line X, column Y

Trait not recognized

The line the error was refering to, was the first instance where I had a condition of the form Trait ABC = # or FatherTrait ABC = # in either EDCT or EDA. What misordering the lines had done was to make the engine not recognize any trait that came after the trait with the misordered lines even though it parsed them without any error. The not recognized trait may even have been in an Affects line before the line in question but that wouldn't get caught.

Trait Level:

All traits will have between 0 and 9 levels. 9 levels is a hardcoded limit. Although I haven't tried to have a trait without the Hidden line have 0 levels, a trait with the Hidden line is not required to have any levels.

Note: Any trait without a level might as well be hidden since it won't ever be acquired and the only use they have is to make other traits go back to 0 points.

If you look at the following image, you'll see how some of the trait information actually looks in game:



If some of this doesn't yet make sense, keep reading and I'll fill in the details as I go along.

Sample Trait Level:

 
    Level Level_Name
        Description Level_Description
        EffectsDescription Level_Effects_Description
        GainMessage Level_Gain_Message
        LoseMessage Level_Lose_Message
        Epithet Level_Epithet_Description
        Threshold Trait_Points

Effect Attribute Attribute_Points

File Linkage: For each of the lines up to (but not including) Threshold, you will have to have a corresponding line in the export_VnVs.txt file of the form:

{Level_Name}<tab>Displayed Level Name
or
{Level_Description}
Description of the Level

Typically Level_Name & Epithet follow the first format, while the other four follow the second format.

CTD Alert: For any of Level_Name, Level_Description, Level_Effects_Description, Level_Epithet_Description if the corresponding entry in export_VnVs.txt does not exist (or is misspelt), then if a character acquires the trait with a missing/incorrect entry a CTD will occur if you try and view the character details screen (i.e. right-click on character portrait, open recruitment window, etc).

Note: If you look at the sample trait level none of the lines from Level to Epithet need to be unique. This means that multiple levels in the same trait, or levels in different traits can have the same values for any or all of those lines. This is a great way to cut down on the size your export_VnVs.txt file.

So let's examine a Trait Level line by line:

    Level Level_Name

This is the line that you see in the trait window (when you right-click on a character portrait, open the recruitment screen, etc).

         Description Level_Description

This is the line that provides the description of this level of the trait. It is visible in the trait window when you mouse over the Level_Name on a character's trait screen.

EffectsDescription Level_Effects

This is the line that provides the list of effect that this level of the trait provides. It is visible in the trait window when you mouse over the Level_Name on a character's trait screen.

        GainMessage Level_Gain_Message

Optional, if the GainMessage line is included with the level of a trait, then when a character acquires that level an event message will appear with the text from this message.

         LoseMessage Level_Lose_Message

Optional, if the LoseMessage line is included with the level of a trait, then when a character has reached a level of trait with a LoseMessage line, and the character acquires enough points in an antitrait that it reduces the number of points they have in the trait below the Threshold value, then an event message will appear with the text from this message.

Note:

• If you have a gain/lose message for a level of a hidden trait, the event message will still be displayed even though the trait remains hidden. All appropriate VnV entries need to exist.

         Epithet Level_Epithet_Description

Optional, if the Epithet line is included with the level of a trait, then when the character acquires the level of the trait with the Epithet line that characters name will change to be their first name plus the contents of the Epithet line message.

Threshold  Trait_Points

The value given for trait points, is the number of points a character needs to accumulate in order to acquire that particular level of trait. The hardcoded minimum threshold value is 1.

Effect Attribute Attribute_Points

Optional, Each trait can have zero or more Effect lines. Each Effect line
can have a positive or negative effect on the associated attribute.

The list of known attributes is:

• MovementPoints
• Command
• Loyalty
• TroopMorale
• Influence
• Management
• Fertility
• PersonalSecurity
• PublicSecurity
• Negotiation
• Subterfuge
• HitPoints
• Attack
• Defence
• Ambush
• Law
• SiegeAttack
• SiegeDefence
• Unrest
• Construction
• LineOfSight
• Trading
• Squalor
• BribeResistance
• Bribery
• TrainingAgents
• Farming
• Mining
• SiegeEngineering
• NightBattle
• NavalCommand
• InfantryCommand
• CavalryCommand
• Combat_V_Roman
• Combat_V_Greek
• Combat_V_Slave
• Combat_V_Carthaginian
• Combat_V_Eastern
• Combat_V_Barbarian
• Combat_V_Egyptian
• Combat_V_Nomad
• Combat_V_Hun
• TaxCollection
• PopularStanding
• SenateStanding
• LocalPopularity
• Electability
• Looting
• TrainingAnimalUnits
• BodyguardValour
• BattleSurgery
• TrainingUnits
• SlaveTrading
• Health
• GrainTrading

Notes:

• Not all of the attributes listed above are usable in both RTW and BI, at least without some modification of the game files.
• Even if a level does not have an effect, it still needs an EffectsDescription line. The corresponding line in export_VnVs.txt file can be blank.
• Combat_V_faction_name is not a valid attribute
• Combat_V_culture_name does not support gaining negative points in a trigger

Trigger Section:

The trigger section is read sequentially by the game engine, meaning that triggers earlier in the trigger section will trigger before those that appear later.

The file BI_docs.zip contains much of the information that will be required for use in the triggers, it contains a list of all events and conditions that are available in the game as of 1.5/1.6 patch. Not all the information included is accurate and where known I will point out events and conditions that don't work.

Sample Trigger:

Trigger Trigger_Name
    WhenToTest Event_Name

    Condition Condition_1
           and Condition_2

    Affects Trait_Name Trait_Points_Assigned  Chance  Percentage

Trigger Trigger_Name

This is the name of the trigger, no two triggers can share the same name.

CTD Alert: If two triggers share the same name, when one of the triggers is triggered by the game, an errorless CTD will result.

WhenToTest Event_Name

The Event_Name indicates when the trigger should be tested. The list of possible events are located in the docudemon_events.txt file. Not all events listed in this file can be used in EDCT/EDA. An examination of the events used in EDCT/EDA seems to indicate that the usable events are those for which in the Exports line lists character_record or nc_character_record.

Non-Functional Events: The following is a list of events which, while exporting the correct record, do not work or do not work as expected for traits:

Condition Condition_1
           and Condition_2 

Optional, the condition(s) that can be used to limit when the Affects of the trigger are implemented. Every condition in the condition list must be met in order for the Affects line(s) to kick in. The list of conditions are located in the docudemon_conditions.txt file. Not all conditions can be used with all events. A condition can be used with an event if the Trigger requirements line for the condition is listed on the Exports line of the Event_Name in the docudemon_events.txt file.

Notes:

• If there are no conditions for a trigger the Affects line(s) will always be implemented.
• Affects accepts negative points for traits

• An invalid condition will always evaluate to true.

Non-Functional Conditions: The following is a list of conditions which, while do not work or do not work as expected for traits:


CTD Alert: Certain conditions make reference to items defined in other files, such as EDB, sm_cultures, etc. Some of these conditions will produce CTDs if the items are undefined in the external files. Here are the CTDs that can be produced:

Undefined/Incorrect Building Name:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
 
Building level name building_level_name not found in building database

Undefined/Incorrect Culture:

Script Error in data/export_descr_character_traits.txt, at line X, column Y  

culture type not recognized

Undefined/Incorrect Faction:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
   
faction type not recognized

Undefined/Incorrect Character Type:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
  
character type not recognized

Affects Trait_Name Trait_Points_Assigned  Chance  Percentage

Each trigger must have one or more Affects lines. The Trait_Name will be given Trait_Points_Assigned towards reaching the Threshold of the next level of the trait Percentage of the time. Percentage is always a whole number (i.e. no decimals, no fractions, etc) between 1 and 100.

Example: Affect Trait_Name 5 Chance 50 will increase Trait_Name (or decrease it's AntiTraits) by 5 points 50% of the time.

CTD Alert: Using an undefined trait in either the Affects line(s) or the Condition section will result in the following CTD:

Script Error in data/export_descr_character_traits.txt, at line X, column Y

Trait not recognized

EDA Breakdown

The EDA contains all information regarding the ancillaries, or retinue members as they are refered to ingame. This file is split into two distinct sections, the Ancillary section, and the trigger section. The ancillary section contains all the information about the ancillaries, their names, which picture to use to represent them, which cultures cannot acquire an ancillary as well as the description and effects associated with an ancillary, as well it lists which entries from the related export_ancillaries.txt file are to be used when displaying the ancillary.

Ancillary Section

Sample Ancillary:

Ancillary ancillary_name
    Image ancillary_image.tga
    Unique
    ExcludedAncillaries ancillary_name(s)
    ExcludeCultures excluded_culture(s)
    Description ancillary_description
    EffectsDescription ancillary_effects_description
    Effect Attribute Attribute_points 

File Linkage: For each of ancillary_name, ancillary_description and ancillary_effects_description, you will have to have a corresponding line in the export_ancillaries.txt file of the form:

{ancillary_name}<tab>Displayed Ancillary Name
or
{ancillary_description}
Description of the Level

Typically ancillary_name follows the first format, while ancillary_description,ancillary_effects_description follow the second format.

Note: Neither ancillary_description norancillary_effects_description are required to be unique entries in export_ancillaries.txt; however, ancillary_name is required to be unique as the name of the ancillary must be unique.

CTD Alert: For any of ancillary_name, ancillary_description and ancillary_effects_description, if the corresponding entry in export_ancillaries.txt does not exist (or is misspelt), then upon acquiring the ancillary, or trying to view the character screen of a character with an ancillary with a missing/incorrect entry an errorless CTD will occur.

So let's examine an ancillary line by line:

Ancillary ancillary_name

This is the name of the ancillary, ancillary_name must be unique. No two ancillaries can have the same value for ancillary_name. The name of the ancillary can be used in the ExcludedAncillaries line below, in the trigger section of EDA on the AcquireAncillary line, or in the conditions section of a trigger. The one other place you will use ancillary_name is in descr_stat.txt to give an ancillary to a character that starts on the campaign map.

Image ancillary_image.tga

This line specifies the image file to be used on the character screen. By default the ancillary images are located data/ui/ancillaries, the contents of this folder are in a pak file by default.

Unique

Optional, this line is used to specify that a particular ancillary is unique, in other words the ancillary can only ever be acquired once.

ExcludedAncillaries ancillary_name(s)

Optional, this line gives the list of ancillaries that prevent the given ancillary from being acquired. So if an ancillary A has ancillary B on it's ExcludedAncillaries list then if a character has ancillary B they cannot get ancillary A. The list of ExcludedAncillaries is a comma seperated list

Notes:

• For any ancillary that has the Unique line, it seems to require that the ancillary list itself on the ExcludedAncillaries list

CTD Alert: There is a hardcoded limit of 3 ExcludedAncillaries. If more than 3 are listed an errorless CTD is produced.

ExcludeCultures excluded_culture(s)

Optional, this line is added when you want to exclude certain culture group(s) from being able to acquire a trait. The cultures on the list should be taken from the descr_sm_cultures.txt file. If listing more than one culture they must be listed as a comma seperated list of cultures.

Description ancillary_description

This is the line that provides the description of the ancillary. It is visible in the character info window when you mouse over the Ancillary_Name.

EffectsDescription ancillary_effects_description

This is the line that provides the list of effect that the ancillary provides. It is visible in the character info window when you mouse over the Ancillary_Name.

Effect Attribute Attribute_points 

Optional, Each ancillary can have zero or more Effect lines. Each Effect line can have a positive or negative effect on the associated attribute.

The list of known attributes is:

• MovementPoints
• Command
• Loyalty
• TroopMorale
• Influence
• Management
• Fertility
• PersonalSecurity
• PublicSecurity
• Negotiation
• Subterfuge
• HitPoints
• Attack
• Defence
• Ambush
• Law
• SiegeAttack
• SiegeDefence
• Unrest
• Construction
• LineOfSight
• Trading
• Squalor
• BribeResistance
• Bribery
• TrainingAgents
• Farming
• Mining
• SiegeEngineering
• NightBattle
• NavalCommand
• InfantryCommand
• CavalryCommand
• Combat_V_Roman
• Combat_V_Greek
• Combat_V_Slave
• Combat_V_Carthaginian
• Combat_V_Eastern
• Combat_V_Barbarian
• Combat_V_Egyptian
• Combat_V_Nomad
• Combat_V_Hun
• TaxCollection
• PopularStanding
• SenateStanding
• LocalPopularity
• Electability
• Looting
• TrainingAnimalUnits
• BodyguardValour
• BattleSurgery
• TrainingUnits
• SlaveTrading
• Health
• GrainTrading

Notes:

• Not all of the attributes listed above are usable in both RTW and BI, at least without some modification of the game files.
• Even if an ancillary does not have an effect, it still needs an EffectsDescription line. The corresponding line in export_ancillaries.txt file can be blank.
• Combat_V_faction_name is not a valid attribute
• Combat_V_culture_name does not support gaining negative points in a trigger

EDA Trigger Section:

The EDA triggers are mostly like their counterparts in EDCT but there are a few key differences.

Sample Trigger:

Trigger Trigger_Name
    WhenToTest Event_Name

    Condition Condition_1
           and Condition_2

    Affects Trait_Name Trait_Points_Assigned  Chance  Percentage
    AcquireAncillary ancillary_name  Chance  Percentage 
 

Trigger Trigger_Name
 

This is the name of the trigger, no two triggers can share the same name.

CTD Alert: If two triggers share the same name, when one of the triggers is triggered by the game, an errorless CTD will result.

WhenToTest Event_Name
 

The Event_Name indicates when the trigger should be tested. The list of possible events are located in the docudemon_events.txt file. Not all events listed in this file can be used in EDCT/EDA. An examination of the events used in EDCT/EDA seems to indicate that the usable events are those for which in the Exports line lists character_record or nc_character_record.

Non-Functional Events: The following is a list of events which, while exporting the correct record, do not work or do not work as expected for traits:

• PreBattle
• CharacterMarries
• OfferedForMarriage - works in EDCT

Condition Condition_1
            and Condition_2 
 

Optional, the condition(s) that can be used to limit when the Affects of the trigger are implemented. Every condition in the condition list must be met in order for the Affects line(s) to kick in. The list of conditions are located in the docudemon_conditions.txt file. Not all conditions can be used with all events. A condition can be used with an event if the Trigger requirements line for the condition is listed on the Exports line of the Event_Name in the docudemon_events.txt file.

Notes:

• If there are no conditions for a trigger the Affects/AcquireAncillary line(s) will always be implemented.
• Affects accepts negative points for traits

• An invalid condition will always evaluate to true.

Non-Functional Conditions: The following is a list of conditions which, while do not work or do not work as expected for traits:

• NumEnemiesInBattle - may cause a CTD with PostBattle event in reinforcement battles

CTD Alert: Certain conditions make reference to items defined in other files, such as EDB, sm_cultures, etc. Some of these conditions will produce CTDs if the items are undefined in the external files. Here are the CTDs that can be produced:

Undefined/Incorrect Building Name:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
 
Building level name building_level_name not found in building database
 

Undefined/Incorrect Culture:

Script Error in data/export_descr_character_traits.txt, at line X, column Y  

culture type not recognized
 

Undefined/Incorrect Faction:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
   
faction type not recognized
 

Undefined/Incorrect Character Type:

Script Error in data/export_descr_character_traits.txt, at line X, column Y
  
character type not recognized
 

Affects Trait_Name Trait_Points_Assigned  Chance  Percentage
     AcquireAncillary ancillary_name  Chance  Percentage 
 

Each EDA trigger must have one or more Affects and/or AcquireAncillary lines. The ancillary_name ancillary will be acquired Percentage of the time. For how an affects line works see the trait version of the trigger section.

Example: AcquireAncillary ancillary_name Chance 50 will acquire the ancillary ancillary_name 50% of the time.

CTD Alert: Using an undefined Ancillary in either the AcquireAncillary line(s) or the Condition section will result in the following CTD:

Script Error in data/export_descr_ancillaries.txt, at line X, column Y

Ancillary not recognized

Notes:

• You can't trigger a trait directly from what ancillary a general has, but you can give ancillaries for generals a NavalCommand bonus that doesn't show up, and use that attribute level as a trigger condition in the trait file. (from Makanyane)
• If you have a mixed trigger (i.e. both affects and acquireancillary are present), then the affects lines must come before the acquireancillary lines or the traits are not assigned even with a chance of 100.