To implement a system, you must have a script that is referenced in your .system file. This chapter explains how to create a basic system script that increases a ship's flux dissipation by 20%.

The Foundation: BaseShipSystemScript

Every ship system script must inherit from BaseShipSystemScript. This class provides the standard API hooks to control your system, giving you two main jobs: applying your changes when the system turns on, and removing them when it turns off.

package data.scripts.systems; 

import com.fs.starfarer.api.combat.MutableShipStatsAPI;
import com.fs.starfarer.api.impl.combat.BaseShipSystemScript;

// This class inherits from the API base class to define your system logic.
public class FluxBoostStats extends BaseShipSystemScript {

    // Called while the system is active.
    @Override
    public void apply(MutableShipStatsAPI stats, String id, State state, float effectLevel) {
        /*
         * id is the ship system id, usually from data/shipsystems/ship_systems.csv.
         * The stat modifier is stored under this id so it can be removed later.
         */
        stats.getFluxDissipation().modifyMult(id, 1.2f);
    }

    // Called when the system effect should be removed.
    @Override
    public void unapply(MutableShipStatsAPI stats, String id) {
        // Remove only the modifier applied by this system.
        stats.getFluxDissipation().unmodify(id);
    }
}

Troubleshooting

If your system isn't loading or working, follow these steps to diagnose the issue:

Step 1: ID matches. Ensure the ID used in your ship_systems.csv exactly matches the ID used in your .system file. The game uses this ID as the "key" to connect the registry to the configuration.

Step 2: Script Linking. Verify the statsScript field in your .system file points to the correct package and class name (e.g., data.scripts.systems.FluxBoostStats). Java is case-sensitive, so FluxBoostStats is not the same as fluxbooststats.

Step 3: Verify the Jar. Ensure your code is compiled into your .jar file. You can verify this by opening the .jar with an archive manager (like 7-Zip or WinRAR) to ensure the .class file exists in the expected folder path.

Step 4: Check the Logs. If the game crashes, check your log file. Look for ClassNotFoundException (indicating a wrong file path or a missing class) or FATAL errors (indicating a specific line of code that caused the crash).