homechevron_rightEnchantments

Enchantments

Minecraft enchantments modify game mechanics by altering item behavior, applying effects or changing damage calculations. Kore provides a fully type‐safe, Kotlin-based DSL for creating custom enchantments that can be used in datapacks. This documentation explains how to create enchantments in Kore, and presents a detailed example for every available enchantment effect.

For general concepts on creating datapacks with Kore, please refer to the other documentation pages (e.g. Predicates, Components). This article is dedicated exclusively to creating enchantments.

Basic Enchantment Creation

Creating an enchantment in Kore is as simple as calling the enchantment function inside a data pack. A basic enchantment is defined by its description, what items it supports, and additional properties such as exclusive sets, primary items, and equipment slots.

For example:

dataPack("my_datapack") {
    enchantment("test") {
        description("This is a test enchantment.")
        exclusiveSet(Tags.Enchantment.IN_ENCHANTING_TABLE)
        supportedItems(Items.DIAMOND_SWORD, Items.DIAMOND_AXE)
        primaryItems(Tags.Item.AXES)
        slots(EquipmentSlot.MAINHAND, EquipmentSlot.OFFHAND)
    }
}

This snippet creates a simple enchantment named “test” that can be applied to a diamond sword or axe, with additional restrictions on the type of items and slots.

Enchantment Effects

An enchantment’s power is defined in the effects block. Kore supports a wide range of effects – each affecting a different aspect of gameplay. You can combine multiple effects by using functions within the effects { ... } builder. Below is an exhaustive list of every supported enchantment effect along with a precise Kotlin example.

Ammo Use

Sets the amount of ammunition used when firing a bow or crossbow.

enchantment("ammo_use") {
    effects {
        ammoUse {
            add(5)
        }
    }
}

Attributes

Modifies or adds attribute modifiers to items. For example, increasing an item’s scale.

enchantment("attributes") {
    effects {
        attributes {
            attribute("my_modifier", name, Attributes.SCALE, AttributeModifierOperation.ADD_VALUE, 5)
        }
    }
}

Armor Effectiveness

Modifies the effectiveness of armor when the enchantment is active.

enchantment("armor_effectiveness") {
    effects {
        armorEffectiveness {
            add(5) {
                requirements {
                    weatherCheck(raining = true)
                }
            }
            allOf {
                add(5)
                allOf {
                    add(5)
                }
            }
            multiply(2)
            removeBinomial(2)
            set(2)
        }
    }
}

Block Experience

Calculates and awards experience based on block-related factors using a combination of level-based providers. This effect demonstrates the DSL’s advanced capabilities by combining several sub-effects:

enchantment("block_experience") {
    effects {
        blockExperience {
            allOf {
                add(clampedLevelBased(5, 0.0, 10.0))
                add(constantLevelBased(5))
                add(fractionLevelBased(1, 5))
                add(levelsSquaredLevelBased(2))
                add(linearLevelBased(2, 2))
                add(lookupLevelBased(2, 2, fallback = 2))
            }
        }
    }
}

Crossbow Charging Sounds

Changes the sounds produced when a crossbow is charged.

enchantment("crossbow_charging_sounds") {
    effects {
        crossbowChargingSounds {
            crossbowChargingSound {
                start(SoundEvents.Item.Crossbow.QUICK_CHARGE_3)
            }
        }
    }
}

Crossbow Charge Time

Alters the time required to charge a crossbow.

enchantment("crossbow_charge_time") {
    effects {
        crossbowChargeTime {
            add(5)
        }
    }
}

Damage

Applies an additional damage effect when the enchanted item is used.

enchantment("damage") {
    effects {
        damage {
            add(5)
        }
    }
}

Damage Immunity

Gives temporary immunity from damage; can also trigger a sound effect when activated.

enchantment("damage_immunity") {
    effects {
        damageImmunity {
            sound {
                requirements {
                    weatherCheck(raining = true)
                }
            }
        }
    }
}

Equipment Drops

Modifies the probability and quantity of equipment drops when an entity is defeated.

enchantment("equipment_drops") {
    effects {
        equipmentDrops {
            add(EquipmentDropsSpecifier.ATTACKER, 5) {
                requirements {
                    weatherCheck(raining = true)
                }
            }
            allOf(EquipmentDropsSpecifier.VICTIM) {
                add(5)
                allOf {
                    add(5)
                }
            }
        }
    }
}

Fishing Luck Bonus

Increases luck when fishing.

enchantment("fishing_luck_bonus") {
    effects {
        fishingLuckBonus {
            add(5)
        }
    }
}

Fishing Time Reduction

Reduces the time required to catch fish.

enchantment("fishing_time_reduction") {
    effects {
        fishingTimeReduction {
            add(5)
        }
    }
}

Hit Block

A multifaceted effect triggered when the enchanted item is used to hit a block. It supports many sub-effects including applying mob effects, damaging entities, modifying item durability, explosions, igniting blocks, playing sounds, changing block states, and summoning particles or entities.

