Flag modding

Country flags in Victoria 3 are selected by triggers from scripted coats of arms which are made up of one or more graphical elements.

Flag definition

Country flag selection is scripted in common/flag_definitions. Each country with one or more defined flags should have its TAG listed as a block with a flag_definition block for each possible flag. The following example is taken from common/flag_definitions/00_flag_definitions.txt.

# FLAG_DEFINITION_LIST = {		# countries search for a list with the same name as their tag, the DEFAULT list is always included, if no flag definition is applicable for a country then its tag is used a COA_KEY
# 	includes = ANOTHER_LIST		# includes another list in this list, can be repeated
# 
# 	flag_definition = {			# the flag definitions that make up this list, can be repeated
# 		coa = [list] COA_KEY	# main flag, optional list keyword denotes a coa template
# 		allow_overlord_canton = yes				# default no
# 		coa_with_overlord_canton = <[list] coa>	# flag where a canton can be placed, optional list keyword same as above, defaults to coa
# 		overlord_canton_offset = { x y }		# canton placement offset, default { 0 0 }
# 		overlord_canton_scale = { x y }			# canton placement scale, default { 0.5 0.5 }
# 		subject_canton = [list] COA_KEY	# canton applied to subjects by this country, optional list keyword same as above
# 
# 		priority = value		# valid flag definition with the highest priority applies
# 		trigger = {}			# a trigger that determines if this flag definition is valid, see below for scope
#       allow_revolutionary_indicator = no      # Default = yes. If yes, a temporary revolutionary indicator will appear while the country is revolutionary
#       revolutionary_canton = [list] COA_KEY   # Optional. Default = default_revolutionary_canton. Defines which flag should be used as canton while this country is revolutionary
# 	}
# }

The following is an example from the vanilla file with added commentary.

ALD = { # Algeria
	flag_definition = {
		coa = ALD
		subject_canton = ALD					#If the game rule for modifying subject flags is on, this COA is added to the canton of this country's subjects, it does not need to match the main flag
		allow_overlord_canton = yes				#If the game rule for modifying subject flags is on, can another country's canton be added to this flag set
		coa_with_overlord_canton = ALD_subject	#If the game rule for modifying subject flags is on, alternate COA for adding the overlords canton, e.g. to move central emblems to one side
		priority = 1							#Highest, i.e. largest priority definition which passes its triggers is used
	}
	flag_definition = {
		coa = ALD_republic
		subject_canton = ALD_republic
		priority = 10
		trigger = { 
			coa_def_republic_flag_trigger = yes	#Scripted triggers can be used, but note scope rules must still be respected
		}
	}
	flag_definition = {
		coa = ALD_subject_FRA
		priority = 30
		trigger = { 
			coa_def_french_ensign_trigger = yes
		}
	}	
}

If a country doesn't have a scripted flag definition list, it will search for a coat of arms with its tag as the key term, and failing that the game will generate a flag from scripted random elements.

Trigger scope rules

Flag definition triggers have three possible states and a number of key terms.

	Existing country	Releasing a country	Forming a country
Root	Definition	Definition	Definition
Target	Country	N/A	N/A
Initiator	N/A	Player	Player
Actor	Country	Player	Player
Overlord	Country's direct overlord, if any	Player	Player's direct overlord, if any

Coat of arms

You can find all in-game flags on this wiki at List of flags; that page does not include dynamic overlord cantons.

Coats of arms (CoA) are the actual flags, which are referenced in the flag definition files common/coat_of_arms/coat_of_arms. A CoA is scripted a named block with a list of graphical elements, namely patterns, colored emblems, textured emblems, and subs. These elements typically have a base dimension of 768 × 512 pixels, though some are 256×256 in dimension. Except for subs, which are references to other CoAs, these are image files which can be found in game/gfx/coat_of_arms/colored_emblems, game/gfx/coat_of_arms/patterns and game/gfx/coat_of_arms/textured_emblems.

As an example, the definition on the left generates the flag on the right.

…/game/common/coat_of_arms/coat_of_arms/02_countries.txt SWE_union_mark_canton = { pattern = "pattern_solid.tga" color1 = "blue" color2 = "yellow" sub = { parent = "sub_SWE_union_mark" instance = { scale = { @canton_scale_sweden_x @canton_scale_sweden_y } } } colored_emblem = { texture = "ce_cross_sweden.dds" color1 = color2 color2 = color2 } }

