Equipment.plist

Using Equipment

Player buyable equipment is stored in a file named equipment.plist that resides in the Config folder of a OXP. You can add equipment by adding arrays to this plist file. Every equipment array is build of an array of entries.

Equipment Structure

The following equipment data are read in by Oolite.

(
   (
      1,
      300,
      Missile,
      "EQ_MISSILE",
      "Faulcon de Lacy HM3 homing missile, fast and accurate when used in conjunction with standard targetting scanners.",
       {
          "available_to_all" = YES;
       }
    )
)

1) The first entry is an integer that determines the technical level from which the equipment can be bought. A level of 99 has a special meaning. Only this value can be changed by script. Please note that the number displayed on the system data screen is one higher than the system's tech level, so to make equipment available at a displayed TL:10 and above in game, enter 9 here.

Repairs can take place at tech levels one lower than the purchase level, and occasionally equipment will be offered at systems of a slightly lower tech level than the number given here.

2) The second entry is the costs of the equipment in tenths of a credit.

3) This is a string that shows the name of the equipment as seen by the player.

4) This is a string that shows the name of the equipment that is used by scripting. Must start with EQ_ and endings like _MISSILE or _MINE give it a special handling.

5) This string gives a short description of the item.

6) This is a dictionary that can contain several special features like:

{
   "available_to_all" = yes;
   "available_to_NPCs" = yes;
   "available_to_player" = no;
   conditions = (
       "systemGovernment_number morethan 3" // note: deprecated and should not be used in new code
   );
   "condition_script" = "myoxp_conditions.js";
   "damage_probability" = 1.0;
   "display_color" = "whiteColor";
   "fast_affinity_defensive" = no;
   "fast_affinity_offensive" = no;
   "incompatible_with_equipment" = "EQ_FUEL_SCOOPS";
   "installation_time" = 86400;
   "is_external_store" = no; // is missile or mine and added to pylon.
   "portable_between_ships" = yes;
   "provides" = ("EQ_CARGO_SCOOPS");
   "repair_time" = 3600;
   "requires_any_equipment" = (
       "EQ_FUEL_SCOOPS",
       "EQ_ECM
    );
   "requires_cargo_space" = 5;
   "requires_clean" = yes;
   "requires_empty_pylon" = yes;
   "requires_equipment" = "EQ_FUEL_SCOOPS";
   "requires_free_passenger_berth" = no;
   "requires_full_fuel" = no;
   "requires_mounted_pylon" = yes;
   "requires_not_clean" = yes;
   "requires_non_full_fuel" = no;
   "script" = "myCustomScript.js";
   "script_info" = {
        myCustomProperty = 0;
   };
   "strict_mode_only" = no; // version 1.77 or earlier only
   "strict_mode_compatible" = yes; // version 1.77 or earlier only
   "visible" = yes; // values are yes/true or no/false; defaults to yes; it means the item is listed on the F5 screen.
   "weapon_info" = {
	range = 15000;
	energy = 0.5;
	damage = 6.0;
	recharge_rate = 0.1;
	shot_temperature = 3.2;
	color = "yellowColor";
	threat_assessment = 0.5;
       is_mining_laser = 0;
       is_turret_laser = 0;
   };
}

Most names will explain themselves. For detailed explanation look at the corresponding values in EquipmentInfo.scriptInfo. In this list the empty/mounted pylons are not necessary when the equipment ends on MINE or MISSILE.

Notes

• Conditions can contain a single string with one condition or an array of condition strings. Conditions are only checked when the equipment would be available by the other criteria. The condition_script option, available from Oolite 1.77 onwards, specifies a Javascript file which controls the conditions for this equipment. The allowAwardEquipment function in that condition script will then be tested before the equipment is allowed.

• available_to_all means all ships can buy the item. When not set it is only buyable when the equipment is defined in the shipyard.plist under optional_equipment.

• requires_cargo_space is only used to determine a condition to show an item on the list. Until Oolite 1.76 it uses no cargo space when bought, and except for the core game's passenger cabins has a bug which will sometimes cause equipment to mysteriously vanish when reloading a saved game. Starting with Oolite 1.77, this key will use cargo space for user defined equipment.

• "script_info" is added with test release 1.74. It contains a directory of custom entries that become properties of EquipmentInfo.scriptInfo

• "script" is added with test release 1.75. It contains a name of a script file used by the equipment. Equipment that contains a script is put on a special list. The player than can cycle through that list by pressing "shift-N". (similar as selecting a missile). The primed script is than the active script. Whenever a player now presses "n", the "this.activated()" event handler of the primed equipment is executed.

this.activated = function ()
{
	// your code
}

In testrelease 1.77 the 'b' key is added to primable equipment. Whenever the 'b' is pressed, the "this.mode()" event handler of the currently primed equipment is executed.

this.mode = function ()
{
	// your code
}

• requires_equipment, requires_any_equipment, incompatible_with_equipment can be a single string or an array of strings.

• "damage_probability" is added in test release 1.77. It is the relative probability that this equipment will be damaged. It is ignored (and always zero) for missiles and mines, and defaults to 1.0 for all other equipment.

