Buff System

Journey includes a powerful and extensible buff system that allows you to grant temporary or permanent effects to players as rewards, bonuses, or through other gameplay mechanics.

🛠️ Visual Buff Builder Create buff configurations with an easy-to-use visual interface

What are Buffs?

Buffs are effects that modify player attributes, apply status effects, execute scripts, or interact with game systems like Cobblemon. They can be:

Temporary (expire after a set duration) or Permanent (last forever)
Stackable (multiple instances can exist) or Unique (only one at a time)
Visible (shown to player) or Hidden (background effects)
Beneficial or Debuffs (negative effects)

Built-in Types

4 Types

Attribute modification
Potion effects
Script execution
Shiny chance boost

Extensible

API Available

Third-party mods can add custom buff types through the BuffTypeRegistry

Integration

Buffs can be granted as:

Task rewards
Levelable rewards
Command grants
Custom triggers

Persistent

Buffs survive:

Server restarts
Player logout/login
World reloads

Buff Types

Attribute Buffs

Modify player attributes like movement speed, attack damage, health, etc.

Operations:

add_value - Adds flat value to attribute
add_multiplied_base - Adds percentage of base value
add_multiplied_total - Multiplies total value

Example:

{
  "id": "speed_boost",
  "type": "attribute",
  "name": "Speed Boost",
  "description": "Increases movement speed by 20%",
  "max_stacks": 1,
  "is_debuff": false,
  "hidden": false,
  "attribute": "minecraft:generic.movement_speed",
  "operation": "add_multiplied_base",
  "value": 0.2
}

Potion Buffs

Apply Minecraft potion effects with custom settings. Every potion effect can be used.

Example:

{
  "id": "regeneration",
  "type": "potion",
  "name": "Regeneration",
  "description": "Slowly restores health",
  "max_stacks": 1,
  "is_debuff": false,
  "hidden": false,
  "potion_effect": "minecraft:regeneration",
  "show_particles": false,
  "show_icon": true,
  "ambient": false
}

Script Buffs

Execute MoLang scripts when buff is applied, ticked, or removed.

Available Scripts:

on_apply_script - Runs once when buff is applied
on_tick_script - Runs periodically based on tick_interval
on_remove_script - Runs once when buff is removed

Script Context:

Full player context (q.player.* functions)
Buff properties (query.amplifier(), query.remaining_ticks(), query.buff_duration())
MoLang query functions

Example:

{
  "id": "explorers_celebration",
  "type": "script",
  "name": "Explorer's Celebration",
  "description": "A burst of energy celebrates your achievement",
  "max_stacks": 1,
  "is_debuff": false,
  "hidden": false,
  "on_apply_script": "q.player.tell_minimessage('&lt;gold&gt;✨ You feel a surge of explorer\\'s energy! ✨&lt;/gold&gt;')",
  "on_tick_script": "query.random(1, 100) > 90 ? q.player.snowstorm_particle('journey:sparkle', query.position_x + query.random(-1, 1), query.position_y + query.random(0, 2), query.position_z + query.random(-1, 1)) : 0",
  "on_remove_script": "q.player.tell_minimessage('&lt;gray&gt;The explorer\\'s energy fades...&lt;/gray&gt;')",
  "tick_interval": 20
}

Shiny Chance Buffs

Increase the chance of encountering shiny Pokémon (Cobblemon integration).

How it Works:

Integrates with Cobblemon’s shiny calculation event
Multiple shiny buffs stack additively
Applies to all Pokémon encounters while buff is active

Example:

{
  "id": "shiny_hunter",
  "type": "shiny_chance",
  "name": "Shiny Hunter",
  "description": "Increases your chance of encountering shiny Pokémon",
  "max_stacks": 3,
  "is_debuff": false,
  "hidden": false,
  "chance_increase": 100.0
}

Configuration

File Location

Buff definitions are stored as JSON files in:

config/journey/buffs/

