Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Named hook points

Implement catalog hooks as methods of mod_api::Hooks.

For function-slot listeners, declare [[inject]] with id, a target in at, kind ("head", "return" or "replace"), and a crate-root listener in with. The optional hash pins the function fingerprint; when you omit it, the build uses the pinned game's catalog. The schema rejects hook and hook_version. See Injections.

Native rendering callbacks such as horizon_mod_render::render::world_drawn, hand_drawn and world_views use a HEAD mixin. The launcher compiles the patched function against the prebuilt game. Callbacks borrow the frame's GPU resources; world_views supplies additional camera views. The renderer refuses invalid, duplicate and oversized view requests by name, as push returns them.

Use the geometry types re-exported as horizon_mod_render::render::{Vertex, EntitySpan}. Implement the render_needs callback to set RenderNeeds requests for world depth and entity geometry; these requests feed the engine's frame requirements so it retains the resources your drawing callbacks borrow.

Leaving a bed

player_bed_leave is a server-side, listen-only notice. It runs before the sleeping position and pose are cleared, so a listener can still read the player as sleeping at pos; it cannot cancel the wake. For example, a listener recording why a player left a bed should retain both flags rather than treating every wake as a manual leave:

Wake reason(wake_immediately, update_level)
Morning after skipping the night(false, false)
Explicit leave or bed-rule refusal(false, true)
Generic stop-sleeping, missing bed or death(true, true)

wake_immediately resets the sleep counter to 0 when true, skipping the fade-out; false sets it to 100 for the normal fade-out. update_level is false for the morning wake because the sleeping list has already been handled, and true for the individual wakes above. The same pairs apply to the acting player and stored guests. Waking that same player again inside the callback does not emit a second notice.

See the generated API reference and the hook's caller notes.

Physical movement decisions

entity_move runs on the server before one physical Entity.move invocation, including its no-physics and stuck-multiplier handling. This hook receives the loop context, not a Host: it decides only the movement delta. MoveCause distinguishes self movement, player packets, pistons, shulker boxes and shulkers; boats and minecarts use self movement.

A replacement must have finite components, each within ±64 blocks. Invalid output is refused whole, retaining the requested delta rather than clamping it. Cancellation skips the invocation: no position, velocity, collision-flag or fall change, and no displacement notice. An overridden player or vehicle packet move sends a correction even below the normal distance threshold, for creative players and from obstructed starts too. A replacement equal to the request retains the normal vanilla distance rules.

A native panic or trapped/refused wasm listener restores the originally requested delta, not an earlier listener's replacement. Later listeners do not run on that invocation, and the failed listener is disabled for this hook for the session; its other hooks remain enabled. Native and wasm listeners share this contract.

Teleport hooks

ender_pearl_teleport covers player-owned and mob-owned pearls. Its owner is an EntityRef; listeners can cancel or redirect target, and read what the pearl hit (hit_entity, or hit_block and hit_face, and the point hit_at). Player owners retain the acting-player context and mutable fall damage. Mob owners take no pearl damage and make no endermite roll. Pearl placement does not emit the command-only entity_teleport notification. The pearl is consumed even when teleportation is canceled.

item_consumption_teleport covers players and foxes with the random-teleport consume effect. Its consumer is a LivingRef, and consumed is the stack captured before use, including count and components. Cancellation ends further teleport attempts, not consumption. Fox callbacks run before that fox's living AI/movement and before the next mob ticks, with the full server host. Listener changes to an actor's item, position or eligibility survive rather than being overwritten by a stale teleport decision.