enchantment("hit_block") {
    effects {
        hitBlock {
            allOf {
                applyMobEffect(Effects.SPEED) {
                    maxDuration(2)
                    minAmplifier(1)
                }
                requirements {
                    weatherCheck(raining = true)
                }
            }
            damageEntity(DamageTypes.IN_FIRE, 1, 2) {
                requirements {
                    weatherCheck(raining = false)
                }
            }
            changeItemDamage(1)
            explode(
                attributeToUser = true,
                createFire = true,
                blockInteraction = BlockInteraction.TNT,
                smallParticle = Particles.ANGRY_VILLAGER,
                largeParticle = Particles.ANGRY_VILLAGER,
                sound = Sounds.Random.FUSE
            ) {
                radius(2)
            }
            ignite(2)
            playSound(SoundEvents.Entity.FireworkRocket.LAUNCH, 5f)
            replaceBlock(simpleStateProvider(Blocks.DIAMOND_BLOCK)) {
                offset(5, 5, 5)
                triggerGameEvent = GameEvents.BLOCK_PLACE
            }
            replaceDisk(simpleStateProvider(Blocks.DIAMOND_BLOCK)) {
                radius(5)
                height(2)
            }
            runFunction(FunctionArgument("function", "namespace"))
            setBlockProperties {
                properties {
                    this["test"] = "test"
                }
            }
            spawnParticles(
                Particles.ANGRY_VILLAGER,
                horizontalPositionType = ParticlePositionType.IN_BOUNDING_BOX,
                verticalPositionType = ParticlePositionType.IN_BOUNDING_BOX,
            ) {
                horizontalVelocity(base = 2.5f, movementScale = 1.2f)
            }
            summonEntity(EntityTypes.AREA_EFFECT_CLOUD)
        }
    }
}

Item Damage

Inflicts additional damage (i.e. worsening the item's condition).

enchantment("item_damage") {
    effects {
        itemDamage {
            add(5)
        }
    }
}

Knockback

Applies extra knockback to the target when attacking.

enchantment("knockback") {
    effects {
        knockback {
            add(5)
        }
    }
}

Mob Experience

Increases the experience dropped by mobs upon death.

enchantment("mob_experience") {
    effects {
        mobExperience {
            add(5)
        }
    }
}

Post Attack

Executes effects immediately after an attack is completed. This effect can both apply a mob effect and cause damage.

enchantment("post_attack") {
    effects {
        postAttack {
            applyMobEffect(PostAttackSpecifier.ATTACKER, PostAttackSpecifier.DAMAGING_ENTITY, Effects.SPEED) {
                requirements {
                    weatherCheck(raining = true)
                }
            }
            damageEntity(PostAttackSpecifier.VICTIM, PostAttackSpecifier.DAMAGING_ENTITY, DamageTypes.IN_FIRE, 1, 2)
        }
    }
}

Prevent Armor Change

Prevents armor slots from being modified.

enchantment("prevent_armor_change") {
    effects {
        preventArmorChange()
    }
}

Prevent Equipment Drop

Stops equipment from being dropped on death.

enchantment("prevent_equipment_drop") {
    effects {
        preventEquipmentDrop()
    }
}

Projectile Count

Modifies the number of projectiles produced (for example, by a crossbow).

enchantment("projectile_count") {
    effects {
        projectileCount {
            add(5)
        }
    }
}

Projectile Piercing

Sets the number of targets a projectile can pierce.

enchantment("projectile_piercing") {
    effects {
        projectilePiercing {
            add(5)
        }
    }
}

Projectile Spawned

Executes an effect when a projectile entity has been spawned from a bow, crossbow, snowball, trident, splash potion, lingering potion, ender pearl, firework rocket, wind charge, or egg.

enchantment("projectile_spawned") {
    effects {
        projectileSpawned {
            applyMobEffect(Effects.SPEED) {
                maxDuration(2)
                minAmplifier(1)
            }
        }
    }
}

Projectile Spread

Alters the spread angle of projectiles fired.

enchantment("projectile_spread") {
    effects {
        projectileSpread {
            add(5)
        }
    }
}

Repair with XP

Repairs an item using player experience when the item is used.

enchantment("repair_with_xp") {
    effects {
        repairWithXp {
            add(5)
        }
    }
}

Smash Damage Per Fallen Block

Increases damage based on the number of blocks fallen before impact.

enchantment("smash_damage_per_fallen_block") {
    effects {
        smashDamagePerFallenBlock {
            add(5)
        }
    }
}

Tick

Executes an effect periodically (every game tick). For example, dealing damage over time.

enchantment("tick") {
    effects {
        tick {
            damageEntity(DamageTypes.IN_FIRE, 1, 2)
        }
    }
}

Trident Return Acceleration

Accelerates the return speed of a thrown trident.

enchantment("trident_return_acceleration") {
    effects {
        tridentReturnAcceleration {
            add(5)
        }
    }
}

Trident Spin Attack Strength

Boosts the strength of a trident’s spin attack.

enchantment("trident_spin_attack_strength") {
    effects {
        tridentSpinAttackStrength {
            add(5)
        }
    }
}

Trident Sound

Modifies the sound played when a trident is thrown or returns.

enchantment("trident_sound") {
    effects {
        tridentSound {
            sound(SoundEvents.Entity.FireworkRocket.LAUNCH, 5f)
        }
    }
}

linkEnchantments

linkBasic Enchantment Creation

linkEnchantment Effects

linkAmmo Use

linkAttributes

linkArmor Effectiveness

linkBlock Experience

linkCrossbow Charging Sounds

linkCrossbow Charge Time

linkDamage

linkDamage Immunity

linkEquipment Drops

linkFishing Luck Bonus

linkFishing Time Reduction

linkHit Block

linkItem Damage

linkKnockback

linkMob Experience

linkPost Attack

linkPrevent Armor Change

linkPrevent Equipment Drop

linkProjectile Count

linkProjectile Piercing

linkProjectile Spawned

linkProjectile Spread

linkRepair with XP

linkSmash Damage Per Fallen Block

linkTick

linkTrident Return Acceleration

linkTrident Spin Attack Strength

linkTrident Sound

linkFurther Reading