Static syntax - KSPSnark/IndicatorLights GitHub Wiki

What's a "static"?

In IndicatorLights, a "static" is a numeric constant with a floating-point value. Unlike a scalar value, which can change dynamically at run time, a static's value is calculated just once, at module OnStart time, and then that value is used for the life of the module.

On the one hand, this makes statics less flexible than scalars, since they can't be used to model dynamic behavior. On the other hand... it totally lets them off the hook, in terms of performance. Static expressions can be arbitrarily complex without worrying about impacting performance, since they're calculated only once instead of on every frame.

Note that a static is actually a special case of a scalar, which means that anywhere you're allowed to put a scalar syntax, you're also allowed to put a static syntax instead. However, the reverse is not true.

IndicatorLights provides a variety of static syntax options to allow achieving various complex effects. This page describes the syntax of static parameters and provides some examples.

Please see the IndicatorLights syntax overview for a high-level summary of the syntax language, a discussion of the various other types of syntax available besides statics, and debugging tips.

Note that statics, like all IndicatorLights syntax, can be nested to form complex expressions. For example:

between(subtract(multiply(sqrt(static(dataRate)), 1.1), 2.3), -0.4, 0.5))

...this means "take the square root of the value of the static field dataRate, multiply by 1.1, then subtract 2.3; then use that value, unless it's less than -0.4 (in which case use that), or unless it's greater than 0.5 (in which case use that)."

Where's the code?

See Statics.cs for the source code in IndicatorLights that handles the parsing of statics.

Types of static

The following types of scalar syntax are supported:

The following sections describe the syntax for each of these types of static.

Literal numeric values

The simplest form of static is a literal number, such as "0", "3.5", or "-1.3e5".

The only requirement is that it has to be parseable as a double.

Field reference

Some modules designate certain (unchanging) fields as "static fields". These fields can be referenced by name to use their values in static expressions.

For example, ModuleDataTransmitterIndicator defines a static field dataRate, which stores the speed at which the antenna can transmit data. Since this field has been marked as a static field, then it's possible to use "dataRate" as a static expression in the module's syntax expressions. For example, the antenna config uses dataRate to control how fast the antenna indicator blinks when the antenna is transmitting.

The field reference syntax is simple:

static(fieldname)

...for example, "static(dataRate)" means "use the value of the static field dataRate on this module."

Note that you can only do this for specific fields that have been designated as static fields. These fields may be exposed as KSPField values on the PartModule, but aren't necessarily. To identify which static fields (if any) are available on any give controller module, please see the module's description in the controller reference. Alternatively, if you're looking at the module's source code, you can identify static fields because they have the StaticField annotation on them.

Parameterized

This is the most complex (but most flexible and powerful) type of static syntax. It allows specifying some complex behaviors by using parameters.

A parameterized static has the form:

functionName(param1,param2,param3,...)

The number and type of parameters will depend on what the function is.

The following functions are currently supported (more may be added in the future):

add

This adds two or more static inputs together. Synonyms: sum, plus.

add(static1, static2, ...)

Parameters:

  • Each input is a static value.
  • The result is the sum of all the inputs.

Example: add(1, 2, 3) evaluates to 6.

subtract

This subtracts one static from another. Synonyms: subtract, difference, diff, minus

subtract(static1, static2)

Parameters:

  • Each input is a static value.
  • The result is static1 minus static2.

Example: subtract(10, 1) evaluates to 9.

multiply

This multiplies two or more static inputs together. Synonym: product

multiply(static1, static2, ...)

Parameters:

  • Each input is a static value.
  • The result is the product of all the inputs.

Example: multiply(2, 3, 5) evaluates to 30.

divide

This divides one static by another. Synonym: quotient

divide(static1, static2)

Parameters:

  • Each input is a static value.
  • The result is static1 divided by static2.

Example: divide(6, 2) evaluates to 3.

sqrt

This takes the square root of a static.

sqrt(static)

Parameters:

  • The input is a static value.
  • The result is the square root of the input.

Example: sqrt(64) evaluates to 8.

minimum

This takes the minimum value of two or more static inputs. Synonym: min

minimum(static1, static2, ...)

Parameters:

  • Each input is a static value.
  • The result is the lowest of all the inputs.

Example: minimum(7, 3, 11) evaluates to 3.

maximum

This takes the maximum value of two or more static inputs. Synonym: max

maximum(static1, static2, ...)

Parameters:

  • Each input is a static value.
  • The result is the highest of all the inputs.

Example: maximum(7, 3, 11) evaluates to 11.

between

This gets the value of an input, constrained to be between a specified minimum and maximum.

between(static, minimum, maximum)

Parameters:

  • static: The static input value.
  • minimum: The static minimum value allowed.
  • maximum: The static maximum value allowed.

Examples:

  • between(100, 5, 10) evaluates to 10
  • between(0, 5, 10) evaluates to 5
  • between(7, 5, 10) evaluates to 7