🔮 Buffs

See also: List of Buffs

Buffs are effects that allow parts to alter the properties and stats of other parts, including themselves as a "self-buff". They are not part components, nor projectile components.

Anything that can be affected by a buff is said to be '"buffable". Values lacking this property are not compatible with the buffing system and must be modified in other ways.

How They Work

Mostly, buff providers handle what parts are the sources of buffs, and then the receiving parts may use toggles, scaling and so on for the buffs to have an effect.

All the buffs in the game can be found in buffs/buffs.rules file (see more about where to find it and other .rules files).

You can add new buffs to the game in your mod, by adding them to that file. There are always other necessary steps, but those depend on what each individual buff is supposed to do.

The buff itself (as found in buffs.rules) is defined by the following parameters.

Parameters (Complete list)

Name	Type	Required	Default value	Description
BuffID	ID<BuffType>	Yes	true	The name for your buff. This should be unique across the game.
CombineMode	BuffCombineMode	No		How the buff behaves when multiple buffs are applied to the same part.
BaseValue	float	No	-	Influences the effect of the buff. Is presumably added to the BuffAmount in a BuffProvider component.
MinValue	float	No	float.NegativeInfinity	Presumably goes up to 2,147,483,647 and accepts negative values (needs test).
MaxValue	float	No	float.PositiveInfinity	Presumably goes up to 2,147,483,647 and accepts negative values (needs test).
Exponent	float	No	1	Influences the effect of the buff. Exact formula unclear.
Multiplier	float	No	1	Influences the effect of the buff. Exact formula unclear.
Icon	ISprite? meaning : A path to a PNG	No	-	What icon visual the buff will try to display on whatever part(s) is/are affected.
IconTextFormatKey	string?	No	-	Presumably a reference to what formatting should be applied. See Stats for more about formatting.
IconTextMultiply	float	No	1	Possibly scales the size of the displayed icon's companion text.
IconTextAdd	float	No	-	??
IconPriority	int	No	0	If multiple buff icons are trying to be displayed on the same part, only the one with the highest value here will be displayed.
ShowIconTextForZeroValue	bool	No	true	Whether or not the text for the buff's value should be displayed when the buff's value is 0. Engine, RailgunShot and RocketThrust have "false".
RectBorderColor	Color meaning : A color code	No	-	Presumably the color of the borders of UI rectangle containing the icon.
RectFillColor	Color meaning : A color code	No	-	Presumably the background color of the UI rectangle containing the icon.

Buffable values

Buffs are typically used to modify values. Only these types of value can be buffed :

• BuffableAngle
• BuffableFloat (by far the most common)
• BuffableInt
• BuffableTime

See also : the BuffableValue part component.

Do note that you can use a toggle detecting the buff's presence if you just need a boolean check, for example to activate something or display an icon.

BuffValueMode

Specifies how a buff value will impact the base value.

These are all the available ways to apply a buff's "value" to the BaseValue (see BuffableValues above) :

BuffValueMode	Meaning	Notes
Replace	The buff value will replace the base value.
Add	The buff value will be added to the base value.
Subtract	The buff value will be subtracted from the base value.
Multiply	The buff value will be multiplied with the base value.	Often used to proportionally increase effects. Used by thrusters for an engine_room buff.
Divide	The base value will be divided by the buff value.	Often used for increasing speed by reducing delays. Helps preventing BaseValue from going negative.
Lerp	The new value will be calculated using the buff value to lerp between the MinValue and MaxValue.	See BuffableValues.

Criteria

Main article : RelativePartCriteria.

These are used inside of part components to filter what parts can or cannot receive the buff.

Formula

You can make pretty complicated formulas by using buffs, like with the Railgun. It can also be quite simple, like the buff from Engine Room.

Here is the full formula :

Final value = Buff.BaseValue + ( BuffProvider.BaseValue Buff.Multiplier * Buff.Count ^ Buff.Exponent)

• Buff.Count is the value that can be seen in the devmode's PartDebugger under "Buffs".

WIth the railgun's numbers, that's :

TargetValue * (1+ 20% * [Number of Accelerators]^0,8)

Examples

Railgun

This is the Railgun's final buff if you set the BaseValue of RailgunShot to zero :

RailgunShot science 1

As you can see, that makes the buff's final value start at -80% and then rise normally. Comparing with the default values reveals a missing 100% total buff in every result.

This demonstrates that BaseValue is simply added to the final result.

ViaBuffs

Work in Progress

This section is currently work-in-progress. Some things may be missing.

Feel free to contribute to make it better!

Examples

Let's look at examples from the base game.

