Plugins are code that hooks into the Starsector game engine. There are many different types of plugins.

Plugins that are not object specific can be hooked in by listing them as plugins, such as EveryFrameCombatPlugin. Object specific plugins often need to be be hooked into a particular object, such as OnHitEffectPlugin

Plugin registering[edit | edit source]

There are different methods to register loose uncompiled scripts or compiled scripts. Either will need to ensure they are implementing an appropriate plugin interface from the Starsector API

Loose uncompiled scripts can be registered by putting them in the magic folder in the mod


This is a prescribed folder that will automatically register any scripts within that have an appropriate plugin interface.

Compiled scripts can be registered by appending them to the array in settings.json in the "plugins" element.

Plugins[edit | edit source]

An extremely common method for plugins is the advance method, which is called each frame and is generally passed the time in seconds since the last frame occurred.

ModPlugin[edit | edit source]

ModPlugin is the master plugin for a mod, and is commonly used to set up the scripts and plugins your mod requires. ModPlugin's methods can be used to load resources when Starsector first starts up, add campaign scripts when a game is loaded, as well as generate your mod's campaign content when your mod is first enabled.

ModPlugins are registered in your mod's mod_info.json using the "modPlugin" field. For example:

    "modPlugin": "data.scripts.plugins.YourModPlugin",

ModPlugin also controls which AutofireAIPlugin, ShipAIPlugin, and MissileAIPlugin are picked for each created ship and missile, using a priority picker system that lets mods override vanilla's picks, and other mods to override them in turn.

EveryFrameCombatPlugin[edit | edit source]

When trying to register an EveryFrameCombatPlugin, the proper way is to add it to the "plugins" section of your mod's data/config/settings.json. Plugins should be registered with a unique ID. For example:

    "plugins": {
        "ExampleCombatPlugin": "data.scripts.plugins.ExampleCombatPlugin"

The plugin registered here will be added automatically to every battle so long as its class implements EveryFrameCombatPlugin.

OnHitEffectPlugin[edit | edit source]

  • interface to use - com.fs.starfarer.api.combat.OnHitEffectPlugin
  • hook into - projectile .proj file by specifying script in element "onHitEffect"
  • methods called when - onHit method is called the frame after this projectile hits something

EveryFrameWeaponEffectPlugin[edit | edit source]

  • interface to use - com.fs.starfarer.api.combat.EveryFrameWeaponEffectPlugin
  • hook into - weapon .wpn file by specifying script in element "everyFrameEffect"
  • methods called when - advance method is called each frame

IMPORTANT NOTE: Script will be active when the weapon is on a ship in combat. This includes destroyed ship hulks with the weapon attached but does not include if the ship & hulk is completely destroyed.

BeamEffectPlugin[edit | edit source]

  • interface to use - com.fs.starfarer.api.combat.BeamEffectPlugin
  • hook into - beam weapon .wpn file by specifying script in element "beamEffect"
  • methods called when - advance method is called each frame
  • instanced per weapon

Icon check temp.png

Only up to date for version 0.9. It is likely still broadly correct but not verified for the most up to date data yet. Please double check the Version History

Community content is available under CC-BY-SA unless otherwise noted.