Advancements

Advancements

Advancements in Kore can be created using the advancement function. This documentation will show you how to create and customize advancements.

Basic Usage

To create a basic advancement:

dataPack("my_datapack") {
    advancement("my_advancement") {
        display(Items.DIAMOND_SWORD, "Title", "Description") {
            frame = AdvancementFrameType.TASK
        }

        criteria {
            // Define criteria here
        }
    }
}

Parent Advancements

You can specify a parent advancement for your advancement. This is done by setting the parent property to an Advancement object or an AdvancementArgument object. Here's an example:

advancement("my_advancement") {
    parent = Advancements.Story.ROOT  // Reference to vanilla advancement
    // or
    parent = AdvancementArgument("custom_advancement", "my_namespace")
}

Display

The display block allows you to customize how the advancement appears in-game:

advancement("my_advancement") {
    display(Items.DIAMOND_SWORD) {
        icon {
            item(Items.DIAMOND_SWORD)
        }
        title = textComponent("Title")
        description = textComponent("Description", Color.GRAY)
        frame = AdvancementFrameType.TASK
        background = "minecraft:textures/gui/advancements/backgrounds/adventure.png"
        showToast = true
        announceToChat = true
        hidden = false
    }
}

• icon: The icon of the advancement, defined by an AdvancementIcon object which is an item + nbt data.
• title: The title of the advancement, defined by a ChatComponents object.
• description: The description of the advancement, defined by a ChatComponents object.
• frame: The frame type of the advancement, which can be CHALLENGE, GOAL, or TASK, defaults to TASK.
• background: The background texture of the advancement, specified as a string (optional).
• showToast: Whether to show a toast notification when the advancement is achieved (optional).
• announceToChat: Whether to announce the advancement in chat when it is achieved (optional).
• hidden: Whether the advancement is hidden until it is achieved (optional).

Criteria

Example usage:

Criteria define the conditions that must be met to earn the advancement. You can add multiple criteria:

advancement("my_advancement") {
    criteria {
        // Simple item consumption
        consumeItem("eat_golden_apple") {
            item {
                item(Items.GOLDEN_APPLE)
            }
        }

        // With conditions
        sleptInBed("sleep_in_bed") {
            conditions {
                randomChance(0.8f)
                timeCheck(5f..15f)
            }
        }
    }
}

Available Triggers

Here are all the available trigger types:

• allayDropItemOnBlock: Triggers when an allay drops an item on a block
  • Properties: location
• anyBlockUse: Triggers when a player uses any block
• avoidVibrations: Triggers when a player avoids vibrations
• beeNestDestroyed: Triggers when a bee nest is destroyed
  • Properties: block, item, numBeesInside
• bredAnimals: Triggers when animals are bred
  • Properties: child, parent, partner
• changedDimension: Triggers when a player changes dimension
  • Properties: from, to
• channeledLightning: Triggers when lightning is channeled
  • Properties: victims (list of entities)
• constructBeacon: Triggers when a beacon is constructed
  • Properties: level
• consumeItem: Triggers when an item is consumed
  • Properties: item
• crafterRecipeCrafted: Triggers when a recipe is crafted
  • Properties: recipeId, ingredients
• curedZombieVillager: Triggers when a zombie villager is cured
  • Properties: villager, zombie
• defaultBlockUse: Triggers when a block is used with default interaction
• effectsChanged: Triggers when a player's effects change
  • Properties: effects, source
• enchantedItem: Triggers when an item is enchanted
  • Properties: item, levels
• enter_block: Triggers when a player enters a block
  • Properties: block, states
• entityHurtPlayer: Triggers when an entity hurts a player
  • Properties: damage
• entityKilledPlayer: Triggers when an entity kills a player
  • Properties: entity, killingBlow
• fallAfterExplosion: Triggers after falling from an explosion
  • Properties: startPosition, distance, cause
• fallFromHeight: Triggers when falling from a height
  • Properties: startPosition, distance
• filledBucket: Triggers when a bucket is filled
  • Properties: item
• fishingRodHooked: Triggers when a fishing rod hooks something
  • Properties: entity, item, rod
• heroOfTheVillage: Triggers when becoming a hero of the village
• impossible: Prevents the advancement from being achieved, very useful for creating advancements that should only trigger functions
• inventoryChanged: Triggers when inventory contents change
  • Properties: items, slots
• itemDurabilityChanged: Triggers when item durability changes
  • Properties: delta, durability, item
• itemUsedOnBlock: Triggers when an item is used on a block
  • Properties: location
• killedByCrossbow: Triggers when killed by a crossbow
  • Properties: uniqueEntityTypes, victims
• killMobNearSculkCatalyst: Triggers when a mob is killed near a sculk catalyst
  • Properties: entity, killingBlow
