Modding Guide for VP 4.0+ (COMPLETE, v1.0)

[azum4roll]

Important Note: this isn't a guide for modmodding, though modmodders may still find it worth by reading this.

We have recently completed The Merge, which completed the work of integrating C4DF, CSD, More Luxuries, and various modular elements like Corporations into the main VP folders.
Files were reorganized into correct folders and renamed to clear and precise names.
Almost all SQL and XML have been rewritten. This also dug up various long-hidden bugs and allowed them to be fixed.
Most unused game components (not in base game) have been removed.

Note that other than moving Events from (1) to (2), the (1) Community Patch folder is mostly untouched, so that can continue to act as a base for other mods.

In this post, base game always refers to Civilization V with the Brave New World expansion and all DLCs.

---

Overview​

There are only 5 main folders left in (2) Vox Populi.

Assets:
All art assets are put here.
File extensions: dds, dge, fsmxml, ftsxml, fxsxml, ggxml, gr2
All of them are imported into VFS.
Since I didn't check the contents of these files, they're only vaguely sorted into folders, and there can be potentially unused assets.

Core Files:
Non-database, non-asset files.
File extensions: lua, xml
- Core Changes: Contains non-database (not starting with <GameData>) xml. Need to follow base game file names and imported into VFS to work. Currently has only farm_types.xml, which handles farm graphics.
- New Lua: Contains new functions that trigger on game events. These should be kept at a minimum. Each has a InGameUIAddin entry in <ModContent>.
- New UI: Contains new UI components that are not present in the base game. Each has a InGameUIAddin entry in <ModContent>.
- Overrides: Contains UI and event triggers that are already present in the base game. Need to follow base game file names and imported into VFS to work.

LUA:
Base game UI components. Unlike the Overrides folder in Core Files, this folder is for non-EUI only, and is not installed if the EUI option is selected in the installer.
The equivalent EUI folder is (3a) Compatibility Files/LUA.
All of them have the same names as base game files and are imported into VFS.

Mapscripts:
Contains Communitu_79a map and other base game maps that have to be edited to keep compatible with VP. All are imported into VFS and have a MapScript entry in <ModContent>.
EMP folder: identical to the Explorer's Map Pack DLC. VP unloads the DLC in order to get the difficulty blurbs to update. This folder adds it back. Never modify its contents.

Database Changes:
The main content of the Merge project. Contains ALL and ONLY files that modify the database. All of them have an UpdateDatabase entry in <ModActions>.
As many bulk inserts, updates and deletes are used, the order in <ModActions> and where you put each SQL statement matters a lot. More on that in later sections.

---

Main Tables​

Before we dig deeper, I need to explain main tables.
Main tables are database tables that have a unique "Type" column, and usually also has an "ID" column. Each row in main tables represents a game component, whether a building (Buildings), an AI military strategy (AIMilitaryStrategies), or a game option (GameOptions).
The types are commonly referenced in other main or non-main tables. If a reference is not met, i.e. the referenced type doesn't exist in the corresponding main table, at the end of mod loading, the line "Failed Validation" will show up on Database.log, which signals some errors in the SQL/XML.
Other, non-main, tables define interactions between game components. For example, the Policy_BuildingClassYieldChanges table defines which building class gets which yield type, and how much of it, if you have a certain policy.

Main tables usually have numerous columns, but most have default values of 0, false or null and don't have to be set. This makes XML more suitable for adding game components, as using mass SQL insert would have extremely long and unreadable rows filled with default values. However, it's also not ideal to insert every column of a row using XML, only the ones that are 1) text keys, or 2) not inter-related (e.g. PrereqTech, MoveRate), or 3) component-defining (e.g. IconAtlas, SpecialCargo). Any column that is easily bulk updated should be done using SQL.

Non-main tables have few columns and usually can be bulk inserted/updated/deleted via use of temp tables and where conditions, so SQL is always more suitable for changing them.

---

File Name Conventions and Load Order​

File names in the Database Changes folder mostly follow these patterns (in load order):
- CommunityOptions.sql: Community table values. Game options for the less-technical people who still know how to open a file. Always loads first.

---

- New<plural>.xml: inserts new main table entries.
- CustomModOptionChanges.sql, DefineChanges.sql, GameOptionChanges.sql, GameSpeedChanges.sql, WorldChanges.sql:

