Modular curve

This feature requires FreeSpace Open

Revision information.....

FSO Git Commit: Date: 2024-12-10 SHA: 228fd17

Note: Please update the revision information when the page is updated. If your edit had nothing to do with new code entries then please do not edit the revision information

FS2 Open, 25.0:

Modular curves are an SCP feature which uses the curves defined in Curves.tbl to allow many different parameters to drive behaviors according to arbitrary curves -- for example, causing the brightness of a laser bolt to scale with its current velocity. Each modular curve entry has an input and an output, as well as the name of the curve to use. The input and output are always scalar floating-point numbers. The input corresponds to the curve's X axis, while the output corresponds to the Y axis. When the modular curve entry is queried, the system uses the input's current value as X, gets the corresponding Y value, and sets the value of the output to that.

There are multiple different modular curve sets throughout FSO. Each curveset has a group of possible inputs and a group of possible outputs, depending on what's relevant for the circumstances. For example, a set of curves relating to weapons might have parameters like "weapon velocity" or "lifetime" as inputs, and parameters like "laser radius multiplier" or "turn rate multiplier" as outputs. Meanwhile, a curveset relating to ships might have inputs like "current health fraction" or "engine energy", and outputs like "shield regen multiplier" or "speed multiplier". Some curvesets are derived from other curvesets, which means that they inherit their parent curveset's inputs and outputs, but may add more inputs or outputs associated with specific circumstances.

Any time a modular curveset is available, you may define as many entries as you like. It is permitted to have multiple entries with the same input/output pair. If multiple entries affect the same output, the different values will be multiplied together before being used.

When constructing curves for use in modular entries, note that for multipliers, 1.0 is the value which has no effect on the underlying value, while for adders, 0.0 is the value that has no effect.

The syntax for a modular curve entry is as follows:

$Entry Name:

• The name of the type of modular curve this is, such as "Weapon Lifetime Curve" or "Particle Source Curve", generally preceded by "$" and followed by ":". For more details, see the page for whatever table you are working with.
• Syntax: String

+Input:

• Defines the input. A list of available input names can be found on the page for the table you're working with.
• Syntax: String

+Output:

• As above, but for the output!
• Syntax: String

+Curve Name:

• Defines the curve to be used.
• "+Curve:" is also valid
• Syntax: String, name of a curve defined in Curves.tbl

+Random Scaling Factor:

• Multiplies the input by a randomized value when the curve is queried, effectively stretching or shrinking the curve along the X axis.
• In cases where a curve entry is associated with an entity -- like a weapon or a ship -- and will be repeatedly queried over the course of that entity's existence, as in the case of a curve being queried every frame over a weapon's lifetime, each entity's random value will be consistent over time and tracked individually. That is, each weapon will have a different random value, but a given weapon's value will remain the same for its entire lifetime.
• Defaults to 1.0, which has no effect.
• Syntax: Parsed random range

+Random Translation:

• Adds a randomized value to the input when the curve is queried, effectively moving the curve along the X axis.
• Random values are consistent and tracked individually, as above.
• In combination with the scaling factor, useful for causing behavior to vary chaotically between entities.
• Optional. Defaults to 0.0, which has no effect.
• Syntax: Parsed random range

+Wraparound:

• Any given curve has a lowest keyframe and a highest keyframe along the X axis. This parameter defines how the modular curve entry will behave when the input value is outside that range.
• If wraparound is off, input values below the lowest keyframe will use the lowest keyframe's Y value for the output, and input values above the highest keyframe will use the highest keyframe's value. In other words, the lowest and highest keyframes' Y values stretch into infinity along the X axis.
• If wraparound is on, an input value exceeding the highest keyframed value will overflow and wrap around so as to remain within the defined range, and likewise, values which are too low will underflow. In essence, the range defined by the keyframes will be treated as repeating endlessly along the X axis.
• Wraparound can sometimes produce very unintuitive behavior. If your modular curve isn't acting the way you expect, check if the problem goes away when wraparound is off!
• Optional. Defaults to true, God help us.
• Syntax: Boolean, true or false (or yes or no)

Sample Entries

$Lifetime Curve:
	+Input: Base Damage
	+Output: Laser Radius Mult
	+Curve Name: Curve_01
	+Wraparound: False
$Lifetime Curve:
	+Input: Apparent Size
	+Output: Laser Length Mult
	+Curve Name: Curve_02
        +Random Scaling Factor: (0.5 2.5)
        +Random Translation: (-0.7 0.1)
        +Wraparound: True