HookSystem

HookSystem

Lifecycle hook system. Multiple bindings per hook name, each identified by a unique string ID. Supports optional per-binding filter functions.

Constructor

import { HookSystem, HOOKS } from './src/hook.js';

const hooks = new HookSystem();
hooks.setDebug(true);

---

Predefined hooks

HOOKS is a frozen array of 27 predefined lifecycle hook names:

on_break_block       on_placed_block      on_eat
on_player_death      on_player_join       on_player_respawn
on_entity_kill       on_fish_caught       on_trade
on_item_use          on_dimension_change  on_sneak_start
on_sneak_stop        on_sprint_start      on_sprint_stop
on_jump              on_elytra_start      on_elytra_stop
on_interact_anvil    on_interact_shulker_box  on_level_up
on_target_hit        on_open_chest        on_using_item
on_killed_by_arrow   on_hero_of_the_village   on_drop

You are not limited to these — any string is a valid hook name.

---

Binding

hooks.bind(hookName, id, fn, { filter });

Parameter	Type	Description
hookName	string	Hook to bind to
id	string	Unique binding ID — re-binding the same ID replaces the old entry
fn	function	Handler called with ctx
filter	function | null	Optional — if provided, handler is skipped when filter(ctx) is false

hooks.bind('on_player_join', 'my_plugin', (ctx) => {
  console.log('joined:', ctx.name);
});

// With filter — only fires for ops
hooks.bind('on_player_join', 'op_only', (ctx) => {
  console.log('op joined:', ctx.name);
}, { filter: (ctx) => ctx.isOp });

---

Unbinding

hooks.unbind('my_plugin');             // removes binding ID from all hooks
hooks.unbind('my_plugin', 'on_jump'); // removes only from specific hook
hooks.unbindAll('on_player_join');    // removes all bindings for a hook

---

Dispatching

The host calls dispatch() when a lifecycle event occurs:

hooks.dispatch('on_player_join', { name: 'Alice', isOp: false });
// → number of handlers actually called

Errors thrown inside handlers are caught and logged. Other bindings are not affected.

---

Introspection

hooks.list('on_player_join'); // → ['my_plugin', 'op_only']
hooks.list();                 // → [{ hook, id }, ...]