These are foundational values for the mod, and should always go before other changes.​

---

- Pre<singular>Changes.sql: bulk deletions or updates that need to be done before individual updates, e.g. categorizing resources or promotions.

---

- <singular>Changes.sql: individual updates of rows or columns of main tables, and insertions of non-main table entries that are related to the main table.

Tradition.sql etc. also belong to this category.​

- <Civilization>.sql: updates Civilization UA, UU, and UB/UI. Any pseudo unique components like Ordo, Mission and West Point also belong here.

Needs to be loaded after all UnitChanges and BuildingChanges files.​

- BarbarianUnitChanges.sql, CityStateUnitChanges.sql, PolicyUnitChanges.sql: updates barbarian, CS and policy exclusive units. CS and policy units are also given their exclusive unit class here.

Needs to be loaded after all UnitChanges files.​

---

- <singular>Sweeps.sql: bulk deletions, insertions or updates of main table columns or non-main table entries.

As one bulk insert statement is faster than many individual update statements, non-main tables are commonly deleted (either in here or in the PreChanges file) and re-inserted. This also makes referring to base game values unnecessary for modders.​

Some main table columns are highly inter-related or follow a pattern, like unit costs and building capture chance. These are suitable for bulk updates, usually done by first assigning a default value to all rows, then updating with conditions.​

Both Changes.sql and Sweeps.sql can do bulk updates, and sometimes the line between them is muddied. Just bear in mind that Sweeps.sql is always loaded after ALL Changes.sql files. This is particularly important for Buildings and Units.​

---

- New<singular>Text.xml: inserts new text entries. Only Language_en_US table allowed. Other tables don't belong to the Text folder, which is used for localization only.

XML is used instead of SQL since quotes are common and don't have to be escaped. However, there are still two SQL files (NewUnitText.sql and NewUIText.sql) inserting short text.​

---

- <singular>TextChanges.sql: updates existing base game text entries, or those added in (1). Only Language_en_US table updates allowed. Move your unit text key updates elsewhere.

SQL is used for text changes instead of XML since the <Update> tag seems to fail to handle single quotes and still requires escaping double quotes.​

---

- Remapper.sql: the deletions of main table entries and the complete replacement of the UnitPromotions table leave many gaps in ID values, which would crash the game when loaded. This magical file re-inserts every affected main table to have their ID start at 0 without any gaps.

---

- Triggers.sql: VP doesn't use triggers for itself, but has some to save work for modmodders. This file always loads last and must not contain any statements other than CREATE TRIGGER.

 

[azum4roll]

Small modders can skip to Post #3 and only use this post as a reference when making changes. Modders that frequently make changes should read this post carefully.​

---

Digging deeper through Database Changes​

DefineChanges.sql​

What used to be called CoreDefines.sql. Almost all changes to the Defines table have been moved here, and roughly categorized. I've also put comments on most Defines to explain what they do.
Some Defines changes are put in MinorQuestChanges.sql and MinorYieldChanges.sql since they really, really should be in separate tables.
(@Recursive, mind working on that? )

AI​

Contains changes to all flavor tables, all strategy tables, Diplomacy_Responses, Leader tables, and the DiploEmphasisReligion and DiploEmphasisLatePolicies columns of the Eras table.
All of these changes affect only the AI and nothing else.

Art​

Not to be confused with Assets, this contains database changes to:

• ArtDefine_Landmarks
• ArtDefine_LandmarkTypes
• ArtDefine_StrategicView
• ArtDefine_UnitInfos
• ArtDefine_UnitMemberInfos
• ArtDefine_UnitMemberCombats
• ArtDefine_UnitMemberCombatWeapons
• ArtDefine_UnitInfoMemberInfos
• IconTextureAtlases
• IconFontTextures
• IconFontMapping

These define the Resources, Improvements, and Units models, icons, size scaling, as well as Unit formations, movement animations and attack animations, and font icons.
Ask the art guys for more details; I merely rewrote all of these while guessing how these work.

Barbarians​