By itself the sub CoA is …/game/common/coat_of_arms/coat_of_arms/01_subs.txt sub_SWE_union_mark = { # herring salad pattern = "pattern_per_saltire.dds" color1 = "red" color2 = "blue" color3 = "yellow" color4 = "white" colored_emblem = { texture = "ce_solid.dds" color1 = color3 color2 = color3 instance = { scale = { 1 @[1/5] } } } colored_emblem = { texture = "ce_solid.dds" color1 = color4 instance = { scale = { @[1/4.5] 1 } } mask = { 1 } } colored_emblem = { texture = "ce_solid.dds" color1 = color2 instance = { scale = { @[1/8] 1 } } mask = { 1 } } }

A simpler example is the flag of Scandinavia, the definition on the left generates the flag on the right.

…/game/common/coat_of_arms/coat_of_arms/02_countries.txt SCA = { pattern = "pattern_solid.tga" color1 = "red" color2 = "red" colored_emblem = { texture = "ce_bicolor_bottom.dds" color1 = "blue" color2 = "blue" } colored_emblem = { texture = "ce_cross_denmark.dds" color1 = "white" color2 = "white" instance = { scale = { 1.6 1.6 } position = { 0.6 0.5 } } } colored_emblem = { texture = "ce_cross_denmark.dds" color1 = "blue" color2 = "blue" instance = { scale = { 1.4 1.4 } position = { 0.565 0.5 } } } colored_emblem = { texture = "ce_cross_denmark.dds" color1 = "yellow" color2 = "yellow" instance = { scale = { 1.0 1.0 } position = { 0.5 0.5 } } } }

The color names are defined in common/named_colors, where they are defined either as HSV or decimal RGB values.

Pattern

Each CoA starts with a pattern as its base. Patterns are found in gfx/coat_of_arms/patterns. Each pattern image acts as a mask, with its red color being replaced by color1, and its yellow color – if present – by color2, and a few patterns have a third white color replaced by color3. In addition to setting the flag's base colors, the pattern can mask elements of a colored emblem, hiding the emblem where the pattern and emblem intersect.

Patterns are added to a CoA with pattern = "pattern_name" including the file extension in pattern_name.

It is possible to assign named colors to color# which are not used by the pattern, these can be used in colored emblem elements. Similarly, it is possible to define two different color# to have the same named color.

Emblem

Emblems are more detailed designs that are layered on top of patterns and each other. They are layered from first to last definition, such that the earliest defined emblem is overlaid by the rest and only the finally defined emblem is fully visible if there is any overlap. There are two types of emblems: colored emblems and textured emblems.

Colored emblems are similar to patterns, with the emblem image acting as a mask for the defined colors. Colored emblems use a blue color for color1, a green/teal color for color2, and a pink color for color3.

Textured emblems are premade images, which are added to the CoA as is. These are useful for adding more intricate details, such as elaborate seals or heraldry to a flag.

Emblems are added to a CoA by adding a block with the type of emblem, either colored_emblem or textured_emblem, then defining the emblem with texture = "emblem_name" including the file extension like with patterns. Colored emblems need a number of colors equal to amount used in the emblem image. Both types of emblems can be modified by including one or more instance blocks. Each instance block adds the emblem to the flag once and allows for manipulating its scale, position, and rotation.

Scale modifies the size of the emblem as a percentage, independently in the x and y axes; position moves the emblem so its center point is positioned relative to the top left of the flag, and rotation rotates the emblem clockwise by that number of degrees.

Sub

Sub treats another CoA like a textured emblem, with the main difference being that the CoA is called with parent = "CoA_Name" and a CoA with a sub as part of its definition can't be used as a sub in another CoA (no nesting or recursion). Sub can still use instance, to duplicate and/or modify the incorporated CoA.

Script terms

The following table is a list of script terms used in defining coats of arms.

Term	Function	Example	Used in
			Base	Colored emblem	Textured emblem	Sub
pattern	Calls a pattern file	pattern = "pattern_solid.tga"
color#	Defines a color for a pattern or colored emblem Refers to a named color, or previously defined color	color1 = "red" color1 = color3
colored_emblem	Begins a colored emblem block	colored_emblem = { … }
textured_emblem	Begins a textured emblem block	textured_emblem = { … }
sub	Begins a sub block	sub = { … }
texture	Calls an emblem file	emblem = "ce_solid.dds"
parent	Calls a CoA definition	parent = "sub_SWE_union_mark"
instance	Begins an instance block	instance = { … }
mask	Selects which part of the pattern shows the emblem or sub	mask = { 1 }

The following are terms used inside of an instance block. All values inside these terms can be replaced by prescripted values with @prescripted_value_name or use mathmatical expressions with @[expression]. The latter is especially useful for values such as 1/3 or 1/6 that are imprecise in fixed decimal. For example, 1/3 would be written as @[1/3].

Term	Function	Example	Example explanation
scale	Scales the instance as a percentage of default size in x y format	scale = { 0.5 0.25 }	Scaled to half size horizontally and quarter size vertically
position	Moves the center of the instance as a percentage relative to the top left of the base in x y format	position = { 0.25 0.75 }	Centered one quarter from left and three quarters from top of base
rotation	Rotates the instance clockwise by that many degrees (counterclockwise for negative values)	rotation = { 45 }	Rotated 45 degrees clockwise

References

Modding

Map

Map

Audio

Music • Sound