Ship.json for setting up ship properties

From PioneerWiki
Jump to: navigation, search

Ship.json files are used for setting up the properties and capabilities of the ships. They are found in the data/ships directory, and each ship has it's own <shipname>.json file

It's a .json formatted file, containing "key" : data pairs, and each line ends in a comma, except the last one. Each file starts with a { and ends with a } The data in most ship.json files are sorted alphabetically, but that isn't mandatory. Text entries are between "quote marks", numerical entries don't need them.

There are different types of entries in these files, setting up maneuverability, manufacturer data, capacities, model file and so on.

Model and manufacturer data

"model" : "storeria",

Points to the storeria.model file of the ship, case sensitive, and omitting the .model extension.

"name" : "Storeria",

The name of the ship, displayed to the player.

"cockpit" : "",

The cockpit.model file for the ship, to set up custom cockpit. It points to the default cockpit if left empty. Case sensitive.

"manufacturer" : "opli", 

Defines the manufacturer of the ship. Right now it's only used for selecting the manufacturer icon and decal. Valid entries currently: albr, auronox, haber, kaluri, mandarava_csepel, opli. These are the manufacturer icons found in data/icons/manufacturers, so putting a new icon in this directory makes it available as a manufacturer.

"ship_class" : "medium_freighter",

Defines the class of the ship. Right now it's only used for selecting the class icon for the list in the ship market. Valid entries currently: light_cargo_shuttle, light_courier, light_fighter, light_freighter, light_passenger_shuttle, light_passenger_transport, medium_cargo_shuttle, medium_courier, medium_fighter, medium_freighter, medium_passenger_shuttle, medium_passenger_transport, heavy_cargo_shuttle, heavy_courier, heavy_fighter, heavy_freighter, heavy_passenger_shuttle, heavy_passenger_transport. Similar to the manufacturer, valid entries are the filenames found in the /data/icons/shipclass directory.

Capacities and masses

"min_crew" : 1,
"max_crew" : 5,

The amount of crew needed to operate the ship, and the maximum number of crew the ship supports.

"price" : 2527000.0,

The base price of the ship for the ship market. Actual price shown in the market is usually lower, because of the trade-in value of the player's current ship.

"hull mass" : 500,

The dry mass of the ship in metric tons. Sans equipment, cargo and fuel mass. This also defines the amount of armour, AKA health the ship has.

"capacity" : 1550,

The cargo and equipment capacity of the ship, in metric tons or cargo units. (Right now every kind of cargo has 1t mass/unit).