Barbarian, like all players, has a defined Leader and Civilization.
LEADER_BARBARIAN changes are in LeaderFlavorSweeps.sql in the AI folder as it's only in the Leader_Flavors table.
CIVILIZATION_BARBARIAN changes are in BarbarianSweeps.sql. These include sweeping the list of units and buildings that barbarians cannot spawn/build, and changing their art style to look like Russians for some reason.
In addition, the SpawnLocationUnitFreePromotion column in Terrains and Features tables are changed here, giving promotions to barbarians spawned.
Lastly, Improvement_ValidTerrains is changed here to allow Barbarian Encampment to spawn on Snow.

Beliefs​

Pantheons, Founders, Followers, Enhancers and Reformations have separate Changes.sql files here.
The Tooltip column in Beliefs table is swept separately. It's almost always the same as the Description, except in the Follower beliefs that unlock a building, where it lists the yields of the building and the building's Help text.

City​

Building, Process, Project, Specialist and Great Work changes belong here. I'm saving Buildings for last, along with Units and Civilizations.

Process and Project
The difference between Process and Project is that Project has a local Production cost, and thus a local progress, while Process does not.
Notably, all World Congress Projects are built with Processes in city, as they have a global cost.
Manhattan Project and Apollo Program grant dummy Policies that give their first-built benefits - these are the only instances of dummy Policies in VP and they belong to this folder instead of the Policies folder.

Specialist
SPECIALIST_CITIZEN, AKA Laborer, is (technically) a Specialist.
Tech_SpecialistYieldChanges is inserted here instead of the Tech folder.

Great Work
Nothing special, just adding the Flood Tablet and Crown Jewels.

Concepts​

Concepts is a section of the Civilopedia that explains game features, many of which have been changed, overhauled or added in VP.
All Concept changes have been rescued from the Text folder. Not the Concept text though, those stay there!

Corporations​

When you build a headquarters in your city, it merely founds a Corporation for you and does nothing else. The Corporation is what allows you to build Offices and gain Franchises, as well as giving some of the Corporation benefits like free trade routes, extended trade route distance and invincible trade routes.

Things that are controlled by Corporations instead of the Buildings they unlock:
Corporation_ResourceMonopolyOrs: the monopolies required to construct the HQ
Corporation_BuildingClassYieldChanges: founding a Corporation gives yield boosts to some Buildings
Corporation_SpecialistYieldChanges: founding a Corporation gives yield boosts to some Specialists
Corporation_UnitResourceProductionModifier: founding a Corporation gives a production modifier to Units that require specific Resources
Corporation_TradeRouteMod: enables its Offices to give a yield boost to trade routes targeting a city with its Franchise
Corporation_TradeRouteCityYield: enables its Offices to give a yield boost to the city for each trade route targeting another city with its Franchise
Corporation_ResourceYieldChanges: makes its Franchises boost certain Resource yields
The last one is linked to Corporations instead of Franchise Buildings (using Building_ResourceYieldChanges) for some reason.

Difficulty​

HandicapInfos and related non-main table changes belong here.

Events​

Moved from (1). Every change to Events, CityEvents, EventChoices, CityEventChoices, and related non-main tables are placed here.

Minors​

CIVILIZATION_MINOR changes are here similar to the barbarian ones, blocking specific units and buildings from being produced by CS.
Also contains changes to the SmallAwards table (quests), quest yield modifiers per CS personality/trait, and friendly/allied CS yields per era.

Policies​

Policy changes are separated by policy tree/ideology. Also contains changes to the PolicyBranchTypes table.
Each policy tree file starts with reorganizing the tree structure, then opener changes, individual policy changes, finisher changes, and lastly scaler changes.

Tech​

Changes to Eras, Technologies and related non-main tables are placed here.
The main change of VP tech is the tree structure, which is sorted out nicely in TechTreeSweeps.sql.

WorldCongress​

Contains changes to:

• LeagueSpecialSessions (the Congress itself)
• Resolutions
• ResolutionDecisions (the title of the secondary choices of a resolution, e.g. who to sanction; actual choices are populated in the DLL)
• LeagueProjects (Congress projects)
• LeagueProjectRewards

WorldMap​

Anything that appears on the map but is not a unit belongs here.