• levitation: Triggers during levitation
  • Properties: distance, duration
• lightningStrike: Triggers on lightning strike
  • Properties: bystander, lightning
• location: Triggers every seconds
• netherTravel: Triggers when a player enters or exits the Nether
  • Properties: distance, startPosition
• placedBlock: Triggers when a block is placed
  • Properties: location
• playerGeneratesContainerLoot: Triggers when container loot is generated
  • Properties: lootTable
• playerHurtEntity: Triggers when a player hurts an entity
  • Properties: damage, entity
• playerKilledEntity: Triggers when a player kills an entity
  • Properties: entity, killingBlow
• recipeCrafted: Triggers when a recipe is crafted
  • Properties: recipeId, ingredients
• recipeUnlocked: Triggers when a recipe is unlocked
  • Properties: recipe
• rideEntityInLava: Triggers when riding an entity in lava
  • Properties: distance, startPosition
• shotCrossbow: Triggers when shooting a crossbow
  • Properties: item
• sleptInBed: Triggers when a player sleeps in a bed
• slideDownBlock: Triggers when sliding down a block
  • Properties: block
• startedRiding: Triggers when riding an entity
• summonedEntity: Triggers when an entity is summoned
  • Properties: entity
• tameAnimal: Triggers when an animal is tamed
  • Properties: entity
• targetHit: Triggers when a target block is hit
  • Properties: signalStrength, projectile
• thrownItemPickedUpByEntity: Triggers when a thrown item is picked up by an entity
  • Properties: entity, item
• thrownItemPickedUpByPlayer: Triggers when a thrown item is picked up by a player
  • Properties: entity, item
• tick: Triggers every tick, aka 20 times per second
• usedEnderEye: Triggers when an ender eye is used
  • Properties: distance
• usedTotem: Triggers when a totem is used
  • Properties: item
• usingItem: Triggers while using an item
  • Properties: item
• villagerTrade: Triggers when a villager trades
  • Properties: item, zombie
• voluntaryExile: Triggers when a player causes a raid in a village

Each trigger can include conditions that further specify when it should activate. See the specific trigger examples above for detailed usage.

Trigger Examples

Here are examples for each trigger type:

