API and Modules Documentation

Mods can define resources for the Kethane plugin to manage. Mods can use a selection of Kethane-defined part modules on custom parts, so every function of finding and extracting a custom resource can be accomplished without Kethane parts. Additionally, no modifications to the original Kethane package are necessary, and multiple mods can interact with Kethane simultaneously.

All use of Kethane is subject to the license.

Defining Resources

Resources are exposed to Kethane with KethaneResource config nodes. (Note: These do not replace the KSP RESOURCE_DEFINITION nodes.) These nodes define the parameters for deposit generation and map configuration.

KethaneResource nodes may be placed in any configuration file. Since any mod exposing a resource to Kethane is likely to be defining its own resource types, a good convention is to place KethaneResource nodes in the KSP resource configuration files alongside RESOURCE_DEFINITION nodes. However, any configuration file will work. The node for Kethane can be found here.

KethaneResource Parameters

• Resource: This is the name of the resource for Kethane to generate.
• MinRadius: Minimum radius of a deposit. For each deposit, the generator picks a random number between this and the maximum radius; that number becomes the radius of the farthest vertex from the center, so this is the "minimum maximum radius", not the radius of the minimum vertex.
• MaxRadius: Maximum possible radius of a deposit.
• MinQuantity: Minimum quantity of the resource a deposit begins with. The physical size of a deposit has no bearing on its starting quantity.
• MaxQuantity: Maximum quantity of the resource.
• MinVertices: Minimum number of vertices in a deposit's shape. Vertices are distributed uniformly in a circle around the center of the deposit. (See RadiusVariance for a description of how vertices are distorted from this circle.)
• MaxVertices: Maximum number of vertices.
• RadiusVariance: Random multiplier for each vertex distance. Each deposit gets a radius (random number between MinRadius and MaxRadius) and then each vertex is placed at a distance of that radius multiplied by a random number between 1 and RadiusVariance. In other words, this property determines how jagged a deposit will be. Numbers both higher and lower than 1 are acceptable. Negative numbers might break things.
• DepositCount: Number of deposits the generator will attempt to place.
• NumberOfTries: Number of times the generator will attempt to place each deposit. A deposit location and shape is randomly selected for each attempt, and an attempt is considered successful if no vertex is inside a deposit that's already been placed. If all tries are exhausted and a suitable location was not found, that deposit is skipped. You can set this to a low number to create some variance in the total number of deposits.
• SeedModifier: Overrides the seed modifier for deposit generation. This is a legacy support feature that you shouldn't need to use in most cases; definitely remove the SeedModifier = 0 line if you copy and paste the Kethane configuration. By default, the seed used for generation is XOR'd with a hashcode of the resource name. This ensures different resources with the same parameters are still distributed differently and consistently. Kethane has an override of 0 to ensure compatibility with previous versions. You will only need to use this if you change the name of your resource and want to keep deposit locations, or if you want your deposits to line up with another resource.
• ColorFull: Scan map coloring for a deposit with a quantity equal to MaxQuantity. For deposits at some level in between, this is interpolated with ColorEmpty.
• ColorEmpty: Scan map coloring for a deposit with a quantity equal to MinQuantity.

Body Nodes

Resource configurations can contain Body nodes which override generation parameters for a given celestial body. This lets you give each planet and moon a unique distribution of your resource, or even remove the resource entirely. Any attributes specified in a Body node will override those given in the main definition node, and any omitted will be inherited. All properties can be overridden except for Resource and SeedModifier, and Body nodes are not recursive. The name of the body is specified in the name field.

Part Modules

The Kethane plugin exposes part modules (classes extending the KSP PartModule class) which can be used by other mods. The license details exactly which modules are allowed for use.

KethaneConverter

The converter module facilitates transforming resources into others. All input resources must be present for conversion to work, and there must be room for all target resources to be produced. The converter respects the flowMode defined in KSP RESOURCE_DEFINITION nodes. Multiple converter modules may be defined for a single part. Resources do not need to have KethaneResource nodes to be used in a converter.

Sample module configuration:

MODULE
{
    name = KethaneConverter
    Label = Rocket Fuel
    InputRates
    {
        Kethane = 4
        ElectricCharge = 12
    }
    OutputRatios
    {
        LiquidFuel = 0.36
        Oxidizer = 0.44
    }
    OutputRates
    {
        MonoPropellant = 0.1
    }
}

