Religion modding

From Europa Universalis 4 Wiki
Jump to navigation Jump to search

This article is a guide to adding new and editing existing religions and religion groups. It assumes familiarity with the game mechanics surrounding religion.

Quick checklist[edit | edit source]

To add a new religion:

  • Create an entry for the religion (and a religion group, if necessary) in a religion file
  • Add icons to the icon_religion, icon_religion_small, and province_view_religion files in the gfx/interface folder
  • Add frames to the corresponding entries in interface/countryview.GFX, interface/provinceview.GFX, and interface/countrycourtview.GUI
  • Add localisation for the new religion
  • Confucian modifiers are distributed across religion.txt, defines.lua, and event modifiers

The religion file[edit | edit source]

Vanilla religions are found in common/religions/00_religions.txt. To edit these religions or to add new religions to vanilla religion groups, copy this file to a mod and edit it there. Do not change the name of the file. To add entirely new religion groups, instead create a new .txt file with any name in a mod's common/religions folder. A simple religious group with a single entry looks like this:

jewish_group = {
        flags_with_emblem_percentage = 33
        flag_emblem_index_range = { 28 28 }
        jewish = {
                icon = 20
                color = { 0.6 0.1 0.4 }
                country = {
                        tolerance_own = 2
                        advisor_pool = 1
                province = {
                        local_missionary_strength = -0.02
                heretic = { SAMARITAN KARAITE }

Religion group[edit | edit source]

All religions must be within religion groups (Christian, Jewish, Muslim, etc). Religion groups must have a unique name. In this section, before the addition of religions to a group, can be attributes shared by all religions in the group. All of these attributes are optional. The most notable are:

Script Description
defender_of_faith = yes Determines whether countries with a religion in the group can use the defender of the faith mechanic.
can_form_personal_unions = yes Determines whether countries with a religion in the group can use the personal unions mechanic
center_of_religion = [province id] Determines the most important province for this religion group. Centers of Reformation can only appear on the same continent as the Center of Religion.
crusade_name = CRUSADE Determines the name of a holy war declared in the name of this religion group using certain CB's.

Custom and client nation flags[edit | edit source]

It is also possible to determine the variety of flags that will be generated for non-player-created custom nations and client states. This can be determined at the religion group level (as it always is in vanilla), but can be overridden in the individual religion entries within the group.

flags_with_emblem_percentage = 33
flag_emblem_index_range = { 1 18 }

The first attribute determines how likely a generated flag is to contain an emblem. It is a simple percentage rate. The second attribute determines the range of emblems that can be generated. This is to ensure that entirely inappropriate flags are not generated for new countries, e.g. a Muslim nation with a crucifix emblem.

Religion entry[edit | edit source]

New religions must have a unique name. Religion entries must contain at least the following:

  • color = { 0 127 255 } - A color (used for the religion map mode), using 8-bit RGB (0-255) format since Patch 1.21; using decimal (0.0-1.0) in all versions before Patch 1.21.
  • icon = 20 - An integer representing the icon for the religion in the interface files. This will be further explained later.
  • heretic = { SAMARITAN KARAITE } - The name/s of heretic rebel types for the religion. There should be at least one heretic type listed.

Modifiers[edit | edit source]

Country-scope modifiers are applied to a country that is a specific religion. The country scope within the religion scope defines these modifiers:

country = {
    tolerance_own = 2
    advisor_pool = 1

Province-scope modifiers are applied to provinces that are a specific religion. The province scope within the religion scope defines these modifiers:

province = {
    local_missionary_strength = -0.02

For syncretic faiths, different country-scope modifiers are applied to a country that adopts a specific religion via syncretic faith. The country_as_secondary scope within the religion scope defines these modifiers:

country_as_secondary = {
     idea_cost = -0.1

Religious conversion[edit | edit source]

Some religions can choose, under certain circumstances, to convert to other religions. To allow a religion to convert to another religion, add the following to the religion entry:

allowed_conversion = {

If religious conversion is allowed, an "on_convert" section should also be included, such as the following:

on_convert = {
        change_religion = hinduism
        add_prestige = -100	
        add_country_modifier = {
                name = "conversion_zeal"
                duration = 3650

At the very least, this section should contain the "change_religion = [target religion]" line. This section can include any standard effects that scope to a country.

Religion mechanics[edit | edit source]

A new religion can use the special mechanics of vanilla religions if specified. It is recommended that you do not mix and match mechanics from different vanilla religions. It is possible to do so, but may require advanced interface modding to work correctly. Mechanics include:

Script Description
papacy = {} Uses the Catholic Papacy system. Is not Boolean; must define Papal tag, election cost, and seat of papacy within papacy entry.
hre_religion = yes Uses the HRE religious factions and thirty years war systems. A religion with this attribute will be the default official religion of the HRE, as Catholicism is in the vanilla game.
hre_heretic_religion = yes As above, but determines the religion that will be considered the primary heresy, as Protestantism is in the vanilla game.
date = [any date] Determines the date that this religion becomes active in the game's history (will have no effect on games started before this date).
fervor = yes Uses the Reformed fervor mechanic
fetishist_cult = yes Uses the fetishist cult mechanic (used both by Fetishist and Alcheringa in the basegame)
has_patriarchs = yes Uses the Orthodox patriarch authority mechanic
uses_piety = yes Uses the Muslim piety mechanic
personal_deity = yes Uses the personal deity system (used by Norse and Hinduism in vanilla)
authority = yes Uses the Inti authority mechanic
religious_reforms = yes Uses the Mesoamerican religious reform mechanic
doom = yes Uses the Nahuatl doom mechanic
uses_church_power = yes Uses church power mechanics
uses_anglican_power = yes Uses Anglican aspect mechanics
uses_karma = yes Uses the Buddhist Karma mechanic
uses_isolationism = yes Uses the Shinto isolationism mechanics. Disasters must be defined separately.
ancestors = yes Uses the Totemist ancestors mechanic
gurus = {} Uses the Sikh gurus mechanic. Is not Boolean; must define gurus separately within guru entry.

Other religion attributes[edit | edit source]

There are some other special attributes that can be used, but which do not involve the complications associated with religious mechanics:

Script Description
misguided_heretic = yes Other religions in the group will have a higher default relation with these countries than they would with other heretic countries. In the vanilla game, Coptic and Orthodox have this bonus.
declare_war_in_regency = yes Countries with this religion can declare war during regencies. In the vanilla game, only Nahuatl has this bonus.
can_have_secondary_religion = yes Countries with this religion can have a syncretic faith, like the Tengri religion in the vanilla game. Unlike other religious mechanics, religions with this mechanic can also utilize one other religious mechanic without problem.

Modability of mechanics[edit | edit source]

An overview of what mechanics work for a new custom religion.

Mechanic Modability
Catholic papacy Can only be changed globally. Can change Papal Actions, Golden Bulls, Papal screen is mostly hard-coded but localization and appearance is moddable. Papal tags are unique to each religion, and without one the papacy mechanic will not function.
Reformed fervor Can only be changed globally. Can change gain modifier of fervor. Can change effect and cost of fervor focus.
Orthodox patriarchs Icons can be changed and are well moddable. Patriarch authority can only be changed globally.
Muslim piety Can only be changed globally. Change scaled modifiers for high and low piety, and can change piety actions.
Norse/Hinduism personal_deity Well moddable, can add new deities for a custom religion.
Inti authority Fairly well moddable. To make religious reforms work for a new religion, add an event in on_buy_religious_reform within 00_on_actions.txt in common/on_actions.
Mesoamerican religious reforms See Inti authority.
Nahuatl doom Doom mechanics can only be changed globally, and only works before reforming the faith, but is otherwise moddable. See Inti authority.
Protestant aspects Well moddable, introducing new aspects and changing costs.
Anglican aspects Well moddable, introducing new aspects, changing costs and support for trigger
Coptic holy sites Well moddable, adding new holy site locations and effects. Does not require a specific entry for countryreligionview.gui unlike Protestant or Anglican aspects.
Buddhist karma Can only be changed globally. Effects of actions changable. Modifier of low/high karma changeable.
Shinto isolationism Fairly well moddable. Isolationism level can only be changed globally and is defined for every country using this mechanic. Unique incidents can be added for custom religions .
Sikh gurus Well moddable, adding guru effects, aspects, dates, and names unique for each religion. The Guru teaching modifier can only be changed globally.

Religion graphics and interface[edit | edit source]

New religions should have their own graphics and icons, and they may fail without an interface.

Icon graphics[edit | edit source]

Find the following files in the gfx/interface folder and copy them to a mod:

  • seen in diplomacy view.
  • seen in religion tab.
  • seen in province view.
  • seen on CoR on the map.

Edit these files with your preferred graphics editing software. Expand the image horizontally and add your new icon.

Hint: The file for and are equivalent.

Icon interface[edit | edit source]

Find the following files in the interface folder and copy them to a mod:

  • countryview.gfx
  • ledger.gfx
  • provinceview.gfx

In countryview.gfx, find the sprites with the names "GFX_icon_religion", "GFX_country_icon_religion" and "GFX_icon_religion_small". In these entries, find the line with the number of frames. Add to this number the number of new religion icons you added to the religion strip in the above stage. In provinceview.gfx, do the same for the sprite named "GFX_province_view_religion". In ledger.gfx, do the same for the sprite named "GFX_religion_icon_strip".

Religion interface window[edit | edit source]

If you're attempting to make a mod-added religion work with the Protestant or Anglican aspects screen, you'll have to go into interface/countryreligionview.gui and add a religion-specific datafield window named YOURRELIGION_specific_window (Protestant example shown):

		windowType = {
			name = "protestant_specific_window"
			backGround =""
			position = { x=32 y=300 }	
			size = { x=280 y=50 }
			moveable = 0
			dontRender = ""
			horizontalBorder = ""
			Orientation = "UPPER_LEFT"
			instantTextBoxType = {
				name = "church_name"
				position = { x = 10 y = -65 }
				font = "vic_18"
				borderSize = {x = 0 y = 0}
				text = "Church of Nothingland"
				maxWidth = 200
				maxHeight = 25
				Orientation = "UPPER_LEFT"
				format = left
			iconType =
				name ="protestant_aspects_frame_bg"
				spriteType = "GFX_country_religion_view_protestant_bg"
				position = { x= 3 y = -44 }
			instantTextBoxType = {
				name = "church_power_label"
				position = { x = 10 y = -37 }
				font = "vic_18"
				borderSize = {x = 0 y = 0}
				maxWidth = 150
				maxHeight = 25
				Orientation = "UPPER_LEFT"
				format = left
			OverlappingElementsBoxType = {
				name = "unlocked_aspects"
				position = { x = 50 y = -30 }
				size = { x = 260 y = 80 }
				Orientation = "UPPER_LEFT"
				format = left
				spacing = 14
			guiButtonType = {
				name = "view_aspects"
				position = { x=8 y = -22}
				quadTextureSprite ="GFX_protestant_aspects_icon"
				Orientation = "LEFT"

...and a church aspect item window named countryreligionview_aspectitem_YOURRELIGION (Protestant example shown):

	windowType = {
		name = "countryreligionview_aspectitem_protestant"
		backGround =""
		position = { x=10 y=-20 }	
		size = { x=50 y=46 }
		moveable = 0
		dontRender = ""
		horizontalBorder = ""
		Orientation = "UPPER_LEFT"
		iconType =
			name ="aspect_icon"
			spriteType = "GFX_hindu_deities_strip"
			position = { x= 45 y = -14 }
		instantTextBoxType = {
			name = "aspect_name"
			position = { x= -42 y = 6 }
			font = "vic_18"
			borderSize = {x = 0 y = 0}
			text = "AspectName"	
			maxWidth = 102
			maxHeight = 108
			Orientation = "UPPER_LEFT"
			format = left
		instantTextBoxType = {
			name = "aspect_effect"
			position = { x = 98 y = -2 }
			font = "vic_18"
			borderSize = {x = 0 y = 0}
			text = "AspectEffect"	
			maxWidth = 206
			maxHeight = 108
			Orientation = "UPPER_LEFT"
			format = left
		guiButtonType = {
			name = "pick_aspect"
			position = { x=301 y = 1}
			quadTextureSprite ="GFX_standard_button_71"
			buttonText = "SELECT"
			buttonFont = "vic_18"
			Orientation = "LEFT"

Without these, the game may crash upon starting a nation with the added religion.

Localisation[edit | edit source]

There are a variety of items that need to be localised once a religion has been added. These are the localisation entries for the Jewish religion group, as an example:

jewish_group: "Jewish"
jewish: "Jewish"
karaite: "Karaite"
samaritan: "Samaritan"
jewish_rebels_demand: "Convert $COUNTRYNAME$"
jewish_rebels_demand_desc: "The religious rebels fight for the $RELIGION$ religion. They demand that we recognize its supremacy or at the very least cease our efforts to convert them and let them worship in peace."
jewish_rebels_title: "Religious"
jewish_rebels_name: "$RELIGION$ Zealots"
jewish_rebels_desc: "Religious fanatics tend to rise up in provinces controlled by nations of a different faith. They seek to spread their faith and smite all unbelievers."
jewish_rebels_army: "$RELIGION$ Army"

Here, the names of the religion and religion group have been localised, as well as the names of heretic types. Localisation has also been added for religious rebels of the Jewish religion.

Personal deity modding[edit | edit source]

A religion uses the personal deities system if the line personal_deity = yes is included in its entry in the religion folder. To edit existing Norse or Hindu deities, copy the relevant file from common/personal_deities to a mod. To create new personal deities, create a new text file in the common/personal_deities folder of a mod.

Personal deities file[edit | edit source]

Here is an example of a custom entry in a personal deities file:

quetzalcoatl = {
	idea_cost = 0.05
	land_morale = 0.1
	allow = { religion = nahuatl }
	sprite = 55
	ai_will_do = {
	 	factor = 1
	 	modifier = {
	        	factor = 2
	        	personality = ai_militarist
	 	modifier = {
	        	factor = 0.5
	        	personality = ai_diplomat

There are 4 sections in this entry:

  • Bonuses: Unsorted attributes at the beginning of the entry. Uses any effect that scopes to a country.
  • allow: Uses any trigger that scopes to a country. One trigger should determine the religion the deity is designed for.
  • sprite: Determines which deity icon will be used. A value higher than the actual number of deities will result in no icon being displayed, which is a valid choice.
  • ai_will_do: Instructions for how AI nations choose personal deities. Uses any trigger that scopes to a country, though in vanilla the only triggers used are ai personality.

Personal deity icons[edit | edit source]

Icons for personal deities are created and referenced in much the same way as icons for religions, though in this case there are files to edit.

The graphics file is found in gfx/interface/ Copy it over to a mod. To add new icons, open the file with your preferred graphics editing software, expand the frame, and add your new icon(s).

The interface file is found in interface/countryreligionview. Copy it over to a mod. Find the sprite named "GFX_hindu_deities_strip" within this file, and add a number of frames equal to the number of new icons you added to the graphics file.

Personal deity localisation[edit | edit source]

Localisation for personal deities is very simple:

shiva: "Shiva"
shiva_desc: "Shiva is the god of transformation through destruction and the Lord of Dance."

Church Aspects modding[edit | edit source]

A religion uses the Church Aspects mechanics if uses_church_power = yes is included as a line in its religion entry. Church Aspect files are found in the common/church_aspects path. Vanilla entries can be edited in common/church_aspects/00_church_aspects.txt, while new entries can either be added to that file or added to a new file in that folder.

Church Aspects file[edit | edit source]

Here is an example of an entry in a Church Aspects file:

organised_through_bishops_aspect = {
        cost = 100
        modifier = {
                development_cost = -0.05
        ai_will_do = {
                factor = 15
                modifier = {
                        factor = 1
                        is_at_war = no

The entry has three sections: a modifier, an effect, and instructions for AI use. The modifier and effect use any standard modifier/effect which scopes to a country. ai_will_do works in the usual way that it does in decision modding.

Church Aspects GUI[edit | edit source]

This section only applies if adding new religions that use church power.

In order for new religions to utilize custom church power aspects, you must edit the countryreligionview.gui in the interface MODNAME/interface folder (see the above section on icon and graphics modding). Each new religion that uses church power needs to have a section dedicated to it for the gui to work and not instantly crash the game upon either loading the religion in the first place or trying to use church power. Even if you don't plan on making any custom icons, this is a requirement for non-vanilla religions that use church power.

If the above is not done, the game will crash if you try to use any church aspects for custom religions.

Church Aspects localisation[edit | edit source]

Like personal deities, localisation for church aspects is very simple. Note that desc_ should be added before the rest of the string for description localisation.

organised_through_bishops_aspect: "Organised Through Bishops"
desc_organised_through_bishops_aspect: "Bishops used to be leader of a single church, confined to an urban area. Etc."

Centre of Reformation modding[edit | edit source]

A religion uses the Centre of Reformation mechanics if "will_get_center" is included as a trigger in its religion entry. If the trigger evaluates to true, the effect "will_get_center" can be used to add a centre of reformation to the country via event or "on_convert" effect. If "will_get_center" evaluates to false for the country, "add_reform_centre" on a province in that country will do nothing. Also note that centres of reformation can only appear on the same continent as the province defined as the "centre_of_religion" in your religion file. A religion must also have a center of reformation associated with it in /common/religious_conversions/00_religious_conversions.txt for it to use the center of reformation mechanic. Optionially another image can be assigned to the map icons by adding an entry to /interface/mapicons.gfx and changing the value in 00_religious_conversions.txt to the name of the entry added (can use a '.dds' file and have in the entry the path to that file but with '.tga') The first 'frame' of the image is used for provinces with that type of center of reformation, the second 'frame' for provinces being converted by centers of reformation of that type. (Needs verification) Centers of reformation religions must be added (even as a new religious group) to /common/religions/00_religions.txt rather than another file for it to work.

Attributes for the centres can be found in the defines.lua file (note: as of 1.27, Reformation Center base_conversion_speed can be found in common\religious_conversions\00_religious_conversions.txt):

Script Description
MAX_CHRISTIAN_RELIGIOUS_CENTERS How many centres of reformation can exist for each religion
MAX_RELIGIOUS_CENTER_SPREAD_DISTANCE The maximum distance a centre of reformation can convert an adjacent province
MONTHLY_CONVERSION_SPEED The percentage at which a centre converts a province per month

This means that the attributes above are common to all religions with centres of reformation.

The vanilla game adds centres in two ways: When the Protestant Reformation and Reformed Reformation events fire, one country is given a centre, and when converting to Protestant or Reformed, a centre of reformation is added if there is a viable province.

Centre of Reformation localisation[edit | edit source]

Script Description
CENTER_OF_REFORMATION The text to display for the effect "add_reform_centre"
REMOVE_CENTER_OF_REFORMATION The text to display for the effect "remove_reform_center"
CENTER_OF_REFORMATION_CENTER The text to display when hovering the mouse over a centre of reformation icon in a province
CENTER_OF_REFORMATION_CONVERT The text to display when hovering the mouse over a province being converted by a centre of reformation
CENTER_OF_REFORMATION_POSSIBLE The text to display when converting to a religion and the "will_get_center" clause evaluates to true, and the text to display for the effect "add_reform_centre" in the "on_convert" effect.
CENTER_OF_REFORMATION_NO_PROVINCE The text to display when converting to a religion and the "will_get_centre" clause evaluates to false
CENTER_OF_REFORMATION_IMPOSSIBLE The text to display when converting to a religion and the number of centres is already at maximum
CENTER_OF_REFORMATION_END Does not appear to be in-game
CENTER_OF_REFORMATION_NOT_AVAILABLE The text to display when converting to a religion without the centres of reformation mechanic
CENTER_OF_REFORMATION_HAS_ALREADY The text to display when converting to a religion and you already have a centre of reformation
CENTER_OF_REFORMATION_CONVERT_PROGRESS The text to display when hovering the mouse over a progress bar above a province's religion icon showing its conversion by a centre of reformation
CENTER_OF_REFORMATION_CONVERT_END Does not appear to be in-game

Sound effects[edit | edit source]

There are various sound effects associated with every religion. For instance: start_convert_$RELIGION$, religion_$RELIGION$, defender_of_the_$RELIGION$_faith and $RELIGION$_blessings. See Sound_modding.

Vanilla religion names[edit | edit source]

Some religions have a different religion id than expected, the table below has all vanilla religions and their corresponding ids

In game name id
Catholic catholic
Protestant protestant
Reformed reformed
Orthodox orthodox
Coptic coptic
Hussite hussite
Sunni sunni
Ibadi ibadi
Shia shiite
Mahayana mahayana
Vajrayana vajrayana
Shinto shinto
Theravada buddhism
Confucian confucianism
Hindu hinduism
Sikh sikhism
Inti inti
Nahuatl nahuatl
Animalist animism
Fetishist shamanism
Totemist totemism
Mayan mesoamerican_religion
Norse norse_pagan_reformed
Tengri tengri_pagan_reformed
Alcheringa dreamtime
Jewish jewish
Zoroastrian zoroastrian

Documentation EffectsTriggersModifiersScopesVariablesLocalisationCustomizable localizationRun files
Scripting Scripted functionAdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEmpire of ChinaEstatesEventsFactionsGovernmentGreat projectsHistoryHoly Roman EmpireIdea groupsInstitutionsMercenariesMissionsModifiersNation designerOn ActionsParliamentPeace treatiesPoliciesRebel typesReligionSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapNation designerRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe ValidatorRun files
Guides Adding a provinceSave-game editingScripting Tutorial