JSPrismarine

API reference / @jsprismarine/advancements / AdvancementEngine

Class: AdvancementEngine ​

Defined in: engine.ts:62

The advancement engine: it holds the loaded tree, routes game events to the criteria listening for them, records progress against a player's store, and fires rewards when an advancement completes.

Criteria are indexed by trigger, and the four triggers whose event names a registry element are indexed by that element as well, so raising an event touches the criteria that could match it rather than all of them.

Constructors ​

Constructor ​

new AdvancementEngine(options?): AdvancementEngine

Defined in: engine.ts:72

Parameters ​

options? ​

AdvancementEngineOptions = {}

Returns ​

AdvancementEngine

Accessors ​

diagnostics ​

Get Signature ​

get diagnostics(): DiagnosticCollector

Defined in: engine.ts:83

Diagnostics from loading and from every evaluation since.

Returns ​

DiagnosticCollector

tree ​

Get Signature ​

get tree(): AdvancementTree

Defined in: engine.ts:78

The parent tree of everything loaded, rebuilt by each load.

Returns ​

AdvancementTree

Methods ​

award() ​

award(id, progress, player, at?): boolean

Defined in: engine.ts:180

Completes every criterion of one advancement, the way /advancement grant does.

Parameters ​

id ​

string

progress ​

PlayerAdvancements

player ​

EntityView

at? ​

string

Returns ​

boolean

Whether this call completed the advancement.

get() ​

get(id): ParsedAdvancement | undefined

Defined in: engine.ts:88

One loaded advancement by namespaced id.

Parameters ​

id ​

string

Returns ​

ParsedAdvancement | undefined

listensFor() ​

listensFor(trigger): boolean

Defined in: engine.ts:103

Whether any loaded criterion is listening for one trigger.

For the call site rather than for this class: building a trigger's event means reading a player's inventory, equipment, position and attributes, and that work is wasted when the loaded set has no criterion for the trigger. A stack with no advancements in it answers false to everything.

Parameters ​

trigger ​

"villager_trade" | "enchanted_item" | "impossible" | "player_killed_entity" | "entity_killed_player" | "enter_block" | "inventory_changed" | "recipe_unlocked" | "player_hurt_entity" | "entity_hurt_player" | "filled_bucket" | "brewed_potion" | "construct_beacon" | "used_ender_eye" | "summoned_entity" | "bred_animals" | "location" | "slept_in_bed" | "cured_zombie_villager" | "item_durability_changed" | "levitation" | "changed_dimension" | "tick" | "tame_animal" | "placed_block" | "consume_item" | "effects_changed" | "used_totem" | "nether_travel" | "fishing_rod_hooked" | "channeled_lightning" | "shot_crossbow" | "spear_mobs" | "killed_by_arrow" | "hero_of_the_village" | "voluntary_exile" | "slide_down_block" | "bee_nest_destroyed" | "target_hit" | "item_used_on_block" | "default_block_use" | "any_block_use" | "player_generates_container_loot" | "thrown_item_picked_up_by_entity" | "thrown_item_picked_up_by_player" | "player_interacted_with_entity" | "player_sheared_equipment" | "started_riding" | "lightning_strike" | "using_item" | "fall_from_height" | "ride_entity_in_lava" | "kill_mob_near_sculk_catalyst" | "allay_drop_item_on_block" | "avoid_vibration" | "recipe_crafted" | "crafter_recipe_crafted" | "fall_after_explosion"

The trigger name a caller is about to raise.

Returns ​

boolean

Whether raising it could match anything.

load() ​

load(advancements): void

Defined in: engine.ts:111

Replaces everything loaded with a new set, rebuilds the parent tree and rebuilds the dispatch index. Tree faults go to the engine's collector.

Parameters ​

advancements ​

Iterable<ParsedAdvancement>

Returns ​

void

raise() ​

raise<K>(trigger, event, progress, at?): readonly string[]

Defined in: engine.ts:144

Routes one game event to the criteria listening for its trigger and records every criterion it satisfies.

Type Parameters ​

K ​

K extends "villager_trade" | "enchanted_item" | "impossible" | "player_killed_entity" | "entity_killed_player" | "enter_block" | "inventory_changed" | "recipe_unlocked" | "player_hurt_entity" | "entity_hurt_player" | "filled_bucket" | "brewed_potion" | "construct_beacon" | "used_ender_eye" | "summoned_entity" | "bred_animals" | "location" | "slept_in_bed" | "cured_zombie_villager" | "item_durability_changed" | "levitation" | "changed_dimension" | "tick" | "tame_animal" | "placed_block" | "consume_item" | "effects_changed" | "used_totem" | "nether_travel" | "fishing_rod_hooked" | "channeled_lightning" | "shot_crossbow" | "spear_mobs" | "killed_by_arrow" | "hero_of_the_village" | "voluntary_exile" | "slide_down_block" | "bee_nest_destroyed" | "target_hit" | "item_used_on_block" | "default_block_use" | "any_block_use" | "player_generates_container_loot" | "thrown_item_picked_up_by_entity" | "thrown_item_picked_up_by_player" | "player_interacted_with_entity" | "player_sheared_equipment" | "started_riding" | "lightning_strike" | "using_item" | "fall_from_height" | "ride_entity_in_lava" | "kill_mob_near_sculk_catalyst" | "allay_drop_item_on_block" | "avoid_vibration" | "recipe_crafted" | "crafter_recipe_crafted" | "fall_after_explosion"

Parameters ​

trigger ​

K

event ​

TriggerEvents[K]

progress ​

PlayerAdvancements

The player's store, updated in place.

at? ​

string = ...

ISO-8601 instant to record on each criterion; defaults to now.

Returns ​

readonly string[]

Namespaced ids of the advancements this event completed, in the order they completed. An advancement already done completes no second time and fires no second reward.