Ship modding

Version

Please help with verifying or updating older sections of this article. At least some were last verified for version 3.0.

This article is for the PC version of Stellaris only.

This page is about modding of Ships, Sections and Components.

Basics

Ships consists of three basic components:

1. ship_size – #Ship Sizes
2. section_template – #Ship Sections
3. component_template – #Components

These three things are then used by a ship_design to formulate a complete ship. – #Global Ship Designs

A ship_size has a list of slots that can have sections attached to them. Each slot has a name and specify a locator where the section will be attached graphically.

Example:

	section_slots = {
		"north"	= { locator = "part1" }
		"west"	= { locator = "part2" }
		"east"	= { locator = "part3" }
		"south"	= { locator = "part4" }
	}

A section_template then specify what ship_sizes they are compatible with and which slots they fit on.

Example:

	ship_size = name_of_a_shipsize
	ship_size = name_of_another_shipsize
	fits_on_slot = "north"
	fits_on_slot = "a_slot_in_some_other_shipsize"

Sections also specify slots for components. – #Component Slot Templates

Example:

 	component_slot = {
 	    name = "LARGE_GUN_01"
 	    slot_size = large
 	    slot_type = weapon
 	    locatorname = "large_gun_01"
 	}
 	small_utility_slots	= 1
 	medium_utility_slots = 2
 	large_utility_slots	= 3

Components are placed by the ship_design in a way that sizes match and weapon components go on slot_type = weapon and vice versa.

Graphics

Graphically the ship is structured the same way as above. A core entity is selected based on gfx_culture and ship_size. The name of the entity should be: <gfx_culture>_<ship_size>_entity

Example:

mammalian_01_corvette_entity

NOTE: If you don't want to use graphical cultures simply leave that part out of your entity name! E.g. corvette_entity will be used if the current graphical culture (or its fallback) fail to find an entity with their name as a prefix.

For ships with multiple sections this entity is usually invisible (exception is military stations) but holds the skeleton. Animations are usually done on the core entity. This core entity should have the "part1", "part2" etc. locators referenced by the ship_size slots.

Each section_template specify a name for their entity directly in their script files (common/section_templates/). The game then prepends the name of the gfx_culture to that name when getting an actual entity.

Example:

(common/component_templates/):

			section_template = {
					...
					entity = "some_entity"
			}

The game will look for mammalian_01_some_entity if the current gfx_culture is mammalian_01, the section entity is then attached to a locator on the core entity specified by the slot (like "part1").

Weapon entities are similar to section entities, with the differences being that they attach to the locator specified in the section_template and component_slot scripts. The name would be <gfx_culture>_<entity found in component_template>_entity. Weapon component entities should also have a locator named turret_muzzle_01 (this is specified in defines.lua as NGraphics::SHIP_TURRET_PROJECTILE_SPAWN_LOCATOR).

Ship Sizes

By ship sizes the game classifies all ships and stations. Ship sizes are defined at common/ship_sizes/xyz.txt.

Data Structure

Property	Military Ships	Civilian Ships	Starbases	Defense Platforms	Civilian Stations
graphical_culture = { mammalian_01 … }	A list of Graphical Cultures this ship size is valid to have. Can also specify as graphical_culture = no to indicate that this ship size doesn't need Graphical Cultures.
entity = some_entity	Defines the graphical entity used, replacing the default SHIPSIZE_entity (or GFX_CULTURE_SHIPSIZE_entity) lookup.
max_hitpoints = <int>	Defines the base Hull Points of this ship size.
combat_disengage_chance = <float>	This property multiplies the chance this ship disengages in battle.		Vanilla always have 0 or leave this property undefined.
max_speed = <int>	Defines the base speed, acceleration and rotation speed of this ship size.		Vanilla Starbases usually have 0 for these properties, except for the Juggernaut.	Defense Platforms also need these properties because they need to move from the Starbase to their defense position.	Vanilla Civilian Stations always have 0 for these properties.
acceleration = <float>
rotation_speed = <float>
formation_priority = <int>	Ships with higher formation priority trends to go ahead of the rest of the fleet.
collision_radius = <int>	The radius other ships will try to avoid colliding with.
modifier	A block of Modifiers to be added to the ships of this size. These modifiers will come to effect even before the actual ships are built, you can see these in the Ship Designer. Only the following modifiers are allowed here. ship_evasion_(add/mult) ship_speed_mult & ship_base_speed_mult ship_(hull/armor/shield)_(add/mult) & ship_(hull/armor/shield)_regen_add_(static/perc) ship_weapon_damage & <weapon slot size>_weapon_damage_mult ships_upkeep_mult & ships_<resource type>_upkeep_mult ship_piracy_suppression_add Starbases can also use the following modifiers here. starbase_(module/building/defense_platform/shipyard)_capacity_add starbase_(trade_collection_range/protection_range/protection)_add
ship_modifier	Another block of Modifiers to be added to the ships of this size. Modifiers like ship_fire_rate_mult and ship_weapon_range_mult go here.
size_multiplier	How large should the fleet battle AI consider this ship of.
	This also determines the number of Command Points needed to add this Ship Design to a Fleet.	Vanilla Civilian Ships always have 1 for this property.	Vanilla Starbases always have 4 for this property.	This also determines the number of Defense Platform Capacities this Defense Platform will take up from a Starbase.	Vanilla Civilian Stations always have 1 for this property.