• Plots (no change in VP, so doesn't need a file)
• Terrains
• Features
  • Natural Wonders are Features so they belong here
  • Natural_Wonder_Placement table is also updated
• Resources
• Improvements
  • Also include Builds and Routes
  • Unique Improvements belong to the respective Civilization file and should not be in ImprovementChanges.sql and BuildChanges.sql
  • However, the New and Sweeps files still add and update (sweep) Unique Improvements
• GoodyHuts (Ancient Ruins)
• Yields

Units​

Changes to Units, UnitClasses, UnitCombatInfos, UnitAIInfos, UnitGameplay2DScripts, GreatPeople (acting as a bridge between the Specialist and the Unit), Missions and related non-main tables belong here.
Temp tables and bulk inserts/updates are extensively used here to reduce file size, increase readability, and reduce modding effort.

• NewUnits.xml - the only place that inserts new UnitCombats, UnitAIs, UnitClasses and Units into the database
  • (Category 1) New generic units and unique units that don't replace anything: all column values, except those to be swept, are inserted here
  • (Category 2) New unique units or exclusive units who replace Category 1 units:
    • Policy- and CS-exclusive units are assigned a unit class based on what they replace, instead of their real unit class, for now
    • Text and art columns: inserted normally
    • Columns to be swept: not inserted
    • Other columns: inserted based on values of their base units
    • These units are expected to be identical to their base units (except text and art) at the end of this file
    • Currently there are no Category 2 units in VP
  • (Category 3) New unique units or exclusive units who replace units already in base game:
    • Policy- and CS-exclusive units are assigned a unit class based on what they replace, instead of their real unit class, for now
    • Text and art columns: inserted normally
    • Columns to be swept: not inserted
    • Other columns: inserted based on base game values of their base units
    • These units are expected to be identical to their base units (except text and art) at the end of this file
  • This file only needs to be updated if
    • A new unit or unit class is added to VP;
    • An existing unit or unit class is removed from VP;
    • An existing Category 1 unit has something changed in its main table (Units) entry (you have to also update the associated Category 2 unit(s) in this case); or
    • An existing Category 2/3 unit has its Class, model, flag, or icon changed.
  • Refer to this guide or the comments in the file carefully when updating this file
• PreUnitChanges.sql - deletes the tables that need to be re-inserted later, and makes sure every unique or exclusive unit is identical to their base unit (except text and art) before UnitChanges.sql. Also assigns correct unit classes and the MinorCivGift column to every unit. Refer to the comments in the file for more details.
  • Please update the comments in this file if any unique/exclusive unit has its base unit changed
  • (Category 1) New/existing unique/exclusive units with existing base units
    • Updated to base game stats and properties of their base units, including any associated non-main tables that are not to be swept
  • (Category 2) Existing unique/exclusive units with new base units
    • Updated to have the same stats and properties as their base units as specified in NewUnits.xml, while deleting any entries from associated non-main tables that are not to be swept
    • Column names are hardcoded, values are NOT
  • (Category 3) New unique/exclusive units with new base units
    • NewUnits.xml has already made them identical to each other, no need to update here
  • This file only needs to be updated if
    • Any unique/exclusive unit is added/deleted or has its base unit changed
    • Any new non-swept column value is added to the base unit of a Category 2 unit
    • Any unit is turned into a CS-exclusive unit
  • After this file is loaded, EVERY unique/exclusive unit is expected to be identical to its base unit except text and art
• UnitChanges.sql - modifies Units and related non-main tables based on their Class, unless it's a text or art column
  • Only non-interrelated columns and tables are updated here. Others are either in UnitChanges2.sql or one of the Sweeps files.
  • Surprisingly few changes here - most unit traits are defined through promotions.
  • Please keep the comments up to date, if units are added/removed/renamed/reclassified.
• UnitChanges2.sql - bulk inserts/updates Units and related non-main tables based on their Class or CombatClass
  • Temp tables are used heavily here
  • 4 columns have been added to the UnitCombatInfos table in (1), to easily tell whether a UnitCombat is military unit, ranged, naval or aerial, reducing the need of listing UnitCombats.
• UnitStatChanges.sql - specifically sets moves, sight range, CS/RCS, range, and air defense for all units
• UnitAIChanges.sql - re-inserts the UnitClass_AITypes table, based on UnitClass. Is not a sweep since later files still update this for specific unique/exclusive units.
• <Civilization>.sql files are loaded now - see the Civilizations section
• PolicyUnitChanges.sql, CityStateUnitChanges.sql, BarbarianUnitChanges.sql
  • Assigns their own UnitClasses to Policy- and CS-exclusive units
  • Updates policy-, CS- and barbarian-exclusive units based on the difference between them and their base units
• UnitSweeps.sql, UnitCostSweeps.sql
  • Final sweeps on units, now that unique and exclusive units are their own thing

Buildings​

Contains all changes to Buildings table and related non-main tables. Buildings include all National Wonders and World Wonders.
A BuildingClass is considered a National Wonder if MaxPlayerInstances = 1.
A Building is considered a World Wonder if WonderSplashImage is NOT null or its BuildingClass's MaxGlobalInstances = 1.
Temp tables and bulk inserts/updates are extensively used here to reduce file size, increase readability, and reduce modding effort.

• NewBuildings.xml - the only place that inserts new BuildingClasses and Buildings into the database. Technically Audio_Sounds and Audio_2DSounds should belong to their own file in a Sounds folder, but currently the only new audio in VP is the Motherland Calls quote so I put it in this file. Maybe move it when there are more.
  • There are comments to separate building classes into sections: National Wonders, World Wonders, World Congress buildings, policy buildings, religious buildings, reformation wonders, and corporation buildings. Please put buildings in the correct section when editing this file.
  • Similar with the buildings, except unique buildings are further separated out.
  • And similar to units, there are special handling for buildings:
    • (Category 1) New generic buildings, or unique buildings that don't replace anything: all column values, except those to be swept, are inserted here.
    • (Category 2) New unique buildings that replace buildings in Category 1:
      • Text and art columns: inserted normally
      • Columns to be swept: not inserted
      • Other columns: inserted based onvalues of their base buildings
      • These buildings are expected to be identical to their base buildings (except text and art) at the end of this file
      • Only Ger belongs to this category currently
    • (Category 3) New unique buildings that replace buildings already in base game:
      • Text and art columns: inserted normally
      • Columns to be swept: not inserted
      • Other columns: inserted based on base game values of their base buildings
      • These buildings are expected to be identical to their base buildings (except text and art) at the end of this file
  • This file only needs to be updated if
    • A new building or building class is added to VP;
    • An existing building or building class is removed from VP;
    • An existing Category 1 building has something changed in its main table (Buildings) entry (you have to also update its associated Category 2 building(s) in this case); or
    • An existing Category 2/3 building has its BuildingClass, model, or icon changed.
  • Refer to this guide or the comments in the file carefully when updating this file
• PreBuildingChanges.sql - deletes unused buildings and the tables that need to be re-inserted later, and makes sure every unique building is identical to their base building (except text and art) before BuildingChanges.sql. Also assigns correct building classes. Refer to the comments in the file for more details.
  • Please update the comments in this file if any unique building has its base building changed
  • (Category 1) New/existing unique buildings with existing base buildings
    • Updated to base game stats and properties of their base buildings, including any associated non-main tables that are not to be swept
  • (Category 2) Existing unique buildings with new base buildings
    • Updated to have the same stats and properties as their base buildings as specified in NewBuildings.xml, while deleting any entries from associated non-main tables that are not to be swept
    • Column names are hardcoded, values are NOT
  • (Category 3) New unique buildings with new base buildings
    • NewBuildings.xml has already made them identical to each other, no need to update here
  • This file only needs to be updated if
    • Any unique building is added/deleted or has its base building changed
    • Any new non-swept column value is added to the base building of a Category 2 building
    • Any base game building is deleted
  • After this file is loaded, EVERY unique building is expected to be identical to its base building except text and art
• BuildingChanges.sql - modifies buildings and National Wonders based on their building class, unless it's a text or art column
  • Some of the Building_ThemingBonuses columns are inserted here. Others will be swept.
  • Unlike units, there are lots of changes on buildings and associated non-main tables. Temp tables need to be used often.
  • Every building class is updated individually, except the Defense, ExtraCityHitPoints, DamageReducionFlat columns, and Building_GreatWorkYieldChangesLocal, Building_YieldFromInternalTR and Building_ClassesNeededInCity tables, as they are more interrelated.
• BuildingChanges2.sql - modifies all buildings that aren't supposed to have replacements
  • As such, there's no need to update these using building classes.
• <Civilization>.sql files are loaded now - see the Civilizations section
• BuildingSweeps.sql, BuildingCostSweeps.sql
  • Final sweeps on buildings, notably with the rest of the columns of the Building_ThemingBonuses table. No way they can be updated individually.
  • The LaterEraBuildingConstructMod column in the Eras table is also updated here. Did you know buildings are 2% cheaper for every era past their unlock tech?

Civilizations​

Changes to each Civilization's unique components are here. Each civilization has its own file.
Traits are updated directly from base game values.
Existing Units and Buildings that don't replace anything and existing Improvements/Builds are updated from base game values.
New Units and Buildings that don't replace anything and new Improvements/Builds are updated from an empty state.
Other Units and Buildings are updated based on the difference between them and their base units/buildings. We have set it up so this is always possible.
Notably, the Unit_Builds table (for unique builds) are updated in civilization files.
After this, all unique components are finalized except the values to be swept.
Start biases are also swept in this folder.

UnitPromotions​

ALL promotions, new and old, are completely rewritten here. Note that promotions are completely separated from units and should never be mixed up.

• OldPromotions.xml and NewPromotions.xml - the Old file contains all base game promotions that are still used in VP, while the New file contains all promotions added in VP.
  • Pre-4.0 unused new promotions have been removed, and unused old promotions are not updated (except icon).
  • Only text/pedia info and prereqs of each promotion are in these files. Other columns are all moved to the Changes and Sweeps files.
  • Which means unless a promotion is added or promotion trees are reorganized, there's no need to edit these files. Or the below bolded thing happens.
  • The promotions are sorted in sections based on how they can be obtained: Pickable, Trait, Policy, Tech, Natural Wonder, Building, Unit (free promotion), Unique Unit, Post-Combat (Mystic Blade and Bushido), Plague, Event, Barbarian, and Hardcoded Source (the Conscript promotion). Please put promotions in the correct section if any of them have their source changed.
• PrePromotionChanges.sql - assigns some groupable promotions into "promotion classes" called RankLists. Promotions of the same RankList are stacked when displayed if a unit has multiple of them, with only the one of the highest RankNumber value displayed, both on the unit panel and above the unit flag. Assigning them here also facilitates bulk updates, as promotions of the same RankList are often similar.
• PromotionChanges.sql - re-defines non-text/pedia/prereq values of ALL promotions, again sorted by source.
  • Again, please make sure the comments stay correct after every promotion update, and that the promotions are in the correct section.
  • Promotion trees of each unit combat are drawn here using ASCIIFlow. Please also make sure those are up to date.
• PromotionIconChanges.sql - what used to be the Promotion Icons modmod. Make sure all promotions are included here even if the icons are unchanged from base game ones, since the XML files removed all of these. This file can be a Changes or a Sweeps file - it doesn't matter.
• PromotionSweeps.sql
  • UnitPromotions_UnitCombats table: determines which unit combat(s) can have the promotion. Trait, (Unique) Unit, Post-Combat, Plague, and Hardcoded sources ignore this limitation.
  • UnitPromotions_CivilianUnitType table: similar to above, but used to assign promotions to civilians.
  • Lists ALL of the LostWithUpgrade promotions, since the amount of those is way fewer than the not LostWithUpgrade ones.
  • CannotBeChosen is easily handled by including all LostWithUpgrade promotions, ones that are not in the above UnitPromotions_UnitCombats table, and the ones from Buildings, Natural Wonders, Policies, Techs, Events, and Barbarians.
• PromotionDisplaySweeps.sql - this used to be in (3a), but non-EUI should have the promotion orders changed too. Plus, (3a) should NOT contain any database changes, minus some text and UI stuff which has to be different from non-EUI.
  • This file assigns an OrderPriority to each promotion, which determines the order of their appearance both on the unit panel, and above the unit flag. The promotions providing more important information should always be shown and have lower OrderPriority.

Text​

Oops, almost forgot about this! The folder has been organized in a similar way to the outer Database Changes folder. The New files are loaded first, then the Changes files.
You'll notice that everything is placed inside the Text/en_US folder. Only updates to the Language_en_US table is allowed here, and all updates to the Language_en_US table must be placed here.
Localizers can clone the entire en_US folder, replace all instances of Language_en_US with the language they desire, and start translating each entry right away.

Special notes about the Notificaitons and UI folders and what should be placed there:
If a text key cannot be found in the database, it generally belongs to notifications and UI.
Notifications are the icons that pop up on the right side of the screen that contains a tooltip when hovered on, and can be dismissed. Any text on those tooltips belongs to the Notifications folder.
Other texts all belong to the UI folder. Both NewUIText.xml and UITextChanges.sql have comments separating the entries into sections, grouping them based on which interface they appear on.
Sometimes a text belongs to multiple interfaces. To be fair, they should be separated into two text keys but I'll leave the task to the UI modders.
When adding a new UI text key, please make sure the new entry is placed under the correct section.

Some update SQL references values from other tables, which is why Text updates are always loaded last.

The InterfaceModes table also has text keys that should be put into UI.

 

[azum4roll]

Guidelines for making changes​

Useful tips​

• Start the game, load the VP mods, and check your Cache folder. The Civ5DebugDatabase.db is the game database with VP loaded. You can use a SQLite viewer to open the file and look for tables/columns you want.
• If you still can't find what you need to change (like if you don't know the Type of a component), you can try downloading or building a modpack. Inside the Overrides folder in the modpack, the CIV5Units.xml file is the full VP database in text form, and even more important is the CIV5Units_Mongol.xml file, which contains the entire Localization database (the Language_en_US table). Want to change Special Forces but don't know what it's called internally? Just Ctrl+F "Special Forces" in the Mongol file and you'll find TXT_KEY_UNIT_MARINE, and searching for that in the CIV5Units file will give you your answer.
• Want to know BNW values instead? You can either grab the .db file or make a modpack of BNW, but the simplest way is visiting the Civ Wiki. It has almost every base game table parsed in readable form.
• Usually though, the comments I scattered throughout the code should give enough hint of what you need to change. Which is why I keep repeating the request to keep the comments up to date.

