Welcome, diplomats and demographic engineers! This guide provides a detailed, step-by-step explanation of how the Cultural Repatriation Treaties mod works, from the initial proposal to the final migration wave. Understanding these mechanics will allow you to make more informed and strategic decisions.

The entire process begins not in the treaty screen, but with a new diplomatic action.

Step 1: The "Prepare Repatriation Treaty" Diplomatic Action
To start, you must use the Prepare Repatriation Treaty diplomatic action on a target country. This action signifies the beginning of diplomatic preparations and applies a short-term Prepare Repatriation Treaty modifier to your country.

Step 2: Define the Treaty Direction
Immediately after using the action, you will receive an event titled "Define Repatriation Mandate." Here you must choose the fundamental direction of your proposal:

• Inbound: You will request that the target country allows one of its cultural groups to migrate to your nation.
  
• Outbound: You will offer to send one of your own cultural groups to migrate to the target nation.

Step 3: Select the Culture
Based on your choice, you will be presented with a list of eligible cultures. Due to the potentially large number of cultures, this list is paginated.
However, not every culture will be available. The selection is strictly limited by the Migration Laws of both your country and the target nation.

• Closed Borders: If either country has the Closed Borders law, this diplomatic action cannot be initiated at all.
  
• Migration Controls: This law is the most significant limiting factor. If either country has it, you will only be able to select cultures that have an acceptance score of 60+ in the country with this law.
  
• No Migration Controls: If a country has No Migration Controls, it places no legal restrictions on which cultures can be chosen for repatriation to or from its lands.

In short, a treaty is only possible for a culture that is legally permitted to migrate between both nations. You must always consider the laws of both parties before making your selection. Also, only non-primary cultures are allowed to migrate.

After selecting a culture, you will be shown a final confirmation screen. This screen displays a detailed breakdown of the target AI's calculated stance on the proposal, which we call the Estimated Population Value. This is the core calculation that determines how willing or unwilling the AI will be. Below are the formulas used to calculate this score.

When you ask the AI to give up its people, it evaluates the culture based on the following factors:

• Relative Population Size
  A penalty based on the culture's percentage of the target's total population. The AI is reluctant to lose a significant demographic bloc.
  Formula: (Culture Population ÷ Total Population) * -100 (min: -75, max: 0)
  
  
• Absolute Population Size
  A tiered penalty based on the raw number of people. Losing millions of pops is a serious matter, regardless of percentages.
  Formula: A static penalty based on tiers. Examples: -5 for >100k pops, -20 for >1M pops, -50 for >10M pops.
  
  
• Culture Acceptance
  A score based on how the target country's government views the chosen culture. They will resist giving up cherished cultures and will be happy to see persecuted ones leave.
  Formula: A static value from +40 (for Violent Hostility) to -40 (for Full Acceptance).
  
  
• Economic Burden
  A score that measures how productive the culture is. A high percentage of Peasants and Unemployed is seen as a burden, resulting in a positive score.
  Formula: (((Peasant Pops + Unemployed Pops) ÷ Total Culture Pops) - 0.5) * 60 (min: -30, max: +30)

The sum of these factors gives you the final Estimated Population Value for the Inbound treaty.

When you offer your people to the AI, it evaluates them based on its own needs across three main categories:

1. Cultural Desirability

• Primary Culture Bonus: A massive static bonus of +75 if you are offering them more of their own primary culture.
  
• Cultural Acceptance: In other case, a score from +40 to -40 based on how much they accept the culture you are sending. They will not want to import groups they discriminate against.

2. Economic Need

• Workforce Shortage: A bonus based on how few Peasants and Unemployed the AI has. A low percentage means they are desperate for workers.
  Formula: (0.4 - (Peasants + Unemployed) ÷ Total Population) * 50 (min: -10, max: +20).
  
• Available Land: A bonus based on the ratio of free arable land to total arable land. "Empty" countries are more willing to accept potential farmer pops.
  Formula: (Free Arable Land ÷ Total Arable Land) * 10 (min: 0, max: +10).
  
• Unfilled Jobs: A powerful bonus based on the number of vacant jobs in their industries relative to their total population.
  Formula: (Total Unfilled Jobs ÷ Total Population) * 2000 (min: 0, max: +20).

3. Political & Social Factors

• National Turmoil: A penalty based on the AI's current level of turmoil. Unstable nations are hesitant to accept new populations.
  Formula: Total Turmoil Percentage * -50 (min: -25, max: 0).
  
• Interest Group Power: Powerful IGs influence the decision based on their agendas. This is a sum of the following potential modifiers:
  
  • Industrialists: +10 (Want more workers)
    
  • Landowners (if non-primary culture): -15 (Oppose cultural change)
    
  • Petite Bourgeoisie (if non-primary culture): -20 (Fear economic/cultural competition)
    
  • Trade Unions: -10 (Fear wage depression)
    
  • Rural Folk: -5 (Resist outsiders)
    
  • Intelligentsia (if has Multiculturalism): +5 (Like diversity)

The sum of all these outbound factors is capped at a maximum of +50 to prevent exploits.


Step 4: Proposing the Treaty
After you confirm the culture choice in the event, your country receives a 30-day Repatriation Treaty Prepared (Inbound/Outbound) modifier. During this time, the Cultural Repatriation article will be available and unlocked in the treaty negotiation screen with the target country. The Estimated Population Value you saw in the event is added to the standard diplomatic acceptance factors (Relations, Infamy, Rank, etc.) to determine the final treaty acceptance chance.

Step 5: The Migration Process
Once the treaty is signed, the Repatriation Treaty Prepared (Inbound/Outbound) modifier is replaced by a 5-year Repatriation Treaty Signed (Inbound/Outbound) modifier. The migration itself does not use the vanilla mass migration system, but a custom scripted effect to ensure a complete population transfer.

The process consists of 50 migration ticks that occur every 37 days over the 5-year treaty duration. Each tick moves a percentage (by default, 2%) of the total population of the chosen culture. This method ensures that by the end of the 5-year period, the entire cultural population will have moved from the source country to the target state(s).