Engine Room

Engine Rooms apply 2 buffs to nearby thrusters.

1. One of the buffs makes said thrusters 50% stronger, with 50% increased fuel usage. In the code, that buff is named Engine.
2. The other buff handles battery distribution.

Info

Note: the Engine Room's .rules file can be found at : ships\terran\engine_room\engine_room.rules

Now, let's look at the Engine buff defined in buffs.rules :

Engine
{
	CombineMode = Max
	BaseValue = 100%

	Icon
	{
		Texture
		{
			File = "buff_engine.png"
			MipLevels = 2
			SampleMode = Linear
		}
		Size = [2, 2]
	}
	IconTextFormatKey = "BuildBox/BuffPercentageFmt"
	IconTextMultiply = 100
	IconTextAdd = -100

	RectBorderColor = [10, 212, 98, 160]
	RectFillColor = [10, 212, 98, 64]
}

To provide the buff, engine_room.rules has a BuffProvider component.
This is where the value BuffAmount that indicates the "strength" of the buff is set:

BuffProvider
{
	Type = GridBuffProvider
	BuffType = Engine
	BuffAmount = 50%
	GridDistance = 1
	OperationalToggle = IsOperational
}

Finally, to receive the buff and apply its effect(s) we must go into a thruster .rules file and modify some things. Since there are multiple thrusters, let's pick, for example, the large thruster — its .rules file is located at ships\terran\thruster_large\thruster_large.rules.

For the buff to take effect, the .rules must contain the following four(4) parts:
1. The buff's name (BuffType) must be added to the ReceivableBuffs[] list of buffs.

Note: ^/0/ReceivableBuffs adds any buffs defined in the part from which the current part (EngineRoom) was inherited from. The base part for EngineRoom is base_part_terran.rules, so any buffs defined there in ReceivableBuffs will be added. This even includes the buffs inherited in base_part_terran.rules from its base part, base_part.rules.
More on path syntax.

ReceivableBuffs : ^/0/ReceivableBuffs [Engine]

2. A toggle must be added that "detects the presence" of the added buff type:

EngineBuffToggle
{
	Type = BuffToggle
	BuffType = Engine
}

3. The block added in step 2 must be used as toggle for the battery consumption component ToggledBatteryConsumer:

ToggledBatteryConsumer
{
	Type = ToggledComponents
	Toggle = EngineBuffToggle
	Invert = true
	IncludeInBlueprints = true
	Components
	{
		BatteryConsumer
		{
			Type = ResourceConsumer
			ResourceType = battery
			Storage = BatteryStorage
			DefaultPriority = &/PRIORITIES/Thruster_Supply
			ResupplyThreshold = 500
			OperationalToggle = PowerToggle
		}
	}
}

4. Lastly, the effect is applied in the MainThruster component (see MaxActivation field):

MainThruster
{
	Type = Thruster
	Location = [1, 2.5]// Relative to upper-left corner of unrotated part.
	Rotation = 90d// Relative to unrotated part.
	OperationalToggle = IsOperational
	Force = &../../ThrusterForce
	MinActivation = 0
	MaxActivation = { BaseValue=1; BuffType=Engine; BuffMode=Multiply; }
	MinUncommandedActivation = &MinActivation
	MaxUncommandedActivation = &MaxActivation
	ActivationIncreaseTime = &../../ThrustIncreaseTime
	ActivationRecoveryTime = &../../ThrustRecoveryTime
	FuelStorage = BatteryStorage
	FuelUsagePerSecond = &../../FuelUsage
}

Recap

1. A buff exists in buffs.rules
2. A BuffProvider provides it
3. In each receiver :
   1. It's added to ReceivableBuffs
   2. A component detects it presence or absence
   3. A component turns things On/Off if the buff is present
   4. A component that's only active if the buff is present modifies a value with it.

Railgun

The railgun has 3 buffs:

1. one is the percent buff, which is what is shown on the build screen and is what determines the % buff,
2. the operational buff, which is a buff that is passed upwards from the loader when it's operational,
3. and it's counterpart, the reverse operational buff, which is passed downwards from the launcher;

The railgun may only fire if both the operational buff reaches the launcher, and the reverse operational buff reaches the loader, through any accelerators.

Railgun Compared to MRT

The difference between railguns and MRT is that it doesn't have as restrictive of a condition to activate, since extenders that are down still propagate power.

The "operational buff" moves through powered down extenders, and the % buff is from the extenders, moving downward only if the buff that confirms that there is in fact a base thruster at the end of the system, is buffing the extender.

Practical Application

Main article: How to mod 🔮Buffs