API reference / @jsprismarine/item-behaviors
@jsprismarine/item-behaviors
The vanilla item behavior families. @jsprismarine/items turns Java 26.3's 122 data component types into parsed data and declares seven hooks; none of its components implements one. This package is what fills them.
Two things are in here. The behavior families, which are Behavior<ItemHooks> objects the server registers in one call. And the formulas Java computes in code rather than publishing as data: mining speed, break progress, attack damage and Unbreaking, each transcribed from the unobfuscated 26.3 server jar and pinned to golden vectors the jar itself produced.
import { BehaviorRegistry } from '@jsprismarine/content';
import { loadItemTypes } from '@jsprismarine/items';
import { deferredItemFactory, registerVanillaItemBehaviors } from '@jsprismarine/item-behaviors';
const behaviors = new BehaviorRegistry();
const items = deferredItemFactory();
registerVanillaItemBehaviors(behaviors, { world, items });
const { registry } = loadItemTypes({ behaviors });
items.bind(registry);world is the server's WorldActions. items makes the stacks a behavior hands back, and it is deferred because the registry does not exist until after the behaviors are registered.
The families
The classifier in families.ts assigns every one of the 1658 Java items of the pinned registry to exactly one family, or to data only. The counts below are measured, families.test.ts asserts each one, and they sum to 1658. Run the classifier yourself with classifyVanillaItems().
A family is recognized one of two ways. Where Java's data already says what the item is, the rule names a component, and the behavior then attaches to every item and binds nothing where the component is absent, so a pack's own food eats with no registration. Where neither edition publishes anything to recognize the item by, the rule names identifiers, which is the list the behavior inventory section 2 measured.
| Family | Items | Recognized by | Behaviors |
|---|---|---|---|
| bow | 1 | name | vanilla:bow |
| crossbow | 1 | name | vanilla:crossbow |
| ammunition | 3 | name | none; a projectile's own behavior is the entity's |
| trident | 1 | name | vanilla:trident, vanilla:melee_weapon |
| mace | 1 | name | vanilla:mace, vanilla:melee_weapon |
| fishing rod | 1 | name | vanilla:fishing_rod |
| mob steering rod | 2 | name | vanilla:steering_rod |
| shears | 1 | name | vanilla:shears, vanilla:mining_tool |
| fire starter | 2 | name | vanilla:fire_starter |
| bone meal | 1 | name | vanilla:bone_meal |
| spyglass | 1 | name | vanilla:spyglass |
| compass | 2 | name | vanilla:compass |
| clock | 1 | name | none; clockReading is an entry point |
| map | 18 | name | vanilla:map |
| lead | 1 | name | vanilla:lead |
| name tag | 1 | name | vanilla:name_tag |
| brush | 1 | name | vanilla:brush |
| eye of ender | 1 | name | vanilla:eye_of_ender |
| bucket | 4 | name | vanilla:bucket |
| throwable | 9 | name | vanilla:throwable |
| bottle and bowl | 2 | name | vanilla:fillable |
| waxing | 1 | name | vanilla:waxing |
| sign ink | 2 | name | vanilla:sign_ink |
| written book | 2 | name | vanilla:written_book |
| entity placement | 47 | name | vanilla:entity_placement |
| mob bucket | 7 | minecraft:bucket_entity_data | vanilla:mob_bucket |
| shield | 1 | minecraft:blocks_attacks | vanilla:shield |
| elytra | 1 | minecraft:glider | vanilla:equippable |
| totem | 1 | minecraft:death_protection | none; applyDeathProtection is an entry point |
| spear | 7 | minecraft:kinetic_weapon | vanilla:spear, vanilla:melee_weapon |
| firework rocket | 1 | minecraft:fireworks | vanilla:firework_rocket |
| goat horn | 1 | minecraft:instrument | vanilla:goat_horn |
| writable book | 1 | minecraft:writable_book_content | vanilla:writable_book |
| enchanted book | 1 | minecraft:stored_enchantments | none; the anvil reads it |
| banner | 16 | minecraft:banner_patterns or name | vanilla:banner |
| dye | 16 | minecraft:dye | vanilla:dye |
| bundle | 17 | minecraft:bundle_contents | vanilla:bundle |
| spawn egg | 88 | minecraft:entity_data | vanilla:spawn_egg |
| potion | 1 | minecraft:potion_contents | vanilla:potion, vanilla:consumable |
| suspicious stew | 1 | minecraft:suspicious_stew_effects | vanilla:suspicious_stew, vanilla:consumable |
| ominous bottle | 1 | minecraft:ominous_bottle_amplifier | vanilla:ominous_bottle, vanilla:consumable |
| block transforming tool | 21 | minecraft:block_transformer | vanilla:block_transformer, vanilla:mining_tool, vanilla:melee_weapon |
| mining tool | 7 | a #minecraft:mineable/* tool rule | vanilla:mining_tool, vanilla:melee_weapon |
| melee weapon | 7 | minecraft:weapon | vanilla:melee_weapon, vanilla:mining_tool |
| equippable | 82 | minecraft:equippable | vanilla:equippable |
| food | 39 | minecraft:food | vanilla:consumable |
| consumable | 1 | minecraft:consumable | vanilla:consumable |
| data only | 1233 | nothing claimed it | none |
Forty-seven families and one terminal bucket. Three things about the numbers are worth stating.
data only is an answer, not a gap. Most of its 1233 items are block items, and placing a block is the block family's rule rather than the item's, so the item side is one shared behavior the blocks package owns. The rest are plain materials with no use behavior in either edition: ingots, gems, sherds, smithing templates, music discs, brewing ingredients.
Classification and attachment are different questions. A family says which behavior owns an item. Attachment says what code runs for it, and more than one behavior runs for many items. A diamond axe is classified block transforming tool, and three behaviors bind to it: the stripping transform, the mining tool's durability and the melee weapon's.
The 53 merged and excepted items carry no components. The item table keeps one Java item's properties per Bedrock identifier, so the fifteen other banner colors, the sixteen structure maps, the tipped arrow and the knowledge book arrive with an empty component map. Those are classified by identifier, which is why the banner and map rules name a pattern as well as a component.
The world seam
Nothing here imports a server class. Every behavior reaches the world through WorldActions, which has nine required queries and one perform. Four optional queries let a host decline an entity action before the item is consumed, answer the structure search an eye of ender makes before it flies, or say which actions it performs at all:
interface WorldActions {
blockAt(position: BlockPosition): BlockReference | undefined;
hardnessOf(block: BlockReference): number;
stateOf(source: ItemSource): SourceState;
environment(): EnvironmentState;
targetOf(source: ItemSource): ItemSource | undefined;
includes(set: HolderSet, member: string): boolean;
transform(transformer: string, block: BlockReference): BlockPlacement | undefined;
effectsOf(potion: string): readonly EffectApplication[];
random(): number;
canNameEntity?(target: ItemSource): boolean;
canDyeEntity?(target: ItemSource, color: string): boolean;
locate?(destination: string, origin: BlockPosition): BlockPosition | undefined;
supports?(action: ItemWorldActionKind): boolean;
perform(action: ItemWorldAction): void;
}Effects go through one tagged union of 28 variants rather than 28 methods, so adding an effect is a new variant and not a change every adapter has to grow. The variants cover placing and breaking a block, spawning an entity, launching a projectile, sounds, effects, damage, teleports, experience, cooldowns, durability, giving and equipping items, naming, leashing, dyeing, shearing, fertilizing, igniting, brushing, blocking, maps, a signal toward a structure and opening a screen.
createTestWorld is the typed double, exported rather than kept in the test folder because this is the only interface a behavior has to the world. Every query is a value a test sets, every action lands in an ordered log, and random is a fixed sequence so an Unbreaking roll is reproducible.
const world = createTestWorld({ state: { foodLevel: 10 } });
consume(appleStack);
world.performed('feed'); // [{ kind: 'feed', target, nutrition: 4, saturation: 2.4 }]Four decisions about the seam are worth knowing.
There is no entity-interaction hook. ItemHooks has onUse and onUseOn, and Mojang's ItemCustomComponent has no entity hook either. A behavior that acts on an entity, which is the name tag, the lead, the dye, the saddle and the shears, calls targetOf(source) and declines when there is nothing there.
A release is reported as onCompleteUse. The bow, the crossbow and the trident fire on release and the hook table has no release hook. The engine calls onCompleteUse when a held use ends for any reason, and useDuration carries how long it was held, which is the bow's whole power curve.
A behavior asks before it spends. perform returns nothing, so a host that has not written the system behind a variant can only log the action and drop it. A behavior that spends its item on one action, which is the empty map, the knowledge book, the nine throwables, a loaded crossbow, shears on an entity and the fishing rod, calls supports(kind) first through canPerform in behavior.ts. When the host says no, the behavior performs nothing and returns {}: the click is taken and the stack is unchanged, the same answer an eye of ender gives when locate finds no stronghold. A host without supports is taken to perform everything. This is what stops a right click on nothing from spending a map on a server that draws none. createTestWorld({ unsupported: ['map'] }) is how a test plays that host.
Four behaviors are server entry points rather than hooks. A mining speed is a number the engine asks for while a block breaks, a totem fires on the damage path, a gliding elytra wears out on a tick, and a shield's durability cost happens while damage resolves. None of the seven hooks covers those, so they are exported functions, each listed in the family catalog's entryPoints and checked by registry.test.ts.
The formulas
Every formula here is transcribed from the pinned, unobfuscated 26.3 server jar, and the JSDoc on each one quotes the Java it came from. utils/oracle/DumpItemFormulas.java compiles against that jar and writes vectors/formulas.json, which is 1665 cases the test suite checks exactly. All the arithmetic runs through Math.fround, because Java computes these in float and the difference shows: 0.2F is not 0.2, and a speed rounded twice in float is not a speed rounded once in double.
Mining speed
Player.getDestroySpeed(BlockState), line for line:
float speed = this.inventory.getSelectedItem().getDestroySpeed(state);
if (speed > 1.0F) speed += (float)this.getAttributeValue(Attributes.MINING_EFFICIENCY);
if (MobEffectUtil.hasDigSpeed(this)) speed *= 1.0F + (MobEffectUtil.getDigSpeedAmplification(this) + 1) * 0.2F;
if (this.hasEffect(MobEffects.MINING_FATIGUE)) speed *= (float)Math.pow(0.3, amplifier + 1);
speed *= (float)this.getAttributeValue(Attributes.BLOCK_BREAK_SPEED);
if (this.isEyeInFluid(FluidTags.WATER)) speed *= (float)...SUBMERGED_MINING_SPEED...;
if (!this.onGround()) speed /= 5.0F;The tool's own speed is Tool.getMiningSpeed: the first rule whose block set matches and that carries a speed wins, and the default applies when none does. Tool tier is not a constant anywhere in this package, because 26.3 expresses it entirely in that rule list. A diamond pickaxe carries #minecraft:incorrect_for_diamond_tool with correct_for_drops: false and #minecraft:mineable/pickaxe at speed 8, and that is the whole tier.
The attribute defaults come from Attributes: mining_efficiency 0, block_break_speed 1, submerged_mining_speed 0.2. Efficiency raises the first by level * level + 1, from efficiency.json's levels_squared with added: 1.0. Aqua Affinity multiplies the third by five, from aqua_affinity.json's add_multiplied_total with base: 4.0, which takes 0.2 to 1 and removes the underwater penalty outright.
destroyProgress is BlockBehaviour.getDestroyProgress: the speed over the block's hardness over 30 when the tool is correct for drops and 100 when it is not. breakTicks turns that into the whole break, which is 150 ticks for stone with a bare hand and 23 with a wooden pickaxe.
The Bedrock client computes a different number, and the server cannot fix it
This matters enough to state plainly. The Bedrock client decides how long a block takes to break, and server-authoritative-block-breaking does not change that. Mojang's own guide says the toggle makes the client report its prediction and the server agree or correct, not accept a timing from the server ("When the client predicts a block is broken, it notifies the server of this prediction with a PlayerBlockAction [...] the server validates that it agrees with the client's prediction").
The two formulas disagree in at least four places, measured in the edition differences note section 2:
- Haste adds 20% per level in Java. Bedrock multiplies by
(0.2 × level + 1) × 1.2^level. - Mining Fatigue is
0.3^(amplifier + 1)in 26.3's code. Bedrock uses0.3^level × 0.7^level. - Java's
mining_efficiency,block_break_speedandsubmerged_mining_speedhave no Bedrock attribute to send them in, which is Geyser issue #3987, closed asCan't Fix. - Reach differs: 4.5 blocks in Java and 5 on Bedrock with a keyboard, 12 on touch in creative.
A server that uses Java's number disagrees with the client on every enchanted or hasted break, and the player sees blocks pop back. So miningSpeed is the server's figure, for drops, progress validation and anything else the server decides, and the client's own timing is left alone. That is the plan's rule for a client-decided behavior: do not send a correction for something the client owns.
Attack damage
The damage half of Player.attack:
float magicBoost = attackStrengthScale * (this.getEnchantedDamage(...) - baseDamage);
baseDamage *= 0.2F + attackStrengthScale * attackStrengthScale * 0.8F;
baseDamage += attackingItemStack.getItem().getAttackDamageBonus(...);
if (criticalAttack) baseDamage *= 1.5F;
float totalDamage = baseDamage + magicBoost;baseAttackDamage is the player's own 1 plus the item's minecraft:base_attack_damage modifier, so a diamond sword is 7 and a diamond axe is 9. The enchantment bonus scales linearly with the charge while the base scales quadratically, which is why a half-charged sharpened sword keeps most of its enchantment damage and almost none of its own.
attackStrengthScale defaults to 1, a fully charged swing. That is this project's choice for the attack cooldown, and it follows the plan section 12 decision 2: the Bedrock client draws no cooldown meter and plays the strong-attack sound for every connecting hit, so scaling damage by time since the last swing produces hits that deal 20% for no reason the player can see. The parameter is there, and attackStrengthScale(ticks, attackSpeed) computes it from Player.getCurrentItemAttackStrengthDelay, so a server that wants Java's rule passes it.
The mace's bonus arrives through itemBonus and is MaceItem.getAttackDamageBonus: 4 × fall up to 3 blocks, 12 + 2 × (fall - 3) up to 8, and 22 + fall - 8 above that, with no smash at all below 1.5 blocks.
Durability and Unbreaking
spendDurability is ItemStack.hurtAndBreak through processDurabilityChange and applyDamage. A stack takes damage only when it has minecraft:max_damage and minecraft:damage and no minecraft:unbreakable, and a holder with infinite materials spends nothing.
Unbreaking is RemoveBinomial.process: one roll per point of damage against a chance of level / (level + 1) for anything that is not armor and 2 × level / (5 × level + 5) for armor, both read off unbreaking.json. Java truncates the result to an int and skips the whole path when it lands on zero, so an Unbreaking III pickaxe spends nothing three times out of four. Java switches to a normal approximation above 128 points in one hit, which no item use produces, so only the exact branch is implemented.
Consumables
One behavior covers the 47 items carrying minecraft:food or minecraft:consumable, because Java 26.3 already says what each one does. minecraft:food gives nutrition and saturation, minecraft:use_remainder gives the bowl or bottle left behind, minecraft:use_cooldown gives the chorus fruit's second, and minecraft:consumable.on_consume_effects gives the rest. The golden apple, the pufferfish, milk and the honey bottle need no code of their own.
That list is the one place the item package deliberately stops parsing. Its schema keeps the discriminator of each consume effect and drops the payload, because the five effect types belong to whoever runs them. consumeEffects.ts parses the payload once per item type from the definition's own JSON, which BindContext hands a behavior at load, and implements the five: apply_effects, remove_effects, clear_all_effects, teleport_randomly and play_sound.
Three consumables need code because their effects are not in the component that names them. A potion's are in a registry Java keeps in code, in Potions, so WorldActions.effectsOf answers for them. A suspicious stew's were decided by the flower it was crafted with and live on the stack. An ominous bottle's amplifier is a number that has to become 100 minutes of Bad Omen. All three run before the general behavior and return undefined, so the dispatch reaches the one that produces the result. HookTable.dispatchFirst stops at the first handler that returns a value, which is why VANILLA_ITEM_BEHAVIORS is an ordered list and registry.test.ts holds the order.
Tests
vitest run covers 148 cases over five files. behaviors.test.ts builds the real vanilla registry with every behavior attached and dispatches through each item type's own HookTable, so the attachment rules and the dispatch order are under test and not only the handlers. families.test.ts asserts the partition is total and that every family holds the count above. formulas.test.ts checks all 1665 oracle vectors.
Regenerating the oracle vectors
vectors/formulas.json is generated and committed. After a Java version bump:
pnpm --filter @jsprismarine/bedrock-data run dump:java
node packages/item-behaviors/utils/oracle/run.mjsThe dumper compiles against the pinned server jar and needs a JDK of at least version 25 (JAVA_HOME or JSP_JAVA_HOME). It runs with its working directory inside the cache, because Mojang's logger writes a logs/ directory wherever it starts.
Interfaces
ActiveEffect
Defined in: item-behaviors/src/world.ts:37
One status effect the source already has, which can_always_eat and the formulas read.
Properties
amplifier
readonlyamplifier:number
Defined in: item-behaviors/src/world.ts:41
The level above the first.
id
readonlyid:string
Defined in: item-behaviors/src/world.ts:39
The effect identifier.
ApplyEffectsAction
Defined in: item-behaviors/src/world.ts:135
Give an entity status effects, which is the consumable effect path.
Properties
effects
readonlyeffects: readonlyEffectApplication[]
Defined in: item-behaviors/src/world.ts:138
kind
readonlykind:"apply-effects"
Defined in: item-behaviors/src/world.ts:136
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:137
ApplyEffectsConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:21
minecraft:apply_effects: give the effects, with a probability.
Properties
effects
readonlyeffects: readonlyEffectApplication[]
Defined in: item-behaviors/src/consumeEffects.ts:23
kind
readonlykind:"apply-effects"
Defined in: item-behaviors/src/consumeEffects.ts:22
probability
readonlyprobability:number
Defined in: item-behaviors/src/consumeEffects.ts:25
From 0 to 1; apply_effects defaults it to 1.
AttachLeadAction
Defined in: item-behaviors/src/world.ts:227
Tie a lead between two entities, or to a fence when the target is a knot.
Properties
kind
readonlykind:"attach-lead"
Defined in: item-behaviors/src/world.ts:228
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:229
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:230
AttackContext
Defined in: item-behaviors/src/formulas.ts:215
What attackDamage needs, which is one line of Player.attack each.
Properties
attackStrengthScale?
readonlyoptionalattackStrengthScale?:number
Defined in: item-behaviors/src/formulas.ts:225
Player.getAttackStrengthScale(0.5F), from 0 to 1.
Defaults to 1, a fully charged swing, because this project takes Bedrock's behavior for the attack cooldown: the Bedrock client draws no cooldown meter, so a scaled hit would be unexplained. See the README.
baseAttackDamage
readonlybaseAttackDamage:number
Defined in: item-behaviors/src/formulas.ts:217
Attributes.ATTACK_DAMAGE, the player's 1 plus the weapon's modifier.
critical?
readonlyoptionalcritical?:boolean
Defined in: item-behaviors/src/formulas.ts:231
Whether the hit is a critical, which multiplies the base by 1.5.
enchantmentBonus?
readonlyoptionalenchantmentBonus?:number
Defined in: item-behaviors/src/formulas.ts:227
What the weapon's enchantments add, before the charge scales them.
itemBonus?
readonlyoptionalitemBonus?:number
Defined in: item-behaviors/src/formulas.ts:229
Item.getAttackDamageBonus, which is zero for everything but the mace.
BehaviorContext
Defined in: item-behaviors/src/behavior.ts:33
What a family's create gets, which is the bind context plus the environment.
Extends
Properties
components
readonlycomponents:Readonly<Record<string,unknown>>
Defined in: item-behaviors/src/behavior.ts:40
The item type's default components as the definition writes them, before the item package's schemas drop the fields they do not model.
identifier
readonlyidentifier:string
Defined in: item-behaviors/src/behavior.ts:35
The Bedrock identifier of the item type being bound.
items
readonlyitems:ItemFactory
Defined in: item-behaviors/src/items.ts:32
The factory they build result stacks with.
Inherited from
world
readonlyworld:WorldActions
Defined in: item-behaviors/src/items.ts:30
The world the behaviors act on.
Inherited from
BlockPlacement
Defined in: item-behaviors/src/world.ts:17
A block identifier with the state values it is placed with.
Properties
identifier
readonlyidentifier:string
Defined in: item-behaviors/src/world.ts:19
The Bedrock block identifier.
states
readonlystates:Readonly<Record<string,string|number|boolean>>
Defined in: item-behaviors/src/world.ts:21
The state values, keyed by Bedrock state name, empty for the default state.
BlockPosition
Defined in: items/src/hooks.ts:11
A block position in world coordinates.
Declared here rather than imported so the item runtime depends on no world implementation; the server's own vector type is assignable to it.
Properties
x
x:
number
Defined in: items/src/hooks.ts:12
y
y:
number
Defined in: items/src/hooks.ts:13
z
z:
number
Defined in: items/src/hooks.ts:14
BlockReference
Defined in: items/src/hooks.ts:34
The block a hook acts on, named the way Bedrock names one.
Properties
identifier
readonlyidentifier:string
Defined in: items/src/hooks.ts:36
The Bedrock block identifier, such as minecraft:grass_block.
position
readonlyposition:BlockPosition
Defined in: items/src/hooks.ts:40
Where the block is.
states
readonlystates:Readonly<Record<string,string|number|boolean>>
Defined in: items/src/hooks.ts:38
The block state values, keyed by Bedrock state name.
BlockingAction
Defined in: item-behaviors/src/world.ts:267
Raise or lower a shield.
Properties
active
readonlyactive:boolean
Defined in: item-behaviors/src/world.ts:271
Whether blocking starts or stops.
delayTicks
readonlydelayTicks:number
Defined in: item-behaviors/src/world.ts:273
How long before the block takes effect, in ticks.
kind
readonlykind:"blocking"
Defined in: item-behaviors/src/world.ts:268
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:269
BreakBlockAction
Defined in: item-behaviors/src/world.ts:98
Take a block out of the world, which is how a bucket picks a fluid up.
Properties
kind
readonlykind:"break-block"
Defined in: item-behaviors/src/world.ts:99
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:100
BrushAction
Defined in: item-behaviors/src/world.ts:260
Brush a block, which the brush does one step at a time.
Properties
kind
readonlykind:"brush"
Defined in: item-behaviors/src/world.ts:261
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:263
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:262
ClassifiableItem
Defined in: item-behaviors/src/families.ts:27
One item as the classifier sees it: a Java identifier and its default components.
Properties
components
readonlycomponents:Readonly<Record<string,unknown>>
Defined in: item-behaviors/src/families.ts:38
The Java default components, keyed by component name.
Empty for the 53 items the Bedrock join merges or excepts, because the table keeps one row's components per Bedrock identifier. Every one of those 53 is classified by identifier instead, which is why the banner and structure map rules name a pattern as well as a component.
identifier
readonlyidentifier:string
Defined in: item-behaviors/src/families.ts:29
The Java item identifier, such as minecraft:diamond_pickaxe.
ClearEffectsConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:35
minecraft:clear_all_effects: take every effect off, which is milk.
Properties
kind
readonlykind:"clear-all-effects"
Defined in: item-behaviors/src/consumeEffects.ts:36
ConsumeDurabilityAction
Defined in: item-behaviors/src/world.ts:196
Spend durability.
The amount has already been through spendDurability, so it accounts for Unbreaking and for an item with no minecraft:max_damage. A zero amount is never performed.
Properties
amount
readonlyamount:number
Defined in: item-behaviors/src/world.ts:199
broke
readonlybroke:boolean
Defined in: item-behaviors/src/world.ts:201
Whether that damage finished the item off.
kind
readonlykind:"consume-durability"
Defined in: item-behaviors/src/world.ts:197
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:198
DamageEntityAction
Defined in: item-behaviors/src/world.ts:150
Hurt an entity, which an ender pearl does to its thrower.
Properties
amount
readonlyamount:number
Defined in: item-behaviors/src/world.ts:153
damageType
readonlydamageType:string
Defined in: item-behaviors/src/world.ts:154
kind
readonlykind:"damage-entity"
Defined in: item-behaviors/src/world.ts:151
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:152
DeferredItemFactory
Defined in: item-behaviors/src/items.ts:42
An ItemFactory whose registry is supplied after the behaviors are registered.
Extends
Methods
bind()
bind(
registry):void
Defined in: item-behaviors/src/items.ts:44
Points the factory at a registry; calling it again repoints it, which a content reload does.
Parameters
registry
Returns
void
create()
create(
identifier,count?):ItemStack|undefined
Defined in: item-behaviors/src/items.ts:24
One stack of an item.
Parameters
identifier
string
count?
number
Returns
ItemStack | undefined
The stack, or undefined when no item type is registered under the identifier, which a behavior treats as "do nothing" rather than as an error.
Inherited from
DisableShieldAction
Defined in: item-behaviors/src/world.ts:277
Disable an entity's shield, which an axe hit does for five seconds.
Properties
kind
readonlykind:"disable-shield"
Defined in: item-behaviors/src/world.ts:278
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:279
ticks
readonlyticks:number
Defined in: item-behaviors/src/world.ts:280
DurabilityOptions
Defined in: item-behaviors/src/formulas.ts:339
What spendDurability needs besides the stack and the amount.
Properties
creative?
readonlyoptionalcreative?:boolean
Defined in: item-behaviors/src/formulas.ts:343
Whether the holder has infinite materials, which spends nothing.
random
readonlyrandom: () =>number
Defined in: item-behaviors/src/formulas.ts:341
A source of numbers in [0, 1) for the Unbreaking rolls.
Returns
number
DurabilitySpend
Defined in: item-behaviors/src/formulas.ts:327
What spendDurability worked out.
Properties
amount
readonlyamount:number
Defined in: item-behaviors/src/formulas.ts:329
The damage actually applied after Unbreaking and the creative check.
broke
readonlybroke:boolean
Defined in: item-behaviors/src/formulas.ts:333
Whether the item is used up.
damage
readonlydamage:number
Defined in: item-behaviors/src/formulas.ts:331
The stack's new minecraft:damage.
stack
readonlystack:ItemStack
Defined in: item-behaviors/src/formulas.ts:335
The stack to put back, already carrying the new damage, or an empty one when it broke.
DyeEntityAction
Defined in: item-behaviors/src/world.ts:234
Color an entity, which is a dye on a sheep, a collar or a harness.
Properties
color
readonlycolor:string
Defined in: item-behaviors/src/world.ts:237
kind
readonlykind:"dye-entity"
Defined in: item-behaviors/src/world.ts:235
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:236
EffectApplication
Defined in: item-behaviors/src/world.ts:25
One status effect as a behavior asks for it, in Java's own units.
Properties
amplifier
readonlyamplifier:number
Defined in: item-behaviors/src/world.ts:31
The level above the first, so Regeneration II is amplifier 1.
durationTicks
readonlydurationTicks:number
Defined in: item-behaviors/src/world.ts:29
How long it lasts, in ticks.
id
readonlyid:string
Defined in: item-behaviors/src/world.ts:27
The effect identifier, such as minecraft:regeneration.
showIcon
readonlyshowIcon:boolean
Defined in: item-behaviors/src/world.ts:33
Whether the client draws the icon.
EnvironmentState
Defined in: item-behaviors/src/world.ts:74
What a behavior needs to know about the world around the source.
Properties
dimension
readonlydimension:string
Defined in: item-behaviors/src/world.ts:76
The dimension identifier, such as minecraft:overworld.
spawnPosition
readonlyspawnPosition:BlockPosition
Defined in: item-behaviors/src/world.ts:80
The world spawn point, which a compass points at.
timeOfDay
readonlytimeOfDay:number
Defined in: item-behaviors/src/world.ts:78
The time of day in ticks, 0 to 23999, which a clock reads.
EquipAction
Defined in: item-behaviors/src/world.ts:212
Put an item on an entity, which is armor, a saddle, a harness or horse armor.
Properties
item
readonlyitem:ItemStack
Defined in: item-behaviors/src/world.ts:216
kind
readonlykind:"equip"
Defined in: item-behaviors/src/world.ts:213
slot
readonlyslot:EquipmentSlot
Defined in: item-behaviors/src/world.ts:215
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:214
FeedAction
Defined in: item-behaviors/src/world.ts:158
Restore hunger and saturation, which is what eating is for.
Properties
kind
readonlykind:"feed"
Defined in: item-behaviors/src/world.ts:159
nutrition
readonlynutrition:number
Defined in: item-behaviors/src/world.ts:162
Half-drumsticks restored, from minecraft:food.
saturation
readonlysaturation:number
Defined in: item-behaviors/src/world.ts:164
Saturation restored, already the absolute figure Java stores.
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:160
FertilizeAction
Defined in: item-behaviors/src/world.ts:247
Bone meal a block, whose outcome the block family decides.
Properties
kind
readonlykind:"fertilize"
Defined in: item-behaviors/src/world.ts:248
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:249
FishingAction
Defined in: item-behaviors/src/world.ts:316
Cast or reel in a fishing line.
Properties
cast
readonlycast:boolean
Defined in: item-behaviors/src/world.ts:320
Whether the line goes out or comes back.
kind
readonlykind:"fishing"
Defined in: item-behaviors/src/world.ts:317
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:318
GiveItemAction
Defined in: item-behaviors/src/world.ts:205
Put an item in the source's inventory, or drop it when there is no room.
Properties
item
readonlyitem:ItemStack
Defined in: item-behaviors/src/world.ts:208
kind
readonlykind:"give-item"
Defined in: item-behaviors/src/world.ts:206
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:207
GrantExperienceAction
Defined in: item-behaviors/src/world.ts:175
Give experience, which is the experience bottle.
Properties
amount
readonlyamount:number
Defined in: item-behaviors/src/world.ts:178
kind
readonlykind:"grant-experience"
Defined in: item-behaviors/src/world.ts:176
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:177
IgniteAction
Defined in: item-behaviors/src/world.ts:253
Set something on fire, which is flint and steel, a fire charge and Flame.
Properties
face
readonlyface:BlockFace
Defined in: item-behaviors/src/world.ts:256
kind
readonlykind:"ignite"
Defined in: item-behaviors/src/world.ts:254
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:255
ItemBehaviorEnvironment
Defined in: item-behaviors/src/items.ts:28
The world and the item factory together, which is what a behavior needs.
Extended by
Properties
items
readonlyitems:ItemFactory
Defined in: item-behaviors/src/items.ts:32
The factory they build result stacks with.
world
readonlyworld:WorldActions
Defined in: item-behaviors/src/items.ts:30
The world the behaviors act on.
ItemBehaviorSpec
Defined in: item-behaviors/src/behavior.ts:44
What itemBehavior takes.
Properties
hooks
readonlyhooks: readonlyItemHookName[]
Defined in: item-behaviors/src/behavior.ts:48
Every hook the behavior may implement, which content checks against.
name
readonlyname:string
Defined in: item-behaviors/src/behavior.ts:46
The behavior name, in this project's vanilla: namespace.
Methods
create()
create(
context):Partial<ItemHooks>
Defined in: item-behaviors/src/behavior.ts:56
Builds the handlers for one item type.
Returning an empty object is how a component-driven family declines an item that does not carry its component, which is what lets one behavior attach to the whole registry and bind only where the data asks for it.
Parameters
context
Returns
Partial<ItemHooks>
ItemClassificationReport
Defined in: item-behaviors/src/families.ts:464
The classification of every Java item, as a partition.
Properties
counts
readonlycounts: readonlyobject[]
Defined in: item-behaviors/src/families.ts:470
How many items each family holds, in catalog order and data only last.
members
readonlymembers:ReadonlyMap<ItemClassification, readonlystring[]>
Defined in: item-behaviors/src/families.ts:468
The identifiers in each family, in identifier order, keyed by family name.
total
readonlytotal:number
Defined in: item-behaviors/src/families.ts:466
How many items were classified, which is the Java item registry's size.
ItemFactory
Defined in: item-behaviors/src/items.ts:16
Makes an item stack from a Bedrock identifier.
Extended by
Methods
create()
create(
identifier,count?):ItemStack|undefined
Defined in: item-behaviors/src/items.ts:24
One stack of an item.
Parameters
identifier
string
count?
number
Returns
ItemStack | undefined
The stack, or undefined when no item type is registered under the identifier, which a behavior treats as "do nothing" rather than as an error.
ItemFamilyDefinition
Defined in: item-behaviors/src/families.ts:45
One behavior family: what it is, how it is recognized, and what runs for it.
Properties
behaviors
readonlybehaviors: readonlystring[]
Defined in: item-behaviors/src/families.ts:53
The behaviors registerVanillaItemBehaviors attaches for it, by name.
entryPoints?
readonlyoptionalentryPoints?: readonlystring[]
Defined in: item-behaviors/src/families.ts:63
The functions the server calls directly for this family, by name.
Not every behavior is an item interaction. A mining speed is a number the engine asks for while a block breaks, a totem fires on the damage path, and a gliding elytra wears out on a tick. None of the seven hooks covers those, so they are exported functions and listed here rather than registered as a behavior with no handlers.
name
readonlyname:string
Defined in: item-behaviors/src/families.ts:47
The family name, which is also its row in the README table.
rule
readonlyrule:FamilyRule
Defined in: item-behaviors/src/families.ts:51
Whether an item belongs to this family, tried in catalog order.
summary
readonlysummary:string
Defined in: item-behaviors/src/families.ts:49
One line on what the family does.
ItemSource
Defined in: items/src/hooks.ts:24
The entity a hook acts for, usually the player holding the item.
The item runtime never reads past these two fields. A behavior that needs more narrows the value itself, which is the seam: widening this interface is a change to every behavior, narrowing inside one behavior is not.
Properties
identifier
readonlyidentifier:string
Defined in: items/src/hooks.ts:26
The Bedrock entity identifier, such as minecraft:player.
position?
readonlyoptionalposition?:BlockPosition
Defined in: items/src/hooks.ts:30
The entity's exact position in world coordinates, when the caller has it.
runtimeId
readonlyruntimeId:number
Defined in: items/src/hooks.ts:28
The entity's runtime id, unique for the length of the session.
LaunchProjectileAction
Defined in: item-behaviors/src/world.ts:115
Throw or shoot something, which covers arrows, snowballs, potions and tridents.
Properties
data?
readonlyoptionaldata?:Readonly<Record<string,unknown>>
Defined in: item-behaviors/src/world.ts:124
The projectile's own data, such as a tipped arrow's potion contents.
identifier
readonlyidentifier:string
Defined in: item-behaviors/src/world.ts:117
inaccuracy
readonlyinaccuracy:number
Defined in: item-behaviors/src/world.ts:122
Spread in degrees; zero is dead on the view ray.
kind
readonlykind:"launch-projectile"
Defined in: item-behaviors/src/world.ts:116
power
readonlypower:number
Defined in: item-behaviors/src/world.ts:120
Launch speed in blocks per tick, as Java's shootFromRotation takes it.
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:118
MapAction
Defined in: item-behaviors/src/world.ts:284
Create, clone, extend or lock a map.
Properties
item
readonlyitem:ItemStack
Defined in: item-behaviors/src/world.ts:288
kind
readonlykind:"map"
Defined in: item-behaviors/src/world.ts:285
operation
readonlyoperation:MapOperation
Defined in: item-behaviors/src/world.ts:286
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:287
MiningContext
Defined in: item-behaviors/src/formulas.ts:65
What miningSpeed needs, which is one line of Player.getDestroySpeed each.
Properties
blockBreakSpeed?
readonlyoptionalblockBreakSpeed?:number
Defined in: item-behaviors/src/formulas.ts:75
Attributes.BLOCK_BREAK_SPEED, 1 unless something modifies it.
digSpeedAmplifier?
readonlyoptionaldigSpeedAmplifier?:number
Defined in: item-behaviors/src/formulas.ts:71
The Haste or Conduit Power amplifier, absent when neither is active.
eyeInWater?
readonlyoptionaleyeInWater?:boolean
Defined in: item-behaviors/src/formulas.ts:79
Whether the source's eyes are in water.
miningEfficiency?
readonlyoptionalminingEfficiency?:number
Defined in: item-behaviors/src/formulas.ts:69
Attributes.MINING_EFFICIENCY, which Efficiency raises by level * level + 1.
miningFatigueAmplifier?
readonlyoptionalminingFatigueAmplifier?:number
Defined in: item-behaviors/src/formulas.ts:73
The Mining Fatigue amplifier, absent when it is not active.
onGround?
readonlyoptionalonGround?:boolean
Defined in: item-behaviors/src/formulas.ts:81
Whether the source is standing on something.
submergedMiningSpeed?
readonlyoptionalsubmergedMiningSpeed?:number
Defined in: item-behaviors/src/formulas.ts:77
Attributes.SUBMERGED_MINING_SPEED, 0.2 unless Aqua Affinity raises it.
toolSpeed
readonlytoolSpeed:number
Defined in: item-behaviors/src/formulas.ts:67
ItemStack.getDestroySpeed: the tool's speed for this block, 1 with no tool.
NameEntityAction
Defined in: item-behaviors/src/world.ts:220
Name an entity, which is the name tag.
Properties
kind
readonlykind:"name-entity"
Defined in: item-behaviors/src/world.ts:221
name
readonlyname:string
Defined in: item-behaviors/src/world.ts:223
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:222
OpenScreenAction
Defined in: item-behaviors/src/world.ts:308
Open a screen for the source, which is the book editor and the lectern.
Properties
item
readonlyitem:ItemStack
Defined in: item-behaviors/src/world.ts:312
kind
readonlykind:"open-screen"
Defined in: item-behaviors/src/world.ts:309
screen
readonlyscreen:string
Defined in: item-behaviors/src/world.ts:311
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:310
PlaceBlockAction
Defined in: item-behaviors/src/world.ts:91
Put a block in the world, which is what a bucket, a fire starter and a tilled hoe all do.
Properties
kind
readonlykind:"place-block"
Defined in: item-behaviors/src/world.ts:92
placement
readonlyplacement:BlockPlacement
Defined in: item-behaviors/src/world.ts:94
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:93
PlaySoundAction
Defined in: item-behaviors/src/world.ts:128
Play a sound at a position.
Properties
kind
readonlykind:"play-sound"
Defined in: item-behaviors/src/world.ts:129
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:131
sound
readonlysound:string
Defined in: item-behaviors/src/world.ts:130
PlaySoundConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:47
minecraft:play_sound: a sound at the consumer.
Properties
kind
readonlykind:"play-sound"
Defined in: item-behaviors/src/consumeEffects.ts:48
sound
readonlysound:string
Defined in: item-behaviors/src/consumeEffects.ts:49
RemoveEffectsAction
Defined in: item-behaviors/src/world.ts:142
Take status effects off an entity.
Properties
effects?
readonlyoptionaleffects?:HolderSet
Defined in: item-behaviors/src/world.ts:146
Which effects to remove, or absent for every one of them, which is milk.
kind
readonlykind:"remove-effects"
Defined in: item-behaviors/src/world.ts:143
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:144
RemoveEffectsConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:29
minecraft:remove_effects: take the named effects off.
Properties
effects
readonlyeffects:HolderSet
Defined in: item-behaviors/src/consumeEffects.ts:31
kind
readonlykind:"remove-effects"
Defined in: item-behaviors/src/consumeEffects.ts:30
ShearEntityAction
Defined in: item-behaviors/src/world.ts:241
Shear an entity, which is what shears do to a sheep or a snow golem.
Properties
kind
readonlykind:"shear-entity"
Defined in: item-behaviors/src/world.ts:242
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:243
SignalAction
Defined in: item-behaviors/src/world.ts:298
Throw a signal that flies toward a position, which is the eye of ender.
The behavior has already asked WorldActions.locate where to send it: a signal with nowhere to go is never thrown, because Java throws nothing when no stronghold is in range.
Properties
item
readonlyitem:ItemStack
Defined in: item-behaviors/src/world.ts:302
What the signal drops when it survives its flight, which is the stack it was thrown as.
kind
readonlykind:"signal"
Defined in: item-behaviors/src/world.ts:299
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:300
target
readonlytarget:BlockPosition
Defined in: item-behaviors/src/world.ts:304
Where it flies toward, which is the located structure's generation point.
SourceState
Defined in: item-behaviors/src/world.ts:50
What a behavior needs to know about the entity using the item.
One query rather than eight accessors, because every field is cheap for a server that already has the entity and a behavior usually reads two of them.
Properties
cooldownGroups
readonlycooldownGroups: readonlystring[]
Defined in: item-behaviors/src/world.ts:68
The cooldown groups the source is currently waiting out.
creative
readonlycreative:boolean
Defined in: item-behaviors/src/world.ts:54
Whether the source may use items without consuming them.
effects
readonlyeffects: readonlyActiveEffect[]
Defined in: item-behaviors/src/world.ts:66
The status effects currently on the source.
eyeInWater
readonlyeyeInWater:boolean
Defined in: item-behaviors/src/world.ts:58
Whether the source's eyes are in water, which scales mining speed.
fallDistance
readonlyfallDistance:number
Defined in: item-behaviors/src/world.ts:64
How far the source has fallen, in blocks, which the mace scales its hit by.
foodLevel
readonlyfoodLevel:number
Defined in: item-behaviors/src/world.ts:70
How full the source's hunger bar is, 0 to 20, which decides whether food is edible.
gliding
readonlygliding:boolean
Defined in: item-behaviors/src/world.ts:60
Whether the source is gliding, which is what a firework rocket boosts.
inWaterOrRain
readonlyinWaterOrRain:boolean
Defined in: item-behaviors/src/world.ts:62
Whether the source is in water or rain, which is what Riptide needs.
onGround
readonlyonGround:boolean
Defined in: item-behaviors/src/world.ts:56
Whether the source is standing on something, which divides mining speed by five.
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:52
Where the source is.
SpawnEntityAction
Defined in: item-behaviors/src/world.ts:104
Spawn an entity, from a spawn egg, a mob bucket, a boat or a firework rocket.
Properties
attachedTo?
readonlyoptionalattachedTo?:ItemSource
Defined in: item-behaviors/src/world.ts:111
The entity the spawned one rides or is attached to, for a rocket boosting a glider.
data?
readonlyoptionaldata?:Readonly<Record<string,unknown>>
Defined in: item-behaviors/src/world.ts:109
The entity's own stored data, such as a bucketed fish's variant.
identifier
readonlyidentifier:string
Defined in: item-behaviors/src/world.ts:106
kind
readonlykind:"spawn-entity"
Defined in: item-behaviors/src/world.ts:105
position
readonlyposition:BlockPosition
Defined in: item-behaviors/src/world.ts:107
StartCooldownAction
Defined in: item-behaviors/src/world.ts:182
Start an item cooldown, keyed by the group minecraft:use_cooldown names.
Properties
group
readonlygroup:string
Defined in: item-behaviors/src/world.ts:185
kind
readonlykind:"start-cooldown"
Defined in: item-behaviors/src/world.ts:183
source
readonlysource:ItemSource
Defined in: item-behaviors/src/world.ts:184
ticks
readonlyticks:number
Defined in: item-behaviors/src/world.ts:186
TeleportConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:40
minecraft:teleport_randomly: the chorus fruit's hop.
Properties
diameter
readonlydiameter:number
Defined in: item-behaviors/src/consumeEffects.ts:43
The search box's width in blocks; Java defaults it to 16.
kind
readonlykind:"teleport-randomly"
Defined in: item-behaviors/src/consumeEffects.ts:41
TeleportRandomlyAction
Defined in: item-behaviors/src/world.ts:168
Move an entity to a random nearby position, which is the chorus fruit.
Properties
kind
readonlykind:"teleport-randomly"
Defined in: item-behaviors/src/world.ts:169
radius
readonlyradius:number
Defined in: item-behaviors/src/world.ts:171
target
readonlytarget:ItemSource
Defined in: item-behaviors/src/world.ts:170
TestWorld
Defined in: item-behaviors/src/testing.ts:59
The double, which is a WorldActions plus the log and a few setters.
Extends
Properties
actions
readonlyactions: readonlyItemWorldAction[]
Defined in: item-behaviors/src/testing.ts:61
Every action performed, in order.
Methods
blockAt()
blockAt(
position):BlockReference|undefined
Defined in: item-behaviors/src/world.ts:369
The block at a position, or undefined when the position is unloaded.
Parameters
position
Returns
BlockReference | undefined
Inherited from
canDyeEntity()?
optionalcanDyeEntity(target,color):boolean
Defined in: item-behaviors/src/world.ts:423
Whether a target entity accepts this dye, when the host can answer.
Parameters
target
color
string
Returns
boolean
Inherited from
canNameEntity()?
optionalcanNameEntity(target):boolean
Defined in: item-behaviors/src/world.ts:421
Whether a target entity accepts a name tag, when the host can answer.
Parameters
target
Returns
boolean
Inherited from
clear()
clear():
void
Defined in: item-behaviors/src/testing.ts:73
Empties the action log.
Returns
void
did()
did(
kind):boolean
Defined in: item-behaviors/src/testing.ts:65
Whether an action of the kind was performed.
Parameters
kind
"map" | "place-block" | "break-block" | "spawn-entity" | "launch-projectile" | "play-sound" | "apply-effects" | "remove-effects" | "damage-entity" | "feed" | "teleport-randomly" | "grant-experience" | "start-cooldown" | "consume-durability" | "give-item" | "equip" | "name-entity" | "attach-lead" | "dye-entity" | "shear-entity" | "fertilize" | "ignite" | "brush" | "blocking" | "disable-shield" | "signal" | "open-screen" | "fishing"
Returns
boolean
effectsOf()
effectsOf(
potion): readonlyEffectApplication[]
Defined in: item-behaviors/src/world.ts:417
The effects one potion identifier applies.
Java keeps its potion table in code rather than data, in Potions, so the 47 entries cannot come from this package. The server, which already builds a potion registry for the client, answers instead.
Parameters
potion
string
Returns
readonly EffectApplication[]
The effects, or an empty list for a water bottle and for a potion the server does not know.
Inherited from
environment()
environment():
EnvironmentState
Defined in: item-behaviors/src/world.ts:382
Everything a behavior reads about the world around it.
Returns
Inherited from
hardnessOf()
hardnessOf(
block):number
Defined in: item-behaviors/src/world.ts:378
A block's hardness, which is Java's destroySpeed.
The number comes from the per-state property table rather than from anything a pack publishes, so the world owns it. -1 means unbreakable, and 0 means the block breaks instantly, which is why it costs a tool no durability.
Parameters
block
Returns
number
Inherited from
includes()
includes(
set,member):boolean
Defined in: item-behaviors/src/world.ts:396
Whether an identifier is in a holder set, which resolves the #tag, single and list forms the same way for blocks, items and entities.
Parameters
set
member
string
Returns
boolean
Inherited from
locate()?
optionallocate(destination,origin):BlockPosition|undefined
Defined in: item-behaviors/src/world.ts:437
The nearest structure in a structure tag, when the host has a structure search.
Java's ServerLevel.findNearestMapStructure, which the eye of ender calls with #minecraft:eye_of_ender_located and a hundred chunks. The host decides the radius, because it belongs to the search and not to the item.
Parameters
destination
string
The structure tag in Java's form, such as #minecraft:eye_of_ender_located.
origin
Where to search from, which is where the source stands.
Returns
BlockPosition | undefined
The structure's generation point, or undefined when none is in range.
Inherited from
perform()
perform(
action):void
Defined in: item-behaviors/src/world.ts:459
Does one thing to the world.
Parameters
action
Returns
void
Inherited from
performed()
performed<
K>(kind): readonlyItemWorldActionOf<K>[]
Defined in: item-behaviors/src/testing.ts:63
The actions of one kind, already narrowed to that variant.
Type Parameters
K
K extends "map" | "place-block" | "break-block" | "spawn-entity" | "launch-projectile" | "play-sound" | "apply-effects" | "remove-effects" | "damage-entity" | "feed" | "teleport-randomly" | "grant-experience" | "start-cooldown" | "consume-durability" | "give-item" | "equip" | "name-entity" | "attach-lead" | "dye-entity" | "shear-entity" | "fertilize" | "ignite" | "brush" | "blocking" | "disable-shield" | "signal" | "open-screen" | "fishing"
Parameters
kind
K
Returns
readonly ItemWorldActionOf<K>[]
placeEndCrystal()?
optionalplaceEndCrystal(base):boolean
Defined in: item-behaviors/src/world.ts:447
Places an end crystal when the clicked block and the three-block spawn box are clear.
The host owns the block and entity indexes needed to check Java's placement rules. It also starts the dragon respawn sequence when this completes a set of four crystals.
Parameters
base
The block the crystal is placed on.
Returns
boolean
Whether the host placed the crystal. A false answer leaves the item stack alone.
Inherited from
random()
random():
number
Defined in: item-behaviors/src/world.ts:419
A number in [0, 1), which is every random roll a behavior makes.
Returns
number
Inherited from
setBlock()
setBlock(
block):void
Defined in: item-behaviors/src/testing.ts:69
Puts a block in the world mid-test.
Parameters
block
Returns
void
setState()
setState(
state):void
Defined in: item-behaviors/src/testing.ts:67
Changes the source state mid-test, for a second hook call.
Parameters
state
Partial<SourceState>
Returns
void
setTarget()
setTarget(
target):void
Defined in: item-behaviors/src/testing.ts:71
Sets the entity targetOf answers with.
Parameters
target
ItemSource | undefined
Returns
void
stateOf()
stateOf(
source):SourceState
Defined in: item-behaviors/src/world.ts:380
Everything a behavior reads about the entity using the item.
Parameters
source
Returns
Inherited from
supports()?
optionalsupports(action):boolean
Defined in: item-behaviors/src/world.ts:457
Whether the host performs an action of this kind, when it can say.
perform returns nothing, so a host that has not written the system behind a variant can only log and ignore it. A behavior that spends its item on one action asks this first and keeps the item when the answer is no, which is the rule canPerform in behavior.ts applies. A host that does not answer is taken to perform everything.
Parameters
action
"map" | "place-block" | "break-block" | "spawn-entity" | "launch-projectile" | "play-sound" | "apply-effects" | "remove-effects" | "damage-entity" | "feed" | "teleport-randomly" | "grant-experience" | "start-cooldown" | "consume-durability" | "give-item" | "equip" | "name-entity" | "attach-lead" | "dye-entity" | "shear-entity" | "fertilize" | "ignite" | "brush" | "blocking" | "disable-shield" | "signal" | "open-screen" | "fishing"
Returns
boolean
Inherited from
targetOf()
targetOf(
source):ItemSource|undefined
Defined in: item-behaviors/src/world.ts:391
The entity an interaction landed on, or undefined when it landed on a block or on nothing.
The item hooks carry no entity-interaction hook, because Mojang's ItemCustomComponent has none, so a behavior that acts on an entity asks the world for the target instead.
Parameters
source
Returns
ItemSource | undefined
Inherited from
transform()
transform(
transformer,block,face):BlockPlacement|undefined
Defined in: item-behaviors/src/world.ts:406
What a minecraft:block_transformer turns a block into: the axe's stripping, the shovel's path and the hoe's tilling, all one data table.
Parameters
transformer
string
block
face
The clicked face, which an entry's disallowed_faces may refuse: a hoe swung at the underside of dirt tills nothing.
Returns
BlockPlacement | undefined
The replacement, or undefined when the transformer has no rule for the block.
Inherited from
TestWorldOptions
Defined in: item-behaviors/src/testing.ts:31
Everything createTestWorld lets a test set up front.
Properties
blocks?
readonlyoptionalblocks?: readonlyBlockReference[]
Defined in: item-behaviors/src/testing.ts:33
The blocks that exist, keyed by position.
environment?
readonlyoptionalenvironment?:Partial<EnvironmentState>
Defined in: item-behaviors/src/testing.ts:39
Fields to override on the default environment.
hardness?
readonlyoptionalhardness?:Readonly<Record<string,number>>
Defined in: item-behaviors/src/testing.ts:35
Block hardness, keyed by block identifier; anything absent is 1.5.
placeEndCrystal?
readonlyoptionalplaceEndCrystal?: (base) =>boolean
Defined in: item-behaviors/src/testing.ts:53
Whether the host accepts an end crystal on one base block.
Parameters
base
Returns
boolean
potions?
readonlyoptionalpotions?:Readonly<Record<string, readonlyEffectApplication[]>>
Defined in: item-behaviors/src/testing.ts:49
What effectsOf answers, keyed by potion identifier.
randoms?
readonlyoptionalrandoms?: readonlynumber[]
Defined in: item-behaviors/src/testing.ts:47
The numbers random hands out in order, repeating the last one.
state?
readonlyoptionalstate?:Partial<SourceState>
Defined in: item-behaviors/src/testing.ts:37
Fields to override on the default source state.
structures?
readonlyoptionalstructures?:Readonly<Record<string,BlockPosition>>
Defined in: item-behaviors/src/testing.ts:51
What locate answers, keyed by structure tag; a tag absent here has nothing in range.
tags?
readonlyoptionaltags?:Readonly<Record<string, readonlystring[]>>
Defined in: item-behaviors/src/testing.ts:43
Tag membership, keyed by tag name without the leading #.
target?
readonlyoptionaltarget?:ItemSource
Defined in: item-behaviors/src/testing.ts:41
The entity a use lands on, which makes targetOf answer.
transforms?
readonlyoptionaltransforms?:Readonly<Record<string,BlockPlacement>>
Defined in: item-behaviors/src/testing.ts:45
What transform answers, keyed by <transformer>|<block identifier>.
unsupported?
readonlyoptionalunsupported?: readonly ("map"|"place-block"|"break-block"|"spawn-entity"|"launch-projectile"|"play-sound"|"apply-effects"|"remove-effects"|"damage-entity"|"feed"|"teleport-randomly"|"grant-experience"|"start-cooldown"|"consume-durability"|"give-item"|"equip"|"name-entity"|"attach-lead"|"dye-entity"|"shear-entity"|"fertilize"|"ignite"|"brush"|"blocking"|"disable-shield"|"signal"|"open-screen"|"fishing")[]
Defined in: item-behaviors/src/testing.ts:55
The action kinds supports says no to; everything else is performed.
WorldActions
Defined in: item-behaviors/src/world.ts:367
What an item behavior may ask of the world and do to it.
The server implements this once. The queries are expected to be cheap and synchronous: a behavior calls them while deciding, and the engine already holds every answer by the time it dispatches a hook.
Extended by
Methods
blockAt()
blockAt(
position):BlockReference|undefined
Defined in: item-behaviors/src/world.ts:369
The block at a position, or undefined when the position is unloaded.
Parameters
position
Returns
BlockReference | undefined
canDyeEntity()?
optionalcanDyeEntity(target,color):boolean
Defined in: item-behaviors/src/world.ts:423
Whether a target entity accepts this dye, when the host can answer.
Parameters
target
color
string
Returns
boolean
canNameEntity()?
optionalcanNameEntity(target):boolean
Defined in: item-behaviors/src/world.ts:421
Whether a target entity accepts a name tag, when the host can answer.
Parameters
target
Returns
boolean
effectsOf()
effectsOf(
potion): readonlyEffectApplication[]
Defined in: item-behaviors/src/world.ts:417
The effects one potion identifier applies.
Java keeps its potion table in code rather than data, in Potions, so the 47 entries cannot come from this package. The server, which already builds a potion registry for the client, answers instead.
Parameters
potion
string
Returns
readonly EffectApplication[]
The effects, or an empty list for a water bottle and for a potion the server does not know.
environment()
environment():
EnvironmentState
Defined in: item-behaviors/src/world.ts:382
Everything a behavior reads about the world around it.
Returns
hardnessOf()
hardnessOf(
block):number
Defined in: item-behaviors/src/world.ts:378
A block's hardness, which is Java's destroySpeed.
The number comes from the per-state property table rather than from anything a pack publishes, so the world owns it. -1 means unbreakable, and 0 means the block breaks instantly, which is why it costs a tool no durability.
Parameters
block
Returns
number
includes()
includes(
set,member):boolean
Defined in: item-behaviors/src/world.ts:396
Whether an identifier is in a holder set, which resolves the #tag, single and list forms the same way for blocks, items and entities.
Parameters
set
member
string
Returns
boolean
locate()?
optionallocate(destination,origin):BlockPosition|undefined
Defined in: item-behaviors/src/world.ts:437
The nearest structure in a structure tag, when the host has a structure search.
Java's ServerLevel.findNearestMapStructure, which the eye of ender calls with #minecraft:eye_of_ender_located and a hundred chunks. The host decides the radius, because it belongs to the search and not to the item.
Parameters
destination
string
The structure tag in Java's form, such as #minecraft:eye_of_ender_located.
origin
Where to search from, which is where the source stands.
Returns
BlockPosition | undefined
The structure's generation point, or undefined when none is in range.
perform()
perform(
action):void
Defined in: item-behaviors/src/world.ts:459
Does one thing to the world.
Parameters
action
Returns
void
placeEndCrystal()?
optionalplaceEndCrystal(base):boolean
Defined in: item-behaviors/src/world.ts:447
Places an end crystal when the clicked block and the three-block spawn box are clear.
The host owns the block and entity indexes needed to check Java's placement rules. It also starts the dragon respawn sequence when this completes a set of four crystals.
Parameters
base
The block the crystal is placed on.
Returns
boolean
Whether the host placed the crystal. A false answer leaves the item stack alone.
random()
random():
number
Defined in: item-behaviors/src/world.ts:419
A number in [0, 1), which is every random roll a behavior makes.
Returns
number
stateOf()
stateOf(
source):SourceState
Defined in: item-behaviors/src/world.ts:380
Everything a behavior reads about the entity using the item.
Parameters
source
Returns
supports()?
optionalsupports(action):boolean
Defined in: item-behaviors/src/world.ts:457
Whether the host performs an action of this kind, when it can say.
perform returns nothing, so a host that has not written the system behind a variant can only log and ignore it. A behavior that spends its item on one action asks this first and keeps the item when the answer is no, which is the rule canPerform in behavior.ts applies. A host that does not answer is taken to perform everything.
Parameters
action
"map" | "place-block" | "break-block" | "spawn-entity" | "launch-projectile" | "play-sound" | "apply-effects" | "remove-effects" | "damage-entity" | "feed" | "teleport-randomly" | "grant-experience" | "start-cooldown" | "consume-durability" | "give-item" | "equip" | "name-entity" | "attach-lead" | "dye-entity" | "shear-entity" | "fertilize" | "ignite" | "brush" | "blocking" | "disable-shield" | "signal" | "open-screen" | "fishing"
Returns
boolean
targetOf()
targetOf(
source):ItemSource|undefined
Defined in: item-behaviors/src/world.ts:391
The entity an interaction landed on, or undefined when it landed on a block or on nothing.
The item hooks carry no entity-interaction hook, because Mojang's ItemCustomComponent has none, so a behavior that acts on an entity asks the world for the target instead.
Parameters
source
Returns
ItemSource | undefined
transform()
transform(
transformer,block,face):BlockPlacement|undefined
Defined in: item-behaviors/src/world.ts:406
What a minecraft:block_transformer turns a block into: the axe's stripping, the shovel's path and the hoe's tilling, all one data table.
Parameters
transformer
string
block
face
The clicked face, which an entry's disallowed_faces may refuse: a hoe swung at the underside of dirt tills nothing.
Returns
BlockPlacement | undefined
The replacement, or undefined when the transformer has no rule for the block.
Type Aliases
BlockFace
BlockFace =
"down"|"up"|"north"|"south"|"west"|"east"
Defined in: items/src/hooks.ts:44
The face of a block an interaction landed on.
ConsumeEffect
ConsumeEffect =
ApplyEffectsConsumeEffect|ClearEffectsConsumeEffect|PlaySoundConsumeEffect|RemoveEffectsConsumeEffect|TeleportConsumeEffect
Defined in: item-behaviors/src/consumeEffects.ts:53
One consume effect, parsed.
EquipmentSlot
EquipmentSlot =
"any"|"hand"|"mainhand"|"offhand"|"armor"|"head"|"chest"|"legs"|"feet"|"body"|"saddle"
Defined in: item-behaviors/src/world.ts:87
Where an equipped item goes, named the way minecraft:equippable names it.
FamilyRule
FamilyRule = (
item) =>boolean
Defined in: item-behaviors/src/families.ts:42
How a family claims an item.
Parameters
item
Returns
boolean
HolderSet
HolderSet = {
kind:"tag";tag:string; } | {entries: readonlystring[];kind:"entries"; }
Defined in: items/src/schema.ts:191
A set of registry entries the way Java 26.3 writes one: a #tag reference, a single identifier, or a list of identifiers.
ItemBehavior
Defined in: item-behaviors/src/behavior.ts:27
A behavior for the item hook table.
ItemClassification
ItemClassification =
ItemFamilyName| typeofDATA_ONLY
Defined in: item-behaviors/src/families.ts:435
What classifyItem returns: a family name, or DATA_ONLY.
ItemFamilyName
ItemFamilyName = typeof
ITEM_FAMILIES[number]["name"]
Defined in: item-behaviors/src/families.ts:432
Every family name, which is the union the classifier returns.
ItemHookName
ItemHookName = keyof
ItemHooks&string
Defined in: item-behaviors/src/behavior.ts:30
One hook name.
ItemWorldAction
ItemWorldAction =
ApplyEffectsAction|AttachLeadAction|BlockingAction|BreakBlockAction|BrushAction|ConsumeDurabilityAction|DamageEntityAction|DisableShieldAction|DyeEntityAction|EquipAction|FeedAction|FertilizeAction|FishingAction|GiveItemAction|GrantExperienceAction|IgniteAction|LaunchProjectileAction|MapAction|NameEntityAction|OpenScreenAction|PlaceBlockAction|PlaySoundAction|RemoveEffectsAction|ShearEntityAction|SignalAction|SpawnEntityAction|StartCooldownAction|TeleportRandomlyAction
Defined in: item-behaviors/src/world.ts:324
Everything a vanilla item behavior does to the world, as one tagged union.
ItemWorldActionKind
ItemWorldActionKind =
ItemWorldAction["kind"]
Defined in: item-behaviors/src/world.ts:355
Every kind ItemWorldAction can carry.
ItemWorldActionOf
ItemWorldActionOf<
K> =Extract<ItemWorldAction, {kind:K; }>
Defined in: item-behaviors/src/world.ts:358
Narrows ItemWorldAction to the one variant with a given kind.
Type Parameters
K
K extends ItemWorldActionKind
MapOperation
MapOperation =
"create"|"clone"|"extend"|"lock"
Defined in: item-behaviors/src/world.ts:84
Which map operation a MapAction asks for.
ToolParameters
ToolParameters =
NonNullable<ReturnType<typeoftoolOf>>
Defined in: item-behaviors/src/formulas.ts:180
The minecraft:tool parameters as the item package parses them.
Variables
BAD_OMEN_EFFECT
constBAD_OMEN_EFFECT:"minecraft:bad_omen"='minecraft:bad_omen'
Defined in: item-behaviors/src/behaviors/consume.ts:39
The effect an ominous bottle applies.
BAD_OMEN_TICKS
constBAD_OMEN_TICKS:120000=120_000
Defined in: item-behaviors/src/behaviors/consume.ts:36
How long Bad Omen lasts, which is OminousBottleItem's 100 minutes.
BOOK_BEHAVIORS
constBOOK_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/books.ts:128
Every behavior this file declares.
BOOK_EDIT_SCREEN
constBOOK_EDIT_SCREEN:"minecraft:book_edit"='minecraft:book_edit'
Defined in: item-behaviors/src/behaviors/books.ts:18
The screen a writable book opens.
BOOK_READ_SCREEN
constBOOK_READ_SCREEN:"minecraft:book_read"='minecraft:book_read'
Defined in: item-behaviors/src/behaviors/books.ts:21
The screen a written book opens.
BOW_LAUNCH_SCALE
constBOW_LAUNCH_SCALE:3=3
Defined in: item-behaviors/src/behaviors/projectiles.ts:67
BowItem.releaseUsing multiplies the power by three to get the launch speed.
BOW_MINIMUM_POWER
constBOW_MINIMUM_POWER:0.1=0.1
Defined in: item-behaviors/src/behaviors/projectiles.ts:64
The smallest draw that shoots anything, from BowItem.releaseUsing.
BUCKET_CONTENTS
constBUCKET_CONTENTS:Readonly<Record<string, {block:string;sound:string; }>>
Defined in: item-behaviors/src/behaviors/fluids.ts:33
What a filled bucket puts down, and the sound it makes.
Keyed by Bedrock identifier, which registry.test.ts checks against the item table.
BUCKET_PICKUPS
constBUCKET_PICKUPS:Readonly<Record<string, {item:string;sound:string; }>>
Defined in: item-behaviors/src/behaviors/fluids.ts:16
What an empty bucket picks each block up as, and the sound it makes.
BUNDLE_SCREEN
constBUNDLE_SCREEN:"minecraft:bundle"='minecraft:bundle'
Defined in: item-behaviors/src/behaviors/books.ts:24
The screen a bundle opens, which Bedrock draws as the bundle interaction.
COMBAT_BEHAVIORS
constCOMBAT_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/combat.ts:259
Every behavior this file declares.
COMPONENT_DRIVEN_BEHAVIORS
constCOMPONENT_DRIVEN_BEHAVIORS:ReadonlySet<string>
Defined in: item-behaviors/src/registry.ts:69
The behaviors that recognize their own work from the item's components.
Each attaches to every identifier and returns no handlers where the component is missing, which is what makes them work for content this package has never heard of.
CONDUIT_POWER_EFFECT
constCONDUIT_POWER_EFFECT:"minecraft:conduit_power"='minecraft:conduit_power'
Defined in: item-behaviors/src/formulas.ts:32
Conduit Power stands in for Haste underwater and uses the same term.
CONSUME_BEHAVIORS
constCONSUME_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/consume.ts:213
Every behavior this file declares, in the order they have to be attached in.
CROSSBOW_CHARGE_TICKS
constCROSSBOW_CHARGE_TICKS:25=25
Defined in: item-behaviors/src/behaviors/projectiles.ts:146
How long a crossbow takes to charge, before Quick Charge, in ticks.
DATA_ONLY
constDATA_ONLY:"data only"
Defined in: item-behaviors/src/families.ts:67
The name the classifier gives an item no family claims.
DEFAULT_ATTACK_SPEED
constDEFAULT_ATTACK_SPEED:4=4
Defined in: item-behaviors/src/formulas.ts:43
Attributes.ATTACK_SPEED's default, which is the bare hand's four swings a second.
DEFAULT_BLOCK_BREAK_SPEED
constDEFAULT_BLOCK_BREAK_SPEED:1=1
Defined in: item-behaviors/src/formulas.ts:37
Attributes.BLOCK_BREAK_SPEED's default.
DEFAULT_MINING_EFFICIENCY
constDEFAULT_MINING_EFFICIENCY:0=0
Defined in: item-behaviors/src/formulas.ts:35
Attributes.MINING_EFFICIENCY's default, which is zero without Efficiency.
DEFAULT_SUBMERGED_MINING_SPEED
constDEFAULT_SUBMERGED_MINING_SPEED:0.2=0.2
Defined in: item-behaviors/src/formulas.ts:39
Attributes.SUBMERGED_MINING_SPEED's default, which Aqua Affinity multiplies up to 1.
DEFAULT_TELEPORT_DIAMETER
constDEFAULT_TELEPORT_DIAMETER:16=16
Defined in: item-behaviors/src/consumeEffects.ts:61
Java's default diameter for minecraft:teleport_randomly.
ELYTRA_DURABILITY_INTERVAL
constELYTRA_DURABILITY_INTERVAL:20=20
Defined in: item-behaviors/src/behaviors/wearable.ts:96
How often a worn elytra costs a point of durability while gliding, in ticks.
FACE_OFFSETS
constFACE_OFFSETS:Readonly<Record<BlockFace, readonly [number,number,number]>>
Defined in: item-behaviors/src/behaviors/placement.ts:19
The face offsets a placement uses, which is the one direction table this package needs.
FLUID_BEHAVIORS
constFLUID_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/fluids.ts:204
Every behavior this file declares.
GOAT_HORN_COOLDOWN_TICKS
constGOAT_HORN_COOLDOWN_TICKS:140=140
Defined in: item-behaviors/src/behaviors/books.ts:15
How long a goat horn's cooldown runs, from InstrumentItem, in ticks.
HASTE_EFFECT
constHASTE_EFFECT:"minecraft:haste"='minecraft:haste'
Defined in: item-behaviors/src/formulas.ts:28
The effect identifiers the mining formula reads.
INTERACTION_BEHAVIORS
constINTERACTION_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/interaction.ts:219
Every behavior this file declares.
ITEM_FAMILIES
constITEM_FAMILIES: readonly [{behaviors: readonly ["vanilla:bow"];entryPoints: readonly ["bowPowerForTime"];name:"bow";rule:FamilyRule;summary:"Draw to charge, release to shoot an arrow with power scaled by the draw."; }, {behaviors: readonly ["vanilla:crossbow"];entryPoints: readonly ["crossbowChargeTicks"];name:"crossbow";rule:FamilyRule;summary:"Charge on draw into `minecraft:charged_projectiles`, then fire what it holds."; }, {behaviors: readonly [];name:"ammunition";rule:FamilyRule;summary:"Shot by a bow, a crossbow or a dispenser; no use behavior of its own."; }, {behaviors: readonly ["vanilla:trident","vanilla:melee_weapon"];name:"trident";rule:FamilyRule;summary:"Melee, or a held throw that returns with Loyalty and launches with Riptide."; }, {behaviors: readonly ["vanilla:mace","vanilla:melee_weapon"];entryPoints: readonly ["maceDamageBonus"];name:"mace";rule:FamilyRule;summary:"A melee hit whose damage grows with the fall it lands from."; }, {behaviors: readonly ["vanilla:fishing_rod"];name:"fishing rod";rule:FamilyRule;summary:"Cast a hook, reel it in for the catch or the entity it hit."; }, {behaviors: readonly ["vanilla:steering_rod"];name:"mob steering rod";rule:FamilyRule;summary:"Steer a saddled pig or strider, spending durability per boost."; }, {behaviors: readonly ["vanilla:shears","vanilla:mining_tool"];name:"shears";rule:FamilyRule;summary:"Shear an entity, or mine leaves, wool and cobwebs intact."; }, {behaviors: readonly ["vanilla:fire_starter"];name:"fire starter";rule:FamilyRule;summary:"Set a block alight; flint and steel spends durability, a fire charge spends itself."; }, {behaviors: readonly ["vanilla:bone_meal"];name:"bone meal";rule:FamilyRule;summary:"Fertilize the block it is used on, which the block family resolves."; }, {behaviors: readonly ["vanilla:spyglass"];name:"spyglass";rule:FamilyRule;summary:"Hold to zoom, which the Bedrock client draws and the server only sounds."; }, {behaviors: readonly ["vanilla:compass"];entryPoints: readonly ["compassTargetOf"];name:"compass";rule:FamilyRule;summary:"Point at the world spawn, a bound lodestone, or the last death position."; }, {behaviors: readonly [];entryPoints: readonly ["clockReading"];name:"clock";rule:FamilyRule;summary:"Read the time of day, which the client draws from the item state."; }, {behaviors: readonly ["vanilla:map"];name:"map";rule:FamilyRule;summary:"Create, clone, extend or lock a map, including the sixteen structure maps."; }, {behaviors: readonly ["vanilla:lead"];name:"lead";rule:FamilyRule;summary:"Tie a leashable entity, or knot the lead to a fence."; }, {behaviors: readonly ["vanilla:name_tag"];name:"name tag";rule:FamilyRule;summary:"Name the entity it is used on, and make it persistent."; }, {behaviors: readonly ["vanilla:brush"];name:"brush";rule:FamilyRule;summary:"Brush a suspicious block one step at a time, spending durability per finish."; }, {behaviors: readonly ["vanilla:eye_of_ender"];name:"eye of ender";rule:FamilyRule;summary:"Fly toward the nearest stronghold, or fill an end portal frame."; }, {behaviors: readonly ["vanilla:bucket"];name:"bucket";rule:FamilyRule;summary:"Pick a fluid or powder snow up, or put one down."; }, {behaviors: readonly ["vanilla:throwable"];name:"throwable";rule:FamilyRule;summary:"Throw a projectile entity: snowballs, eggs, pearls, potions, bottles and charges."; }, {behaviors: readonly ["vanilla:fillable"];name:"bottle and bowl";rule:FamilyRule;summary:"Fill from water, a cauldron, a beehive or a mooshroom."; }, {behaviors: readonly ["vanilla:waxing"];name:"waxing";rule:FamilyRule;summary:"Wax copper, or set a sign so its text cannot be edited."; }, {behaviors: readonly ["vanilla:sign_ink"];name:"sign ink";rule:FamilyRule;summary:"Make sign text glow, or take the glow back off."; }, {behaviors: readonly ["vanilla:written_book"];name:"written book";rule:FamilyRule;summary:"Open for reading; the knowledge book grants its recipes and is consumed."; }, {behaviors: readonly ["vanilla:entity_placement"];name:"entity placement";rule:FamilyRule;summary:"Put an entity in the world: boats, rafts, minecarts, cushions, crystals, stands and paintings."; }, {behaviors: readonly ["vanilla:mob_bucket"];name:"mob bucket";rule:FamilyRule;summary:"Pour the water back and release the entity the bucket holds."; }, {behaviors: readonly ["vanilla:shield"];entryPoints: readonly ["shieldDurabilityCost"];name:"shield";rule:FamilyRule;summary:"Raise to block, taking damage into durability until an axe disables it."; }, {behaviors: readonly ["vanilla:equippable"];entryPoints: readonly ["elytraDurabilityTick"];name:"elytra";rule:FamilyRule;summary:"Worn in the chest slot and lets the wearer glide."; }, {behaviors: readonly [];entryPoints: readonly ["applyDeathProtection","deathProtectionOf"];name:"totem";rule:FamilyRule;summary:"Cancels a fatal hit from the hand or the offhand, and is consumed."; }, {behaviors: readonly ["vanilla:spear","vanilla:melee_weapon"];entryPoints: readonly ["kineticDamageOf"];name:"spear";rule:FamilyRule;summary:"A mounted charge whose damage comes from relative velocity, piercing everything in reach."; }, {behaviors: readonly ["vanilla:firework_rocket"];name:"firework rocket";rule:FamilyRule;summary:"Launch a rocket, or boost a glider with one."; }, {behaviors: readonly ["vanilla:goat_horn"];name:"goat horn";rule:FamilyRule;summary:"Play the instrument the item names, then wait out its cooldown."; }, {behaviors: readonly ["vanilla:writable_book"];name:"writable book";rule:FamilyRule;summary:"Open the page editor, and sign into a written book."; }, {behaviors: readonly [];name:"enchanted book";rule:FamilyRule;summary:"Carries enchantments for an anvil without applying them."; }, {behaviors: readonly ["vanilla:banner"];name:"banner";rule:FamilyRule;summary:"Place the banner block, or apply a pattern in a loom."; }, {behaviors: readonly ["vanilla:dye"];name:"dye";rule:FamilyRule;summary:"Color a sheep, a collar, a harness or a sign."; }, {behaviors: readonly ["vanilla:bundle"];name:"bundle";rule:FamilyRule;summary:"A dynamic container weighted by the stacks it holds."; }, {behaviors: readonly ["vanilla:spawn_egg"];name:"spawn egg";rule:FamilyRule;summary:"Spawn the entity the egg names, or set a spawner to it."; }, {behaviors: readonly ["vanilla:potion","vanilla:consumable"];name:"potion";rule:FamilyRule;summary:"Drink for the effects in `minecraft:potion_contents`, leaving the bottle."; }, {behaviors: readonly ["vanilla:suspicious_stew","vanilla:consumable"];name:"suspicious stew";rule:FamilyRule;summary:"Eaten for the effects the stew stored when it was crafted."; }, {behaviors: readonly ["vanilla:ominous_bottle","vanilla:consumable"];name:"ominous bottle";rule:FamilyRule;summary:"Drink for Bad Omen at the amplifier the bottle carries."; }, {behaviors: readonly ["vanilla:block_transformer","vanilla:mining_tool","vanilla:melee_weapon"];name:"block transforming tool";rule:FamilyRule;summary:"Strip, path or till the block it is used on, from the `minecraft:block_transformer` table."; }, {behaviors: readonly ["vanilla:mining_tool","vanilla:melee_weapon"];entryPoints: readonly ["miningSpeed","destroyProgress","breakTicks"];name:"mining tool";rule:FamilyRule;summary:"Mines its `#minecraft:mineable/*` tag at the speed and tier its rules state."; }, {behaviors: readonly ["vanilla:melee_weapon","vanilla:mining_tool"];entryPoints: readonly ["attackDamage","attackStrengthScale"];name:"melee weapon";rule:FamilyRule;summary:"Attacks for its `minecraft:attack_damage` modifier and spends durability per hit."; }, {behaviors: readonly ["vanilla:equippable"];name:"equippable";rule:FamilyRule;summary:"Worn by the user or put on an entity: armor, saddles, harnesses and horse armor."; }, {behaviors: readonly ["vanilla:consumable"];name:"food";rule:FamilyRule;summary:"Eaten for nutrition and saturation, plus whatever `minecraft:consumable` applies."; }, {behaviors: readonly ["vanilla:consumable"];name:"consumable";rule:FamilyRule;summary:"Drunk rather than eaten: milk, which clears every effect."; }]
Defined in: item-behaviors/src/families.ts:111
Every behavior family, in classification order.
The order is "named before derived": a family the data cannot express names its items, and the component rules below it catch everything the data does express. Swapping two rows changes the partition, which is what the counts test in families.test.ts catches.
LODESTONE_TRACKER
constLODESTONE_TRACKER:"minecraft:lodestone_tracker"='minecraft:lodestone_tracker'
Defined in: item-behaviors/src/behaviors/navigation.ts:16
The component a bound lodestone compass carries, which is Java's own key.
MINING_BEHAVIORS
constMINING_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/mining.ts:123
Every behavior this file declares.
MINING_FATIGUE_EFFECT
constMINING_FATIGUE_EFFECT:"minecraft:mining_fatigue"='minecraft:mining_fatigue'
Defined in: item-behaviors/src/formulas.ts:30
The effect that divides mining speed.
NAVIGATION_BEHAVIORS
constNAVIGATION_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/navigation.ts:183
Every behavior this file declares.
PLACEMENT_BEHAVIORS
constPLACEMENT_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/placement.ts:171
Every behavior this file declares.
PLAYER_BASE_ATTACK_DAMAGE
constPLAYER_BASE_ATTACK_DAMAGE:1=1
Defined in: item-behaviors/src/formulas.ts:41
Attributes.ATTACK_DAMAGE's default for a player, before the weapon's modifier.
PROJECTILE_BEHAVIORS
constPROJECTILE_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/projectiles.ts:311
Every behavior this file declares.
QUICK_CHARGE_TICKS_PER_LEVEL
constQUICK_CHARGE_TICKS_PER_LEVEL:5=5
Defined in: item-behaviors/src/behaviors/projectiles.ts:149
How much each Quick Charge level takes off the charge, in ticks.
SMASH_ATTACK_FALL_THRESHOLD
constSMASH_ATTACK_FALL_THRESHOLD:1.5=1.5
Defined in: item-behaviors/src/behaviors/combat.ts:21
MaceItem.SMASH_ATTACK_FALL_THRESHOLD: the fall a smash needs.
SMASH_ATTACK_KNOCKBACK_RADIUS
constSMASH_ATTACK_KNOCKBACK_RADIUS:3.5=3.5
Defined in: item-behaviors/src/behaviors/combat.ts:23
MaceItem.SMASH_ATTACK_KNOCKBACK_RADIUS.
STRONGHOLD_DESTINATION
constSTRONGHOLD_DESTINATION:"#minecraft:eye_of_ender_located"='#minecraft:eye_of_ender_located'
Defined in: item-behaviors/src/behaviors/navigation.ts:24
The structure tag an eye of ender looks for, in Java's # form.
Passed to the world as written, so the host resolves its members the way /locate does rather than the item knowing that the vanilla tag holds the stronghold.
THROWN_PROJECTILES
constTHROWN_PROJECTILES:Readonly<Record<string, {entity:string;power:number; }>>
Defined in: item-behaviors/src/behaviors/projectiles.ts:30
What each throwable launches and how hard, from Java's own item classes.
The keys are Bedrock identifiers, because that is what an item type is registered under; registry.test.ts checks every one of them against the table, since a Java rename such as map to empty_map would otherwise go unnoticed.
VANILLA_ITEM_BEHAVIORS
constVANILLA_ITEM_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/registry.ts:49
Every vanilla behavior, in attachment order.
The groups are ordered so that a behavior which only performs effects and declines the result comes before the one that produces it.
WEARABLE_BEHAVIORS
constWEARABLE_BEHAVIORS: readonlyItemBehaviorSpec[]
Defined in: item-behaviors/src/behaviors/wearable.ts:148
Every behavior this file declares.
bannerBehavior
constbannerBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/placement.ts:149
A banner placed as a block, carrying its patterns.
Bedrock keeps the banner's color in the item's damage value and its patterns in NBT, and Java keeps both in minecraft:banner_patterns plus the identifier. The placement hands the world both, and the block entity is the world's to write.
blockTransformerBehavior
constblockTransformerBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/mining.ts:65
Stripping, pathing and tilling, from minecraft:block_transformer.
26.3 moved the whole table into the block_transformer registry, so the item names a transformer and the world resolves what the block becomes. The interaction is still code, which is this behavior; the mapping is data, which is WorldActions.transform.
boneMealBehavior
constboneMealBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:152
Bone meal, whose outcome belongs to whatever it was used on.
bowBehavior
constbowBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:108
The bow: hold to draw, release to shoot, Infinity keeps the arrow.
brushBehavior
constbrushBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:201
Brushing a suspicious block.
The progress belongs to the block, which already tracks how far it has been brushed. The item reports the stroke and spends a point on a finished one, which is Java's BrushItem.onUseTick and the single point it spends on completion.
bucketBehavior
constbucketBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/fluids.ts:87
Filling and emptying a bucket.
An empty bucket on a source block takes it; a filled one puts its contents against the face it was used on. Java's rule for which side the fluid lands on is "inside the block when it is replaceable, otherwise against the face"; the world decides replaceability, so this asks it for the block.
bundleBehavior
constbundleBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/books.ts:112
A bundle, which opens as a container rather than doing anything to the world.
compassBehavior
constcompassBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/navigation.ts:34
The compass and the recovery compass.
A plain compass points at the world spawn until it is used on a lodestone, which binds it to that position and dimension; a recovery compass points at the last death position. Both are read by the client off the stack, so the behavior's work is writing the target onto it.
consumableBehavior
constconsumableBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/consume.ts:76
Eating and drinking, for every item carrying minecraft:food or minecraft:consumable.
crossbowBehavior
constcrossbowBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:168
The crossbow: a use charges it, and a use while charged fires it.
The loaded projectile lives in minecraft:charged_projectiles, which is the one component that makes the crossbow's two-step use expressible as data rather than as a second item.
dyeBehavior
constdyeBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:75
Dyeing a sheep, a collar, a harness or a sign, from minecraft:dye.
entityPlacementBehavior
constentityPlacementBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/placement.ts:112
Boats, rafts, minecarts, cushions, end crystals, armor stands and paintings.
equippableBehavior
constequippableBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/wearable.ts:53
Putting equipment on: either on the user, when the item is swappable, or on the entity the use landed on, when it is equip_on_interact and the entity is in allowed_entities.
Java's Item.use reaches Equippable.swapWithEquipmentSlot for the first and Equippable.equipOnTarget for the second, in that order, and so does this.
eyeOfEnderBehavior
consteyeOfEnderBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/navigation.ts:133
The eye of ender, thrown toward the nearest stronghold.
Java's EnderEyeItem.use asks the level for the nearest structure in #minecraft:eye_of_ender_located within a hundred chunks before anything else happens. Nothing found means nothing thrown and nothing spent, which is why the search is a query here and the throw is the action: the world spawns the signal, flies it and plays its sounds, and the item only decides.
Filling a portal frame is the portal block family's job: its onPlayerInteract takes the click for a held eye before any item hook runs, writes end_portal_eye_bit and activates a completed ring, so an onUseOn here would never fire for a frame.
fillableBehavior
constfillableBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/fluids.ts:170
Filling a glass bottle or a bowl from the world.
Both are "use on something and get a different item", and what you get depends on what you used it on, which is the block family's knowledge. The behavior asks for the block and maps the three vanilla cases.
fireStarterBehavior
constfireStarterBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:171
Flint and steel and the fire charge.
The same interaction with two costs: the steel spends a point of durability, and the charge spends itself.
fireworkRocketBehavior
constfireworkRocketBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:233
A firework rocket: launched from the hand, or used to boost a glide.
Java's FireworkRocketItem.use spawns the entity either way; the boost is the entity attaching itself to a gliding player rather than a second rule.
fishingRodBehavior
constfishingRodBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:267
The fishing rod: a use casts the hook, and a use while cast reels it in.
float
constfloat: (x) =>number=Math.fround
Defined in: item-behaviors/src/formulas.ts:22
Rounds a number to the nearest float, which is what every step of Java's arithmetic does.
Returns the nearest single precision float representation of a number.
Parameters
x
number
A numeric expression.
Returns
number
goatHornBehavior
constgoatHornBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/books.ts:78
A goat horn, which plays the instrument minecraft:instrument names and then waits out its cooldown.
The component writes the instrument either as an id or inline with its own sound_event, use_duration and range, so both forms are read.
leadBehavior
constleadBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:44
Leashing: a use on an entity ties the lead, and a use on a fence knots it.
Both go through the same action, because the knot is an entity in Java and the world is the thing that knows which of the two it just made.
maceBehavior
constmaceBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/combat.ts:94
The mace's smash: extra damage from the fall, a ring of knockback, and the fall itself cancelled, which is MaceItem.hurtEnemy and postHurtEnemy.
The damage the smash adds reaches the hit through attackDamage's itemBonus; this behavior is the part that happens afterwards.
mapBehavior
constmapBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/navigation.ts:159
Maps: creating one from an empty map, and cloning, extending or locking one at a cartography table.
The map's own data model is the world's. What the item decides is which of the four operations a use asks for, which is the part that depends on the stack.
meleeWeaponBehavior
constmeleeWeaponBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/combat.ts:72
Every item carrying minecraft:weapon: swords, axes, the mace, the trident and the seven spears.
miningToolBehavior
constminingToolBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/mining.ts:39
The durability a tool spends on a broken block, which is Item.mineBlock:
if (!level.isClientSide() && state.getDestroySpeed(level, pos) != 0.0F && tool.damagePerBlock() > 0) {
itemStack.hurtAndBreak(tool.damagePerBlock(), owner, EquipmentSlot.MAINHAND);
}A block with zero hardness costs nothing, which is why breaking tall grass with a sword is free and breaking a cobweb with it is not.
mobBucketBehavior
constmobBucketBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/fluids.ts:126
Pouring a mob bucket out: the water goes down and the entity comes out with the data the bucket stored, which is variant, name and tropical fish pattern.
nameTagBehavior
constnameTagBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:18
Naming an entity, which also makes it persistent.
ominousBottleBehavior
constominousBottleBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/consume.ts:186
Drinking an ominous bottle, which is Bad Omen at the amplifier the bottle carries.
potionBehavior
constpotionBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/consume.ts:145
Drinking a potion, which is the one consumable whose effects live in a registry.
shearsBehavior
constshearsBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/mining.ts:99
Shears on an entity: a sheep, a snow golem, a mooshroom, or a piece of equipment marked can_be_sheared.
Shearing a block, a beehive or a pumpkin is the block family's side of the interaction; this is the entity side, which is the one no component in either edition expresses.
shieldBehavior
constshieldBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/combat.ts:219
The shield: raising it, and the damage it takes for blocking.
minecraft:blocks_attacks carries the whole rule set, including the quarter second of delay before a raised shield counts and the item_damage function that turns blocked damage into durability.
signInkBehavior
constsignInkBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:123
Making sign text glow with a glow ink sac, or taking the glow back off with ink.
spawnEggBehavior
constspawnEggBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/placement.ts:70
The 88 spawn eggs, which spawn what minecraft:entity_data names.
spearBehavior
constspearBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/combat.ts:174
The spear's charge, from minecraft:kinetic_weapon.
1.26's spears are the only vanilla weapon whose rules are entirely data: the damage multiplier, the delay, the forward movement and the sound all come off the component. Holding the use charges; the stab itself is the server's, which calls kineticDamageOf for the number.
spyglassBehavior
constspyglassBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/navigation.ts:101
The spyglass.
Zooming is the Bedrock client's, which it decides from the item it is holding and the server cannot override. What the server does is play the sound and hold the use open, so the client's own state machine matches.
steeringRodBehavior
conststeeringRodBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:291
The carrot on a stick and the warped fungus on a stick, which steer a mount.
suspiciousStewBehavior
constsuspiciousStewBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/consume.ts:163
Eating a suspicious stew, whose effects the crafting flower wrote onto the stack.
throwableBehavior
constthrowableBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/projectiles.ts:70
Throwing: nine items, each a launch and one off the stack.
tridentBehavior
consttridentBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/combat.ts:122
The trident: held to charge, released to throw, unless Riptide launches the holder instead.
Release maps onto onCompleteUse, because the hook table has no release hook and neither does Mojang's ItemCustomComponent. The engine calls it when a held use ends and useDuration says how long it was held, which is what the ten-tick minimum is measured against.
waxingBehavior
constwaxingBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/interaction.ts:101
Waxing with a honeycomb.
The active transformer registry decides whether the clicked block can be waxed, including blocks outside the vanilla namespace.
writableBookBehavior
constwritableBookBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/books.ts:27
A book and quill, which opens its editor.
writtenBookBehavior
constwrittenBookBehavior:ItemBehaviorSpec
Defined in: item-behaviors/src/behaviors/books.ts:46
A written book, which opens for reading, and the knowledge book, which grants the recipes in minecraft:recipes and is consumed.
Functions
againstFace()
againstFace(
block,face):BlockPosition
Defined in: item-behaviors/src/behaviors/placement.ts:29
The position against a block's face.
Parameters
block
face
Returns
applyDeathProtection()
applyDeathProtection(
world,stack,source):ItemStack
Defined in: item-behaviors/src/behaviors/wearable.ts:137
Runs a totem's save: the effects, the sound, and one totem gone.
Parameters
world
stack
source
Returns
The stack to put back, which is one shorter.
applyUnbreaking()
applyUnbreaking(
amount,level,isArmor,random):number
Defined in: item-behaviors/src/formulas.ts:318
How much of a durability hit Unbreaking removes, which is RemoveBinomial.process: one roll per point of damage against the enchantment's chance.
The chance comes from unbreaking.json: level / (level + 1) for anything that is not armor, and 2 * level / (5 * level + 5) for armor. Java switches to a normal approximation above 128 points in one hit, which no item use produces, so only the exact branch is implemented.
Parameters
amount
number
level
number
isArmor
boolean
random
() => number
A source of numbers in [0, 1), which the tests make fixed.
Returns
number
attackDamage()
attackDamage(
context):number
Defined in: item-behaviors/src/formulas.ts:249
How much one melee hit deals, which is the damage half of Player.attack:
float magicBoost = attackStrengthScale * (this.getEnchantedDamage(...) - baseDamage);
baseDamage *= 0.2F + attackStrengthScale * attackStrengthScale * 0.8F;
baseDamage += attackingItemStack.getItem().getAttackDamageBonus(...);
if (criticalAttack) baseDamage *= 1.5F;
float totalDamage = baseDamage + magicBoost;The enchantment bonus scales linearly with the charge while the base scales quadratically, which is why a half-charged sharpened sword keeps most of its enchantment damage and almost none of its own.
Parameters
context
Returns
number
attackSpeedOf()
attackSpeedOf(
stack):number
Defined in: item-behaviors/src/formulas.ts:295
The minecraft:attack_speed a player holding this stack has, which sets the charge time.
Parameters
stack
Returns
number
attackStrengthScale()
attackStrengthScale(
ticksSinceAttack,attackSpeed?):number
Defined in: item-behaviors/src/formulas.ts:268
How charged a swing is, which is Player.getAttackStrengthScale: clamp((attackStrengthTicker + 0.5) / (20 / attackSpeed), 0, 1).
Parameters
ticksSinceAttack
number
attackStrengthTicker, reset to zero on each swing.
attackSpeed?
number = DEFAULT_ATTACK_SPEED
Attributes.ATTACK_SPEED, four for a bare hand.
Returns
number
baseAttackDamageOf()
baseAttackDamageOf(
stack):number
Defined in: item-behaviors/src/formulas.ts:291
The minecraft:attack_damage a player holding this stack has: the player's own base of 1 plus the item's minecraft:base_attack_damage modifier.
Parameters
stack
Returns
number
bedrockIdentifiersInFamilies()
bedrockIdentifiersInFamilies(
families): readonlystring[]
Defined in: item-behaviors/src/registry.ts:110
The Bedrock identifier of every item in one of the named families.
The classifier works on Java items and the registry is keyed by Bedrock identifiers, so this is the join: each row of the table says which Java item its properties came from, and the family of that item is the family of the Bedrock identity.
Parameters
families
ReadonlySet<string>
Returns
readonly string[]
booleanField()
booleanField(
value,key):boolean|undefined
Defined in: item-behaviors/src/raw.ts:36
The value at one key, when it is a boolean.
Parameters
value
unknown
key
string
Returns
boolean | undefined
bowPowerForTime()
bowPowerForTime(
ticksHeld):number
Defined in: item-behaviors/src/behaviors/projectiles.ts:57
The bow's power curve, which is BowItem.getPowerForTime:
float pow = timeHeld / 20.0F;
pow = (pow * pow + pow * 2.0F) / 3.0F;
if (pow > 1.0F) pow = 1.0F;A full draw is 20 ticks and gives 1; below 0.1 the shot does not happen at all, and exactly 1 is what makes an arrow critical.
Parameters
ticksHeld
number
Returns
number
breakTicks()
breakTicks(
speed,hardness,correctToolForDrops):number
Defined in: item-behaviors/src/formulas.ts:152
How many ticks breaking a block takes, which is the figure a server schedules against.
Parameters
speed
number
hardness
number
correctToolForDrops
boolean
Returns
number
canPerform()
canPerform(
world,action):boolean
Defined in: item-behaviors/src/behavior.ts:129
Whether the host performs an action kind, which a behavior asks before it spends its item on one.
A host that cannot perform the action keeps the item: the behavior answers {}, so the click is taken and the stack is unchanged, the way an eye of ender with no stronghold in range is. A host without supports performs everything.
Parameters
world
action
"map" | "place-block" | "break-block" | "spawn-entity" | "launch-projectile" | "play-sound" | "apply-effects" | "remove-effects" | "damage-entity" | "feed" | "teleport-randomly" | "grant-experience" | "start-cooldown" | "consume-durability" | "give-item" | "equip" | "name-entity" | "attach-lead" | "dye-entity" | "shear-entity" | "fertilize" | "ignite" | "brush" | "blocking" | "disable-shield" | "signal" | "open-screen" | "fishing"
Returns
boolean
classifyItem()
classifyItem(
item):ItemClassification
Defined in: item-behaviors/src/families.ts:445
The family one item belongs to.
Parameters
item
Returns
The first family whose rule claims the item, or DATA_ONLY when none does. data only is a real answer rather than a gap: it holds the block items, whose placement the block package owns, and the plain materials that have no use behavior in either edition.
classifyVanillaItems()
classifyVanillaItems(
items?):ItemClassificationReport
Defined in: item-behaviors/src/families.ts:479
Classifies every Java item in the pinned table.
Parameters
items?
readonly ClassifiableItem[] = ...
Returns
The partition. The counts sum to the table's javaItemCount, which is the totality claim and what the test checks.
clockReading()
clockReading(
timeOfDay):number
Defined in: item-behaviors/src/behaviors/navigation.ts:89
The clock face, from 0 at noon round to 1, which is how Java indexes its sixty-four frames.
Parameters
timeOfDay
number
Returns
number
compassTargetOf()
compassTargetOf(
stack,spawn,deathPosition):BlockPosition|undefined
Defined in: item-behaviors/src/behaviors/navigation.ts:68
Where a compass points.
A server entry point rather than a hook, because the answer is read every tick by whatever writes the item's state to the client.
Parameters
stack
spawn
deathPosition
BlockPosition | undefined
Returns
BlockPosition | undefined
The position to point at, or undefined when the needle should spin, which is a lodestone compass in the wrong dimension and a recovery compass with nowhere to go.
consumeOne()
consumeOne(
stack,creative):ItemStack
Defined in: item-behaviors/src/behavior.ts:166
Takes one item off a stack unless the user has infinite materials, which is what every consumable, throwable and placement does.
Parameters
stack
creative
boolean
Returns
The stack to put back in the slot.
cooldownGroupOf()
cooldownGroupOf(
stack):string
Defined in: item-behaviors/src/behavior.ts:101
The cooldown group an item shares, which defaults to the item's own identifier.
Parameters
stack
Returns
string
cooldownTicksOf()
cooldownTicksOf(
stack):number|undefined
Defined in: item-behaviors/src/behavior.ts:95
How many ticks minecraft:use_cooldown asks for, or undefined when the item has none.
Parameters
stack
Returns
number | undefined
correctForDrops()
correctForDrops(
stack,block,world):boolean
Defined in: item-behaviors/src/formulas.ts:204
Whether the tool makes the block drop, which is Tool.isCorrectForDrops: the first rule that matches and states a verdict decides, and an item with no rule for the block is not correct.
Parameters
stack
block
world
Returns
boolean
createTestWorld()
createTestWorld(
options?):TestWorld
Defined in: item-behaviors/src/testing.ts:100
Builds a WorldActions double.
Parameters
options?
TestWorldOptions = {}
The answers the queries give before anything runs.
Returns
crossbowChargeTicks()
crossbowChargeTicks(
stack):number
Defined in: item-behaviors/src/behaviors/projectiles.ts:152
The charge a crossbow needs with its enchantments applied, floored at zero.
Parameters
stack
Returns
number
deathProtectionOf()
deathProtectionOf(
stack): readonlyConsumeEffect[]
Defined in: item-behaviors/src/behaviors/wearable.ts:127
The effects a totem applies when it saves its holder, parsed from minecraft:death_protection.death_effects.
A server entry point rather than a hook, because the save happens on the damage path: the engine finds a stack with the component in either hand, calls this, applies the effects, and takes one off the stack.
Parameters
stack
Returns
readonly ConsumeEffect[]
deferredItemFactory()
deferredItemFactory():
DeferredItemFactory
Defined in: item-behaviors/src/items.ts:55
An ItemFactory for the load order the registry forces.
registerVanillaItemBehaviors runs before loadItemTypes, and the registry it would need does not exist until after. Nothing calls the factory until a hook fires, which is later still, so one indirection is enough.
Returns
destroyProgress()
destroyProgress(
speed,hardness,correctToolForDrops):number
Defined in: item-behaviors/src/formulas.ts:146
The fraction of a block broken in one tick, which is BlockBehaviour.getDestroyProgress:
int modifier = player.hasCorrectToolForDrops(state) ? 30 : 100;
return player.getDestroySpeed(state) / destroySpeed / modifier;Parameters
speed
number
What miningSpeed returned.
hardness
number
The block's destroySpeed; -1 means unbreakable.
correctToolForDrops
boolean
Whether the held tool drops the block.
Returns
number
A fraction per tick; the block breaks when the running total reaches 1, so the whole break takes ceil(1 / progress) ticks.
digSpeedAmplification()
digSpeedAmplification(
effects):number|undefined
Defined in: item-behaviors/src/formulas.ts:51
The highest amplifier Haste or Conduit Power contributes, taken as the strongest of the two the way MobEffectUtil.getDigSpeedAmplification does.
Parameters
effects
readonly ActiveEffect[]
Returns
number | undefined
The amplifier, or undefined when the source has neither effect.
elytraDurabilityTick()
elytraDurabilityTick(
world,stack,source,tick):ItemStack
Defined in: item-behaviors/src/behaviors/wearable.ts:108
One tick of gliding, which costs the elytra a point of durability every twenty ticks.
A server entry point rather than a hook: gliding is a movement state the engine tracks, and the hook table has no tick hook.
Parameters
world
stack
source
tick
number
The glide's tick counter, so the caller decides the phase.
Returns
The stack to keep in the chest slot.
enchantmentLevel()
enchantmentLevel(
stack,enchantment):number
Defined in: item-behaviors/src/formulas.ts:158
The level of one enchantment on a stack, read off minecraft:enchantments.
Parameters
stack
enchantment
string
Returns
number
entityOfBucket()
entityOfBucket(
identifier):string
Defined in: item-behaviors/src/behaviors/fluids.ts:161
The entity behind a mob bucket's identifier.
Java names the item after the mob (cod_bucket holds a cod), so the identifier is the mapping and no table is needed. The one exception is the tadpole, which is also named after its mob, so the rule is total.
Parameters
identifier
string
Returns
string
fieldOf()
fieldOf(
value,key):unknown
Defined in: item-behaviors/src/raw.ts:18
The value at one key of a JSON object, or undefined when there is no object or no key.
Parameters
value
unknown
key
string
Returns
unknown
isArmorForUnbreaking()
isArmorForUnbreaking(
stack):boolean
Defined in: item-behaviors/src/formulas.ts:355
Whether Unbreaking treats the stack as armor, which halves its benefit.
Java asks the #minecraft:enchantable/armor tag; the equipment slot is the same question asked of data this package already has.
Parameters
stack
Returns
boolean
isDamageable()
isDamageable(
stack):boolean
Defined in: item-behaviors/src/formulas.ts:303
Whether a stack can take durability damage at all, which is ItemStack.isDamageableItem: it needs a maximum, a current value, and no minecraft:unbreakable.
Parameters
stack
Returns
boolean
itemBehavior()
itemBehavior(
spec,environment):ItemBehavior
Defined in: item-behaviors/src/behavior.ts:74
Builds an ItemBehavior that closes over the world and the item factory.
Parameters
spec
environment
Returns
itemFactoryFor()
itemFactoryFor(
registry):ItemFactory
Defined in: item-behaviors/src/items.ts:36
An ItemFactory over a registry of resolved item types.
Parameters
registry
Returns
kineticDamageOf()
kineticDamageOf(
stack,baseDamage,charge):number
Defined in: item-behaviors/src/behaviors/combat.ts:204
A spear's kinetic damage: the base attack damage scaled by the component's multiplier against the charge, plus its flat modifier.
Parameters
stack
baseDamage
number
charge
number
How much of the charge is built, 0 to 1.
Returns
number
listField()
listField(
value,key): readonlyunknown[]
Defined in: item-behaviors/src/raw.ts:47
The value at one key as a list.
Java writes several of these fields as either one object or a list of them, so a lone object comes back as a one-element list.
Parameters
value
unknown
key
string
Returns
readonly unknown[]
maceDamageBonus()
maceDamageBonus(
fallDistance):number
Defined in: item-behaviors/src/behaviors/combat.ts:42
The mace's damage bonus, which is MaceItem.getAttackDamageBonus:
if (fallDistance <= 3.0) damage = 4.0 * fallDistance;
else if (fallDistance <= 8.0) damage = 12.0 + 2.0 * (fallDistance - 3.0);
else damage = 22.0 + fallDistance - 8.0;Below the 1.5 block threshold there is no smash and no bonus. The Density and Breach enchantments add to this through modifyFallBasedDamage, which the enchantment package owns.
Parameters
fallDistance
number
How far the attacker has fallen, in blocks.
Returns
number
miningEfficiencyOf()
miningEfficiencyOf(
level):number
Defined in: item-behaviors/src/formulas.ts:165
The minecraft:mining_efficiency an Efficiency level contributes, which is the enchantment's own levels_squared value with added: 1.0.
Parameters
level
number
Returns
number
miningFatigueAmplification()
miningFatigueAmplification(
effects):number|undefined
Defined in: item-behaviors/src/formulas.ts:61
The amplifier of Mining Fatigue, or undefined when the source does not have it.
Parameters
effects
readonly ActiveEffect[]
Returns
number | undefined
miningSpeed()
miningSpeed(
context):number
Defined in: item-behaviors/src/formulas.ts:107
How fast an entity mines, which is Player.getDestroySpeed(BlockState) in the 26.3 server jar, line for line:
float speed = this.inventory.getSelectedItem().getDestroySpeed(state);
if (speed > 1.0F) speed += (float)this.getAttributeValue(Attributes.MINING_EFFICIENCY);
if (MobEffectUtil.hasDigSpeed(this)) speed *= 1.0F + (MobEffectUtil.getDigSpeedAmplification(this) + 1) * 0.2F;
if (this.hasEffect(MobEffects.MINING_FATIGUE)) speed *= (float)Math.pow(0.3, amplifier + 1);
speed *= (float)this.getAttributeValue(Attributes.BLOCK_BREAK_SPEED);
if (this.isEyeInFluid(FluidTags.WATER)) speed *= (float)...SUBMERGED_MINING_SPEED...;
if (!this.onGround()) speed /= 5.0F;The Efficiency bonus only applies when the tool is already faster than bare hands, which is why a pickaxe with Efficiency V mines dirt no faster.
The Bedrock client computes its own, different number and the server cannot override it; see the README for what that costs.
Parameters
context
Returns
number
Blocks of hardness per tick-unit, before destroyProgress divides by the block's hardness.
numberField()
numberField(
value,key):number|undefined
Defined in: item-behaviors/src/raw.ts:24
The value at one key, when it is a number.
Parameters
value
unknown
key
string
Returns
number | undefined
onCooldown()
onCooldown(
world,stack,source):boolean
Defined in: item-behaviors/src/behavior.ts:133
Whether the source is still waiting out the stack's cooldown group.
Parameters
world
stack
source
Returns
boolean
parseConsumeEffect()
parseConsumeEffect(
value):ConsumeEffect|undefined
Defined in: item-behaviors/src/consumeEffects.ts:89
Parses one entry of a consume effect list.
Parameters
value
unknown
Returns
ConsumeEffect | undefined
parseConsumeEffects()
parseConsumeEffects(
value): readonlyConsumeEffect[]
Defined in: item-behaviors/src/consumeEffects.ts:126
Parses a whole consume effect list.
An entry whose type is not one of the five is dropped rather than failing the load, which is the same leniency the item package's schemas take: a release that adds a sixth should not stop the server from starting.
Parameters
value
unknown
Returns
readonly ConsumeEffect[]
parseDeathEffects()
parseDeathEffects(
value): readonlyConsumeEffect[]
Defined in: item-behaviors/src/consumeEffects.ts:132
Parses minecraft:death_protection's list, which is the same union under another key.
Parameters
value
unknown
Returns
readonly ConsumeEffect[]
placedEntityOf()
placedEntityOf(
identifier):object
Defined in: item-behaviors/src/behaviors/placement.ts:55
The entity one placement item spawns.
A boat, raft or minecart item names a variant and a base: oak_chest_boat is a chest_boat carrying oak. Bedrock models that as one entity with a variant, which is what this returns.
Parameters
identifier
string
Returns
object
entity
readonlyentity:string
variant?
readonlyoptionalvariant?:string
potionEffectsOf()
potionEffectsOf(
context,stack): readonlyEffectApplication[]
Defined in: item-behaviors/src/behaviors/consume.ts:125
The effects one potion stack applies: the registry's own list for the named potion, plus whatever custom_effects adds, both scaled.
Parameters
context
stack
Returns
readonly EffectApplication[]
rawComponent()
rawComponent(
stack,name):unknown
Defined in: item-behaviors/src/behavior.ts:88
One component's value for a stack, raw.
The patch wins when the stack has one, as everywhere else in the item model; otherwise this is the type's own JSON rather than the parsed form, so the fields the item package's schema drops are still there.
Parameters
stack
name
string
Returns
unknown
rawComponentsOf()
rawComponentsOf(
context):Readonly<Record<string,unknown>>
Defined in: item-behaviors/src/behavior.ts:65
The raw components map of a definition.
Both the bind context and a resolved type carry the definition, so the same reader serves a behavior at load and an entry point at runtime.
Parameters
context
Returns
Readonly<Record<string, unknown>>
registerVanillaItemBehaviors()
registerVanillaItemBehaviors(
registry,environment):void
Defined in: item-behaviors/src/registry.ts:135
Registers and attaches every vanilla item behavior.
Parameters
registry
The registry to pass to loadItemTypes({ behaviors }).
environment
The world the behaviors act on and the factory they build result stacks with.
Returns
void
Throws
When a behavior name is already registered, which means this ran twice against the same registry.
runConsumeEffects()
runConsumeEffects(
effects,target,world):void
Defined in: item-behaviors/src/consumeEffects.ts:143
Runs the parsed effects on a target.
A probability below 1 draws once per effect, which is what makes raw chicken poison three bites in ten rather than every bite.
Parameters
effects
readonly ConsumeEffect[]
target
world
Returns
void
selectorFor()
selectorFor(
behavior):string| readonlystring[] | ((identifier) =>boolean)
Defined in: item-behaviors/src/registry.ts:120
What one behavior attaches to: every identifier, or a computed list.
Parameters
behavior
string
Returns
string | readonly string[] | ((identifier) => boolean)
shieldDurabilityCost()
shieldDurabilityCost(
stack,blockedDamage):number
Defined in: item-behaviors/src/behaviors/combat.ts:249
The durability a blocked hit costs, which is minecraft:blocks_attacks.item_damage: nothing below the threshold, and base + factor * damage above it, floored.
This is a server entry point rather than a hook, because blocking happens on the damage path and the hook table has no hook for it.
Parameters
stack
blockedDamage
number
Returns
number
spendDurability()
spendDurability(
stack,amount,options):DurabilitySpend
Defined in: item-behaviors/src/formulas.ts:370
Spends durability on a stack, which is ItemStack.hurtAndBreak through processDurabilityChange and applyDamage.
Java truncates the Unbreaking result to an int and skips the whole path when the amount lands on zero, so an Unbreaking III pickaxe spends nothing three times out of four.
Parameters
stack
amount
number
options
Returns
The outcome; stack is a copy and the argument is left alone.
spendItemDurability()
spendItemDurability(
world,stack,source,amount):ItemStack
Defined in: item-behaviors/src/behavior.ts:144
Spends durability on the held stack and tells the world about it.
Every family that wears an item out goes through here, so the Unbreaking roll, the creative check and the "it broke" report happen in one place.
Parameters
world
stack
source
amount
number
Returns
The stack to put back in the slot, unchanged when nothing was spent.
stringField()
stringField(
value,key):string|undefined
Defined in: item-behaviors/src/raw.ts:30
The value at one key, when it is a string.
Parameters
value
unknown
key
string
Returns
string | undefined
submergedMiningSpeedOf()
submergedMiningSpeedOf(
level):number
Defined in: item-behaviors/src/formulas.ts:173
The minecraft:submerged_mining_speed an Aqua Affinity level produces.
The enchantment is add_multiplied_total with base: 4.0, so one level takes the 0.2 default to 1.0 and removes the underwater penalty outright.
Parameters
level
number
Returns
number
testBlock()
testBlock(
identifier,position?,states?):BlockReference
Defined in: item-behaviors/src/testing.ts:160
A plain BlockReference at the origin unless a position is given.
Parameters
identifier
string
position?
BlockPosition = ...
states?
Readonly<Record<string, string | number | boolean>> = {}
Returns
testSource()
testSource(
identifier?,runtimeId?):ItemSource
Defined in: item-behaviors/src/testing.ts:157
A plain ItemSource, so a test does not build one by hand.
Parameters
identifier?
string = 'minecraft:player'
runtimeId?
number = 1
Returns
toolOf()
toolOf(
stack):ObjectShape<{rules:Parser<ObjectShape<{blocks:Parser<HolderSet>; }, {correct_for_drops:Parser<boolean>;speed:Parser<number>; }>[]>; }, {can_destroy_blocks_in_creative:Parser<boolean>;damage_per_block:Parser<number>;default_mining_speed:Parser<number>; }> |undefined
Defined in: item-behaviors/src/formulas.ts:177
Reads minecraft:tool off a stack.
Parameters
stack
Returns
ObjectShape<{ rules: Parser<ObjectShape<{ blocks: Parser<HolderSet>; }, { correct_for_drops: Parser<boolean>; speed: Parser<number>; }>[]>; }, { can_destroy_blocks_in_creative: Parser<boolean>; damage_per_block: Parser<number>; default_mining_speed: Parser<number>; }> | undefined
toolSpeedFor()
toolSpeedFor(
stack,block,world):number
Defined in: item-behaviors/src/formulas.ts:189
The tool's mining speed for one block, which is Tool.getMiningSpeed: the first rule whose block set matches and that carries a speed wins, and the default applies when none does.
An item with no minecraft:tool mines at 1, which is Item.getDestroySpeed.
Parameters
stack
block
world
Returns
number
vanillaJavaItems()
vanillaJavaItems(): readonly
ClassifiableItem[]
Defined in: item-behaviors/src/families.ts:449
Every Java item in the pinned table, including the merged and excepted ones.
Returns
readonly ClassifiableItem[]
withCooldown()
withCooldown(
world,stack,source,result):ItemUseResult
Defined in: item-behaviors/src/behavior.ts:108
Starts the item's minecraft:use_cooldown if it has one, and reports it on the result so the engine and the client agree on the number.