Metaregions

Metaregions are custom scopes created by adding new regions in the regions.txt file. Europa Universalis III, as well as most Paradox games from the same era, support calling any defined region as both a triggers AND effects scope.

The most important metaregion is the any_province_region that can be used to greatly expand the versatility and flexibility of the Clausewitz Game Code.

This guide is an abridged version of the full guide available on the Paradox forums.

The any_province_region metaregion

By far the most important and flexible metaregion is the any_province_region metaregion. This is a metaregion that groups together every province in the game world, including empty provinces, wasteland provinces, and ocean provinces.

To create this metaregion, simply use Excel to generate a column of numbers starting from "1" until the last defined province number appearing in the definitions.csv file. Then, copy this entire column, create a new region in regions.txt, and inside the brackets, paste the list of numbers.

You will now be able to call any_province_region within your mod's code. The any_province_region metaregion will serve to encompass even sea tiles and empty tiles, which makes it much more versatile than other, weaker methods of scoping "every" province.

Scoping a metaregion in the triggers section

In the triggers section, scoping a metaregion acts as such:

"Any province within [metaregion] has: "

The metaregion does not take a limit scope, as is typical for scopes in the triggers section.

any_province_region = {
    religion = catholic
    region = west_indies_region
    owned_by = THIS
}

This trigger will return true if any province is catholic, in the West Indies, and is owned by THIS. Furthermore, as the above code demonstrates, it is possible to use the region trigger within a metaregion.

Scoping a metaregion in the effects section

In the effects section, scoping a metaregion acts as such:

"For any province within [metaregion] that: "

The metaregion takes a limit scope that restricts the scope to a smaller subscope. Once the limit is closed, the effects are leveraged to every province in the limited subscope.

any_province_region = {
    limit = {
        religion = catholic
        region = west_indies_region
        owned_by = THIS
    }
    random = {
        chance = 25
        create_revolt = 1
    }
}

This will scope all West Indies, catholic provinces owned by THIS and leverage a random 25% chance of a revolt in each of these provinces.

How metaregions affect chance and randomness

Take the following code:

any_owned = {
    random = {
        chance = 25
        create_revolt = 1
    }
}

By using any_owned and then calling a random event, one would hope that for every owned province, a 25% chance is calculated individually for there to be a revolt. This would mean that when the effect is called, approximately 25% of the country will be engulfed in rebellion.

In reality, using any_owned, the desired effect does not occur. Instead, there is a 25% chance that every province erupts into rebellion, or that no provinces erupt into rebellion. There is seemingly no way to simulate a per-province chance calculation for a random effect.

However, using metaregions, the game is forced to calculate chance per province, as desired:

any_province_region = {
    limit = {
        owned_by = THIS
    }
    random = {
        chance = 25
        create_revolt = 1
    }
}

When running this effect, approximately 25% of the country will be engulfed in rebellion.

Using the any_province_region metaregion as a global reference

When scoping countries in Europa Universalis III, a common issue that arises for modders is the fact that the trigger scope any_known_country and the effects scope any_country are relative to THIS, and do not scope THIS. For example, if a player runs through an effect with the any_country code, no matter what follows in the limit, the player country (THIS) is automatically excluded. This can create many issues for modders attempting to write global code that does not discriminate based on the position of THIS.

Using the any_province_region metaregion is a great way to scope a global reference that is completely neutral and non-relative to THIS.

For example, if a modder wanted to add a certain province modifier to every province with a base tax of at least 5, the old method is as follows:

### Step 1: Run the code for all owned provinces
any_owned = {
    limit = {
        base_tax = 5
        NOT = { has_province_modifier = base_tax_5 }
    }
    add_province_modifier = {
        name = base_tax_5
        duration = -1
    }
}
### Step 2: Run the code for all non-owned provinces
any_country = {
    limit = {
        any_owned_province = {
            base_tax = 5
            NOT = { has_province_modifier = base_tax_5 }
        }
    }
    any_owned = {
        limit = {
            base_tax = 5
            NOT = { has_province_modifier = base_tax_5 }
        }
        add_province_modifier = {
            name = base_tax_5
            duration = -1
        }
    }
}

This was known as the "double-tap method", and was much clunkier and less functional. Owned and non-owned provinces must be scoped separately due to the relativity problems surrounding any_owned and any_owned_province. Furthermore, this method could never scope empty provinces, or sea provinces, as they do not have an owner. Using the any_province_region metaregion eliminates the issue:

any_province_region = {
    limit = {
        base_tax = 5
        NOT = { has_province_modifier = base_tax_5 }
    }
    add_province_modifier = {
        name = base_tax_5
        duration = -1
    }
}

Not only is the code global, more functional, and more optimized, but also empty provinces fulfilling the criteria will also receive the modifier. Let's look at another example with a country scope. If a modder seeks to find any country, potentially including THIS, that is Catholic and that is at war, they needn't rely on the antiquated double-tap method:

any_province_region = {
    owner = {
        religion = catholic
        war = yes
    }
}

The above will return TRUE once it detects any province with an owner that fulfills the country-scope conditions set forth. It will return TRUE regardless of if that country is THIS or if it is a different country.

Warning: it is not recommended to use the any_province_region metaregion as a global reference for countries in the effects section. This is because isolating all provinces that belong to a country and then scoping the owner will cause all following effects to run as many times as provinces were scoped.

any_province_region = {
    limit = {
        owner = { 
            religion = catholic
            war = yes
        }
    }
    owner = {
        stability = -1
    }
}

The above code will actually run through the effects multiple times. If a Catholic country at war owns 10 provinces, then the owner effect stability = -1 will be executed 10 times in a row. In certain cases, depending on the effect, this may even crash the game.