combat_size_multiplier	How large should the fleet battle AI consider this ship of, overwriting the size_multiplier.
fleet_slot_size	This determines the order this ship size appears in a fleet, with Corvettes having 1 up to Titans having 8.
num_target_locators	⁇
is_civilian = <yes/no>		Vanilla always have is_civilian = yes. Other ship sizes have either is_civilian = no or just have this property undefined, except for the Observation Station being yes.
valid_target_aggressive_stance = <yes/no>	Determines should this ship be ignored by a Military Fleet in aggressive stance. Among vanilla ship sizes, only Civilian Ships and Civilian Stations have valid_target_aggressive_stance = no.
build_block_radius = <int>				Since Military Stations have been reworked, it’s still unclear what’s the use of this property for now.
is_space_station = <yes/no>				Vanilla always have is_space_station = yes. Other ship sizes have either is_space_station = no or just have this property undefined.
is_space_object = <yes/no>	Determines should this ship size have trailers when the ships move in the Space. Space monsters usually have is_space_object = yes.
can_be_inspected = <yes/no>	Determines should Designs of this ship size can be inspected by the player. Some space monsters have can_be_inspected = no.
icon_frame = <int>	Determines the index of the icon of this ship size in a shared icon file.
is_designable = <yes/no>	Determines should this ship size be designable in the Ship Designer. Among vanilla ship sizes, buildable Military Ships, the Juggernaut and buildable Defense Platforms have is_designable = yes.
enable_default_design = <yes/no>	Determines should an Empire start with an auto-generated design of this ship size. All buildable ship sizes have enable_default_design = yes, regardless of they are designable or not, or the AI will not be able to build this.
can_have_federation_design = <yes/no>	Determines if this ship can have a federation design. Among vanilla ship sizes, only buildable Military Ships and the Juggernaut have can_have_federation_design = yes, except for the Colossus being without it.
components_add_to_cost = <yes/no>	Determines should the Ship Construction Cost and the ship upkeep take Ship Components and Ship Sections into account. Among vanilla ship sizes, only undesignable but buildable ship sizes have components_add_to_cost = no.
auto_upgrade = <yes/no>	Determines should the design of this ship size automatically upgrade based on the recent technologies. Existing ships will also be upgraded. Among vanilla ship sizes, only Civilian Ships and Civilian Stations have auto_upgrade = yes, except for the Observation Station being without it.			Determines should the design of this ship size automatically upgrade based on the recent technologies. Existing ships will also be upgraded. Among vanilla ship sizes, only Civilian Ships and Civilian Stations have auto_upgrade = yes, except for the Observation Station being without it.
can_disable = <yes/no>	Determines should this ship be disabled rather than be destroyed if at low health. Among vanilla ship sizes, only buildable Starbases except for the Juggernaut have can_disable = yes.
flip_control_on_disable = <yes/no>	Determines can this ship be captured after it’s disabled. Among vanilla ship sizes, only buildable Starbases except for the Juggernaut have flip_control_on_disable = yes.
default_behavior = <ship behavior>	Determines the default ship behavior the auto generated designs should try to pick when choosing the combat computer component.
section_slots = { <section_slot_name> = { locator = <locator name> } }	Determines the Sections needed for this ship size. The locators are pointers on the ship entity, see Graphics modding for details.
base_buildtime = <int>	Days it takes to build this ship / station or upgrade into this starbase.				Vanilla civilian stations have this property undefined.
prerequisites = { tech_xxx }	A list of Technologies required to design and build this ship size or upgrade existing Starbases into this level.
class	shipclass_military shipclass_military_special (the Colossus)	shipclass_constructor shipclass_colonizer shipclass_science_ship shipclass_transport	shipclass_starbase	shipclass_military_station	shipclass_mining_station shipclass_research_station shipclass_observation_station
construction_type	starbase_shipyard		Starbases usually have this field undefined, except the Juggernaut has starbase_shipyard.	starbase_defenses
potential_construction	A block of Conditions to check should this ship size appear in the construction list of a Starbase or Megastructure. (Starbase or Megastructure scope, use is_scope_type to check scope type; FROM is the builder empire)		Starbases usually have this field undefined, except for the Juggernaut.	The same. Vanilla Defense Platforms only allow Starbases to build them.
possible_construction	A block of Conditions to check can this ship size be built by a Starbase or Megastructure. If evaluated false, the construction option is still visible but grayed out with a tooltip. (Starbase or Megastructure scope, use is_scope_type to check scope type; FROM is the builder empire)			The same. Among vanilla Defense Platforms, the Ion Cannon can only be built by Citadel-level Starbases.
resources	An Economy Unit to determine the construction cost and upkeep of this ship. This is the final cost if this ship size has components_add_to_cost = no. Although vanilla unused, resource productions is also allowed here.
min_upgrade_cost = { <resource key> = <int> }	The minimal cost required to upgrade this ship. Used to prevent zero-cost upgrades by shifting from a Component to another of exactly same cost.			The same.
empire_limit = { base = <int> (max = <int> naval_cap_div = <int>) }	Determines the max number of ships of this size an empire can have at the same time. The number is base plus empire naval capacity divided by naval_cap_div, rounded down, at most max.
required_component_set = <component set key>"	Requires a core component with a Component Set. Multiple allowed. While designing by the Ship Designer, these will be displayed on the right.

Examples

Corvette

0

corvette = {
	formation_priority = @corvette_formation_priority
	max_speed = @speed_very_fast
	acceleration = 0.35
	rotation_speed = 0.1
	collision_radius = @corvette_collision_radius
	max_hitpoints = @corvette_hp
	modifier = {
		ship_evasion_add = @corvette_evasion
		ship_piracy_suppression_add = 10
	}
	size_multiplier = 1
	fleet_slot_size = 1
	section_slots = { "mid" = { locator = "part1" } }
	num_target_locators = 2
	is_space_station = no
	icon_frame = 2
	base_buildtime = @corvette_build_time
	can_have_federation_design = yes
	enable_default_design = yes	#if yes, countries will have an auto-generated design at start

	default_behavior = swarm

	prerequisites = { "tech_corvettes" }

	combat_disengage_chance = 1.00

	class = shipclass_military
	construction_type = starbase_shipyard
	required_component_set = "power_core"
	required_component_set = "ftl_components"
	required_component_set = "thruster_components"
	required_component_set = "sensor_components"
	required_component_set = "combat_computers"

	resources = {
		category = ships
		upkeep = {
			energy = @corvette_upkeep_energy
			alloys = @corvette_upkeep_alloys
		}
	}

	min_upgrade_cost = {
		alloys = 1
	}
}

