Named hook points

Implement catalog hooks as methods of mod_api::Hooks.

From Sunrise's modding bookead8a1e

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 sunrise_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 sunrise_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.

A mod moves an entity through the same moment with EntityRef::move_by(host, delta, cause) (Entity.move(cause, delta), server only): the collision scan stops it at blocks, the world border and entities, it steps up, and its ground flag follows; its velocity is left as it is, and it is no teleport. The entity_move hook fires once for it with cause, and a cancelled move returns [0.0; 3]. It returns how far the entity moved, and None for a stale handle, on a client, for a player (teleport it), for an entity outside the game's entity walk (a display, a painting, a frame, an End crystal, a dragon part) and for a delta that is not finite or beyond 64 blocks on an axis. Fall damage and block effects stay with the entity's tick.

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. A consumed stack the API can't carry, such as a saved item whose id isn't registered, isn't heard: the listeners aren't called and the teleport goes on as vanilla's.

Item use lifecycle (native and wasm)

living_entity_use_item_tick runs after the may-still-use check. Its duration replaces the remaining-ticks counter. Next come per-tick effects only above zero, the decrement, and server completion at zero or below.

On the server, canceling Tick or setting duration to zero or below finishes the use: food is eaten or a potion applied, Finish fires, and use state clears. Setting one runs the effects and finishes in that same tick. This never calls release-using, so a bow fires nothing. A use-on-release item such as a crossbow does not finish here: its counter goes negative until release.

On a client, cancellation sets the counter to -1 before decrement and skips effects. The negative countdown continues; the use remains active until server completion or release, so releasing still notifies the server.

The neighbouring events differ: canceling Start prevents the use beginning, but duration zero does begin it. Canceling Stop skips only release-using, not clearing the use. Finish is not cancellable; its result stack can be replaced.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.