Each buff should be in its own .json file. On first run, Journey creates several example buffs.

Common Properties

All buff types share these properties:

Property	Type	Default	Description
`id`	String	Required	Unique identifier for the buff
`type`	String	Required	Buff type: `attribute`, `potion`, `script`, `shiny_chance`
`name`	String	`null`	Display name shown to player
`description`	String	`null`	Description shown to player
`max_stacks`	Integer	`1`	Maximum number of instances allowed
`is_debuff`	Boolean	`false`	Whether this is a negative effect
`hidden`	Boolean	`false`	Whether to hide from player UI

Type-Specific Properties

Attribute Buff Properties

Property	Type	Required	Description
`attribute`	String	Yes	Minecraft attribute identifier
`operation`	String	Yes	`add_value`, `add_multiplied_base`, or `add_multiplied_total`
`value`	Number	Yes	Value to apply (meaning depends on operation)

Potion Buff Properties

Property	Type	Default	Description
`potion_effect`	String	Required	Minecraft potion effect identifier
`show_particles`	Boolean	`true`	Show particle effects
`show_icon`	Boolean	`true`	Show effect icon in inventory
`ambient`	Boolean	`false`	Ambient effect (lighter particles)

Script Buff Properties

Property	Type	Default	Description
`on_apply_script`	String	`""`	MoLang script to run on apply
`on_tick_script`	String	`""`	MoLang script to run periodically
`on_remove_script`	String	`""`	MoLang script to run on remove
`tick_interval`	Integer	`20`	Ticks between on_tick_script executions

Shiny Chance Buff Properties

Property	Type	Required	Description
`chance_increase`	Number	Yes	Amount to increase shiny chance by

Using Buffs as Rewards

Task Rewards

Buffs can be granted when tasks are completed:

{
  "name": "catch_first_pokemon",
  "display_name": "Catch Your First Pokémon",
  "rewards": [
    {
      "type": "buff",
      "data": {
        "buff_id": "shiny_hunter",
        "duration": 6000,
        "amplifier": 0,
        "source": "first_catch_task"
      }
    }
  ]
}

Levelable Rewards

Buffs can be granted when players level up a levelable:

{
  "name": "Pokemon Breeder",
  "description": ["Become an expert at breeding Pokémon!"],
  "levels": [
    {
      "level": 5,
      "required_experience": 1000,
      "rewards": [
        {
          "type": "buff",
          "data": {
            "buff_id": "shiny_hunter",
            "duration": -1,
            "amplifier": 1,
            "source": "breeder_levelable"
          }
        }
      ]
    }
  ]
}

Reward Properties

Property	Type	Description
`buff_id`	String	ID of the buff definition to apply
`duration`	Integer	Duration in ticks (20 ticks = 1 second), `-1` for permanent
`amplifier`	Integer	Buff level (0-based, 0 = base effect, 1 = enhanced, etc.)
`source`	String	Optional source identifier for tracking/removal

Duration and Amplifier

Duration

Duration is specified in ticks (20 ticks = 1 second):

200 = 10 seconds
600 = 30 seconds
1200 = 1 minute
6000 = 5 minutes
-1 = Permanent/infinite

Amplifier

Amplifier is 0-based and affects buffs differently:

Attribute Buffs: Value is multiplied by (amplifier + 1)

Amplifier 0: value * 1 (100% of value)
Amplifier 1: value * 2 (200% of value)
Amplifier 2: value * 3 (300% of value)

Potion Buffs: Passed directly to potion effect

Amplifier 0: Potion effect level I
Amplifier 1: Potion effect level II
Amplifier 2: Potion effect level III

Script Buffs: Available as query.amplifier() in scripts

Shiny Chance Buffs: Chance is multiplied by (amplifier + 1)

Amplifier 0: chance_increase * 1
Amplifier 1: chance_increase * 2
Amplifier 2: chance_increase * 3

Stacking Behavior