Colossus

0

colossus = {
	formation_priority = @colossus_formation_priority
	max_speed = @speed_very_slow
	acceleration = 0.2
	rotation_speed = 0.15
	collision_radius = @colossus_collision_radius
	max_hitpoints = @colossus_hp
	modifier = {
		ship_evasion_add = @colossus_evasion
	}
	size_multiplier = 32
	fleet_slot_size = 32
	section_slots = { "ship" = { locator = "frame_ship" } }
	num_target_locators = 4
	is_space_station = no
	icon_frame = 7
	base_buildtime = @colossus_build_time
	can_have_federation_design = no
	enable_default_design = yes	#if yes, countries will have an auto-generated design at start

	prerequisites = { "tech_colossus" }

	class = shipclass_military_special
	construction_type = starbase_shipyard
	required_component_set = "power_core"
	required_component_set = "ftl_components"
	required_component_set = "thruster_components"
	required_component_set = "combat_computers"

	potential_construction = {
		OR = {
			is_scope_type = starbase
			AND = {
				is_scope_type = megastructure
				OR = {
					is_megastructure_type = mega_shipyard_3
					is_megastructure_type = mega_shipyard_restored
				}
			}
		}
	}

	possible_construction = {
		custom_tooltip = {
			fail_text = starbase_citadel_trigger
			OR = {
				AND = {
					is_scope_type = megastructure
					OR = {
						is_megastructure_type = mega_shipyard_3
						is_megastructure_type = mega_shipyard_restored
					}
				}
				AND = {
					is_scope_type = starbase
					has_starbase_size >= starbase_citadel
				}
			}
		}
		custom_tooltip = {
			fail_text = starbase_colossal_yards_trigger
			OR = {
				AND = {
					is_scope_type = megastructure
					OR = {
						is_megastructure_type = mega_shipyard_3
						is_megastructure_type = mega_shipyard_restored
					}
				}
				AND = {
					is_scope_type = starbase
					has_starbase_building = colossus_yards
				}
			}
		}
	}

	empire_limit = {
		base = 1
	}

	resources = {
		category = ships
		cost = {
			alloys = 10000
		}
		upkeep = {
			energy = @colossus_upkeep_energy
			alloys = @colossus_upkeep_alloys
		}
	}

	min_upgrade_cost = {
		alloys = 10
	}
}

Juggernaut

0

juggernaut = {
	formation_priority = @juggernaut_formation_priority
	max_speed = @speed_very_slow
	acceleration = 0.2
	rotation_speed = 0.15
	collision_radius = @juggernaut_collision_radius
	max_hitpoints = @juggernaut_hp
	modifier = {
		ship_evasion_add = @juggernaut_evasion
		starbase_shipyard_capacity_add = 2
	}

	base_buildtime = @juggernaut_build_time
	resources = {
		category = ships
		upkeep = {
			energy = @juggernaut_upkeep_energy
			alloys = @juggernaut_upkeep_alloys
		}
	}

	combat_size_multiplier = 5
	size_multiplier = 32
	fleet_slot_size = 32
	section_slots = {
		"core" = { locator = "part1" }
	}

	potential_construction = {
		OR = {
			AND = {
				is_scope_type = starbase
				NOT = { has_starbase_size = juggernaut }
			}
			AND = {
				is_scope_type = megastructure
				OR = {
					is_megastructure_type = mega_shipyard_3
					is_megastructure_type = mega_shipyard_restored
				}
			}
		}
	}

	possible_construction = {
		custom_tooltip = {
			fail_text = starbase_citadel_trigger
			OR = {
				AND = {
					is_scope_type = megastructure
					OR = {
						is_megastructure_type = mega_shipyard_3
						is_megastructure_type = mega_shipyard_restored
					}
				}
				AND = {
					is_scope_type = starbase
					has_starbase_size >= starbase_citadel
				}
			}
		}
		custom_tooltip = {
			fail_text = starbase_colossal_yards_trigger
			OR = {
				AND = {
					is_scope_type = megastructure
					OR = {
						is_megastructure_type = mega_shipyard_3
						is_megastructure_type = mega_shipyard_restored
					}
				}
				AND = {
					is_scope_type = starbase
					has_starbase_building = colossus_yards
				}
			}
		}
	}

	empire_limit = {
		base = 1
	}

	num_target_locators = 0
	can_have_federation_design = yes
	enable_default_design = yes	#if yes, countries will have an auto-generated design at start
	can_disable = no
	icon_frame = 7
	ship_class_icon_frame = 35

	default_behavior = carrier

	prerequisites = { "tech_juggernaut" }
	class = shipclass_starbase
	construction_type = starbase_shipyard

	required_component_set = "power_core"
	required_component_set = "sensor_components"
	required_component_set = "combat_computers"
	required_component_set = "ftl_components"
	required_component_set = "thruster_components"
	required_component_set = "ship_aura_components"

	min_upgrade_cost = {
		alloys = 50
	}
}

Ship Sections

Ships consist of Ship Sections. They are defined at common/section_templates/xyz.txt.

Data Structure