General rules​

• Put your changes in the correct files.
  • (Re-)read post 2 to learn where to place the changes.
  • Most of the time a change to a table starting with ABC belongs to a file containing ABC in the name.
  • If you're changing a unique component but not its base version, look for the civilization file.
  • If you're changing a non-unique component with a unique variant, also make sure the latter is still correct after your change.
• Use consistent formatting.
  • There are numerous XML formatting tools for every popular editor. Should be easy to hit that format button every time before you save.
  • For SQL, try to follow the existing queries. A general rule is that only keywords (SELECT, SET, WHERE, etc.) can have no indentation, and that multi-line bracket blocks must be indented.
  • SQL files should have a trailing new line at the end. XML files should not have one.
  • Split lines that are too long, but UPDATE-SET-WHERE queries should either be on one line, or the three keywords should each be on a separate line.
  • The indentation standard is tabs (not spaces).
  • There should be no more than one whitespace between two words on the same line, and no leading and trailing spaces. Tabs are only allowed at the beginning of non-empty lines as indentation.
    • Most editors should have a setting to show whitespace characters. You can use that to scan for extra spaces and tabs you accidentally left in the code.
  • Generally there is no need to have more than one empty line as separation.
• If you want to save time on formatting SQL and don't mind downloading extra stuff, you can try the SQLFluff extension on VSCode. It can auto-detect and fix most formatting errors, but you'll need to download Python and then SQLFluff off it since the extension merely acts as a bridge between SQLFluff and VSCode. I've attached a config file that ignores the more annoying rules (put it in the root directory of the project).
• Always update comments.
  • I've added many comments in the codebase. Some are component names, some are section titles, and some explain what the following code is meant for. Please try to always keep these comments correct.
  • For example, if you change "Terrace Farm" to "Pata-Pata", besides updating ImprovementTextChanges.sql, you should also do a global search and update every comment mentioning Terrace Farm to its new name.
