Skip to content

API and Modules Documentation

Majiir Paktu edited this page Jun 15, 2013 · 20 revisions

Note: This document only applies to versions 0.6 and later.

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 one resource into another. All input resources must be present for conversion to work, and there must be room for the target resource to be produced. The converter respects the flowMode defined in KSP RESOURCE_DEFINITION nodes. Currently, the converter only supports one input resource plus ElectricCharge, and one output resource. 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
    SourceResource = Kethane
    TargetResource = MonoPropellant
    ConversionEfficiency = 0.85
    SourceConsumption = 3
    PowerConsumption = 10
}
  • SourceResource: The name of the input resource.
  • TargetResource: The name of the output resource.
  • ConversionEfficiency: The mass efficiency of the conversion. An efficiency of 1 indicates that the same mass will be produced as is consumed. This value may be higher or lower than 1. Mass is calculated using the density defined in the RESOURCE_DEFINITION for each resource.
  • SourceConsumption: The rate at which the source resource is consumed in units per second. The target resource rate is computed from this, the ConversionEfficiency and the density ratio between the two.
  • PowerConsumption: Units per second of ElectricCharge required for conversion. Set this to zero to disable electricity requirements. Values less than zero are untested.

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.

KethaneDetectorAnimator

This documentation is incomplete.

KethaneDrillAnimator

This documentation is incomplete.

KethaneDrillAnimatorLanded

Extractor animator with no visual effect that requires the vessel to be landed or splashed down. Deploy and retract commands work instantly.

Sample module configuration:

MODULE
{
    name = KethaneDrillAnimatorLanded
}

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. Extractors work for multiple resources

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
}

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.