Property	Description
key = <localisation key>	Identification key of this section.
ship_size = <ship size key>	Specifies the compatible ship size. Multiple allowed.
fits_on_slot = <section_slot_name>	Specifies the compatible section slot name. Multiple allowed.
should_draw_components = <yes/no>	If no, weapon components on this Ship Section will not have entities (turrets).
entity = <entity key>	Specifies the entity of this section.
icon = <GFX entry>	Although most of the vanilla sections specified this as "GFX_ship_part_core_mid", there is no where for this to be seen.
component_slot	A weapon slot. Multiple allowed. They appear in the Ship Designer in the order they are defined here.
name = <something>	Identification of this weapon slot. No duplications allowed.
template = <component slot template>	The Component Slot Template used for this weapon slot. This determines the weapon type (regular weapon or strike craft), weapon size (small, medium or large), and turret entity.
locatorname = <locator name>	The locators are pointers on the Ship Section entity and indicates where should the turret be, see Graphics modding for details.
small_utility_slots = <int> medium_utility_slots = <int> large_utility_slots = <int> aux_utility_slots = <int>	The number of utility slots of each size of this Ship Section. Multiple allowed. They appear in the Ship Designer in the reversed order they are defined here.
resources	An Economy Unit to determine the construction cost and upkeep of this Ship Section.
ai_weight	Determines how likely the AI and auto-designer will choose this Ship Section. (Country scope)
prerequisites = { tech_xxx }	A list of Technologies. Unlike other game objects, Ship Sections only require ONE of the prerequisites, not all.

Default list of locator names

Playable "graphical cultures" sharing the same locator names for each section, this are:

Vanilla locator names

# CORVETTE
"CORVETTE_MID_M1S1" locator "small_gun_01"
"CORVETTE_MID_M1S1" locator "medium_gun_01"
"CORVETTE_MID_S3" locator "small_gun_01"
"CORVETTE_MID_S3" locator "small_gun_02"
"CORVETTE_MID_S3" locator "small_gun_03"
"CORVETTE_MID_S2PD1" locator "small_gun_01"
"CORVETTE_MID_S2PD1" locator "small_gun_02"
"CORVETTE_MID_S2PD1" locator "small_gun_03"

# DESTROYER
"DESTROYER_BOW_M1S2" locator "medium_gun_01"
"DESTROYER_BOW_M1S2" locator "small_gun_01"
"DESTROYER_BOW_M1S2" locator "small_gun_02"
"DESTROYER_BOW_S3" locator "small_gun_01"
"DESTROYER_BOW_S3" locator "small_gun_02"
"DESTROYER_BOW_S3" locator "small_gun_03"
"DESTROYER_BOW_L1" locator "large_gun_01"

# CRUISER
"CRUISER_BOW_L1" locator "large_gun_01"
"CRUISER_BOW_M1S2" locator "medium_gun_01"
"CRUISER_BOW_M1S2" locator "small_gun_01"
"CRUISER_BOW_M1S2" locator "small_gun_02"
"CRUISER_BOW_M2" locator "medium_gun_01"
"CRUISER_BOW_M2" locator "medium_gun_02"
"CRUISER_MID_S2HB" locator "small_gun_01"
"CRUISER_MID_S2HB" locator "small_gun_02"
"CRUISER_MID_L1M1" locator "large_gun_01"
"CRUISER_MID_L1M1" locator "medium_gun_01"
"CRUISER_MID_M3" locator "medium_gun_01"
"CRUISER_MID_M3" locator "medium_gun_02"
"CRUISER_MID_M3" locator "medium_gun_03"
"CRUISER_MID_M2S2" locator "medium_gun_01"
"CRUISER_MID_M2S2" locator "medium_gun_02"
"CRUISER_MID_M2S2" locator "small_gun_01"
"CRUISER_MID_M2S2" locator "small_gun_02"
"CRUISER_STERN_M1" locator "medium_gun_01"
"CRUISER_STERN_S2" locator "small_gun_01"
"CRUISER_STERN_S2" locator "small_gun_02"

# BATTLESHIP
"BATTLESHIP_BOW_L1M1S2" locator "large_gun_01"
"BATTLESHIP_BOW_L1M1S2" locator "medium_gun_01"
"BATTLESHIP_BOW_L1M1S2" locator "small_gun_01"
"BATTLESHIP_BOW_L1M1S2" locator "small_gun_02"
"BATTLESHIP_BOW_L2" locator "large_gun_01"
"BATTLESHIP_BOW_L2" locator "large_gun_02"
"BATTLESHIP_BOW_M1S2SHB" locator "medium_gun_01"
"BATTLESHIP_BOW_M1S2SHB" locator "small_gun_01"
"BATTLESHIP_BOW_M1S2SHB" locator "small_gun_02"
"BATTLESHIP_MID_L2M2" locator "large_gun_01"
"BATTLESHIP_MID_L2M2" locator "large_gun_02"
"BATTLESHIP_MID_L2M2" locator "medium_gun_01"
"BATTLESHIP_MID_L2M2" locator "medium_gun_02"
"BATTLESHIP_MID_L3" locator "large_gun_01"
"BATTLESHIP_MID_L3" locator "large_gun_02"
"BATTLESHIP_MID_L3" locator "large_gun_03"
"BATTLESHIP_MID_M4SHB" locator "medium_gun_01"
"BATTLESHIP_MID_M4SHB" locator "medium_gun_02"
"BATTLESHIP_MID_M4SHB" locator "medium_gun_03"
"BATTLESHIP_MID_M4SHB" locator "medium_gun_04"
"BATTLESHIP_MID_S4LHB" locator "small_gun_01"
"BATTLESHIP_MID_S4LHB" locator "small_gun_02"
"BATTLESHIP_MID_S4LHB" locator "small_gun_03"
"BATTLESHIP_MID_S4LHB" locator "small_gun_04"
"BATTLESHIP_STERN_L1" locator "large_gun_01"
"BATTLESHIP_STERN_M2" locator "medium_gun_01"
"BATTLESHIP_STERN_M2" locator "medium_gun_02"

