Controllers

Controllers collect data from the game, and provide those values to effects. For example, the ThrottleController gets the engine's throttle value so that it can be wired up to drive modifiers that change properties of the plume effect. The output of a controller is generally a single floating point value, but the RCSController provides a list of values.

Controller Creation

There are two ways to create and edit Controllers.

Ingame

You can add Controllers by adding them in the ingame Editor UI. See the UI Page for more details.

In Config

Add a node with the type of the controller inside the ModuleWaterFallFX MODULE node:

MODULE
{
    name = ModuleWaterFallFX

    THROTTLECONTROLLER
    {
        // The name of the controller, which should be unique
        name = throttle
    }
}

Legacy Method

You can add Controllers by adding CONTROLLER nodes in the body of the ModuleWaterfallEffect config, which look like this:

CONTROLLER
{
  // The name of the controller, which should be unique
  name = atmosphereDepth
  // The ingame variable to link to. Only a few values are possible
  linkedTo = atmosphere_density
}

These variables work as follows:

• Name: The name variable lets you give the controller a name. This will allow Effect Modifiers to link to a controller, so make sure it is something you like writing and not too long.
• linkedTo: The ingame field that controls how it behaves. Valid values are currently throttle, atmosphere_density, random, custom, gimbal, light, mach, rcs, engineEvent, thrust, velocity

Controller Types

When configuring your effect module, it is usually enough to have a throttle or thrust controller and an atmospheric density controller. However, you can add other controllers, each type is detailed below:

Response Rate

Many controllers have responseRateUp and responseRateDown fields. These smooth out the raw value from the game, causing the controller's output to interpolate towards the input value over time. These are in units per second. For example, if a controller's input value goes from 0 to 1 in a single frame and the responseRateUp is 0.2, then the controller's output value will smoothly increase over 5 seconds.

Throttle Controller

A throttle controller links to the engine throttle.

• engineID , which is a field used to link the controller to a specific instance of ModuleEngines on a part. Not necessary if there's only one.
• responseRateUp , Default 100.
• responseRateDown , Default 100.

THROTTLECONTROLLER
{
  name = throttle
  // The ModuleEngines engineID to follow
  engineID = none
  // The response rate as the engine spools up
  responseRateUp = 1
  // The response rate as the engines spools down
  responseRateDown = 1
}

Thrust Controller

A thrust controller links to the engine normalized thrust. The output is a value between 0 and 1 that indicates the fraction of maximum possible thrust in the current situation.

• engineID , which is a field used to link the controller to a specific instance of ModuleEngines on a part. Not necessary if there's only one

THRUSTCONTROLLER
{
  // The name of the controller, which should be unique
  name = thrust
  // The ModuleEngines engineID to follow
  engineID = none
}

Atmosphere Density Controller

This controller links to the atmospheric depth, which is the current density raised to the power of Settings.AmosphereDensityExponent (0.5128 by default).

ATMOSPHEREDENSITYCONTROLLER
{
  // The name of the controller, which should be unique
  name = atmosphereDepth
}

Randomness Controller

This controller creates randomness that can be used in effects. It can be configured with different random distributions, these can be Uniform or Perlin.

Uniform

Uniform noise generates random values between two numbers. It is specified by a noiseType of random. It has an additional parameter of range, which is a field used to specify the minimum and maximum of the randomness generated.

RANDOMNESSCONTROLLER
{
  // The name of the controller, which should be unique
  name = random
  // The noise distribution type
  noiseType = random
  // distribution parameters
  range = -1,1
}

Perlin

Perlin noise generates scrolling predictable values between two numbers. It is specified by a noiseType of perlin. It has additional parameters:

• randomSeed, boolean indicating whether a random seed should be used. Defaults to true.
• seed, which is a field used to specify the noise starting point. Only used if randomSeed is false. Multiple controllers (e.g. on multiple placements of the same part) with the same seed value will return the same output value at the same time.
• speed, which is a field used to specify the rate at which values change
• minimum, which is a field used to specify the minimum value of the noise
• scale, which is a field used to specify the maximum value of the noise

RANDOMNESSCONTROLLER
{
  // The name of the controller, which should be unique
  name = random
  // The noise distribution type
  noiseType = perlin
  // distribution parameters
  minimum = 0
  scale = 1
  speed = 2
}

RCSController

This controller links the effects to RCS thrust. It provides multiple values, one for each transform matching thrusterTransformName.

• thrusterTransformName, the name of the thruster transforms in the ModuleRCSFX you want to control

IMPORTANT: When linking to RCS, it is essential that the number and order of effect transforms specified in the effect match the ones the RCS uses to generate thrust.

