System Setup

To implement a custom ship system, you must define the necessary data across two primary files: ship_systems.csv and a dedicated .system file. These files, in conjunction with your compiled script, contain all the data required for the game to recognize and execute the system.

File Definitions:

ship_systems.csv (The Registry): This file acts as the master list for all systems. It contains information regarding the name and ID of the system, as well as the graphic icon and balance stats, such as the number of charges and cooldown durations. It is formatted as a comma-separated values file. A guide for ship_systems.csv can be found here: ship_systems.csv .system File (The Configuration):

This file contains the technical configuration for the system and is formatted as a JSON file. It defines the aiType (which determines how the AI utilizes the system) as well as the path to the script that powers the system's mechanics. A guide for .system can be found here: .system

Stats Code

Most type of ship systems require stats code, to implement these types of systems, 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).

TBD

• Expand on intro in more step by step details;
• Cover some of other system types;
• Cover what and how system can use custom AI, some minor code examples maybe;
• Annoy Lukas/Tidal in deleting first page and redoing links on this one.