Examples

Battleship XL Bow

0

ship_section_template = {
	key = "BATTLESHIP_BOW_M2S4"
	ship_size = battleship
	fits_on_slot = bow
	should_draw_components = yes
	entity = "battleship_bow_XL1_entity"
	icon = "GFX_ship_part_core_bow"

	prerequisites = { tech_energy_lance_1 tech_energy_lance_2 tech_arc_emitter_1 tech_arc_emitter_2 tech_mass_accelerator_1 tech_mass_accelerator_2 }

	ai_weight = {
		modifier = {
			factor = 10.0
			NOT = { is_preferred_weapons = weapon_type_explosive }
		}
		modifier = {
			factor = 0.1
			is_preferred_weapons = weapon_type_explosive
		}
	}

	component_slot = {
		name = "EXTRA_LARGE_01"
		template = "invisible_extra_large_fixed"
		locatorname = "xl_gun_01"
	}

	large_utility_slots = 3

	resources = {
		category = ship_sections
		cost = {
			alloys = @section_cost
		}
	}
}

Starbase Missile Defense Module

0

ship_section_template = {
	key = "MISSILE_STARBASE_SECTION"
	entity = "starbase_turret_section_entity"
	icon = "GFX_ship_part_core_mid"

	ship_size = starbase_outpost
	ship_size = starbase_starport
	ship_size = starbase_starhold
	ship_size = starbase_starfortress
	ship_size = starbase_citadel

	fits_on_slot = "1"
	fits_on_slot = "2"
	fits_on_slot = "3"
	fits_on_slot = "4"
	fits_on_slot = "5"
	fits_on_slot = "6"

	should_draw_components = yes

	component_slot = {
		name = "TORPEDO_01"
		template = "medium_missile_turret"
		locatorname = "medium_gun_01"
	}

	component_slot = {
		name = "TORPEDO_02"
		template = "medium_missile_turret"
		locatorname = "medium_gun_02"
	}
}

Component Slot Templates

Component Slot Templates are containers of actual Weapon Components attached to Section Templates, or to say "turrets". They are defined at common/component_slot_templates/xyz.txt.

Data Structure

Property	Weapon Component Slots	Strike Craft Slots
component	Only one is allowed. component = weapon	Only one is allowed. component = strike_craft
size	One of the following is allowed. : size = point_defence : size = small : size = medium : size = large : size = torpedo : size = extra_large : size = titanic : size = planet_killer	Only one is allowed. : size = large
entities	Determines the Turret Entities of this Component Slot Template. Define with pairs of component tags and entities.
is_fixed = <yes/no>	Default no. If yes, this "turret" cannot rotate and the entire ship will rotate to have this "turret" face the target.

Examples

Point Defense Turret

0

point_defence_turret = {
	size = point_defence
	component = weapon
	entities = {
		weapon_type_kinetic = "small_kinetic_gun_entity"
		weapon_type_energy = "turret_point_defence_entity"
	}
}

Invisible Extra Large "Turret"

0

invisible_extra_large_fixed = {
	size = extra_large
	component = weapon
	is_fixed = yes
}

Component Sets

Component Sets are groups of Components. They are defined at common/component_sets/xyz.txt.

There are two type of Component Sets.

• One is used to group weapon and utility components together to be used by Ship Designers that are usually the same type of Components of different sizes unlocked by a same Technology;
• Another is used to group all components that fix a Core Component Slot which can be unlocked by different technologies.

Core Components can be weapons and strike crafts, but such a weapon cannot fire and it doesn't have a turret entity. If it was a Planet Killer weapon, it can still be used but has no graphics.

Data Structure

Property	Designer Component Sets	Core Component Sets
key = <localisation key>	Identification key of this Component Set.
required_component_set = <yes/no>	Must be required_component_set = no or leave this undefined.	Must be required_component_set = yes. ship_size must have atleast 1 thing from component_templates can be use, or this ship are unable to be build and break auto-generated.
icon = <GFX entry>	Determines the icon of this component slot.	Vanilla always define these but these is always overwritten by individual Core Components.
icon_frame = <int>	Vanilla always have icon_frame = 1. Actual usage is unclear.

Examples

Core Component Set: "Combat Computers"

0

component_set = {
	key = "combat_computers"

	required_component_set = yes
	icon = "GFX_ship_part_computer"
	icon_frame = 1
}

Designer Component Set: "Red Lasers"

0

component_set = {
	key = "RED_LASER"

	icon = "GFX_ship_part_laser_1"
	icon_frame = 1
}

Components

Components are attachments to ships for a weapon or a functional extension. They are defined at common/component_templates/xyz.txt.

Data Structure