• Always update game text.
  • Making a change is always more than changing/adding a single line. Besides comments, any text referring to the changed game component must also be updated.
  • Global searches are always helpful, but be careful when mass replacing as some text may not be referring to that exact component despite mentioning it.
• Follow existing text of the same category when updating text.
  • Help and Strategy text may not always describe everything about the game component. For example, building help texts don't mention base yields and specialist slots.
  • Some strategy text may currently be already outdated. Please help to correct them if you know how.
• Do a sanity check on relevant AI flavors.
  • If an ability is removed from a game component, a flavor type may also need to be removed as the component doesn't benefit it anymore.
  • If an ability is added to a game component, a flavor type + sane value may need to be added to the component.
• For DLL modders, always (try to) make sure the AI can (still) use the added or changed mechanic.
  • Best case is that the AI factors in the mechanic and scores components well with regard to it.
  • If the AI only coincidentally makes use of the mechanic due to other related factors, it's still acceptable.
  • If the AI randomly uses or doesn't use the mechanic at all, it shouldn't be acceptable.
• Make use of temp tables when mass inserting, updating or deleting. Always consider using general conditions if you need to list out multiple items.
  • It's somewhat like factorization in mathematics. You pull out the common factor and only need to write that once.
  • For example, compare LeaderFlavorSweeps.sql with the pre-4.0 version (LeaderFlavors.sql). It's been shortened from 59362 bytes to only 37205 bytes.
  • The old method of listing unit combats when assigning specific promotions to units is replaced by using the helper columns from UnitCombatInfos instead, where possible.
  • Make sure you drop temp tables in the same file they're created. Even though tables marked as temp are supposed to be removed when the connection is closed, we can't be exactly sure how it works in game.