"slots" : {
    "atmo_shield": 0,
    "cargo" : 1500m
    "scoop" : 2,
    "laser_front" : 1,
    "laser_rear" : 0,
    "missile" : 0

The list and amount of compatible equipment for the ship. In this case: no atmospheric shield, 1500 units of cargo, two scoop mounts, for cargo/fuel/combined scoops, one front laser, no rear laser or missiles.

"effective_exhaust_velocity" : 25000000.0,

The exhaust velocity of the engine in m/s. This defines the effectiveness of the engine. The larger the number, the better the fuel economy, which means higher deltaV for the same amount of propellant.

"thruster_fuel_use" : -1.0,

Another way to define the effectiveness of the engine in g/s. Ignored if -1.0. The higher the value, the less efficient the engine.

"fuel_tank_mass" : 1000,

The propellant capacity of the ship in metric tons. More propellant means more deltaV, but not in a linear manner. Also more propellant increases the total mass of the ship, lowering accelerations.

"hyperdrive_class" : 7,

The hyperdrive fitted to the ship.


The thrust the engines of the ship provide, in each direction. Given in Newtons (1N of thrust accelerates 1kg to 1m/s). Higher value means better acceleration. Usually it's easier to think with kNs calculating the thrust of the ship, (1kN accelerates 1t to 1ms), and then multiply it with 1000 when entering the data.

"forward_thrust" : 100000000.0,
"reverse_thrust" : 30000000.0,
"up_thrust" : 18000000.0,
"down_thrust" : 18000000.0,
"left_thrust" : 8000000.0,
"right_thrust" : 8000000.0,

You can also set an acceleration limit on each direction, in m/s^2 (1g = 9.81m/s^)

"forward_acceleration_cap": 44.145,
"reverse_acceleration_cap": 11.772,
"up_acceleration_cap": 39.24,
"down_acceleration_cap": 19.62,
"left_acceleration_cap": 19.62,
"right_acceleration_cap": 19.62,

The rotation speed/acceleration the ship is capable of.

"angular_thrust" : 183000000.0


Cross sections from the three axes in square meters. They can be measured in Blender, if you flatten a copy of the ship mesh, clean it up to an ngon.

"front_cross_section": 35.2,
"side_cross_section": 46,
"top_cross_section": 345,

Drag coefficients.

"front_drag_coeff": 0.04,
"side_drag_coeff": 0.1,
"top_drag_coeff": 0.85,

Lift coefficient:

"lift_coeff": 1,

Aerodynamic stability - how much the ship wants to turn towards the direction of travel:

"aero_stability": 2.6


There are some additional tags which define the role of a ship.

"tag" : "static"

Sets the ship as bulk ship. Not available for the player, but it can be seen parked next to orbital stations.

"tag" : "missile"

Sets the ship as a missile. Missiles can be bought as equipment, and can be fired from ships that can mount them. They don't need all above data to work.

Example missile setup:

  "tag" : "missile",
  "angular_thrust" : 20000.0,
  "forward_thrust" : 300000.0,
  "reverse_thrust" : 150000.0,
  "hull_mass" : 1,
  "model" : "missile",
  "name" : "MISSILE_SMART",
  "price" : 100.0,
  "down_thrust" : 0.1,
  "left_thrust" : 0.1,
  "right_thrust" : 0.1,
  "up_thrust" : 0.1

Worked example

The above entries are for the Storeria medium freigher:

  "model": "wave",
     "name": "Wave Hypersonic Fighter",
     "cockpit": " ",
     "manufacturer": "auronox",
     "ship_class": "medium_fighter",
     "min_crew": 1,
     "max_crew": 1,
     "price": 62389,
     "hull_mass": 13,
     "atmospheric_pressure_limit": 14,
     "capacity": 30,
     "slots": {
           "engine": 1,
           "autopilot": 1,
           "cabin": 10,
           "scoop": 2,
           "laser_front": 1,
           "laser_rear": 1,
           "missile": 8,
           "cargo_life_support": 1,
           "atmo_shield": 1,
           "ecm": 1,
           "scanner": 1,
           "radar": 1,
           "hypercloud": 1,
           "hull_autorepair": 1,
           "shield": 1,
           "energy_booster": 1,
           "laser_cooler": 1,
           "trade_analyzer": 1,
           "sensor": 1,
           "cargo": 30
     "roles": {
           "mercenary": true,
           "pirate": true
     "effective_exhaust_velocity": 16900000,
     "thruster_fuel_use": -1.0,
     "fuel_tank_mass": 22,
     "hyperdrive_class": 3,
     "forward_thrust": 2800000,
     "forward_acceleration_cap": 44.145,
     "reverse_thrust": 2000000,
     "reverse_acceleration_cap": 11.772,
     "up_thrust": 2000000,
     "up_acceleration_cap": 39.24,
     "down_thrust": 800000,
     "down_acceleration_cap": 19.62,
     "left_thrust": 800000,
     "left_acceleration_cap": 19.62,
     "right_thrust": 800000,
     "right_acceleration_cap": 19.62,
     "angular_thrust": 3000000,
     "front_cross_section": 35.2,
     "side_cross_section": 46,
     "top_cross_section": 345,
     "front_drag_coeff": 0.04,
     "side_drag_coeff": 0.1,
     "top_drag_coeff": 0.85,
     "lift_coeff": 1,
     "aero_stability": 2.6 }