Property	Weapon Components	Strike Craft Components	Utility Components
key = <localisation key>	Identification key of this Component.
icon = <GFX entry>	Determines the icon of this Component, overwriting that of the Component Set.
icon_frame = <int>	Vanilla always have icon_frame = 1. For sprite sheet icons.
size	One of the following is allowed. : size = point_defence : size = small : size = medium : size = large : size = torpedo : size = extra_large : size = titanic : size = planet_killer Without the  Apocalypse DLC, ship designs with a Titanic or Planet Killer weapon cannot be saved as well as the weapons cannot be picked by a generated design.	Only one is allowed. : size = large	One of the following is allowed. : size = small : size = medium : size = large : size = aux
type	One of the following is allowed. type = instant type = point_defence type = missile type = planet_killer Kinetic and Energy weapons are "instant". Though their graphics might look like that their projectiles need time to reach the target, the actual damage is done in an instant. Point defenses is a stronger variant that it can target missiles and strike crafts. Missiles have additional properties to specify missile stats, like speed, retarget range, missile hitpoints, and missile evasion. Planet killers are no regular weapons. They can't be used in fleet battles, but can be used on planets by Colossi to trigger events. Without the  Apocalypse DLC, the fleet command to invoke the Planet Killer weapon can't be used.
weapon_type		One of the following is allowed. type = instant type = point_defence
entity = <entity key>		Determines what should the Strike Crafts be look like.
projectile_gfx = <projectile graphic key>	Specifies the projectile graphic of this Component.
prio_projectile = <yes/no>	If yes, the projectile graphic of this Component will be preferentially displayed if there are too many graphics to be displayed and some of them must be ignored.
planet_destruction_gfx = <GFX entry>	Only relevant to Planet Killer weapons. Specifies the projectile graphic.
tags = { component_tags … }	Specifies the list of Component Tags. This determines what kind of modifiers can affect this weapon. For example, if a weapon has both the kinetic tag and the energy tag, repeatable technologies that affect either will both affect this weapon.
ai_tags = { component_tags … }	What role should the AI consider this weapon to be playing.
ai_tag_weight = <float>	Multiplies the AI weight gained through the ai_tags. Vanilla use this for Missile components for unknown reason.
prerequisites = { tech_xxx }	Technology prerequisites of this Component.
power = <int>	If this value is positive, this Component will generate that much power. If this value is negative, this Component will consume that much power.
resources	An Economy Unit to determine the construction cost and upkeep of this Component.
modifier	A block of Modifiers to be added to the ship. These modifiers will come to effect even before the actual ships are built, you can see these in the Ship Designer. Only the following modifiers are allowed here. ship_evasion_(add/mult) ship_speed_mult & ship_base_speed_mult ship_(hull/armor/shield)_(add/mult) & ship_(hull/armor/shield)_regen_add_(static/perc) ship_weapon_damage & <weapon slot size>_weapon_damage_mult ships_upkeep_mult & ships_<resource type>_upkeep_mult ship_piracy_suppression_add Starbases can also use the following modifiers here. starbase_(module/building/defense_platform/shipyard)_capacity_add starbase_(trade_collection_range/protection_range/protection)_add It’s not recommended to give Weapon Components and Strike Craft Components with modifiers, because the tooltips might go wild and confusing.
ship_modifier	Another block of Modifiers to be added to the ship. Modifiers like ship_fire_rate_mult and ship_weapon_range_mult go here. It’s not recommended to give Weapon Components and Strike Craft Components with modifiers, because the tooltips might go wild and confusing.
ship_behavior = <ship behavior>		Determines the behavior pattern of the Strike Crafts.	Determines the behavior pattern of this ship.
component_set = <component set key>	Specifies the Component Set of this Component.
upgrades_to = <component key>	Specifies the direct upgrade of this Component. When the direct upgrade has been unlocked, this Component will be considered obsolete and will be hidden from Ship Designer unless manually toggled off the "Hide Obsolete" option, and will be automatically replaced by the advanced variant for all existing Ship Designs that is set to auto-upgrade components. For ship sizes that are set to auto_upgrade = yes, existing ships will instantly be upgraded for free. Starbases will redesign themselves and might pick different kind of Weapons.
class_restriction = { shipclass_military … }	Only ships of Ship Classes listed here can equip this Component. Note that Colossi is shipclass_military_special and the Juggernaut and Starbases are shipclass_starbase.
size_restriction = { <ship size keys> }	Only ships of ship sizes listed here can equip this component.
slot_restriction = { <slot template keys> }	Implemented since Stellaris v2.7.1. Only Slot Templates listed here can hold this Component.
hidden = <yes/no>	Optional, default no. If yes, this Component is hidden from the Ship Designer and Generated designs and the AI will also be unable to pick this. Only global ship designs can have this component.
valid_for_country	Define it like this. valid_for_country = { conditions... } If all conditions are true, it's valid. To be confirmed: Generated designs and the AI don't respect this. It was used for Stellaris v1.8 to prevent the Player from using Sapient Combat Computer, while setting the AI policy to outlawed. It’s unused for now but still functional.
friendly_aura hostile_aura			Aura definitions. Head to the examples for details. With system_wide = yes, the aura affects all friendly or enemy ships in the same system. With system_wide = no or undefined, the aura affects all friendly ships in the same fleet or all enemy ships that are in battle with the aura bearer. The aura range property does nothing. The aura graphic property seemingly does nothing as well.
should_ai_use = <yes/no>	If no, AI cannot use this. Among vanilla Components, only empty FTL driver use this.
ftl = <yes/no>			If yes, this ship can use the hyperlane and go FTL.
jumpdrive = <yes/no>			If yes, this ship can use the jumpdrive command.
ftl_inhibitor = <yes/no>			If yes, this ship can be FTL inhibitor.
damage = { min = <float> max = <float> }	Determines the damage.
windup = { min = <int> max = <int> }	The ticks it takes for this Weapon to get ready to fire. (1 day = 10 ticks)
total_fire_time = <int>	The ticks it takes for this Weapon to cooldown before it’s next fire. (1 day = 10 ticks)
cooldown = <int>		The ticks it takes for this Weapon to cooldown before it’s next fire. (1 day = 10 ticks)
hull_damage = <float> shield_damage = <float> shield_penetration = <float> armor_damage = <float> armor_penetration = <float>	Determines the damage efficiencies and penetration rates.
range = <int> accuracy = <float> tracking = <float>	Determines the range, accuracy and tracking.
missile_speed = <int> missile_evasion = <float> missile_shield = <int> missile_armor = <int> missile_health = <int> missile_retarget_range = <int>	Missile stats.
firing_arc = <float>	Limits the arc this Weapon can fire in.
min_range = <float>	Limits the minimal range this Weapon can fire.
use_ship_kill_target = <yes/no>	Unclear.
count = <int> regeneration_per_day = <float> launch_time = <int> speed = <int> rotation_speed = <float> acceleration = <float> evasion = <float> shield = <int> armor = <int> health = <int>		Strike Craft stats.

