View source for Modding:Buffs

← [[Modding:Index|Index]]

This page documents custom buffs.

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

This consists of a string → model lookup, where...
* The key is a [[Modding:Common data field types#Unique string ID|unique string ID]] for the buff.
* The value is a model with the fields listed below.

{| class="wikitable"
|-
! field
! purpose
|-
| <samp>DisplayName</samp>
| A [[Modding:Tokenizable strings|tokenizable string]] for the buff name.
|-
| <samp>Description</samp>
| ''(Optional)'' A [[Modding:Tokenizable strings|tokenizable string]] for the buff name. Default none.
|-
| <samp>IsDebuff</samp>
| ''(Optional)'' >Whether this buff counts as a debuff, so its duration should be halved when wearing a [[Sturdy Ring|sturdy ring]]. Default false.
|-
| <samp>GlowColor</samp>
| ''(Optional)'' The glow color to apply to the player. See [[Modding:Common data field types#Color]]. Default none.
|-
| <samp>Duration</samp>
| The duration in milliseconds for which the buff should be active. This can be set to value <samp>-2</samp> for a buff that should last for the rest of the day.
|-
| <samp>MaxDuration</samp>
| ''(Optional)'' The maximum buff duration in milliseconds. If specified and larger than <samp>Duration</samp>, a random value between <samp>Duration</samp> and <samp>MaxDuration</samp> will be selected for each buff. Default none.
|-
| <samp>IconTexture</samp>
| The asset name for the texture containing the buff's sprite.
|-
| <samp>IconSpriteIndex</samp>
| ''(Optional)'' The sprite index for the buff icon within the <samp>IconTexture</samp>. Default 0.
|-
| <samp>Effects</samp>
| ''(Optional)'' The buff attributes to apply. Default none.

This consists of a model with any combination of these fields:
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>FarmingLevel</samp><br /><samp>FishingLevel</samp><br /><samp>ForagingLevel</samp><br /><samp>LuckLevel</samp><br /><samp>MiningLevel</samp><br /><samp>CombatLevel</samp>
| ''(Optional)'' An amount applied to the matching [[Skills|skill level]] while the buff is active. This can be negative for a debuff. Default 0.
|-
| <samp>Attack</samp><br /><samp>Defense</samp><br /><samp>MagneticRadius</samp><br /><samp>MaxStamina</samp><br /><samp>Speed</samp><br /><samp>Immunity</samp><br /><samp>KnockbackMultiplier</samp><br /><samp>WeaponSpeedMultiplier</samp><br /><samp>AttackMultiplier</samp><br /><samp>CriticalChanceMultiplier</samp><br /><samp>CriticalPowerMultiplier</samp><br /><samp>WeaponPrecisionMultiplier</samp>
| ''(Optional)'' An amount applied to the player's [[attack]], [[defense]], [[Magnetism|magnetic radius]], maximum [[Energy|stamina]], [[speed]], [[immunity]], [[weight]] multiplier, [[speed|weapon speed]] multipler, [[attack]] multiplier, [[Crit._Chance|crit chance]] multiplier, [[Crit._Power|crit power]] multiplier, or weapon percision multiplier while the buff is active. This can be negative for a debuff. Default 0.
|}
|-
| <samp>ActionsOnApply</samp>
| ''(Optional)'' Run any number of [[Modding:Trigger actions|trigger action strings]] when the buff is applied to the current player. For example, this increments a player stat:
<syntaxhighlight lang="js">
"ActionsOnApply": [
    "IncrementStat {{ModId}}_NumberEaten 1"
]
</syntaxhighlight>
|-
| <samp>CustomFields</samp>
| ''(Optional)'' The [[Modding:Common data field types#Custom fields|custom fields]] for this entry. 
|}

[[Category:Modding]]

==For C# mod authors==
1.6 rewrites buffs to work more consistently and be more extensible:

* Buff logic is unified into <samp>Game1.player.buffs</samp>, which is the single source of truth for buff data. This replaces the previous <samp>player.added*</samp> and <samp>player.appliedBuffs</samp> fields, <samp>BuffsDisplay</samp> 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 <samp>Buff.ENDLESS</samp> to remove the duration. It'll last all day until the player sleeps.
* You can add standard buff effects to any equipment by overriding <samp>Item.AddEquipmentEffects</samp>, or add custom behaviour/buffs by overriding <samp>Item.onEquip</samp> and <samp>Item.onUnequip</samp>.
* You can add custom food or drink buffs by overriding <samp>Item.GetFoodOrDrinkBuffs()</samp>.
* The <samp>Buff</samp> 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 <samp>BuffsDisplay.displayAttributes</samp> list.
* You can have invisible buffs by setting <samp>buff.visible = false</samp>.

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

<syntaxhighlight lang="c#">
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);
</syntaxhighlight>

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

[[ru:Модификации:Бонусы]]
[[zh:模组:效果]]