Religion modding

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

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

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

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

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

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

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

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 = {
        hinduism
}

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

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

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

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

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

Icon graphics

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

• country_icon_religion.dds seen in diplomacy view.
• icon_religion.dds seen in religion tab.
• icon_religion_small.dds seen in province view.
• province_view_religion.dds 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 icon_religion_small.dds and province_view_religion.dds are equivalent.

Icon interface

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

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

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

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

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

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/hindu_deities_strip.dds. 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

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

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

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

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

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

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

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_RELIGION_NOT_POSSIBLE	Does not appear to be in-game
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

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

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

Modding

Audio

Music • Sound