Buffs can have multiple instances active based on max_stacks:

Single Stack (`max_stacks: 1`)

Only one instance can be active
Applying again refreshes duration to new duration
Amplifier updates to new amplifier

Multiple Stacks (`max_stacks: 2+`)

Multiple instances can exist simultaneously
Each instance has its own duration and amplifier
When max is reached, oldest instance is refreshed

Example: Shiny Hunter with max_stacks: 3

Player gets buff with amplifier 0 → 1 instance active (+100 shiny chance)
Player gets buff with amplifier 0 → 2 instances active (+200 shiny chance)
Player gets buff with amplifier 1 → 3 instances active (+300 shiny chance total)

Source Tracking

The source field in buff rewards allows tracking where buffs came from:

Benefits

Bulk removal: Remove all buffs from a specific source
Automatic cleanup: Buffs from levelables are removed when levelable is lost
Organization: Track which systems granted which buffs

Naming Convention

For levelable rewards, use: "{levelable_name}_levelable"

Example:

{
  "buff_id": "speed_boost",
  "duration": -1,
  "source": "explorer_levelable"
}

When the “Explorer” levelable is removed, all buffs with source "explorer_levelable" are automatically removed.

Commands

Apply Buff Command

Apply a buff to a player:

/journey buff apply <player> <buff_id> [duration] [amplifier]

Parameters:

<player> - Target player
<buff_id> - Buff identifier (just the name, e.g., speed_boost not journey:speed_boost)
[duration] - Optional duration in ticks (-1 for permanent, defaults to permanent)
[amplifier] - Optional amplifier level (defaults to 0)

Examples:

/journey buff apply @p speed_boost 600 0
/journey buff apply AmoAster shiny_hunter -1 2

Remove Buff Command

Remove a specific buff from a player:

/journey buff remove <player> <buff_id>

Example:

/journey buff remove @p speed_boost

Clear Buffs Command

Remove all buffs from a player:

/journey buff clear <player>

Example:

/journey buff clear @p

List Buffs Command

List all active buffs on a player:

/journey buff list <player>

Example:

/journey buff list @p

Reload Buffs Command

Reload all buff configurations from disk:

/journey buff reload

Advanced: Custom Buff Types

Third-party mods can register custom buff types using the BuffTypeRegistry API.

Custom Buff Types Guide Learn how to create your own buff types (for mod developers)

Examples

Speed Boost for Task Completion

Grant a 30-second speed boost when player completes a task:

Buff Definition (config/journey/buffs/task_speed.json):

{
  "id": "task_speed",
  "type": "attribute",
  "name": "Task Completion Rush",
  "description": "Temporary speed boost for completing a task!",
  "max_stacks": 1,
  "is_debuff": false,
  "hidden": false,
  "attribute": "minecraft:generic.movement_speed",
  "operation": "add_multiplied_base",
  "value": 0.3
}

Task Configuration:

{
  "name": "explore_village",
  "display_name": "Explore the Village",
  "rewards": [
    {
      "type": "buff",
      "data": {
        "buff_id": "task_speed",
        "duration": 600,
        "amplifier": 0
      }
    }
  ]
}

Permanent Shiny Boost from Levelable

Grant permanent shiny boost when player reaches Breeder level 10:

Levelable Configuration:

{
  "name": "Pokemon Breeder",
  "levels": [
    {
      "level": 10,
      "required_experience": 10000,
      "rewards": [
        {
          "type": "buff",
          "data": {
            "buff_id": "shiny_hunter",
            "duration": -1,
            "amplifier": 2,
            "source": "breeder_levelable"
          }
        }
      ]
    }
  ]
}

Celebration Effect with Particles

Create a celebratory buff with particles when player achieves something:

Buff Definition:

