BigPharma wrote:

Upgrade paths are determined by the unit's class and level. Lower-level units in the same class upgrade to higher-level units. If two units are in different classes, the class of the lower-level unit needs to be told to upgrade to the class of the higher-level unit.

Investigating at how the Common Crossbow (UnitClass_Ranged) can be upgraded into  the Common Arquebusier (Unitclass_Gunner), the only thing that they share is the Serializable Family "UnitFamily_Ranged". Is this how an upgrade path is established between Unitclasses?

I am experimenting with the upgrade path as well. I think what happens is that a unit can upgrade from one class to another through the Serializable Family. So for example, using Unity Hub to modify my Project, when I look at Dragoons their Serializable Family is UnitFamily_Cavalry. When I click the "Select the Reference" button for UnifFamily_Cavalry it brings up the UnifFamily_Cavalry(UnitFamilyDefinition) window where there is a dropdown option to select the "Serializable Next Family Name". For UnitFamily_Cavalry , the Devs have currently selected UnitFamily_MechanizedInfantry as the Serializable next Family Name, which is the Armored Personnel Carrier's Serializable Family. So Dragoons upgrade into Armored Personnel Carriers.

This can all quickly become very confusing as in the database Dragoons are UnitClass_MountedGunner but their Serializable Family is UnifFamily_Cavalry which is defined with a Serializable next Family Name of UnitFamily_MechinzedInfantry. The Armored Personnel Carrier is UnitClass_ArmouredVehicle with a Serializable Family of UnitFamily_MechanizedInfantry which is defined with a Serializable next Family Name of None.

If you follow the evolution of Common Horse Units it looks like this:

Era 1: Scout Cavalry are UnitFamily_ScoutCavalry with a next family of UnitFamily_LightCavalry

Era 2: Horsemen are UnitFamily_LightCavalry with a next family of UnitFamily_ShockCavalry

Era 3: Knights are UnitFamily_ShockCavalry  with a next family of UnitFamily_Cavalry

Era 5: Dragoons are UnitFamily_Cavalry with a next family of UnitFamily_MechanizedInfantry

Era 6: Armored Personnel Carriers are UnitFamily_MechanizedInfantry with a next family of None.

There aren't any Common Horse Units in Era 4. But the Polish have Winged Hussars in Era 4.

Era 4: Winged Hussars are UnitFamily_Cavalry which we already know has a next family of UnitFamily_MechanizedInfantry

This allows Knights to be upgraded to Winged Hussars if you choose the Polish Culture, and Winged Hussars to be upgraded to Armored Personnel Carriers.

So the upgrade path appears to be solely based on Serializable Family and Serializable next Family Name.

So, using Unity Hub, for me to change the upgrade path of Arquebusiers (UnitFamily_Ranged) from Musketeers to Heavy Machine Guns, I first had to look at the LandUnit_Era5_Common_MachineGuns definition to find out its Serializable Family, which is UnitFamily_MachineGun. I then imported UnitFamilyDefinition>UnitFamily_Ranged and changed the Serializable next Family Name from UnitFamily_GunpowderInfantry to UnitFamily_MachineGun. 

Hope this helps.