advancement("trigger_examples") {
    criteria {
        // Allay Drop Item On Block
        allayDropItemOnBlock("allay_drop") {
            location {
                block {
                    blocks(Blocks.GRASS_BLOCK, Blocks.DIRT)
                }
            }
        }

        // Any Block Use
        anyBlockUse("use_block") {
            conditions {
                playerProperties {
                    lookingAt(Blocks.CRAFTING_TABLE)
                }
            }
        }

        // Avoid Vibrations
        avoidVibrations("avoid_sculk") {
            conditions {
                location {
                    block = Blocks.SCULK_SENSOR
                }
            }
        }

        // Bee Nest Destroyed
        beeNestDestroyed("destroy_nest") {
            block = Blocks.BEE_NEST
            numBeesInside = rangeOrInt(1)
            item {
                item(Items.HONEYCOMB)
            }
        }

        // Bred Animals
        bredAnimals("breed_animals") {
            child {
                conditions {
                    entityProperties {
                        type(EntityTypes.COW)
                    }
                }
            }
            parent {
                conditions {
                    entityProperties {
                        type(EntityTypes.COW)
                    }
                }
            }
            partner {
                conditions {
                    entityProperties {
                        type(EntityTypes.COW)
                    }
                }
            }
        }

        // Channeled Lightning
        channeledLightning("lightning_rod") {
            victim {
                conditions {
                    entityProperties {
                        type(EntityTypes.CREEPER)
                    }
                }
            }
        }

        // Changed Dimension
        changedDimension("enter_nether") {
            from = Dimensions.OVERWORLD
            to = Dimensions.NETHER
        }

        // Construct Beacon
        constructBeacon("make_beacon") {
            level = rangeOrInt(4)
        }

        // Consume Item
        consumeItem("eat_apple") {
            item {
                items = listOf(Items.GOLDEN_APPLE)
            }
        }

        // Crafter Recipe Crafted
        crafterRecipeCrafted("craft_diamond") {
            recipeId = Recipes.DIAMOND
            ingredient(Items.DIAMOND) {
                components {
                    damage(0)
                }
            }
        }

        // Cured Zombie Villager
        curedZombieVillager("cure_zombie") {
            villager {
                conditions {
                    entityProperties {
                        type(EntityTypes.VILLAGER)
                    }
                }
            }
            zombie {
                conditions {
                    entityProperties {
                        type(EntityTypes.ZOMBIE)
                    }
                }
            }
        }

        // Default Block Use
        defaultBlockUse("use_default") {
            conditions {
                playerProperties {
                    lookingAt(Blocks.CHEST)
                }
            }
        }

        // Effects Changed
        effectsChanged("get_effect") {
            effect(Effects.SPEED) {
                amplifier = rangeOrInt(1..3)
                duration = rangeOrInt(100..200)
            }
            source {
                conditions {
                    entityProperties {
                        type(EntityTypes.WITCH)
                    }
                }
            }
        }

        // Enchanted Item
        enchantedItem("enchant_item") {
            item {
                item(Items.DIAMOND_SWORD)
            }
            levels = rangeOrInt(1..3)
        }

        // Enter Block
        enterBlock("enter_block") {
            block = Blocks.REDSTONE_LAMP
            states {
                this["lit"] = "true"
            }
        }

        // Entity Hurt Player
        entityHurtPlayer("hurt_player") {
            damage {
                sourceEntity {
                    type(EntityTypes.ZOMBIE)
                }
                taken = rangeOrDouble(5.0..10.0)
                type {
                    tag(Tags.DamageType.IS_FALL)
                }
            }
        }

        // Fall After Explosion
        fallAfterExplosion("tnt_launch") {
            startPosition {
                position {
                    y = rangeOrInt(100..200)
                }
            }
            distance {
                horizontal(10f)
            }
        }

        // Fall From Height
        fallFromHeight("high_fall") {
            distance {
                vertical(20f)
            }
        }

        // Filled Bucket
        filledBucket("fill_bucket") {
            item {
                item(Items.WATER_BUCKET)
            }
        }

        // Fishing Rod Hooked
        fishingRodHooked("catch_fish") {
            item {
                item(Items.FISHING_ROD)
            }
            rod {
                components {
                    enchantments {
                        enchantment(Enchantments.LUCK_OF_THE_SEA, 3)
                    }
                }
            }
        }

        // Hero of the Village
        heroOfTheVillage("save_village") {
            conditions {
                location {
                    dimension = Dimensions.OVERWORLD
                }
            }
        }

        // Impossible
        impossible("impossible")

        // Inventory Changed
        inventoryChanged("get_diamond") {
            item {
                item(Items.DIAMOND)
            }
            slots {
                empty = rangeOrInt(1..3)
            }
        }

        // Item Durability Changed
        itemDurabilityChanged("tool_break") {
            delta = rangeOrInt(-10..-1)
            item {
                item(Items.DIAMOND_PICKAXE)
            }
        }

        // Item Used on Block
        itemUsedOnBlock("bone_meal_use") {
            location {
                predicate {
                    locationCheck {
                        block {
                            blocks(Blocks.GRASS_BLOCK, Blocks.DIRT)
                        }
                    }
                }
            }
        }

        // Killed By Crossbow
        killedByCrossbow("crossbow_kill") {
            uniqueEntityTypes = rangeOrInt(1)
            victims {
                conditions {
                    entityProperties {
                        type(EntityTypes.ZOMBIE)
                    }
                }
            }
        }

        // Kill Mob Near Sculk Catalyst
        killMobNearSculkCatalyst("kill_mob") {
            entity {
                type(EntityTypes.ZOMBIE)
            }
            killingBlow {
                sourceEntity {
                    type(EntityTypes.PLAYER)
                }
            }
        }

        // Levitation
        levitation("float_up") {
            distance {
                y(10f)
            }
            duration = rangeOrInt(10..20)
        }

        // Lightning Strike
        lightningStrike("struck") {
            bystander {
                type {
                    conditions {
                        entityProperties {
                            type(EntityTypes.CREEPER)
                        }
                    }
                }
            }
        }

        // Location
        location("reach_end") {
            conditions {
                location {
                    dimension = Dimensions.THE_END
                }
            }
        }

        // Nether Travel
        netherTravel("enter_nether") {
            distance {
                horizontal(100f)
            }
            startPosition {
                position {
                    x = rangeOrInt(0..100)
                    z = rangeOrInt(0..100)
                }
            }
        }

        // Placed Block
        placedBlock("place_block") {
            conditions {
                location {
                    biomes(Biomes.PLAINS)
                }
            }
        }

        // Player Generates Container Loot
        playerGeneratesContainerLoot("find_treasure", LootTables.Chests.BURIED_TREASURE)

        // Player Hurt Entity
        playerHurtEntity("hurt_mob") {
            damage {
                taken = rangeOrDouble(5.0..10.0)
            }
        }

        // Player Killed Entity
        playerKilledEntity("kill_mob") {
            entity {
                conditions {
                    entityProperties {
                        type(EntityTypes.ZOMBIE)
                    }
                }
            }
        }

        // Recipe Crafted
        recipeCrafted("craft_diamond") {
            recipeId = Recipes.DIAMOND
            ingredient(Items.DIAMOND) {
                components {
                    damage(0)
                }
            }
        }

        // Recipe Unlocked
        recipeUnlocked("unlock_recipe", Recipes.DIAMOND)

        // Ride Entity In Lava
        rideEntityInLava("lava_ride") {
            distance {
                horizontal(10f)
            }
            startPosition {
                position {
                    y = rangeOrInt(100..200)
                }
            }
        }

        // Shot Crossbow
        shotCrossbow("shoot_crossbow") {
            item {
                item(Items.CROSSBOW)
                enchantments {
                    enchantment(Enchantments.MULTISHOT, 1)
                }
            }
        }

        // Slept In Bed
        sleptInBed("sleep_in_bed")

        // Slide Down Block
        slideDownBlock("slide_down") {
            block {
                blocks(Blocks.SNOW_BLOCK)
            }
        }

        // Started Riding
        startedRiding("ride_horse") {
            conditions {
                vehicle {
                    type(EntityTypes.HORSE)
                }
            }
        }

        // Summoned Entity
        summonedEntity("summon_iron_golem") {
            entity {
                type(EntityTypes.IRON_GOLEM)
            }
        }

        // Tame Animal
        tameAnimal("tame_wolf") {
            entity {
                type(EntityTypes.WOLF)
            }
        }

        // Target Hit
        targetHit("hit_target") {
            signalStrength = rangeOrInt(1..15)
            projectile {
                conditions {
                    entityProperties {
                        type(EntityTypes.ARROW)
                    }
                }
            }
        }

        // Thrown Item Picked Up By Entity
        thrownItemPickedUpByEntity("feed_animal") {
            entity {
                type(EntityTypes.COW)
            }
            item {
                item(Items.WHEAT)
            }
        }

        // Thrown Item Picked Up By Player
        thrownItemPickedUpByPlayer("catch_trident") {
            item {
                item(Items.TRIDENT)
            }
        }

        // Tick
        tick("game_tick") {
            conditions {
                timeCheck(6000..18000) // Daytime only
            }
        }

        // Used Ender Eye
        usedEnderEye("find_stronghold") {
            distance {
                horizontal(100f)
            }
        }

        // Used Totem
        usedTotem("save_life") {
            item {
                item(Items.TOTEM_OF_UNDYING)
            }
        }

        // Using Item
        usingItem("shield_block") {
            item {
                items = listOf(Items.SHIELD)
            }
        }

        // Villager Trade
        villagerTrade("trade") {
            item {
                item(Items.EMERALD)
            }
            villager {
                conditions {
                    entityProperties {
                        team = "villager"
                    }
                }
            }
        }

        // Voluntary Exile
        voluntaryExile("raid_village") {
            conditions {
                location {
                    dimension = Dimensions.OVERWORLD
                }
            }
        }
    }
}

