Welcome to the BukkitWiki!

This Wiki is home to Bukkit's documentation and regulations surrounding the Bukkit Project and it's services. Want to help out? We would love to have you! Signup to get started!

User:N3X15/Potion Bitflags

From BukkitWiki
Jump to: navigation, search

Here's a bunch of highly technical notes regarding potions since they're quite a bit more complex than other kinds of items.

A potion (currently) defines a single effect that can be given to a user or mob. However, the way in which these effects are defined in the code is highly complex, given the nature of brewing within Minecraft. Ingredients can be mixed with other ingredients to create a potion or enhance the potion already brewed. In order to facilitate this, potions are stored as a complex script that tells Minecraft which bits of the brew's durability value should be turned off or on.

Potion Durability Value Breakdown

First, however, a simple rundown on how the potion durability value is currently structured.

Effect Type

The potion type is determined by the first four bits of durability value of the item stack. For example, if the stack is of a potion with durability 16384, it would break down as follows:

 0100 0000 0000 0001

As the first four bits are 0001, the potion is a regeneration potion. The 14th bit indicates that it is a Splash Potion.

The "effect type" of the potion usually becomes its suffix. (Potion of X)

Potion Type IDs
ID# Name Effects Crafted From
1 (0001) Regeneration Regenerates health slowly over time Ghast Tear + Awkward Potion
2 (0010) Swiftness Increases movement speed. Sugar + Awkward Potion
3 (0011) Fire Resistance Avoids damage to flames Magma Cream + Awkward Potion
4 (0100) Poison Hurts target over time Spider Eye + Awkward Potion
5 (0101) Healing Heals 3 hearts instantly. Glistering Melon + Awkward Potion
6 (0110) Unused
7 (0111) Unused
8 (1000) Weakness Damage dealt is much less than normal. Fermented Spider Eye + Awkward Potion
9 (1001) Strength Boosts damage, obviously. Blaze Powder + Awkward Potion
10 (1010) Slowness Reduces motion speed. Fermented Spider Eye + Swiftness Potion
11 (1011) Unused
12 (1100) Harming Instantly removes 3 hearts of health. Fermented Spider Eye + Potion of Poison
13 (1011) Unused
14 (1110) Unused
15 (1111) Unused


Potions in Minecraft have several bitflags to mark enhancements to the potion or additional information.

NOTE: The indexes of the bits are 0-based.

Bit Description
4 Marks an Awkward potion. Without this flag, you will be unable to brew most of the potions above.
5 Effect boosted by Glowstone dust.
6 Duration boosted by Redstone dust.
7 Unknown, but referenced.
13 Appears to mark a concoction as unbrewable.

Set if bit 4 is NOT set, in most cases.

14 Turned into a Splash potion by gunpowder.

Overall Structure

Overall Durability Structure
Bit Type
0 Potion Effect
4 Flags
12 Flags

Bit Matching Expressions

Minecraft uses a special, proprietary expression reported created by jeb_ for matching potion effects with their bit sequences. In utility, it's both a scripting language and a regular expression, meaning it can set bits, or it can merely match bits with what the potion effect requests.

Like a scripting language, it consists of operators and constants processed by a simple interpreter, although many other elements of scripting languages are missing, such as variables or methods.

The matching expressions are used to determine which potion effects apply for each potion. The bit manipulation expressions apply when potions are brewed (e.g. Netherwart uses "+4" to set bit 5 in a potion).


Each number in jeb_'s bit manipulation expressions expresses a single bit index in the durability value of the potion ItemStack. At the present, the indexes seem to suggest that the maximum size of the durability value is 16 bits. However, the durability value is internally handled in Minecraft as a full 32-bit integer. Whether that's true when it's transmitted over the wire or not remains to be seen.

Each index number is 0-based, so 0 would indicate the first bit, while 4 would indicate the 5th bit.


Minecraft uses several operators for processing and matching bits. However, they are interpreted differently depending on how the expression is being used. Below is a table of these operators and their uses.

Operators and their meanings
Operator Used for Matching Used to Manipulate Bits
No Operator Bit == 1 Unknown
! Bit == 0 Toggles bit status (Boolean NOT)
& Logical AND (expression & expression) If the bit is set, then clear ALL bits and continue parsing
| Logical OR (expression | expression)  
+ Sum of the two bits (bit + bit) (Used for determining damage) Set bit to 1
- Subtract one bit's value from the other (bit - bit) (Used for determining damage) Set bit to 0
* Multiply the bit or expression's value with another bit (Used for determining damage)  


Matching Expressions

Example Meaning
0 & !1 & !2 & 3 & 3+6 If bit 0 == 1 and bit 1 == 0 and bit 2 == 0 and bit 3 == 1, then the strength of the potion is the sum of bit 3 and bit 6 (1 + 1 or 0)