Potion effects API

Effect

An Effect represents a potion effect (speed, strength, invisibility, etc.) that can be applied to players. Effects have a type, duration, amplifier, and visual settings.

---

Constructor

Effect(effect_type=None, duration=0, amplifier=0, ambient=False, particles=True, icon=True)

Create an effect.

• Parameters:
• effect_type (EffectType | str | None) — The effect type (e.g. "SPEED", EffectType.INVISIBILITY).
• duration (int) — Duration in ticks (20 ticks = 1 second). Default 0.
• amplifier (int) — Effect level minus 1. Speed II = amplifier 1. Default 0.
• ambient (bool) — Whether the effect came from a beacon (translucent particles). Default False.
• particles (bool) — Whether to show particles. Default True.
• icon (bool) — Whether to show the effect icon in the HUD. Default True.

speed = Effect("SPEED", duration=600, amplifier=1)         # Speed II for 30 seconds
invis = Effect(EffectType.INVISIBILITY, duration=1200)      # Invisibility for 60 seconds
silent = Effect("REGENERATION", 200, particles=False, icon=False) # Hidden regen

---

Class Methods

apply

await Effect.apply(player, effect_type=None, duration=0, amplifier=0, ambient=False, particles=True, icon=True)

Create and apply an effect to a player in one call.

• Parameters:
• player (Player) — Target player.
• effect_type (EffectType | str | None) — Effect type.
• duration (int) — Duration in ticks. Default 0.
• amplifier (int) — Effect level minus 1. Default 0.
• ambient (bool) — Beacon-style particles. Default False.
• particles (bool) — Show particles. Default True.
• icon (bool) — Show icon. Default True.
• Returns: Awaitable[Any]

await Effect.apply(player, "SPEED", duration=600, amplifier=1)

---

Attributes

type

• Type: EffectType

The effect type.

duration

• Type: int

Remaining duration in ticks.

amplifier

• Type: int

Effect amplifier (level minus 1).

ambient

• Type: bool

Whether particles are translucent (beacon-style).

particles

• Type: bool

Whether particles are visible.

icon

• Type: bool

Whether the HUD icon is shown.

---

Methods

with_duration

new_effect = await effect.with_duration(duration)

Create a copy of this effect with a different duration.

• Parameters:
• duration (int) — New duration in ticks.
• Returns: Awaitable[Effect]

base = Effect("SPEED", 100, amplifier=2)
long_speed = await base.with_duration(6000)  # 5 minutes

with_amplifier

new_effect = await effect.with_amplifier(amplifier)

Create a copy of this effect with a different amplifier.

• Parameters:
• amplifier (int) — New amplifier.
• Returns: Awaitable[Effect]

---

Applying to Players

You can apply effects in two ways:

# 1. Using the class method shortcut
await Effect.apply(player, "SPEED", duration=200, amplifier=1)

# 2. Construct then apply via Player
speed = Effect("SPEED", duration=200, amplifier=1)
await player.add_effect(speed)

To remove an effect:

await player.remove_effect(EffectType.SPEED)

To list active effects:

for effect in player.effects:
    print(f"{effect.type.name}: {effect.duration} ticks remaining")

---

Duration Reference

Duration	Ticks
1 second	20
5 seconds	100
30 seconds	600
1 minute	1200
5 minutes	6000
10 minutes	12000