Weapon Stats CSV

Most stats of vanilla Weapon Components are defined at "common/component_templates/weapon_components.csv". This file has higher priority than individual Weapon Components.

Key	Regular Weapons	Planet Killers
key	The identification of the Weapon Component.
cost	The  Minerals cost of this Weapon Component. This field is deprecated after the economy rework.
power	The power impact of this Weapon Component.
min_damage max_damage	Determines the damage. The equivalent Weapon Component Property is damage = { min = <float> max = <float> }.
hull_damage shield_damage shield_penetration armor_damage armor_penetration	Determines the damage efficiencies and penetration rates.
min_windup max_windup	The ticks it takes for this Weapon to get ready to fire. (1 day = 10 ticks) The equivalent Weapon Component Property is windup = { min = <int> max = <int> }.	World Destroyer weapons have 90 min windup and 0 max windup.
cooldown	The ticks it takes for this Weapon to cooldown before it’s next fire. (1 day = 10 ticks) The equivalent Weapon Component Property is total_fire_time = <int>.	World Destroyer weapons have 30 cooldown.
range accuracy tracking	Determines the range, accuracy and tracking.	World Destroyer weapons have 1 accuracy, 0 range and 0 tracking.
missile_speed missile_evasion missile_shield missile_armor missile_health missile_retarget_range	Missile stats.

Component Tags

Component Tags can be given to Components to make them affected by certain modifiers. Most of the vanilla Component Tags are hard-codely required. They are defined at common/component_tags/xyz.txt.0

weapon_type_energy
weapon_type_kinetic
weapon_type_explosive
weapon_type_strike_craft
weapon_type_point_defense
weapon_role_anti_armor
weapon_role_anti_shield
weapon_role_artillery
weapon_role_anti_hull
weapon_role_point_defense

Examples

Small Red Laser

0

weapon_component_template = {
	key = "SMALL_RED_LASER"
	size = small
	type = instant
	icon = "GFX_ship_part_laser_1"
	icon_frame = 1
	prerequisites = { "tech_lasers_1" }
	component_set = "RED_LASER"
	projectile_gfx = "infrared_laser_s"
	tags = { weapon_type_energy }
	upgrades_to = "SMALL_BLUE_LASER"
	ai_tags = { weapon_role_anti_armor }	#tags must be pre-registered in common/weapon_tags
	resources = {
		category = ship_components
		cost = {
			alloys = @s_t1_cost
		}
		upkeep = {
			energy = @s_t1_upkeep_energy
			alloys = @s_t1_upkeep_alloys
		}
	}
}

Tier 3 Strike Crafts

0

strike_craft_component_template = {
	key = "STRIKE_CRAFT_HANGAR_3"
	size = LARGE
	entity = "bomber_entity"

	weapon_type = point_defence
	projectile_gfx = "strike_craft_laser_3"

	power = @power4
	resources = {
		category = ship_components
		cost = {
			alloys = @l_t5_cost
		}
		upkeep = {
			energy = @l_t5_upkeep_energy
			alloys = @l_t5_upkeep_alloys
		}
	}

	count = @count
	regeneration_per_day = @regen
	launch_time = @launch_time

	damage = { min = 6 max = 17 }
	cooldown = 2.3
	range = @attack_range
	engagement_range = @engagement_range
	accuracy = 1.00
	tracking = 1.00

	health = 45
	armor = 0
	shield = 30
	evasion = 0.80

	speed = @speed4
	rotation_speed = 0.8
	acceleration = 1

	shield_penetration = 1.0
	armor_damage = 1.5

	ship_behavior = "fighters_behavior"

	icon = "GFX_ship_part_strike_craft_fighter_3"
	icon_frame = 1
	component_set = "STRIKE_CRAFT_HANGAR_3"
	prerequisites = { "tech_strike_craft_3" }

	tags = { weapon_type_strike_craft }
	ai_tags = { weapon_role_point_defense }
}

Small Tier 3 Shield

0

utility_component_template = {
	key = "SMALL_SHIELD_3"
	size = small
	icon = "GFX_ship_part_shield_3"
	icon_frame = 1
	power = @power_S3
	resources = {
		category = ship_components
		cost = {
			alloys = @shield_s_t3_cost
		}
		upkeep = {
			energy = @shield_s_t3_upkeep_energy
			alloys = @shield_s_t3_upkeep_alloys
		}
	}
	modifier = {
		ship_shield_add = @shield_S3
		ship_shield_regen_add_static = @regen_S3 #Regeneration per day
	}
	prerequisites = { "tech_shields_3" }
	component_set = "SHIELD_3"
	upgrades_to = "SMALL_SHIELD_4"
}

PD Nullification Juggernaut Aura

0

utility_component_template = {
	key = "SHIP_AURA_PD_PENETRATION"
	size = medium
	icon = "GFX_ship_part_aura_pd_penetration"
	icon_frame = 1
	power = 0

	size_restriction = { juggernaut }
	component_set = "ship_aura_components"

	hostile_aura = {
		name = "aura_pd_penetration"
		system_wide = yes

		stack_info = {			#A ship can only be affected by one aura of a certain id. If multiple auras have the same ID the one with the highest priority will be applied.
			id = hostile_pd_penetration
			priority = 1
		}

		modifier = {
			weapon_type_point_defense_weapon_damage_mult = -0.3
			weapon_type_point_defense_weapon_fire_rate_mult = -0.3
		}

		graphics = {
			area_effect = {
				entity = "circle_area_entity"
				dynamic_scale = yes
			}
			ship_effect = {
				entity = "ship_aura_negative_entity"
				dynamic_scale = no
			}
		}
	}

	ai_weight = {
		weight = 10
		modifier = {
			factor = 2
			is_ai = yes
			is_preferred_weapons = weapon_type_energy
		}
	}
}