RCSCONTROLLER
{
  // The name of the controller, which should be unique
  name = rcs
  thrusterTransformName = thruster
}

GimbalController

This controller links the effects to the engine's gimbal, outputting a value of 1 when the gimbal is fully actuated along the axis and -1 along the reverse. It requires the specification of an additional axis parameter.

• axis, Must be x, y, or z

GIMBALCONTROLLER
{
  // The name of the controller, which should be unique
  name = gimbal
  // axis to link to
  axis = x
}

Mach Number Controller

This controller links to the mach number.

MACHCONTROLLER
{
  // The name of the controller, which should be unique
  name = mach
}

Engine Event Controller

This controller is designed to allow effects to be controlled by specific engine events, like startup, shutdown. The output value is the time since the event happened, mapped through a curve, up until eventDuration has elapsed.

• eventName, required: specifies which event to trigger on. Values are flameout or ignition.
• engineID, optional: if there is more than one engine module, select the one with this ID.
• eventDuration, specifies how long the event lasts

Ignition Event

This event plays when the engine is ignited from an off state.

ENGINEEVENTCONTROLLER
{
  // The name of the controller, which should be unique
  name = ignition
  // The event
  eventName = ignition
  // The duration of the event in seconds
  eventDuration = 2
  // The values supplied by the controller during the event. keys are time, values are output values
  eventCurve
  {
    key = 0 0
    key = 0.2 1 
    key = 2 0
  }
}

Flameout Event

This event plays when the engine is disabled from an on state (both running out of fuel or manual shutdown).

ENGINEEVENTCONTROLLER
{
  // The name of the controller, which should be unique
  name = flameout
  // The event
  eventName = flameout
  // The duration of the event in seconds
  eventDuration = 2
  // The values supplied by the controller during the event. keys are time, values are output values
  eventCurve
  {
    key = 0 0
    key = 0.2 1 
    key = 2 0
  }
}

Custom Pull Controller

This controller pulls a value from some other module on the same part.

• moduleTypeName, the module type to pull from
• engineIDFieldName, if there is more than on module of the specified type, this is the name of a field on the module to use as the identifier.
• engineID, together with engineIDFieldName, this is used to disambiguate between multiple modules of the same type.
• memberName, specifies the member of the module to pull from. Can be a method (taking no arguments), field, or property.
• predicateFieldName, Optional: specifies the name of a boolean field on the module that toggles the value on or off. For example for ModuleEngines this can be set to isOperational so that the controller will return 0 when the engine is off, regardless of what the memberName value is.

CUSTOMPULLCONTROLLER
{
  // The name of the controller, which should be unique
  name = custom1
  moduleTypeName = ModuleControlSurface
  memberName = deployAngle
  minInputValue = -90
  maxInputValue = 90
}

Custom Push Controller

This controller is designed to be used by other mods, which push a value into the controller. Other mods should set CustomPushController.stagedValue to change the value.

CUSTOMPUSHCONTROLLER
{
  name = customPush
}

Engine On Off Controller

Returns either 0 or 1 depending on whether the engine is active.

• engineID, for disambiguating between multiple engine modules
• responseRateUp
• responseRateDown

ENGINEONOFFCONTROLLER
{
  name = engineOn
  responseRateUp = 1
  responseRateDown = 1
}

Light Controller

Returns the intensity value of a light.

• lightName - the name of the light component to use. If omitted, finds the first light on the part.

LIGHTCONTROLLER
{
  name = light
  lightName = spotLight
}

Remap Controller

Remaps the value of some other controller through a curve.

• sourceController - the name of the controller to track
• responseRateUp
• responseRateDown

REMAPCONTROLLER
{
  name = remap
  sourceController = throttle
}

Scalar Module Controller

Pulls the value of any module implementing IScalarModule. The stock list of modules are:

Module name	default ID
ModuleAnimateGeneric	genericAnim
ModuleAnimationSetter	animSetter
ModuleColorChanger	colorChanger
ModuleDeployablePart	deployablePart
ModuleJettison	jettison
ModuleLight	lightModule
ModuleProceduralFairing	fairing
ModuleServiceModule	serviceModule

Parameters:

• moduleID - required. Finds the module with ScalarModuleID equal to this value. Note that this usually comes from the moduleID field in the cfg, but could also be set by code.

SCALARMODULECONTROLLER
{
  name = deploy
  moduleID = genericAnim
}

Velocity Controller

Returns the vessel's speed.

• mode - 0 for surface speed, 1 for orbital speed, 2 for vertical speed

VELOCITYCONTROLLER
{
  name = speed
  mode = 0
}