Each example shows the basic usage of the trigger with some common properties and conditions. You can combine these with additional conditions and requirements as needed for your advancement.

Requirements

Requirements define which criteria must be completed to earn the advancement:

advancement("my_advancement") {
    // Single requirement
    requirements("criterion1")

    // Multiple requirements (AND)
    requirements(listOf("criterion1", "criterion2"))

    // Multiple requirement groups (OR between groups)
    requirements(
        listOf("criterion1", "criterion2"),
        listOf("criterion3")
    )
}

Rewards

You can define rewards for completing the advancement:

advancement("my_advancement") {
    rewards {
        experience = 10
        function = function("reward_function") {
            say("Congratulations!")
        }
        loots(LootTables.Chests.IGLOO_CHEST)
        recipes(Recipes.SOME_RECIPE)
    }
}

• experience: The amount of experience to give the player.
• function: A function to run when the advancement is completed.
• loots: A list of loot tables to give the player.
• recipes: A list of recipes to unlock for the player.

Telemetry

You can enable or disable telemetry for the advancement, defaults to false:

advancement("my_advancement") {
    sendsTelemetryEvent = true
}

Complete Example

Here's a complete example combining various features:

advancement("complex_advancement") {
    display(Items.DIAMOND_SWORD, "Master Craftsman", "Craft a special item") {
        frame = AdvancementFrameType.CHALLENGE
        announceToChat = true
    }

    parent = Advancements.Story.ROOT

    criteria {
        crafterRecipeCrafted("craft_special", Recipes.SPECIAL_RECIPE) {
            ingredient(Items.DIAMOND) {
                components {
                    damage(0)
                }
            }
        }
    }

    requirements("craft_special")

    rewards {
        experience = 100
        function = function("reward") {
            say("Congratulations on becoming a Master Craftsman!")
        }
        loots(LootTables.Chests.IGLOO_CHEST)
    }

    sendsTelemetryEvent = false
}