Modding:Buffs

← Index

This page documents custom buffs.

Data format

You can define custom buffs by editing the Data/Buffs asset. You can then use the buff from other places like Data/Object's Buff field or the C# Buff constructor.

This consists of a string → model lookup, where...

• The key is a unique string ID for the buff.
• The value is a model with the fields listed below.

field	purpose
DisplayName	A tokenizable string for the buff name.
Description	(Optional) A tokenizable string for the buff name. Default none.
IsDebuff	(Optional) >Whether this buff counts as a debuff, so its duration should be halved when wearing a sturdy ring. Default false.
GlowColor	(Optional) The glow color to apply to the player. See Modding:Common data field types#Color. Default none.
Duration	The duration in milliseconds for which the buff should be active. This can be set to value -2 for a buff that should last for the rest of the day.
MaxDuration	(Optional) The maximum buff duration in milliseconds. If specified and larger than Duration, a random value between Duration and MaxDuration will be selected for each buff. Default none.
IconTexture	The asset name for the texture containing the buff's sprite.
IconSpriteIndex	(Optional) The sprite index for the buff icon within the IconTexture. Default 0.
Effects	(Optional) The buff attributes to apply. Default none. This consists of a model with any combination of these fields: field purpose FarmingLevel FishingLevel ForagingLevel LuckLevel MiningLevel CombatLevel (Optional) An amount applied to the matching skill level while the buff is active. This can be negative for a debuff. Default 0. Attack Defense MagneticRadius MaxStamina Speed Immunity KnockbackMultiplier WeaponSpeedMultiplier AttackMultiplier CriticalChanceMultiplier CriticalPowerMultiplier WeaponPrecisionMultiplier (Optional) An amount applied to the player's attack, defense, magnetic radius, maximum stamina, speed, immunity, weight multiplier, weapon speed multipler, attack multiplier, crit chance multiplier, crit power multiplier, or weapon percision multiplier while the buff is active. This can be negative for a debuff. Default 0.
ActionsOnApply	(Optional) Run any number of trigger action strings when the buff is applied to the current player. For example, this increments a player stat: "ActionsOnApply": [ "IncrementStat {{ModId}}_NumberEaten 1" ]
CustomFields	(Optional) The custom fields for this entry.

For C# mod authors

1.6 rewrites buffs to work more consistently and be more extensible:

• Buff logic is unified into Game1.player.buffs, which is the single source of truth for buff data. This replaces the previous player.added* and player.appliedBuffs fields, BuffsDisplay logic, enchantment stat bonuses, and boots/ring attribute changes on (un)equip.
• This also removes limitations on buff types (e.g. buffs can add weapon bonuses and weapons can add attribute buffs) and buffable equipment (e.g. equipped tools can have buffs too).
• Buff effects are now fully recalculated when they change, to fix a range of longstanding bugs like attribute drift and double-debuffs. Just like before, the buffs are managed locally; only the buff IDs and aggregate attribute effects are synced.

For C# mods:

• Each buff now has a unique string ID. You can apply a new buff with the same ID to replace it (so you no longer need to manually find and remove previous instances of the buff).
• The buff duration can now be set to Buff.ENDLESS to remove the duration. It'll last all day until the player sleeps.
• You can add standard buff effects to any equipment by overriding Item.AddEquipmentEffects, or add custom behaviour/buffs by overriding Item.onEquip and Item.onUnequip.
• You can add custom food or drink buffs by overriding Item.GetFoodOrDrinkBuffs().
• The Buff constructor now supports a custom icon texture, sprite index, display name, description, and millisecond duration to fully support custom buffs.
• You can change how buff attributes are displayed (or add new attributes) by extending the BuffsDisplay.displayAttributes list.
• You can have invisible buffs by setting buff.visible = false.

For example, here's how to add a custom buff which adds +3 speed:

Buff buff = new Buff(
    id: "Example.ModId_ZoomZoom",
    displayName: "Zoom Zoom", // can optionally specify description text too
    iconTexture: this.Helper.ModContent.Load<Texture2D>("assets/zoom.png"),
    iconSheetIndex: 0,
    duration: 30_000, // 30 seconds
    effects: new BuffEffects()
    {
        Speed = { 10 } // shortcut for buff.Speed.Value = 10
    }
);
Game1.player.applyBuff(buff);

You can also implement your own custom effects in code by checking if the buff is active, like Game1.player.hasBuff("Example.ModId_ZoomZoom").