Bombardment Juggernaut Aura

0

utility_component_template = {
	key = "SHIP_AURA_BOMBARDMENT"
	size = medium
	icon = "GFX_ship_part_aura_bombardment"
	icon_frame = 1
	power = 0

	size_restriction = { juggernaut }
	component_set = "ship_aura_components"

	friendly_aura = {
		name = "aura_bombardment"
		system_wide = yes

		stack_info = {			#A ship can only be affected by one aura of a certain id. If multiple auras have the same ID the one with the highest priority will be applied.
			id = friendly_bombardment
			priority = 1
		}

		modifier = {
			ship_orbital_bombardment_mult = 0.3
		}

		graphics = {
			area_effect = {
				entity = "circle_area_entity"
				dynamic_scale = yes
			}
			ship_effect = {
				entity = "ship_aura_negative_entity"
				dynamic_scale = no
			}
		}
	}

	ai_weight = {
		weight = 10
		modifier = {
			factor = 2
			is_ai = yes
			is_preferred_weapons = weapon_type_energy
		}
	}
}

How does Colossus Weapons Work?

Colossus Weapons are invoked through a fleet command of the Colossus.0

Before you can fire, a scripted-trigger called can_destroy_planet_with_<colossus weapon component key> is checked. Read the vanilla file "common/scripted_triggers/01_scripted_triggers_planet_killers.txt" and Dynamic modding for details.

When the weapon is fired, an on-action called on_destroy_planet_with_<colossus weapon component key> is fired. Read the vanilla file "common/on_actions/01_planet_destruction.txt" and Event modding for details.

There are also relevant localisation keys to the Colossus Weapons, more than just the component name and description.

FLEETORDER_DESTROY_PLANET_WITH_<component key>:0 "Preparing to crack $PLANET|Y$"
MESSAGE_DESC_FOR_<component key>:0 "was utterly destroyed by"
<component key>_ACTION:0 "Crack World"

Ship Behavior

Ship Behaviors are patterns ships follow during battle. They are called by Combat Computer Components and Strike Craft Components. They are defined at common/ship_behaviors/xyz.txt.

Data Structure

Property	Description
name = <localisation key>	Identification key of this ship behavior.
preferred_attack_range = <min/median/max/int>	The distance from target the ship wants to keep when using 'attack_movement_pattern'.
formation_distance = <min/median/max/int>	The ship will switch to 'attack_movement_pattern' when it crosses inside this distance from a target. The ship will also try to stay at this distance while using 'passive_movement_pattern'.
return_to_formation_distance = <min/median/max/int>	The ship will switch to 'passive_move_pattern' when it crosses outside this distance from a target.
attack_move_pattern passive_move_pattern	Each can be one of the following. charge orbit stay_at_range flee follow stationary none
ignore_combat_movement = <yes/no>	If yes, this ship will totally ignore auto movement patterns. If it is the fleet’s leader, you retain control to move to any point you direct while the rest of the fleet follows their movement patterns. If the ship goes through a hyperlane, the whole fleet will warp out.

Global Ship Designs

Global Ship Designs are pre-scripted designs to be used by events with Effects such as create_ship. They are defined at common/global_ship_designs/xyz.txt.

Data Structure

Property	Description
name = <localisation key>	Identification key of this Global Ship Design.
ship_size = <ship size key>	Marks the ship size of this ship.
is_event_design = <yes/no>	Marks this design an Event Design that should be blocked by the Fleet Manager.
hide_size = <yes/no>	Hide the ship size of this ship, so you won't see something like "Amoeba-class Amoeba".
section template = <ship section key> slot = <section_slot_name>	Specifies the Sections. Multiple allowed. Each of them can also specify components.
component slot = <component slot name> template = <component key>	Specifies the Component. Multiple allowed. The component slot name of Weapon Component Slots are the slot names defined there. The names of Utility Component Slots are (SMALL|MEDIUM|LARGE|AUX)_UTILITY_<int>. The index starts from 1.

Create a special event ship

Sometimes you want ships that can't be designed by players or be compatible with all graphical cultures. To create a ship like the space cloud you need to do the following:

1. Find a suitable ship_size in common/ship_sizes/ or create a new one.

   If you create a new ship_size:

   		is_designable = yes/no 			# should this ship_size be selectable in the ship designer?
   		is_space_object = yes/no		# space objects will not leave engine trails
   		gfx_culture = { "pirate_01" } 	# override which gfx_cultures this size is valid for. By default a ship_size is valid for all gfx_cultures (meaning there should be one entity for each culture)
   		graphical_culture /no 			# overrides the need of a specific gfx_culture
   

   If you want to use the same entity regardless of owner's graphical culture leave out the culture part in the entity name. E.g. my_ship_size_entity instead of mammalian_01_my_ship_size_entity.

2. Add section_templates to common/section_templates/.

   Again, if you want to use the same entity regardless of owner's graphical culture leave out the culture part in the entity name.

3. If you want unique weapon for your ship add weapon_component_templates to common/component_templates/
4. Make a design for your ship in common/global_ship_designs/

You need to have entities for both the ship_size and section_templates. Only one of them has to be visible though. For single-section ships it is recommended to make the entity that belongs to the section the visible part since that will make the ship_size reusable. If your ship has weapons then each weapon_component_template also needs to have an entity, and that entity needs to have a locator called turret_muzzle_01.

Modding

Pops	Jobs • Factions

Leaders

Leaders • Leader traits

Species

Species • Species traits

Land Warfare

Armies • Bombardment stance