• Label: Name for this converter. Defaults to the list of input resources (e.g. Kethane/ElectricCharge).
• InputRates: List of input resource consumption rates in units per second.
• OutputRatios: List of output resource production mass ratios, in terms of the total input mass rate. A ratio of 1 indicates that the same mass will be produced as is consumed. Each value may be higher or lower than 1. Mass is calculated using the density defined in the RESOURCE_DEFINITION for each resource.
• OutputRates: List of output resource production rates in units per second. Use this when you don't want the converter to account for resource density changes or when you need to produce a massless resource. If a resource is specified in both OutputRates and OutputRatios, the resulting rates are added.

All KethaneConverter properties and nodes are optional.

KethaneDetector

The detector module reveals the presence of resource deposits on the scan map and makes a pinging sound to indicate detection. Detectors have configurable power requirement, scan rate, scan range and detectable resources.

Sample module configuration:

MODULE
{
    name = KethaneDetector
    DetectingPeriod = 1.5
    DetectingHeight = 250000
    PowerConsumption = 0.8
    Resource
    {
        Name = Kethane
    }
}

• DetectingPeriod: Number of seconds between scans.
• DetectingHeight: Maximum altitude at which the detector operates.
• PowerConsumption: Units of ElectricCharge consumed per second. If less power is available than required, the detector consumes whatever is available and runs at a proportional rate.
• Resource nodes: Specifies the resources which this detector can scan. Multiple Resource nodes can be defined, and the detector will scan for them simultaneously. These resources must have KethaneResource nodes defined. If no Resource node is given, the detector will scan for all known resources.

KethaneDetectorAnimator

This documentation is incomplete.

KethaneDrillAnimator

This documentation is incomplete.

KethaneExtractor

Extractors pull resources from deposits and produce them at the part. Extractors can be in one of four states: deploying, deployed, retracting and retracted. Extractor animators define exactly how those states are transited and are responsible for accompanying visual effects. (Exactly one extractor animator must be present on any part with a KethaneExtractor module.) One or more resources can be extracted simultaneously, and not all supported resources need to be present for the extractor to work. Electrical power is consumed when the extractor is in the deployed state and intersecting ground, and resources are extracted in proportion to the amount of power that could be drawn. Additional resources do not increase power demand.

Sample module configuration:

MODULE
{
    name = KethaneExtractor
    PowerConsumption = 24
    HeadTransform = drillbit
    TailTransform = housing
    HeadOffset = 0.5
    TailOffset = -0.1
    Resource
    {
        Name = Kethane
        Rate = 5
    }
}

• PowerConsumption: Units of ElectricCharge consumed per second. Defaults to zero.
• HeadTransform: Name of the transform that represents the head (underground part) of the drill. This is used as the endpoint of the ground raycast.
• TailTransform: Name of the transform that represents the tail (highest point that can work underground) of the drill. This is used as the origin of the ground raycast.
• HeadOffset: Distance to extend the ground raycast at the head point.
• TailOffset: Distance to extend the ground raycast at the tail point.
• Resource nodes: Specifies resources that can be extracted. Name is the name of the resource, and Rate is the number of units to extract per second. These resources must have KethaneResource nodes defined.

KethaneExtractorAnimatorLanded

Note: This module is liable to be removed or renamed in a future release.

Extractor animator with no visual effect. Deploy and retract commands work instantly.

Sample module configuration:

MODULE
{
    name = KethaneExtractorAnimatorLanded
}

KethaneWetMassIndicator

This module adds an indicator for the full mass of a resource container in the part info window. Some containers (like Kethane tanks) start empty, and the game reports only the dry mass.

Sample module configuration:

MODULE
{
    name = KethaneWetMassIndicator
    Label = Full Mass
}

Label: Text used to describe the full mass of the tank. Defaults to "Wet Mass".

Interfaces

The Kethane plugin defines several interfaces which are used by modules. You can define your own modules using these interfaces to create more advanced behavior. To reference these interfaces, your plugin assembly must reference the Kethane assembly, MMI_Kethane.dll. This feature should be considered experimental.

IDetectorAnimator

The KethaneDetector module looks on its part for any part module implementing this interface. On every Update, the detector updates the properties of each detector animator. All animators get the same values. Detector animators are optional.

• bool IsDetecting { set; }: Whether the detector is currently enabled. Does not reflect whether the detector is in range or has enough power.
• float PowerRatio { set; }: Ratio of electric power the detector was able to draw to the power it tried to draw. Zero when the detector is not detecting or out of range.

IExtractorAnimator

This documentation is incomplete.