• "display_color" is added in test release 1.85. This value specifies the color to be used for this item on the F3 Equip Ship screen and the F5 Status screen. Any valid color specifier can be used.

• "fast_affinity_defensive" and "fast_affinity_offensive" are added in 1.79. These keys are ignored unless the equipment has a "script" file. If the equipment has a script file, then if set these keys make the equipment preferentially assigned to the "fast activation" keys ('0' and 'tab' in the default keys). This automatic assignment only happens if the equipment is bought while the current fast equipment assignment is blank (or is for equipment not currently installed). Generally these keys should only be set for equipment which might need to be activated quickly in an emergency.

• "installation_time" and "repair_time" are added in 1.81. Value is number of seconds. These override the standard 10 minutes plus one second per decicredit time to purchase an equipment item from the F3 screen. If only installation_time is specified, the repair time will be half of that. If only repair_time is specified, the installation time will be the default from the cost.

• "provides" is added in 1.81, and is an array of equipment keys. This allows OXP equipment to provide some functionality from core equipment (or in theory other OXP equipment though this would need to be managed carefully between the OXPs). For example, a "navigation computer" might have "provides" = ("EQ_DOCK_COMP","EQ_ADVANCED_COMPASS");, and while this equipment was installed the player would get the benefits of those items even if they were not currently fitted. The default value is an empty array, though equipment is always considered to provide its own equipment key. While any string may be added here, only the following items have any in-game effect in the core game:
  • "EQ_ECM": 'e' key can be used to trigger an ECM blast
  • "EQ_FUEL_SCOOPS": may scoop fuel from a star
  • "EQ_CARGO_SCOOPS": may scoop cargo. Note: there is no such core game item, but the core fuel scoops have this in their 'provides' list.
  • "EQ_ESCAPE_POD": may eject with 'escape' key. The item providing this feature will be removed on use.
  • "EQ_DOCK_COMP": 'c' key may be used to initiate autopilot. If multiple items provide this, all must be damaged or removed for autopiloting to cease.
  • "EQ_GAL_DRIVE": may make a galactic jump with 'g' key. The item providing this feature will be removed on use.
  • "EQ_CLOAKING_DEVICE": may remain cloaked. Activation of the cloak via the primable equipment mechanism will not be duplicated simply by providing this item.
  • "EQ_FUEL_INJECTION": allows the 'i' key to be used for speed boost
  • "EQ_SCANNER_SHOW_MISSILE_TARGET": displays the Scanner Targeting Enhancement features
  • "EQ_MULTI_TARGET": allows independent locking of missiles
  • "EQ_ADVANCED_COMPASS": allows tracking of beacons and other objects on the compass
  • "EQ_ADVANCED_NAVIGATIONAL_ARRAY": allows route planning on the chart screen
  • "EQ_TARGET_MEMORY": allows storing and remembering of previous targets
  • "EQ_INTEGRATED_TARGETING_SYSTEM": visual tracking of remembered targets. Note that the core Integrated Targeting System item requires the Scanner Targeting Enhancement and Target Memory items to be installed before it can be bought, and this must be those specific items, not items providing those functions. However, once installed it is sufficient for items providing those functions to be on board for the item to work.
  • "EQ_WORMHOLE_SCANNER": allows targeting and scanning of witchspace wormholes

Creating laser weapons

Note: this is a 1.81 prototype feature and may change significantly before release.

Laser weapons must have a name beginning "EQ_WEAPON_", and then should have a weapon_info dictionary describing them. This dictionary has the following keys, all of which can be omitted to keep the default value:

• range: The maximum range in metres, default 12500.
• energy: The energy used per shot, default 0.8.
• damage: The damage done to the target per shot, default 15.0.
• recharge_rate: The time to recharge between shots in seconds, default 0.5. A value of 0.1 will appear to be a continuous beam. Values lower than 0.1 are not recommended as they may cause the weapon's power to vary significantly depending on the frame rate.
• shot_temperature: The amount of heat generated per shot, default 7.0. Lasers will not fire at heat of 217.6 or over.
• color: The default colour of the laser, if the ship it is mounted on has not specified a laser colour. Any valid colour specifier can be used. The colour will be made "bright".
• threat_assessment: The effect having this weapon fitted has on the threat assessment level of the ship, default 0.0. The beam laser is 0.5, and the military and thargoid lasers are 1.0 in the core game. Values significantly outside this range may cause unusual AI behaviour.
• is_mining_laser: If true, the weapon will break up asteroids and boulders into smaller fragments. Default false.
• is_turret_laser: If true, the weapon will automatically aim independently of the ship facing like the thargoid laser. Default false. This is likely to give buggy behaviour if put on a player ship.

In version 1.89, the following weapon properties can be specified in a weapon_info dictionary:

• fx_shot_miss_name: Sound played when weapon is fired but does not hit anything (laser weapons only).
• fx_shot_hit_name: Sound played when weapon is fired and hits another ship (laser weapons only).
• fx_hitplayer_shielded_name: Sound played when weapon hits the player ship while shields are up.
• fx_hitplayer_unshielded_name: Sound played when weapon hits the player ship while shields are down.
• fx_weapon_launch_name: Sound played when the weapon is launched (missiles and mines only).

See also: equipment-overrides.plist