Modding Horizon

Horizon is Minecraft: Java Edition 26.3 rewritten in Rust. A Horizon mod is one .hmod package. It is one of:

Native and WebAssembly mods are written against one API, mod_api, and share one dependency model: the only difference between them is the build target.

How this book is organised

The book follows Diátaxis: each page is one of four kinds, and says so by where it lives: Start (a tutorial), Concepts (explanation), How-to and Reference. See where each doc lives.

An agents page and llms.txt give a coding agent the rules in one place.

Where things are

• The API reference is cargo doc -p horizon-mod-api: every hook, event and Host method, with its side, its NeoForge 26.3 counterpart and its cancel contract.
• The end-to-end example mod is horizon-machine-sample.
• Design and milestones: #26 and #44.

Your first native mod

A native mod is one flat Rust project that implements mod_api::Hooks, built by the launcher into the game it runs in. You need the launcher and a Horizon commit to build against.

1. Make the project:

   cargo horizon-mod new my_mod --template native
   

   It writes horizon-mod.toml (the manifest, with the exact build pins under [native]), Cargo.toml and src/lib.rs, which implements one hook.

2. Look at the hook. Each method of Hooks is a hook point; implement the ones the mod needs. Every impl Hooks carries #[mod_api::horizon_mod], which subscribes the mod to just the methods in that block:

   #[mod_api::horizon_mod]

impl Hooks for Mod { fn server_tick(&self, host: &mut dyn ServerHost, : &mut ServerTickEvent<'>) { let _ = count(host); } }

3. Build and run it in the launcher: `horizon-launcher native-build . --instance <instance> --trust-native-code`.
Add `--profile developer` while developing for an unoptimized game crate. The choice is remembered for that instance.

Next: [Native mods](../how-to/native-mods.md) for what the launcher does, [Trait mods](../concepts/trait-mods.md)
for Parts and attachments, and [Injections](../injections.md) for the moment no hook covers.

Installing and using mods

Two kinds of mod run in Horizon:

Fabric and NeoForge jars do not run as they are: they target Minecraft's Java runtime, and Horizon has none. What carries over is the data and assets inside a jar (modpacks.md).

Mods are off by default. A fresh install has no horizon-mods folder and plays exactly like vanilla 26.3.

Playing with mods

1. Install a mod from the launcher's Mods page (mod-browser.md) or the game's Options > Mods > Browse Mods (content-only packages, checked against the same registry), or put its files by hand in the game folder (the one holding options.txt): a content mod's .hmod (or a folder holding horizon-mod.toml) in horizon-mods/. Native mods go in horizon-native-mods/, and the launcher builds them (native mods).
2. The Mods button on the title screen (also Options > Mods) opens the mod list, laid out as NeoForge's: Minecraft and Horizon first, then each installed mod with its icon, name and version. Search the list, sort it A-Z or Z-A, and pick a mod to read its id, version, license, authors, credits and description. Homepage and Issues open the mod's links after a confirmation, and Config opens the settings page of a native mod that has one. The screen has no switch. A mod starts off: the launcher (horizon-launcher mods enable <id>) or horizon-mods.txt (mod.<id>:true) turns it on, and a mod that is not on says so in the list.
3. A turned-on content mod with only assets and reloadable data (textures, models, sounds, languages, recipes, tags, loot, advancements and functions) is picked up live when a mod is installed from Browse Mods: the game reloads its resources, then its world's data as /reload does, including for LAN guests. Content that adds registry entries or changes world generation still needs a restart. Packages with jar layers also wait for a restart, because those layers may contain world generation. On another server all content waits: the server owns its data.
4. A mod that can't load shows why, in red, in its panel.

Two turned-on content mods never own the same namespace: the first by file name loads, and the other stays out with the reason in the log.

Benchmarks (--benchmark) never load mods.

Horizon's official mods

Horizon's own mods are native. They live in horizon-rust/horizon-mods under native/<name>/:

The game keeps the parts that must be fast, such as drawing the minimap's map, and a native mod picks the options (extras.md). Far View is not a mod any more: its distance and detail are Graphics > LOD Distance and Far Detail (graphics.md).

Wire types

Native and wasm mods share mod_api::wire::{Wire, Reader, Writer, WireError}. Derive mod_api::Wire explicitly on a type whose values cross a target boundary. The build never adds a derive. Types used only inside one target do not need it. Every field of a derived type must also implement Wire.

#![allow(unused)]
fn main() {
#[derive(mod_api::Wire)]
pub struct ChemicalAmount {
    pub chemical: String,
    pub amount: u64,
}
}

Records encode fields in declaration order. Enums encode a case index followed by its fields. Lengths and numbers are little-endian; collections are length-prefixed. Decoding returns WireError for invalid data rather than accepting an unknown tag, invalid UTF-8 or an unsupported length.

Nesting and stacks

Structural decoding and encoding allow 32 nested records, payload-carrying variants and Box/Arc values (MAX_DEPTH). Collection iteration, Option and tuples do not consume a level. The reader returns WireError::Depth before entering level 33; the writer records the same error. Always check Writer::error before sending its bytes. This is a transport budget for unbounded mod-defined trees, including ingredients, item places, loot vehicles and recipe slot displays.

Vanilla trees are not restricted by that structural budget: NBT Tag uses an explicit work stack with 512 nested containers; Text crosses as the existing validated flat TextForm table, preserving its 512 component-depth contract. These encodings are identical on native and wasm. Text's layout identity is the flat table's identity; mods must rebuild.

JSON-backed serde_json::Value, JSON maps and ModelPart also refuse beyond 32 JSON containers. Their encoders preflight the in-memory tree iteratively before serde recursion; their decoders scan the JSON's nesting outside quoted strings before parsing. A model part's JSON includes object, children-list and named-child-tuple containers, so one part can consume several JSON levels.

The smallest configured guest shadow stack is 256 KiB (horizon-mod-wasm's shared linker). Wasmtime also has its default 512 KiB native call-stack budget. Native decoding runs synchronously on the calling thread: world workers use Rust's normal spawned-thread stack (normally 2 MiB), while integrated server threads reserve at least 8 MiB. The depth regression tests use 128 KiB, leaving half the guest shadow stack for callers. An embedding that supplies smaller stacks or arbitrarily recursive handwritten Wire implementations must enforce its own stack contract; the reader cannot police code outside its codec.

Wire does not own a borrowed value's destructor. Constructing an arbitrarily deep Rust tree and then dropping it can still overflow a thread independently of Wire. Use explicit work stacks when disposing of hostile trees (discard_tag for NBT), and do not transfer arbitrarily deep owned Rust trees to an encoder. The source scanner tools/scan_recursive_wire.py and its classification test require review of every new recursive public vocabulary type.

Checked representations

Use #[wire(via = String)] (or another Wire type) when a checked constructor owns validation. Implement From<&YourType> for String and TryFrom<String> for YourType. The derive writes the representation and maps a failed conversion to WireError::Invalid. Its layout is the representation's layout.

Layout identity

Wire::layout computes an encoding identity recursively, including field names, case names and child layouts. It is a runtime method, not a constant, because recursive types need a visited-type stack. Container layout follows encoding: Vec<T> and VecDeque<T> agree, as do String and Box<str>; Box<T> is transparent. Changing a crossing field requires rebuilding dependents; the wire format has no compatibility versions or default fields.

cargo horizon-mod build writes layouts.json at the package root, mapping mod IDs to public type paths and their 16-digit hexadecimal layout identities. It includes the mod dependencies it compiled against. A cached host probe under target/horizon-mod/ computes these values, for both native and wasm builds. When there are no concrete crossing types, no probe is built and no file is written. Private types without a public path and uninstantiated generic declarations are not listed; a public re-export can give a private module's type a public path.

A mixed-target dependent with a different layout is refused naming the library and differing type. Even matching layouts do not enable mixed native and wasm dependencies yet: those edges are refused explicitly. See the extension design for the complete layout contract.

Hand-written implementations

The trait is unsealed. A hand-written implementation must supply put, take, MIN, and LAYOUT_SEED; compound encodings must override the hidden layout method to incorporate their children and handle recursive visits. Never use a constant leaf seed for a compound encoding: field changes must change its identity. The derive handles this bookkeeping automatically and is preferred.

A hand decoder owns tag validation and must use Reader::nested for recursive values. Reader checks byte bounds and UTF-8, but cannot enforce invariants that an implementation neglects. Keep validation at the checked constructor boundary.

Public declarations used in layout discovery must be unconditional. The layout probe refuses #[cfg] and #[cfg_attr] on public types, modules, and re-exports, naming the declaration. Keep target-specific implementation details private; publish an unconditional Wire representation.

Trait mods, Parts and attachments

Trait mods (draft)

cargo horizon-mod new <path> --template native pins an exact Horizon commit (the newest prebuilt game's, or --horizon <commit>'s; cargo horizon-mod update repins) and writes a flat project: horizon-mod.toml with [native], Cargo.toml, src/lib.rs, and empty assets/ and data/ directories. The template greets each player who joins. Build it with horizon-launcher native-build <path> --trust-native-code; cargo horizon-mod build packages the same project into a .hmod without compiling it (the manifest).

The root Rust package depends on horizon-mod-api (lib mod_api), never on the game. Its root src/lib.rs marks one impl Hooks with the attribute:

use mod_api::{self, Hooks};

#[derive(Default)]
struct Mod;

#[mod_api::horizon_mod]
impl Hooks for Mod {
    // Implement the hooks this mod needs.
}

The attribute generates the hooks() factory and derives optional hook subscriptions from this impl. The mod type implements Default; do not write a second factory. Keep the marked impl at the crate root. Rustc's "cannot find function hooks" at the launcher's generated call means the marked implementation is not at the crate root. The launcher links this package into a generated game executable and calls the generated factory in dependency order (a mod after the mods it depends on, else in bundle order). A mod with no raw injections skips horizon-mixins; typed hooks need no injection declarations. Dependencies follow the pinned Horizon Cargo.lock rules in The mod's crate.

Dependencies between trait mods

A mod can publish functions and statics from its root crate for another mod to call. Declare dependencies in horizon-mod.toml, not Cargo.toml:

[dependencies]
base_mod = "^1"
extra_mod = { version = "^2", optional = true }

Requirements use Cargo semver syntax and are checked against each installed mod's horizon-mod.toml version, not its Cargo package version. Content-only mods use these declarations to validate their requirements and load their layers after dependencies. Code dependencies additionally require API packages for the dependent and every installed dependency. Missing required dependencies, incompatible versions and cycles stop the build with the mods named. An absent optional dependency is permitted; an installed optional dependency must match its requirement.

The launcher adds a path dependency using the mod ID as the Cargo alias and the target's actual Cargo package name. Optional dependencies also get a Cargo feature named exactly as their mod ID, enabled only when that mod is installed. Guard calls with if_installed!, which builds the block only with that feature and runs it only when the mod is installed, so the same source works when built to mod.wasm, where the library is linked at load and an absent one's functions trap:

mod_api::if_installed!(host, extra_mod, {
    extra_mod::register_extra(host);
});

Do not define these dependencies or features yourself in Cargo.toml. Public statics must use appropriate synchronization for shared and reentrant hooks; private state in another mod's hook object is not exposed.

Trait dispatch follows dependency order, with ties kept in bundle order. Mixin injection order remains horizon-mixins' priority, mod ID, then injection ID for source splices. Function-slot listeners instead use descending priority, dependency/registration order, then injection ID within a mod; call-site listeners retain mod-ID tie ordering.

Load phases and access

Native and wasm hooks share the installed dependency-ordered mod slice, including registration, config loading and reload-listener registration. The shared resolver keeps bundle-order ties, checks present optional dependencies too, and refuses cycles for both build targets. Content-only packages stay after code in the loaded-mod inventory; listener-specific edges still use ReloadOrder.

Each owning thread progresses through Packages → Registration → Setup → Config → World.

RegistrationContext::instance_dir() reads the instance directory captured before registration begins, as an InstanceDirectory: Unix(Vec<u8>) preserves raw Unix path bytes, and Windows(Vec<u16>) preserves Windows UTF-16 code units, including unpaired surrogates. Never convert Unix bytes with a lossy UTF-8 conversion when constructing a native filesystem path. Wasm receives the identical host-encoded value through Wire as data only; this does not grant filesystem access. A context with no engine snapshot returns RegistrationReadError::Unavailable.

Registration runs once: register, component_types, blocks, items and standalone_models receive only RegistrationContext. Its mods(), registry(name) and setting(mod_id, key) read one view captured before the first of them runs, so every registration step sees the same values whatever the dispatch order: the loaded packages, the built-in registries as registries.json lists them (not what mods declare during registration) and the settings on disk at that moment. A mod validates the keys it declares against them from Hooks::register; a name that is not a namespaced identifier, an unknown registry, an empty or path-like setting key, a package that is not loaded, or a context the engine gave no data returns a RegistrationReadError. Client setup runs once after the initial asset apply. The window's Client/Common configs load once immediately after client setup and before title, connection, input, render or ordinary tick callbacks. This includes pack-error recovery: the failed selection is cleared and saved during initialization, but its options screen opens only after Config completes. A title-screen callback is already in World: world-handle constructors can return None, rather than being forbidden in Setup. A dedicated server loads Common once before its first world; Server configs load and unload per world. A second world does not repeat registration or client setup. Config loading can read settings and use the existing scoped ConfigFiles service to read or save its own config files. World handles, transactions and other game operations panic with Config in the diagnostic. Config file polling is not a phase transition, and Server config unloading leaves the World phase.

Every data or asset reload enters Reloading, including listener registration, prepare, apply and the reload completion notice. Initial loads can nest in Setup; runtime reloads nest in World. Returning, including after a failed prepare, restores the entering phase. Published asset/data queries are classified in the catalog (resource_read), not granted by helper-name exceptions. They read the currently published generation, not pending prepare output: completion callbacks can refresh sprite and recipe caches after apply, including on first world open, without gaining world handles or transactions. Their rustdoc names their load-phase availability. Server listener registration retains &dyn Host, restricted to these published facts, registry facts, settings and mod-list queries; callbacks already taking DataLoadContext keep that context. Neither permits opening a world handle or transaction. The first client registration and prepare run on the loader thread; later registration runs on the render thread, prepare on its worker, and apply on the owning game thread. Startup's empty client Host is not an extra permission.

DataLoadOrigin and LoopSide are API-owned enums, not engine exports. Load and loop callbacks read frozen registry and settings metadata through DataLoadContext and LoopContext. The engine supplies borrowed LoadReader and LoopReader implementations; the API's owning views contain no engine types and do not copy or rescan the resource snapshot. Mod listeners keep using the context traits, with the same origin, side and registry ordering on both targets. The reader adapters themselves are native host implementation details, not wasm resources.

The game alone advances phases. An illegal or wrong-thread advance is refused before dispatch; a forbidden mod call panics naming the phase, rather than returning a Result a listener could ignore. There is no separate common-setup, load-complete or intermod event: registration and the first server reload cover common setup, client setup is client_setup, dedicated setup is server_about_to_start, and dependencies express intermod ordering. Load complete is the edge after initial Config and before server_about_to_start, not a hook.

Settings snapshots accept only regular UTF-8 files, without following file or package-directory symlinks (including internal links). Invalid UTF-8, special files and refused entries are absent, not errors. Each file is limited to 64 KiB before trimming, each mod to 1,024 captured keys, and the whole snapshot to 16 MiB before trimming. Over-limit keys are omitted in sorted package-id and key-name order. Enumeration is limited to 4,096 names per package; packages exceeding that budget are omitted entirely rather than retaining an unstable enumeration prefix. One warning per refusal class is emitted per snapshot. These generous limits cover the small scalar setting values used by the settings API; they do not apply to mod data files.

The generated executable uses the installed game's crates/horizon-client/src/native_main.rs.template. The launcher supplies only ordered literal mod IDs and hook factory paths. The template owns entry construction, the allocator and the canonical game identity. Source without this template is refused before staging trait mods: update the game first.

A mod whose bootstrap cannot complete should call cx.refuse("reason") inside Hooks::register, then return. This refuses only the calling mod's registration: there is no mod ID argument. Its declarations from that registration (before or after the call) are discarded. Later declarations do not add secondary validation errors, and another mod's declarations are unchanged. Native and wasm report the same diagnostic through the normal registration error path. This does not panic or exit the process. The first reason wins, including an empty reason. Reasons are preserved verbatim up to 4096 UTF-8 bytes; longer strings are truncated at the last character boundary within that limit.

A panic in a trait mod's hook adds in native mod <id>, hook <hook> to the panic's message, in the crash report and in the server thread's log line, with the horizon-mod.toml id. Each entry passed to entry::main_with must bind its id and hooks together: ModEntry::new("example", example::hooks()). The ordered list is Mods = Arc<[ModEntry]>; there is no separate naming step or unnamed entry. Before installation, mod_api::mods() still returns an empty list. Parts retain their registering mod's id for startup errors and hook panics. The game stops. A point listener's panic names its mod and method; render hooks are not named yet.

A native runtime that hosts converted packages (Portizon's wasm packages, a Java interpreter's jars) declares the packages it loaded with mod_api::content::crash::ConvertedPackages::new(runtime_id, ids) and marks a guest call with mod_api::content::crash::ConvertedPackage::enter(export, site). The scope nests, restores the previous one on return and while a panic unwinds, and adds in converted package <id>, export <export>, call site <site> below the runtime's in native mod line in the report. A package id the runtime did not declare is refused, as is a scope entered while another mod's call is the current one, so guest code cannot impersonate a mod the runtime did not load.

The guard is thread-affine (not Send or Sync), and attribution ends when the native frame that entered it exits, even if the converted guard is retained. A nested native frame hides the outer frame's package until it returns. Worker threads have no scope unless the runtime enters a native call and package scope there. Registry ids are stored, not interned: entering a package clones an owned id on every call (borrowed static ids do not allocate).

A code mod may listen at the game's injection points as a rare escape hatch, through a crate-root function named by [[inject]].with, taking a mod_points record; the form and its limits are in Injections.

A linked trait mod implements mod_api::Hooks. A hook function is not an injection point, so [[inject]] never runs inside a hook's dispatch; a head injection that cancels the game function calling a hook keeps the hook from firing at all. A claimed cancellation reaches only trait listeners that receive cancelled events. Otherwise, trait mods run by priority, then in dependency order. Once a mod cancels, later mods are skipped unless they receive cancelled events. For replacement hooks, the first Some wins. Collection hooks call every mod. Receiverless hooks have no Host.

To save from inside a hook, use level.request_save(host) so the save runs at the next settled start-of-tick boundary. A synchronous save-all while an entity pass or held-out row is borrowed fails with vanilla's commands.save.failed feedback and a failed command result, without saving.

To emit a vibration-producing game event, use level.game_event(host, event, at, context). GameEventContext carries an optional source entity and affected block state; see game events with context for listener semantics and refusals.

#[listener] on a hook method sets both, as NeoForge's EventPriority and receiveCanceled do. Two mods, each its own crate:

#![allow(unused)]
fn main() {
#[mod_api::horizon_mod]
impl Hooks for Protection {
    // Runs before mods at the default priority, 0; higher runs first.
    #[listener(priority = 100)]
    fn break_block(&self, host: &mut dyn ServerHost, event: &mut BreakBlockEvent<'_>) -> Flow {
        if self.protected(host, event.pos) { Flow::Cancel } else { Flow::Continue }
    }
}

#[mod_api::horizon_mod]
impl Hooks for Override {
    // Still told after a cancel, and may undo it.
    #[listener(priority = -100, receive_cancelled)]
    fn break_block(&self, host: &mut dyn ServerHost, event: &mut BreakBlockEvent<'_>) -> Flow {
        if event.cancelled && self.allowed(host, event.pos) {
            event.cancelled = false;
        }
        Flow::Continue
    }
}
}

priority is an i32, 0 when omitted; mods of equal priority keep dependency order, as [[inject]] priorities do (Injections). Each hook's order is fixed once, when the mods are installed. Every cancellable hook's event has a cancelled field: a mod without receive_cancelled always sees false, since it is not called once the event is cancelled. A mod that receives cancelled events and sets it back to false lets the game's behaviour run, and the mods after it are told again. An event the game hands over already cancelled reaches only mods that receive cancelled events. receive_cancelled on a hook without a cancel does not compile, and #[listener] is for a trait mod's hooks only: a part is called for its own thing, in no order.

Native and wasm trait mods use the same listener ordering and cancellation rules. Wasm subscription records carry the hook name, signed priority, and receive-cancelled flag through the shared-memory Wire boundary at load time. The event's cancelled field crosses with its other writable fields. No component-model adapter is involved.

Each hook method takes its host, where it has one, and one event:

#![allow(unused)]
fn main() {
fn living_incoming_damage(
    &self,
    _level: &mut dyn LevelRandomHost,
    event: &mut LivingIncomingDamageEvent<'_>,
) -> Flow {
    if event.kind == "minecraft:pig" {
        let halved = event.container.new_damage() * 0.5;
        event.container.set_new_damage(halved);
    }
    Flow::Continue
}
}

The event is a generated struct named after the catalog hook, in CamelCase plus Event, with the hook point's arguments as public fields: values as values and borrowed ones as references (event.kind). A number or bool a mod may change is a plain field, written back once every mod has run, even after a Cancel; anything else a mod may change, a game struct or a list, is a &mut field. A cancellation or replacement is still the return value; a collection hook's list is a field (event.lines). One event goes through every mod, so each sees the changes before it. Because no mod can build or match the whole struct, a later version can add a field without breaking any mod, as NeoForge's event objects do; the cost is that a mod's own tests drive a hook through its dispatch function (Testing a trait mod).

Hook methods take &self and require Send + Sync. The process-wide mod list is installed once, like mixin module statics. One mod instance serves both the window's game and the server-thread game. A hook can also fire again inside the same mod: for example, LevelRef::set_block fires block_changed. Mods keep mutable state with interior mutability so these calls can share the instance safely. Data-load hooks can run on any loading thread; item default changes must be identical on every side.

The trait has every hook declared under crates/horizon-mod-vocab/src/hooks/ (Adding a hook). Level hooks use access-specific hosts rather than Host. LevelHost provides block_state through LevelAccess::block_state, client-side detection and state_with_property. state_string(state) serializes the full name and properties, or returns None for an unknown state; min_y() and height() read the level's build range. It also reads light and loaded state, through the game's own queries: brightness(LightLayer::Block | Sky, pos) (getBrightness, the stored 0 to 15), raw_brightness(pos, sky_darken) (getRawBrightness, which CropBlock.randomTick asks with 0) and is_loaded(pos) (Level.isLoaded: inside the build height and in a loaded chunk), is_raining_at(pos) (Level.isRainingAt, false where pos is not loaded) and enabled_features() (LevelReader.enabledFeatures, a borrowed FeatureFlags<'_>). Neither allocates. None of them loads a chunk. Light above the build height reads as full sky and below it as none, and a chunk that isn't loaded reads as the game's query does (full sky, no block light), so check is_loaded first. It also answers tag and fluid questions without a Host: block_in_tag(block_key, tag), fluid_state(pos) (getFluidState, None where the block read is), state_fluid_state(state) and fluid_in_tag(fluid_name, tag). Fluid reads return FluidState with a FluidKey, amount, falling flag and engine-derived source flag; is_empty() and is_source() report those states without a registry lookup. block_state_id(name) parses a block and properties, and block_state_default(block) gives a block's default state, as on Host; both return None for invalid input or unavailable context. Tag reads are None when authoritative tags are unavailable, including on a client before its server's tags are applied. For item membership and member lists, use Host::tags(): resolve a TagKey with Tags::key, then call Tags::is_in_tag, Tags::items or Tags::fluids. Membership reads return None on clients until server-sent tags are applied, which tags_updated announces; they never substitute local resource-pack tags. LevelHost has no random, by design: a draw from a read-only hook inside a level write would shift the level's random sequence away from vanilla's order. A hook that may draw is given a LevelRandomHost. LevelRandomHost provides vanilla's Level.random so mod draws come in vanilla's order. LevelTicksHost adds scheduling through native_schedule_block_tick and native_schedule_fluid_tick, while LevelWriteHost adds random access, set_block, set_block_property, native_play_sound and native_send_particles and native_level_event (levelEvent, queued in order with the write's own events). set_block(pos, state, flags) is Level.setBlock on a whole state, as LevelRef::set_block takes it: it removes the old block's block entity and creates the new block's in the write (LevelChunk.setBlockState), runs the neighbour and shape updates flags ask for, and queues the write's level events in order. A mod block entity it creates starts with the data the block_entity hook gives, which is fired in the write and receives the level (LevelSide, read-only: vanilla's newBlockEntity gets no level), as the Host's native_set_block fires it. It returns true when the block changed, and false off an authoritative server, for a position that is not loaded or outside the build height, an invalid state, or the state the block already has. It never loads a chunk. The game owns the tick queue; mods do not pass it back to these helpers. Frame drawing through DrawContext, BlockEntityDrawContext and WorldDrawContext stays in mod_api. Raw GPU access is native-only, unstable and outside that API, in mod_render::render (horizon-mod-render). Register its listed frame functions through [[inject]] with access = "internals" and kind = "head"; the ordinary listener registry owns ordering and disabling. render_needs collects requests; world_drawn runs before the hand and HUD, and hand_drawn runs after the hand, on the render thread.

The typed API from mixin code

An [[inject]] listener can use the typed API: an API point's listener gets the side's Host and calls attachments and handles through it. The worked examples, and which shape to choose, are in Injections; each mixin injector's form is in From mixins and legacy kinds.

A catalog hook's trait method, event and return make up its hook_version contract (Named hook points). These per-hook contract versions are catalog metadata, not minimum game versions. Catalog hooks, Host calls and internals [[inject]] declarations all build against the game's exact source revision. Rebuild the mod when that contract changes.

Every impl Hooks must have #[mod_api::horizon_mod]. The attribute derives subscriptions from the methods implemented in that block, so dispatch knows them at installation.

Parts

A part is code a trait mod attaches to one block, block entity, item or mod menu type, its own or vanilla's (the spec). A mod attaches its parts once, at startup, in Hooks::register. Each part trait implementation must have #[mod_api::horizon_part]; the attribute subscribes it only to the methods it implements. A BlockEntityPart also needs a separately annotated BlockPart implementation:

#![allow(unused)]
fn main() {
struct Gauge;
#[mod_api::horizon_part]
impl BlockPart for Gauge {
    fn has_analog_output(&self, _: &dyn LevelHost, event: &mut HasAnalogOutputEvent) {
        event.output = true;
    }
    fn analog_output(&self, _: &dyn LevelHost, event: &mut AnalogOutputEvent) {
        event.output = 15;
    }
}

#[mod_api::horizon_mod]
impl Hooks for MyMod {
    fn register(&self, r: &mut dyn Registrar, _: &RegistrationContext) {
        let stone = r.block_key("minecraft:stone");
        r.block_part(stone, Gauge);
    }
}
}

On r: &mut dyn Registrar, r.block_key(id) and r.effect_key(id) request registry entries, not new content. Registrar is the generated union of the kind-local registration traits (such as BlocksRegistrar and EffectsRegistrar); mod registration hooks and the horizon-machine-sample continue to use dyn Registrar. Each kind owns its declarations and implementation in parts/<kind>.rs; the union and WebAssembly bindings discover those traits without a shared method list. The capability-provider lookup union is assembled the same way. Declare them in register, retain the returned BlockKey or EffectKey in the mod or Part, and reuse them for registry operations. Requests are canonicalized (a bare id uses minecraft:), deduplicated across mods and checked after every mod's content is known. An unknown entry refuses the load with the requesting mod and canonical id, even if the key was never attached to a Part. A later mod may supply the requested entry.

The completed block identity table includes every vanilla and mod block, even blocks no mod requested. Completion preserves requested slots and appends the remaining canonical names in sorted order. Names belong to the installed mod registry; world load and reload prepare a separate numeric mapping for every retained key before publishing it. A missing requested block refuses completion without publishing a partial table. Immutable block definitions (property names, legal values, state combinations and defaults) are published with those names before mesh tables are constructed. Workers share read-only definitions; property reads allocate nothing. Pack reload does not mutate definitions or identities. The world's numeric mappings and tag membership remain separate reloadable data.

Metadata contexts are read-only and borrow the same table on the host and on workers. Wire transport records are internal, not saved block values. Persist canonical identifiers and property strings rather than slots or state ordinals.

BlockState is a small owned value with private fields, not a tint-specific snapshot or an engine numeric ID. state.block() reads its BlockKey; state.ordinal() reads its local ordinal. Property operations take explicit metadata: retain let metadata = host.block_states() and call state.property(&metadata, "facing") or state.with(&metadata, "facing", "east"). BlockState::of(&metadata, key, constraints) starts from the published default and applies the supplied StateConstraints. Changes return a new value and never mutate the original. Unknown keys, ordinals and property combinations return typed BlockStateErrors.

SceneBlock::new(pos, state, entity) and StructureTemplateBlock::new(pos, state, nbt) use this owned BlockState, including all properties. Structure reads preserve vanilla palette selection, mirror-then-rotation and placement order; an unavailable state mapping refuses the whole snapshot with None. DrawContext::draw_scene checks the entire scene before drawing: an unknown key, invalid ordinal or unavailable mapping draws nothing, never a partial scene or a replacement air block. Native and wasm use the same values and refusal rules.

Tint callbacks receive the same immutable metadata resource explicitly, without a Host. The game prepares their owned state array before constructing mesh tables; renderer workers only copy those values and invoke metadata reads. When world numeric state IDs are reordered, the game resolves each state's property combination against the published definition, so local ordinals retain their meaning across reloads.

host.block_states().states_of(key) returns a BlockStateRange in that same immutable local ordinal order. Its iterator yields owned BlockStates; it is not a span of world numeric IDs. BlockStateRange::new(first, count) returns a typed error if the span would exceed the u16 ordinal domain, and decoded transport spans obey the same check. Membership checks both the block key and the ordinal. A zero-count span is empty.

A restricted LevelHost::block_state(pos) read returns Option<BlockState>. A successful engine read retains its vanilla result: unloaded or out-of-height reads that produce air return Some(air), using the owning registry's real air state. An unavailable owning state index or a refused engine-to-API conversion returns None; the boundary never fabricates a key or air state and never panics to satisfy a mandatory value. Other optional/result read contracts are unchanged; in particular, this does not change LevelRef's loaded-position policy.

LevelRef::set_block, update_neighbors and neighbor_changed take owned block states and return Result<bool, LevelWriteError>. Stale identifies a closed or reopened level; Unavailable identifies the wrong side, phase or nonactive write target; InvalidState retains the block-state refusal. Errors do not mutate the level. Ok(false) is still vanilla refusal, such as an unloaded or out-of-height position or an unchanged block, not a lost handle or a guessed replacement state. Update flags retain their vanilla effect.

Walking a whole registry uses the typed keys, never names: host.block_keys() and host.item_keys() return every entry in the registry's registration order (vanilla's entries first, then mods' in the order they registered); host.entity_type_keys(), host.menu_keys() do the same for the built-in entity-type and menu registries. host.enchantment_keys() uses global sorted loaded-registry order, with vanilla and mod data-pack entries sorted together. A block registry lists a name once per state, and its iteration lists the block once. Build lookup tables from these lists at load time instead of resolving names per tick. A table is empty before its registry loads (blocks and items during rest load, enchantments with the item tables); registration-time RegistrationContext does not see any of them (#1001).

Keys are small, private u32 registration slots on both native and wasm. key.id(host) returns an owned canonical String through the generated read backend for diagnostics; it requires a game-backed host and an invalid slot is a boundary error, not an empty name. Block defaults come from immutable API metadata and cross through the game's sole forward/reverse state index. Behavior queries obtain their engine block from the resulting engine state; there is no separate per-key numeric block binding. Reload preserves key identity and canonical names. A refused resource rebind clears the active index, while failed transactional Parts preparation leaves the previously published Parts and index intact. Effect registration is process-owned and fixed until restart, matching the engine's effect registry.

A name that only arrives at run time (data, config, a command, a network message) turns into a key with the host: host.block_key("minecraft:stone"), host.effect_key("mymod:rage") and host.fluid_key("minecraft:water") return Option, and key.id(host) gives the name back for blocks, effects, fluids and items. Names are full registry names; the lookup reads the completed registry and does not allocate, so a hook can call it. It returns None for a name the registry does not hold, and before the registry is complete, so a mod uses r.block_key(id) in register. These work on the client and the server, for native and wasm mods alike.

Block tag membership is bound from the same merged item/block tag snapshot at world load and reload, including worlds without pack overrides. A read checks that the owning state index is available, looks up the tag name and tests membership in a prepared API BlockKey set; it never resolves the block's name. A fully namespaced tag needs no allocation (a bare tag adds minecraft:). Binding visits each merged block-tag member once and resolves its API key; it replaces the previous snapshot rather than accumulating membership. No membership work is added to ticks that do not call this read. Tags and block mappings belong to their resolving thread; missing authoritative context or an unavailable mapping returns None, not a stale membership result.

host.tags().blocks(tag) reads the current authoritative block members in vanilla order as BlockKey values, including blocks no mod requested. Resolve tag once with Tags::key and retain it across reloads. Unknown or empty tags return Some(Vec::new()); an unavailable context or any unresolved member returns None, never a partial member list. The same service is available through restricted level Hosts, without borrowing an engine registry.

host.block_state_default(stone), host.block_states().states_of(stone), host.block_item(stone), host.block_in_tag(stone, tag) and restricted-level schedule_block_tick(pos, stone, delay) use BlockKey. Property expressions accepted by block_state_id, tag names and existing fluid operation arguments remain strings for now.

Declare a tank-only fluid in your own namespace with r.declare_fluid("chocolate"); the returned FluidKey identifies it for the mod load. Request vanilla or another mod's declared fluid with r.fluid_key("minecraft:water") or r.fluid_key("other:chocolate"). Requests resolve after all registrations, so declaration order does not matter; an unknown request stops the load and names the requesting mod. Tank-only fluids have no world simulation or world state. Fluid stacks and recipe ingredients use these keys; remaining fluid operations move to them in subsequent changes. Declare a fluid that exists in the world with let mut fluid = WorldFluid::default(); fluid.drop_off = 2; r.declare_world_fluid("oil", fluid);, using mod_api::WorldFluid, the code form of a fluid file's world object (content mods): it adds the block mymod:oil, the flowing fluid mymod:flowing_oil and the bucket mymod:oil_bucket, and its fluid file, if it has one, still says how it looks. r.fluid_part("mymod:oil", Part) attaches a FluidPart, whose fluid_rules can change the declared values by position on the server. It is asked for every cell a spread looks at, so answer fast.

A saved tank whose fluid's mod is absent carries an opaque unresolved identity. Its stack's key() is None; UnresolvedFluid::id(host) reads its saved name. It can move between name-backed mod tanks, but not into vanilla buckets or cauldrons.

ActiveEffect::id and effect hook payloads carry EffectKey; living effect queries, application and removal use the same resolved key. ActiveEffect::new(speed, …) uses a key requested through r.effect_key("minecraft:speed"). Beacon-selection hooks carry Option<EffectKey> for each power; None is no selection. Enchantment effect-component names (for example minecraft:damage in has_enchantment_effect) are a different registry and remain strings, as do labels and tags.

Hot item and block identities

Resolve item and block keys during load and keep them for tick and menu calls. item_burn_time, item_compost_chance, give, enchantment_supports's item, and GUI item / item_model take ItemKey. block_item, fluid_bucket and screen_hovered_item return item keys. level.block, lit_block_name and Hit.block return block keys; BlockEntityDrawContext::block takes one. HeldItemSlot.id (including use-start/stop events) and Stack.item carry item keys, not names. Unknown incoming slots are refused at the boundary. block_sprites takes API-owned BlockState values, preserving properties without parsing state strings or exposing numeric engine state IDs. The pre-change block event carries resolved from / to states and does not allocate their names. Property names and values in set_block_property are not block identifiers and remain strings.

These calls remove string transport across wasm. Engine metadata reads may still hash borrowed registry names; no formatted identifier is built for these inputs.

Matched recipe lookup

level.recipe_for(host, &recipe_type, &inputs) replaces the crafting-only lookup. Use RecipeInput::Crafting { width, height, slots } for minecraft:crafting (row-major slots, dimensions 1 through 3), Single(stack) for smelting, blasting, smoking, campfire cooking and stonecutting, or Smithing { template, base, addition } for minecraft:smithing. Recipe types are not serializers: shaped and shapeless files both belong to minecraft:crafting, and transform/trim both belong to smithing.

The server uses the same engine matchers and assembled outputs as its menus, including data-pack overrides of vanilla recipe types. A RecipeMatch contains the matched recipe identifier, typed output, ordered remaining items, experience and processing time. Lookup consumes nothing; the caller applies inventory changes transactionally. Keep the result until inputs or the recipe load change.

Ok(None) means valid input without a match. Invalid shapes/items and unavailable levels are typed errors. A type without an engine matcher returns RecipeLookupError::NotMatchable, not an empty match. For mod-owned types, retain recipes_of_type once per load/reload and match that cached data inside the mod, with zero crossings per tick. Dynamic custom outputs and contextual predicates remain mod-owned; the host does not call guest code to match recipes.

At publication, call ingredient.item_keys(host) once per ingredient to retain Arc<[ItemKey]> for local matching. This load-time read returns exactly the plain item membership for lists, expanded tags and standard shapes, using the engine matcher. It returns IngredientKeysError::NotEnumerable if any custom or component predicate occurs anywhere in the tree; a displayed item list is not a safe substitute. UnknownItem refuses a missing registry identity. Do not call this method per tick. The sample's ProcessingRecipes::publish retains these keys; result then checks input.item() locally, with no Ingredient::test host call per candidate.

Stack placement predicates and drawing consumers (HUD items, GUI item decorations, block-entity items and tooltip images) encode API stacks without enforcing resident count or damage maxima. Engine-legal over-limit stacks can still be inspected and drawn. Unknown item keys and invalid/unrepresentable effect payloads still refuse encoding; this is not a total conversion. Insertion and other world writes retain strict validation.

API-owned values: migration table

mod_api::GameRuleValue owns the Bool(bool) and Int(i32) cases, in that order. level.game_rule(host, id) returns Result<Option<GameRuleValue>, LevelReadError>: Ok(None) means unknown rule, Stale means a gone/reopened level, and Unavailable means the side or phase cannot read it. level.game_rules(host) returns the typed result containing every available rule, not an optional list. The existing boolean key getter is unchanged. The game converts values after the subscription guard for game_rule_changed; no subscriber means no conversion work.

The API's GameRuleDecl records a mod's boolean rule name, category and default. Its internal RuleSchema input describes vanilla categories and dense rule positions through read-only lookups rather than a copied vanilla list or fixed slot numbers. Schema validation resolves category references after all mods have declared them and returns either all declaration slots or every refusal; it never installs a partial table. The game supplies this schema at Parts installation, then builds each world's engine rule registry from the installed GameRuleDecl snapshots. Existing rule registrar calls are unchanged; engine registry construction is no longer exposed through the API.

The game owns package and completion conversion. Mods do not import package-loader or client-core types for these values. Completion edits are copied back after subscribed listeners run; no listener means no snapshot allocation. Package metadata is copied once at startup, retaining declared namespaces and dependencies.

Opaque NBT metadata

The shared JSON/NBT conversion is iterative and follows vanilla's 512 nested list/compound limit; scalars and NBT typed arrays add no recursive container. Conversion to JSON intentionally loses numeric tag widths, boolean-as-byte identity and typed-array identity. NonFinite refuses NaN and infinities: serde_json::Value cannot hold them, and Gson's strict JSON writer also refuses them. InvalidString refuses an unpaired UTF-16 surrogate in a Tag string or compound key. Neither case is replaced with null, a string or U+FFFD. JSON input already uses UTF-8, so valid non-BMP pairs survive; a lone surrogate cannot reach this converter through that input representation.

Owned component trees

The text module defines owned component data: literal and translatable contents, style overrides, ordered children, selector and NBT sources, inline objects, and click and hover actions. Translation keys and argument components stay unresolved until the game displays them. None style fields inherit; Some(false) overrides an inherited decoration. Metadata, dialog/custom click payloads and hover-item component patches are owned Tag data, never JSON strings or engine state. TextProfile carries an optional name and UUID, signed property records and opaque unknown profile/property fields. Signed record order and unsigned values within each property name are preserved. Player names use U+0021..U+007E and at most 16 characters. Vanilla's unsigned property-map form allows at most 16 distinct names; signed or metadata-bearing records use a 16-entry list, with UTF-16 limits of 64, 32767 and 1024 units for property name, value and signature respectively. Inline player and atlas objects use Option<Box<Text>> for their fallback: None keeps the engine-computed default; Some preserves a styled or translatable component rather than flattening it to a string.

The native boundary plans borrowed source topology before cloning payloads. It reads source-less spans directly and validates every Tag's JSON representation before building an engine component. Text::validate() checks tree/payload bounds and profile fields without cloning; validate_depth() is the component-only preflight. NaN/infinity and unpaired UTF-16 remain legal Tag data but cause typed NonFinite or InvalidString refusals when engine emission requires JSON. Nested JSON null is refused as NestedNull when capturing opaque NBT fields; it is never silently replaced. Host methods accepting or returning Text return Result<_, TextFormError>; mixed item/Text writes preserve the refusal in StackWriteError::Text, and unspawned-mob reads use UnspawnedMobError::Text. TooDeep means a component path or opaque NBT container path exceeds 512. Unavailable backends are distinct from invalid text or unrepresentable payloads. A refused hook capture does not dispatch; a refused writeback leaves every field unchanged. No subscriber means no conversion or snapshot allocation. Mutable stack arguments are compared using value equality with the snapshot passed to the listener. An unchanged argument retains the original engine value without strict write validation (including engine-legal stacks above effective count or damage maxima). A changed argument is validated in full; a refusal still commits no outputs. The same rule applies to anvil/grindstone records and menu cursor/quick-move stacks.

Recursive Clone, Eq and Drop of a tree a mod itself built are ordinary Rust ownership, not part of the boundary guarantee.

Text::new(content) constructs any content kind without exposing an engine value. The content, NBT-source, object, click and hover enums are exhaustive protocol enums; new cases change the link contract, just as enum-case order does. Mod matches should name every case rather than silently treating a new protocol case as an old one. Typed content and style fields are authoritative; metadata retains unrecognized properties, not overrides of those typed fields. Game-side encoding is fallible and reuses the engine's translation-argument and fallback construction rules. Capture keeps dynamic contents and metadata rather than flattening the rendered spans. It shares the engine's SNBT flag, shadow-colour, click-policy and inline-object parsers. File-opening metadata is discarded before a listener receives the owned value; a no-op listener cannot promote an untrusted file action into a local action. A translatable's fallback is a literal format template, not another language key. A missing key whose fallback equals an existing key therefore still displays the fallback text itself; parsing and native constructors follow the same rule.

Particle identities

ParticleKey is an opaque slot in the load-owned registry tables. One completed snapshot retains both canonical names and provider identities: a vanilla provider's numeric index or a custom named sprite provider. The load resolves each provider once; reads of a retained key do not parse identifiers or scan the provider list. Unknown forward references refuse publication of the entire particle snapshot. Name-table completion shares the item registry's requested-slot preservation and sorted enumeration.

Placement and loot snapshots

mod_api::PlacementContext owns the placement inputs, including world-space click coordinates and the placer view/flags. Its item is Option<ItemKey>: None is a real empty hand, including falling-block placement contexts, not an invented air item. Nonempty items resolve through the existing load-owned item table. The game captures this read-only snapshot after the scoped subscription guard; no subscriber means no snapshot or item lookup. The block-state answer is applied as before.

The snapshots module owns placement inputs and loot-roll facts. Placement and tool items are resolved ItemKeys. Loot context entities, damage sources, tools, biome, block and place facts are owned values; retaining one never retains a borrowed engine context or a live level. A loot candidate is not an inventory ItemStack: its signed count can be non-positive while loot functions run, in which case it produces no item. Exploration searches remain deferred data, and name components remain unresolved text.

Item values and tag names

Every item has an ItemKey, including vanilla items no mod requested during registration. r.item_key(id) retains a forward reference in the same load-owned table; after the item registry is complete, host.item_key(&identifier) resolves any registered item. A key is still a private u32 index, not a copy of an item definition. Resolve once and retain it. host.max_stack_size(key) and host.max_damage(key) read item defaults without exposing the engine's item table.

ItemStack is owned API data with private fields. ItemStack::new(key, count) refuses zero, while ItemStack::of(key) makes one item. Count mutation refuses zero and arithmetic overflow. Registry-dependent maximum count and damage, including component overrides, are checked by the game when accepting a write; an oversized value is refused with a typed error, never silently clamped. This is the same boundary on native and wasm. Consuming split(n) returns StackSplit { taken, remainder }, both optional; consuming shrink(n) returns the remainder or None. There is no empty-stack sentinel. Component descriptors read and write an optional owned NBT patch; a plain stack has no patch allocation.

host.tags() and a restricted level host's tags() expose the same Tags service. Resolve a validated identifier once with tags.key(&identifier) and retain its TagKey. The runtime owns tag-name slots for the process; reload replaces membership, not names or key identity. tags.is_in_tag(item_key, tag_key) tests merged item membership. tags.items(tag_key) and tags.fluids(tag_key) return registered keys in vanilla's member order. Unknown tags return false or empty lists. Membership reads return None on clients, before authoritative tags load, or if the relevant registry mapping is unavailable. Key resolution itself can be refused if the runtime cannot allocate a name slot. No lookup stringifies a retained key. Block member enumeration moves with the registry-wide BlockKey table in the next type slice. The engine TagRegistry, StackData, StackView and DisplayContext are not API types.

A hook whose catalog entry has a scope (block, block_entity, item, menu) and a key, the argument naming the thing it is about, is a method on that scope's trait only: BlockPart, BlockEntityPart (a BlockPart too), ItemPart and MenuPart, as vanilla's and NeoForge's Block and Item methods are. It has no Hooks method: a thing without parts is never asked, and the game asks the parts attached to it in dispatch order, through the hook's contract, so a Cancel or a replacement skips the parts after it. Where a NeoForge bus event is the counterpart for that moment, the event is a hook of its own on Hooks, asked first for every thing, and its cancel skips the parts: a mod reacting to its own blocks uses a part, one reacting to every block the event. A part's kind is its type: the same kind twice on one thing, an invalid key declaration, or an unnamespaced id in the other Part registrations stops the game at startup with a message naming the mods. A panic in a part adds , part <type> to the mod and hook it names. Parts take &self and are Send + Sync, like Hooks.

Damage and item metadata snapshots

The three damage hooks convert only after their subscription guard. DamageValues retains the entire sequence, including reductions and the pre-hook input, so changing new_damage still reaches the engine's original NaN and negative normalization point. DamageValues::set_reduction edits snapshot data; it does not run a damage calculation. The fixed reduction storage is private; use its accessors rather than an array index. Reduction case order is append-only. Engine record_*, enter_pre, capture_inflicted and pre_change are not mod API methods.

ItemResource::damageable, foil and repairable delegate to the game's existing property readers through metadata access. Defaults, explicit overrides, component removals, compass glint and repair tags follow gameplay's single property path.

Recipe-file fields and small values

Host::recipe_ingredient and Host::recipe_result take the field's JSON text, not a serde_json::Value. Pass a quoted item id (r#""iron_ingot""#), a quoted #tag, or an ingredient array. Parse failures return RecipeJsonError::InvalidJson; unknown items and empty tags still return Ok(None). Result objects retain their components patch. These helpers are reload-time reads, not per-tick JSON parsers.

BlockPart::clone_item_stack answers on the server when a player picks the block. It receives the level, position, block state and include_data, true when a creative player picks with Ctrl. Return None to keep the game's item.

BlockPart::fall_on runs at vanilla's landing moment on a read-only level random host. Request a deferred write with event.request(LandingWrite::SetBlock(state)), where state is an API BlockState, or LandingWrite::DestroyBlock { drop }. The game checks the complete write batch before queuing it. An invalid block key or ordinal refuses that callback's writes and other outputs, including damage; it never applies a valid prefix. After the entity batch ticks, writes apply in request order if the block still matches its original landed state. That guard runs once, so a first write can change the state without suppressing the next write. SetBlock notifies neighbors and clients; DestroyBlock preserves the requested resource-drop flag.

BlockPart::contents_changed(host, event) observes a world block's storage at setChanged, with a ServerHost, typed event.level, event.pos: BlockPos and event.state. Attach it to the specific blocks you observe, including vanilla containers; it has no global Hooks counterpart. The backing contents are already written, before dirty/comparator updates. Native transactions notify once per backing block at root commit, never on abort or simulation. An explicit BlockEntityRef::set_changed notifies even if contents are unchanged. A double container notifies each component, not once again for the other half's comparator refresh. A listener's writes still apply, but a nested notice for that same backing block does not re-enter the listener; writes to a different backing block notify normally. Entity/menu placeholder coordinates are not block notices. This replaces Create's positional contents_changed mixin for depot/package/schematic storage; there is no NeoForge bus event. A compiled listener that reads the committed items through the typed level (the game's own test, so it cannot drift):

#[derive(Clone, Debug, PartialEq, Eq)]
struct Notice {
    level: LevelRef,
    pos: [i32; 3],
    amount: u32,
    version: Option<i32>,
}

#[derive(Clone, Default)]
struct Changes(Arc<Mutex<Vec<Notice>>>);

#[mod_api::horizon_part]
impl BlockPart for Changes {
    fn contents_changed(&self, host: &mut dyn ServerHost, event: &mut ContentsChangedEvent) {
        let pos = [event.pos.x, event.pos.y, event.pos.z];
        let amount = event
            .level
            .capability(host, &ITEMS, pos, None)
            .map_or(0, |items| {
                (0..items.size(host))
                    .map(|slot| items.amount(host, slot))
                    .sum()
            });
        let version = host
            .block_entity(event.level, pos)
            .and_then(|entity| entity.data(host))
            .and_then(|data| match data.get(&"Version".into()) {
                Some(Tag::Int(value)) => Some(*value),
                _ => None,
            });
        self.0.lock().unwrap().push(Notice {
            level: event.level,
            pos,
            amount,
            version,
        });
    }
}

Declare a block entity type and its valid blocks during Hooks::register, then attach its part:

let press = r.block_entity_type("press")
    .blocks(&["mymod:press", "mymod:big_press"])
    .build();
r.block_entity_part(&press, Press).expect("native block entity type");

The builder qualifies the type ID with the registering mod's namespace. It owns the save ID, wire type and valid blocks; block_entity returns only initial Compound data (or none for an empty compound). It is fired inside the write that creates the entity (LevelChunk.setBlockState) and receives the read-only level, a LevelSide, on a server and on a client of one. Unknown blocks, duplicate types, overlapping membership and attempts to own a minecraft: block are refused at load. Refused native block, item or block entity declarations stop startup, as does unreadable known-components input; the game does not fall back to vanilla content. An explicitly declared mod template block uses its declared type; undeclared template blocks retain their vanilla behavior. Adding mod blocks to vanilla types is not supported by this builder. The hooks about the entity (block_entity_tick, block_entity_update_tag, pre_remove_side_effects, menu_button, menu_quick_move) find it by that declared type; the others (block_entity, screen, the block hooks) by block. The factory is a BlockEntityPart method, not a global Hooks method.

r.block_entity_type_key("other:press") looks up another mod's type, and r.block_entity_type_key("minecraft:chest") looks up a vanilla type. Both return the same opaque BlockEntityTypeKey as the declaration builder: equality and hashing use the shared load-owned registration slot, not the type's blocks. Bare names use the minecraft: namespace. The final registry resolves requests after all declarations and refuses unknown IDs, naming the requesting mod and type. key.id(host) reads the canonical name for diagnostics; a key retains its identity until restart. Use a type ID, not a block ID (minecraft:shulker_box, not minecraft:red_shulker_box). BlockEntityRef::kind(host) returns Option<BlockEntityTypeKey>. living.hurt_and_break(host, slot, amount) changes equipped durability on the server; negative amounts repair. It returns the pre-shrink stack only on break, and None when nothing breaks or the entity or slot is unavailable. Creative players' equipment is exempt. The operation does not fire equip effects.

block_entity.replace_data(host, data) replaces its saved payload, clearing omitted fields while retaining identity and position. Like merge_data, it loads transactionally and synchronizes the change; it returns Err(BlockEntityError::Stale) for an invalidated handle, or Ok(false) for data the entity cannot load or an unchanged result. Lookup keys may answer capabilities for vanilla and native types. block_entity_part accepts only native types and returns BlockEntityPartError::VanillaType immediately for a vanilla key. Native Parts are expanded after every mod has registered, so a Part can target a type declared later.

Item and tag Parts

For an item-specific Part, request its canonical registry key once in register: let stick = r.item_key("minecraft:stick"); r.item_part(stick, Sharp);. Bare names use the minecraft: namespace. Requests may refer to content declared later; the final item registry refuses unknown IDs with the requesting mod. ItemKey equality uses its load-owned slot, and key.id(host) reads its canonical diagnostic name. Item capability registration and item helpers still use strings; their migration is a separate change.

r.block_part_tag("minecraft:logs", Rotates) and r.item_part_tag("minecraft:axes", Sharp) attach a part to every member of a tag (its name without #). Each game resolves them against its own tags when its world opens, again on /reload, and when a client joins a server, so the window's game and its server thread each answer from the tags they play with; a block that leaves the tag is no longer asked. A mod's parts on one thing run in the order it registered them, by key or by tag. A part a tag gives a thing that already has that kind of part warns, naming both mods, and the earlier mod's part stays. A tag that doesn't exist warns. Opening a world fails, naming the mod, when a part is attached to a block or item the game doesn't have. Scoped hooks run on a game's thread; one dispatched from any other thread (which no game hook does) can't see tag parts, and warns once.

Instant item use

ItemPart::use_item receives UseItemEvent { stack, hand }. hand: Hand is the interaction hand of this click (Hand::Main or Hand::Off), including air clicks with identical stacks in both hands. Read it directly when choosing which held stack to shrink. living_used_item_hand instead answers only during active item use and cannot identify an instantaneous click. The Part runs on both sides with HostSide, after the global right-click event and before the item's own use, on native and wasm. Return Some(InteractionResult::Success) to consume and swing on the client, Some(SuccessServer) to consume and swing on the server, or Some(Consume) to consume without a swing. Some(Fail) skips this item's own use without swinging and allows the off-hand sequence to proceed; unlike a block-use Fail, it does not end the entire click. None (the default) lets later Parts answer; if none answers, the item's own use runs. Some(Pass) stops dispatch to later Parts and continues directly to the item's own use. TryWithEmptyHand belongs to block use and is treated as Pass here. A thrown item can return Success on the client and Consume on the server. The hand field corresponds to NeoForge's PlayerInteractEvent.RightClickItem.getHand().

Hooks::right_click_item runs before Item.use, including after the same hand's unhandled block or entity interaction. A block success or FAIL, or an entity success, stops fallback. The server fires it for the separate use-item packet, once for that packet's hand. Canceling skips the item Part and vanilla action on native and wasm alike.

Item wear

ItemPart::damage_item is IItemExtension.damageItem: the wear a stack of the part's item is about to take (ItemStack.hurtAndBreak), after Unbreaking, as NeoForge passes it. The part reads event.amount, the points about to be lost, and changes it (0 or less leaves the item whole) or returns Flow::Cancel for no wear at all. It runs on every wear path: a player's tools, armour, shield and mace, a tool a dispenser uses, and a mob's armour. It is not asked when Unbreaking already saved the item or for a creative player's tools, and an item with no part costs one table lookup. With no part, the vanilla amount applies.

The global item_damaged hook is gone: this method is its one moment, and a part acts only on its own item. What the global hook could do and a part cannot is change the wear of another mod's or vanilla's items, which no part is attached to. Do that with an enchantment effect in data (a minecraft:item_damage effect on the enchantment, the component Unbreaking uses), or with an injection. A part does not get the wearing entity; host.players().acting_player() names the player on the paths a player takes.

A capability is answered by providers, registered by block entity type as NeoForge's RegisterCapabilitiesEvent registers them: obtain pipe with the declaration builder or r.block_entity_type_key("mymod:pipe"), then r.block_entity_capability(&ITEMS, &pipe, |host, at| Some(Box::new(PipeItems))) gives a handler for the block entity and side at (a BlockSide), or none to leave it to the next provider. A provider may answer for a vanilla block entity type too, using its lookup key. Providers add up: level.capability(host, &ITEMS, pos, side) (Level.getCapability, on a LevelRef) asks those registered with r.block_entity_capability_before_game first, then the game's own (a block entity's slots by side, by the rules hoppers follow, and a mod block entity's block_entity_container), then the others, each in registration order, and the first to answer wins. That order is the fork's choice, the game first and _before_game to go ahead of it: NeoForge 26.3's javadoc doesn't state one between mods' providers and the game's. It returns a Capability, the handler and who answered. A handler holds no borrow: each call is given the host, so it may call a neighbour's capability, and it keeps its state in the block entity's slots, compound or attachments. A provider is given the block entity and side, so the handler it makes knows where its contents live. Item handlers are NeoForge 26.3's ResourceHandler<ItemResource>: indices from 0 (size), what each holds (resource, an ItemResource: an item and its components, without a count) and how much (amount), how much of a resource an index holds when it holds that (capacity, none where it may not go), and insert and extract, which take a &Transaction and answer how much moved. There is no simulate: a write happens in a transaction (host.transaction(|host, tx| …), below), and to try one, abort it. move_resources(host, &from, &to, filter, max, tx) (NeoForge's ResourceHandlerUtil.move) moves what filter accepts, up to max, index by index out of from into wherever to takes it, each move all or nothing: what to won't take stays put. It answers how much moved, or Overanswered (below). Hoppers use a mod's handler where one is registered, each move in a transaction of its own. A mod's own capability is a CapabilityKey::new("mymod:chemicals"), answered only by parts.

A Capability may be held for the tick: look a neighbour's up once per tick and reuse it for every move that tick, as pipes and machines do. Ask again on the next tick, since the block entity behind it may be gone by then. For a wasm mod each lookup crosses the sandbox (about 2.5 µs, see Building a mod to mod.wasm), so holding it matters more there.

An item's own capability is reached where its stack lives, an ItemPlace: a player's slot, hand or cursor, a block entity's slot, an item entity, a stack inside another item (ItemPlace::Nested) or a mod's own place (ItemPlace::Mod, read and written by the PlaceProvider it registers with r.place_provider). r.item_capability(&ITEM_ITEMS, "mymod:backpack", |host, place| Some(Box::new(Backpack))) answers ITEM_ITEMS for an item with a ResourceHandler<ItemResource> made for that place, and r.item_capability_before_game ahead of the game's own over item_container; place.capability(host, &ITEM_ITEMS) (ItemAccess.getCapability) asks them in the same order. A handler keeps its contents in the stack, and reads and writes it through the place, as NeoForge 26.3's ItemAccess: place.stack(host), place.resource(host) and place.amount(host), and place.insert, place.extract and place.exchange(host, tx, &resource, amount), which answer how much moved. Each runs in a transaction of its own, nested in tx, and changes the place where it is, journaled, so an abort puts it back at every level of an item inside an item. A handler answering more than it was asked or offered is a mod bug: the move it was part of is undone, and the game warns once, naming the mod. What doesn't stack with the place, or doesn't fit, goes where vanilla puts an item split off it, so exchange(host, tx, &filled, 1) on a stack of empty buckets is vanilla's filled bucket: from a player's place into their inventory, else dropped with no thrower (a creative player's hand takes anything and gives them one if they have none, as forInfiniteMaterials); from an item entity dropped beside it; from a block entity's, an entity's or an item's slot into that container's other slots (forHandlerIndex). A handler rewrites its item with an exchange of one. An exchange inside one of two backpacks is done in one of them: that one is rewritten holding the change and splits off, and the other stays as it was.

A stack's components change the same way, where it lives (NeoForge's ItemResource.with and without). A component is named by a ComponentId, checked once as a namespaced id (ComponentId::new("minecraft:damage"), None for Damage or !minecraft:food). resource.component(&id) reads the stack's own value in its patch as saved; resource.with_component(host, &id, value) sets it as vanilla's PatchedDataComponentMap.set does, keeping no value of the stack's own where value is the item's default (host.item_default_component(item, id), compared as the component's codec reads it: a vanilla component's numbers by exact value, custom_data and the other raw NBT components and a mod's own type for type), and resource.without_component(host, &id) removes the component as remove does: the stack's own value goes, and where the item has the component by default a removal ("!minecraft:max_damage": {}) is recorded in the patch. An exchange of one puts the changed item in place: place.exchange(host, tx, &place.resource(host)?.with_component(host, &damage, Tag::Int(5)), 1) damages one sword of a stack, splitting it off.

An entity's items

entity.capability(host, &ENTITY_ITEMS, ()) (NeoForge 26.3's Capabilities.Item.ENTITY) is an entity's items, None for a stale handle and an entity outside the level in place. The game answers it for a player with their inventory (PlayerInventoryWrapper), indices as vanilla's Inventory numbers them: 0..36 the main inventory (0..9 the hotbar), 36..40 the armour from feet to head, 40 the off hand. Each index is the player's ItemPlace::PlayerSlot and takes only what fits there: an armour slot one of what its equippable names it for (ArmorSlot: its allowed entities hold the player by id or by tag), and bound armour comes off only in creative. insert_any, without an index, goes where Inventory.add puts a stack: onto the same item in the selected slot, the off hand and the main inventory in order, then into its empty slots, never the armour. For a chest or hopper minecart, a chest boat and a chested donkey, mule or llama the game answers with their container's slots (ItemPlace::EntitySlot). A handler kept past its entity's removal or its world's close reaches nothing. r.entity_capability(&ENTITY_ITEMS, "mymod:robot", |host, robot, ()| …) answers it for a mod's entity type, and r.entity_capability_before_game ahead of the game's own, asked as block entities' providers are. Giving, taking and counting a player's items go through it:

#![allow(unused)]
fn main() {
// A trade: each offer is (index, the exact stack it must still hold). A stale offer or no
// room for one aborts the transaction, and every move in it is put back.
let (a, b) = (seller.capability(host, &ENTITY_ITEMS, ())?, buyer.capability(host, &ENTITY_ITEMS, ())?);
host.transaction(|host, tx| {
    for (from, to, offer) in [(&a, &b, &seller_offer), (&b, &a, &buyer_offer)] {
        for (index, stack) in offer {
            let offered = ItemResource::of(stack);
            let still = from.resource(host, *index).as_ref() == Some(&offered)
                && from.amount(host, *index) == stack.count();
            if !still
                || from.extract(host, tx, *index, &offered, stack.count()) != stack.count()
                || to.insert_any(host, tx, &offered, stack.count()) != stack.count()
            {
                return Err(());
            }
        }
    }
    Ok(())
})
}

Cauldron interactions outside a transaction keep vanilla's effect order. Inside an open transaction, their statistic award (including player_stat_award), sound and overflow item toss/spawn wait until the outermost successful commit; an abort emits none of them.

Entity energy and fluids

entity.capability(host, &ENTITY_ENERGY, side) and entity.capability(host, &ENTITY_FLUIDS, side) reach a mod's entity energy and fluid handlers (NeoForge 26.3's Capabilities.Energy.ENTITY and Capabilities.Fluid.ENTITY), where side is the Option<Direction> of the entity the lookup reaches it from, None for no particular side. Vanilla answers neither; register a provider with r.entity_capability(&ENTITY_ENERGY, "mymod:robot", |host, robot, side| …), which is given that side and may answer differently for each. An entity capability's context is its key's second type: () for ENTITY_ITEMS, Option<Direction> for these two and for ENTITY_AUTOMATION. The existing move_energy and move_resources transfer between these and block or item handlers inside a transaction.

Entity automation

entity.capability(host, &ENTITY_AUTOMATION, side) (NeoForge 26.3's Capabilities.Item.ENTITY_AUTOMATION, "automation-accessible inventory of an entity (boats, minecarts, etc)") is the items of an entity as a hopper reaches them, with the same Option<Direction> context as the energy and fluid keys. The game answers it for the container entities EntitySelector.CONTAINER_ENTITY_SELECTOR picks (chest and hopper minecarts, chest boats) with the slots their ENTITY_ITEMS handler has; a player and a chested donkey, mule or llama answer none. A hopper pushing into the entity in front of it asks for the side it faces the entity from (Up for a hopper over it), a hopper pulling from the entity above it for Down, and a dropper for the side it drops onto. Beside the game's container entities, those entities at the target whose mod provider answers it join the candidates, and the hopper picks one at random with the draw getEntityContainer makes; a mod handler takes the container's place and moves one item at a time in a transaction, as a mod block's ITEMS does. r.entity_capability(&ENTITY_AUTOMATION, "mymod:robot", |host, robot, side| …) registers one, and r.entity_capability_before_game answers ahead of the game's own for a minecart or a boat.

A menu's slots

Mod-created recipe input sets

Hooks::recipe_property_sets runs once after recipes resolve for each load and again after /reload. Add RecipePropertyAddition::new("mymod:cooking_pot_input", items) to its event.additions: a key in the listener's manifest-owned namespaces creates a set. Ownership uses the package ID plus the manifest's namespaces, so a package named ported_farmersdelight with namespaces = ["farmersdelight"] can create farmersdelight:cooking_pot_input. A later listener may extend an existing set but cannot create a new foreign key. Invalid keys, unknown vanilla keys and air are skipped with a warning; unregistered items do not participate in acceptance or network sync.

Attach a MenuPart to the registered menu type and filter its input slot with the same set:

struct PotInput;
#[mod_api::horizon_part]
impl mod_api::MenuPart for PotInput {
    fn menu_slot_rules(
        &self,
        context: &dyn mod_api::LoopContext,
        event: &mut mod_api::MenuSlotRulesEvent<'_>,
    ) {
        if event.slot == 0 {
            event.may_place &= context.mod_recipe_property_contains(
                "farmersdelight:cooking_pot_input", event.stack.item(),
            );
        }
    }
}
// In Hooks::register:
// registrar.menu_part("farmersdelight:cooking_pot", PotInput);

The Host exposes the same mod_recipe_property_contains(set, ItemKey) query outside restricted menu callbacks. This query covers mod-created sets only: unknown sets, unknown items and vanilla set keys return false. Existing vanilla station acceptance is unchanged. The server reads its owning load; the client reads local preload sets before its first UpdateRecipes, then the authoritative server generation. A packet replaces the entire generation, including an empty one. Closing a screen or changing dimension retains it; disconnecting discards it. Reads allocate nothing and do not rescan recipes or registries. There is no second hook and no per-slot load callback.

Client hooks can read the local player's menu with host.local_player()?.container_menu(host), including the inventory when no container is open. MenuRef::slot_count, slot and carried read on either side; slot and carried return an outer None when the handle or slot is unavailable and Some(None) for an empty slot. Each read checks the world epoch and menu generation, so a handle cannot read a replacement, reopened or respawned menu. These methods do not click or change slots.

Mutable client hooks can submit a vanilla click with menu.click(host, &[mod_api::MenuClick::QuickMove { slot }]). The slot is the same menu-order index used by slot, not a hotbar index or a GUI slot id. For example:

/// Shift-click a slot in the local player's current menu.
pub fn quick_move(host: &mut dyn mod_api::ClientHost, slot: usize) -> bool {
    let Some(menu) = host
        .local_player()
        .and_then(|player| player.container_menu(host))
    else {
        return false;
    };
    menu.click(host, &[mod_api::MenuClick::QuickMove { slot }])
}

The typed actions are Pickup (with MouseButton::Left or Right), QuickMove, Swap (with SwapWith::Hotbar(0..=8) or Offhand), Clone, Throw, Drag and PickupAll. Pickup accepts None for outside, dropping the carried stack. A Drag { kind, slots } owns its menu-order slot list and always submits a complete gesture; DragKind::Split divides evenly, One places one per slot and Clone fills slots in creative mode. Every action in a batch is validated before any prediction or sending; out-of-range slots/hotbar indices, creative-only actions in survival and empty batches refuse without effects. Stale/replaced/respawned menus, spectators, non-client hosts and the creative inventory screen refuse with false. true means submitted, not server acceptance: prediction uses the normal menu engine and sends ContainerClick with its state id, changed slots and carried item. Server corrections still win. Inventory reads and direct server-side item transactions keep their existing contracts; a click does not expose direct client inventory writes or enforce a mod's locked-slot policy. Call from an explicit input action rather than submitting every render/tick. Diverges from upstream: new helper.

menu.close(host) closes the menu's screen as Escape does and tells the server (ContainerClose); it returns false while that screen is not open, so the inventory menu closes only while the inventory screen shows. menu.click_button(host, button) presses one of the open menu's buttons (ContainerButtonClick, as a loom's pattern list does), for input the screen's own buttons don't take; the server's menu decides what it does, and the inventory menu has none.

ItemPlace::MenuSlot { menu, slot } is slot slot of a player's open menu, a MenuRef (player.container_menu(host)). It is a fork addition: NeoForge 26.3's ItemAccess reaches a player's inventory slot (forPlayerSlot) and cursor (forPlayerCursor), not a menu's slot. It is the storage the slot shows, named by menu.slot_backing(host, slot) (MenuSlotBacking), and a write goes to that storage through its own handler, so it is kept once by the transaction and the storage's rules hold: the player's inventory, armour and off hand by their ENTITY_ITEMS index, a chest's or a furnace's slot through its ITEMS handler, a chest minecart's or a chested mount's through its ENTITY_ITEMS, and the player's ender chest, inventory crafting grid and a mod's chest menu (open_menu), kept by the game. The slot's own rules come first, as a click has them: menu.slot_holds(host, slot, &stack) is how many of a stack it holds (Slot.mayPlace, then Slot.getMaxStackSize: a furnace's fuel slot one bucket, an armour slot one piece that fits it, a shulker box's slot no shulker box, a result slot none), and menu.slot_gives(host, slot) whether it gives up what it holds (Slot.mayPickup: bound armour stays on outside creative). An insert fills that slot alone, and what doesn't fit stays out. A crafting grid a transaction changed has its result made again at the outermost commit, once for each player however many writes it took (InventoryMenu.slotsChanged, with native_prepare_item_craft); the result slot takes nothing and gives nothing, since taking it is a craft. A menu closed, replaced or reopened since the MenuRef was made, or one whose player left, reads and writes nothing. menu.cursor() is that menu's cursor (ItemPlace::PlayerCursor { menu }, forPlayerCursor), which reaches nothing once the menu is gone, so a kept cursor never reaches the next menu's. The player's screen follows with the tick's container sync.

#![allow(unused)]
fn main() {
// Put four of the menu's offered emeralds into slot 0 of the open chest, or nothing.
let (slot, cursor) = (ItemPlace::MenuSlot { menu, slot: 0 }, menu.cursor());
host.transaction(|host, tx| {
    let took = cursor.extract(host, tx, &emerald, 4);
    if took == 4 && slot.insert(host, tx, &emerald, 4) == 4 { Ok(()) } else { Err(()) }
})
}

A block's fluids

Fluids are the capability FLUIDS (NeoForge's Capabilities.Fluid.BLOCK), answered as items are, by a ResourceHandler<FluidResource> in millibuckets. A FluidResource is a fluid id and its data components, without an amount, kept as an item stack's are (a potion fluid's contents; water and lava have none), and a tank fills only from empty or with the same fluid and the same components. A FluidStack is one with an amount, as tanks keep it (resource.to_stack(amount), FluidResource::of(&stack)). The game's own answer is a mod block's tanks by side (block_entity_fluids) and a cauldron, one tank of 1000 mB that holds water in thirds and lava only whole; a cauldron has no block entity and is answered by position, and a powder snow cauldron holds no fluid. A cauldron takes water and lava whatever their components and discards them, so what comes out of it is plain: the one place a fluid's components are dropped. A mod block's saved tanks take no fluid with components. level.capability(host, &FLUIDS, pos, side) finds a handler in a LevelRef's level, as ITEMS' are found, and move_resources moves fluids as it moves items. A move the target takes only part of is undone and tried again with that part, so a cauldron, which gives whole thirds and never more than asked, gives what fits: asked for a bucket with room for 500 mB, it gives one level, 334 mB.

Fluid held by an item is ITEM_FLUIDS (NeoForge's Capabilities.Fluid.ITEM), found where its stack lives, as ITEM_ITEMS is: place.capability(host, &ITEM_FLUIDS) gives a ResourceHandler<FluidResource> for the item at that ItemPlace, and a write rewrites the item there by an exchange of one, so from a stack of more than one the changed item splits off (r.item_capability(&ITEM_FLUIDS, "mymod:canister", …) answers it for a mod's item). The game answers it for vanilla's buckets: one tank of 1000 mB, filled and drained whole, an empty bucket taking plain water or lava and becoming its full bucket, a full one becoming an empty bucket. move_resources moves between an item and a block as between two blocks: a full cauldron fills a bucket in a player's slot, and two thirds of one fill none.

A block's energy

Energy is the capability ENERGY (NeoForge's Capabilities.Energy.BLOCK), answered by an EnergyHandler: an amount and a capacity, with no resource, and insert and extract written in a transaction as a ResourceHandler's are. r.block_entity_capability(&ENERGY, &battery, …) (with a declared or looked-up type key) registers a provider, asked as ITEMS' are, and level.capability(host, &ENERGY, pos, side) finds one. The game's own answer is a mod block entity's block_entity_energy buffer, as NeoForge's SimpleEnergyHandler: a fill through the sides it comes through, up to the buffer's room and its limit per insert, and a drain by the sides it leaves by, up to the limit per extract; a side that reaches neither finds no handler. move_energy(host, &from, &to, max, tx) moves between two (EnergyHandlerUtil.move) as one step of move_resources: all or nothing, a move the target takes only part of tried again with that part.

Energy held by an item is ITEM_ENERGY (NeoForge's Capabilities.Energy.ITEM), found where its stack lives with place.capability(host, &ITEM_ENERGY), as ITEM_FLUIDS is, and moved by move_energy as a block's is. A mod answers it for its item with r.item_capability(&ITEM_ENERGY, "mymod:cell", …), keeping the energy in the item's own stack and rewriting it by an exchange of one, so from a stack of more than one the charged item splits off. Vanilla has no energy items, so the game answers it for none.

The game never trusts an answer past what it asked or offered. A handler answering more than it was asked has its move undone, in its transaction, and is warned once naming the mod, and move_resources or move_energy returns Overanswered naming it. Returned from the closure of host.transaction with ?, it aborts the whole move, so neither end keeps any of it: a broken handler can't make a move overflow, duplicate or lose items, fluid or energy, or panic the game.

A LivingRef on the server can apply one effect from an item's loaded consumable with living.apply_consume_effect(host, &stack, index). The index is zero-based in component order; this does not eat food, shrink the stack or run consume triggers. Some(true) or Some(false) is the effect's result; None means the item, index or target is unavailable or the effect is unsupported. Mob random teleport, armor stands and dragons are not supported. Player random teleport uses the level random as normal.

Mod-defined kinds dispatch through the ordinary consume_effect hook. For these kinds, Some(true) means dispatch was entered, not that a listener changed game state; an unclaimed kind still does nothing. Reapplying the same kind from inside its own handler on the same call stack returns Some(false) without recursion. Another kind, including one owned by another mod, dispatches normally, and a later independent call can apply the original kind again. This deliberately reverses #550's original blanket exclusion of mod-defined kinds; it is not a second consume hook or an alternate dispatch path.

On a ServerHost, import HostTransaction to call host.transaction(|host, tx| …) (NeoForge 26.3's Transaction). It runs a closure whose Ok commits and whose Err aborts, nested in the open transaction if any. tx, a &Transaction (NeoForge's TransactionContext), is what every handler and place write takes, so none happens outside one. Inside, a capability write applies at once, so later steps see it, and the game keeps each storage as it was before the transaction first wrote it: a block entity's item slots, saved compound and attachments, a hopper's cooldown, a cauldron's block state, a player's inventory (slots, armour, off hand and cursor, whether the player is the host or a guest), an entity's inventory (a chest or hopper minecart, a chest boat, a chested donkey, mule or llama) and an item entity's stack (one emptied stays, empty, until the outermost commit removes it). A nested commit hands its changes to the transaction around it, and only the outermost commit makes them final. Then the world is told of each change once, as SnapshotJournal.onRootCommit: setChanged and comparators, a jukebox starting or stopping, a cauldron's block update, and an item dropped at a block, thrown by a player (what a filled bucket's split no longer fits) or by an entity or split off an item entity. An abort puts every storage back quietly, so nothing outside saw the change. A panic unwinding out of the closure aborts that transaction as it passes, and the one around it stays open. Open one with host.transaction. The game, not the values it hands out, holds the authority, and it keeps writing apart from ending. The closure, like any handler, is lent the Transaction: it names one open transaction by a token the game drew (unguessable in practice), and a write given one that names no open transaction changes nothing. Ending a transaction takes its TransactionSeal, which only host.transaction's guard (or whoever called the raw transaction_open) holds; the raw transaction_close refuses a seal that names no open transaction. So a handler can neither commit the transaction it was lent, nor end one around it, and a value decoded from bytes or kept past its closure does nothing. A transaction left open inside another is aborted when the one around it closes, so a caught panic or an Err still finds the rollback done. A handler keeps no journal of its own: its state is the game's, so the game's journal covers it. Direct writes are not covered: an item entity's stack, LivingRef::set_equipment, and the player and armor-stand slot_set paths take effect and are final at once, even inside a transaction. Any equip/unequip event and equip sound from set_equipment also happen immediately; an abort does not undo them. This differs from writes through journaled capability handlers.

ItemPlace::EntitySlot { entity, slot } is slot slot of such an entity's inventory (NeoForge's Capabilities.Item.ENTITY), read and written like any other place. Reading or writing a minecart's slots unpacks its loot table with no player, as getChestVehicleItem does.

A mod's own capability

A mod can define a capability of its own, as Mekanism defines chemicals: a resource type and a key, published from its root crate (Dependencies between trait mods) for other mods to use.

#![allow(unused)]
fn main() {
// The chemistry mod's root crate
#[derive(Clone, PartialEq)]
pub struct Chemical(pub String);
pub const CHEMICALS: CapabilityKey<dyn ResourceHandler<Chemical>> = CapabilityKey::new("chem_api:chemical");
}

A mod that names it under [dependencies] builds against the same Chemical and CHEMICALS, so its providers, r.block_entity_capability(&chem_api::CHEMICALS, &vat, …) (where vat is a declared type key or r.block_entity_type_key("chem_pipe:vat")), answer the same capability, and level.capability(host, &chem_api::CHEMICALS, pos, side) finds either mod's handler. move_resources moves a chemical as it moves items, in the caller's transaction. The game has no answer of its own for a mod's key, so only the mods' providers do, and a lookup with none registered costs one table check. A handler that keeps its amount in its block entity's saved data (BlockEntityRef::merge_data) is covered by the game's journal, so an aborted transaction puts it back. ItemCapabilityKey::new and EntityCapabilityKey::new define item and entity capabilities the same way.

A key is known by its name, which must be namespaced (chem_api:chemical), and a name has one handler type. Two mods that each declare their own Chemical under one name, rather than sharing the defining mod's, would never see each other's handlers. So the game refuses that at startup, naming both mods and both types, and it refuses a key whose name has no namespace. Both checks run once, when the mods register.

Entity parts and mob goals

r.entity_part("minecraft:zombie", ZombieGoals) attaches an EntityPart to one entity type, a mod's own or vanilla's. Its method register_goals runs at every Mob construction of that type — spawned or loaded, the moment vanilla's registerGoals fan-out ends — and the goals it adds join the mob's two selectors beside the species' own, with the same priorities, flag locks and interruption:

#![allow(unused)]
fn main() {
struct ZombieGoals;
#[mod_api::horizon_part]
impl EntityPart for ZombieGoals {
    fn register_goals(&self, goals: &mut GoalRegistrar<'_>) {
        // goals.mob().id() is "minecraft:zombie": branch as per-species code does.
        goals.add_goal(7, Stare::default());
        goals.add_target_goal(3, Remember::default());
    }
}
}

goals.add_goal(priority, goal) and goals.add_target_goal(priority, goal) are GoalSelector.addGoal on the mob's two selectors; GoalFlags claims MOVE, LOOK, JUMP and TARGET as vanilla's Goal.Flag does, and a higher priority (a lower number) interrupts a running goal holding the same flag. A goal object is per mob, built fresh at every construction, and its state is never saved: a goal that needs memory across loads keeps it in attachments. A mob whose type has no part, or a game with no entity parts at all, pays nothing — the wrapper and the tick's read view exist only where a mod goal runs.

A Goal reads and writes through its GoalContext: mob() is a fresh handle of the mob it runs on, host() the tick's read view, random() the mob's own random (mob.getRandom(), so a mod's draws keep the mob's stream in shape). The read view answers the ticking mob itself directly, the player the tick sees, and every other entity from the tick's snapshot — a getEntities of the moment the mob list was taken out — so a read the snapshot does not carry (a mob's gear or effects, its species id) answers None, and the handle docs mark the reads that carry the snapshot rule. Writes apply to the mob itself through the engine's own paths: move_to(pos, speed) and stop_navigation() (PathNavigation), look_at(pos) (LookControl), jump(), and set_target(Option<LivingRef>) (Mob.setTarget, with the write handle's rules: a fox, an enderman or a zombified piglin stores it with its setter's side effects, and a brain-backed species refuses, since its target is a brain memory that MobRef::set_brain_target writes from a server host). Writes to other entities are not part of a goal; the write handles a ServerHost takes do not exist in a goal tick. Clearing a fox's target ends defending without changing its trusted entities. An enderman's target controls its creepy flag and attacking speed modifier; clearing it also clears its stared-at flag. A zombified piglin schedules its first anger sound and next alert when it acquires a target from none, not when switching between targets. Targeting a player does not count as player damage.

Brain behaviors

Native mods only: entity parts do not cross to wasm yet.

EntityPart::register_behaviors receives a BehaviorRegistrar whenever a brain-driven species builds or rebuilds its brain. Use add(activity, priority, min_duration, max_duration, requirements, behavior) to join a fresh Behavior to the species' supported activity. Registration returns a BehaviorRefusal for an unsupported activity or invalid duration. Behaviors start and stop in vanilla Brain.tick order: priority, activity bucket, then insertion order, with mod behaviors after vanilla behaviors in the same bucket. Their state is not saved. BehaviorCx provides the mob, host, random source and typed brain memory access; each species refuses memories it does not support.

The part's other method, spawn_cluster_size, changes how large a natural spawn group of the type grows (Mob.getMaxSpawnClusterSize); controlling spawns shows it.

Entity parts are a native mod's for now: the goal surface does not cross to wasm (see the attach_entity_part note), so r.entity_part is absent from a wasm build.

Block-state facts

A BlockState is an API-owned value pairing a BlockKey with a block-local canonical ordinal, not a numeric engine state ID or a live object. Facts that need no world are a small read-only service on any host, both sides: host.block_states() (import HostBlockStates). Each reads the game's own tables through checked crossings. Fact queries and matching allocate nothing; definition copies the property data for the caller. Property operations on BlockState borrow explicit immutable block metadata; block() and ordinal() need no host:

Use StateConstraint for each partial constraint; StateMatchError identifies an invalid property or value by index. StateProperty describes a property's legal values. These types are shared by state-definition services.

None for an unknown state or block, including an invalid local ordinal, and on a host with no game behind it (a mod's test double). The ordinal order is defined by the complete canonical property constraints, not by the engine's numeric enumeration.

Fluid-state facts

Import HostFluidStates to reach host.fluid_states() on either owning side. definition(key) returns Some(FluidDefinition::World { default, properties }) for a world fluid, Some(FluidDefinition::TankOnly) for a registered tank-only fluid, and None without a loaded registry. The properties and typed default come from the loaded preparation, not a second vanilla table. These metadata reads are available in setup, reload and world callbacks after the fluid keys resolve, not during registration or configuration.

validate(key, constraints) checks partial StateConstraint values in input order without matching any particular state. It returns Result<(), FluidStateError>: UnknownProperty(index), InvalidValue(index) or Duplicate(index) identifies the first offending input. NoWorldState means the fluid is tank-only or the host has no definition; use definition to distinguish them.

type_properties(key) returns a FluidTypeProperties record, or None without a loaded registry or for a key it doesn't hold; host.fluid_key(name) is None for an unknown name. The record is the same in every level: description_id, light_level, fall_distance_modifier, and whether the fluid can push entities, be swum in, drown, extinguish, hydrate and carry boats. Flowing forms answer as their source. The empty fluid and tank-only fluids emit no light, do nothing to an entity and have a fall modifier of 1. Anything that depends on a level, such as lava's current or source conversion, isn't in the record. The record also carries three Fluid facts: explosion_resistance (100 for water, lava and a mod's world fluid, 0 for the empty or a tank-only fluid), randomly_ticks (lava only) and drip_particle (minecraft:dripping_water or minecraft:dripping_lava, none for the rest).

legacy_block(state) is FluidState.createLegacyBlock: the water, lava or mod-fluid block that holds a fluid state (a source is level 0, a flowing amount is 8 - amount, falling adds 8) and air for the empty fluid. It is None for a state no fluid can be in: a tank-only fluid, an amount above 8, a zero amount for anything but the empty fluid, or a source that isn't full.

What depends on a position is on LevelRef, not in this service: fluid_tick_delay(host, fluid, pos) (water 5, lava 30 and 10 in the Nether, a mod fluid's as its fluid_rules parts change it there), fluid_height, fluid_height_for_camera and fluid_can_be_replaced_with(host, pos, fluid, direction). fluid_tick(server, pos) runs a fluid's flow step now; schedule_fluid_tick queues one.

FluidState::matches(constraints) is a pure local check of carried vanilla fields. Unknown properties or noncanonical serialized values return false. A falling source remains a source; a flowing state of level 8 remains flowing. Empty constraints match any state. Validate separately for indexed errors. Neither matching nor validation allocates; explicitly copying a definition may allocate. Unresolved saved tank identities remain FluidIdentity::Unresolved(handle), not world states or tank-only keys.

Fake players

host.fake_player(level, uuid, name) makes, or finds again, a player with no connection in the level in place, as NeoForge's FakePlayerFactory does: a machine that acts as a player (a deployer, a block breaker). It is no online player: the tab list, player counts, sleeping, natural spawning, chunk tickets, statistics and saves leave it out. player.is_fake(host) tells one apart; player.remove_fake(host) removes it.

player.perform_action(host, action) makes it act as a player does, through the game's own path for the action, as that player's packet would run it:

• PlayerAction::UseOn { hand, pos, hit } is a click on a block (ServerPlayerGameMode.useItemOn): reach, the hit's place on the block, the build height, spawn protection and the border, then the block's use and the item's useOn, which is how a block item is placed;
• PlayerAction::UseItem { hand } is a use in the air (ServerPlayerGameMode.useItem), by the item's own ray from the player's eyes and look: a bucket clicked on a block passes, as vanilla's does, and empties when used.
• PlayerAction::InteractOn { hand, target, location } interacts with that entity (Player.interactOn), after the border and interaction-range checks, with the hit relative to its origin. A passed click does not fall back to using the item in the air. The fake keeps its own supplied look, rather than aiming a new ray;
• PlayerAction::Attack { target } is a hit with the main hand (handleInteract's ATTACK, then Player.attack): the border and the attack range, the native mods' attack_entity, then the blow on a player, a mob or another entity, or a fireball, wind charge or shulker bullet turned back. The blow is scaled by the attack strength, as a player's is, so a fake that hits every tick does a fraction of a full blow. A mob doesn't take the fake as the player to answer;
• PlayerAction::BreakBlock { pos } breaks the block at once (ServerPlayerGameMode.destroyBlock): reach, the build height, spawn protection and the border, then the game mode's and the held tool's rules (adventure mode can't, a sword in creative can't, and outside creative a block no digging breaks, destroy time -1 such as bedrock, stays), the native mods' break_block, the tool's wear and the drops. There is no digging time: a machine that digs over time counts its own progress and breaks the block when it is done.

Its items are its own inventory: set the stack in its hand first (through ENTITY_ITEMS or an ItemPlace), and read what is left after. The answer says what happened:

For a machine using an isolated stack, player.perform_action_scoped(host, action, setup) composes that same persistent player's action with temporary state. Build PlayerActionSetup::new(stack, eye, yaw, pitch, secondary_use): the fake acts in survival with a fresh standing body (eye height 1.62), that stack in its main hand, and no other inventory or equipment. Its supplied rotation is used for item rays. Secondary use holds semantic sneak without changing that standing eye height. No second player is created.

The ScopedActionResult contains outcome (the same ActionOutcome), held (the nonempty main-hand remainder) and other (other nonempty inventory stacks, then offhand, carried stack and armor). These stacks are returned to the caller, not kept by the fake. The fake's persistent body, inventory, game mode, look, secondary-use state and action timers are restored even on refusal; world changes and the usual interaction/Parts hooks remain. The ordinary fake safety rules still apply: no screens, sleep, rides, dimension travel, online participation, statistics, advancement credit or network connection. Neither action method can run inside another player turn or an open transaction; the action's own ordinary write paths still run transactionally.

On either side, player.entity().is_shift_key_down(host) reads semantic secondary use rather than a physical key mapping or a crouching pose. On the client obtain the reachable local handle with host.local_player() (or host.entity(id)); it reads live secondary use even before the next movement tick updates the body's shift flag. On the server the existing entity flag is read, including a scoped fake's setup. Stale handles and clients without a joined local player return None.

What a machine does beyond a player's action stays in the mod: its own mining progress and catching world drops. Scoped actions retain player reach, protection and border checks; eye placement is supplied by the mod.

Testing a trait mod

Enable the testing feature on the mod's horizon-mod-api test dependency. Then testing::with_mods takes an owned Mods list and runs a closure with it installed on the current thread. It restores the previous list even if the closure panics. The test allocation is retained because dispatch exposes a static slice. Call dispatch_<hook>(&mut host, args…) inside the closure to build the event as the game does.

testing::FakeHost is a server and client host built from one small fake per service, so a test runs without the game: registries (item reports, items with slots of their own, the loaded mods), players (who is online, their inventories by slot, what was given to them and shown on their action bar), level (blocks, block entities with item slots, fluid tanks and energy storage as the game answers them, and entities), commands and messages (what ran and what was said), and journal, which keeps the players and the level on each transaction and puts them back when it aborts. Set the world up through those fields, run the code under test with &mut host, then read the fakes back:

#![allow(unused)]
fn main() {
use mod_api::testing::{FakeHost, with_mods};
use mod_api::{self, ClientHost, ClientTickPreEvent, Hooks, ModEntry, dispatch_client_tick_pre};
use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};

#[derive(Default)]
struct Counter(Arc<AtomicUsize>);
#[mod_api::horizon_mod]
impl Hooks for Counter {
    fn client_tick_pre(&self, _: &mut dyn ClientHost, _: &mut ClientTickPreEvent) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}
let count = Arc::new(AtomicUsize::new(0));
let mods = [ModEntry::new("counter", Box::new(Counter(count.clone())))];
with_mods(mods.into(), || dispatch_client_tick_pre(&mut FakeHost::new()));
assert_eq!(count.load(Ordering::Relaxed), 1);
}

A test of item moves puts two chests in the level and reads back what went where; the transaction's journal is the fake's:

#![allow(unused)]
fn main() {
use mod_api::testing::FakeHost;
use mod_api::{HostTransaction, ITEMS, ItemResource, ItemStack, ServerHost, move_resources};

let mut host = FakeHost::new();
let level = host.level.level();
host.level.block_entity([0, 64, 0]).with_items(1);
host.level.block_entity([1, 64, 0]).with_items(1);
let stone = ItemStack { item: "minecraft:stone".into(), count: 5, damage: 0, extra: None };
host.level.block_entity([0, 64, 0]).items.as_mut().unwrap().slots[0] = Some(stone);

let server: &mut dyn ServerHost = &mut host;
let from = level.capability(server, &ITEMS, [0, 64, 0], None).unwrap();
let into = level.capability(server, &ITEMS, [1, 64, 0], None).unwrap();
let moved = server.transaction(|host, tx| {
    move_resources(host, &from, &into, |_: &ItemResource| true, 3, tx)
});
assert_eq!(moved.ok(), Some(3));
let into = host.level.block_entity_at([1, 64, 0]).unwrap().items.as_ref().unwrap();
assert_eq!(into.count("minecraft:stone"), 3);
}

A Host method no fake answers panics naming it, as every Host method defaults to, so an unexpected call fails loudly. A test can still write its own double for what the fakes don't model, implementing only what its hook calls; testing::FakeJournal gives such a host the same transaction journal over its own state.

If a Host method returns a game value a test can't build, a double can return None instead, as with Players::acting_player() -> Option<PlayerRef>. If the dispatch function itself takes an unconstructible value, such as dispatch_perform_command's &ServerPlayer, test the logic beneath the hook instead. The level hosts are small enough to implement whole. NeoForge's GameTest is the in-game counterpart.

Adding a hook

A new hook needs its declaration in the area file of crates/horizon-mod-vocab/src/hooks/ (/// lines and #[hook(side = "server", contract = "cancel", out = "cancel")] on fn name();; the argument list is in that folder's mod.rs), its native_* function with the placeholder body let _ = (every, parameter); (all its parameters, in order), and a run of cargo run -p xtask -- mod-api. Put that function in crates/horizon-client/src/game/native_hooks/<area>.rs, matching the declaration's area filename. Alternatively, a named hook may live in any logical module under game/, including area folders, mod.rs and #[path] modules. Its target must name that module and Game<'_>::native_<name>. Exactly one matching Game method must exist. Outside native_hooks/, the method must call dispatch_<name> itself: placeholders are not filled there. Remove macros, cfg and cfg_attr from that method so injections can patch it. A refusal names the hook and what to change. These checks run at build time and add no dispatch-time work. The build discovers native hook modules automatically; do not add a module list entry. Shared support lives in shared.rs; fire.rs includes generated dispatch entry points, not hook implementations. That command only replaces the placeholder in its owning area file with the dispatch_<hook> call; commit that source change and the declaration. Fills are idempotent; rerun the command after a failed write. The horizon-mod-api-gen build dependency generates the hook traits, Host methods and dispatch code into Cargo's OUT_DIR when the game and renderer build, including release builds. These generated Rust files are not kept in the source tree or committed, and no manual regeneration is needed after a merge. Every hook needs a mod_api entry: the build fails naming any hook without one. A hook that stands in for a method a vanilla block, block entity, item or menu overrides also gets a scope and a key ({"contract": "collect", "out": "output", "scope": "block", "key": "state"}): the key is a BlockState (routed by its prepared block key for block parts), an &ItemStack, a ModBlockEntity or an id &str, and the generator also puts the method on that scope's part trait (Parts). A body that is neither the placeholder nor already calls the dispatch is an error, and the generator never changes it. Hooks that are free functions outside Game are wired by hand: those crates can't see the mod list, so each calls a callback the executable installs once, such as NativeLoadHooks in horizon-world and NativeClientHooks in the client library (menu_slot_rules, living_breathe, ingredient). A build reports a placeholder still to fill instead of changing hand-written source; run cargo run -p xtask -- mod-api to fill it. Mixin injections go at the head of the body, before the dispatch, so they still run first.

Server attachments

A mod can declare an AttachmentType<T> once and call its get, set, remove, has and get_existing methods with the hook's host and a Holder. T is Clone + Send + Sync + 'static; get returns a clone and inserts the default on first access. has and get_existing read without inserting (NeoForge's hasData and getExistingData): has says whether a value is stored, saved or set, even before it decodes, and get_existing returns None instead of the default. Neither adds anything to the holder's saved data. set runs the optional codec before changing the value, returning an AttachmentError if it cannot encode. Keys are the pair (namespace, name); a key already decoded as another Rust type is an error. On a server, a missing holder is an error, not a new phantom holder; a client keeps a copy for any holder it is asked about (see the sync paragraph below). AttachmentError distinguishes MissingHolder, TypeMismatch, Decode, Encode, InvalidNamespace (a malformed saved compound), InvalidCopyPolicy (death-copy without a codec) and InvalidSyncPolicy (sync without a codec). Every host is an AttachmentStore (and host.attachments() gives it): the typed methods stand on its few erased ones, so they work the same in a native mod and a wasm mod. A value keeps its own Rust type, shared: reading one clones it out, and copying a holder's data copies no value.

AttachmentHolder keeps an existing typed handle when a system needs to store a holder identity: Entity, Player, BlockEntity, Chunk or Level. It is Copy, does not keep anything loaded, and follows each handle's ordinary stale-world and unload rules. Unlike the storage-relative Holder, it carries the handle's world scope.

Import AttachmentQueries to use host.query(&TYPE) on either host side. The returned batch is a snapshot of membership and stored value bindings in the host's current dimension. Its iter() borrows &T without cloning values and lazily decodes saved entries; malformed or incompatible values produce row errors, not defaults. Later sets, removals and unloads appear only in fresh queries. This is a residency view: an entity queued for removal but not yet swept can still appear. Captured handles do not keep holders loaded, and stale writes fail. Interior mutability inside T is not deep-frozen by a snapshot.

On a server, import AttachmentQueriesMut for host.query_mut(&TYPE) (T: Clone). Each borrowed row has holder(), value(), and explicit set(host, replacement) / remove(host) methods. These validate residency against the host's current dimension and then use the ordinary attachment journal. There is no &mut T, implicit transaction, or commit on drop: wrap a system in host.transaction for all-or-nothing writes. Unload or replacement produces AttachmentRowError::StaleHolder. Rows retain captured values even after successful write-through updates.

Traversal follows dense index order: insertion appends, and removal fills its slot with the last row. The same ordered mutation history is deterministic, but the order is neither sorted nor stable across structural changes. Retaining a batch can make the next live mutation copy row metadata and shared pointers once; retaining many batches keeps their old bindings alive. Native acquisition clones only the bucket Arc. Erased values from an incompatible type domain report TypeMismatch rather than falling back to saved decoding.

#![allow(unused)]
fn main() {
use mod_api::{AttachmentCodec, AttachmentError, AttachmentType, Compound, Holder, Tag};

static COUNTER: AttachmentType<i32> = AttachmentType {
    namespace: "example", name: "counter", default: || 0,
    codec: Some(AttachmentCodec {
        encode: |n| Ok([("count".into(), Tag::Int(*n))].into()),
        decode: |data: &Compound| match data.get(&"count".into()) {
            Some(Tag::Int(n)) => Ok(*n), _ => Err(AttachmentError::Decode),
        },
    }),
    copy_on_death: false,
    sync: false,
};
// Inside a server hook, or mixin code, with `host: &mut dyn ServerHost`:
if !COUNTER.has(host, Holder::Chunk([0, 0]))? { /* chunk carries no counter yet */ }
let old = COUNTER.get(host, Holder::Chunk([0, 0]))?;
COUNTER.set(host, Holder::Chunk([0, 0]), old + 1)?;
Ok::<(), AttachmentError>(())
}

For mixin code, see The typed API from mixin code.

Use Holder::Level, Holder::Chunk([x, z]), Holder::BlockEntity([x, y, z]), Holder::Entity(id), or Holder::Player(uuid). Entity IDs cover every entity in the level apart from players: mobs, items, experience orbs, projectiles, tridents, falling blocks, primed TNT, fireworks, boats, minecarts, armor stands, cushions, item frames, paintings, End crystals, the ender dragon, ominous item spawners and the server's OtherEntity records. An entity keeps its UUID through saves, so its saved attachments load back with it; an orb saved with a count above one loads as several orbs, and only the first keeps the attachments. Player UUIDs cover online guests and the acting player. Mutable level hosts can access their level, loaded chunks and block entities; read-only level hosts cannot access attachments. Unserialized values disappear on unload or restart. A saved value is stored under horizon:attachments, then the mod namespace and attachment name, as {value: <compound>, copy_on_death: 1b, sync: 1b} (a flag is omitted when false). Unknown mods' saved entries survive load and save without being decoded. Level attachments use the dimension's data/minecraft/horizon_attachments.dat SavedData file, not level.dat.

A type with sync: true sends its value to Horizon clients when get creates the default, on set and remove, and on demand with AttachmentType::sync_data(host, holder); changes made in one tick are sent once, at its end. The recipients are the players who track the holder: guests who were sent a chunk for a chunk or block entity, who track an entity for an entity, the player and those tracking them for a player, and everyone in the level for the level. A client also gets all of a holder's synced values when it starts seeing it: a chunk sent (with its block entities), a level joined or re-entered, an entity tracked, and its own player. With no native mod loaded nothing is sent. The wire form is the codec's compound, so sync requires a codec.

Only Horizon clients are sent values. A message with a namespace or name over 256 characters, a value that cannot be written or a payload past 1 MiB is not sent.

On a client, Host::attachments returns a copy of what the server synced, which get decodes; set and remove change only that copy, which is dropped when the chunk, entity or player goes. A client keeps no copy for the level hosts (LevelRandomHost): they stay server-only there, though their changes on a server are synced.

copy_on_death requires a codec. Player respawn copies opted-in entries via their encoded representation, including raw entries of an absent mod; other entries are removed. Living-entity conversion is not supported. This follows the default supplier, optional server-side persistence, player-respawn option and sync with a StreamCodec (with syncData) of NeoForge 26.3's public AttachmentType.Builder contract, and IAttachmentHolder's hasData/getExistingData, but not its holder-aware supplier, custom copy handler, conditional serialization, the sendToPlayer predicate, AttachmentSyncHandler partial updates or a wire codec apart from the disk codec.

The API owns these public names. Their engine-independent storage and query index live in horizon-mod-runtime, which depends only on the shared vocabulary in horizon-core; world and game storage use the same implementation.

Host exposes the documented Game helpers declared by area in crates/horizon-mod-vocab/src/host/<area>.rs, one trait per area; Host, ServerHost and ClientHost are the unions of those traits, so a mod calls through them and never names an area trait. Each helper keeps its receiver and documentation; a helper without self (config_files) takes &self in Host. Level services stay on the level hosts above. For the per-method comparison with NeoForge's block, item, entity, block-entity and fluid extension interfaces, including which gaps are tracked, see NeoForge extension coverage. For item registry facts, host.item_crafting_remainder(&stack) returns a count-one plain remainder stack, or None when there is none or the item is unknown. Horizon currently stores only the remainder item id, not a template's count or components. host.block_item(stone) returns its item registry name; an unavailable block mapping returns None, while a known block with no item returns Some("minecraft:air"). Both reads are available on either side.

For engine contributors, every area method declares its load access once with #[access(...)]. Metadata admits registry facts during setup and reload; WorldOnly, ClientSetup and PublishedResources retain their phase-specific contracts. The area's host_area attribute builds the test-double defaults, and the API generator emits every game forwarder at build time. Implement only the inherent Game function with the same name, not a hand-written forwarder. Static implementations use #[static_call]; service accessors use #[service]. A helper's receiver also exposes it on that handle. Receivers come from public *Ref structs in mod_api.rs: BlockEntityRef gives block_entity, for example. Adding a handle requires no separate generator registration. The following documented Game helpers are not in the trait yet:

• spawn_mob, mob, mobs, block_in_tag, item_in_tag, server_block_in_tag, server_item_in_tag, server_block, set_display, sidebar, experience_orbs, item_entities, player, panel_recipes, recipes, component, set_component, remove_component, spawn_falling_block, explode, container_slots uses gameplay-private types.
• with_mod_block_entity is generic, so its signature cannot be called through dyn Host.

Experience-orb values use vanilla's signed i32 representation in ExperienceOrb, ServerHost::set_experience_orb, and the pickup and merge hooks. Reading or changing a value preserves zero and negative saved values rather than clamping them through an unsigned representation. A negative value does not grant positive experience when picked up.

Advancement triggers instead live on PlayerRef::trigger_criterion, with a mod-owned CriterionTest and the game's scoped CriterionContext resource. The context keeps real world-aware item predicates; it is not a conditions-only snapshot. See advancement triggers for the contract and the wasm runtime's current same-group callback limitation.

A mod that consumes a block use can run vanilla advancement predicates and rewards through PlayerRef::trigger_block_use(host, pos) or PlayerRef::trigger_item_used_on_block(host, pos, original, after). These server operations use the player's own level and never read inventory. Default use fires default_block_use, then any_block_use, both without a tool: the default helper is specifically tool-free, not general default block use while holding an item. Item use fires item_used_on_block against original (copied after a before-block PASS and before block/item effects), then any_block_use against after (that original hand stack mutated in place, excluding a replacement swapped into the hand), in that order. Consuming right-click/before-block cancellation already fires automatic any_block_use only; do not call either pair helper for it, which would duplicate any and add an inner trigger. This follows ServerPlayerGameMode.useItemOn and ServerGamePacketListenerImpl.handleUseItemOn; the predicate evaluators are DefaultBlockInteractionTrigger, ItemUsedOnLocationTrigger, and AnyBlockInteractionTrigger.

Ok(()) means the player was reached, even if no criterion matched. Failures are NotServer for a remote client, PlayerUnavailable for a stale, offline or displaced handle, UnloadedChunk for a position outside loaded chunks, and Stack(StackWriteError) when the item boundary rejects either stack before any trigger fires. Native and wasm use the same generated operations. The minecraft: guard on trigger_criterion remains: this grants no general access to fire arbitrary vanilla triggers.

The following catalog hooks are not in the trait:

• player_command, item_decorations, client_resources_reloaded, camera_shake, screen_key_pressed_pre, screen_char_typed_pre, screen_mouse_scrolled_pre, use_duration, use_animation, can_eat, living_entity_use_item_start, living_entity_use_item_finish, render_hand, shader_params and block_highlight.
• biome_colors, camera_distance, compute_fog_color, compute_fov, data_pack_files, mob_submit, mouse_button_pre, mouse_button_post, player_respawned and tags_updated.

The client render_tooltip_texture hook (NeoForge's RenderTooltipEvent.Texture) picks a tooltip box's look. Setting texture to a tooltip style <namespace>:<name> draws the GUI sprites <namespace>:tooltip/<name>_background and _frame from the resource packs, nine-sliced by their gui.scaling metadata or stretched without it, as vanilla draws an item's tooltip_style; the atlas a resource reload restitches is the one drawn. Left None, the box keeps Horizon's solid fills, whose background and top and bottom border gradient colours it changes as mutable ARGB u32 values; it does not change text colours. It covers solid-fill item tooltips (including creative, recipe book, chat, trading and bundle-selected item names), screen text boxes, and native panel tooltips. The stack is None for text-only boxes, including recipe-book item lines where the stack is discarded before drawing. Sprite-based screen tooltips (including options and title screens) use a separate renderer and are not covered.

Tooltip component geometry

render_tooltip_gather_components preserves the mixed text/image list, including an image inserted immediately after the name. Wrapping splits text in place. The text pass visits the entire list before the image pass starts; both passes advance through the same component heights, with 2 extra pixels after the first component of an item tooltip. Each image callback receives the box's left edge and its own running top, but the whole content box size, not TooltipImage.size. That field is the component measurement used to reserve space. The box width is the widest component; its height is the sum of heights, minus 2 normally, with no subtraction for item tooltips containing multiple components. Text components measure 10 pixels high. Factory registration and selectable fonts are separate capabilities, not provided by this geometry contract.

Camera and collision reads

ClientHost::is_paused() reads the applied client pause state, not whether a pause screen is open. A multiplayer game continues running while its pause screen is open. The pause-change pre hook sees the old state; the post hook sees the new state.

ClientHost::playing() is true while the player is in the world with nothing over it: no screen, title, sign editor or book, so keys and zoom apply. ClientHost::mapping(name) reads a vanilla key mapping (key.forward, key.left, key.back, key.right, key.jump, key.sneak, key.sprint, key.attack, key.use) as a KeyMapping: whether it is held (KeyMapping.isDown) and the label of the key it is bound to, as Controls shows it. It is None for any other name. Both read without &mut, so the HUD and screen hooks can ask them.

ClientHost::clipboard_text() reads the system clipboard (KeyboardHandler.getClipboard, empty text when it holds none) and ClientHost::set_clipboard_text(text) writes it (setClipboard; empty text copies nothing). Both work only while the game handles a key, mouse or typed-text event, from the window or from the control socket (horizon-ctl key, mouse, type and its clicks): a key, mouse or screen hook that fires inside one, such as Ctrl+V into a mod's own field. At any other moment (a tick, a frame, a packet) the read is None and the write is false with nothing copied, so no mod reaches the clipboard without the player doing something. Both are None and false on a server, and take &self, so a screen hook can call them. Vanilla's KeyboardHandler has no such rule: Horizon adds it.

The camera() helper returns the most recently extracted world frame's camera, or none before one exists. Its position, interpolated eye height, partial tick, angles, final FOV, near/far planes and dimension accompany column-major view and projection matrices. The view is camera-relative and includes bob and spin; projection uses reversed Z. Earlier callbacks in a frame can see the previous frame. block_collision(pos) returns block-local [min_x, min_y, min_z, max_x, max_y, max_z] boxes with an empty collision context; unloaded blocks and collision errors give no boxes.

ClientHost::set_camera_type(type) is a queued client-only effect and takes &self, so shared callbacks such as camera_pose can request a perspective. camera_type() reports the latest request immediately; several requests coalesce to the last one. Requests before or during camera_pose apply before that frame's final camera, FOV and spectator post effects. The pose hook runs only once: its explicit position or angle overrides survive a refreshed vanilla camera. Requests from later render callbacks apply at the next frame's extraction. Setting a type never emits camera_type_cycle; F5 alone cycles, and its final event choice wins over requests made inside the cycle callback.

ClientHost::crosshair_target() returns the ordinary interaction-range target as CrosshairTarget::Block { pos, state, hit } or CrosshairTarget::Entity { entity, point }. The block hit contains its world-space location, face and inside flag; the entity point is also in world coordinates. It uses the game's current targeting ray and block/entity reach, respects blocks occluding entities, and returns None on a miss or without a client world. It can be read with a screen open. entity is an EntityRef carrying the current client level's epoch and network entity ID, including dragon parts. It becomes stale when the client level is replaced or the client disconnects; a same-level respawn keeps its epoch. This supplies identity, not client entity reads: the server-only entity data methods still reject client handles. Unlike view_hit and raycast, this does not find blocks in distant terrain or return a block behind a targeted entity.

Combat targeting

ClientHost::targeting() and set_targeting(ClientTargeting) control liquid picking, entity occlusion and an optional crosshair entity override. Defaults preserve ordinary vanilla targeting. Set pick_liquids to include source and flowing fluid shapes, or hit_through_walls to ignore block occlusion for entity picks and attacks. An entity override must name a live entity in this client level; stale or self handles make the setter return false without changing the controls. The setter requires a logged-in client world. An override is rechecked for reach, held-item range and occlusion when used and disappears from reads after its level is replaced.

Reach remains attribute-backed: use the server player's living handle and set_attribute_base(host, "minecraft:block_interaction_range", value) or "minecraft:entity_interaction_range". The client's cached reach follows the server's attribute updates. Client targeting controls do not grant extra server reach.

client_attack_target receives a mutable targets list before an ordinary melee click (spear jabs use their existing path). It starts with the crosshair entity. Replace it for redirection, append for multiple hits, or clear it to suppress an entity attack. Flow::Cancel cancels the batch. There is no batch cap; duplicates are sent once in first-occurrence order. Each target is checked again against live handles, attackability, reach, held-item range and the occlusion control. Clearing an entity hit does not mine the block behind it; an empty list on a block or miss keeps the ordinary path. Each accepted hit uses normal attack packets and prediction. Server validation and cooldowns still apply. Native and Wasm mods use the same typed API. Conditional, numeric and categorical item model properties and item tint sources receive an API-owned ItemStack snapshot. The engine's resolver keeps its own StackView; that engine type is not part of mod_api. This applies to nested bundle contents as well as the outer item being drawn.

bundle_selected is the runtime bundle selection index: -1 means none. It is not a saved component and is deliberately separate from the stack's component patch. The patch contains explicit overrides and removals, not merged defaults. The host is &dyn ClientHost for each callback. Only answer property names or sources the mod owns; unanswered callbacks retain their existing defaults.

ItemTintSourceEvent.config is a borrowed Tag, converted once from the tint's JSON definition at load. Read fields with Tag::get and match tag variants. Invalid payloads refuse model loading; resolving a tint does not convert or clone its payload.

A native or wasm listener sees the same owned values. Snapshot construction occurs only after the subscription check, so a model resolution with no listeners does not allocate or encode a snapshot. An empty or unresolved resolver view does not dispatch an invalid stack; its property or tint retains the unanswered default.

ItemStack is the mod API's own nonempty value, not an engine inventory slot or a borrowed rendering view. It contains an ItemKey, a nonzero count, an optional numeric damage override and a lazily allocated component patch. Plain stacks allocate no component storage. An empty slot or a consumed stack is None; it is never a zero-count ItemStack.

Every loaded item, vanilla or modded, has an ItemKey. Resolve identifiers through Host::item_key once when loading data and retain the key. Forward references requested during registration keep their slots when the load completes; unresolved references refuse the load. Keys are process-local identities, not persistent names. Tags likewise have retained TagKey identities, while their item and fluid membership is read through Host::tags and changes on reload. Unknown tags are empty; unavailable authoritative mappings return None.

Stored values and effective components

Count and component edits do not consult the game. new refuses zero; set_count and grow refuse invalid or overflowing counts without changing the original value. Consuming split and shrink return optional portions so consuming the last item needs no empty sentinel.

The damage representation has three states:

damage() returns the stored number or zero. damage_component() distinguishes an explicit zero from no numeric override. set_damage(u32) is infallible; the game validates its effective maximum when accepting a write. Adding only a maximum-damage override to an item does not invent a damage component: explicitly adding Some(0) is what makes that component present.

All numeric damage lives in the optional field. Raw damage entries normalize out of the component patch; malformed numbers, conflicting numeric values, or a simultaneous value and removal refuse the entire replacement. Generic component setters and raw set_components therefore return Result. A refusal leaves the stack unchanged. Typed damage setters do not need an error path.

ItemResource::with_component is also fallible for raw component values. Its default-value elision and without_component preserve the normal prototype-plus-patch semantics. The latter records real NBT removal entries for default components; it is not an unknown-value fallback.

Game boundaries

A consume or death-protection override whose opaque native effect payload cannot be decoded refuses the whole stack write with StackWriteError::InvalidEffectPayload, before any resident state changes. The engine's infallible preserved-component setter remains infallible: invalid replacements retain its prior raw component and decoded cache rather than erasing them.

The items host area owns metadata reads such as max_stack_size(ItemKey) and max_damage(ItemKey). A stack does not take a host just to read a maximum, and an unavailable maximum never turns into a fabricated limit of 64.

The game validates effective count and durability limits, including component overrides, when accepting a resident write. An effective max_stack_size must be in 1..=99, and the presence of max_damage forbids a stack limit above one, even when the current count is one. Removing max_stack_size uses the absent limit of one. Invalid values produce typed errors, not clamped values. A transfer request is different: ItemResource plus a separate amount can request or return more than one resident stack's capacity. The resident writes it produces still have to pass validation.

Game inventory, menus, trades and models keep their engine-owned representations. Native hooks and host methods exchange owned API snapshots. The game converts only after a listener guard, and stages every mutable result before committing any captured output. Invalid hook edits retain those captured engine values. Consuming mutable events such as bonemeal and item_after_vertical_collision lend Option<ItemStack> so a listener can consume the value by setting None.

The item_stacked_on_other bridge commits its clicked slot, cursor and cancellation flags as one unit, including the menu's slot-operation queues and map-id reservations. The block-entity tick, menu-button and menu-quick-move bridges validate their captured snapshot outputs together before applying them. These are output guarantees, not whole-world transactions: independent ServerHost storage writes, commands, messages and other effects are not rolled back on a refused output. Carrier-form callbacks such as bonemeal and item_after_vertical_collision also retain their captured stack outputs on refusal but do not journal independent host writes. The storage-journal follow-up covers that gap. Restricted in-write LevelHost callbacks keep their existing write and random-draw order.

Item-model callbacks receive the owned stack and a separate bundle_selected number (-1 means none). Runtime selection is not a persistent component. Drawing receives the API-owned ItemDisplayContext, not the renderer's enum.

The NBT escape

ItemStack::from_nbt(host, compound) and to_nbt(host) are the NBT escape. They live on the plain API value, not as a second engine implementation in the items host area. They use only typed host key lookup and canonical id metadata, so native and WebAssembly mods execute the same parsing and serialization code. Persistent NBT contains identifiers, never process-local key slots. Unknown ids, malformed values and zero counts fail decoding; unavailable id metadata fails encoding.

The escape preserves explicit zero damage, default-component removals and opaque component NBT. It does not apply resident maxima or materialize prototype defaults. Those remain the responsibility of the metadata service and game write boundary respectively.

A server mod asks for a call back after some server ticks with schedule_task, the stand-in for vanilla's MinecraftServer.tell(new TickTask(getTickCount() + delay, runnable)). A closure cannot cross into a wasm mod or outlive the host a hook borrows, so the callback is a hook: the mod passes a u64 token and Hooks::scheduled_task hands it back.

const REMINDER: u64 = 1;

impl Hooks for MyMod {
    fn player_logged_in(&self, host: &mut dyn ServerHost, player: u128, name: &str) {
        // 20 server ticks from now: one second at the normal rate.
        if let Ok(id) = host.schedule_task(20, REMINDER) {
            // Keep `id` if the reminder may need to be withdrawn: host.cancel_task(id).
        }
    }

    fn scheduled_task(&self, host: &mut dyn ServerHost, id: TaskId, owner: &str, token: u64) {
        if owner != "mymod" || token != REMINDER {
            return; // every mod is asked about every task
        }
        // The task has fired and its id is spent.
    }
}

Timing. Delays count ticks the server runs: a paused integrated server does not advance them. A task fires at the start of its due tick, right after server_tick's start phase, in the order the tasks were scheduled. A task never fires in the tick that scheduled it, whichever hook scheduled it, the tick's start hook and scheduled_task itself included: it fires on a later tick.

Ownership. The task belongs to the mod whose hook called schedule_task; the game takes that from the running hook, never from an argument. Outside a mod's hook the call returns ScheduleError::NotInMod. cancel_task answers false for another mod's id, an unknown one, and one that has fired or been cancelled. Every mod hears scheduled_task for every due task, so a mod compares owner with its own id and ignores the rest. Ids are never reused in a world.

Limits. A mod may have MAX_PENDING_TASKS (4096) tasks waiting; the next schedule_task returns ScheduleError::TooMany until one fires or is cancelled. A task that panics does not drop the others due on the same tick: they still run, and the panic goes on afterwards as any hook's does.

Lifetime. The queue belongs to the running world. It is dropped when the world opens or closes (including a failed open or close), and is never saved. A mod that must outlive a restart writes its deadline to its own storage and schedules again when the world opens. A mod's tasks are not cancelled when the mod unloads; the world's close is the end of them.

EntityRef::extinguish_fire(host) exposes vanilla Entity.extinguishFire on players, guests, mobs, armor stands and dropped items. If the entity is burning, it first emits minecraft:entity.generic.extinguish_fire at its feet with volume 0.7 and vanilla's pitch from two ordered random float draws. It then clears positive remaining fire ticks, preserving a negative fire-immunity countdown. Fire-immune mob kinds and dropped stacks resistant to in-fire damage do not count as burning, even when their timer is positive.

The operation reuses the engine's mob sound outbox and entity random, and the player/armor-stand cosmetic random and captured sound route. Dropped items use their own random. Sounds use the entity's sound source, including Players for a guest rather than a generic sound category. It does not draw pitch randomness for a non-burning entity. It returns false for stale or unsupported handles.

EntityRef::clear_fire(host) is the distinct vanilla Entity.clearFire operation: it is silent, draws no random, and preserves the same negative countdown. Choose it only when the original behavior explicitly calls clearFire, rather than using it as a substitute for extinguishing.

Trait mods (draft)

cargo horizon-mod new <path> --template native pins an exact Horizon commit (the newest prebuilt game's, or --horizon <commit>'s; cargo horizon-mod update repins) and writes a flat project: horizon-mod.toml with [native], Cargo.toml, src/lib.rs, and empty assets/ and data/ directories. The template greets each player who joins. Build it with horizon-launcher native-build <path> --trust-native-code; cargo horizon-mod build packages the same project into a .hmod without compiling it (the manifest).

The root Rust package depends on horizon-mod-api (lib mod_api), never on the game. Its root src/lib.rs marks one impl Hooks with the attribute:

use mod_api::{self, Hooks};

#[derive(Default)]
struct Mod;

#[mod_api::horizon_mod]
impl Hooks for Mod {
    // Implement the hooks this mod needs.
}

The attribute generates the hooks() factory and derives optional hook subscriptions from this impl. The mod type implements Default; do not write a second factory. Keep the marked impl at the crate root. Rustc's "cannot find function hooks" at the launcher's generated call means the marked implementation is not at the crate root. The launcher links this package into a generated game executable and calls the generated factory in dependency order (a mod after the mods it depends on, else in bundle order). A mod with no raw injections skips horizon-mixins; typed hooks need no injection declarations. Dependencies follow the pinned Horizon Cargo.lock rules in The mod's crate.

Dependencies between trait mods

A mod can publish functions and statics from its root crate for another mod to call. Declare dependencies in horizon-mod.toml, not Cargo.toml:

[dependencies]
base_mod = "^1"
extra_mod = { version = "^2", optional = true }

Requirements use Cargo semver syntax and are checked against each installed mod's horizon-mod.toml version, not its Cargo package version. Content-only mods use these declarations to validate their requirements and load their layers after dependencies. Code dependencies additionally require API packages for the dependent and every installed dependency. Missing required dependencies, incompatible versions and cycles stop the build with the mods named. An absent optional dependency is permitted; an installed optional dependency must match its requirement.

The launcher adds a path dependency using the mod ID as the Cargo alias and the target's actual Cargo package name. Optional dependencies also get a Cargo feature named exactly as their mod ID, enabled only when that mod is installed. Guard calls with if_installed!, which builds the block only with that feature and runs it only when the mod is installed, so the same source works when built to mod.wasm, where the library is linked at load and an absent one's functions trap:

mod_api::if_installed!(host, extra_mod, {
    extra_mod::register_extra(host);
});

Do not define these dependencies or features yourself in Cargo.toml. Public statics must use appropriate synchronization for shared and reentrant hooks; private state in another mod's hook object is not exposed.

Trait dispatch follows dependency order, with ties kept in bundle order. Mixin injection order remains horizon-mixins' priority, mod ID, then injection ID for source splices. Function-slot listeners instead use descending priority, dependency/registration order, then injection ID within a mod; call-site listeners retain mod-ID tie ordering.

Load phases and access

Native and wasm hooks share the installed dependency-ordered mod slice, including registration, config loading and reload-listener registration. The shared resolver keeps bundle-order ties, checks present optional dependencies too, and refuses cycles for both build targets. Content-only packages stay after code in the loaded-mod inventory; listener-specific edges still use ReloadOrder.

Each owning thread progresses through Packages → Registration → Setup → Config → World.

RegistrationContext::instance_dir() reads the instance directory captured before registration begins, as an InstanceDirectory: Unix(Vec<u8>) preserves raw Unix path bytes, and Windows(Vec<u16>) preserves Windows UTF-16 code units, including unpaired surrogates. Never convert Unix bytes with a lossy UTF-8 conversion when constructing a native filesystem path. Wasm receives the identical host-encoded value through Wire as data only; this does not grant filesystem access. A context with no engine snapshot returns RegistrationReadError::Unavailable.

Registration runs once: register, component_types, blocks, items and standalone_models receive only RegistrationContext. Its mods(), registry(name) and setting(mod_id, key) read one view captured before the first of them runs, so every registration step sees the same values whatever the dispatch order: the loaded packages, the built-in registries as registries.json lists them (not what mods declare during registration) and the settings on disk at that moment. A mod validates the keys it declares against them from Hooks::register; a name that is not a namespaced identifier, an unknown registry, an empty or path-like setting key, a package that is not loaded, or a context the engine gave no data returns a RegistrationReadError. Client setup runs once after the initial asset apply. The window's Client/Common configs load once immediately after client setup and before title, connection, input, render or ordinary tick callbacks. This includes pack-error recovery: the failed selection is cleared and saved during initialization, but its options screen opens only after Config completes. A title-screen callback is already in World: world-handle constructors can return None, rather than being forbidden in Setup. A dedicated server loads Common once before its first world; Server configs load and unload per world. A second world does not repeat registration or client setup. Config loading can read settings and use the existing scoped ConfigFiles service to read or save its own config files. World handles, transactions and other game operations panic with Config in the diagnostic. Config file polling is not a phase transition, and Server config unloading leaves the World phase.

Every data or asset reload enters Reloading, including listener registration, prepare, apply and the reload completion notice. Initial loads can nest in Setup; runtime reloads nest in World. Returning, including after a failed prepare, restores the entering phase. Published asset/data queries are classified in the catalog (resource_read), not granted by helper-name exceptions. They read the currently published generation, not pending prepare output: completion callbacks can refresh sprite and recipe caches after apply, including on first world open, without gaining world handles or transactions. Their rustdoc names their load-phase availability. Server listener registration retains &dyn Host, restricted to these published facts, registry facts, settings and mod-list queries; callbacks already taking DataLoadContext keep that context. Neither permits opening a world handle or transaction. The first client registration and prepare run on the loader thread; later registration runs on the render thread, prepare on its worker, and apply on the owning game thread. Startup's empty client Host is not an extra permission.

DataLoadOrigin and LoopSide are API-owned enums, not engine exports. Load and loop callbacks read frozen registry and settings metadata through DataLoadContext and LoopContext. The engine supplies borrowed LoadReader and LoopReader implementations; the API's owning views contain no engine types and do not copy or rescan the resource snapshot. Mod listeners keep using the context traits, with the same origin, side and registry ordering on both targets. The reader adapters themselves are native host implementation details, not wasm resources.

The game alone advances phases. An illegal or wrong-thread advance is refused before dispatch; a forbidden mod call panics naming the phase, rather than returning a Result a listener could ignore. There is no separate common-setup, load-complete or intermod event: registration and the first server reload cover common setup, client setup is client_setup, dedicated setup is server_about_to_start, and dependencies express intermod ordering. Load complete is the edge after initial Config and before server_about_to_start, not a hook.

Settings snapshots accept only regular UTF-8 files, without following file or package-directory symlinks (including internal links). Invalid UTF-8, special files and refused entries are absent, not errors. Each file is limited to 64 KiB before trimming, each mod to 1,024 captured keys, and the whole snapshot to 16 MiB before trimming. Over-limit keys are omitted in sorted package-id and key-name order. Enumeration is limited to 4,096 names per package; packages exceeding that budget are omitted entirely rather than retaining an unstable enumeration prefix. One warning per refusal class is emitted per snapshot. These generous limits cover the small scalar setting values used by the settings API; they do not apply to mod data files.

Native entry point and diagnostics

The generated executable uses the installed game's crates/horizon-client/src/native_main.rs.template. The launcher supplies only ordered literal mod IDs and hook factory paths. The template owns entry construction, the allocator and the canonical game identity. Source without this template is refused before staging trait mods: update the game first.

A mod whose bootstrap cannot complete should call cx.refuse("reason") inside Hooks::register, then return. This refuses only the calling mod's registration: there is no mod ID argument. Its declarations from that registration (before or after the call) are discarded. Later declarations do not add secondary validation errors, and another mod's declarations are unchanged. Native and wasm report the same diagnostic through the normal registration error path. This does not panic or exit the process. The first reason wins, including an empty reason. Reasons are preserved verbatim up to 4096 UTF-8 bytes; longer strings are truncated at the last character boundary within that limit.

A panic in a trait mod's hook adds in native mod <id>, hook <hook> to the panic's message, in the crash report and in the server thread's log line, with the horizon-mod.toml id. Each entry passed to entry::main_with must bind its id and hooks together: ModEntry::new("example", example::hooks()). The ordered list is Mods = Arc<[ModEntry]>; there is no separate naming step or unnamed entry. Before installation, mod_api::mods() still returns an empty list. Parts retain their registering mod's id for startup errors and hook panics. The game stops. A point listener's panic names its mod and method; render hooks are not named yet.

A native runtime that hosts converted packages (Portizon's wasm packages, a Java interpreter's jars) declares the packages it loaded with mod_api::content::crash::ConvertedPackages::new(runtime_id, ids) and marks a guest call with mod_api::content::crash::ConvertedPackage::enter(export, site). The scope nests, restores the previous one on return and while a panic unwinds, and adds in converted package <id>, export <export>, call site <site> below the runtime's in native mod line in the report. A package id the runtime did not declare is refused, as is a scope entered while another mod's call is the current one, so guest code cannot impersonate a mod the runtime did not load.

The guard is thread-affine (not Send or Sync), and attribution ends when the native frame that entered it exits, even if the converted guard is retained. A nested native frame hides the outer frame's package until it returns. Worker threads have no scope unless the runtime enters a native call and package scope there. Registry ids are stored, not interned: entering a package clones an owned id on every call (borrowed static ids do not allocate).

A code mod may listen at the game's injection points as a rare escape hatch, through a crate-root function named by [[inject]].with, taking a mod_points record; the form and its limits are in Injections.

Hook dispatch and level hosts

A linked trait mod implements mod_api::Hooks. A hook function is not an injection point, so [[inject]] never runs inside a hook's dispatch; a head injection that cancels the game function calling a hook keeps the hook from firing at all. A claimed cancellation reaches only trait listeners that receive cancelled events. Otherwise, trait mods run by priority, then in dependency order. Once a mod cancels, later mods are skipped unless they receive cancelled events. For replacement hooks, the first Some wins. Collection hooks call every mod. Receiverless hooks have no Host.

To save from inside a hook, use level.request_save(host) so the save runs at the next settled start-of-tick boundary. A synchronous save-all while an entity pass or held-out row is borrowed fails with vanilla's commands.save.failed feedback and a failed command result, without saving.

To emit a vibration-producing game event, use level.game_event(host, event, at, context). GameEventContext carries an optional source entity and affected block state; see game events with context for listener semantics and refusals.

#[listener] on a hook method sets both, as NeoForge's EventPriority and receiveCanceled do. Two mods, each its own crate:

#![allow(unused)]
fn main() {
#[mod_api::horizon_mod]
impl Hooks for Protection {
    // Runs before mods at the default priority, 0; higher runs first.
    #[listener(priority = 100)]
    fn break_block(&self, host: &mut dyn ServerHost, event: &mut BreakBlockEvent<'_>) -> Flow {
        if self.protected(host, event.pos) { Flow::Cancel } else { Flow::Continue }
    }
}

#[mod_api::horizon_mod]
impl Hooks for Override {
    // Still told after a cancel, and may undo it.
    #[listener(priority = -100, receive_cancelled)]
    fn break_block(&self, host: &mut dyn ServerHost, event: &mut BreakBlockEvent<'_>) -> Flow {
        if event.cancelled && self.allowed(host, event.pos) {
            event.cancelled = false;
        }
        Flow::Continue
    }
}
}

priority is an i32, 0 when omitted; mods of equal priority keep dependency order, as [[inject]] priorities do (Injections). Each hook's order is fixed once, when the mods are installed. Every cancellable hook's event has a cancelled field: a mod without receive_cancelled always sees false, since it is not called once the event is cancelled. A mod that receives cancelled events and sets it back to false lets the game's behaviour run, and the mods after it are told again. An event the game hands over already cancelled reaches only mods that receive cancelled events. receive_cancelled on a hook without a cancel does not compile, and #[listener] is for a trait mod's hooks only: a part is called for its own thing, in no order.

Native and wasm trait mods use the same listener ordering and cancellation rules. Wasm subscription records carry the hook name, signed priority, and receive-cancelled flag through the shared-memory Wire boundary at load time. The event's cancelled field crosses with its other writable fields. No component-model adapter is involved.

Each hook method takes its host, where it has one, and one event:

#![allow(unused)]
fn main() {
fn living_incoming_damage(
    &self,
    _level: &mut dyn LevelRandomHost,
    event: &mut LivingIncomingDamageEvent<'_>,
) -> Flow {
    if event.kind == "minecraft:pig" {
        let halved = event.container.new_damage() * 0.5;
        event.container.set_new_damage(halved);
    }
    Flow::Continue
}
}

The event is a generated struct named after the catalog hook, in CamelCase plus Event, with the hook point's arguments as public fields: values as values and borrowed ones as references (event.kind). A number or bool a mod may change is a plain field, written back once every mod has run, even after a Cancel; anything else a mod may change, a game struct or a list, is a &mut field. A cancellation or replacement is still the return value; a collection hook's list is a field (event.lines). One event goes through every mod, so each sees the changes before it. Because no mod can build or match the whole struct, a later version can add a field without breaking any mod, as NeoForge's event objects do; the cost is that a mod's own tests drive a hook through its dispatch function (Testing a trait mod).

Hook methods take &self and require Send + Sync. The process-wide mod list is installed once, like mixin module statics. One mod instance serves both the window's game and the server-thread game. A hook can also fire again inside the same mod: for example, LevelRef::set_block fires block_changed. Mods keep mutable state with interior mutability so these calls can share the instance safely. Data-load hooks can run on any loading thread; item default changes must be identical on every side.

The trait has every hook declared under crates/horizon-mod-vocab/src/hooks/ (Adding a hook). Level hooks use access-specific hosts rather than Host. LevelHost provides block_state through LevelAccess::block_state, client-side detection and state_with_property. state_string(state) serializes the full name and properties, or returns None for an unknown state; min_y() and height() read the level's build range. It also reads light and loaded state, through the game's own queries: brightness(LightLayer::Block | Sky, pos) (getBrightness, the stored 0 to 15), raw_brightness(pos, sky_darken) (getRawBrightness, which CropBlock.randomTick asks with 0) and is_loaded(pos) (Level.isLoaded: inside the build height and in a loaded chunk), is_raining_at(pos) (Level.isRainingAt, false where pos is not loaded) and enabled_features() (LevelReader.enabledFeatures, a borrowed FeatureFlags<'_>). Neither allocates. None of them loads a chunk. Light above the build height reads as full sky and below it as none, and a chunk that isn't loaded reads as the game's query does (full sky, no block light), so check is_loaded first. It also answers tag and fluid questions without a Host: block_in_tag(block_key, tag), fluid_state(pos) (getFluidState, None where the block read is), state_fluid_state(state) and fluid_in_tag(fluid_name, tag). Fluid reads return FluidState with a FluidKey, amount, falling flag and engine-derived source flag; is_empty() and is_source() report those states without a registry lookup. block_state_id(name) parses a block and properties, and block_state_default(block) gives a block's default state, as on Host; both return None for invalid input or unavailable context. Tag reads are None when authoritative tags are unavailable, including on a client before its server's tags are applied. For item membership and member lists, use Host::tags(): resolve a TagKey with Tags::key, then call Tags::is_in_tag, Tags::items or Tags::fluids. Membership reads return None on clients until server-sent tags are applied, which tags_updated announces; they never substitute local resource-pack tags. LevelHost has no random, by design: a draw from a read-only hook inside a level write would shift the level's random sequence away from vanilla's order. A hook that may draw is given a LevelRandomHost. LevelRandomHost provides vanilla's Level.random so mod draws come in vanilla's order. LevelTicksHost adds scheduling through native_schedule_block_tick and native_schedule_fluid_tick, while LevelWriteHost adds random access, set_block, set_block_property, native_play_sound and native_send_particles and native_level_event (levelEvent, queued in order with the write's own events). set_block(pos, state, flags) is Level.setBlock on a whole state, as LevelRef::set_block takes it: it removes the old block's block entity and creates the new block's in the write (LevelChunk.setBlockState), runs the neighbour and shape updates flags ask for, and queues the write's level events in order. A mod block entity it creates starts with the data the block_entity hook gives, which is fired in the write and receives the level (LevelSide, read-only: vanilla's newBlockEntity gets no level), as the Host's native_set_block fires it. It returns true when the block changed, and false off an authoritative server, for a position that is not loaded or outside the build height, an invalid state, or the state the block already has. It never loads a chunk. The game owns the tick queue; mods do not pass it back to these helpers. Frame drawing through DrawContext, BlockEntityDrawContext and WorldDrawContext stays in mod_api. Raw GPU access is native-only, unstable and outside that API, in mod_render::render (horizon-mod-render). Register its listed frame functions through [[inject]] with access = "internals" and kind = "head"; the ordinary listener registry owns ordering and disabling. render_needs collects requests; world_drawn runs before the hand and HUD, and hand_drawn runs after the hand, on the render thread.

The typed API from mixin code

An [[inject]] listener can use the typed API: an API point's listener gets the side's Host and calls attachments and handles through it. The worked examples, and which shape to choose, are in Injections; each mixin injector's form is in From mixins and legacy kinds.

A catalog hook's trait method, event and return make up its hook_version contract (Named hook points). These per-hook contract versions are catalog metadata, not minimum game versions. Catalog hooks, Host calls and internals [[inject]] declarations all build against the game's exact source revision. Rebuild the mod when that contract changes.

Every impl Hooks must have #[mod_api::horizon_mod]. The attribute derives subscriptions from the methods implemented in that block, so dispatch knows them at installation.

Parts

A part is code a trait mod attaches to one block, block entity, item or mod menu type, its own or vanilla's (the spec). A mod attaches its parts once, at startup, in Hooks::register. Each part trait implementation must have #[mod_api::horizon_part]; the attribute subscribes it only to the methods it implements. A BlockEntityPart also needs a separately annotated BlockPart implementation:

#![allow(unused)]
fn main() {
struct Gauge;
#[mod_api::horizon_part]
impl BlockPart for Gauge {
    fn has_analog_output(&self, _: &dyn LevelHost, event: &mut HasAnalogOutputEvent) {
        event.output = true;
    }
    fn analog_output(&self, _: &dyn LevelHost, event: &mut AnalogOutputEvent) {
        event.output = 15;
    }
}

#[mod_api::horizon_mod]
impl Hooks for MyMod {
    fn register(&self, r: &mut dyn Registrar, _: &RegistrationContext) {
        let stone = r.block_key("minecraft:stone");
        r.block_part(stone, Gauge);
    }
}
}

Registry keys

On r: &mut dyn Registrar, r.block_key(id) and r.effect_key(id) request registry entries, not new content. Registrar is the generated union of the kind-local registration traits (such as BlocksRegistrar and EffectsRegistrar); mod registration hooks and the horizon-machine-sample continue to use dyn Registrar. Each kind owns its declarations and implementation in parts/<kind>.rs; the union and WebAssembly bindings discover those traits without a shared method list. The capability-provider lookup union is assembled the same way. Declare them in register, retain the returned BlockKey or EffectKey in the mod or Part, and reuse them for registry operations. Requests are canonicalized (a bare id uses minecraft:), deduplicated across mods and checked after every mod's content is known. An unknown entry refuses the load with the requesting mod and canonical id, even if the key was never attached to a Part. A later mod may supply the requested entry.

The completed block identity table includes every vanilla and mod block, even blocks no mod requested. Completion preserves requested slots and appends the remaining canonical names in sorted order. Names belong to the installed mod registry; world load and reload prepare a separate numeric mapping for every retained key before publishing it. A missing requested block refuses completion without publishing a partial table. Immutable block definitions (property names, legal values, state combinations and defaults) are published with those names before mesh tables are constructed. Workers share read-only definitions; property reads allocate nothing. Pack reload does not mutate definitions or identities. The world's numeric mappings and tag membership remain separate reloadable data.

Metadata contexts are read-only and borrow the same table on the host and on workers. Wire transport records are internal, not saved block values. Persist canonical identifiers and property strings rather than slots or state ordinals.

BlockState is a small owned value with private fields, not a tint-specific snapshot or an engine numeric ID. state.block() reads its BlockKey; state.ordinal() reads its local ordinal. Property operations take explicit metadata: retain let metadata = host.block_states() and call state.property(&metadata, "facing") or state.with(&metadata, "facing", "east"). BlockState::of(&metadata, key, constraints) starts from the published default and applies the supplied StateConstraints. Changes return a new value and never mutate the original. Unknown keys, ordinals and property combinations return typed BlockStateErrors.

SceneBlock::new(pos, state, entity) and StructureTemplateBlock::new(pos, state, nbt) use this owned BlockState, including all properties. Structure reads preserve vanilla palette selection, mirror-then-rotation and placement order; an unavailable state mapping refuses the whole snapshot with None. DrawContext::draw_scene checks the entire scene before drawing: an unknown key, invalid ordinal or unavailable mapping draws nothing, never a partial scene or a replacement air block. Native and wasm use the same values and refusal rules.

Tint callbacks receive the same immutable metadata resource explicitly, without a Host. The game prepares their owned state array before constructing mesh tables; renderer workers only copy those values and invoke metadata reads. When world numeric state IDs are reordered, the game resolves each state's property combination against the published definition, so local ordinals retain their meaning across reloads.

host.block_states().states_of(key) returns a BlockStateRange in that same immutable local ordinal order. Its iterator yields owned BlockStates; it is not a span of world numeric IDs. BlockStateRange::new(first, count) returns a typed error if the span would exceed the u16 ordinal domain, and decoded transport spans obey the same check. Membership checks both the block key and the ordinal. A zero-count span is empty.

A restricted LevelHost::block_state(pos) read returns Option<BlockState>. A successful engine read retains its vanilla result: unloaded or out-of-height reads that produce air return Some(air), using the owning registry's real air state. An unavailable owning state index or a refused engine-to-API conversion returns None; the boundary never fabricates a key or air state and never panics to satisfy a mandatory value. Other optional/result read contracts are unchanged; in particular, this does not change LevelRef's loaded-position policy.

LevelRef::set_block, update_neighbors and neighbor_changed take owned block states and return Result<bool, LevelWriteError>. Stale identifies a closed or reopened level; Unavailable identifies the wrong side, phase or nonactive write target; InvalidState retains the block-state refusal. Errors do not mutate the level. Ok(false) is still vanilla refusal, such as an unloaded or out-of-height position or an unchanged block, not a lost handle or a guessed replacement state. Update flags retain their vanilla effect.

Walking a whole registry uses the typed keys, never names: host.block_keys() and host.item_keys() return every entry in the registry's registration order (vanilla's entries first, then mods' in the order they registered); host.entity_type_keys(), host.menu_keys() do the same for the built-in entity-type and menu registries. host.enchantment_keys() uses global sorted loaded-registry order, with vanilla and mod data-pack entries sorted together. A block registry lists a name once per state, and its iteration lists the block once. Build lookup tables from these lists at load time instead of resolving names per tick. A table is empty before its registry loads (blocks and items during rest load, enchantments with the item tables); registration-time RegistrationContext does not see any of them (#1001).

Keys are small, private u32 registration slots on both native and wasm. key.id(host) returns an owned canonical String through the generated read backend for diagnostics; it requires a game-backed host and an invalid slot is a boundary error, not an empty name. Block defaults come from immutable API metadata and cross through the game's sole forward/reverse state index. Behavior queries obtain their engine block from the resulting engine state; there is no separate per-key numeric block binding. Reload preserves key identity and canonical names. A refused resource rebind clears the active index, while failed transactional Parts preparation leaves the previously published Parts and index intact. Effect registration is process-owned and fixed until restart, matching the engine's effect registry.

A name that only arrives at run time (data, config, a command, a network message) turns into a key with the host: host.block_key("minecraft:stone"), host.effect_key("mymod:rage") and host.fluid_key("minecraft:water") return Option, and key.id(host) gives the name back for blocks, effects, fluids and items. Names are full registry names; the lookup reads the completed registry and does not allocate, so a hook can call it. It returns None for a name the registry does not hold, and before the registry is complete, so a mod uses r.block_key(id) in register. These work on the client and the server, for native and wasm mods alike.

Block tag membership is bound from the same merged item/block tag snapshot at world load and reload, including worlds without pack overrides. A read checks that the owning state index is available, looks up the tag name and tests membership in a prepared API BlockKey set; it never resolves the block's name. A fully namespaced tag needs no allocation (a bare tag adds minecraft:). Binding visits each merged block-tag member once and resolves its API key; it replaces the previous snapshot rather than accumulating membership. No membership work is added to ticks that do not call this read. Tags and block mappings belong to their resolving thread; missing authoritative context or an unavailable mapping returns None, not a stale membership result.

host.tags().blocks(tag) reads the current authoritative block members in vanilla order as BlockKey values, including blocks no mod requested. Resolve tag once with Tags::key and retain it across reloads. Unknown or empty tags return Some(Vec::new()); an unavailable context or any unresolved member returns None, never a partial member list. The same service is available through restricted level Hosts, without borrowing an engine registry.

host.block_state_default(stone), host.block_states().states_of(stone), host.block_item(stone), host.block_in_tag(stone, tag) and restricted-level schedule_block_tick(pos, stone, delay) use BlockKey. Property expressions accepted by block_state_id, tag names and existing fluid operation arguments remain strings for now.

Declare a tank-only fluid in your own namespace with r.declare_fluid("chocolate"); the returned FluidKey identifies it for the mod load. Request vanilla or another mod's declared fluid with r.fluid_key("minecraft:water") or r.fluid_key("other:chocolate"). Requests resolve after all registrations, so declaration order does not matter; an unknown request stops the load and names the requesting mod. Tank-only fluids have no world simulation or world state. Fluid stacks and recipe ingredients use these keys; remaining fluid operations move to them in subsequent changes. Declare a fluid that exists in the world with let mut fluid = WorldFluid::default(); fluid.drop_off = 2; r.declare_world_fluid("oil", fluid);, using mod_api::WorldFluid, the code form of a fluid file's world object (content mods): it adds the block mymod:oil, the flowing fluid mymod:flowing_oil and the bucket mymod:oil_bucket, and its fluid file, if it has one, still says how it looks. r.fluid_part("mymod:oil", Part) attaches a FluidPart, whose fluid_rules can change the declared values by position on the server. It is asked for every cell a spread looks at, so answer fast.

A saved tank whose fluid's mod is absent carries an opaque unresolved identity. Its stack's key() is None; UnresolvedFluid::id(host) reads its saved name. It can move between name-backed mod tanks, but not into vanilla buckets or cauldrons.

ActiveEffect::id and effect hook payloads carry EffectKey; living effect queries, application and removal use the same resolved key. ActiveEffect::new(speed, …) uses a key requested through r.effect_key("minecraft:speed"). Beacon-selection hooks carry Option<EffectKey> for each power; None is no selection. Enchantment effect-component names (for example minecraft:damage in has_enchantment_effect) are a different registry and remain strings, as do labels and tags.

Hot item and block identities

Resolve item and block keys during load and keep them for tick and menu calls. item_burn_time, item_compost_chance, give, enchantment_supports's item, and GUI item / item_model take ItemKey. block_item, fluid_bucket and screen_hovered_item return item keys. level.block, lit_block_name and Hit.block return block keys; BlockEntityDrawContext::block takes one. HeldItemSlot.id (including use-start/stop events) and Stack.item carry item keys, not names. Unknown incoming slots are refused at the boundary. block_sprites takes API-owned BlockState values, preserving properties without parsing state strings or exposing numeric engine state IDs. The pre-change block event carries resolved from / to states and does not allocate their names. Property names and values in set_block_property are not block identifiers and remain strings.

These calls remove string transport across wasm. Engine metadata reads may still hash borrowed registry names; no formatted identifier is built for these inputs.

Matched recipe lookup

level.recipe_for(host, &recipe_type, &inputs) replaces the crafting-only lookup. Use RecipeInput::Crafting { width, height, slots } for minecraft:crafting (row-major slots, dimensions 1 through 3), Single(stack) for smelting, blasting, smoking, campfire cooking and stonecutting, or Smithing { template, base, addition } for minecraft:smithing. Recipe types are not serializers: shaped and shapeless files both belong to minecraft:crafting, and transform/trim both belong to smithing.

The server uses the same engine matchers and assembled outputs as its menus, including data-pack overrides of vanilla recipe types. A RecipeMatch contains the matched recipe identifier, typed output, ordered remaining items, experience and processing time. Lookup consumes nothing; the caller applies inventory changes transactionally. Keep the result until inputs or the recipe load change.

Ok(None) means valid input without a match. Invalid shapes/items and unavailable levels are typed errors. A type without an engine matcher returns RecipeLookupError::NotMatchable, not an empty match. For mod-owned types, retain recipes_of_type once per load/reload and match that cached data inside the mod, with zero crossings per tick. Dynamic custom outputs and contextual predicates remain mod-owned; the host does not call guest code to match recipes.

At publication, call ingredient.item_keys(host) once per ingredient to retain Arc<[ItemKey]> for local matching. This load-time read returns exactly the plain item membership for lists, expanded tags and standard shapes, using the engine matcher. It returns IngredientKeysError::NotEnumerable if any custom or component predicate occurs anywhere in the tree; a displayed item list is not a safe substitute. UnknownItem refuses a missing registry identity. Do not call this method per tick. The sample's ProcessingRecipes::publish retains these keys; result then checks input.item() locally, with no Ingredient::test host call per candidate.

Stack placement predicates and drawing consumers (HUD items, GUI item decorations, block-entity items and tooltip images) encode API stacks without enforcing resident count or damage maxima. Engine-legal over-limit stacks can still be inspected and drawn. Unknown item keys and invalid/unrepresentable effect payloads still refuse encoding; this is not a total conversion. Insertion and other world writes retain strict validation.

API-owned values: migration table

mod_api::GameRuleValue owns the Bool(bool) and Int(i32) cases, in that order. level.game_rule(host, id) returns Result<Option<GameRuleValue>, LevelReadError>: Ok(None) means unknown rule, Stale means a gone/reopened level, and Unavailable means the side or phase cannot read it. level.game_rules(host) returns the typed result containing every available rule, not an optional list. The existing boolean key getter is unchanged. The game converts values after the subscription guard for game_rule_changed; no subscriber means no conversion work.

The API's GameRuleDecl records a mod's boolean rule name, category and default. Its internal RuleSchema input describes vanilla categories and dense rule positions through read-only lookups rather than a copied vanilla list or fixed slot numbers. Schema validation resolves category references after all mods have declared them and returns either all declaration slots or every refusal; it never installs a partial table. The game supplies this schema at Parts installation, then builds each world's engine rule registry from the installed GameRuleDecl snapshots. Existing rule registrar calls are unchanged; engine registry construction is no longer exposed through the API.

The game owns package and completion conversion. Mods do not import package-loader or client-core types for these values. Completion edits are copied back after subscribed listeners run; no listener means no snapshot allocation. Package metadata is copied once at startup, retaining declared namespaces and dependencies.

Opaque NBT metadata

The shared JSON/NBT conversion is iterative and follows vanilla's 512 nested list/compound limit; scalars and NBT typed arrays add no recursive container. Conversion to JSON intentionally loses numeric tag widths, boolean-as-byte identity and typed-array identity. NonFinite refuses NaN and infinities: serde_json::Value cannot hold them, and Gson's strict JSON writer also refuses them. InvalidString refuses an unpaired UTF-16 surrogate in a Tag string or compound key. Neither case is replaced with null, a string or U+FFFD. JSON input already uses UTF-8, so valid non-BMP pairs survive; a lone surrogate cannot reach this converter through that input representation.

Owned component trees

The text module defines owned component data: literal and translatable contents, style overrides, ordered children, selector and NBT sources, inline objects, and click and hover actions. Translation keys and argument components stay unresolved until the game displays them. None style fields inherit; Some(false) overrides an inherited decoration. Metadata, dialog/custom click payloads and hover-item component patches are owned Tag data, never JSON strings or engine state. TextProfile carries an optional name and UUID, signed property records and opaque unknown profile/property fields. Signed record order and unsigned values within each property name are preserved. Player names use U+0021..U+007E and at most 16 characters. Vanilla's unsigned property-map form allows at most 16 distinct names; signed or metadata-bearing records use a 16-entry list, with UTF-16 limits of 64, 32767 and 1024 units for property name, value and signature respectively. Inline player and atlas objects use Option<Box<Text>> for their fallback: None keeps the engine-computed default; Some preserves a styled or translatable component rather than flattening it to a string.

The native boundary plans borrowed source topology before cloning payloads. It reads source-less spans directly and validates every Tag's JSON representation before building an engine component. Text::validate() checks tree/payload bounds and profile fields without cloning; validate_depth() is the component-only preflight. NaN/infinity and unpaired UTF-16 remain legal Tag data but cause typed NonFinite or InvalidString refusals when engine emission requires JSON. Nested JSON null is refused as NestedNull when capturing opaque NBT fields; it is never silently replaced. Host methods accepting or returning Text return Result<_, TextFormError>; mixed item/Text writes preserve the refusal in StackWriteError::Text, and unspawned-mob reads use UnspawnedMobError::Text. TooDeep means a component path or opaque NBT container path exceeds 512. Unavailable backends are distinct from invalid text or unrepresentable payloads. A refused hook capture does not dispatch; a refused writeback leaves every field unchanged. No subscriber means no conversion or snapshot allocation. Mutable stack arguments are compared using value equality with the snapshot passed to the listener. An unchanged argument retains the original engine value without strict write validation (including engine-legal stacks above effective count or damage maxima). A changed argument is validated in full; a refusal still commits no outputs. The same rule applies to anvil/grindstone records and menu cursor/quick-move stacks.

Recursive Clone, Eq and Drop of a tree a mod itself built are ordinary Rust ownership, not part of the boundary guarantee.

Text::new(content) constructs any content kind without exposing an engine value. The content, NBT-source, object, click and hover enums are exhaustive protocol enums; new cases change the link contract, just as enum-case order does. Mod matches should name every case rather than silently treating a new protocol case as an old one. Typed content and style fields are authoritative; metadata retains unrecognized properties, not overrides of those typed fields. Game-side encoding is fallible and reuses the engine's translation-argument and fallback construction rules. Capture keeps dynamic contents and metadata rather than flattening the rendered spans. It shares the engine's SNBT flag, shadow-colour, click-policy and inline-object parsers. File-opening metadata is discarded before a listener receives the owned value; a no-op listener cannot promote an untrusted file action into a local action. A translatable's fallback is a literal format template, not another language key. A missing key whose fallback equals an existing key therefore still displays the fallback text itself; parsing and native constructors follow the same rule.

Particle identities

ParticleKey is an opaque slot in the load-owned registry tables. One completed snapshot retains both canonical names and provider identities: a vanilla provider's numeric index or a custom named sprite provider. The load resolves each provider once; reads of a retained key do not parse identifiers or scan the provider list. Unknown forward references refuse publication of the entire particle snapshot. Name-table completion shares the item registry's requested-slot preservation and sorted enumeration.

Placement and loot snapshots

mod_api::PlacementContext owns the placement inputs, including world-space click coordinates and the placer view/flags. Its item is Option<ItemKey>: None is a real empty hand, including falling-block placement contexts, not an invented air item. Nonempty items resolve through the existing load-owned item table. The game captures this read-only snapshot after the scoped subscription guard; no subscriber means no snapshot or item lookup. The block-state answer is applied as before.

The snapshots module owns placement inputs and loot-roll facts. Placement and tool items are resolved ItemKeys. Loot context entities, damage sources, tools, biome, block and place facts are owned values; retaining one never retains a borrowed engine context or a live level. A loot candidate is not an inventory ItemStack: its signed count can be non-positive while loot functions run, in which case it produces no item. Exploration searches remain deferred data, and name components remain unresolved text.

Item values and tag names

Every item has an ItemKey, including vanilla items no mod requested during registration. r.item_key(id) retains a forward reference in the same load-owned table; after the item registry is complete, host.item_key(&identifier) resolves any registered item. A key is still a private u32 index, not a copy of an item definition. Resolve once and retain it. host.max_stack_size(key) and host.max_damage(key) read item defaults without exposing the engine's item table.

ItemStack is owned API data with private fields. ItemStack::new(key, count) refuses zero, while ItemStack::of(key) makes one item. Count mutation refuses zero and arithmetic overflow. Registry-dependent maximum count and damage, including component overrides, are checked by the game when accepting a write; an oversized value is refused with a typed error, never silently clamped. This is the same boundary on native and wasm. Consuming split(n) returns StackSplit { taken, remainder }, both optional; consuming shrink(n) returns the remainder or None. There is no empty-stack sentinel. Component descriptors read and write an optional owned NBT patch; a plain stack has no patch allocation.

host.tags() and a restricted level host's tags() expose the same Tags service. Resolve a validated identifier once with tags.key(&identifier) and retain its TagKey. The runtime owns tag-name slots for the process; reload replaces membership, not names or key identity. tags.is_in_tag(item_key, tag_key) tests merged item membership. tags.items(tag_key) and tags.fluids(tag_key) return registered keys in vanilla's member order. Unknown tags return false or empty lists. Membership reads return None on clients, before authoritative tags load, or if the relevant registry mapping is unavailable. Key resolution itself can be refused if the runtime cannot allocate a name slot. No lookup stringifies a retained key. Block member enumeration moves with the registry-wide BlockKey table in the next type slice. The engine TagRegistry, StackData, StackView and DisplayContext are not API types.

A hook whose catalog entry has a scope (block, block_entity, item, menu) and a key, the argument naming the thing it is about, is a method on that scope's trait only: BlockPart, BlockEntityPart (a BlockPart too), ItemPart and MenuPart, as vanilla's and NeoForge's Block and Item methods are. It has no Hooks method: a thing without parts is never asked, and the game asks the parts attached to it in dispatch order, through the hook's contract, so a Cancel or a replacement skips the parts after it. Where a NeoForge bus event is the counterpart for that moment, the event is a hook of its own on Hooks, asked first for every thing, and its cancel skips the parts: a mod reacting to its own blocks uses a part, one reacting to every block the event. A part's kind is its type: the same kind twice on one thing, an invalid key declaration, or an unnamespaced id in the other Part registrations stops the game at startup with a message naming the mods. A panic in a part adds , part <type> to the mod and hook it names. Parts take &self and are Send + Sync, like Hooks.

Damage and item metadata snapshots

The three damage hooks convert only after their subscription guard. DamageValues retains the entire sequence, including reductions and the pre-hook input, so changing new_damage still reaches the engine's original NaN and negative normalization point. DamageValues::set_reduction edits snapshot data; it does not run a damage calculation. The fixed reduction storage is private; use its accessors rather than an array index. Reduction case order is append-only. Engine record_*, enter_pre, capture_inflicted and pre_change are not mod API methods.

ItemResource::damageable, foil and repairable delegate to the game's existing property readers through metadata access. Defaults, explicit overrides, component removals, compass glint and repair tags follow gameplay's single property path.

Recipe-file fields and small values

Host::recipe_ingredient and Host::recipe_result take the field's JSON text, not a serde_json::Value. Pass a quoted item id (r#""iron_ingot""#), a quoted #tag, or an ingredient array. Parse failures return RecipeJsonError::InvalidJson; unknown items and empty tags still return Ok(None). Result objects retain their components patch. These helpers are reload-time reads, not per-tick JSON parsers.

Block Parts

BlockPart::clone_item_stack answers on the server when a player picks the block. It receives the level, position, block state and include_data, true when a creative player picks with Ctrl. Return None to keep the game's item.

BlockPart::fall_on runs at vanilla's landing moment on a read-only level random host. Request a deferred write with event.request(LandingWrite::SetBlock(state)), where state is an API BlockState, or LandingWrite::DestroyBlock { drop }. The game checks the complete write batch before queuing it. An invalid block key or ordinal refuses that callback's writes and other outputs, including damage; it never applies a valid prefix. After the entity batch ticks, writes apply in request order if the block still matches its original landed state. That guard runs once, so a first write can change the state without suppressing the next write. SetBlock notifies neighbors and clients; DestroyBlock preserves the requested resource-drop flag.

BlockPart::contents_changed(host, event) observes a world block's storage at setChanged, with a ServerHost, typed event.level, event.pos: BlockPos and event.state. Attach it to the specific blocks you observe, including vanilla containers; it has no global Hooks counterpart. The backing contents are already written, before dirty/comparator updates. Native transactions notify once per backing block at root commit, never on abort or simulation. An explicit BlockEntityRef::set_changed notifies even if contents are unchanged. A double container notifies each component, not once again for the other half's comparator refresh. A listener's writes still apply, but a nested notice for that same backing block does not re-enter the listener; writes to a different backing block notify normally. Entity/menu placeholder coordinates are not block notices. This replaces Create's positional contents_changed mixin for depot/package/schematic storage; there is no NeoForge bus event. A compiled listener that reads the committed items through the typed level (the game's own test, so it cannot drift):

#[derive(Clone, Debug, PartialEq, Eq)]
struct Notice {
    level: LevelRef,
    pos: [i32; 3],
    amount: u32,
    version: Option<i32>,
}

#[derive(Clone, Default)]
struct Changes(Arc<Mutex<Vec<Notice>>>);

#[mod_api::horizon_part]
impl BlockPart for Changes {
    fn contents_changed(&self, host: &mut dyn ServerHost, event: &mut ContentsChangedEvent) {
        let pos = [event.pos.x, event.pos.y, event.pos.z];
        let amount = event
            .level
            .capability(host, &ITEMS, pos, None)
            .map_or(0, |items| {
                (0..items.size(host))
                    .map(|slot| items.amount(host, slot))
                    .sum()
            });
        let version = host
            .block_entity(event.level, pos)
            .and_then(|entity| entity.data(host))
            .and_then(|data| match data.get(&"Version".into()) {
                Some(Tag::Int(value)) => Some(*value),
                _ => None,
            });
        self.0.lock().unwrap().push(Notice {
            level: event.level,
            pos,
            amount,
            version,
        });
    }
}

Block entity types

Declare a block entity type and its valid blocks during Hooks::register, then attach its part:

let press = r.block_entity_type("press")
    .blocks(&["mymod:press", "mymod:big_press"])
    .build();
r.block_entity_part(&press, Press).expect("native block entity type");

The builder qualifies the type ID with the registering mod's namespace. It owns the save ID, wire type and valid blocks; block_entity returns only initial Compound data (or none for an empty compound). It is fired inside the write that creates the entity (LevelChunk.setBlockState) and receives the read-only level, a LevelSide, on a server and on a client of one. Unknown blocks, duplicate types, overlapping membership and attempts to own a minecraft: block are refused at load. Refused native block, item or block entity declarations stop startup, as does unreadable known-components input; the game does not fall back to vanilla content. An explicitly declared mod template block uses its declared type; undeclared template blocks retain their vanilla behavior. Adding mod blocks to vanilla types is not supported by this builder. The hooks about the entity (block_entity_tick, block_entity_update_tag, pre_remove_side_effects, menu_button, menu_quick_move) find it by that declared type; the others (block_entity, screen, the block hooks) by block. The factory is a BlockEntityPart method, not a global Hooks method.

r.block_entity_type_key("other:press") looks up another mod's type, and r.block_entity_type_key("minecraft:chest") looks up a vanilla type. Both return the same opaque BlockEntityTypeKey as the declaration builder: equality and hashing use the shared load-owned registration slot, not the type's blocks. Bare names use the minecraft: namespace. The final registry resolves requests after all declarations and refuses unknown IDs, naming the requesting mod and type. key.id(host) reads the canonical name for diagnostics; a key retains its identity until restart. Use a type ID, not a block ID (minecraft:shulker_box, not minecraft:red_shulker_box). BlockEntityRef::kind(host) returns Option<BlockEntityTypeKey>. living.hurt_and_break(host, slot, amount) changes equipped durability on the server; negative amounts repair. It returns the pre-shrink stack only on break, and None when nothing breaks or the entity or slot is unavailable. Creative players' equipment is exempt. The operation does not fire equip effects.

block_entity.replace_data(host, data) replaces its saved payload, clearing omitted fields while retaining identity and position. Like merge_data, it loads transactionally and synchronizes the change; it returns Err(BlockEntityError::Stale) for an invalidated handle, or Ok(false) for data the entity cannot load or an unchanged result. Lookup keys may answer capabilities for vanilla and native types. block_entity_part accepts only native types and returns BlockEntityPartError::VanillaType immediately for a vanilla key. Native Parts are expanded after every mod has registered, so a Part can target a type declared later.

Item and tag Parts

For an item-specific Part, request its canonical registry key once in register: let stick = r.item_key("minecraft:stick"); r.item_part(stick, Sharp);. Bare names use the minecraft: namespace. Requests may refer to content declared later; the final item registry refuses unknown IDs with the requesting mod. ItemKey equality uses its load-owned slot, and key.id(host) reads its canonical diagnostic name. Item capability registration and item helpers still use strings; their migration is a separate change.

r.block_part_tag("minecraft:logs", Rotates) and r.item_part_tag("minecraft:axes", Sharp) attach a part to every member of a tag (its name without #). Each game resolves them against its own tags when its world opens, again on /reload, and when a client joins a server, so the window's game and its server thread each answer from the tags they play with; a block that leaves the tag is no longer asked. A mod's parts on one thing run in the order it registered them, by key or by tag. A part a tag gives a thing that already has that kind of part warns, naming both mods, and the earlier mod's part stays. A tag that doesn't exist warns. Opening a world fails, naming the mod, when a part is attached to a block or item the game doesn't have. Scoped hooks run on a game's thread; one dispatched from any other thread (which no game hook does) can't see tag parts, and warns once.

Instant item use

ItemPart::use_item receives UseItemEvent { stack, hand }. hand: Hand is the interaction hand of this click (Hand::Main or Hand::Off), including air clicks with identical stacks in both hands. Read it directly when choosing which held stack to shrink. living_used_item_hand instead answers only during active item use and cannot identify an instantaneous click. The Part runs on both sides with HostSide, after the global right-click event and before the item's own use, on native and wasm. Return Some(InteractionResult::Success) to consume and swing on the client, Some(SuccessServer) to consume and swing on the server, or Some(Consume) to consume without a swing. Some(Fail) skips this item's own use without swinging and allows the off-hand sequence to proceed; unlike a block-use Fail, it does not end the entire click. None (the default) lets later Parts answer; if none answers, the item's own use runs. Some(Pass) stops dispatch to later Parts and continues directly to the item's own use. TryWithEmptyHand belongs to block use and is treated as Pass here. A thrown item can return Success on the client and Consume on the server. The hand field corresponds to NeoForge's PlayerInteractEvent.RightClickItem.getHand().

Hooks::right_click_item runs before Item.use, including after the same hand's unhandled block or entity interaction. A block success or FAIL, or an entity success, stops fallback. The server fires it for the separate use-item packet, once for that packet's hand. Canceling skips the item Part and vanilla action on native and wasm alike.

Item wear

ItemPart::damage_item is IItemExtension.damageItem: the wear a stack of the part's item is about to take (ItemStack.hurtAndBreak), after Unbreaking, as NeoForge passes it. The part reads event.amount, the points about to be lost, and changes it (0 or less leaves the item whole) or returns Flow::Cancel for no wear at all. It runs on every wear path: a player's tools, armour, shield and mace, a tool a dispenser uses, and a mob's armour. It is not asked when Unbreaking already saved the item or for a creative player's tools, and an item with no part costs one table lookup. With no part, the vanilla amount applies.

The global item_damaged hook is gone: this method is its one moment, and a part acts only on its own item. What the global hook could do and a part cannot is change the wear of another mod's or vanilla's items, which no part is attached to. Do that with an enchantment effect in data (a minecraft:item_damage effect on the enchantment, the component Unbreaking uses), or with an injection. A part does not get the wearing entity; host.players().acting_player() names the player on the paths a player takes.

Capability providers

A capability is answered by providers, registered by block entity type as NeoForge's RegisterCapabilitiesEvent registers them: obtain pipe with the declaration builder or r.block_entity_type_key("mymod:pipe"), then r.block_entity_capability(&ITEMS, &pipe, |host, at| Some(Box::new(PipeItems))) gives a handler for the block entity and side at (a BlockSide), or none to leave it to the next provider. A provider may answer for a vanilla block entity type too, using its lookup key. Providers add up: level.capability(host, &ITEMS, pos, side) (Level.getCapability, on a LevelRef) asks those registered with r.block_entity_capability_before_game first, then the game's own (a block entity's slots by side, by the rules hoppers follow, and a mod block entity's block_entity_container), then the others, each in registration order, and the first to answer wins. That order is the fork's choice, the game first and _before_game to go ahead of it: NeoForge 26.3's javadoc doesn't state one between mods' providers and the game's. It returns a Capability, the handler and who answered. A handler holds no borrow: each call is given the host, so it may call a neighbour's capability, and it keeps its state in the block entity's slots, compound or attachments. A provider is given the block entity and side, so the handler it makes knows where its contents live. Item handlers are NeoForge 26.3's ResourceHandler<ItemResource>: indices from 0 (size), what each holds (resource, an ItemResource: an item and its components, without a count) and how much (amount), how much of a resource an index holds when it holds that (capacity, none where it may not go), and insert and extract, which take a &Transaction and answer how much moved. There is no simulate: a write happens in a transaction (host.transaction(|host, tx| …), below), and to try one, abort it. move_resources(host, &from, &to, filter, max, tx) (NeoForge's ResourceHandlerUtil.move) moves what filter accepts, up to max, index by index out of from into wherever to takes it, each move all or nothing: what to won't take stays put. It answers how much moved, or Overanswered (below). Hoppers use a mod's handler where one is registered, each move in a transaction of its own. A mod's own capability is a CapabilityKey::new("mymod:chemicals"), answered only by parts.

A Capability may be held for the tick: look a neighbour's up once per tick and reuse it for every move that tick, as pipes and machines do. Ask again on the next tick, since the block entity behind it may be gone by then. For a wasm mod each lookup crosses the sandbox (about 2.5 µs, see Building a mod to mod.wasm), so holding it matters more there.

Item places and components

An item's own capability is reached where its stack lives, an ItemPlace: a player's slot, hand or cursor, a block entity's slot, an item entity, a stack inside another item (ItemPlace::Nested) or a mod's own place (ItemPlace::Mod, read and written by the PlaceProvider it registers with r.place_provider). r.item_capability(&ITEM_ITEMS, "mymod:backpack", |host, place| Some(Box::new(Backpack))) answers ITEM_ITEMS for an item with a ResourceHandler<ItemResource> made for that place, and r.item_capability_before_game ahead of the game's own over item_container; place.capability(host, &ITEM_ITEMS) (ItemAccess.getCapability) asks them in the same order. A handler keeps its contents in the stack, and reads and writes it through the place, as NeoForge 26.3's ItemAccess: place.stack(host), place.resource(host) and place.amount(host), and place.insert, place.extract and place.exchange(host, tx, &resource, amount), which answer how much moved. Each runs in a transaction of its own, nested in tx, and changes the place where it is, journaled, so an abort puts it back at every level of an item inside an item. A handler answering more than it was asked or offered is a mod bug: the move it was part of is undone, and the game warns once, naming the mod. What doesn't stack with the place, or doesn't fit, goes where vanilla puts an item split off it, so exchange(host, tx, &filled, 1) on a stack of empty buckets is vanilla's filled bucket: from a player's place into their inventory, else dropped with no thrower (a creative player's hand takes anything and gives them one if they have none, as forInfiniteMaterials); from an item entity dropped beside it; from a block entity's, an entity's or an item's slot into that container's other slots (forHandlerIndex). A handler rewrites its item with an exchange of one. An exchange inside one of two backpacks is done in one of them: that one is rewritten holding the change and splits off, and the other stays as it was.

A stack's components change the same way, where it lives (NeoForge's ItemResource.with and without). A component is named by a ComponentId, checked once as a namespaced id (ComponentId::new("minecraft:damage"), None for Damage or !minecraft:food). resource.component(&id) reads the stack's own value in its patch as saved; resource.with_component(host, &id, value) sets it as vanilla's PatchedDataComponentMap.set does, keeping no value of the stack's own where value is the item's default (host.item_default_component(item, id), compared as the component's codec reads it: a vanilla component's numbers by exact value, custom_data and the other raw NBT components and a mod's own type for type), and resource.without_component(host, &id) removes the component as remove does: the stack's own value goes, and where the item has the component by default a removal ("!minecraft:max_damage": {}) is recorded in the patch. An exchange of one puts the changed item in place: place.exchange(host, tx, &place.resource(host)?.with_component(host, &damage, Tag::Int(5)), 1) damages one sword of a stack, splitting it off.

An entity's items

entity.capability(host, &ENTITY_ITEMS, ()) (NeoForge 26.3's Capabilities.Item.ENTITY) is an entity's items, None for a stale handle and an entity outside the level in place. The game answers it for a player with their inventory (PlayerInventoryWrapper), indices as vanilla's Inventory numbers them: 0..36 the main inventory (0..9 the hotbar), 36..40 the armour from feet to head, 40 the off hand. Each index is the player's ItemPlace::PlayerSlot and takes only what fits there: an armour slot one of what its equippable names it for (ArmorSlot: its allowed entities hold the player by id or by tag), and bound armour comes off only in creative. insert_any, without an index, goes where Inventory.add puts a stack: onto the same item in the selected slot, the off hand and the main inventory in order, then into its empty slots, never the armour. For a chest or hopper minecart, a chest boat and a chested donkey, mule or llama the game answers with their container's slots (ItemPlace::EntitySlot). A handler kept past its entity's removal or its world's close reaches nothing. r.entity_capability(&ENTITY_ITEMS, "mymod:robot", |host, robot, ()| …) answers it for a mod's entity type, and r.entity_capability_before_game ahead of the game's own, asked as block entities' providers are. Giving, taking and counting a player's items go through it:

#![allow(unused)]
fn main() {
// A trade: each offer is (index, the exact stack it must still hold). A stale offer or no
// room for one aborts the transaction, and every move in it is put back.
let (a, b) = (seller.capability(host, &ENTITY_ITEMS, ())?, buyer.capability(host, &ENTITY_ITEMS, ())?);
host.transaction(|host, tx| {
    for (from, to, offer) in [(&a, &b, &seller_offer), (&b, &a, &buyer_offer)] {
        for (index, stack) in offer {
            let offered = ItemResource::of(stack);
            let still = from.resource(host, *index).as_ref() == Some(&offered)
                && from.amount(host, *index) == stack.count();
            if !still
                || from.extract(host, tx, *index, &offered, stack.count()) != stack.count()
                || to.insert_any(host, tx, &offered, stack.count()) != stack.count()
            {
                return Err(());
            }
        }
    }
    Ok(())
})
}

Cauldron interactions outside a transaction keep vanilla's effect order. Inside an open transaction, their statistic award (including player_stat_award), sound and overflow item toss/spawn wait until the outermost successful commit; an abort emits none of them.

Entity energy and fluids

entity.capability(host, &ENTITY_ENERGY, side) and entity.capability(host, &ENTITY_FLUIDS, side) reach a mod's entity energy and fluid handlers (NeoForge 26.3's Capabilities.Energy.ENTITY and Capabilities.Fluid.ENTITY), where side is the Option<Direction> of the entity the lookup reaches it from, None for no particular side. Vanilla answers neither; register a provider with r.entity_capability(&ENTITY_ENERGY, "mymod:robot", |host, robot, side| …), which is given that side and may answer differently for each. An entity capability's context is its key's second type: () for ENTITY_ITEMS, Option<Direction> for these two and for ENTITY_AUTOMATION. The existing move_energy and move_resources transfer between these and block or item handlers inside a transaction.

Entity automation

entity.capability(host, &ENTITY_AUTOMATION, side) (NeoForge 26.3's Capabilities.Item.ENTITY_AUTOMATION, "automation-accessible inventory of an entity (boats, minecarts, etc)") is the items of an entity as a hopper reaches them, with the same Option<Direction> context as the energy and fluid keys. The game answers it for the container entities EntitySelector.CONTAINER_ENTITY_SELECTOR picks (chest and hopper minecarts, chest boats) with the slots their ENTITY_ITEMS handler has; a player and a chested donkey, mule or llama answer none. A hopper pushing into the entity in front of it asks for the side it faces the entity from (Up for a hopper over it), a hopper pulling from the entity above it for Down, and a dropper for the side it drops onto. Beside the game's container entities, those entities at the target whose mod provider answers it join the candidates, and the hopper picks one at random with the draw getEntityContainer makes; a mod handler takes the container's place and moves one item at a time in a transaction, as a mod block's ITEMS does. r.entity_capability(&ENTITY_AUTOMATION, "mymod:robot", |host, robot, side| …) registers one, and r.entity_capability_before_game answers ahead of the game's own for a minecart or a boat.

A menu's slots

Mod-created recipe input sets

Hooks::recipe_property_sets runs once after recipes resolve for each load and again after /reload. Add RecipePropertyAddition::new("mymod:cooking_pot_input", items) to its event.additions: a key in the listener's manifest-owned namespaces creates a set. Ownership uses the package ID plus the manifest's namespaces, so a package named ported_farmersdelight with namespaces = ["farmersdelight"] can create farmersdelight:cooking_pot_input. A later listener may extend an existing set but cannot create a new foreign key. Invalid keys, unknown vanilla keys and air are skipped with a warning; unregistered items do not participate in acceptance or network sync.

Attach a MenuPart to the registered menu type and filter its input slot with the same set:

struct PotInput;
#[mod_api::horizon_part]
impl mod_api::MenuPart for PotInput {
    fn menu_slot_rules(
        &self,
        context: &dyn mod_api::LoopContext,
        event: &mut mod_api::MenuSlotRulesEvent<'_>,
    ) {
        if event.slot == 0 {
            event.may_place &= context.mod_recipe_property_contains(
                "farmersdelight:cooking_pot_input", event.stack.item(),
            );
        }
    }
}
// In Hooks::register:
// registrar.menu_part("farmersdelight:cooking_pot", PotInput);

The Host exposes the same mod_recipe_property_contains(set, ItemKey) query outside restricted menu callbacks. This query covers mod-created sets only: unknown sets, unknown items and vanilla set keys return false. Existing vanilla station acceptance is unchanged. The server reads its owning load; the client reads local preload sets before its first UpdateRecipes, then the authoritative server generation. A packet replaces the entire generation, including an empty one. Closing a screen or changing dimension retains it; disconnecting discards it. Reads allocate nothing and do not rescan recipes or registries. There is no second hook and no per-slot load callback.

Client hooks can read the local player's menu with host.local_player()?.container_menu(host), including the inventory when no container is open. MenuRef::slot_count, slot and carried read on either side; slot and carried return an outer None when the handle or slot is unavailable and Some(None) for an empty slot. Each read checks the world epoch and menu generation, so a handle cannot read a replacement, reopened or respawned menu. These methods do not click or change slots.

Mutable client hooks can submit a vanilla click with menu.click(host, &[mod_api::MenuClick::QuickMove { slot }]). The slot is the same menu-order index used by slot, not a hotbar index or a GUI slot id. For example:

/// Shift-click a slot in the local player's current menu.
pub fn quick_move(host: &mut dyn mod_api::ClientHost, slot: usize) -> bool {
    let Some(menu) = host
        .local_player()
        .and_then(|player| player.container_menu(host))
    else {
        return false;
    };
    menu.click(host, &[mod_api::MenuClick::QuickMove { slot }])
}

The typed actions are Pickup (with MouseButton::Left or Right), QuickMove, Swap (with SwapWith::Hotbar(0..=8) or Offhand), Clone, Throw, Drag and PickupAll. Pickup accepts None for outside, dropping the carried stack. A Drag { kind, slots } owns its menu-order slot list and always submits a complete gesture; DragKind::Split divides evenly, One places one per slot and Clone fills slots in creative mode. Every action in a batch is validated before any prediction or sending; out-of-range slots/hotbar indices, creative-only actions in survival and empty batches refuse without effects. Stale/replaced/respawned menus, spectators, non-client hosts and the creative inventory screen refuse with false. true means submitted, not server acceptance: prediction uses the normal menu engine and sends ContainerClick with its state id, changed slots and carried item. Server corrections still win. Inventory reads and direct server-side item transactions keep their existing contracts; a click does not expose direct client inventory writes or enforce a mod's locked-slot policy. Call from an explicit input action rather than submitting every render/tick. Diverges from upstream: new helper.

menu.close(host) closes the menu's screen as Escape does and tells the server (ContainerClose); it returns false while that screen is not open, so the inventory menu closes only while the inventory screen shows. menu.click_button(host, button) presses one of the open menu's buttons (ContainerButtonClick, as a loom's pattern list does), for input the screen's own buttons don't take; the server's menu decides what it does, and the inventory menu has none.

ItemPlace::MenuSlot { menu, slot } is slot slot of a player's open menu, a MenuRef (player.container_menu(host)). It is a fork addition: NeoForge 26.3's ItemAccess reaches a player's inventory slot (forPlayerSlot) and cursor (forPlayerCursor), not a menu's slot. It is the storage the slot shows, named by menu.slot_backing(host, slot) (MenuSlotBacking), and a write goes to that storage through its own handler, so it is kept once by the transaction and the storage's rules hold: the player's inventory, armour and off hand by their ENTITY_ITEMS index, a chest's or a furnace's slot through its ITEMS handler, a chest minecart's or a chested mount's through its ENTITY_ITEMS, and the player's ender chest, inventory crafting grid and a mod's chest menu (open_menu), kept by the game. The slot's own rules come first, as a click has them: menu.slot_holds(host, slot, &stack) is how many of a stack it holds (Slot.mayPlace, then Slot.getMaxStackSize: a furnace's fuel slot one bucket, an armour slot one piece that fits it, a shulker box's slot no shulker box, a result slot none), and menu.slot_gives(host, slot) whether it gives up what it holds (Slot.mayPickup: bound armour stays on outside creative). An insert fills that slot alone, and what doesn't fit stays out. A crafting grid a transaction changed has its result made again at the outermost commit, once for each player however many writes it took (InventoryMenu.slotsChanged, with native_prepare_item_craft); the result slot takes nothing and gives nothing, since taking it is a craft. A menu closed, replaced or reopened since the MenuRef was made, or one whose player left, reads and writes nothing. menu.cursor() is that menu's cursor (ItemPlace::PlayerCursor { menu }, forPlayerCursor), which reaches nothing once the menu is gone, so a kept cursor never reaches the next menu's. The player's screen follows with the tick's container sync.

#![allow(unused)]
fn main() {
// Put four of the menu's offered emeralds into slot 0 of the open chest, or nothing.
let (slot, cursor) = (ItemPlace::MenuSlot { menu, slot: 0 }, menu.cursor());
host.transaction(|host, tx| {
    let took = cursor.extract(host, tx, &emerald, 4);
    if took == 4 && slot.insert(host, tx, &emerald, 4) == 4 { Ok(()) } else { Err(()) }
})
}

A block's fluids

Fluids are the capability FLUIDS (NeoForge's Capabilities.Fluid.BLOCK), answered as items are, by a ResourceHandler<FluidResource> in millibuckets. A FluidResource is a fluid id and its data components, without an amount, kept as an item stack's are (a potion fluid's contents; water and lava have none), and a tank fills only from empty or with the same fluid and the same components. A FluidStack is one with an amount, as tanks keep it (resource.to_stack(amount), FluidResource::of(&stack)). The game's own answer is a mod block's tanks by side (block_entity_fluids) and a cauldron, one tank of 1000 mB that holds water in thirds and lava only whole; a cauldron has no block entity and is answered by position, and a powder snow cauldron holds no fluid. A cauldron takes water and lava whatever their components and discards them, so what comes out of it is plain: the one place a fluid's components are dropped. A mod block's saved tanks take no fluid with components. level.capability(host, &FLUIDS, pos, side) finds a handler in a LevelRef's level, as ITEMS' are found, and move_resources moves fluids as it moves items. A move the target takes only part of is undone and tried again with that part, so a cauldron, which gives whole thirds and never more than asked, gives what fits: asked for a bucket with room for 500 mB, it gives one level, 334 mB.

Fluid held by an item is ITEM_FLUIDS (NeoForge's Capabilities.Fluid.ITEM), found where its stack lives, as ITEM_ITEMS is: place.capability(host, &ITEM_FLUIDS) gives a ResourceHandler<FluidResource> for the item at that ItemPlace, and a write rewrites the item there by an exchange of one, so from a stack of more than one the changed item splits off (r.item_capability(&ITEM_FLUIDS, "mymod:canister", …) answers it for a mod's item). The game answers it for vanilla's buckets: one tank of 1000 mB, filled and drained whole, an empty bucket taking plain water or lava and becoming its full bucket, a full one becoming an empty bucket. move_resources moves between an item and a block as between two blocks: a full cauldron fills a bucket in a player's slot, and two thirds of one fill none.

A block's energy

Energy is the capability ENERGY (NeoForge's Capabilities.Energy.BLOCK), answered by an EnergyHandler: an amount and a capacity, with no resource, and insert and extract written in a transaction as a ResourceHandler's are. r.block_entity_capability(&ENERGY, &battery, …) (with a declared or looked-up type key) registers a provider, asked as ITEMS' are, and level.capability(host, &ENERGY, pos, side) finds one. The game's own answer is a mod block entity's block_entity_energy buffer, as NeoForge's SimpleEnergyHandler: a fill through the sides it comes through, up to the buffer's room and its limit per insert, and a drain by the sides it leaves by, up to the limit per extract; a side that reaches neither finds no handler. move_energy(host, &from, &to, max, tx) moves between two (EnergyHandlerUtil.move) as one step of move_resources: all or nothing, a move the target takes only part of tried again with that part.

Energy held by an item is ITEM_ENERGY (NeoForge's Capabilities.Energy.ITEM), found where its stack lives with place.capability(host, &ITEM_ENERGY), as ITEM_FLUIDS is, and moved by move_energy as a block's is. A mod answers it for its item with r.item_capability(&ITEM_ENERGY, "mymod:cell", …), keeping the energy in the item's own stack and rewriting it by an exchange of one, so from a stack of more than one the charged item splits off. Vanilla has no energy items, so the game answers it for none.

Capability answer limits

The game never trusts an answer past what it asked or offered. A handler answering more than it was asked has its move undone, in its transaction, and is warned once naming the mod, and move_resources or move_energy returns Overanswered naming it. Returned from the closure of host.transaction with ?, it aborts the whole move, so neither end keeps any of it: a broken handler can't make a move overflow, duplicate or lose items, fluid or energy, or panic the game.

Consumable effects

A LivingRef on the server can apply one effect from an item's loaded consumable with living.apply_consume_effect(host, &stack, index). The index is zero-based in component order; this does not eat food, shrink the stack or run consume triggers. Some(true) or Some(false) is the effect's result; None means the item, index or target is unavailable or the effect is unsupported. Mob random teleport, armor stands and dragons are not supported. Player random teleport uses the level random as normal.

Mod-defined kinds dispatch through the ordinary consume_effect hook. For these kinds, Some(true) means dispatch was entered, not that a listener changed game state; an unclaimed kind still does nothing. Reapplying the same kind from inside its own handler on the same call stack returns Some(false) without recursion. Another kind, including one owned by another mod, dispatches normally, and a later independent call can apply the original kind again. This deliberately reverses #550's original blanket exclusion of mod-defined kinds; it is not a second consume hook or an alternate dispatch path.

Transactions

On a ServerHost, import HostTransaction to call host.transaction(|host, tx| …) (NeoForge 26.3's Transaction). It runs a closure whose Ok commits and whose Err aborts, nested in the open transaction if any. tx, a &Transaction (NeoForge's TransactionContext), is what every handler and place write takes, so none happens outside one. Inside, a capability write applies at once, so later steps see it, and the game keeps each storage as it was before the transaction first wrote it: a block entity's item slots, saved compound and attachments, a hopper's cooldown, a cauldron's block state, a player's inventory (slots, armour, off hand and cursor, whether the player is the host or a guest), an entity's inventory (a chest or hopper minecart, a chest boat, a chested donkey, mule or llama) and an item entity's stack (one emptied stays, empty, until the outermost commit removes it). A nested commit hands its changes to the transaction around it, and only the outermost commit makes them final. Then the world is told of each change once, as SnapshotJournal.onRootCommit: setChanged and comparators, a jukebox starting or stopping, a cauldron's block update, and an item dropped at a block, thrown by a player (what a filled bucket's split no longer fits) or by an entity or split off an item entity. An abort puts every storage back quietly, so nothing outside saw the change. A panic unwinding out of the closure aborts that transaction as it passes, and the one around it stays open. Open one with host.transaction. The game, not the values it hands out, holds the authority, and it keeps writing apart from ending. The closure, like any handler, is lent the Transaction: it names one open transaction by a token the game drew (unguessable in practice), and a write given one that names no open transaction changes nothing. Ending a transaction takes its TransactionSeal, which only host.transaction's guard (or whoever called the raw transaction_open) holds; the raw transaction_close refuses a seal that names no open transaction. So a handler can neither commit the transaction it was lent, nor end one around it, and a value decoded from bytes or kept past its closure does nothing. A transaction left open inside another is aborted when the one around it closes, so a caught panic or an Err still finds the rollback done. A handler keeps no journal of its own: its state is the game's, so the game's journal covers it. Direct writes are not covered: an item entity's stack, LivingRef::set_equipment, and the player and armor-stand slot_set paths take effect and are final at once, even inside a transaction. Any equip/unequip event and equip sound from set_equipment also happen immediately; an abort does not undo them. This differs from writes through journaled capability handlers.

ItemPlace::EntitySlot { entity, slot } is slot slot of such an entity's inventory (NeoForge's Capabilities.Item.ENTITY), read and written like any other place. Reading or writing a minecart's slots unpacks its loot table with no player, as getChestVehicleItem does.

A mod's own capability

A mod can define a capability of its own, as Mekanism defines chemicals: a resource type and a key, published from its root crate (Dependencies between trait mods) for other mods to use.

#![allow(unused)]
fn main() {
// The chemistry mod's root crate
#[derive(Clone, PartialEq)]
pub struct Chemical(pub String);
pub const CHEMICALS: CapabilityKey<dyn ResourceHandler<Chemical>> = CapabilityKey::new("chem_api:chemical");
}

A mod that names it under [dependencies] builds against the same Chemical and CHEMICALS, so its providers, r.block_entity_capability(&chem_api::CHEMICALS, &vat, …) (where vat is a declared type key or r.block_entity_type_key("chem_pipe:vat")), answer the same capability, and level.capability(host, &chem_api::CHEMICALS, pos, side) finds either mod's handler. move_resources moves a chemical as it moves items, in the caller's transaction. The game has no answer of its own for a mod's key, so only the mods' providers do, and a lookup with none registered costs one table check. A handler that keeps its amount in its block entity's saved data (BlockEntityRef::merge_data) is covered by the game's journal, so an aborted transaction puts it back. ItemCapabilityKey::new and EntityCapabilityKey::new define item and entity capabilities the same way.

A key is known by its name, which must be namespaced (chem_api:chemical), and a name has one handler type. Two mods that each declare their own Chemical under one name, rather than sharing the defining mod's, would never see each other's handlers. So the game refuses that at startup, naming both mods and both types, and it refuses a key whose name has no namespace. Both checks run once, when the mods register.

Entity parts and mob goals

r.entity_part("minecraft:zombie", ZombieGoals) attaches an EntityPart to one entity type, a mod's own or vanilla's. Its method register_goals runs at every Mob construction of that type — spawned or loaded, the moment vanilla's registerGoals fan-out ends — and the goals it adds join the mob's two selectors beside the species' own, with the same priorities, flag locks and interruption:

#![allow(unused)]
fn main() {
struct ZombieGoals;
#[mod_api::horizon_part]
impl EntityPart for ZombieGoals {
    fn register_goals(&self, goals: &mut GoalRegistrar<'_>) {
        // goals.mob().id() is "minecraft:zombie": branch as per-species code does.
        goals.add_goal(7, Stare::default());
        goals.add_target_goal(3, Remember::default());
    }
}
}

goals.add_goal(priority, goal) and goals.add_target_goal(priority, goal) are GoalSelector.addGoal on the mob's two selectors; GoalFlags claims MOVE, LOOK, JUMP and TARGET as vanilla's Goal.Flag does, and a higher priority (a lower number) interrupts a running goal holding the same flag. A goal object is per mob, built fresh at every construction, and its state is never saved: a goal that needs memory across loads keeps it in attachments. A mob whose type has no part, or a game with no entity parts at all, pays nothing — the wrapper and the tick's read view exist only where a mod goal runs.

A Goal reads and writes through its GoalContext: mob() is a fresh handle of the mob it runs on, host() the tick's read view, random() the mob's own random (mob.getRandom(), so a mod's draws keep the mob's stream in shape). The read view answers the ticking mob itself directly, the player the tick sees, and every other entity from the tick's snapshot — a getEntities of the moment the mob list was taken out — so a read the snapshot does not carry (a mob's gear or effects, its species id) answers None, and the handle docs mark the reads that carry the snapshot rule. Writes apply to the mob itself through the engine's own paths: move_to(pos, speed) and stop_navigation() (PathNavigation), look_at(pos) (LookControl), jump(), and set_target(Option<LivingRef>) (Mob.setTarget, with the write handle's rules: a fox, an enderman or a zombified piglin stores it with its setter's side effects, and a brain-backed species refuses, since its target is a brain memory that MobRef::set_brain_target writes from a server host). Writes to other entities are not part of a goal; the write handles a ServerHost takes do not exist in a goal tick. Clearing a fox's target ends defending without changing its trusted entities. An enderman's target controls its creepy flag and attacking speed modifier; clearing it also clears its stared-at flag. A zombified piglin schedules its first anger sound and next alert when it acquires a target from none, not when switching between targets. Targeting a player does not count as player damage.

Brain behaviors

Native mods only: entity parts do not cross to wasm yet.

EntityPart::register_behaviors receives a BehaviorRegistrar whenever a brain-driven species builds or rebuilds its brain. Use add(activity, priority, min_duration, max_duration, requirements, behavior) to join a fresh Behavior to the species' supported activity. Registration returns a BehaviorRefusal for an unsupported activity or invalid duration. Behaviors start and stop in vanilla Brain.tick order: priority, activity bucket, then insertion order, with mod behaviors after vanilla behaviors in the same bucket. Their state is not saved. BehaviorCx provides the mob, host, random source and typed brain memory access; each species refuses memories it does not support.

The part's other method, spawn_cluster_size, changes how large a natural spawn group of the type grows (Mob.getMaxSpawnClusterSize); controlling spawns shows it.

Entity parts are a native mod's for now: the goal surface does not cross to wasm (see the attach_entity_part note), so r.entity_part is absent from a wasm build.

Block-state facts

A BlockState is an API-owned value pairing a BlockKey with a block-local canonical ordinal, not a numeric engine state ID or a live object. Facts that need no world are a small read-only service on any host, both sides: host.block_states() (import HostBlockStates). Each reads the game's own tables through checked crossings. Fact queries and matching allocate nothing; definition copies the property data for the caller. Property operations on BlockState borrow explicit immutable block metadata; block() and ordinal() need no host:

Use StateConstraint for each partial constraint; StateMatchError identifies an invalid property or value by index. StateProperty describes a property's legal values. These types are shared by state-definition services.

None for an unknown state or block, including an invalid local ordinal, and on a host with no game behind it (a mod's test double). The ordinal order is defined by the complete canonical property constraints, not by the engine's numeric enumeration.

Fluid-state facts

Import HostFluidStates to reach host.fluid_states() on either owning side. definition(key) returns Some(FluidDefinition::World { default, properties }) for a world fluid, Some(FluidDefinition::TankOnly) for a registered tank-only fluid, and None without a loaded registry. The properties and typed default come from the loaded preparation, not a second vanilla table. These metadata reads are available in setup, reload and world callbacks after the fluid keys resolve, not during registration or configuration.

validate(key, constraints) checks partial StateConstraint values in input order without matching any particular state. It returns Result<(), FluidStateError>: UnknownProperty(index), InvalidValue(index) or Duplicate(index) identifies the first offending input. NoWorldState means the fluid is tank-only or the host has no definition; use definition to distinguish them.

type_properties(key) returns a FluidTypeProperties record, or None without a loaded registry or for a key it doesn't hold; host.fluid_key(name) is None for an unknown name. The record is the same in every level: description_id, light_level, fall_distance_modifier, and whether the fluid can push entities, be swum in, drown, extinguish, hydrate and carry boats. Flowing forms answer as their source. The empty fluid and tank-only fluids emit no light, do nothing to an entity and have a fall modifier of 1. Anything that depends on a level, such as lava's current or source conversion, isn't in the record. The record also carries three Fluid facts: explosion_resistance (100 for water, lava and a mod's world fluid, 0 for the empty or a tank-only fluid), randomly_ticks (lava only) and drip_particle (minecraft:dripping_water or minecraft:dripping_lava, none for the rest).

legacy_block(state) is FluidState.createLegacyBlock: the water, lava or mod-fluid block that holds a fluid state (a source is level 0, a flowing amount is 8 - amount, falling adds 8) and air for the empty fluid. It is None for a state no fluid can be in: a tank-only fluid, an amount above 8, a zero amount for anything but the empty fluid, or a source that isn't full.

What depends on a position is on LevelRef, not in this service: fluid_tick_delay(host, fluid, pos) (water 5, lava 30 and 10 in the Nether, a mod fluid's as its fluid_rules parts change it there), fluid_height, fluid_height_for_camera and fluid_can_be_replaced_with(host, pos, fluid, direction). fluid_tick(server, pos) runs a fluid's flow step now; schedule_fluid_tick queues one.

FluidState::matches(constraints) is a pure local check of carried vanilla fields. Unknown properties or noncanonical serialized values return false. A falling source remains a source; a flowing state of level 8 remains flowing. Empty constraints match any state. Validate separately for indexed errors. Neither matching nor validation allocates; explicitly copying a definition may allocate. Unresolved saved tank identities remain FluidIdentity::Unresolved(handle), not world states or tank-only keys.

Fake players

host.fake_player(level, uuid, name) makes, or finds again, a player with no connection in the level in place, as NeoForge's FakePlayerFactory does: a machine that acts as a player (a deployer, a block breaker). It is no online player: the tab list, player counts, sleeping, natural spawning, chunk tickets, statistics and saves leave it out. player.is_fake(host) tells one apart; player.remove_fake(host) removes it.

player.perform_action(host, action) makes it act as a player does, through the game's own path for the action, as that player's packet would run it:

• PlayerAction::UseOn { hand, pos, hit } is a click on a block (ServerPlayerGameMode.useItemOn): reach, the hit's place on the block, the build height, spawn protection and the border, then the block's use and the item's useOn, which is how a block item is placed;
• PlayerAction::UseItem { hand } is a use in the air (ServerPlayerGameMode.useItem), by the item's own ray from the player's eyes and look: a bucket clicked on a block passes, as vanilla's does, and empties when used.
• PlayerAction::InteractOn { hand, target, location } interacts with that entity (Player.interactOn), after the border and interaction-range checks, with the hit relative to its origin. A passed click does not fall back to using the item in the air. The fake keeps its own supplied look, rather than aiming a new ray;
• PlayerAction::Attack { target } is a hit with the main hand (handleInteract's ATTACK, then Player.attack): the border and the attack range, the native mods' attack_entity, then the blow on a player, a mob or another entity, or a fireball, wind charge or shulker bullet turned back. The blow is scaled by the attack strength, as a player's is, so a fake that hits every tick does a fraction of a full blow. A mob doesn't take the fake as the player to answer;
• PlayerAction::BreakBlock { pos } breaks the block at once (ServerPlayerGameMode.destroyBlock): reach, the build height, spawn protection and the border, then the game mode's and the held tool's rules (adventure mode can't, a sword in creative can't, and outside creative a block no digging breaks, destroy time -1 such as bedrock, stays), the native mods' break_block, the tool's wear and the drops. There is no digging time: a machine that digs over time counts its own progress and breaks the block when it is done.

Its items are its own inventory: set the stack in its hand first (through ENTITY_ITEMS or an ItemPlace), and read what is left after. The answer says what happened:

For a machine using an isolated stack, player.perform_action_scoped(host, action, setup) composes that same persistent player's action with temporary state. Build PlayerActionSetup::new(stack, eye, yaw, pitch, secondary_use): the fake acts in survival with a fresh standing body (eye height 1.62), that stack in its main hand, and no other inventory or equipment. Its supplied rotation is used for item rays. Secondary use holds semantic sneak without changing that standing eye height. No second player is created.

The ScopedActionResult contains outcome (the same ActionOutcome), held (the nonempty main-hand remainder) and other (other nonempty inventory stacks, then offhand, carried stack and armor). These stacks are returned to the caller, not kept by the fake. The fake's persistent body, inventory, game mode, look, secondary-use state and action timers are restored even on refusal; world changes and the usual interaction/Parts hooks remain. The ordinary fake safety rules still apply: no screens, sleep, rides, dimension travel, online participation, statistics, advancement credit or network connection. Neither action method can run inside another player turn or an open transaction; the action's own ordinary write paths still run transactionally.

On either side, player.entity().is_shift_key_down(host) reads semantic secondary use rather than a physical key mapping or a crouching pose. On the client obtain the reachable local handle with host.local_player() (or host.entity(id)); it reads live secondary use even before the next movement tick updates the body's shift flag. On the server the existing entity flag is read, including a scoped fake's setup. Stale handles and clients without a joined local player return None.

What a machine does beyond a player's action stays in the mod: its own mining progress and catching world drops. Scoped actions retain player reach, protection and border checks; eye placement is supplied by the mod.

Testing a trait mod

Enable the testing feature on the mod's horizon-mod-api test dependency. Then testing::with_mods takes an owned Mods list and runs a closure with it installed on the current thread. It restores the previous list even if the closure panics. The test allocation is retained because dispatch exposes a static slice. Call dispatch_<hook>(&mut host, args…) inside the closure to build the event as the game does.

testing::FakeHost is a server and client host built from one small fake per service, so a test runs without the game: registries (item reports, items with slots of their own, the loaded mods), players (who is online, their inventories by slot, what was given to them and shown on their action bar), level (blocks, block entities with item slots, fluid tanks and energy storage as the game answers them, and entities), commands and messages (what ran and what was said), and journal, which keeps the players and the level on each transaction and puts them back when it aborts. Set the world up through those fields, run the code under test with &mut host, then read the fakes back:

#![allow(unused)]
fn main() {
use mod_api::testing::{FakeHost, with_mods};
use mod_api::{self, ClientHost, ClientTickPreEvent, Hooks, ModEntry, dispatch_client_tick_pre};
use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};

#[derive(Default)]
struct Counter(Arc<AtomicUsize>);
#[mod_api::horizon_mod]
impl Hooks for Counter {
    fn client_tick_pre(&self, _: &mut dyn ClientHost, _: &mut ClientTickPreEvent) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}
let count = Arc::new(AtomicUsize::new(0));
let mods = [ModEntry::new("counter", Box::new(Counter(count.clone())))];
with_mods(mods.into(), || dispatch_client_tick_pre(&mut FakeHost::new()));
assert_eq!(count.load(Ordering::Relaxed), 1);
}

A test of item moves puts two chests in the level and reads back what went where; the transaction's journal is the fake's:

#![allow(unused)]
fn main() {
use mod_api::testing::FakeHost;
use mod_api::{HostTransaction, ITEMS, ItemResource, ItemStack, ServerHost, move_resources};

let mut host = FakeHost::new();
let level = host.level.level();
host.level.block_entity([0, 64, 0]).with_items(1);
host.level.block_entity([1, 64, 0]).with_items(1);
let stone = ItemStack { item: "minecraft:stone".into(), count: 5, damage: 0, extra: None };
host.level.block_entity([0, 64, 0]).items.as_mut().unwrap().slots[0] = Some(stone);

let server: &mut dyn ServerHost = &mut host;
let from = level.capability(server, &ITEMS, [0, 64, 0], None).unwrap();
let into = level.capability(server, &ITEMS, [1, 64, 0], None).unwrap();
let moved = server.transaction(|host, tx| {
    move_resources(host, &from, &into, |_: &ItemResource| true, 3, tx)
});
assert_eq!(moved.ok(), Some(3));
let into = host.level.block_entity_at([1, 64, 0]).unwrap().items.as_ref().unwrap();
assert_eq!(into.count("minecraft:stone"), 3);
}

A Host method no fake answers panics naming it, as every Host method defaults to, so an unexpected call fails loudly. A test can still write its own double for what the fakes don't model, implementing only what its hook calls; testing::FakeJournal gives such a host the same transaction journal over its own state.

If a Host method returns a game value a test can't build, a double can return None instead, as with Players::acting_player() -> Option<PlayerRef>. If the dispatch function itself takes an unconstructible value, such as dispatch_perform_command's &ServerPlayer, test the logic beneath the hook instead. The level hosts are small enough to implement whole. NeoForge's GameTest is the in-game counterpart.

Adding a hook

A new hook needs its declaration in the area file of crates/horizon-mod-vocab/src/hooks/ (/// lines and #[hook(side = "server", contract = "cancel", out = "cancel")] on fn name();; the argument list is in that folder's mod.rs), its native_* function with the placeholder body let _ = (every, parameter); (all its parameters, in order), and a run of cargo run -p xtask -- mod-api. Put that function in crates/horizon-client/src/game/native_hooks/<area>.rs, matching the declaration's area filename. Alternatively, a named hook may live in any logical module under game/, including area folders, mod.rs and #[path] modules. Its target must name that module and Game<'_>::native_<name>. Exactly one matching Game method must exist. Outside native_hooks/, the method must call dispatch_<name> itself: placeholders are not filled there. Remove macros, cfg and cfg_attr from that method so injections can patch it. A refusal names the hook and what to change. These checks run at build time and add no dispatch-time work. The build discovers native hook modules automatically; do not add a module list entry. Shared support lives in shared.rs; fire.rs includes generated dispatch entry points, not hook implementations. That command only replaces the placeholder in its owning area file with the dispatch_<hook> call; commit that source change and the declaration. Fills are idempotent; rerun the command after a failed write. The horizon-mod-api-gen build dependency generates the hook traits, Host methods and dispatch code into Cargo's OUT_DIR when the game and renderer build, including release builds. These generated Rust files are not kept in the source tree or committed, and no manual regeneration is needed after a merge. Every hook needs a mod_api entry: the build fails naming any hook without one. A hook that stands in for a method a vanilla block, block entity, item or menu overrides also gets a scope and a key ({"contract": "collect", "out": "output", "scope": "block", "key": "state"}): the key is a BlockState (routed by its prepared block key for block parts), an &ItemStack, a ModBlockEntity or an id &str, and the generator also puts the method on that scope's part trait (Parts). A body that is neither the placeholder nor already calls the dispatch is an error, and the generator never changes it. Hooks that are free functions outside Game are wired by hand: those crates can't see the mod list, so each calls a callback the executable installs once, such as NativeLoadHooks in horizon-world and NativeClientHooks in the client library (menu_slot_rules, living_breathe, ingredient). A build reports a placeholder still to fill instead of changing hand-written source; run cargo run -p xtask -- mod-api to fill it. Mixin injections go at the head of the body, before the dispatch, so they still run first.

Server attachments

A mod can declare an AttachmentType<T> once and call its get, set, remove, has and get_existing methods with the hook's host and a Holder. T is Clone + Send + Sync + 'static; get returns a clone and inserts the default on first access. has and get_existing read without inserting (NeoForge's hasData and getExistingData): has says whether a value is stored, saved or set, even before it decodes, and get_existing returns None instead of the default. Neither adds anything to the holder's saved data. set runs the optional codec before changing the value, returning an AttachmentError if it cannot encode. Keys are the pair (namespace, name); a key already decoded as another Rust type is an error. On a server, a missing holder is an error, not a new phantom holder; a client keeps a copy for any holder it is asked about (see the sync paragraph below). AttachmentError distinguishes MissingHolder, TypeMismatch, Decode, Encode, InvalidNamespace (a malformed saved compound), InvalidCopyPolicy (death-copy without a codec) and InvalidSyncPolicy (sync without a codec). Every host is an AttachmentStore (and host.attachments() gives it): the typed methods stand on its few erased ones, so they work the same in a native mod and a wasm mod. A value keeps its own Rust type, shared: reading one clones it out, and copying a holder's data copies no value.

AttachmentHolder keeps an existing typed handle when a system needs to store a holder identity: Entity, Player, BlockEntity, Chunk or Level. It is Copy, does not keep anything loaded, and follows each handle's ordinary stale-world and unload rules. Unlike the storage-relative Holder, it carries the handle's world scope.

Import AttachmentQueries to use host.query(&TYPE) on either host side. The returned batch is a snapshot of membership and stored value bindings in the host's current dimension. Its iter() borrows &T without cloning values and lazily decodes saved entries; malformed or incompatible values produce row errors, not defaults. Later sets, removals and unloads appear only in fresh queries. This is a residency view: an entity queued for removal but not yet swept can still appear. Captured handles do not keep holders loaded, and stale writes fail. Interior mutability inside T is not deep-frozen by a snapshot.

On a server, import AttachmentQueriesMut for host.query_mut(&TYPE) (T: Clone). Each borrowed row has holder(), value(), and explicit set(host, replacement) / remove(host) methods. These validate residency against the host's current dimension and then use the ordinary attachment journal. There is no &mut T, implicit transaction, or commit on drop: wrap a system in host.transaction for all-or-nothing writes. Unload or replacement produces AttachmentRowError::StaleHolder. Rows retain captured values even after successful write-through updates.

Traversal follows dense index order: insertion appends, and removal fills its slot with the last row. The same ordered mutation history is deterministic, but the order is neither sorted nor stable across structural changes. Retaining a batch can make the next live mutation copy row metadata and shared pointers once; retaining many batches keeps their old bindings alive. Native acquisition clones only the bucket Arc. Erased values from an incompatible type domain report TypeMismatch rather than falling back to saved decoding.

#![allow(unused)]
fn main() {
use mod_api::{AttachmentCodec, AttachmentError, AttachmentType, Compound, Holder, Tag};

static COUNTER: AttachmentType<i32> = AttachmentType {
    namespace: "example", name: "counter", default: || 0,
    codec: Some(AttachmentCodec {
        encode: |n| Ok([("count".into(), Tag::Int(*n))].into()),
        decode: |data: &Compound| match data.get(&"count".into()) {
            Some(Tag::Int(n)) => Ok(*n), _ => Err(AttachmentError::Decode),
        },
    }),
    copy_on_death: false,
    sync: false,
};
// Inside a server hook, or mixin code, with `host: &mut dyn ServerHost`:
if !COUNTER.has(host, Holder::Chunk([0, 0]))? { /* chunk carries no counter yet */ }
let old = COUNTER.get(host, Holder::Chunk([0, 0]))?;
COUNTER.set(host, Holder::Chunk([0, 0]), old + 1)?;
Ok::<(), AttachmentError>(())
}

For mixin code, see The typed API from mixin code.

Use Holder::Level, Holder::Chunk([x, z]), Holder::BlockEntity([x, y, z]), Holder::Entity(id), or Holder::Player(uuid). Entity IDs cover every entity in the level apart from players: mobs, items, experience orbs, projectiles, tridents, falling blocks, primed TNT, fireworks, boats, minecarts, armor stands, cushions, item frames, paintings, End crystals, the ender dragon, ominous item spawners and the server's OtherEntity records. An entity keeps its UUID through saves, so its saved attachments load back with it; an orb saved with a count above one loads as several orbs, and only the first keeps the attachments. Player UUIDs cover online guests and the acting player. Mutable level hosts can access their level, loaded chunks and block entities; read-only level hosts cannot access attachments. Unserialized values disappear on unload or restart. A saved value is stored under horizon:attachments, then the mod namespace and attachment name, as {value: <compound>, copy_on_death: 1b, sync: 1b} (a flag is omitted when false). Unknown mods' saved entries survive load and save without being decoded. Level attachments use the dimension's data/minecraft/horizon_attachments.dat SavedData file, not level.dat.

A type with sync: true sends its value to Horizon clients when get creates the default, on set and remove, and on demand with AttachmentType::sync_data(host, holder); changes made in one tick are sent once, at its end. The recipients are the players who track the holder: guests who were sent a chunk for a chunk or block entity, who track an entity for an entity, the player and those tracking them for a player, and everyone in the level for the level. A client also gets all of a holder's synced values when it starts seeing it: a chunk sent (with its block entities), a level joined or re-entered, an entity tracked, and its own player. With no native mod loaded nothing is sent. The wire form is the codec's compound, so sync requires a codec.

Only Horizon clients are sent values. A message with a namespace or name over 256 characters, a value that cannot be written or a payload past 1 MiB is not sent.

On a client, Host::attachments returns a copy of what the server synced, which get decodes; set and remove change only that copy, which is dropped when the chunk, entity or player goes. A client keeps no copy for the level hosts (LevelRandomHost): they stay server-only there, though their changes on a server are synced.

copy_on_death requires a codec. Player respawn copies opted-in entries via their encoded representation, including raw entries of an absent mod; other entries are removed. Living-entity conversion is not supported. This follows the default supplier, optional server-side persistence, player-respawn option and sync with a StreamCodec (with syncData) of NeoForge 26.3's public AttachmentType.Builder contract, and IAttachmentHolder's hasData/getExistingData, but not its holder-aware supplier, custom copy handler, conditional serialization, the sendToPlayer predicate, AttachmentSyncHandler partial updates or a wire codec apart from the disk codec.

The API owns these public names. Their engine-independent storage and query index live in horizon-mod-runtime, which depends only on the shared vocabulary in horizon-core; world and game storage use the same implementation.

Host helpers and remaining gaps

Host exposes the documented Game helpers declared by area in crates/horizon-mod-vocab/src/host/<area>.rs, one trait per area; Host, ServerHost and ClientHost are the unions of those traits, so a mod calls through them and never names an area trait. Each helper keeps its receiver and documentation; a helper without self (config_files) takes &self in Host. Level services stay on the level hosts above. For the per-method comparison with NeoForge's block, item, entity, block-entity and fluid extension interfaces, including which gaps are tracked, see NeoForge extension coverage. For item registry facts, host.item_crafting_remainder(&stack) returns a count-one plain remainder stack, or None when there is none or the item is unknown. Horizon currently stores only the remainder item id, not a template's count or components. host.block_item(stone) returns its item registry name; an unavailable block mapping returns None, while a known block with no item returns Some("minecraft:air"). Both reads are available on either side.

For engine contributors, every area method declares its load access once with #[access(...)]. Metadata admits registry facts during setup and reload; WorldOnly, ClientSetup and PublishedResources retain their phase-specific contracts. The area's host_area attribute builds the test-double defaults, and the API generator emits every game forwarder at build time. Implement only the inherent Game function with the same name, not a hand-written forwarder. Static implementations use #[static_call]; service accessors use #[service]. A helper's receiver also exposes it on that handle. Receivers come from public *Ref structs in mod_api.rs: BlockEntityRef gives block_entity, for example. Adding a handle requires no separate generator registration. The following documented Game helpers are not in the trait yet:

• spawn_mob, mob, mobs, block_in_tag, item_in_tag, server_block_in_tag, server_item_in_tag, server_block, set_display, sidebar, experience_orbs, item_entities, player, panel_recipes, recipes, component, set_component, remove_component, spawn_falling_block, explode, container_slots uses gameplay-private types.
• with_mod_block_entity is generic, so its signature cannot be called through dyn Host.

Experience-orb values use vanilla's signed i32 representation in ExperienceOrb, ServerHost::set_experience_orb, and the pickup and merge hooks. Reading or changing a value preserves zero and negative saved values rather than clamping them through an unsigned representation. A negative value does not grant positive experience when picked up.

Advancement triggers instead live on PlayerRef::trigger_criterion, with a mod-owned CriterionTest and the game's scoped CriterionContext resource. The context keeps real world-aware item predicates; it is not a conditions-only snapshot. See advancement triggers for the contract and the wasm runtime's current same-group callback limitation.

A mod that consumes a block use can run vanilla advancement predicates and rewards through PlayerRef::trigger_block_use(host, pos) or PlayerRef::trigger_item_used_on_block(host, pos, original, after). These server operations use the player's own level and never read inventory. Default use fires default_block_use, then any_block_use, both without a tool: the default helper is specifically tool-free, not general default block use while holding an item. Item use fires item_used_on_block against original (copied after a before-block PASS and before block/item effects), then any_block_use against after (that original hand stack mutated in place, excluding a replacement swapped into the hand), in that order. Consuming right-click/before-block cancellation already fires automatic any_block_use only; do not call either pair helper for it, which would duplicate any and add an inner trigger. This follows ServerPlayerGameMode.useItemOn and ServerGamePacketListenerImpl.handleUseItemOn; the predicate evaluators are DefaultBlockInteractionTrigger, ItemUsedOnLocationTrigger, and AnyBlockInteractionTrigger.

Ok(()) means the player was reached, even if no criterion matched. Failures are NotServer for a remote client, PlayerUnavailable for a stale, offline or displaced handle, UnloadedChunk for a position outside loaded chunks, and Stack(StackWriteError) when the item boundary rejects either stack before any trigger fires. Native and wasm use the same generated operations. The minecraft: guard on trigger_criterion remains: this grants no general access to fire arbitrary vanilla triggers.

The following catalog hooks are not in the trait:

• player_command, item_decorations, client_resources_reloaded, camera_shake, screen_key_pressed_pre, screen_char_typed_pre, screen_mouse_scrolled_pre, use_duration, use_animation, can_eat, living_entity_use_item_start, living_entity_use_item_finish, render_hand, shader_params and block_highlight.
• biome_colors, camera_distance, compute_fog_color, compute_fov, data_pack_files, mob_submit, mouse_button_pre, mouse_button_post, player_respawned and tags_updated.

The client render_tooltip_texture hook (NeoForge's RenderTooltipEvent.Texture) picks a tooltip box's look. Setting texture to a tooltip style <namespace>:<name> draws the GUI sprites <namespace>:tooltip/<name>_background and _frame from the resource packs, nine-sliced by their gui.scaling metadata or stretched without it, as vanilla draws an item's tooltip_style; the atlas a resource reload restitches is the one drawn. Left None, the box keeps Horizon's solid fills, whose background and top and bottom border gradient colours it changes as mutable ARGB u32 values; it does not change text colours. It covers solid-fill item tooltips (including creative, recipe book, chat, trading and bundle-selected item names), screen text boxes, and native panel tooltips. The stack is None for text-only boxes, including recipe-book item lines where the stack is discarded before drawing. Sprite-based screen tooltips (including options and title screens) use a separate renderer and are not covered.

Tooltip component geometry

render_tooltip_gather_components preserves the mixed text/image list, including an image inserted immediately after the name. Wrapping splits text in place. The text pass visits the entire list before the image pass starts; both passes advance through the same component heights, with 2 extra pixels after the first component of an item tooltip. Each image callback receives the box's left edge and its own running top, but the whole content box size, not TooltipImage.size. That field is the component measurement used to reserve space. The box width is the widest component; its height is the sum of heights, minus 2 normally, with no subtraction for item tooltips containing multiple components. Text components measure 10 pixels high. Factory registration and selectable fonts are separate capabilities, not provided by this geometry contract.

Camera and collision reads

ClientHost::is_paused() reads the applied client pause state, not whether a pause screen is open. A multiplayer game continues running while its pause screen is open. The pause-change pre hook sees the old state; the post hook sees the new state.

ClientHost::playing() is true while the player is in the world with nothing over it: no screen, title, sign editor or book, so keys and zoom apply. ClientHost::mapping(name) reads a vanilla key mapping (key.forward, key.left, key.back, key.right, key.jump, key.sneak, key.sprint, key.attack, key.use) as a KeyMapping: whether it is held (KeyMapping.isDown) and the label of the key it is bound to, as Controls shows it. It is None for any other name. Both read without &mut, so the HUD and screen hooks can ask them.

ClientHost::clipboard_text() reads the system clipboard (KeyboardHandler.getClipboard, empty text when it holds none) and ClientHost::set_clipboard_text(text) writes it (setClipboard; empty text copies nothing). Both work only while the game handles a key, mouse or typed-text event, from the window or from the control socket (horizon-ctl key, mouse, type and its clicks): a key, mouse or screen hook that fires inside one, such as Ctrl+V into a mod's own field. At any other moment (a tick, a frame, a packet) the read is None and the write is false with nothing copied, so no mod reaches the clipboard without the player doing something. Both are None and false on a server, and take &self, so a screen hook can call them. Vanilla's KeyboardHandler has no such rule: Horizon adds it.

The camera() helper returns the most recently extracted world frame's camera, or none before one exists. Its position, interpolated eye height, partial tick, angles, final FOV, near/far planes and dimension accompany column-major view and projection matrices. The view is camera-relative and includes bob and spin; projection uses reversed Z. Earlier callbacks in a frame can see the previous frame. block_collision(pos) returns block-local [min_x, min_y, min_z, max_x, max_y, max_z] boxes with an empty collision context; unloaded blocks and collision errors give no boxes.

ClientHost::set_camera_type(type) is a queued client-only effect and takes &self, so shared callbacks such as camera_pose can request a perspective. camera_type() reports the latest request immediately; several requests coalesce to the last one. Requests before or during camera_pose apply before that frame's final camera, FOV and spectator post effects. The pose hook runs only once: its explicit position or angle overrides survive a refreshed vanilla camera. Requests from later render callbacks apply at the next frame's extraction. Setting a type never emits camera_type_cycle; F5 alone cycles, and its final event choice wins over requests made inside the cycle callback.

ClientHost::crosshair_target() returns the ordinary interaction-range target as CrosshairTarget::Block { pos, state, hit } or CrosshairTarget::Entity { entity, point }. The block hit contains its world-space location, face and inside flag; the entity point is also in world coordinates. It uses the game's current targeting ray and block/entity reach, respects blocks occluding entities, and returns None on a miss or without a client world. It can be read with a screen open. entity is an EntityRef carrying the current client level's epoch and network entity ID, including dragon parts. It becomes stale when the client level is replaced or the client disconnects; a same-level respawn keeps its epoch. This supplies identity, not client entity reads: the server-only entity data methods still reject client handles. Unlike view_hit and raycast, this does not find blocks in distant terrain or return a block behind a targeted entity.

Combat targeting

ClientHost::targeting() and set_targeting(ClientTargeting) control liquid picking, entity occlusion and an optional crosshair entity override. Defaults preserve ordinary vanilla targeting. Set pick_liquids to include source and flowing fluid shapes, or hit_through_walls to ignore block occlusion for entity picks and attacks. An entity override must name a live entity in this client level; stale or self handles make the setter return false without changing the controls. The setter requires a logged-in client world. An override is rechecked for reach, held-item range and occlusion when used and disappears from reads after its level is replaced.

Reach remains attribute-backed: use the server player's living handle and set_attribute_base(host, "minecraft:block_interaction_range", value) or "minecraft:entity_interaction_range". The client's cached reach follows the server's attribute updates. Client targeting controls do not grant extra server reach.

client_attack_target receives a mutable targets list before an ordinary melee click (spear jabs use their existing path). It starts with the crosshair entity. Replace it for redirection, append for multiple hits, or clear it to suppress an entity attack. Flow::Cancel cancels the batch. There is no batch cap; duplicates are sent once in first-occurrence order. Each target is checked again against live handles, attackability, reach, held-item range and the occlusion control. Clearing an entity hit does not mine the block behind it; an empty list on a block or miss keeps the ordinary path. Each accepted hit uses normal attack packets and prediction. Server validation and cooldowns still apply. Native and Wasm mods use the same typed API.

Item model values

Conditional, numeric and categorical item model properties and item tint sources receive an API-owned ItemStack snapshot. The engine's resolver keeps its own StackView; that engine type is not part of mod_api. This applies to nested bundle contents as well as the outer item being drawn.

bundle_selected is the runtime bundle selection index: -1 means none. It is not a saved component and is deliberately separate from the stack's component patch. The patch contains explicit overrides and removals, not merged defaults. The host is &dyn ClientHost for each callback. Only answer property names or sources the mod owns; unanswered callbacks retain their existing defaults.

ItemTintSourceEvent.config is a borrowed Tag, converted once from the tint's JSON definition at load. Read fields with Tag::get and match tag variants. Invalid payloads refuse model loading; resolving a tint does not convert or clone its payload.

A native or wasm listener sees the same owned values. Snapshot construction occurs only after the subscription check, so a model resolution with no listeners does not allocate or encode a snapshot. An empty or unresolved resolver view does not dispatch an invalid stack; its property or tint retains the unanswered default.

Owned item values

ItemStack is the mod API's own nonempty value, not an engine inventory slot or a borrowed rendering view. It contains an ItemKey, a nonzero count, an optional numeric damage override and a lazily allocated component patch. Plain stacks allocate no component storage. An empty slot or a consumed stack is None; it is never a zero-count ItemStack.

Every loaded item, vanilla or modded, has an ItemKey. Resolve identifiers through Host::item_key once when loading data and retain the key. Forward references requested during registration keep their slots when the load completes; unresolved references refuse the load. Keys are process-local identities, not persistent names. Tags likewise have retained TagKey identities, while their item and fluid membership is read through Host::tags and changes on reload. Unknown tags are empty; unavailable authoritative mappings return None.

Stored values and effective components

Count and component edits do not consult the game. new refuses zero; set_count and grow refuse invalid or overflowing counts without changing the original value. Consuming split and shrink return optional portions so consuming the last item needs no empty sentinel.

The damage representation has three states:

damage() returns the stored number or zero. damage_component() distinguishes an explicit zero from no numeric override. set_damage(u32) is infallible; the game validates its effective maximum when accepting a write. Adding only a maximum-damage override to an item does not invent a damage component: explicitly adding Some(0) is what makes that component present.

All numeric damage lives in the optional field. Raw damage entries normalize out of the component patch; malformed numbers, conflicting numeric values, or a simultaneous value and removal refuse the entire replacement. Generic component setters and raw set_components therefore return Result. A refusal leaves the stack unchanged. Typed damage setters do not need an error path.

ItemResource::with_component is also fallible for raw component values. Its default-value elision and without_component preserve the normal prototype-plus-patch semantics. The latter records real NBT removal entries for default components; it is not an unknown-value fallback.

Game boundaries

A consume or death-protection override whose opaque native effect payload cannot be decoded refuses the whole stack write with StackWriteError::InvalidEffectPayload, before any resident state changes. The engine's infallible preserved-component setter remains infallible: invalid replacements retain its prior raw component and decoded cache rather than erasing them.

The items host area owns metadata reads such as max_stack_size(ItemKey) and max_damage(ItemKey). A stack does not take a host just to read a maximum, and an unavailable maximum never turns into a fabricated limit of 64.

The game validates effective count and durability limits, including component overrides, when accepting a resident write. An effective max_stack_size must be in 1..=99, and the presence of max_damage forbids a stack limit above one, even when the current count is one. Removing max_stack_size uses the absent limit of one. Invalid values produce typed errors, not clamped values. A transfer request is different: ItemResource plus a separate amount can request or return more than one resident stack's capacity. The resident writes it produces still have to pass validation.

Game inventory, menus, trades and models keep their engine-owned representations. Native hooks and host methods exchange owned API snapshots. The game converts only after a listener guard, and stages every mutable result before committing any captured output. Invalid hook edits retain those captured engine values. Consuming mutable events such as bonemeal and item_after_vertical_collision lend Option<ItemStack> so a listener can consume the value by setting None.

The item_stacked_on_other bridge commits its clicked slot, cursor and cancellation flags as one unit, including the menu's slot-operation queues and map-id reservations. The block-entity tick, menu-button and menu-quick-move bridges validate their captured snapshot outputs together before applying them. These are output guarantees, not whole-world transactions: independent ServerHost storage writes, commands, messages and other effects are not rolled back on a refused output. Carrier-form callbacks such as bonemeal and item_after_vertical_collision also retain their captured stack outputs on refusal but do not journal independent host writes. The storage-journal follow-up covers that gap. Restricted in-write LevelHost callbacks keep their existing write and random-draw order.

Item-model callbacks receive the owned stack and a separate bundle_selected number (-1 means none). Runtime selection is not a persistent component. Drawing receives the API-owned ItemDisplayContext, not the renderer's enum.

The NBT escape

ItemStack::from_nbt(host, compound) and to_nbt(host) are the NBT escape. They live on the plain API value, not as a second engine implementation in the items host area. They use only typed host key lookup and canonical id metadata, so native and WebAssembly mods execute the same parsing and serialization code. Persistent NBT contains identifiers, never process-local key slots. Unknown ids, malformed values and zero counts fail decoding; unavailable id metadata fails encoding.

The escape preserves explicit zero damage, default-component removals and opaque component NBT. It does not apply resident maxima or materialize prototype defaults. Those remain the responsibility of the metadata service and game write boundary respectively.

Delayed tasks

A server mod asks for a call back after some server ticks with schedule_task, the stand-in for vanilla's MinecraftServer.tell(new TickTask(getTickCount() + delay, runnable)). A closure cannot cross into a wasm mod or outlive the host a hook borrows, so the callback is a hook: the mod passes a u64 token and Hooks::scheduled_task hands it back.

const REMINDER: u64 = 1;

impl Hooks for MyMod {
    fn player_logged_in(&self, host: &mut dyn ServerHost, player: u128, name: &str) {
        // 20 server ticks from now: one second at the normal rate.
        if let Ok(id) = host.schedule_task(20, REMINDER) {
            // Keep `id` if the reminder may need to be withdrawn: host.cancel_task(id).
        }
    }

    fn scheduled_task(&self, host: &mut dyn ServerHost, id: TaskId, owner: &str, token: u64) {
        if owner != "mymod" || token != REMINDER {
            return; // every mod is asked about every task
        }
        // The task has fired and its id is spent.
    }
}

Timing. Delays count ticks the server runs: a paused integrated server does not advance them. A task fires at the start of its due tick, right after server_tick's start phase, in the order the tasks were scheduled. A task never fires in the tick that scheduled it, whichever hook scheduled it, the tick's start hook and scheduled_task itself included: it fires on a later tick.

Ownership. The task belongs to the mod whose hook called schedule_task; the game takes that from the running hook, never from an argument. Outside a mod's hook the call returns ScheduleError::NotInMod. cancel_task answers false for another mod's id, an unknown one, and one that has fired or been cancelled. Every mod hears scheduled_task for every due task, so a mod compares owner with its own id and ignores the rest. Ids are never reused in a world.

Limits. A mod may have MAX_PENDING_TASKS (4096) tasks waiting; the next schedule_task returns ScheduleError::TooMany until one fires or is cancelled. A task that panics does not drop the others due on the same tick: they still run, and the panic goes on afterwards as any hook's does.

Lifetime. The queue belongs to the running world. It is dropped when the world opens or closes (including a failed open or close), and is never saved. A mod that must outlive a restart writes its deadline to its own storage and schedules again when the world opens. A mod's tasks are not cancelled when the mod unloads; the world's close is the end of them.

Extinguishing fire

EntityRef::extinguish_fire(host) exposes vanilla Entity.extinguishFire on players, guests, mobs, armor stands and dropped items. If the entity is burning, it first emits minecraft:entity.generic.extinguish_fire at its feet with volume 0.7 and vanilla's pitch from two ordered random float draws. It then clears positive remaining fire ticks, preserving a negative fire-immunity countdown. Fire-immune mob kinds and dropped stacks resistant to in-fire damage do not count as burning, even when their timer is positive.

The operation reuses the engine's mob sound outbox and entity random, and the player/armor-stand cosmetic random and captured sound route. Dropped items use their own random. Sounds use the entity's sound source, including Players for a guest rather than a generic sound category. It does not draw pitch randomness for a non-burning entity. It returns false for stale or unsupported handles.

EntityRef::clear_fire(host) is the distinct vanilla Entity.clearFire operation: it is silent, draws no random, and preserves the same negative countdown. Choose it only when the original behavior explicitly calls clearFire, rather than using it as a substitute for extinguishing.

Where the mod API is going

The mod API is built toward one shape, and every change to it is judged against that shape. This page explains the shape and why it is the one. The trait mods page says how to write against it today; the project board and the pinned roadmap issue #771 hold the work that is still open.

One clean break

A mod is written against one API, mod_api (the crate horizon-mod-api), and the API keeps one hook per moment. A hook whose NeoForge 26.3 counterpart exists takes its name, side and full contract. Two hooks at the same vanilla call site, _v1 and _v2 pairs included, are one hook, and the old one is deleted, not kept beside it. A veto before an action and a notice after it stay separate when vanilla runs code between them. A hook whose vanilla call site is gone leaves the catalog.

There are no shims: no aliases, deprecated names, fallback paths, version gates or "kept for old mods" branches. An old mod rebuilds, and the compiler says what moved. Removing a path updates every caller, the catalog, these docs, the tests and the sample mod in the same change. A hook with no NeoForge counterpart is judged on its merits like any other.

Every hook is declared once, in the catalog (crates/horizon-mod-vocab/src/hooks/): its name, side, contract, scope and doc. The generator writes everything repeated from it: the Hooks trait, the part traits, the Host traits, the dispatch and the reference. A hook is added by declaring it, not by editing match arms.

The Host is split by side

A hook receives the game through a host, and the host is a small set of traits, so that a call on the wrong side does not compile:

• Host is the shared base: handle constructors, registries and settings.
• ServerHost: Host and ClientHost: Host are generated from each catalog entry's side. Only the server writes the world, so transaction is on ServerHost alone.
• A hook that fires on both sides receives a typed HostSide to match on. A hook fired inside a level write, where there is no game to borrow, receives the read-only LevelHost (a LevelSide) instead.
• Drawing goes through a DrawContext, a trait object given only to render and screen hooks, beside a &dyn ClientHost.

A method with a natural receiver belongs to a handle, not to the host: EntityRef, LivingRef, PlayerRef, LevelRef, BlockEntityRef and the other handles carry the per-object methods. A block entity's lock is the vanilla item-predicate compound: lock reads it and set_lock sets or clears it through the transaction journal. replace_data replaces saved data while retaining the entity's identity and position; it does not change its type. Changing type requires the owning block's lifecycle path, as described in transactional block-entity removal. Reads take &dyn Host; writes take &mut dyn ServerHost. Once a handle method exists, the id-based helper it covers is removed, so there is one way to do each thing. Attachments live on handles too. Commands, players, messages and scheduling are small services reached from the host, not methods on it.

A hook fires with the right host for its moment. A client-side decision that vanilla makes inside a client library is split into decide, fire and apply: the library decides, the game fires the hook with a ClientHost, and the apply re-checks the decision's preconditions and refuses, never recomputes, if they changed.

Load access belongs to the owning thread

Registration has only a RegistrationContext. Each side then enters Setup, Config and World; config loading can read settings and use its existing scoped ConfigFiles service, but cannot acquire world handles, open transactions or call other game operations. Client setup and initial Client/Common configs finish before title, connection or ordinary runtime callbacks begin, so the first client pre-tick is already in World even without an open world. Data and asset reloads temporarily enter Reloading and restore Setup or World when they finish or fail. The catalog marks published asset/data queries as resource_read: completion hooks can refresh sprite/recipe caches from the newly published generation without acquiring a world handle or transaction. Server reload Host reads are restricted to those published facts, registry facts, settings and the mod list; existing data-context callbacks keep DataLoadContext. A forbidden operation panics naming the phase. The game alone advances the thread-local boundary, so the window and integrated server cannot change one another's permissions. Load phases and access lists the once-per-process, per-world and per-reload moments. No additional FML or intermod bus is added.

Registering behaviour

Choose the entry point by who owns the result. For behaviour attached to an existing block, item, entity or menu, implement Hooks::register and call the corresponding method on &mut dyn Registrar. For a subsystem that rebuilds its own table, implement its collection hook. The game owns both the lifetime of the table and the point at which it becomes visible.

Hooks::register runs once at startup, in mod dispatch order, with a RegistrationContext. The registrar records the owning mod, checks for conflicting declarations and reports refusals before installing the table. It accepts registry keys and tags before the final per-game tables are available. When a game resolves its registries and tags, it binds the Parts to the objects they target. Runtime hooks then dispatch to the attached Parts. See registry keys and Parts.

Content mods declare identities and data such as blocks, items, entity types and menus in data/<id>/horizon/. These declarations supply the game's registry entries, models or templates and other data. The startup blocks and items hooks can submit the same declaration types from code and go through the same content checks. Attaching a Part or providing a callback adds behaviour to an identity. For example, a menu declaration describes its slots, while a MenuPart supplies code for that menu's lifecycle. Likewise, the item-scoped item_decorations hook draws after the game's default item icon decorations in slots, the hotbar and other views that use the shared item decoration path.

Tracked gaps in registration

The issues below specify registrations still missing at this revision. Use the existing registration surface for startup declarations and the owning subsystem's collection hook for tables rebuilt during reload. Each builder should collect typed declarations and validate keys before publishing them.

Parts

A per-block, per-item or per-entity moment is a method on a part, as it is a method on Block or Item in vanilla and NeoForge. A mod attaches parts once, in Hooks::register, and the game asks only the parts attached to the thing in question. Trait mods, Parts and attachments covers writing them; the design is this:

• One trait per scope. BlockPart, BlockEntityPart, ItemPart and MenuPart are generated from the catalog entries whose scope names them, so a part on a plain block has no tick method to write.
• A global hook only where NeoForge has a bus event. Where a NeoForge event is the counterpart for the override moment, that event is a hook on Hooks, asked first for everything, and its cancel skips the parts. Where it has none, the moment is a part method alone and has no global form. A mod reacting to its own blocks uses a part; one reacting to every block uses the event.
• A part is configuration. It takes &self and is Send + Sync, like a vanilla Block's properties. State belongs to the game, in the block entity's slots, saved compound or attachments, so it saves, syncs and copies with the holder and is never kept in a mod's statics.
• The same kind twice on one thing is refused at load, naming the mods, and a part's kind is its type. Parts attach by key or by tag, and the tags resolve against each game's own tags. Block dispatch uses a load-prepared API key lookup, refreshed on tag reload. If no part subscribes for that block, the game skips converting the event's state values and write collections. This per-block filter does not restrict ordinary global hook listeners.

Items, fluids and energy are Parts as well, as capabilities in NeoForge's transfer shape. A capability is a CapabilityKey (ITEMS, FLUIDS, ENERGY) for a block entity, and an ItemCapabilityKey (ITEM_ITEMS, ITEM_FLUIDS, ITEM_ENERGY) or EntityCapabilityKey (ENTITY_ITEMS) for a stack or an entity. The game answers a key for what it owns, a mod's provider answers it for what the mod owns, and the first to answer wins. Handlers are NeoForge's ResourceHandler<R>, and every write runs in a transaction opened with host.transaction:

• One journal, in the game. A handler holds no state and no mod writes a journal. A write applies in place; the first write to a storage at each depth snapshots it; a nested commit hands its snapshots to its parent; an abort restores them. Notifications to the world run once per changed storage at the outermost commit.
• One move. move_resources moves items and fluids between two handlers, each step all or nothing, and energy shares its step. A handler that answers more than it was asked or offered is a mod bug: the move is undone and the game warns once, naming the mod.
• Exact units. Fluid amounts are millibuckets. A Fabric amount that is not a whole number of millibuckets (81 droplets) is refused, never rounded.
• Holders have stable identities. An ItemPlace names where a stack lives, so a handler inside an item inside a player's inventory changes the stack where it is, journaled.

Systems that run over many things at once can be added beside the part methods later without changing them, because the game owns the data, the data saves and syncs through the attachment codecs, holders have stable identities, and a per-hook part method stays when a system joins it.

One dependency model, native or wasm

A mod can be built two ways, from the same source: native, compiled into the game, or to mod.wasm, which the game's one sandboxed runtime runs with no rebuild. The only difference between them is the build target.

• [dependencies] in horizon-mod.toml means the same for both: required and optional dependencies, semver against the manifest's versions, dispatch in dependency order, and a mod publishing functions and statics its dependents call. Native links through Cargo; wasm links through the runtime's linker, with one copy of each library shared by its dependents. Both targets use one resolver, keep bundle-order ties, and refuse cycles.
• There is no wasm-only packaging unit and no native-only dependency rule. A change to the model lands for both targets together.
• The wasm interface is generated from the same catalog as the Host, at build time, and never committed: a committed generated file would make every two catalog changes conflict. CI reports the added, changed and removed imports of a change in its job summary, and a coverage test fails on an entry with no binding.
• There is no second API. Every mod_api type is plain data or a resource, both generated, and nothing in the API is written twice for wasm. An API shape that cannot cross is fixed in the API.

Building a mod to mod.wasm is the how-to. The two targets differ in how a mod is checked against the game, because they differ in what they link to:

A wasm mod keeps running on a newer game while the hooks it imports are unchanged. horizon-mod-api therefore always builds for wasm32-unknown-unknown: a hook that needs an engine type takes a plain-data type of the API's own, converted on the game side.

Injections stay, and the API comes first

[[inject]] is the shared native/wasm escape hatch for what the API does not yet reach. The rule is API first: a mod needing something the API lacks asks for the hook that replaces the injection, and the injection is the stopgap until it exists. The injections chapter holds the current forms, the decision ladder and the hook-request format.

The order of the build route

Compiling a native mod against a game already built is the route that makes native mods cheap, and each step rests on the one before:

1. The prebuilt game. The game as a dylib with its metadata, built daily and published as prerelease builds, so a native mod compiles against it instead of rebuilding the game.
2. Slots. Injection targets compiled into the prebuilt game, so a mixin does not force a rebuild. The generated slot points exist; filling them from a mod follows.
3. The internals tier. A per-mod declared list of game internals the prebuilt game exposes. It is native only and logged, and each internal a mod needs is a request for an API.
4. The blend. A wasm mod that also carries slot mixins. An API-typed mixin is filled by the mod.wasm itself, with no native code. A mixin that needs internals ships as source, compiles on install, and marks the package as including native code. The native and wasm parts talk only through interfaces the mod declares, with plain data or resources crossing, so raw internals never reach the wasm side.

A mod that needs a change to a non-slot part of the game still rebuilds the game.

No telemetry

The launcher and the game send nothing about the player or their machine to any server: no performance, crash, bug or benchmark uploads, and no "I'm playing" ping. Reports stay local files the player can read and share by hand. A mod API that reported on mods would break this, so none does; the repository's docs/telemetry.md says what stays local.

What is next

The open work is not listed here, because a list in a page goes stale. It is on the project board, grouped by phase, and the pinned roadmap issue #771 gives the direction. A change to the mod API updates its catalog doc and the pages it affects in the same pull request, so this page and the reference follow the code.

Design: vehicle health layout

Provisional implementation contract for #2741; records the provisional answers A and B, with vanilla default sizing preserved. Approval admits this note only; public counterpart verification remains a shipping gate. Mods supply effective maximum hearts, not rows. The engine prepares one immutable result per visible HUD frame, before reserving space or drawing any status layer. Reservation, vehicle drawing and the player's status layout consume that same result. Cancelling a layer changes drawing only.

Current owners

References are against main at d57e01504e.

• crates/horizon-client/src/game/mobs/mounts.rs:951: draw_mount_hud resolves mount_index, computes capacity, constructs vehicle draws, calls keep_status_rows before gui_layer, then returns capacity even when drawing was cancelled.
• crates/horizon-client/src/game.rs:8770: initializes the frame's HUD room; game.rs:8867 calls mount drawing except for spectators, then passes its returned vehicle_hearts into player layout at game.rs:8903. This shared client presentation route serves single player, LAN and remote servers; dedicated servers draw no HUD.
• crates/horizon-client/src/game/interface/hud_room.rs:59: reserves status keep-outs from draw geometry, independently of whether the layer later draws.
• crates/horizon-client-render/src/hud_layout.rs:473: default capacity; hud_layout.rs:478: ten containers per row, starting at h - 39, stepping up ten pixels; hud_layout.rs:674 selects food using zero vehicle capacity; hud_layout.rs:704 offsets the player's air row using vehicle row count. Player health hearts themselves need no new vertical displacement.
• crates/horizon-mod-vocab/src/client/hud_layout.rs:143: HealthInputs.vehicle_hearts is the vocabulary crossing to player layout. The exports live in crates/horizon-mod-vocab/src/exports/hud_layout.rs:1.
• crates/horizon-client/src/game/native_hooks/shared.rs:2202: gui_layer runs preceding mod layers, Pre, conditional drawing, then Post. Today Post runs even when Pre cancels. Preserve that existing behavior pending verified counterpart evidence.

PR #2697 moves vocabulary hud_layout.rs; PR #2586 touches mounts.rs. Re-resolve these owners after they land; do not create a parallel vocabulary or mount path.

Vanilla and public counterpart evidence

Read vanilla 26.3 with these reproducible queries from the repository containing prepared vanilla resources:

python3 tools/rea_vanilla.py method net.minecraft.client.gui.Hud getVehicleMaxHearts
python3 tools/rea_vanilla.py method net.minecraft.client.gui.Hud getVisibleVehicleHeartRows
python3 tools/rea_vanilla.py callers net.minecraft.client.gui.Hud getVehicleMaxHearts
python3 tools/rea_vanilla.py callers net.minecraft.client.gui.Hud getVisibleVehicleHeartRows

The private Hud.getVehicleMaxHearts(LivingEntity) returns zero for null or a vehicle not showing health; otherwise min(30, ((int)(maxHealth + 0.5f)) / 2). The private getVisibleVehicleHeartRows(int) returns ceil(hearts / 10.0). These are sizing helpers, not public mod hooks. Thirty health therefore means 15 hearts and two rows; 8 current health fills four containers.

Vanilla 26.3 registers minecraft:max_health with default 20.0, minimum 1.0 and maximum 1024.0 health. The prepared vanilla attributes.json records these as raw f64 bits 4034000000000000, 3ff0000000000000 and 4090000000000000, respectively. These registered bounds are readable through Horizon's attribute table: crates/horizon-world/src/attribute_health.rs:79 resolves minecraft:max_health, and attribute_health.rs:114 reads its value. At two health per heart, the allowed effective capacity is 0.5–512 hearts. The default HUD's 30-heart display cap is not the attribute maximum and must not restrict mod output.

Public-only checks of the NeoForge GUI layer documentation and the 26.3 RenderGuiLayerEvent.Pre javadoc were inaccessible. A named sizing counterpart, layer name and cancellation/Post contract are unverified. No NeoForge source or patches were consulted. If public 26.3 documentation establishes a counterpart at this sizing moment, adopt its name, side and full contract before shipping; do not add an alias.

Proposed preparation contract

Provisional name: vehicle_health_layout, client side, with &dyn ClientHost. This is a sizing callback, without DrawContext or cancellation. Inputs are the existing lifecycle-owned vehicle handle, current health, actual maximum health, vanilla default heart capacity and frame dimensions. No second identity generation. Output is a mutable f64 effective_max_hearts, measured in hearts and initialized to the exact vanilla default, including zero at maximum health 1.0. Dependency-ordered listeners see prior accepted output; the last accepted value wins. They cannot independently change rows or real entity health.

Resolve eligibility once after HUD visibility is known and before the first status reservation or mod-layer drawing. No mount, spectator or hidden HUD prepares zero without firing. Recheck the selected handle before applying; if retired, refuse that preparation and use zero for all consumers for that frame, without recomputing. Cache only for that frame, never across riding changes or HUD visibility changes. Move preparation into a sibling module; keep oversized game.rs call-site edits net zero lines.

Validate explicitly supplied callback output at the boundary; an unchanged output retains the previous answer, including a zero vanilla default. Refuse NaN and either infinity, retaining the previous validated capacity; clamp every finite answer to exactly [0.5, 512.0] hearts (equivalently [1.0, 1024.0] health). Zero and negative answers therefore become 0.5; hiding drawing remains the layer Pre hook's job. Apply the same policy after native callbacks and wasm Wire decoding.

Keep fractional capacity separate from whole sprite containers: a half-heart capacity occupies one container. Compute occupied containers as ceil(capacity) and rows with vanilla's ceil(capacity / 10.0) arithmetic, once. Thus 0.5 hearts means one container and one row, while 512 means 512 containers and 52 rows. Vanilla's current-fill arithmetic uses ceil(health) health points and full/half sprite comparisons; 1.0 current health paints a half heart in that one container. This fractional-capacity rounding deliberately differs from the private default getVehicleMaxHearts integer division quoted above, which returns zero for 1.0 maximum health. Preserve that helper's exact default sizing whenever no listener changes output. Fractional capacity is reserved for explicitly supplied listener output; attribute bounds do not impose a minimum on vanilla HUD containers. Retain vanilla's 30-heart default display cap while allowing mod output to 512. Clamp displayed current fill to capacity without altering entity health. A panic/trap discards that listener's output and retains the previous validated value, using the runtime's existing fault isolation and diagnostics.

The prepared record contains effective hearts, derived rows, selected vehicle and health snapshot. Generate vehicle geometry and the status keep-out from it; pass its occupied-container count to HealthInputs, whose integer field yields the same row count. Retain fractional capacity in the prepared record for fill clipping. No consumer rereads max health or calls sizing again. Pre and Post may inspect the prepared sizing but cannot mutate it. A Pre cancellation leaves the keep-out and player placement unchanged. Custom redraws can use the prepared geometry. Post follows the existing layer dispatcher contract.

Native and wasm use the same catalog declaration and API-owned Wire input/output records, generated adapters and validation. Unsupported capability registration must refuse with a named UnsupportedCapability(vehicle_health_layout) error; never silently register an inert callback. The no-subscriber path performs one O(1) subscriber-presence check, uses exact vanilla sizing without an unconditional half-heart minimum and creates no event, serialization, listener scan or extra allocation. Existing draw allocation is unchanged. With subscribers, dispatch only to the indexed subscriber list.

Acceptance matrix

For air-row examples let GUI height be 240. With a vehicle the food row is skipped, so the air baseline is h - 49 = 191, and the air row is drawn at 191 - (rows - 1) * 10.

Test malformed wasm output followed by the built-in layout, frame-to-frame riding changes, one invocation per frame, and no-listener equivalence.

Stages

1. Verify the public NeoForge counterpart and settle the provisional name. Use the registered attribute bounds above for implementation.
2. Add the shared preparation record, catalog/Wire contract and both adapters; update the three consumers together, after reconciling #2697 and #2586.
3. Add focused layout and native/wasm dispatch tests for the matrix, then regenerate hook and boundary documentation. This proposal itself changes documentation only.

Open questions

• Does public NeoForge 26.3 name this sizing moment? Recommendation: retain the provisional name only if no counterpart exists; public evidence decides naming and any required layer dispatch correction.

Design: per-type batched block entity ticks

Provisional; implementation waits for a maintainer decision. This answers #2759. The recommendation is contiguous same-type runs in the existing ticker order, with each entity committed before the next one starts. This reduces outer calls where runs exist; it does not promise one call per type across a whole level.

Existing moments and verified owners

The existing plural block_entity_ticks is not a batched execution hook. crates/horizon-mod-vocab/src/hooks/block_entity_ticks.rs:4 declares a server, read-Host eligibility query, keyed by block, asked for block states at world open. BlockEntityTicksEvent.ticks selects whether a ticker exists; it contains no list of entities. The Part example at crates/horizon-mod-vocab/src/parts/block_entities.rs:334 sets it to true, then implements the separate mutable individual tick. The adapter is crates/horizon-client/src/game/native_hooks/base.rs:1083, called by crates/horizon-client/src/game/native_hooks/shared.rs:3112 (native_ticks). Reuse this eligibility decision and its frozen state tables. Do not turn it into a second execution callback, or introduce a parallel batch moment.

Extend the existing singular execution moment instead: crates/horizon-mod-vocab/src/hooks/block_entity_tick.rs:4 and crates/horizon-client/src/game/native_hooks/base.rs:1162. Replace its individual event/dispatch shape with the approved run cursor shape in one clean break, updating all callers, generated catalog/coverage, examples and the machine sample together. No legacy individual callback or compatibility adapter remains alongside it. A run of length one uses the same listener. It remains a BlockEntityPart listener with &mut dyn ServerHost on both targets.

The loop also invokes built-in hoppers, furnaces and other vanilla tickers. Separate sculk passes (crates/horizon-client/src/game.rs:8565) and client animation work are outside this mod saved-data listener; do not move them into it. Implementation must audit all generated callers and any newly added routes. These anchors identify present owners, not already implemented guarantees.

Vanilla and NeoForge evidence

Inspect the pinned vanilla 26.3 bytecode reproducibly with:

python3 tools/rea_vanilla.py method net.minecraft.world.level.Level tickBlockEntities
python3 tools/rea_vanilla.py method net.minecraft.world.level.chunk.LevelChunk.BoundTickingBlockEntity tick
python3 tools/rea_vanilla.py method net.minecraft.world.level.chunk.LevelChunk.RebindableTickingBlockEntityWrapper tick

Level.tickBlockEntities appends pending tickers before iteration, removes removed entries as it reaches them, and otherwise calls each eligible ticker in list order when normal ticking and shouldTickBlocksAt permit it. New pending entries added during iteration wait for a later pass. The bound ticker checks removal, level presence, chunk ticking and the current block state's validity before invoking the ticker. Exceptions produce a ticking-block-entity crash report. The rebindable wrapper’s tick delegates to its current ticker. These observations support ordered processing and fresh checks, not a whole-level type grouping. The actual rebind and replacement callers remain unverified and must be checked before implementing replacement parity; a replacement must never receive an old entity's saved-data reply.

The public NeoForge block entity guide retrieved for this note is labelled 26.1. It describes EntityBlock#getTicker returning a per-entity BlockEntityTicker and recommends caching expensive work. Its storage section requires setChanged to mark the chunk for saving. This is contextual evidence, not a 26.3 batching contract. The 26.3 BlockEntityTicker javadoc was inaccessible. NeoForge 26.3 batching, limits and fault behavior remain unverified; no counterpart or equivalence is claimed. Only public docs and Javadoc were consulted; no NeoForge source or patches were read.

Proposed execution contract

Choose A: contiguous runs, not B: one call per type across the level. For [A1,A2,B1,A3], dispatch [A1,A2], tick B1, then dispatch [A3]. An ineligible or different-type slot ends a run; do not scan ahead to merge runs. Grouping by type would move A3 before B1 and change neighbor reads, hopper chains and observable side effects. There is no batching measurement justifying that change. Preserve dependency order of listeners within each entity: A1 listener L1, A1 L2, A2 L1, A2 L2. A naive outer call to L1 for all entries followed by L2 for all entries violates this rule. Initially batch only runs with one resolved execution listener; with multiple listeners, use singleton runs through the same cursor contract until a scheduler preserves that order.

A precomputed list of snapshots and an eventual list of replies cannot provide per-entity visibility. Recommend a host-driven, sequential cursor: the outer listener receives the run context, asks for its next entry, processes it, then calls a checked done(result) operation before requesting another entry. done validates and completes that entity's action, and only then may next materialize the next snapshot. This import costs a crossing per entity in wasm; benchmark the net saving rather than advertising elimination of all crossings. Only one entry may be outstanding; double completion, wrong run tokens and out-of-order identities refuse without mutation. Ending a call with an unfinished entry aborts that entry; it must not silently mark it complete.

Each snapshot carries the existing scoped lifecycle holder, type key, position, current block state and saved-data revision. The revision is not the lifecycle generation. Read it beside the holder; cache reuse requires equality of holder, revision, position and state. Recommend a full saved-data snapshot on cache miss and a compact validity record on hit. NeedFull supplies that same entry's full snapshot once without advancing the cursor or executing a second tick. Recheck versions after host writes; a stale reply refuses rather than recomputing or writing over another entity. The saved-data revision owner is unresolved: #2794 is the outside-engine JVM/language-host workstream, not this prerequisite. Identify the actual revision owner and audit every saved-data and inventory mutation path before implementation; cache reuse is gated on complete mutation coverage.

The entity action covers listener Host writes and checked saved-data apply. A1's commit is visible to A2, including neighbor reads. Do not hold a mutable engine entity borrow across dispatch or remove the entire run into placeholders. Revalidate eligibility, residency, holder and state at each next and done. A1 removing A2 means no A2 callback; unloading its chunk means no subsequent callback there. A replacement invalidates the old reply and cache match. New pending tickers wait until the next pass; wrapper rebinding must preserve the vanilla distinction between updating a ticker and appending a new one.

Reuse crates/horizon-client/src/game/runtime/transactions.rs:193,212,293 for action savepoints and block-entity journaling, and the Part instance state contract for holder identity and state. During lifted outer actions, per-entry commit merges into the parent: later entries see tentative earlier writes, but retirement, irreversible effects and journal publication wait for root commit; root abort restores all entries. Do not open a batch-wide transaction in the normal tick path. Refuse saves while an action savepoint is open, so today's temporary placeholder cannot omit an entity from a save. This gate and holder-safe access are prerequisites, not claims about the current singular callback.

Write-back, caches and trust

Results are Unchanged, a validated delta, or NeedFull. Deltas contain changed and removed saved keys plus checked item/data-slot updates; they cannot edit identity or type. Reject duplicate/conflicting keys, invalid slots/stacks, wrong holders, stale revisions and malformed Wire before any apply. Apply the whole entity result atomically through the existing write-back validation. Deleting absent key K or setting V=5 when V is already 5 is unchanged: no dirty mark solely for ticking or receiving a delta. A real write marks the owning chunk and emits required container/comparator effects once through existing owners. A listener's independent Host write still has its own normal dirty effects. This overlaps #1780; this note specifies the desired result, not a general write-back implementation.

API-owned Wire records must represent cursor tokens, holder/revision metadata, full snapshots and results; no engine NBT types, guest pointers or native-only Any cross the boundary. Native and wasm expose the same listener, ordering, snapshot fields, validation and failure outcomes. Unsupported record/state Wire capabilities refuse registration/load with the proposed named refusal UnsupportedBatchTickCapability(type, capability) before ticking.

Bound lengths, total encoded bytes, nesting, cursor lifetime and host operations using shared Wire/NBT and runtime fuel/deadline budgets on both targets. Require at most one full-snapshot retry per entry. Chunk long runs at existing transport limits without reordering; batch capacity must not cap the world's vanilla entity count. A full snapshot too large for one frame needs the approved shared bounded transfer route, never truncation or silently skipping that entity. Exact numeric budgets and that route require approval before code.

On native unwinding or a wasm trap/interrupt, abort the outstanding entity's savepoint and invalidate that cache entry. Keep already root-committed A1. Use the runtime's existing fault policy to disable/stop the failing listener; do not retry it later in this run. Other listeners and built-in entries follow the existing dispatch policy. Process-aborting native panics are unrecoverable. Wasm stop/disable owners include crates/horizon-mod-wasm/src/runtime.rs:426,631; precise native recovery and later-listener continuation need an explicit audit before implementation claims parity. A lifted root abort can still undo A1.

A mod may keep a bounded, evictable cache in its own memory, never saved or synced; losing it only causes a rebuild. Persistent typed per-holder data must use #796/#781's attachment-backed contract. No new engine cache store or generation is introduced. Invalidation notices may be an optimization of existing holder lifecycle notices, never necessary for correctness. A 4096-entry LRU is the external experiment's policy, not an engine or vanilla limit.

Cost and measurement input

Resolve subscribers by type at registration. With no subscriber, one O(1) type-table lookup selects today's path: zero batch events, no grouping, no entity snapshots/copies and zero allocations beyond today's ticker machinery. Do not scan every mod or serialize data to discover whether someone listens. Subscribed cost is linear in processed entries and changed bytes, with bounded buffer reuse; alternating types may offer no batching gain.

reservedbytes' measurements on #2759 are external input, not re-measured here. Their 1000 cooking entities ran on a Ryzen 9 9950X, Ubuntu 26.04, pinned to eight physical cores on a loaded box (load 40–58), fork 964de9d3f, Wasmtime 50.0.1, a custom single-store runtime rather than the group linker, four interleaved runs per side. Retaining guest objects changed tick mean 125.3 to 94.4 ms (median across runs), guest handler 103.9 to 74.6 ms, and collection 7.6 to 13.5 ms per tick. Earlier-build bytes in/out changed 371/287 to 21/24 per entity; in-game host calls 46 to 33, offline 54 to 39. Offline interpreter work changed 774k to 591k operations; full rebuild cost about 260k and delta comparison added about 127k. Post-collection live heap rose 1.1 to 6.2 MB. All results still used one call per entity; batching was not measured. They motivate cache experiments and GC accounting, not a claimed Horizon batching speedup.

Existing measurements are crates/horizon-mod-wasm/tests/bench.rs:84 (1000 fake in-memory dispatches) and crates/horizon-client/src/game/modding/native_live_holder_tests.rs:46 (real Game holder path). Neither establishes this proposed batching's performance. Measure no-listener, singleton, long-run and alternating-type scenes on both targets, including collection, memory, payload bytes, host calls and multi-listener order. Do not promise an improvement until those results include the cursor cost.

Batching ships only with a measured total tick win on a real prepared-data scene in the optimized profile, including cursor crossings and GC. The no-mod tick must remain within measurement noise, and the build must change no saved data. These are shipping conditions, not optional performance claims.

Acceptance matrix

These are proposed implementation tests with literal expectations, not checks executed for this documentation-only change.

Proposed implementation stages

No Rust, runtime promise or benchmark result is added by this note.

1. Approve ordered runs, cursor/per-entity commits and multi-listener scheduling; complete wrapper and public NeoForge 26.3 verification.
2. Audit revision mutation coverage, holder-safe live access, save refusal, rollback and fault continuation with the lifecycle/write-back owners.
3. Specify API-owned Wire records and budgets; update the existing singular hook, generator, adapters, all callers and coverage in one clean break while retaining the plural eligibility moment.
4. Implement and test native/wasm matrix cases through the real holders and transaction owners; integrate changed-only apply with #1780.
5. Measure both existing benchmark paths and real ordered world scenes, including GC and unused-path costs, before claiming batching support.

Open questions

• Execution shape: approve the cursor and singleton scheduling for multiple listeners. Recommendation: preserve exact order even at reduced batching gain; an eventual reply list cannot satisfy immediate visibility.
• Revision completeness: identify the actual saved-data revision owner and coordinate #1780; #2794 does not own revisions. Recommendation: require saved-data/items revision coverage and atomic checked apply before enabling cache reuse; never treat generation as a revision.
• Replacement and faults: confirm wrapper rebinding and native recovery, plus whether remaining healthy listeners continue after a fault. Recommendation: use the existing lifecycle and runtime policy, with no retry of a stopped listener and no stale successor writes.
• Transport capacity: approve numeric shared limits and full-snapshot transfer. Recommendation: bounded streaming/chunking that preserves vanilla capacity; no arbitrary entity-count cap or truncated data.
• Benefit gate: recommendation: require measured total tick improvement with the per-entry import and GC included before enabling a performance claim. NeoForge 26.3 equivalence remains unverified until public evidence is available.

Design: Source-validated guest point artifact

Provisional proposal for #2553. Docs only; this is not approval to skip source validation or a speedup claim. The proposed answer is conditional: an SDK-produced, identity-bound artifact can replace repeated discovery only when it carries the complete validated point, private-type and site input. Keep the full-source generator as an independent check. A supplied --catalog alone never authorizes this route.

Measure actual-mod cold builds after #2596's interface cache first. Do not build or ship an artifact on an estimate; proceed only after the measured post-cache baseline demonstrates worthwhile remaining work.

What remains after the interface cache

#2552 and #2596 are merged context. The latter already caches source interfaces locally and preserves unchanged output timestamps. Repeating the original uncached premise would overstate the remaining problem. Verified owners on the current source tree:

A target-cold build with an empty OUT_DIR must still create these cache entries. A cache hit still reads/hashes inputs, parses smaller summaries, constructs point and private metadata, discovers sites and emits/parses/formats Rust. Source traversal, generator compilation and downstream guest compilation remain possible costs. Their current proportions have not been measured here. Cache reuse across build-script executables or fresh targets must be measured, not assumed.

Vanilla 26.3 is the gameplay specification; this Rust SDK generation facility is Horizon-specific and changes no vanilla call site. No vanilla declaration is claimed as a point-artifact contract. The NeoForge public documentation separately documents its modding API and Gradle toolchain; no equivalent 26.3 point/type/site artifact contract was verified. The public 26.3 javadoc could not be fetched (HTTP 503). NeoForge limits and equivalence remain unverified; public documentation is required before adopting any such contract. No NeoForge source or patches are inputs to this proposal.

Proposed contract and alternatives

Prefer a generated input artifact consumed by the existing validator and emitter, not arbitrary precompiled Rust supplied by a mod. The SDK producer runs full source validation once against its exact staged source. Preserve canonical point order, signatures, host side, head/return behavior, API and internals capability refusals, private lexical types/fields/exports, site definitions and IDs, and the complete inputs to layout computation. Use the existing API-owned representations and one explicit Wire derivation; do not add a second serializer or substitute internals access when an API capability is unsupported. Carry existing refusal reasons through artifact generation and refuse unsupported selected capabilities at registration with a named diagnostic.

A safely narrowed scanner is the alternative. It must resolve the complete transitive module/type closure, imports, target-dependent paths, private lexical scope, global point order and sites before pruning work. Selecting a single function name is insufficient: unselected records still contribute public shape and layout. Recommend retaining full scanning until a closure proof and equivalence fixtures establish safe narrowing. Both candidates use the same emission rules; the independent check bypasses artifact loading and the disposable interface cache.

The authoritative identity is a canonical manifest produced alongside the SDK, anchored in the chosen engine distribution or locally validated source tree, not an engine ID asserted inside mod input. The trusted manifest comes from the Nightly build and is signed with the same key as that build; verify that signature before trusting artifact digests. Bind:

• Exact engine build and staged-source identity, including private staging plans, source bytes and normalized repository-relative paths; directory membership, additions and deletions are inputs too.
• Generator/parser and artifact schema revision, API/Wire declarations and signatures/layout inputs, point/internals catalog bytes and site definitions.
• Canonical selected names (including head/return distinction), target/cfg/features, toolchain and relevant build/profile settings. A reusable complete SDK payload may serve several selections, but each derived build admission binds its exact set.

Use content digests rather than mtimes. Check artifact availability, bounded header and expected identity before decoding its payload. Verify payload length and digest against trusted manifest data, then run structural and semantic validation; a self-reported checksum does not authenticate a modified payload. A local source edit invalidates the SDK identity even if the release name is unchanged. For local source builds, full regeneration establishes the new identity. For an SDK-only build without matching source, refuse with the mismatched field and rebuild/reinstall guidance. Missing, stale, unknown-schema or corrupt artifacts may regenerate only from the exact matching available source through the current full generator. This is recomputation of current inputs, not an old-mod compatibility path; never silently accept stale definitions or omit a selected row.

Mod inputs, selection strings and artifact bytes are untrusted. Before allocation, require bounded file size, row counts, string lengths, nesting and cumulative payload bytes; reject duplicates, unknown selected names, invalid paths and out-of-range IDs. Do not execute artifact Rust or callbacks during admission. Proposed diagnostics are ArtifactIdentityMismatch, ArtifactCorrupt, ArtifactLimitExceeded and SelectedPointUnsupported (names subject to review). Malformed input returns a build error; internal generator panics abort that build, never produce a partial artifact. Publish only complete output atomically.

Native and wasm keep one dependency and api/internals contract. Native retains exact engine-build loading; wasm retains interface linking. Artifact build identity is stricter provenance for generation, not a new wasm runtime exact-build restriction. No new Host, callback, lifecycle holder or generation counter is introduced. No world mutation, journal, retirement or save boundary is involved. Admission happens during builds; unused feature cost is zero runtime work, including zero tick scans, allocations and no-listener dispatch changes.

Packaging and module identity

Coordinate packaging with open #2815. Its reviewed diff adds versioned mod-catalog.json to SDK/source staging, with schema_version, api_version, hooks and public point descriptions. It is a discovery surface, not proof of complete private layouts or site definitions. Do not overload it into an executable generation contract or assume it contains private source plans. Recommend a sibling generation artifact referenced by a trusted SDK manifest, owned by the same staging pipeline. Avoid a committed shared hash that every point change must edit; regenerate and compare in drift checks, with feature-scoped fixtures.

Open #2697 overlaps generator build.rs, points.rs and points/source.rs; open #2524 overlaps build.rs. Reconcile their final ownership before code work. The interface-cache file and point build script are not touched by those reviewed diffs. This note reserves no implementation files.

Byte-identical module identity is the default admission policy. Refuse a mismatch with a diagnostic naming its reason and the differing identity field; never silently accept it on an estimate of equivalence. Identical effective inputs must yield byte-identical generated definitions, point/site IDs, layout values and module identity between routes and across repeated runs. Preserve current path remapping and compiler metadata handling (crates/cargo-horizon-mod/src/wasm/group.rs:625). Compare generated Rust, embedded identities, package points digest and module bytes separately; a matching POINT_LAYOUT alone is insufficient. Adding an artifact dependency or changing build-script inputs can itself change compiler/build identities. Any unavoidable difference needs an explicit explanation, loader/linker compatibility evidence and maintainer approval before adoption; never normalize away the difference in the test or repeat the rejected profile-override experiment as a solution.

Acceptance and measurements

These are proposed literal fixtures, not executed results.

Measure an actual mod build with representative selected points and private type/site use, after #2596. Run 3 cold actual-mod builds per route: current cached full generator, artifact candidate, and narrowed scanner only if implemented. Hold engine, source, selected names, toolchain, target/features, profile, machine and parallelism constant. Define cold as a fresh Cargo target and generator-interface cache for each run; report filesystem/OS cache state and reuse of downloaded sources separately. Report all 3 total wall times and all 3 generation times, not just averages. Also report artifact production time/size, admission/hash/decode, source discovery, emission/formatting and guest compilation time so moving work to SDK production is visible. A separate warm-cache series characterizes #2596; it must not be mixed into the cold series. Check equivalence before interpreting timings. There is no speed threshold until evidence supports one, and historical fixture timings establish no actual-mod speedup.

Proposed stages and open questions

Stages: first collect the post-cache baseline and identity inventory; then agree manifest/authentication and limits with SDK staging owners; then implement artifact production/admission using existing validation/emission; finally run equivalence, corruption and actual-mod measurements before deciding whether to enable the route. Put future logic/tests in separate modules; no growth of the over-limit crates/horizon-client/src/game.rs for instrumentation.

• Trust anchor and packaging: recommend a sibling artifact authenticated by the engine SDK manifest; agree its manifest owner and local-source verification procedure with #2815 before implementation. A payload digest alone is insufficient.
• Concrete resource limits: recommend finite byte/count/depth budgets derived from the complete current SDK plus measured headroom; choose literal limits before shipping. No vanilla capacity is reduced by this build-only proposal.
• Identity differences: recommend exact preservation by default. If artifact integration changes compiler identity despite equivalent output, obtain a maintainer decision with the measured native/wasm linking consequences.
• Does this remove enough work? Recommend measuring first and retaining full generation if admission plus remaining compilation erases the benefit. Safe source narrowing remains conditional on closure correctness, not a promised win.

Design: typed cauldron interactions

Provisional contract for #1323 and parent #854. This note implements no API. Typed registration, handler shape, prediction and atomicity require maintainer approval before code. The merged #1325 table and #1390 journal are foundations, not a mod registrar.

Vanilla and public counterpart

Reproduce the vanilla inspection with python3 tools/rea_vanilla.py class net.minecraft.core.cauldron.CauldronInteractions, then method queries for bootStrap, addDefaultInteractions, fillBucket, emptyBucket, fillWaterInteraction, fillLavaInteraction, fillPowderSnowInteraction, isUnderWater, dyedItemIteration, bannerInteraction and shulkerBoxInteraction. Query net.minecraft.core.cauldron.CauldronInteraction.Dispatcher get and callers of net.minecraft.core.cauldron.CauldronInteraction interact too. These are pinned vanilla 26.3 bytecode queries; no foreign implementation is used.

Dispatcher.get selects the first matching tag, otherwise the exact item, otherwise DEFAULT. Returning TRY_WITH_EMPTY_HAND from the selected tag handler does not resume the item lookup. All registrations in bootStrap and its default-registration helper are covered below:

Lowering level 1 gives an empty cauldron. Bucket and bottle exchanges use ItemUtils.createFilledResult; washing uses its non-limited-creative form for banner/shulker. Preserve survival consumption, creative inventory deduplication where enabled, returned-stack components, inventory insertion and leftover drops. Washing has its cleaning statistic and BLOCK_CHANGE from lowering, with no fluid sound/event. Transfers have their existing statistics, sound and FLUID_PLACE/FLUID_PICKUP; a bottle lowering also has BLOCK_CHANGE. Successful handlers check the same guards on the client but mutate only on the server. This is why a prediction result and an authoritative application are separate operations.

The public NeoForge cauldron documentation describes RegisterCauldronInteractionEvent.Dispatcher on the mod event bus, an identifier for a dispatcher, Interaction registration by dispatcher and item, and registerToAll. Its 26.1 migration primer describes tags preceding items. The accessible documentation is labeled 26.1, not 26.3. Exact NeoForge 26.3 duplicate policy, overlapping-tag order, reload lifetime, side behavior, prediction and rollback guarantees remain unverified; no 26.3 Javadoc contract was established. No NeoForge source or patches were read. The Horizon rules below are proposals, not claims of NeoForge parity.

Verified owners and routes

These file:line anchors describe the inspected base and must be checked again before implementation.

Paths abbreviated as game/ above are under crates/horizon-client/src/. The vanilla caller query identifies AbstractCauldronBlock.useItemOn as the item dispatch moment. Future implementation must test each authority route above and both remote prediction paths.

PR #2835 owns fluid content/capacity, planned game/blocks/machines/cauldron_contents.rs, and native fluid capability integration. That file is absent at this base. Reuse its BlockKey/FluidKey and resolved resource snapshot when integrated; an interaction entry neither registers fluid capacity nor invents a second fluid table. Powder snow need not become a fluid. A fill recipe must respect the registered level schema and content capacity. PR #2697 owns activity/dispatch restructuring, following vocabulary/loading moves. Declare types in vocabulary and generate facade/transport through the owning generator after that work; do not restore old private point registries. Keep future adapters in small dedicated modules: game.rs, native_hooks/shared.rs and modding/api_values.rs must not grow beyond the fork's file-size gate.

Proposed typed registration

One registration moment, provisionally register_cauldron_interaction, corresponding to RegisterCauldronInteractionEvent. Public 26.3 verification remains required: adopt its exact names (Dispatcher and Interaction if verified), side and full contract before shipping, without aliases. No 26.3 counterpart is claimed verified here. Use this moment with typed dispatcher and entry phases if public 26.3 verification requires them. Register by (BlockKey, ItemKey) through a CauldronInteractions registrar with a Host. A custom block opts into a dispatcher explicitly; vanilla blocks come prebound. Several blocks may deliberately share a dispatcher, but binding and conflicts must resolve before publication. A convenience register-to-all expands over the complete prepared dispatcher set, including later mod declarations, never over the live mod list at click time.

Use exact typed items for the initial mod surface. Retain vanilla's tag branch in the same dispatcher; do not expose arbitrary mod tag priority until its counterpart contract is verified. Resolve tags against the authoritative prepared tag snapshot on both sides. Exact entries shadowed by the dye tag stay shadowed, even when washing passes.

Refuse duplicate entries (including attempts to replace vanilla entries) with CauldronRegistrationError::Duplicate, identifying both owners. No override flag, priority integer or last-wins behavior. Dependency order and stable declaration order determine diagnostics, not behavior: a conflicting preparation fails publication rather than choosing a winner. Unknown keys refuse admission as UnknownItem, UnknownBlock or UnknownDispatcher; unknown ordinary held items still pass without a new runtime error. These names are proposed API variants. Unsupported native/wasm callback or codec capability refuses registration as UnsupportedCapability, never silently omitting one target.

Build the entire resolved snapshot at resource preparation and reload, validate, then publish atomically with the existing resource/lifecycle holder. Failed reload retains the prior complete snapshot. Capture that holder in a decision; reload or world closure invalidates the decision through existing identity, without adding a cauldron-specific generation counter. Retain old callback code until its in-flight scopes finish. No retained native pointers or wasm callback indices may survive their owner. Client/server synchronize the existing resource generation and require a matching handler build before prediction.

Handler and prediction contract

Proposed API-owned Wire records: CauldronUse (dimension, target position and state, actor handle, hand, complete immutable held stack, underwater/creative flags and resource identity), CauldronDecision, CauldronPlan, CauldronResult and typed refusal/error enums. Use existing ItemKey, BlockKey, state, stack, lifecycle and handle representations; never serialize internal Action, Rust closures, pointers or borrowed Game state. Every field and result must support the same generated Wire boundary for native and wasm. A callable registration references the runtime's owned callback identity, not a function pointer in a packet.

Split decide, fire, apply. A handler receives a callback-scoped read Host with typed HostSide and returns Pass, Consume, or Success plus a bounded plan. Server fire receives a ServerHost with the game's open transaction for additional supported writes. Client prediction receives only ClientHost reads; it cannot mutate inventories, draw authoritative random, send messages, spawn drops or publish effects. No recursive dispatch from decide; refuse same-action reentry as Reentrant, on both targets. Server callbacks are invoked once per attempt, with nested transaction commits merging into the action. Pass discards all staged writes; Consume may stop item use with an empty plan (vanilla underwater behavior).

The plan describes one target block replacement, an optional exchange of one held item for one returned stack, and optional one sound, one fluid game event and up to two statistics (custom cauldron stat and ITEM_USED, preserving vanilla transfer capacity). Lower-fill BLOCK_CHANGE remains a distinct effect. Washing can edit the held components without an exchange. Helpers implement existing filled-result semantics instead of making mods reconstruct creative and overflow rules. More extensive world changes use existing journal-supported Host operations; unsupported operations refuse the action before any escape. No irreversible I/O during callbacks.

Prediction uses the same decision rules and selected entry but computes only result and visual proposal. Do not call the authoritative handler on the client. Missing matching client resources suppress custom prediction and await the server; they do not guess Pass and launch a second bucket use. Server revalidates target, dimension, actor identity, complete stack/components, relevant reads and resource holder before applying. Changed preconditions produce Stale, discard the entire action, and send normal authoritative correction; never recompute a different interaction inside that attempt.

Track speculative visual effects with the existing use/prediction acknowledgement identity. Confirmation reconciles the proposed block and suppresses duplicate local sound; refusal restores the authoritative block. Inventory, statistics, drops and game events are server-only. One server mutation is committed regardless of whether a client predicted. Preserve Success/Consume/TRY_WITH_EMPTY_HAND semantics and swing behavior across both hands; prediction must not cause a second UseItem after a consuming UseOn.

Atomicity, trust and cost

Open an action child transaction before the server handler, under any enclosing Host transaction. Journal the acting player's full inventory/hand/components and supported attachment writes, stage the block through journal_set_block, and queue sounds, statistics, game events and leftover drops. Validate the whole plan before mutation and again after callback writes. Nested success merges into its parent; only successful root commit publishes effects, block logs and outbound changes. Any refusal, stale read, panic, guest trap or outer abort restores the original inventory and block and discards every effect. Do not execute the callback again at root commit.

The existing journal already buffers cauldron blocks and effects inside a transaction, but the immediate route is not proof that arbitrary mod callbacks are atomic. Before supporting another write domain, prove its undo and publication behavior or return UnsupportedCapability. In lifted passes, defer entity/attachment retirement and journal Remove emission to root commit using the existing lifecycle holder; rollback preserves identity and attachments. Never assign a second generation to restored objects. Refuse saves while an action savepoint is open, including save-all invoked by a handler; extend crates/horizon-client/src/game/world/autosave.rs:6 admit_entity_save (currently a passes_settled check) and audit every save entry so tentative inventory or blocks cannot reach disk. This is a required implementation guarantee, not a claim that every such gate already exists.

Treat decoded plans as untrusted. Validate keys, state property values, current holder, actor scope, hand and stack components before use. Consume count is 0 or 1 and cannot exceed the held count; exchange count obeys the returned item's real stack limit. State must belong to a registered dispatcher and valid property schema; water/snow levels remain 1..3 and lava remains unlayered. Do not impose a smaller capacity than vanilla. Sounds/events/statistics resolve typed keys; reject unknown owned keys, non-finite volume/pitch/positions and out-of-range values rather than clamping malicious data. Proposed sound bounds are volume 0..=1 and pitch 0..=2, preserving these vanilla interactions. Use existing codec/NBT limits for stacks; cap plan at one exchange, block, sound and fluid event, and up to two statistics, with a separate lower-fill event. Finite host-write/nesting budgets must refuse atomically, never truncate valid vanilla work.

Contain native unwinding and wasm traps at callback dispatch, abort the complete action, and apply the runtime's reporting/quarantine policy. A native process abort cannot be recovered. A failing callback must leave the next built-in interaction usable.

This docs-only change has zero runtime cost. Future unused custom dispatch is one indexed (block, item) lookup after the existing constant dye-tag membership test, with no all-mod scan, allocation or Host construction for a miss. Resolve keys, tag membership and register-to-all at preparation. A custom hit pays for one selected handler and bounded plan plus actual journaled writes. Both prediction paths share that indexed dispatcher. Measure miss allocations and callback count before claiming the hot-path requirement complete.

Acceptance matrix for implementation

Vanilla isUnderWater checks the fluid above against FluidTags.WATER; the current game.rs:12350 and remote prediction use an exact water block check. This known discrepancy needs a waterlogged-above oracle case during integration; it is not silently treated as established parity. The immediate adapter also exposes one custom stat while vanilla transfers award ITEM_USED as well: preserve both through the plan and audit the surrounding item-use statistic owner to avoid double awarding.

These are required tests with literal expectations, not checks run by this note. Run on native and wasm and through integrated, LAN, dedicated and fake-player authority routes where applicable.

Proposed stages and open questions

File no issues from this note. First obtain exact public 26.3 event/side semantics and approve this contract with the #2835 and #2697 owners. Second add API-owned vocabulary/Wire records, registration validation and one prepared native/wasm snapshot. Third integrate the shared dispatcher, both prediction paths and mandatory action transaction without growing oversized files. Fourth add real test-mod fixtures, adversarial rollback/reload tests and vanilla oracle coverage for every map/tag branch; then measure the miss path. None of these stages is implemented here.

• Counterpart scope: does public NeoForge 26.3 require arbitrary tag registrations, override, or different event phases/sides? Recommendation: obtain its public contract before freezing names; retain exact-item admission and vanilla tag precedence until then. Do not infer semantics from its implementation.
• Budgets: which shared limits cover additional Host writes and nesting without refusing legitimate vanilla interactions? Recommendation: use existing runtime/codec budgets where sufficient and pin the largest vanilla washing/container fixture before approving numeric journal limits.
• Prediction authority: are read-only custom decisions on both sides acceptable when hidden server state affects eligibility? Recommendation: let the server correct predictions; offer explicit server-only prediction suppression using the same selected entry, never an alternate item-use route. Confirm the missing-client-resource handshake behavior before code.

Design: villager professions and trades

Provisional proposal for #1328 and parent #1043, one workstream. Root approval of the typed public API and save/network gates is required before code. This page implements nothing and does not complete either issue.

Answer and references

Register professions at mod load through one load-owned typed registry. A resolved profession joins workstation/POI selection, level-to-trade-set keys, texture and hat selection, saved resource identity and its network projection. Trade JSON alone cannot register a profession. Use #2339's general resolved-table contract; do not introduce a second generation counter or an independent global registry.

Merged prerequisites #1333, #1360 and #1398 provide vanilla metadata, unresolved names and the frozen vanilla table. Parent prerequisites #1341, #1348, #1352, #1374 and #1379 cover POI, namespaced rendering and unresolved trading routes. #2635 adds secondary work-block tags, not custom profession registration. #2838 overlaps profession sounds/rendering; #2697 overlaps villager hook vocabulary. Coordinate those implementations rather than copying their declarations here.

Vanilla 26.3 reference: inspect VillagerProfession using python3 tools/rea_vanilla.py class net.minecraft.world.entity.npc.villager.VillagerProfession and method for its constructor, bootstrap, static initializer, accessors and all five register overloads (select with --overload-index). Its record holds name, held/acquirable POI predicates, requested items, secondary blocks, optional work sound and an integer-level-to-TradeSet-key map. getTrades looks up that map. The complete bootstrap declares:

Each employed profession uses its corresponding work sound and profession-specific trade-set constants for all five levels; none and nitwit have null sounds. Textures and hats are separate rendering resources, not fields in this record. REA returned no body for the static initializer and synthetic lambda methods, even with raw evidence inspection. Their exact predicate/tag initialization is unverified; the table records the predicates passed by the complete bootstrap, not independently verified membership of ALL_ACQUIRABLE_JOBS.

NeoForge's public 26.1 migration primer documents the move to separate villager_trade and trade_set datapack registries and a profession's level map. The 26.3 primer describes changed trade provider types. Neither establishes the current event contract. The attempted public 26.3 profession documentation at https://docs.neoforged.net/docs/26.3/misc/villager/ was inaccessible. VillagerTradesEvent is the issue's named counterpart; its 26.3 existence, side, mutation ordering, limits and full callback contract remain unverified. Require public 26.3 documentation/Javadoc before adopting an event contract. No NeoForge source or patches are a reference for this proposal.

Current owners and routes

Anchors below were checked against this worktree; they describe current owners, not implemented custom registration. Paths are repository-relative.

Proposed public contract

Proposed names, pending root approval: ProfessionKey, PoiKey, TradeSetKey and ProfessionDefinition, owned by the public mod API. A definition contains its namespaced key and translation component; workstation block-state references; held and acquirable POI key sets; an explicit map for levels 1–5; requested item keys; secondary block/tag references; optional work sound; and villager/zombie texture resource identifiers with hat policy. Empty trade maps are legal. A missing level means no new offers at that level, never a fabricated vanilla key. Trade-set identity is independent of profession identity: test:engineer may select test:engineer at level 1 without suffix or namespace rewriting.

Collect dependency-ordered declarations during load, before world admission, with a load-scoped registrar and shared Host services. World mutation is unavailable at this phase. No per-tick registration callback is proposed. Generate native and wasm entry points and API-owned Wire records together; never expose Rust pointers, closures, serde JSON values or guest addresses as public transport. Refuse UnsupportedProfessionCapability for arbitrary POI predicates, executable trade factories or unsupported render policies rather than accepting inert fields. Do not add a speculative event beside #2697's hook.

Resolve references against the complete candidate graph, including blocks, POIs, items, tags, sounds and trade sets. Build POI-to-profession and texture indexes before publication. Recommend refusing overlapping acquirable POIs between custom declarations until an explicit selection policy is approved. Held and acquirable sets may differ. Duplicate profession keys refuse deterministically with DuplicateProfession, key and both owners, independent of dispatch order. Recommend no replacement of vanilla profession declarations in stage one; ReservedProfession refuses it. Normal pack priority for trade resources remains owned by the existing loader, not a competing profession override mechanism.

The current world epoch belongs to NativeLifecycle in crates/horizon-client/src/game/modding/native_lifecycle.rs:65 and its epoch accessor at line 83. Use that existing load/world lifecycle identity and #2339's table holder for all resolved keys. Session/epoch validation and stale-key refusal follow that owner; no profession-local generation. Publish profession, POI, trade and client projection tables atomically. Failed resolution publishes zero entries and retains the old active set on reload. Registration is fixed for the mod load; reload re-resolves data and tags without rerunning mod startup. Runtime mod unload requires closing its worlds. In lifted passes, queue retirement and journal emission until root commit; rollback emits neither. Refuse saves during an open action savepoint; never persist a candidate registry or provisional offer reset.

Saves, network and resources

Persist fully qualified names in VillagerData, plus existing serialized offers, experience and restock state. On restart resolve names against the new owning load. Missing mods retain Unresolved(name) byte-for-byte, disable job assignment, profession reset and trade mutation, and preserve offers for later restoration. Do not map an unresolved name through u8 wrapping, farmer or none. Render a neutral base layer without discarding identity. Restoring the mod resolves the same name; a different registry order must not change profession or trade-set identity.

Server authority applies to integrated, LAN and dedicated play equally. Negotiate custom registry support before entity pairing through the #813/#2882 negotiation layer. Until that layer lands, refuse a client without the required mod at admission with MissingRequiredProfessionMod(mod_id), naming the missing mod and reason; do not send custom metadata or silently substitute vanilla. API-owned Wire projections carry qualified profession/POI/trade keys, translation data, texture identifiers and hat policy under the existing lifecycle identity. Reuse the common registry snapshot transport: peers validate a complete mapping and acknowledge activation before receiving its numeric references. VillagerData integers are scoped to that mapping, never stable save identities or process-local slots. Invalid/out-of-range ids refuse the packet/session; never leave an old farmer value silently in place. An unsupported peer is refused at admission when custom professions are present; vanilla-only sessions retain their existing protocol. Exact configuration and snapshot packet integration is a protocol review gate, not implemented here.

The server sends resource identifiers, not arbitrary paths or texture bytes. For test:textures/entity/villager/engineer.png, resolve that exact resource and its metadata; current convention-only hat scanning must be extended to declared textures. Resolve the zombie texture separately. Cache None/Partial/Full hat metadata with the effective pack resources; default missing metadata to None and preserve vanilla type/profession head-visibility composition. Client resource reload refreshes this cache without replacing server profession identity. Missing optional textures use the missing-resource visual with a diagnostic, never a vanilla profession substitution. Required client content is checked at admission.

Bounds, failure and cost

Treat all mod declarations and network projections as untrusted. Proposed Horizon limits (not NeoForge limits): 65,536 total professions including all 15 vanilla entries; identifier length unresolved pending owning vanilla codec evidence; 1 MiB per declaration; 64 MiB aggregate candidate definitions; nesting depth 64; 4,096 references per set; at most five level mappings with unique levels 1–5. Reject traversal, malformed identifiers, missing required references, cycles in trade-set references and unsupported tags/providers before publication. Reuse bounded trade decoding; counts, costs, XP and provider results must be finite and fit their engine target ranges, including item stack limits. Never truncate an oversized input. These budgets preserve vanilla's profession and five-level capacity; the implementation must check the complete vanilla trade dataset fits before fixing trade budgets. Identifier admission is gated on evidence of the owning vanilla codec limit or an approved bounded-transfer route preserving its capacity. A 256-byte cap is not approved; dataset fit alone does not establish vanilla capacity.

Native unwind or wasm trap aborts candidate preparation with owner/key context; apply the runtime's failing-mod policy. Process-aborting native panics cannot be recovered. No callback executes while partially installing live tables. Future trade callbacks need a separate approved boundary and budget; they are refused by this declaration contract.

Resolve names and reverse indexes at load. Hot job, trade and render reads use validated indexed keys, with O(1) unused-path checks and no scans over mods, per-villager string construction or registration dispatch. Empty custom registries add no listeners or custom synchronization payloads. Existing secondary sensor spatial work keeps its cadence and skips empty membership. Hat application must use cached resource keys rather than its current formatting lookup.

Acceptance matrix

These are required future tests, on native and wasm, not results of this docs task.

Proposed stages

1. Root approves keys, declaration/replacement policy, budgets and save/network contract after #2339 alignment and public NeoForge contract verification.
2. Implement generated native/wasm registrar and typed POI resolution together; validate duplicates, references and unsupported capabilities before publication. This server half may land as its own change, but main never accepts a profession registration that no client can show: until the client half in stage 4 lands, registration stays refused with a named reason, or both halves land in the same rollup.
3. Route all owners above through the load-owned table, including merchant handles, zombie saves and resource caches; preserve unresolved behavior.
4. Implement negotiated snapshot activation and all metadata send/receive routes.
5. Run the matrix with vanilla parity, adversarial inputs and unused-path cost measurements. No registrar code is authorized by this provisional page.

Open questions

• Exact public registration shape and counterpart? Recommend declarative startup registration; verify 26.3 VillagerTradesEvent before choosing any event name, side or semantics. Root approves the public API before code.
• Custom POI sharing or vanilla replacement? Recommend refusing both initially; permit differing held/acquirable sets but require unambiguous acquisition.
• Network admission and activation? Recommend required custom-content capability and shared snapshot acknowledgment before pairing; protocol owners must approve packet placement and transfer/reconfiguration behavior.
• Final resource/trade budgets? Recommend the limits above after complete vanilla dataset measurement, with existing decoder limits retained wherever stricter without reducing vanilla capacity. No NeoForge limit is claimed verified.

Block entity neighbour changes

A block's BlockPart::on_neighbor_change receives the changed block entity's position in neighbor. On authoritative servers, the comparator invalidation walk visits the four horizontal neighbours, skipping unloaded adjacent chunks. Vanilla comparator processing at each cell runs before its part is notified. This is separate from neighbor_changed, the vanilla block neighbour callback.

A block one cell farther through a redstone conductor receives this notice only when its weak_changes part sets receive to true (initially false). This query belongs to the farther block. Reading that cell never loads a chunk.

These correspond to NeoForge's IBlockExtension.onNeighborChange and getWeakChanges. Using the comparator walk and ordering vanilla before parts are fork decisions. With no parts, vanilla's comparator rules are unchanged.

Block experience and explosions

Attach a BlockPart to the blocks that own the behavior.

exp_drop(level, event) answers Some(points) to replace the vanilla experience sample, before enchantments. None leaves the answer to another attached part and then vanilla. The query receives the dimension, state, position, optional block entity, breaker entity handle and tool. The level host reads without writing; level.block_entity_data(entity) reads the supplied entity's saved data without identity metadata and refuses stale handles. Answers are clamped to 0 through 32,767. Player breaks supply the part's answer to the global break_block event's exp_to_drop, after Silk Touch suppresses the starting amount (except for spawners). An explicit global override is applied as given. block_drops sees the resulting amount afterwards. Level and mob breaks use the shared resource-drop path. A canceled player break or a break that does not harvest produces no award.

on_block_exploded(host, event) runs before the engine removes each destroyed block. The server host permits writes. event.block_entity is a live handle, and entity.data(host) can read it while the block remains. The event borrows the same ExplosionStart description as the global start event: dimension, center, radius, fire, interaction, damage type, source and owner.

The engine still writes air after the callback, including when the callback replaced the block. Vanilla's separate wasExploded behavior follows removal. Air, spared blocks, canceled explosions and explosions that keep blocks produce no callback. Explosions retain their existing zero initial XP behavior.

Both methods route through prepared per-block subscriptions. Unsubscribed blocks build no callback context. Callback panics follow the existing native hook unwinding behavior; the engine does not apply a returned XP answer after a panic.

Client action pipeline design

The window owns input, targeting, animation and prediction. The logical server owns combat and world changes. A single-player window uses the same client path as a window connected to a remote server. Client action hooks serve mods such as auto-tool, hold-attack and mining overlays without changing the server's gameplay events.

Where an action starts

• Game::remote_mouse updates key state and queues presses. Keyboard bindings and controller actions should reach the same queue and held state. Raw input events can consume a physical input before it becomes a mapping. Action hooks run later, after the game has decided that a mapping may act.
• Game::remote_handle_input sends any changed held slot, stops a dig when gameplay is unavailable and delegates to InteractionInput::tick. This is the boundary between physical inputs and gameplay. The input crate owns the sequence and should keep no dependency on mods.
• InteractionInput::tick snapshots the crosshair once, drains attack, use and pick presses in order, then tries the held use and attack continuations. While an item is being used, it drains the press queues and releases the item when the use key goes up. Preserve this order and the same target for every attempt in a tick.

Input and prediction contracts

Extend interaction_key_mapping_triggered at its existing call sites. The event should carry whether the attempt is from a queued press or a held mapping, alongside the existing key, hand, cancellation and swing controls. A press attempt and a held attempt can occur in the same tick. The reason travels from InteractionInput through the game's InteractionWorld adapter. Deriving it from the current key state would confuse a queued press with a held continuation. Listeners use the existing ClientHost crosshair query while the tick's target is pinned.

client_mining_predict runs at the distinct prediction boundary inside remote_mining, after target, restriction and delay checks. It describes the block position, face, whether the accepted attempt starts or advances a dig, and the proposed progress. Its typed snapshot and client host are read-only. It runs after the interaction mapping event, so tool selection can settle before progress is computed. The server still independently validates the held item, position, reach and break progression.

A mining veto skips prediction, crack updates and the new action packet. For a continuation it leaves the existing dig intact so a later allowed attempt can resume it. A veto of a new target leaves the previous target untouched until the normal target-change or release path stops it. Ordinary release, focus loss, opening a screen and server correction must still clean up a running dig. These cleanup paths do not take a cancellable hook. Preserve the current retained-target behavior when a survival dig resumes after a miss.

Feature boundary

Auto-tool can distinguish a fresh attack from a mining continuation, inspect the current target and react before progress is calculated. Held use is distinguishable from a queued click. A mod can refuse predicted mining for selected blocks and still let the existing stop path clear the crack and send the abort. Holding attack on an entity keeps vanilla's attack cadence. Any API for requesting new actions, retrying attacks against entities, teleport correction or changing the server's validation belongs to a separate contract.

Verification

• Extend the input crate's behavioral tests to distinguish press from repeat and prove unchanged target lifetime, click ordering and release while using an item.
• At the client packet boundary check allowed and vetoed attack, main/off-hand use, active dig continuation and creative instant break. Compare emitted packets, sequence allocation, prediction, swing and crack state. Check a tool switch before a start and between continuation ticks.
• Exercise release, screen opening, focus loss, target loss and a server correction while an action listener refuses progress. Verify at most one abort for a running dig and no surviving crack after cleanup.
• Run the same fixture through the single-player window's integrated server connection and a dedicated connection. The mod hook should fire only on the window side.
• Compare the no-subscriber path against the pinned vanilla input/mining harness and avoid constructing snapshots or scanning subscribers on unsubscribed held ticks.

Create and Mekanism capabilities

Clean-room capability audit of main 5c2583c030 (2026-11-08); no foreign mod or NeoForge source consulted. Status applies to the stated engine operation, not a completed port. Tests below were inspected, not run here. Public wiki requirements are unversioned unless noted; exact release applicability remains unknown. Create's official CurseForge description (listing 6.0.10 for Minecraft 1.21.1) establishes animated automation, but no detailed interaction contract. The Create manual and Fandom Deployer page were inaccessible; detailed moving-structure requirements come from #794, and fake-player interactions are the audit scope requested by #806, not a claimed Create contract.

Source abbreviations: items, fluids (v9 upgrade note), energy (V10 upgrade note), chemicals, sides are official Mekanism user wiki pages. They motivate operations, not engine implementation details.

Repository references below are verified paths and lines. Prefix API = crates/horizon-mod-vocab/src/; Game = crates/horizon-client/src/game/.

Verified gap

Route limits

Works rows establish exactly the listed operation. Game tests use an in-process host (some set dedicated options), not a running network acceptance scene. LAN, integrated-server scheduling, actual dedicated networking and wasm execution were not verified for these rows. Item/entity lookup implementations were traced through provider dispatch; no claim is made that every provider journals correctly. API wire_resources.rs:18–30 explicitly refuses erased capabilities across link groups; this audit does not establish typed provider interoperability across all native/wasm groups. Chemical identity policy remains the provider's responsibility.

No hook count or complete-port claim follows from these results. Board searches used gh issue list -R arismoko/horizon --state all --search with energy, fake player, and moving structures; the verified carrier gap maps to #794. No issues were filed and no additional gap is inferred from untested routes.

Death sources at the loot hook

LootDrops::damage_source carries the death's damage type and causing/direct entity IDs. Non-death drops have no source. Environmental deaths retain their type, with 0 for absent or unknown IDs. player is remembered kill credit, not necessarily the attacker.

tool is the breaking or using tool (LootContextParams.TOOL), and is always None for entity deaths. To read the attacker's main hand, resolve damage_source.causing with host.entity(id), then host.living(entity), and call living.hand_item(host, Hand::Main). Handle resolution can fail for an absent attacker. This is a live read, including all stack components: changes during living_death and by earlier loot_drops listeners are visible to later readers. No hand snapshot is carried in the context. Native and wasm use the same Host operations.

Projectile direct IDs are currently 0; melee direct IDs equal the causing ID. The shooter's live hand is not the projectile's recorded firing weapon. Reading that recorded weapon through the damage source is separate work.

Design: a mod's biomes inside the Overworld and Nether

Provisional answer to scope 2 of #2554: how a mod's biomes can generate among vanilla's in the Overworld and the Nether. This is a proposal, not an implemented API. Scope 1, a mod's own dimension with its own climate points (BiomeSourceKind::Points), is separate and does not need this note.

Decision from the issue

Ari's answer on #2554 sets two starting points, and this note keeps both:

• Regions with weights. Each mod lays out its biomes in its own region. A hidden extra parameter decides which region owns an area, and vanilla's layout is one region among them. Ordering between mods is settled by the regions, not by competing for the same climate points.
• The mix is fixed when the world is created and saved with the world. The promise is: terrain in an existing world changes only by a recorded, per-world choice.

The same answer says NeoForge has no API for this: its biome modifiers change biomes that already generate and cannot add a biome to a dimension's layout, and the region mechanism is a third-party library. So there is no NeoForge contract to mirror. That statement comes from the issue; this note did not verify it, and it did not read the third-party library's source. Behaviour of that library is therefore not claimed anywhere below.

Horizon today

Not verified for this note: how vanilla's MultiNoiseBiomeSource presets are built from parameter lists, whether terrain depends on a chunk's biomes or only on the climate router, and how the existing preset lists are cached.

Proposal

Region. A region is (owner mod, region id, integer weight, points), where points are the BiomePoints of scope 1. Vanilla's own list is the region minecraft:vanilla with a fixed default weight. The declaration is a load-time registrar call, Registrar::declare_biome_region(path, weight, points), namespaced to the declaring mod and refused for a malformed or duplicate id, a weight of 0, or invalid points, as declare_attribute is.

Order. The region list is sorted by owner mod id, then region id, the rule the attribute catalog uses (#2191). The same mods give the same order on every side, so it can be saved and compared.

Choosing a region. A low-frequency noise of the world seed, sampled per biome cell, picks a region by cumulative weight. The nearest-point search then runs inside that region's own index only. A region never competes with another region's points, which is what makes ordering between mods unnecessary. The noise's exact form, frequency and its random-stream position are open (see questions) and must not disturb any vanilla stream: a world with no regions declared must generate exactly as today.

Fixed at creation. When a world is created the ordered region list (owner mod, region id, weight and full climate points, including biome ids) is written into the world's data, not hashes. A point's numeric payload is 52 bytes plus its biome id and region metadata; there is no per-region total because this proposal sets no point bound. The saved layout wins on load:

• the same mods installed: use the saved points even if a mod later changes its declaration;
• a mod added: ignored for that world unless the player opts in;
• a saved region's mod absent: tell the player which mod and region are missing and require an explicit per-world choice: do not open, or open with a recorded substitution. With substitution, vanilla's layout takes that region's share from then on. Save that decision once with the world, rather than silently substituting on each load. A dedicated server requires the decision in a setting and refuses to start otherwise, explaining the missing mod and region and the required choice.

Opt-in for an existing world. A recorded per-world choice, off by default, adopts the installed layout, including new regions or changed points. Without it the full saved points remain authoritative. Already generated chunks are never touched, including after a missing-mod substitution. The border between old and new chunks can show a biome seam. Whether terrain shape can also seam depends on whether terrain reads the biome (open, see questions).

API surface. One registrar method, one BiomeRegion record with Wire, and a read of the saved list (level.biome_regions(host)) for mods that want to know what the world was created with. No new hook.

Acceptance matrix (proposed, not reported passing)

Open questions

• What noise picks the region, and how is its seed offset kept from moving any vanilla random stream? Recommendation: a dedicated noise instance seeded from the world seed and a fixed salt, with the same sampling grid as the biome source, verified against the vanilla presets as an oracle.
• Does terrain shape read the biome, or only the climate router? Recommendation: check before the opt-in border is promised to be seam-free.
• Should weights be integers with a fixed default for vanilla, or relative to it? Recommendation: integers, vanilla at a fixed default, written down in the API docs.
• Nether, Overworld and the End: should the End be included? Recommendation: Overworld and Nether first, as the issue asks.
• Where is the saved list stored (level data or a separate file), and how does it round-trip the full saved points and recorded per-world decisions? Recommendation: decide with the world-save owners before any code.

Implementation boundaries in Horizon

The generator resolves the preset's biome source from the dimension's generator settings in generator.rs. BiomeSourceCatalog decodes a named multi-noise preset separately from an inline list. Keep both routes intact: the region selector belongs around the resolved Overworld or Nether preset, and only when a saved layout enables it. Inline points for custom dimensions keep their existing behavior.

Biome selection can change generated blocks. The generator passes biome samples into surface material rules and uses carver_biome to select a carver list at each origin. An opt-in can therefore produce material and carving seams in newly generated chunks. Do not promise a biome-color-only transition.

For the save owners to review: store a versioned, Horizon-namespaced world record separate from data/minecraft/world_gen_settings.dat. Key the full layout and recorded substitutions by dimension. Preserve the exact region order, weights and points on read. Reject malformed data and missing biome IDs before constructing a generator. An absent record in an existing world means vanilla generation until the player opts in. Persist an accepted change before generating chunks with the new layout. Pin the selector algorithm and its constants to the record version, since changing either would move regions in existing worlds.

For the generator owners to review: use a dedicated seed stream and sample in quart coordinates. Choose the weighted region before querying its climate index. Check the total weight for overflow, and retain a substituted region's weight and slot so unaffected regions keep their boundaries. Use distinct fixtures for the Overworld and Nether, including negative coordinates and chunk boundaries. Compare the unmodified preset against the Java oracle and compare the region-enabled path with no saved regions against that same baseline. The existing test_biome_source_parity.py covers fixed, checkerboard and End sources; it does not establish seeded multi-noise preset parity.

Stages

1. Settle the open questions above, with oracle fixtures for the presets.
2. The registrar, BiomeRegion and validation, with unit tests and a wire round trip (no generator change).
3. Region selection inside the biome source, behind "no region declared means identical output".
4. Saved list, load comparison and the per-world opt-in.
5. Docs, an example mod and the acceptance matrix.

Design: Attachment query joins

Provisional proposal for #2497, extending #1108's attachment query contract. Docs only; approval precedes implementation. The existing single-type API remains the same operation, extended through typed query specifications, without aliases or compatibility paths. Follow Part instance state for lifecycle identity and root commit rules.

Evidence and route owners

Vanilla 26.3 BlockEntity.saveCustomOnly(HolderLookup.Provider), inspected using tools/rea_vanilla.py from /workspace/horizon, delegates object-owned saving through ValueOutput. It establishes no attachment join contract. Vanilla has no counterpart to this mod query facility. The issue explicitly names no NeoForge counterpart: this proposal is judged on its merits. NeoForge 26.3 query behavior is unverified; no public documentation establishing such a query was inspected and no NeoForge source or patches were used. Public documentation would be required before adopting any claimed NeoForge contract.

Verified current owners (repository-relative paths):

These owners establish existing mechanics, not implementation of the contracts below. Before code, audit every #1606 residency producer, lifted-pass exit, world close, transfer, chunk unload and save gate against the same publication boundary; the exact #1606 owner integration remains a prerequisite.

Typed API and atomic writes

Choose tuples over a builder for access declarations, with options for scope/filter. Illustrative proposed syntax:

host.query((read(&MANA), read(&TEMPERATURE)), options)?;
host.query_mut((write(&MANA), read(&TEMPERATURE)), options)?;
host.query_mut((write(&MANA), write(&TEMPERATURE)), options)?;
row.apply(host, (Set(8), Keep))?;
row.apply(host, (Set(8), Remove))?;

Support arities 1 through 8 through generated tuple implementations. Reads require Send + Sync + 'static; writable slots additionally require Clone, as today. Read slots expose borrowed captured values and cannot accept replacement operations. No escaping mutable references. Reject duplicate keys, including two read slots, before capture with proposed DuplicateQueryKey; reject empty/oversized tuples as InvalidQueryArity. Declaration/type incompatibility remains an error, never a skipped holder. A row is a holder having every requested key, not a Cartesian product; joins never cross holder identities or dimensions.

apply opens one nested savepoint, validates every captured holder/residency and expected binding revision, pre-encodes all replacements, then invokes ordinary journaled writes for each writable slot. Merge only after every operation succeeds; otherwise abort the entire row. Recommend proposed StaleBinding when a queried binding has changed since capture, including remove/reinsert. This adds optimistic conflict checking for joined writes; existing single-key semantics need not change. Snapshot values never change after apply. A read slot's revision is also checked because the decision may depend on it. Same-holder/key recursive edits refuse; no borrow or index lock crosses a codec or callback.

Two writes to one holder reuse its first journaled map image. Different dimensions must journal under scoped dimension identity, never the currently selected relative Holder alone. Nested commit merges into the caller's action; root abort restores both types, membership, dirty flags and queued sync. There is no transaction on batch drop and no automatic transaction around a whole loop: use host.transaction for all rows. Root commit alone publishes journal emissions and retirement during lifted passes; save refuses while an action savepoint is open. Rollback must not invoke mod code.

Scope and residency

Options select Current, Dimensions([DimensionRef, ...]), or AllLoaded. Current is the default. Explicit references validate world and loaded status, deduplicate, and refuse unloaded dimensions without loading them. AllLoaded captures the loaded-dimension registry at acquisition, including parked dimensions, never persisted unloaded worlds. A newly loaded dimension appears only in a fresh batch.

Capture all selected per-dimension versions on the owning server thread in one non-reentrant capture phase, without callbacks, ticking or dimension swaps between captures. This is one logical snapshot, not sequential observations across ticks. Each row carries its captured owning dimension for validation/routing; entity identity still uses the existing lifecycle epoch/id and contains no dimension. Reuse existing holder lifecycles and residency tokens; add no second generation.

Parked residents remain visible. Lifted residents remain visible exactly once through #1606's authoritative owner table and stable attachment binding, despite temporary absence from a raw list. Never enumerate raw lists to reconstruct a query. Queued removal remains a residency view until the committed removal boundary. Transfer publishes departure/arrival atomically at root commit; a fresh capture cannot see both copies. Old captured values remain readable; writes after residency changes refuse rather than retargeting a successor. If a lifted owner cannot safely accept a write, refuse explicitly before mutation; never treat temporary list absence as permission to recreate it.

Cross-dimension apply resolves the captured dimension through the host's world service under one transaction; it must not silently change the host's selected dimension or run gameplay callbacks under another dimension. Client reads cover only loaded authorized replicas; writes require ServerHost. World close invalidates live authority, without changing already captured immutable values.

Holder filters

Use API-owned AttachmentHolderKind::{Entity, Player, BlockEntity, Chunk, Level} plus optional API registry handles for entity type or block-entity type. Players are a distinct holder variant; Entity does not implicitly include Player. Validate filter/type compatibility and registry handles before capture. Unknown or foreign registry handles refuse, not an empty accidental match.

Store immutable kind and resolved API type id with residency metadata. Check the candidate row's metadata before probing the other types or decoding values. This is O(1) per candidate, not zero total work and not a separate kind index. No engine enums cross the API. Replacement refreshes metadata through the existing lifecycle owner; type-preserving mutations retain it. Plain blocks and item stacks remain outside supported attachment holder kinds.

Cost, transport and untrusted input

For k keys in D selected dimensions, let n_d be the smallest bucket size in dimension d and R the matched rows. Capture costs expected O(Dk); matching costs expected O(sum(n_dk)), plus O(R*k) value access and actual codec work. With bounded k this is O(sum n_d), not O(all holders). Absent keys make that dimension empty immediately. Explicit dimension validation costs O(D); AllLoaded necessarily enumerates D loaded dimensions only when called.

The current dense bucket snapshots lack immutable per-key membership probes. Add a hash map from existing scoped holder/residency identity to row slot in each versioned bucket; capture its version together with dense rows. Do not build it by scanning the larger bucket at query acquisition. Probe those captured maps, never live mutable maps, to preserve snapshot joins. Retained versions require O(bucket size) metadata/map copy on first subsequent mutation; ordinary hash operations are expected, not worst-case, O(1). Memory is O(total indexed memberships) plus retained versions and O(Dk) batch descriptors. Decode/encode and transport add costs proportional to visited payload bytes. Native warm traversal allocates no per-row metadata; first decode may allocate. Wasm whole-batch serialization materializes matched rows and costs O(Rk + bytes); do not claim O(1) acquisition for wasm.

No query or attachment/lifecycle mutation means zero extra index work per tick: at most an O(1) enabled-path branch, zero allocations, codecs, holder scans or all-mod scans. Unbound holders create no query memberships. Lifecycle work touches only that holder's attachment keys. Subscription/type keys resolve at registration. Benchmark against #1811's 10,000-holder baseline, reporting capture, traversal, codec, transport, retained-version copy time and allocations separately; no invented timings.

Native and wasm share API-owned Wire query specs, scopes, filters, row errors and scoped apply payloads through the existing generator. One whole-batch capture import; one whole-batch apply import for submitted updates, never per-row imports. Validate the complete apply payload before executing row savepoints; an explicit enclosing transaction supplies whole-batch atomicity. Every new public crossing type must carry an explicit #[derive(Wire)] (fully qualified as #[derive(horizon_mod_api_macros::Wire)] where needed). The generator builds only the host call tables; serialization belongs to the derive, never copied or extended manual token/batch Wire implementations. The derive entry point is crates/horizon-mod-api-macros/src/lib.rs:6; existing derived public types include crates/horizon-mod-vocab/src/state_predicate.rs:6. Require the shared Wire capability for every boundary type and refuse registration with proposed UnsupportedQueryWireCapability, naming type and capability. No hand-written codec or guest pointer crosses the ABI.

Treat keys, scopes, tokens, lengths and replacements as untrusted. Proposed limits: 8 keys, 256 explicitly named dimensions, the existing shared NBT limits (64 MiB encoded bytes and depth 512), and existing shared Wire message budgets; refuse oversize before mutation, never truncate or constrain vanilla storage capacity. AllLoaded over transport budget returns a capacity error, never partial silent results. Query reads preserve malformed saved bytes and report row errors without defaults. Native unwind or wasm trap aborts active savepoints and pending publications under runtime callback policy; process-aborting panics are unrecoverable. Disable/report the failing callback according to runtime policy. Tuple and explicit-dimension limits require approval before implementation; payload limits reuse the shared boundary budgets. The current batch conversion calls Limits::default() for both encoding and decoding (crates/horizon-mod-vocab/src/entity/attachment_query.rs:93 and :108); its defaults are defined at crates/horizon-core/src/nbt.rs:202 and :204. Wire nesting has its own representation-aware depth budget, 1040 (crates/horizon-mod-vocab/src/wire/mod.rs:73), not an NBT depth override.

Acceptance matrix

Expected future tests, not results from this documentation change:

Proposed stages

File: none. First approve tuple access, atomic row apply, scope/filter and limits. Then audit #1606 lifted and parked ownership, retirement, cross-dimension journal keys and save refusal. Add snapshot-compatible probe maps and residency metadata; require explicit #[derive(Wire)] on every new public crossing type, with no copied or extended manual Wire implementations; extend generated native/wasm host call tables for capture/apply together. Finally implement the matrix and #1811 comparative benchmark before advertising support.

Open questions

• Resource budgets: reuse existing shared NBT and Wire budgets; approve only the tuple and explicit-dimension limits above; maintainer approval is required before code.
• #1606 integration: recommend stable bindings through lifted passes and root-only publication; name and verify every concrete owner and save-gate route in the implementation PR. The current route audit does not establish those end-to-end guarantees.

Design: baked models and ModelData

Provisional answer to #861: the engine owns immutable modified baked results for each resource generation; mods own bounded edit descriptions, never mutable renderer models. Evaluate ModelData on the client world-owning thread before freezing geometry selection. Workers read concrete results from section meshing's #1508 plan. This extends that plan's input boundary; its scheduling, halo, publication, geometry limits and rendering rules remain authoritative. No Rust API is implemented; every stage below has file none pending design approval.

Evidence and limits

Vanilla 26.3 was inspected only through tools/rea_vanilla.py from /workspace/horizon: method net.minecraft.client.renderer.chunk.SectionCompiler compile, its callers query, and method net.minecraft.client.renderer.item.ItemModelResolver updateForTopItem. SectionCompiler reads a render region, selects block models by state, passes a position seed to tessellation, treats fluids and block entities separately, and sorts translucent output. Its verified caller is CompileTask.doTask. Item resolution clears output and appends layers for nonempty stacks with display context, level, owner and seed. These observations do not establish a vanilla ModelData API or a vanilla mod callback. The owner-thread preparation boundary below is Horizon policy.

The public NeoForge model guide was reachable on 2026-11-09 but labelled 26.1. It describes client baking-result edits for block and item models and block-entity ModelData consumed during model selection. It is contextual evidence only. The requested 26.3 ModifyBakingResult Javadoc was inaccessible. Exact 26.3 event threading, mutability, reload ordering, ModelData invalidation and item applicability are unverified. In particular, no claimed NeoForge radius, size, thread-safety or item-data limit is verified. Require public 26.3 documentation of those contracts before adopting counterpart semantics or implementing the hook. No NeoForge source/patches or other project's source were consulted.

Ownership and registration

Propose one client modify_baking_result moment, with ClientHost, after baking and before publishing caches on initial load and every resource reload. Client-lib prepares the candidate; game dispatches subscribers in dependency order; validation and publication apply in the same transaction, rechecking resource/mod generations. Refuse stale preconditions without recomputing inside apply. Resource preparation may be asynchronous, but dispatch and commit return to the client owner thread. Keep standalone registration unchanged.

API-owned proposed representations: BakedModelKeyWire (resource generation, resolved slot and block/item kind), BakedModelEditWire, BakedModelRecipeWire, ModelDataSchemaWire, ModelDataValueWire, ModelEvaluationInputWire, and ModelEvaluationResultWire. Reuse #1508's prepared model/material/quad Wire values rather than introduce another geometry format. Recipes select bounded prepared variants or validated replacement geometry, with explicit particle, lighting, culling and item transform metadata. Wire is a mod boundary, not network traffic. No renderer structs, pointers, closures or GPU objects cross it.

Resolve model targets and schema property ids once at registration. Properties have declared scalar/enum or bounded-vector types and defaults; no arbitrary serialized objects. Refuse unsupported capabilities at registration with owner and capability named: worker callbacks, live-world evaluation during meshing, unbounded neighbourhoods, arbitrary native model delegates, raw pipelines and undeclared data types. Apply the same refusal on native and wasm. Reject conflicting exclusive replacements with both owners named; composable edits run in dependency order. Unknown feature-owned target ids refuse registration; unrelated existing unknown-id no-ops retain their behavior.

Build generation B from B's original baked inputs, never from modified A. Publish block and item tables atomically. Shared immutable engine references lease A until old jobs and item draw snapshots release it; A cannot publish into B. Mods receive scoped keys, not ownership of engine allocations. Teardown follows #1508's job lease/drain ordering before unloading native code or wasm stores.

ModelData evaluation boundary and routes

Registered providers receive a read-only captured evaluation input plus ClientHost at owner-thread preparation. Their result is a typed property value set, not a callback stored in the model. World writes are forbidden during this preparation moment. Block inputs use #1508's radius-one snapshot and explicit Missing cells; model selection freezes deterministic seeds, data revision, resource generation and prepared geometry keys into state recipes/sparse overrides. The mesher receives those through the existing proposed SectionMeshPlanWire. There is no worker hot-path dispatch, native trait-object invocation or wasm call for this feature. Existing worker tint capabilities remain as documented in section meshing; they do not authorize ModelData callbacks.

Cache by model key, typed input revisions and seed. Block/state, neighbour, block-entity data, light/biome dependencies and provider invalidations dirty the applicable plans; never poll arbitrary mod state per frame. Reload invalidates all old data keys. Providers explicitly request invalidation on changed source data. Missing data uses declared defaults. Stale data refuses publication using #1508's tokens. Items evaluate during owner-thread item preparation using captured stack components, display context, optional level/owner and seed; freeze output before drawing. A block item does not inherit world-position ModelData implicitly.

Verified current integration owners at base 0ef42f9e54 (paths relative to repo; these are seams, not already implemented callbacks):

Initial mesh, remesh, halo changes, unload, reload, cancellation and stale upload all use section meshing's route and token table, not a second invalidation system. GUI, held, dropped, frame and equipment item callers must converge before item submission; exact preparation caller coverage remains to be audited before code. Special block-entity drawing stays on R2; it may consume a prepared model but does not acquire a terrain callback. Dedicated servers neither bake nor evaluate.

Untrusted input and cost

Proposed ceilings: 64 properties per schema, 256 elements per vector, 16 KiB encoded and decoded ModelData per evaluation, 256 variants per recipe. Checked length arithmetic precedes allocation; count captured values against #1508's 32 MiB section and 128 MiB in-flight budgets. Geometry obeys that page's quad, coordinate, UV, colour and material bounds. Reject NaN/infinity, invalid tags, stale keys, duplicate properties and values outside declared scalar ranges before selection. No partial edits: refusal preserves the original candidate model.

Catch unwind-capable native panics at the adapter; wasm traps or fuel exhaustion have identical refusal. Disable the faulty registration for this generation, diagnose once and invalidate its cached selections; use original baked geometry and default data. Native abort cannot be caught and native callbacks cannot be safely forcibly preempted. Wasm gets finite fuel and the same output limits. Generated adapters share semantics and dependency ordering across both targets.

With no subscribers, choose the existing path once at resource/dispatch setup: zero ModelData allocations, provider calls, per-block checks or all-mod scans. With subscribers, dispatch only indexed providers during preparation; workers read arrays. Reload edits cost only at bake time. Performance numbers remain unmeasured.

Acceptance matrix

Future implementation tests, not results of this docs change:

Proposed stages

1. Public-contract audit and approval (file none): obtain exact 26.3 documentation, settle counterpart semantics and audit every item preparation caller.
2. Shared boundary and generation ownership (file none): approve API-owned Wire types, registration refusals and native/wasm codecs together.
3. Baking and owner-thread evaluation (file none): implement one transactional moment, reload leases and provider invalidation with focused fixtures.
4. Frozen-plan and item integration (file none): wire #1508 and item preparation, then run the matrix and measure empty-path cost before enabling registration.

Open questions

• Exact NeoForge 26.3 contract? Recommend requiring public documentation before naming the final hook contract; do not infer restrictions from 26.1 or source.
• Arbitrary dynamic delegates versus finite variants? Recommend finite recipes and owner-prepared geometry; refuse unsupported registrations explicitly.
• Item ModelData parity? Recommend a distinct typed item evaluation input under the same preparation contract, conditional on documented counterpart coverage.
• Final R2/#1508 geometry identities? Recommend reuse of their approved keys and generation leases rather than a parallel model store.
• Data budgets and provider scheduling cost? Recommend the explicit ceilings above initially, with dense-scene measurements before raising them.
• Complete item caller convergence? Recommend an implementation gate: audit GUI, hands, dropped items, frames and equipment and test context-dependent selection on each before claiming full route coverage.

Design: chunk attachment disk hooks

Provisional proposal for #857; no implementation or adopted guarantee. This answers the worker Host versus server-thread snapshot question: retain the existing server-thread capture seams, but execute mod load, save and persistence codec callbacks on a chunk worker with a restricted Host. Do not pass Game to a worker or silently relocate the requested callbacks to the server thread.

Evidence and limits

Vanilla 26.3 was inspected from /workspace/horizon with python3 tools/rea_vanilla.py method net.minecraft.world.level.chunk.storage.SerializableChunkData copyOf and the same command for parse. copyOf rejects unserializable chunks, copies sections, light arrays and heightmaps, and collects block-entity tags and proto entities. parse constructs serialized chunk data and returns null when Status is absent. These establish separate capture and decoding boundaries, not a vanilla mod attachment hook or proof of worker scheduling. Vanilla callers, unload ordering and disk failure recovery remain unverified; audit them with the same oracle before code.

The issue names NeoForge 26.3 ChunkDataEvent.Load/Save. The public attachment documentation describes optional persistence serializers but is labelled 26.1. The 26.3 event Javadoc was inaccessible. Therefore NeoForge 26.3 thread, event ordering, cancellation, exception, size and data-loss limits are unverified. Require public 26.3 event and attachment lifecycle documentation before adopting a parity contract. No NeoForge source, patches or other project's source were consulted. The rules below are Horizon recommendations pending that evidence.

Verified current owners and route audit

Paths and lines refer to this checkout; these are inspected owners, not completed callback routes.

Forced saves, periodic saves, dimension transitions and shutdown must be traced to these owners during implementation; this audit does not claim their entire caller graphs are verified. Background job failure currently requires an explicit result/acknowledgement audit rather than assuming Done::Saved means durable success. Remote clients must never run authoritative disk hooks. Missing chunks and newly generated chunks with no decoded disk record do not fire load; proto-to-full promotion does not fire a second load.

Proposed contract

Capture only committed attachment state on the server thread under the existing world visibility/save lease. An open action savepoint refuses saves through the #2211 save gate, including forced, unload and shutdown saves; do not serialize tentative state or take a second private transaction snapshot. Defer unload when the gate refuses. Reuse the existing lifecycle AttachmentHolder/ChunkRef and residency owner, scoped to world and dimension; do not introduce another chunk generation. A snapshot capability expires at callback return and never resolves back to the live world.

A job owns its isolated attachment store. Save dispatch runs after capture and before encoding. Listener writes affect that store only. Capture 7, listener writes 8, live world changes to 9: disk gets 8, live remains 9. Use immutable shared encoded values or deep owned copies; never share mutable typed values or hold a world lock across mod code. Dependency-ordered listeners run sequentially for a job. Serialize jobs for a chunk in capture order, reject stale completions after residency/world retirement, and never allow an older write to replace a newer successful save.

Load dispatch runs after bounded disk decoding and before publication. Its successful edits become the loaded attachment store; failure publishes no partially initialized holder. Full and proto disk loads follow the same rule. Unload notification follows successful save completion when persistence is required; unload itself does not delete saved attachments. Persistence does not imply network synchronization.

The worker Host implements shared Host facilities only where safe: immutable registry/settings snapshots, handle construction and a local transaction over this job's attachment store. It exposes no world mutation, scheduling into live state, live chunk lookup, Parts, packets or Game access. Ordinary ChunkRef live operations refuse in this context; snapshot attachment methods validate the job capability and existing holder identity. No mutable borrow escapes a callback. Recursive edits to the same key refuse, and callback failure aborts the whole job's tentative edits.

Native and wasm use the same catalog hooks, dependency order and generated adapter. Define API-owned Wire representations ChunkDiskContextWire (world scope, dimension, chunk position, full/proto kind and load/save phase), AttachmentDiskEntryWire (registered key, schema, bounded encoded value), and ChunkDiskResultWire (success or structured refusal). These are proposed names and fields, not existing types. Each declared typed value needs both its persistence codec and the shared Wire capability required by dispatch. Refuse registration before first callback if worker-safe execution, codec or Wire support is absent, naming the type and missing capability. No Rust Any, pointers or runtime handle serialization across wasm. A native module has the same validation obligations and must explicitly support concurrent worker invocation; unsupported modules refuse registration rather than gaining server-thread fallback.

Failure, trust and cost

Propose 64 KiB per encoded value, depth 64 and 1 MiB total mod attachment data per chunk, including unknown keys; validate lengths before allocation, keys/schema/scope before mutation, and finite numeric fields where the schema requires them. Refuse oversize data without truncation. These budgets apply only to attachment data, not vanilla chunk contents. Preserve bounded unknown keys opaquely; do not turn unknown unrelated ids into new errors. Corrupt or over-budget input must remain recoverable on disk rather than being overwritten by defaults.

On codec error, native unwind or wasm trap, abort the snapshot transaction, report the mod/key/phase and keep the prior disk record. Disable the failing callback according to runtime policy; never silently retry without it and claim a successful save. A process-aborting native panic is unrecoverable. Rollback uses engine-owned captured bytes and invokes no mod code. Disk failure retains a retryable snapshot and dirty/recovery ownership, reports failure to wait/flush/close, and prevents silent successful unload. Partial publication and clearing dirty state before acknowledgement are forbidden. Exact atomic-write and crash durability guarantees require an audit of the disk writer before adoption.

Resolve subscriptions and capabilities at registration. With no listener, one cached subscription check selects the existing persistence route: zero new per-chunk allocations, codec calls, worker messages or mod scans. Existing attachment persistence costs remain. Subscriber work is bounded by the declared entries and budgets; use bounded queues and backpressure rather than unbounded retained snapshots.

Acceptance matrix

Proposed tests; none are claimed executed for this design.

Proposed implementation stages

File: none. These are future work packages, not Rust changes in this note.

1. Obtain public NeoForge 26.3 evidence and approve worker capability, budgets and failure policy.
2. Complete vanilla caller and Horizon route audits, including forced/periodic/close and disk acknowledgements; integrate the existing save gate and lifecycle owner.
3. Specify and generate Wire declarations, registration refusals and native/wasm worker dispatch; centralize the callback boundary below all preparation routes.
4. Implement isolated load/save stores, bounded queues, rollback and ordered persistence acknowledgement without early dirty clearing.
5. Exercise the matrix through real disk routes on both targets and measure the unsubscribed path.

Open questions

• Thread contract: recommend worker dispatch and server capture as above; require public 26.3 evidence before adoption, rather than infer scheduling from event names.
• Lifecycle authority: recommend the existing world-visibility owner approve snapshot capability validation and unload recovery; no second generation counter.
• Failure handling: recommend fail closed with retained recovery data and explicit close failure. Audit writer atomicity and decide crash recovery before advertising loss prevention.
• Worker module safety: recommend explicit registration capability for both targets; settle runtime instance concurrency and wasm fuel limits before implementation.
• Budgets: recommend 64 KiB/value, depth 64, 1 MiB/chunk plus bounded queues; confirm against the shared Wire budgets and unknown-key preservation policy.
• Remaining routes: recommend treating the unverified forced/periodic/transition caller graph and vanilla unload sequence as mandatory implementation evidence, not inferred coverage.

Design: client extensions

Provisional answer for #895. This proposes ownership and registration, not an implemented API or a completed NeoForge parity audit. Implementation requires review first.

Reference and category discrepancy

The named question is the complete extension surface for items, blocks, fluids and entities, and its mapping to a typed client-extension registrar. The issue's actual ask and batch 20 triage instead name effects as the fourth registration category. Do not silently equate an entity renderer with a status-effect renderer. The proposed four counterpart builders are item, block, fluid and effect; entity capabilities resolve to existing entity rendering owners, outside that four-category registrar until public documentation establishes otherwise.

The public 26.3 registration Javadoc returned HTTP 503 during this investigation. Triage reports four registration categories and registration queries, but does not establish the complete method surface. NeoForge 26.3 method names, defaults, overloads, duplicate policy and limits therefore remain unverified. Require accessible public documentation and a method-by-method disposition before adopting the final counterpart contract. No NeoForge source, patches or other project's source are inputs. The following is a complete proposed capability disposition, not a claimed complete census of NeoForge methods. Unsupported methods must never become silent no-ops.

Vanilla has rendering consumers rather than Horizon's registrar. The vanilla 26.3 SectionCompiler.compile oracle query is recorded below; terrain compilation is the relevant block/fluid convergence boundary. Other vanilla consumer details remain unverified here; the linked merged designs retain their own evidence.

Surface and ownership mapping

Reuse Part instance state, baked models and ModelData, and section meshing. Their lifecycle, geometry, budgets and invalidation contracts remain authoritative; this registrar adds no second store, mesher, generation counter or draw bus.

Current route census

Verified file:line anchors at this worktree's base ff35cdee95 describe current owners, not proof that proposed dispatch already exists.

Every route either uses the listed owner or is explicitly unsupported. Initial load, resource reload, world switch, unload, mod teardown and failed reload must be acceptance cases. Dedicated servers do not dispatch client registration.

Typed registration contract

Propose one register_client_extensions setup moment with ClientHost and a scoped ClientExtensionRegistrar. Typed item/block/fluid/effect keys select small builders; queries inspect staged registrations without invoking providers. Resolve keys once after declarations and before rendering. Dependency order is shared by native and wasm. A second provider for the same key/capability refuses with both owners named; distinct capabilities can compose. Extensions to another mod's declaration require an explicit dependency, not accidental load order.

Proposed API-owned Wire types: ClientExtensionRegistrationWire, ClientExtensionCapabilityWire, ClientExtensionTargetWire, ClientExtensionResourceRefWire and ClientExtensionRefusalWire. These carry explicit tags, bounded lengths and typed keys; no Rust trait object, guest pointer, engine model or GPU object crosses the boundary. Callback references resolve through the generated runtime adapter. Refusals include UnknownExtensionTarget, DuplicateClientExtension, UnsupportedClientExtensionCapability, MissingClientExtensionWire and StaleClientExtensionResource. Unknown-target refusal applies only to explicit registrar requests, never existing vanilla no-ops.

Stage an immutable indexed table; validate all requests before atomic publication. Reload prepares a replacement and keeps the old valid table on failure. Resource keys and callbacks lease existing resource/mod lifecycle holders; no second epoch. Stop new dispatch, drain leases, then unload code. Object state follows existing holders: stack components for items, existing scoped entity/block-entity handles where available, and no invented plain-block or fluid instance holder.

Callbacks use their existing owner Host and decide/fire/apply transaction. Recheck captured versions at apply and refuse stale decisions. In lifted passes, defer retirement and journal emission until root commit; nested abort exposes no partial registration or state. Saves refuse while an action savepoint is open, as specified by Part state. DrawContext is supplied only by the owning draw moment.

Untrusted input, bounds and cost

Validate native and wasm identically: enum tags, key ownership, resource existence, finite numeric values, length arithmetic and declared schemas before allocation or publication. Propose 4096 new registrations per mod and 64 KiB encoded/decoded registration records; these bound extension additions, never vanilla registry capacity. Geometry and state payloads retain their owners' bounds. Reject negative, NaN or infinite values where finite nonnegative values are required; capability specific ranges require public-contract review, not arbitrary clamps.

Catch native unwinds and wasm traps at the adapter, discard the whole tentative result, diagnose once and disable the faulty capability for the current lifecycle; use the unchanged built-in result. Native abort cannot be recovered. Wasm receives finite fuel; native callbacks cannot be forcibly preempted safely.

Resolve dense slots at setup and select the ordinary path when no capability is registered: O(1) dispatch selection, zero extension allocation/callbacks and no all-mod scans. Workers consume the existing frozen representations. Performance is proposed, not measured.

Acceptance matrix

Future implementation tests, not results of this note:

Proposed stages

1. Public 26.3 method census and category approval (file none): enumerate every interface method/default/overload and assign one owner or named refusal.
2. Consumer audit (file none): complete item, particle, terrain/camera fluid, effect inventory/HUD and non-mob entity routes with verified caller anchors.
3. Typed registrar and generated adapters (file none): approve Wire schemas, duplicate policy and lifecycle integration together for native and wasm.
4. Owner integration (file none): implement only approved capabilities through existing Parts/rendering; run the matrix and measure unused-path cost.

Open questions

• Fourth category? Recommend effects for the documented counterpart and explicit separate entity ownership; obtain maintainer agreement on the task wording.
• Full 26.3 method surface and semantics? Recommend public documentation as a hard implementation gate; current family matrix cannot establish full parity.
• Unsupported families and incomplete caller coverage? Recommend named refusal until each owning design and route audit is approved, never silent acceptance.
• Registration ceilings? Recommend the proposed additive limits, measured against representative mods without reducing built-in capacity.

Design: custom recipe-book settings

Design for #1023. Storage, registration, player settings handles and negotiated synchronization are implemented. This is a Horizon design; vanilla 26.3 is the reference for the four existing books. No other project's implementation is a reference.

Player settings operations

PlayerRef::recipe_book_settings(host, &key) reads an authoritative RecipeBookSettings { open, filtering } pair. Fresh registered books read false, false; unavailable players and unregistered keys return None. PlayerRef::set_recipe_book_settings(host, &key, settings) is a server-only write. It leaves every other book untouched, synchronizes changed flags and notifies the existing player_recipe_book_settings_change moment once. That notification now carries RecipeBookIdentity: one of the four vanilla identities or Custom(RecipeBookTypeKey), never a fabricated vanilla ordinal. The values explicitly derive Wire and share the generated native/wasm boundary.

A client mod reads PlayerRef::synced_recipe_book_settings and submits intent with PlayerRef::request_recipe_book_settings through a ClientHost. Engine menu panels use the same view through Game::custom_book_settings and Game::request_custom_book_settings. Until a negotiated snapshot arrives, or while a revision gap needs a replacement snapshot, reads return None and the panel must stay disabled. Requesting never changes saved flags. Disconnecting with pending intent restores the server's last accepted pair on the next join.

Registration and ownership

Add an API-owned RecipeBookTypeKey, a validated namespaced resource id, and register declarations in the existing mod registration phase. Registration returns a typed key; it does not extend BookType or its ordinals. Require an explicit namespace owned by the registering mod, lowercase resource-id syntax, a nonempty namespace and path, and at most 256 UTF-8 bytes. Reject minecraft:. Duplicate keys fail registration with the key and both declaring mod identities; invalid ids report the mod, supplied id and violated rule. Never silently select a winner. Freeze the registry when registration finishes, before loading player state or negotiating connections. Late registration returns an explicit frozen registry error. Resource reload does not reopen it.

Declarations are shared content on server and client. Native and wasm use the same declaration, validation, limits and generated boundary contract. A client must register a key to negotiate it; a server-only declaration can retain state but cannot make an unmodified client display a book. Reads belong on a player's recipe-book settings handle with &dyn Host; authoritative writes take &mut dyn ServerHost. A client UI requests a change through its client settings handle; it cannot directly mutate server state. Do not add player-id helpers to Host. Registration uses its existing registration receiver.

Book identities are separate from RecipeBookCategory in crates/horizon-mod-vocab/src/item/recipe_book.rs. Categories group recipes and provide icons; a book owns two flags. A screen associates categories with a registered book explicitly through Screen.recipe_book. Neither category registration nor recipe-type registration implicitly registers a book. Recipe unlocking and placement remain separate from displaying the declared recipe layouts.

Registration API

In Hooks::register, call r.recipe_book_type("demo:cooking_pot") on the existing Registrar. It returns Result<RecipeBookTypeKey, String>; failures include the declaring mod, supplied ID and rule and refuse installation even if ignored. Keep the returned key (mod_api::item::recipe_book::RecipeBookTypeKey) for screen bindings. as_str() returns its stable identity and is_registered() checks membership in this process's installed registry. No public unchecked constructor exists. Native and wasm share the same registrar method through the generated Wire boundary; the key explicitly derives Wire.

This registration does not create a category, settings handle, UI or network payload. Successful installation freezes the registry; resource reload does not reopen it. The settings and synchronization operations described here are implemented on the typed player handle.

Storage, persistence, copy and replace

Keep Settings.open and Settings.filtering as [bool; 4]. Add a custom map from validated key to a value { open: bool, filtering: bool } alongside them in crates/horizon-client/src/recipe_book.rs. Missing keys read as (false,false). There is no fifth vanilla index. Use one shared map implementation for local, host and guest players, persistence and payload application.

Persist the map inside recipeBook under horizon:book_settings, a compound whose keys are book ids and whose values contain byte booleans open and filtering. Write both flags, including zero, and sort keys for stable output. Missing extension means an empty map. Preserve well-formed entries even when the owning mod is absent; registration is required for live access and sync, not for retention. Parse the extension independently of vanilla recipe-list validation so an invalid recipe list does not erase retained custom flags.

Bound the extension to 1024 entries, 256 bytes per key and 512 KiB encoded data. Check lengths before allocating or iterating nested values. Accept only a compound of compounds with both flags byte 0 or 1; skip malformed individual entries with a diagnostic. Reject a duplicate key or an over-limit extension as a whole, leaving the custom map empty and vanilla settings intact. The NBT reader must enforce the byte/depth budget before materializing this subtree. Registration also caps custom types at 1024, reporting overflow at registration. Do not evict absent-mod entries to make room: a write exceeding the cap fails without changing state. This bounds retention as well as network input.

Copy is an independent value copy of all four vanilla pairs and every custom entry, including absent-mod entries. Mutating either player afterward cannot change the other. Replace assigns the complete source settings value, clearing destination-only entries; it is never map merge. Existing recipe and highlight sets retain their existing whole-Settings copy semantics. Import without the recipe_book section preserves the complete destination value. Import with the section replaces it, including clearing custom entries when the extension is missing. Host/guest swaps must move the complete value.

First sync and subsequent changes

The server owns persisted player state. Negotiate a custom-settings capability and the intersection of registered keys during connection setup. Send no extension payload without successful negotiation. Namespaced keys, not process local registration indices, identify entries on the wire. Vanilla settings and seen/add/remove packets retain their current fields, ordinals and meaning; a vanilla client receives exactly the existing four-book traffic.

After player load and ordinary initial recipe-book packets, send one bounded custom snapshot on the negotiated mod payload channel, before enabling custom book UI. Snapshot includes every negotiated key, explicitly (false,false) when absent from storage. Applying it replaces the client's custom view. Retained unregistered or unnegotiated keys never leave the server. Snapshot delivery is also required on imported-state replacement and every reconnect. Clear the old client view and pending requests at disconnect; never upload that cache as a replacement for server state.

Use reliable ordered delivery on the connection. A snapshot starts a fresh connection epoch at revision 0; each accepted server change increments the revision. Updates contain epoch, revision, key and both flags. Clients apply only the current epoch in revision order; a gap disables the custom UI until a fresh snapshot arrives. Client requests carry the current epoch and a monotonic request number; the server validates ownership of the connection's player, capability, negotiated key, booleans and bounds before applying once. Reject stale/duplicate requests without mutation; answer with authoritative state so the UI can settle. Later valid requests are processed in arrival order. Server writes use the same apply path, then send the resulting update. Notify gameplay once after an accepted change, never for rejection or an unchanged pair, through the existing settings-change moment extended to typed identity.

Cap payloads at 512 KiB and snapshots at 1024 distinct entries; updates contain exactly one entry. Reject malformed/oversized payloads before allocation or mutation, including duplicate snapshot keys. Rate-limit requests to 20 per second per player; excess requests are rejected and cannot alter flags. Client UI may show pending intent but only authoritative replies enter saved state. The design called for single-player to use the same server apply operation without serialization; this build instead preserves the existing integrated server's byte-pipe connection and identical negotiated, rate-limited authority semantics, because a typed local route needs per-connection ordered queues bound to integrated player ownership and reconnect lifetime.

Worked book and acceptance cases

A cooking mod registers demo:cooking_pot during registration and binds its cooking screen to that key. The screen reads (false,false) initially. Opening it requests (true,false); the server accepts, stores that pair and sends it back. Selecting the craftable-only filter requests (true,true). A category such as demo:soups can appear in that screen without owning either flag. These are proposed operations, not compilable API examples.

Use these independent expectations in implementation tests:

Current routes to update

References below are verified against this worktree at 84e57e6a79; paths are relative to crates/horizon-client/src/. Implementation must keep each route on the shared settings operations rather than duplicate custom-map handling.

The vanilla reference queries are rea_vanilla.py method net.minecraft.stats.RecipeBookSettings replaceFrom and rea_vanilla.py method net.minecraft.stats.ServerRecipeBook sendInitialRecipeBook. Custom registration, retention and negotiation are Horizon decisions, not claims about vanilla.

Recipe displays and category membership (#828)

The recipe_book_categories declaration now carries target_menu, book, search_group and displays beside the category id, recipe type and icon. A type supplies RecipeBookDisplayEntry values for its recipes during the existing recipe-table declaration callback. The callback can read the Host's recipe table and interpret its own JSON; the engine does not impose a JSON schema on mod recipes.

RecipeBookDisplay names the shaped, shapeless, furnace, stonecutter and smithing layouts. RecipeSlotDisplay describes slots using API-owned values: items, stacks, tags, fuel, potion/component transforms, dyeing, trimming, remainders and composites. All three display types explicitly derive Wire. Named resource references are validated against the owning resource generation at load. Display stacks are materialized when the panel's content changes.

The engine's ModBookIndex::build boundary validates declarations atomically against resource tables. Unknown resources, invalid layouts, duplicate recipe ownership and conflicting book membership return DisplayLoadError values. A book has one menu and one search group; no search group can aggregate two books. Search membership is derived from the book's categories, so two mod books remain isolated and vanilla books have no mod search members.

The live recipe-table declaration path validates the entire batch before publishing any categories. A refused batch retains its typed load error for that generation and publishes no partial book; reload or disconnect clears the cache. Multiple categories may share a recipe type. The engine's panel projection requires both the declared target menu and registered book key, and a category selected in another book cannot be reused as a tab here.

Hosting the panel in a mod screen

Construct Screen with the geometry your menu needs and use struct update syntax for fields you do not set. This keeps the literal compiling when optional fields are added; it does not make the default geometry suitable for your menu.

#![allow(unused)]
fn main() {
let screen = mod_api::Screen {
    width: 176.0,
    height: 166.0,
    slots: vec![Some([44.0, 35.0]), Some([116.0, 35.0])],
    inventory_x: 8.0,
    inventory_y: 84.0,
    ..mod_api::Screen::default()
};
}

Set Screen.recipe_book to Some(key.clone()) in the existing native_screen declaration. Leave it None for a screen without a recipe book. The key must belong to the categories' target_menu; a different menu cannot display that book. The green book button sits just outside the menu's right edge so it does not cover slots chosen by the mod. The open panel uses the normal narrow-window coverage and wide-window menu shift.

The panel is disabled until the connection has an authoritative settings snapshot for the registered key. Opening and filtering submit requests through the shared custom-settings route; neither click optimistically changes the saved flags. Tabs show this book's category icons, with a search tab aggregating only this book. Four category tabs fit on each tab page; separate arrows reach additional categories while search stays visible. Search matches displayed result names. The craftable filter matches the display's required input alternatives against player inventory and visible menu contents, not the custom recipe's opaque JSON logic.

Recipe buttons cycle through their declared result displays. Clicking a button opens a display preview using the shared recipe-book overlay painter, including stonecutter and smithing ingredient layouts. Larger ingredient grids scale to fit the preview instead of spilling into adjacent alternatives. These previews do not place recipes, create ghost slots, or send a custom id through vanilla placement packets; placement and ghosts are tracked separately in #2599.

A declaration's book is a registered RecipeBookTypeKey from #2415; it does not implicitly register a book or create settings. The index checks the key against the frozen registry. No vanilla book ordinal or packet meaning changes.

Transport and cost

The dedicated horizon:recipe_book_settings channel is used only after the server announces mod transport and the client offers its frozen registered keys. The server intersects those keys with its own registry before replying with the initial snapshot. Vanilla clients never send the offer and receive no custom settings. The bounded binary codec refuses oversized payloads, invalid flags, trailing bytes and duplicate snapshot keys before applying anything.

Negotiation, snapshots and requests do work only on connection or a settings change. There is no per-tick mod scan or new tick allocation. A connection's request replay guard and rate allowance survive rejected requests and repeat offers. Disconnect removes the connection authority and clears pending client intent; the saved server map remains independent of the client view.

The response budget covers every payload, including malformed input and snapshot requests. Once exhausted, a negotiated peer receives a one-byte busy control reply instead of another large snapshot. The client disables the custom view and coalesces a retry after one second; a busy response schedules the next retry, and a successful authoritative snapshot cancels it. This bounds response amplification without leaving a lost resnapshot or pending UI intent unresolved.

Toggle layout and large books

Screen.recipe_book_toggle optionally reserves a 20 × 18 GUI-pixel toggle at an [x, y] offset from the menu origin. Like vanilla's screen-specific button positions, this is space the screen author must keep clear of slots and labels. Both native and wasm declarations carry the same optional value over Wire.

Without an anchor, the client tries an external right, left, then above-menu gutter, rejecting positions covered by the overlay panel. Menus wider than 176 GUI pixels, windows narrower than 379 GUI pixels, or windows narrower than the menu width plus 202 GUI pixels use overlay mode instead of shifting slots. If the toggle does not fit in the viewport in the closed layout or in the open layout, the book is refused with a diagnostic identifying the mod block and menu. The diagnostic requests Screen.recipe_book_toggle when absent, or reports an anchored toggle outside the viewport when the declared anchor does not fit. The menu still opens unchanged; the engine never clamps a toggle onto mod slots or clips the menu to make room.

The client caches resolved result/search metadata for the screen binding. Stock changes re-evaluate craftability and filtering, but only the selected page's twenty recipes materialize ingredient previews. Search still considers the entire declared book, not just the visible page.

Menu-owned destination roles

During shared registration, r.menu_recipe_book(menu, &book, recipe_type, layout, screen) binds a content menu to a registered book, a recipe type and its existing typed Screen value. The menu namespace must belong to the registering mod. Duplicate bindings and unknown books refuse installation even when the registration error is ignored. The declaration is frozen with the other registrations and explicitly derives Wire, for the same native and wasm transport.

RecipeBookLayout declares one of four destination maps:

• Crafting { width, height, slots, result } supports shaped and shapeless displays. Slots are row-major container indices.
• Furnace { input, fuel, result } supports cooking displays.
• Stonecutter { input, result } supports stonecutting displays.
• Smithing { template, base, addition, result } supports smithing displays.

These are container slots, not the appended player inventory. Overlapping roles, invalid dimensions and indices outside the 256-slot menu bound refuse registration. Book loading checks against the actual content menu size. If the menu has an instantaneous MenuCrafting backend, its grid and computed result must exactly agree with the declaration. Without that backend, a crafting map describes real persistent input storage instead: for example, six cooking-pot inputs in a 3 by 2 grid. Placement never fills its cooked output or fuel, and preserves those slots. An incompatible display or one that does not fit refuses the declaration generation rather than truncating ingredients. All mapped slots need finite coordinates in Screen.slots. Registration rejects missing or nonfinite coordinates, nonpositive/nonfinite panel sizes and a screen bound to another book. Startup also rejects geometry for slots beyond the actual content menu. The screen is frozen in this same declaration, not a second registry. For these book-enabled menus, both the client layout and server hidden-slot policy use that registered screen; native_screen is not consulted. Other mod menus still obtain their screens dynamically.

The shared mapper uses vanilla PlaceRecipeHelper: a 1 by 1 shaped recipe in a 3 by 3 grid is centered; a 2 by 2 recipe starts at the upper left and retains its holes. Shapeless ingredients occupy consecutive cells. Furnace fuel is included in a preview only when its slot is empty. Station icons never map to menu ingredients. Result display stacks retain their components and counts.

Authoritative placement information

A menu-bound recipe type supplies RecipeBookDisplayEntry.placement as Some(PlacementInfo { cells, shape }). Each cell is either an authoritative Ingredient predicate or an empty position; shape: Some([width, height]) preserves shaped holes, while None gives the menu's ordered inputs. The recipe type owns these predicates, including custom component-sensitive tests. Display pictures never substitute for them. Use PlacementInfo::NOT_PLACEABLE explicitly for a preview-only recipe. Omitting placement information from a bound recipe refuses its declaration load rather than guessing ingredients from its icons.

The shared Wire boundary allows 32 structural record levels, including the category, display-entry and placement-info envelope. Nested ingredient shapes must fit that complete envelope; the native validator and wasm boundary use the same codec and refuse excess depth with WireError. Opaque NBT has its separate, iterative vanilla limit of 512 container levels; it does not spend one structural level per NBT container. Wide, shallow cooking grids do not consume extra depth.

Bound menus use the server's negotiated catalogue, not a reconstruction from local client recipe JSON. Each request names the exact published recipe and original display alternative, scoped to the connection epoch, open window, screen nonce, server menu instance and declaration generation. Left click places one increment; Shift requests the maximum. Right click opens the alternatives preview, whose left-click selection preserves the original source index even after filtering and craftability sorting. Unbound books remain preview-only.

The server tests the recipe type's authoritative predicates against exact component-aware stack classes and rechecks its live context after callbacks. It commits placement atomically, or refuses without publishing a partial plan. Persistent machines retain their real fuel and cooked output; placement does not craft their output. Only a current server missing-ingredients response installs ghost hints. Every new click, window change, disconnect or declaration reload revokes pending hints. Ghosts use the shared vanilla painter and the registered screen's native slot geometry, never built-in slot coordinates.

Displays are pictures, not ingredient predicates; declaring a result ghost never grants a real stack. NeoForge 26.3 public documentation names no registration counterpart for vanilla's internal GhostSlots.setInput and setResult; these declaration names are Horizon's.

Design: decide, fire, apply

Status: accepted with changes by the maintainer decision, combining both review views. The requirements below must be settled before runtime code; the note remains a provisional design, not implemented behavior.

Contract for #784, for Ari's review and decision on the issue. This is a documentation proposal, not implemented behavior. The named question is the decision token and stale-apply semantics across client-lib and menus.

Evidence and limits

Vanilla 26.3 was inspected from /workspace/horizon with python3 tools/rea_vanilla.py method net.minecraft.world.inventory.AbstractContainerMenu clicked. Its entry calls doClick(slotIndex, buttonNum, containerInput, player) synchronously. Exceptions become a reported crash with menu type, class, slot count, slot, button and input type. This verifies the entry and exception boundary only; it does not establish a reusable decision token, atomic rollback, or all downstream click semantics. Downstream vanilla callers and individual station algorithms remain to be pinned before runtime migration.

The issue explicitly names no NeoForge 26.3 counterpart (Horizon design). The permitted 26.3 AbstractContainerMenu Javadoc could not be accessed by the web reader. NeoForge's downstream click, cancellation and transaction behavior is consequently unverified; no equivalence is claimed. No NeoForge source, patches or other project's source were consulted. Public docs must supply any future counterpart claims.

Proposed contract

Client-lib decides using an immutable view; game dispatches the existing named hook with the catalog-selected Host; client-lib applies the frozen plan after validation. Lower crates never construct a Host or depend on Game. This is a control-flow boundary, not three new public hooks. Retain one hook per vanilla moment, and remove replaced transports and all callers together without compatibility aliases.

A decision is an internal, opaque, non-cloneable, single-use value. It contains action kind, side, actor lifecycle holder, world/session identity, target lifecycle holder, transaction/savepoint identity, proposed ordered mutations/effects, and a typed read set. Menu decisions additionally bind the menu instance generation, container identity, selected recipe and registry generation, slot layout/rules generation, cursor, input slots, output slots, capacities, permissions, costs, drag state and backing-storage versions actually consulted. Full stack components participate, not just item IDs/counts. Capture RNG state/draw position where relevant; decide must not consume shared RNG or publish effects. Store planned draws or reserve them transactionally. Never expose the token as mod-controlled bytes or retain borrowed menu pointers across dispatch.

Versions advance on every relevant mutation, including changes restored to equal values (ABA). The read set is operation-specific: an unrelated slot outside it need not invalidate a decision. Global identity checks always apply. Complete mutation epochs are required even in the interim: exact snapshots cannot detect ABA. Where per-slot mutation coverage is incomplete, conservatively invalidate the whole menu with a complete menu mutation epoch; snapshots may supplement, never replace, epochs. Do not silently accept an incomplete read set for performance.

Apply returns a proposed typed outcome: Applied, Canceled, Stale(reason), InvalidInput(reason) or ListenerFailed. Busy is an admission error before token creation, dispatch or mutation, not an apply outcome. Existing public operation results remain the only public result API: Applied maps to the existing success result; Canceled to that hook’s existing cancellation result; Stale and admission Busy to the operation’s existing refused/no-change result; InvalidInput and ListenerFailed to its existing failure/refusal result, with runtime diagnostics. Preserve each operation’s existing return shape and cancellation semantics; export neither tokens nor a second transaction API. A no-action decision dispatches nothing. Validate once before firing and again immediately before mutation against the transaction's live overlay, including listener writes. Deferred actions validate again at their ordered execution position. Invalid identity, changed cursor/slot/rule/recipe/permission or invalidated world refuses the original operation. Never rerun decide, retarget, reselect a recipe, repeat dispatch or retry automatically. A later player input can request a new operation. Consume the token on every terminal outcome; a second apply is invalid input.

Entity identity uses the existing lifecycle holder (server-wide epoch plus id), resolved through the entity table lookup as Found, Taken or Missing (#1606). No second entity generation is introduced. Missing is stale; Taken at admission is Busy, or during apply is Stale, never a retry.

Hook-specific mutable output is distinct from token preconditions. Validate that output against the unchanged decision inputs, then apply it once. For example, an anvil output override is allowed by its hook; replacing the input stack via Host invalidates the decision. Preserve each existing hook’s name, side and cancellation meaning rather than assigning a universal item-loss policy.

Transactions and reentrancy

Open an action child savepoint under the existing Host transaction before decide. Listener writes and apply share that action boundary. Nested listener commits merge into the action, never publish independently. Cancellation, stale refusal, invalid output or recoverable failure aborts the action, including listener writes, inventories, cursor, costs, RNG, deferred drops, notifications and packets. Outer abort also undoes an accepted action. Root commit alone publishes effects. Inside a lifted pass, defer drops, entity spawns, attachment-holder retirement and journal emission to root commit, following the placement note (#2319); rollback cannot un-retire a holder. Preserve its rollback ordering: discard listener pending writes/effects, undo listener Sim writes, reverse action mutations, restore actor/inventory/RNG, then close aborted. Listener reads of other entities use entity rows refreshed at tick exit; tentative entity changes remain invisible until commit.

An open action savepoint counts as a lifted pass for the save gate (#2211 and follow-up). Refuse every save during it, including listener save-all, with the existing save-failed message; the lease foundation alone is not the save gate. Use game/runtime/transactions.rs:174,179,303,399,462,513 for the existing open/close, menu journal, deferred effects, commit and rollback owners; these facilities are foundations, not proof of a complete menu/Sim journal.

Reentrant close/replace or same-menu click invalidates the outer decision. Refuse recursive execution on the active menu with Busy, before dispatch or mutation; allow other-object work only under nested savepoints. A requested close may be staged, but if it invalidates the outer action the whole action aborts, including that close. Do not retain a mutable borrow while firing. Restore lifted storage and release guards on all unwind paths. Multi-step quick move and recipe placement are one action with an ordered plan; no partial successful prefix on refusal. Post-commit notices remain separate moments and cannot retroactively veto committed writes.

Scope and inspected owners

Paths below are relative to this worktree's base. These are verified existing entry owners, not claims that their complete transitive caller graph is already migrated. The implementation must finish the vanilla caller oracle and per-route trace before claiming #784 complete.

Remote prediction never gains server authority. Client-side hooks receive ClientHost; server menu mutations receive ServerHost; both-side moments use typed HostSide. Network corrections may be sent after refusal to reconcile prediction, containing authoritative pre-action state; no success effects escape. Non-menu targets above are migration scope, but their precise read sets require individual oracle fixtures; this note does not invent their vanilla algorithms.

Trust, panic, target parity and cost

Validate untrusted mutable hook outputs and Host requests at the callback boundary. Internal typed values guaranteed by construction need no repeated structural validation in apply; apply rechecks live preconditions only. Validate owned IDs, generations, enum discriminants, slot indices, stack components/counts and capacities; reject non-finite numeric outputs and checked-arithmetic overflow. Preserve existing documented clamps where the hook owns them; do not turn unrelated unknown IDs from no-ops into errors. No arbitrary token deserialization, pointers or caller-supplied version numbers. Set finite read-set, plan-size and recursion budgets before runtime rollout; overflow refuses atomically, never truncates a plan.

Menu routes require #2232 and tracking issues #2244 and #2240 before migration: clicks run under as_guest, and a panicking listener must leave the guest swap restored.

Catch native unwinding at game dispatch; guest traps use the same ListenerFailed outcome and rollback. Log/report the failing listener under runtime policy. Process-aborting panics and rollback failure cannot be promised recoverable. A subsequent built-in action must work after a caught failure. Native and wasm expose the same hook/Host contract and ordered dependency dispatch; wasm handles are scoped, checked resources, not transferable decisions. Any changed public payload requires a shared-memory Wire representation and generated coverage row. Unsupported capabilities must fail registration/load with a named UnsupportedHookCapability refusal identifying the hook/capability, for both targets. Internal tokens need no Wire form. Leave frozen injection-point machinery untouched. Update generated bindings, docs and samples together.

Resolve subscribers at load. With no listeners, take the ordinary operation directly with zero token/read-set/payload allocations and zero all-mod scans; preserve enclosing transaction guarantees. Subscribed cost is proportional to consulted state and planned writes. Validation reads stored rule results and versions; it must not re-fire callbacks or recalculate an alternative action.

Acceptance matrix for implementation

These values are proposed requirements, not passing runtime tests. All refused cases publish zero success packets, drops and costs.

Proposed implementation stages

File no issues or PRs from this note.

1. Before code (PR 1), confirm downstream NeoForge menu click, cancellation and transaction contracts from public method/event documentation before assigning counterpart contracts to individual hooks; inventories and class-level coverage do not establish semantics. Finish downstream vanilla oracle/caller fixtures and the accepted token, refusal and rollback requirements on #784. Inventory every generated client-lib target, including targets without explicit annotations.
2. Add internal typed tokens, mutation generations and action savepoints to the existing coordinator; prove rollback and overlay validation with adversarial fixtures before exposing callbacks.
3. After #2232, #2244 and #2240 guest restoration prerequisites, migrate menu routes together, coordinating #2318 capacity ownership, #2259 mutable argument write-back and #2249 transaction fixtures. Remove old transports and update generated native/wasm bindings and samples.
4. Excluding the eight motion value transforms, migrate remaining client-lib targets in bounded slices with their individual read sets and side contracts. Run parity, failure recovery and allocation measurements before closure.

This unblocks the Host-bearing client-lib/menu half of the clean break, and supplies the stale-action foundation for #855 multi-block placement and #731 screen initialization where applicable. It does not settle #781 attachment Data storage, #792 entity storage or #796 identity by itself; those contracts supply identities this mechanism must validate.

Open questions

• Version granularity: whole menu or consulted slots? Per-slot/rule epochs plus mandatory menu generation are preferred; complete whole-menu mutation epochs are required until per-slot coverage is complete. Only the eventual granularity remains open; snapshots alone are never sufficient.
• Reentrant close semantics: should a listener close survive refusal? Atomic rollback with the action and admission Busy for recursive same-menu execution are required here; confirm operation-specific public refusal mappings in each route inventory before code.
• Budgets: which numeric limits? Recommend measuring maximum valid recipe/menu plans first, then freezing explicit limits and boundary tests; no arbitrary guessed limit in this proposal.
• Legacy clamp versus rejection: recommend retaining each hook's documented range/clamp and rejecting malformed structural output. Review each migrated declaration rather than imposing a new universal numeric policy.
• Complete route evidence: downstream vanilla and implicit generated targets remain unverified. Recommend making the route inventory and individual oracle fixtures a merge prerequisite for runtime implementation; this accepted provisional note is not evidence of completion. NeoForge downstream menu contracts remain unverified and public documentation confirmation is a PR 1 prerequisite.

Design: effect added

Accepted with changes for #835, per the maintainer decision. This remains a provisional design, not an implemented contract. The additional requirement withholds adoption of the pre-apply Added moment until the public NeoForge 26.3 contract is verified.

Evidence and vanilla moment

Inspected at base 95672cb54f using python3 tools/rea_vanilla.py from /workspace/horizon: LivingEntity.addEffect overload 1, LivingEntity.onEffectAdded, and MobEffectInstance.update. No NeoForge source, patches or other project's source were consulted.

Vanilla 26.3 first calls canBeAffected; refusal returns false. It looks up the active instance. An absent effect is inserted, onEffectAdded runs, changed becomes true, and the incoming instance's onEffectAdded runs. An existing instance is updated; only a true update result calls onEffectUpdated with forced=true and sets changed. Afterwards incoming.onEffectStarted runs even when update returned false. LivingEntity.onEffectAdded marks effects dirty, adds attribute modifiers and sends to passengers on the server. These are three distinct moments: first insertion, update, and accepted application attempt. Hidden-chain updates may mutate state while update returns false; false does not mean nothing changed. Stronger short effects preserve the former active instance in the hidden chain; equal-strength longer effects extend duration. Visibility/icon/ambient changes can count as updates.

The issue names MobEffectEvent.Added. The public 26.3 Javadoc request failed as inaccessible. Public living-entity docs were reachable but identified themselves as 26.1 and did not establish Added's 26.3 contract. Its exact timing, side, cancellation, payload and unchanged-update semantics are unverified. Do not infer them from its name or from vanilla onEffectAdded. Public verification is a prerequisite to implementation and may change the provisional moment below.

Proposed ownership and contract

Game owns the authoritative effect-add coordinator and the paused continuation. Lower effect stores own pure applicability/update decisions and versioned apply primitives; they never depend on Game or dispatch hooks. Every authoritative producer requests this operation with a stable LivingRef, incoming full instance and optional source. The coordinator covers vanilla and registered content effects identically.

The following moment is not adopted. Provisionally define Added as one notification for each application admitted by canBeAffected, including replacement, extension and unchanged/hidden-chain updates. Fire after applicability, before mutating the effect store. Payload freezes incoming and previous instances, target LivingRef and optional source; provide mutable ServerHost. Added is a notice, not another applicability veto. Its return does not replace the instance. This recommendation deliberately does not equate Added with vanilla's first-insertion-only onEffectAdded. Approve only after checking the published counterpart.

Follow CLAUDE.md's decide, fire, apply rule: decide captures target identity/generation, dimension, residency and the relevant effect-store version, immutable input and exact continuation phase. Outside lifted passes, callbacks read current holders and write through Host. Inside a lifted pass, do not restore rows mid-pass: listeners read entity rows refreshed at tick exit, and listener writes queue for application after that entity's tick at its exit apply point. A heavy read of another mid-pass entity must return a narrow Lifted error. These read rows and the write queue are prerequisites, not existing coordinator capabilities. Apply listener writes and the stored continuation in one transaction. Revalidate after dispatch; if the target was removed, changed dimension, replaced, or its effect read set changed, refuse the stale continuation without recalculating it. Aborting that action rolls back its listener child writes. Do not overwrite the holder with a cloned pre-callback row. Unrelated actor writes survive a successful transaction.

An explicit nested add requested by a listener is a distinct operation with its own notification. Execute it in deterministic transaction order, bounded by a declared nesting budget. If it changes the outer target's read set, refuse the outer operation; never replay its notification. Nested additions merge into the outer action and roll back with it when it becomes stale. Define how coordinator refusal maps onto public operation results separately from vanilla update false, which may retain hidden-chain mutation. Count notifications at dispatch, including a subsequently refused continuation, and count committed additions separately. There is no exactly-once committed-event claim for a pre-apply notice.

Keep vanilla first-insertion behavior and effect-type onEffectAdded separate from the public Added notice because vanilla executes different work between those moments. In game/items/potions.rs:1503, mod_effect_added_resolved currently filters to content effects and multiplexes new-only native_on_effect_added with native_mob_effect_added. Split those responsibilities by their actual moments, remove the content filter for Added and delete duplicate caller notifications. game/modding/native_living_effects.rs:138 must enter the coordinator instead of notifying independently. Update the catalog, generated adapters, hook notes and consumers together; retain no old numeric-ID alias.

Before implementation, verify the published counterpart's timing, logical side, mutability, cancellation, source/previous payload and unchanged/hidden-update behavior using public documentation only. Write the exact catalog signature and Host observation guarantees from that evidence. Today's catalog places Added after the first-insertion callback; moving it before mutation changes Host reads. If the verified counterpart is after mutation, preserve that public moment; internal stale tokens must not move it. Class-level coverage and vanilla algorithms do not establish this contract.

Define API-owned snapshots for incoming and previous full instances, effect keys, optional source identity and hidden chains; keep engine store types internal. Explicitly settle whether the source can be nonliving rather than narrowing it accidentally to LivingRef. Require shared-memory Wire layouts, generated coverage updates and registration/load refusal for unsupported payload capabilities; existing Hooks::mob_effect_added coverage does not prove redesigned payload support. Keep frozen injection-point machinery untouched.

Route owners to migrate

Paths below are relative to crates/horizon-client/src/; line numbers identify inspected current owners, not promised APIs. All rows enter the same coordinator; no producer gets its own Added dispatch.

Before migration, classify every producer by whether its actual call path runs inside a lifted pass. Commands, beacon, conduit, drink and splash from item use, and consumption outside passes migrate first. Mob attacks, raids, sculk and other mob AI wait for entity read rows and the write queue; consumption reached from mob AI belongs to that later group. Audit remaining routes rather than assuming their phase. Extend the census to turtle helmet, witch, illusioner, axolotl, contact effects, pufferfish and lower consumable paths.

This census identifies write owners, not a completed vanilla caller parity proof. Initialization/deserialization, network replication and test setup must be classified explicitly: restoring an already-active effect emits zero Added. Audit direct store mutations and trial-spawner initialization (game/mobs/trial_spawner.rs:353) before implementation; do not silently turn load/spawn restoration into application attempts.

All living holders use stable handles: local authoritative player, LAN guest, ordinary mobs, bosses and living holders currently refused by native writes (armor stands and dragon). Preserve vanilla immunity/override behavior; do not broaden acceptance merely to provide a handle. Resolve holder capabilities through the residency table lookup: dragon belongs to the design's 20 residency kinds and must not acquire a native-only exclusion. Verify armor stand applicability through the same capability model. Native API currently refuses these holders (native_living_effects.rs:90); holder capability parity requires explicit verification. Nonliving entities cannot be targets. Integrated single player, LAN host/guest and dedicated server use the same authoritative coordinator; remote prediction and inbound effect packets emit zero server Added. Exercise real guest routing rather than treating temporary player context as holder identity.

Residency, safety and cost

Use the existing residency boundary from #1606 and the placement design. Within a pass, retain lifted ownership and use the read rows and queued writes at the entity exit apply point; reacquire by generation there. Do not require restoring all lifted rows before dispatch or describe the planned write queue as already built. Balance lifted-pass leases on success, refusal and unwinding; no duplicate raw entity-list path. Preserve listener-spawned entities and attachment/join identities; defer retirement and publication to root commit. Saving while a lifted pass/action is open must refuse rather than persist partial state.

PR #2297 and PR #1863 were OPEN when inspected. The former carries the latter and modifies consume, fox and native effect integration. Neither establishes complete effect-add unification. Coordinate with their paused mob continuations and preserve their ownership restoration; recheck merged owners before implementation. Do not introduce a competing mob lift. PR #2112 is also OPEN; its mob-listener unwind restoration and stack are dependencies to coordinate with, not merged guarantees.

Mod input is untrusted: validate registry ownership, handle generation, dimension, duration (-1 infinite or nonnegative ticks), amplifier clamped to 0..=255 and flags at the handle boundary. Reject duration below -1 and unknown effect keys without changing unrelated no-op behavior. Validate finite numeric inputs before conversion where an adapter accepts floats; measure hidden-chain/nesting budgets without rejecting vanilla-valid instances or silently truncating valid state. Catch native unwinding and guest traps at dispatch, abort the action transaction, restore lifts and use runtime failure reporting/disable policy. Process-aborting panic cannot be recovered.

Resolve subscribers at load. No listeners means no payload allocation, cloning of hidden chains, event queue or per-tick scan; use the same vanilla update primitive directly with existing transaction guarantees. Subscribed cost is proportional to listeners and the touched effect chain. Never scan every mod or every living holder to find additions.

Acceptance matrix

Required future tests, not validation claimed by this note. Counts follow the provisional admitted-attempt definition above.

Proposed implementation stages

File no issues from this list.

1. Before any code, verify the public NeoForge 26.3 Added contract. Confirm timing, cancellation, payload, side and mutability using public docs only; record the exact signature and observation guarantees. The pre-apply moment is not adopted until then. Complete the vanilla caller census, phase classification and holder capability fixtures.
2. Introduce pure lower-store decisions and the Game-owned coordinator with stale checks for producers outside lifted passes first: commands, beacon, conduit, item use and consumption outside passes. Require payload/Wire coverage and refusal behavior before exposing the API.
3. Wait for entity read rows and the write queue before migrating mob-pass producers, including attacks, raids, sculk and other mob AI. Apply queued writes at entity exit and reuse accepted mob-listener unwind restoration; never restore rows mid-pass or migrate these producers first. Remove duplicate/content-only dispatch as each route migrates and update generated API/docs atomically.
4. Run the full route/holder/server matrix, per-producer in-pass panic and balanced-lift fixtures, nested rollback/result mapping, save refusal and allocation/budget measurements before claiming #835 complete.

Open questions

• What exact moment does published 26.3 Added cover? Recommendation: admitted application attempts, including unchanged updates, provisionally; verify Javadoc before implementation and follow Ari's decision if different.
• Can a pre-apply Added be observed for a refused continuation? Recommendation: yes, explicitly distinguish dispatched from committed counts; never retry a stale decision. If committed-only notice is required, redesign the moment before coding.
• How broad must holder capability support be? Recommendation: every vanilla living holder with its real applicability overrides; verify armor stand/dragon behavior rather than retaining blanket native exclusions by accident.
• What nesting and chain budgets apply? Recommendation: deterministic runtime-wide measured limits with transaction refusal, shared with existing Host operations; no silent truncation.
• What exact catalog payload, source identity (including nonliving sources), Wire layouts and public refusal result follow from verification? Requirement: settle these before exposing code; reject unsupported capabilities at registration/load.
• When may in-pass producers migrate? Requirement: only after read rows, write queue and shared unwind restoration exist; outside-pass producers go first.
• What may merge ahead of the carry PRs? Recommendation: this docs note only; implementation must integrate the accepted continuation ownership and world-visibility decision.

Design: entity render state

Provisional answer to #897: introduce one owner-thread entity preparation operation, after complete base and specialized extraction and before model posing or geometry emission. All entity routes call it. Extend the frame-owned store accepted in PR #2357, rather than adding an entity cache, callback bus or second lifetime system. This is a proposal, not an implemented API. That page/store is absent at this checkout (5166fe4588); its implementation is a prerequisite, not presumed landed.

Vanilla and NeoForge 26.3

Verified using /workspace/horizon: python3 tools/rea_vanilla.py method net.minecraft.client.renderer.entity.EntityRenderer extractRenderState. Vanilla copies type, interpolated position, invisibility, age, dimensions, name/leash data, fire, outline and packed light into state. The corresponding callers query reports 25 references with complete coverage, including createRenderState, living renderers and specialized boat, minecart, projectile, display and other renderers. This establishes that the base extractor alone is not the final specialized-state boundary. It does not establish a mod hook or complete higher-level world/UI caller coverage.

The issue requests RegisterRenderStateModifiersEvent. The public 26.3 Javadoc was inaccessible. Exact registration types, callback order, threading, field coverage and limits are unverified. Obtain public documentation before adopting the final counterpart contract. No NeoForge source, patches or other project renderer source was read. The limits below are Horizon proposals.

Verified routes and preparation boundary

Owners relative to the repository at 5166fe4588; these are current integration points, not existing extracted-state implementations.