Steps of making changes​

Each person can have their own methods and procedures, but I'm going to list mine here as a reference.
Let's say I'm implementing proposal 6-39. The changes are as below:
A. increase / per desert/tundra tile worked from 1 per 3 to 1 per 2
B. remove bonus to Merchants
C. change the relevant values on the Egyptian Burial Tomb to match

My steps, after finishing the necessary git actions:
1. Identify the component that needs to be changed. In this case, it's going to be BUILDINGCLASS_CARAVANSARY, since we're changing both Caravansary and Burial Tomb at the same time.
2. Global search the component type. The file needs to be changed is BuildingChanges.sql.
3a. Change A is on the Building_YieldPerXTerrainTimes100 table. The yield types are not changed, so we only need to change the 34 (1 per 3) to 50 (1 per 2) here.
3b. Change B is on the Building_SpecialistYieldChangesLocal table. The bonus is removed, so we delete the insert statement.
4. Burial Tomb should be automatically updated, but we need to check to make sure. Go to Egypt.sql.
4a. We see that the bonus and on tiles worked is already 1 per 2 on the Burial Tomb. If this is considered "matching", we can delete the update statement.
4b. Otherwise, if the intended bonus is actually 2 per 3, we can change the 50 to 67 here.

Are we done here? Not yet! We need to also make sure comments and game text are up to date.
5. Global search Caravansary. BuildingTextChanges.sql has an entry. We need to update "every 3 Desert or 3 Tundra tiles" to "every 2 Desert or 2 Tundra tiles", and delete "[ICON_VP_MERCHANT] Merchants in this City gain +1 [ICON_GOLD] Gold".
6. Global search Burial Tomb. The text entry is in CivilizationTextChanges.sql. We need to update the help text and potentially the strategy text accordingly.
7. We're only changing numbers without adding or removing abilities, so building flavors don't need to be changed.
8. The comments look fine, so we can stop here and commit the change.

 

[azum4roll]

The guide is done! Feel free to ask me anything here or on Discord.

@Recursive can you sticky this?

 

[azum4roll]

Added parts to Post #3 for AI stuff.

 

[mofab16084]

Hello.
1) Thanks for the theme about "Vox Populi". I saved it to my bookmarks. Is there a similar theme for "Community Patch only"? - I'm wondering what files do what; options.
I used before "Community Patch only", i.e. without "Vox Populi". For several reasons.

2) I would really like to use the installed combination of mods: CP + VP (v. 4.4.2 at the moment) to "modify" VP so, as to remove some things.
For example, Folder: "(2) Vox Populi/Database Changes/Civilizations" - how can we return to standard leaders?
Simply deleting this folder is not enough - when the game starts, only the first leader is given a choice, then it ends. Apparently you need to edit files with associated VP-features, for example, NewUnits.xml, NewBuildings.xml, etc. And then the text description... can this be done somehow easier?