How to mod 🔮Buffs

There are multiple possibilities for how your own buffs can be implemented.

Modifying an existing buff

That is, modifying a buff from the base game. This is done with Actions (if you're not sure what this means, click the link) of the following types: Replace, or Overrides.

It is preferable to avoid doing this if you want your mod to be compatible with other mods that modify the same base game files. If two or more mods are trying to modify the same thing, that causes problems. Not to mention, the original functionality of the buffs may be lost, in case that's not what you are trying to achieve.

Making your own buff

To add a new buff to the game, in your mod.rules file you need Actions of the following types: Add, AddMany, or Overrides with CreateIfNotExisting = true.

Creation

In your mod.rules file, give a name to your buff in the Action adding it to the buffs.rules file, then add it to ReceivableBuffs like so:

{
		Action = Overrides
		OverrideIn = "<buffs/buffs.rules>/NameOfMyBuff"
		CreateIfNotExisting = true
		Overrides
		{
			CombineMode = Max
			BaseValue = 100%

			Icon
			{
				Texture
				{
					File = "icons/buff_nameofmybuff.png"
					MipLevels = 2
					SampleMode = Linear
				}
				Size = [2, 2]
			}

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

	{
		Action = Add
		AddTo = "<ships/base_part.rules>/Part/ReceivableBuffs"
		Name = NameOfMyBuff
		ToAdd = NameOfMyBuff
	}

The name should be descriptive and unique (it could include your personal prefix for example, like mod.rules files in general) so that any buff added by another mod is unlikely to have the same name. That would cause problems.

Source

Add a source for the buff. Two possibilities :

1. Add it to an existing part

This will allow you to skip the part-making process entirely. However your buff provider may be affected by changes from other mods that affect the same part. To do this, add a BuffProvider component in the .rules file of an existing part, with an Action like this one :

{
	Action = Overrides
	OverrideIn = "<ships/terran/reactor_small/reactor_small.rules>/Part/Components"
	CreateIfNotExisting = true
	Overrides
	{
		BuffProvider
		{
			Type = GridBuffProvider
			BuffType = NameOfMyBuff
			BuffAmount = 25%
			GridDistance = 2
			Criteria
			{
				Category = uses_power
			}
		}
	}
}

2. Bake it into a new part that comes with your mod.

To do this, the BuffProvider component will simply be included in the .rules file of your new part, like so :

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

There are a few parameters you can change here, click the Buffprovider link to find out, or more specifically this one for GridBuffProvider or here for OperationalToggle.

In this context, OperationalToggle decides whether or not your buff is being provided. If the toggle you put there is ("returns", technically) true, your buff is being provided, or not if it's false. Typically the value used here in the base game is IsOperational, which is defined near the top of the part's components and checks for the part being turned On, and powered/crewed if applicable. You might want to change this to a custom toggle.

Examples

(WIP)

Affected parts

Finally, something needs to be affected by it, else the buff has no reason to be in the game, taking up memory.

Add this BuffToggle component to any part it should affect, or use an Add/Overrides action to insert it into an existing part.

NameOfMyBuffToggle
	{
		Type = BuffToggle
		BuffType = NameOfMyBuff
	}

You can then reference it in the rest of the part's code for effects. It can be done in multiple places.

"What places" depends entirely on what you want your buff to do.

By desired buff effect

Work in Progress

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

Feel free to contribute to make it better!

These subsections will tell you the more specific, shortest series of steps you can follow to achieve these results, depending on what you want.

Requiring relative part placement

This is how you can tell the game and the players that a part should be placed in a specific way next to another part, like chaingun magazines, railgun segments or MRT parts.

((WIP))

Distributing resources

This is how to establish a crewless supply chain between parts, like engine rooms, chaingun parts and MRT extenders and their fuel pods.

((WIP))

Projectile scaling like the Railgun

This is how to have parts influence the characteristics of projectiles that come from them, like the railgun launcher does.

The general principle is to pass a value from the part to the projectile, while using a mix of buffable value brackets and math formulas to scale the projectile's data field(s).

((WIP))

Never seen in the base game

There are other things you can do with buffs that have no equivalent in the base game. Here are a few.

((WIP))