Description[]
A .ship file and a ship_data.csv entry contain all of the information directly about a ship. The more commonly balance tweaked information is in the ship_data.csv while the less commonly edited information is in the .ship file. It is formatted in Starsector's somewhat loose JSON schema.
It is highly recommended to use the third party GUI Ship Editor tool to create a .ship file, although some manual adjustment may be required. It is particularly helpful to have a GUI when setting coordinates for bounds, engines and hardpoints. The tool is Trylobot's Ship Editor or Deathfly's fork of the Ship Editor. Instructions for the Ship Editor can be found in it's directory in the readme.txt file.
Example[]
The .Ship file for the frequently seen Hound
{
"bounds": [
43,
13,
37,
-14,
5,
-10,
14,
-19,
13,
-28,
-21,
-27,
-23,
-17,
-7,
-15,
-19,
-11,
-20,
9,
-8,
15,
-23,
17,
-24,
26,
15,
27,
16,
18,
11,
12
],
"builtInMods": ["shielded_holds"],
"center": [
31,
27
],
"collisionRadius": 73,
"engineSlots": [
{
"angle": 180,
"contrailSize": 64,
"length": 80,
"location": [
-25,
22
],
"style": "LOW_TECH",
"width": 16
},
{
"angle": 180,
"contrailSize": 64,
"length": 80,
"location": [
-25,
-22
],
"style": "LOW_TECH",
"width": 16
}
],
"height": 72,
"hullId": "hound",
"hullName": "Hound",
"hullSize": "FRIGATE",
"shieldCenter": [
8,
0
],
"shieldRadius": 64,
"spriteName": "graphics/ships/hound/hound_base.png",
"style": "LOW_TECH",
"viewOffset": 0,
"weaponSlots": [
{
"angle": 0,
"arc": 5,
"id": "WS 001",
"locations": [
34,
-6
],
"mount": "HARDPOINT",
"size": "MEDIUM",
"type": "BALLISTIC"
},
{
"angle": 145,
"arc": 290,
"id": "WS 002",
"locations": [
-4,
4
],
"mount": "TURRET",
"size": "SMALL",
"type": "BALLISTIC"
},
{
"angle": 180,
"arc": 90,
"id": "WS 003",
"locations": [
-19,
0
],
"mount": "HIDDEN",
"size": "SMALL",
"type": "SYSTEM"
}
],
"width": 62
}
Elements[]
bounds[]
- The collision bounds of the ship hull as defined by a polygon. The points of the polygon are an array of Cartesian coordinates relative to the defined Center of the ship rotated 90 degrees clockwise. The polygon can be concave or convex and non-polygon shapes cause undefined behaviour. It is generally better to have it a little inside the ship hull rather than outside[1]. Excessive amounts of points can be a performance issue[2].
builtInMods[]
- An optional array of hullmod IDs that are build into the base ship.
builtInWings[]
- An optional array of wingIds that are build into the base ship.
center[]
- The defined center of the ship, as a set of Cartesian coordinates relative to the most bottom left pixel of the sprite. Please do note that this is not necessarily the literal center but that it is a really good idea. The defined center point is the relative reference point for the bounds, collisionRadius, engineSlots, shieldCenter, shieldRadius, viewOffset & weaponSlots. It is also the pivot point when the ship turns.
collisionRadius[]
- The radius of the collision circle in pixels, relative to the defined Center. This defines the boundary within which the game engine starts (expensively) checking for collisions with the ship's shield or bounds. Collisions cannot occur outside this radius so it is a good idea to have the collision radius fully enclose the shield & bounds. Ship death explosion radius is also based on this, being collision radius + 200. Number
engineSlots[]
- An array of engines with each engine defined by an array of values.
- angle
- The angle in degrees that the engine plume will face, relative to the top of the sprite. Please do note that GUI ship editors rotate the sprite 90 degree clockwise, so 180 degrees points relative "down" which is to the left.
- contrailSize
- The size of the visual particle effects trailing the engine plume, in pixels.
- NOTE: contrailSize 128 is a special magic hardcoded number that will define this engine as part of a Maneuvering Jets ship system.
- length
- The length of the engine plume. This has both visual & gameplay effects, as plume length is part of the engine HP calculations.
- location
- The location of engine as Cartesian coordinates relative to the defined Center of the ship rotated 90 degrees clockwise.
- style
- Refers to a visual engine style set as defined in engine_styles.json
- width
- The width of the engine plume. This has both visual & gameplay effects, as plume width is part of the engine HP calculations.
height[]
- The maximum height of the sprite canvas in pixels. Setting this bigger or smaller than the actual canvas dimensions will cause the sprite to stretch or shrink to fit in-game.
hullId[]
- The unique hullId specified in the corresponding ship_data.csv entry. This is what links these pieces of data together, not the filename of the .ship file. Case sensitive.
hullName[]
- The friendly name of this hull.
hullSize[]
- The size class of this hull. Possible sizes are FIGHTER, FRIGATE, DESTROYER, CRUISER, CAPITAL_SHIP
shieldCenter[]
- The center point of the shield as Cartesian coordinates relative to the defined Center of the ship rotated 90 degrees clockwise.
shieldRadius[]
- The radius of the visual shield in pixels, relative to the defined shieldCenter. Where the shield can actually collide with objects is defined by the collisionRadius.
spriteName[]
- The file path to the sprite for this ship, as a png file. The file path is relative to the base /starsector-core/ folder for vanilla content or the mod's base folder.
style[]
- Refers to a visual ship style set as defined in hull_styles.json
viewOffset[]
- The relative view offset as Cartesian coordinates relative to the defined Center of the ship rotated 90 degrees clockwise. Use this if you want the player to center over a part of the ship that is not the center point.
weaponSlots[]
- An array of weapon mounts with each mount defined by an array of values.
- angle
- The angle is where the weapon points and is the midpoint for the weapon arc, in degrees relative to the front of the ship (which is to the right in the GUI ship editors).
- arc
- The width of the weapon's arc in degrees, centered on the weapons angle of facing.
- id
- The id of this weapon mount. Must be unique to other mounts on this ship. This is used to link these mounts to which weapons are mounted in them in the corresponding .variant files for this hullId.
- locations
- The location of this mount as Cartesian coordinates relative to the defined Center of the ship rotated 90 degrees clockwise.
- mount
- The mount type. Possible mount types are TURRET, HARDPOINT or HIDDEN.
- size
- The size of mount. Possible sizes are SMALL, MEDIUM or LARGE.
- type
- The type of weapon to fit in this mount. Possible types are BALLISTIC, ENERGY, MISSILE, HYBRID, COMPOSITE, SYNERGY, UNIVERSAL, LAUNCH_BAY, SYSTEM, DECORATIVE, BUILT_IN or STATION_MODULE.
width[]
- The maximum width of the sprite canvas in pixels. Setting this bigger or smaller than the actual canvas dimensions will cause the sprite to stretch or shrink to fit in-game.
References[]
- ↑ [1] Alex on ship bounds near the edges
- ↑ Starsector PSA #1: Your Ship's Bounds Polygon Is Too Detailed
At least two versions out of date. Last verified for version 0.8.1a-RC8. Please refer to Version History and update this page
Return to: Modding