Tutorial: Adding Buffs
Last edited by AtlasVBot on 2025-09-13 18:56:00
With Content Patcher, it's easier than ever to add buffs to food and create custom buffs! This tutorial will cover both adding vanilla buffs to objects and creating a custom buff using just Content Patcher.
Before You Start
This tutorial assumes you know how to create a basic edible object with CP, and will gloss over adding an item itself. If you don't know how, check out Tutorial: Adding a New Crop and/or Tutorial: Adding Recipes with CP if you want a cooked dish! For the adding a new crop tutorial, you only need to know how to add the item itself to follow this guide - adding a crop itself isn't necessary.
As always, the official wiki is a great companion for more in depth documentation. Objects Wiki Page Buffs Wiki Page
Set Up
First, set up a simple content pack with a manifest and a content.json. See how to make a manifest here: Tutorial: How to create a manifest
Then, set up a simple edible object with no buffs yet.
{
"Format": "2.8.0",
"Changes": [
{
"LogName": "Magic blueberry assets load",
"Action": "Load",
"Target": "Mods/{{ModId}}/MagicBlueberry" ,
"Fromfile": "assets/MagicBlueberry.png"
},
{
"LogName": "Add magic blueberry item",
"Action": "EditData",
"Target": "Data/Objects",
"Entries": {
"{{ModId}}_MagicBlueberry": {
"Name": "{{ModId}}_MagicBlueberry",
"DisplayName": "Magic Blueberry",
"Description": "It's glowing with magic...",
"Edibility": "100",
"Type": "Basic",
"Category": -79,
"Price": "600",
"Texture": "Mods\\{{ModId}}\\MagicBlueberry",
"SpriteIndex": 0,
"ContextTags": [
"color_iridium",
"dye_strong"
]
}
}
}
]
}
Here, I loaded the asset for the magic blueberry object, and added the entry for it. It's time to add the magic!
Adding a buff to an object - Using an Existing Vanilla Buff
The buff data will be a field within the object data. The buffs field is a list, since a single object can have multiple buffs.
"Buffs": [
{
"Id": "{{ModId}}_LuckBuff",
"BuffId": "statue_of_blessings_1"
}
]
This is the bare minimum for a buff. The Id refers to the unique id of the buff within this specific item's buff list. It's highly recommended to use {{ModId}}_ for the Id still, for a consistent naming convention.
The BuffId property is optional, and is used when you want to add an existing buff in vanilla to your item. You can find the vanilla buff ids in Content/Data/Buffs.json after the content folder is unpacked (you should ideally have them unpacked already, but if not reference how in the official wiki here.
But because sticking to vanilla buffs only is limited and restricting, learning how to add custom buffs can be very helpful. And thankfully, it's not complicated at all!
Adding a buff to an object - Adding a custom buff
There are two ways to add a custom buff to an object - either manually adding properties into the object itself, or adding a custom buff then referencing that buff in the BuffId field. I will cover adding a custom buff then referencing it, but the other way should be similar, with nearly the same fields, just in different locations. For the method of adding the properties to the object, you will add fields in the buff model that was set up in the previous section, just without specifying a BuffId.
First, add a new entry in content.json, within the Changes list, and do an EditData targeting Data/Buffs.
{
"LogName": "Adding a custom buff!",
"Action": "EditData",
"Target": "Data/Buffs",
"Entries": {
}
}
When you make a custom buff, the main properties you need are the display name, the duration, the icon texture, and the effect itself. There are other fancy properties like descriptions, glow color, trigger actions, etc, but the ones listed before are the ones necessary.
Key: The key will be the unique id of the custom buff. I strongly recommend adding {{ModId}} to the front, as it will ensure that it is unique from other mods.
Display name: The display name is the one that will show when the player's cursor hovers over the buff icon. Since this is the display name, not the internal name, it would ideally be an i18n token. You can reference Tutorial: Making Dialogue Compatible with Other Languages (i18n) since it covers how to set up i18n and how to use tokens if you don't know how or haven't set it up yet.
Duration: This refers to the duration, measured in milliseconds, of the buff. When set to -2, it will last for the entire day.
Icon texture: This refers to the asset used for the buff icon. For reference, vanilla buff icon assets are located at Content/Tilesheets/BuffsIcons when unpacked. You can either create a custom icon or use one of the existing vanilla icons.
Here's an example buff icon I made for this tutorial:
Also, the dimensions of a buff icon are 16x16. Debuffs usually have a dark red border.
You can go really creative with this! Make sure it looks recognizable from a distance. Details can get lost at the in-game scale.
If you made a custom icon, there's an extra step I listed in the Extras section, so be sure to reference that!
Effects: This field will consist of a model with combinations of fields, including various level changes, attack/defense changes, speed, stamina, and more. For an extensive list, check the Effects section of the official wiki page.
{
"LogName": "Adding a custom buff!",
"Action": "EditData",
"Target": "Data/Buffs",
"Entries": {
"{{ModId}}_LuckBuff": {
"DisplayName": "{{i18n:LuckBuff.DisplayName}}", // This is what it might look like with i18n.
"Duration": -2, // This sets it to last for the entire day
"IconTexture": "Mods\\{{ModId}}\\BuffIcon", // If it's using a vanilla buff icon, this will be "Tilesheets\\BuffsIcons"
"IconSpriteIndex": 0, // The index within the icon texture set above. Each index is 16x16, and is read left to right, top to bottom.
"Effects": {
"LuckLevel": 1.0,
"Speed": 2.0
}
}
}
}
Adding the custom buff to the object
Adding it is very simple and close to the original way with the vanilla buff. You simply need to change the BuffId value in the object to match your custom buff's id. In my case, it's {{ModId}}_LuckBuff.
"Buffs": [
{
"Id": "{{ModId}}_LuckBuff",
"BuffId": "{{ModId}}_LuckBuff"
}
]
That's It!
For more detailed documentation, check out the official wiki page on this topic! I might come back to this to add some steps for glow effects and any of the optional fields, so keep an eye out for that :)
Here's the full code, stitched together:
{
"Format": "2.8.0",
"Changes": [
{
"LogName": "Magic blueberry assets load",
"Action": "Load",
"Target": "Mods/{{ModId}}/MagicBlueberry" ,
"Fromfile": "assets/MagicBlueberry.png"
},
{
"LogName": "Add magic blueberry item",
"Action": "EditData",
"Target": "Data/Objects",
"Entries": {
"{{ModId}}_MagicBlueberry": {
"Name": "{{ModId}}_MagicBlueberry",
"DisplayName": "Magic Blueberry",
"Description": "It's glowing with magic...",
"Edibility": "100",
"Type": "Basic",
"Category": -79,
"Price": "600",
"Texture": "Mods\\{{ModId}}\\MagicBlueberry",
"SpriteIndex": 0,
"ContextTags": [
"color_iridium",
"dye_strong"
],
"Buffs": [
{
"Id": "{{ModId}}_LuckBuff",
"BuffId": "{{ModId}}_LuckBuff"
}
]
}
}
},
{
"LogName": "Loading the icon asset",
"Action": "Load",
"Target": "Mods/{{ModId}}/BuffIcon", // Where the asset is being loaded to
"FromFile": "assets/bufficon.png" // Change this to where your asset is stored, relative to your mod folder.
},
{
"LogName": "Adding a custom buff!",
"Action": "EditData",
"Target": "Data/Buffs",
"Entries": {
"{{ModId}}_LuckBuff": {
"DisplayName": "{{i18n:LuckBuff.DisplayName}}", // This is what it might look like with i18n.
"Duration": -2, // This sets it to last for the entire day
"IconTexture": "Mods\\{{ModId}}\\BuffIcon", // If it's using a vanilla buff icon, this will be "Tilesheets\\BuffsIcons"
"IconSpriteIndex": 0, // The index within the icon texture set above. Each index is 16x16, and is read left to right, top to bottom.
"Effects": {
"LuckLevel": 1.0,
"Speed": 2.0
}
}
}
}
]
}
Extras
Loading the Icon Asset - Only for custom assets!
If you are using a vanilla asset for the icon, you can skip this section. If you're made a custom icon for your buff, you need to load it before you can use it.
Add the following above the custom buff entry.
{
"LogName": "Loading the icon asset",
"Action": "Load",
"Target": "Mods/{{ModId}}/BuffIcon", // Where the asset is being loaded to
"FromFile": "assets/bufficon.png" // Change this to where your asset is stored, relative to your mod folder.
}