{
  "id": "celebration",
  "type": "script",
  "name": "Celebration!",
  "description": "You did something amazing!",
  "max_stacks": 1,
  "is_debuff": false,
  "hidden": false,
  "on_apply_script": "q.player.tell_minimessage('&lt;rainbow&gt;✨ AMAZING! ✨&lt;/rainbow&gt;'); q.player.play_sound('minecraft:entity.player.levelup', 1.0, 1.0)",
  "on_tick_script": "q.player.snowstorm_particle('minecraft:happy_villager', query.position_x + query.random(-1, 1), query.position_y + query.random(0, 2), query.position_z + query.random(-1, 1))",
  "on_remove_script": "q.player.tell_minimessage('&lt;gray&gt;Back to normal!&lt;/gray&gt;')",
  "tick_interval": 10
}

Best Practices

Naming IDs

Use descriptive, lowercase IDs with underscores:

✅ shiny_hunter, speed_boost, mining_haste
❌ buff1, SpeedBoost, shiny-hunter

Duration Values

For readability, use these common durations:

{
  "duration": 200,    // 10 seconds
  "duration": 600,    // 30 seconds
  "duration": 1200,   // 1 minute
  "duration": 6000,   // 5 minutes
  "duration": 12000,  // 10 minutes
  "duration": -1      // Permanent
}

Source Naming

Use consistent source naming:

Levelables: "{levelable_name}_levelable"
Tasks: "{task_name}_task"
Custom systems: "{mod_id}_{feature_name}"

Max Stacks

Use max_stacks: 1 for unique buffs that shouldn’t stack
Use higher values when stacking makes sense (shiny buffs, damage buffs)
Consider balance: more stacks = more powerful

Hidden Buffs

Use hidden: true for:

Background calculations
System-level effects
Effects that shouldn’t clutter player UI

Troubleshooting

Buff Not Loading

Check:

JSON syntax is valid (use a JSON validator)
File is in config/journey/buffs/ directory
File has .json extension
Server logs for error messages

Buff Not Applying

Check:

Buff ID matches exactly (case-sensitive)
Player doesn’t already have max_stacks instances
Duration is valid (-1 or positive number)
Server logs for error messages

Attribute Buff Not Working

Check:

Attribute name is valid Minecraft attribute
Operation is one of: add_value, add_multiplied_base, add_multiplied_total
Value is appropriate for the operation
Player has the attribute (not all entities have all attributes)

Script Not Executing

Check:

MoLang syntax is correct
Script doesn’t have syntax errors (check logs)
For on_tick_script, ensure tick_interval is reasonable
Functions used exist in Journey’s MoLang implementation

Next Steps

Tasks System Learn how to create tasks that grant buffs

Levelables System Create levelables with buff rewards

MoLang Scripting Write powerful script buffs

Custom Buff Types Create your own buff types (developers)

Buff System

Buff System

What are Buffs?

Buff Types

Attribute Buffs

Potion Buffs

Script Buffs

Shiny Chance Buffs

Configuration

File Location

Common Properties

Type-Specific Properties

Attribute Buff Properties

Potion Buff Properties

Script Buff Properties

Shiny Chance Buff Properties

Using Buffs as Rewards

Task Rewards

Levelable Rewards

Reward Properties

Duration and Amplifier

Duration

Amplifier

Stacking Behavior

Single Stack (max_stacks: 1)

Multiple Stacks (max_stacks: 2+)

Source Tracking

Benefits

Naming Convention

Commands

Apply Buff Command

Remove Buff Command

Clear Buffs Command

List Buffs Command

Reload Buffs Command

Advanced: Custom Buff Types

Examples

Speed Boost for Task Completion

Permanent Shiny Boost from Levelable

Celebration Effect with Particles

Best Practices

Naming IDs

Duration Values

Source Naming

Max Stacks

Hidden Buffs

Troubleshooting

Buff Not Loading

Buff Not Applying

Attribute Buff Not Working

Script Not Executing

Next Steps

Single Stack (`max_stacks: 1`)

Multiple Stacks (`max_stacks: 2+`)