###############

# Ship basics #
###############
Ships consists of three basic components:
ship_size #common/ship_sizes.txt
section_template #common/section_templates/*
component_template #common/component_templates/*

These three things are then used by a ship_design to formulate a complete ship.
#common/global_ship_designs.txt

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

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.

you can find complete ship designs in "common/global_ship_designs.txt"

############
# 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 is should be: <gfx_culture>_<ship_size_name>_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: in common/component_templates/some_section.txt
section_template = {
...
entity = "some_entity"
}
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 component_slot
scripts.
the name would be "<gfx_culture>_<entity found in compnent_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")

#########################
# Create a special 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 ship_sizes.txt 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.txt"

You need to have entities for both the ship_size and you 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".