Registry keys
Request existing entries inside Hooks::register with r.block_key(id), r.item_key(id), r.effect_key(id) or r.fluid_key(id), where r is a &mut dyn Registrar. Retain the returned keys in your mod or Part and reuse them.
From Sunrise's modding bookead8a1e
On this page
- Entity-type reads
- Block states
- Registry lookup and enumeration
- Fluids and effects
- Hot item and block identities
- Matched recipe lookup
- Owned values
- Opaque NBT metadata
- Owned component trees
- Particle identities
- Placement and loot snapshots
- Item values and tag names
- Scoped Parts
- Damage and item metadata snapshots
- Recipe-file fields and small values
- A bare registration ID uses
minecraft:. Requests are canonicalized and deduplicated. - Requests resolve after every mod's content is known, so another mod can supply an entry.
- An unknown request refuses the load with the requesting mod and canonical ID, even if you never attach the key to a Part.
- Keys are opaque
u32slots on native and wasm, not engine numeric IDs. key.id(host)returns an owned canonicalStringfor diagnostics. It needs a game-backed host; an invalid slot is a boundary error, not an empty name.
Keys identify entries for the running mod load, not persistent data. Persist canonical identifiers and property strings rather than registration slots or state ordinals. Reload preserves key identity; world numeric mappings and tag membership are separate reloadable data.
Entity-type reads
EntityRef::kind(host) and the handles that delegate to it return Option<EntityTypeKey>, using the existing entity-type registry. The key is a copyable scalar on native and wasm; compare it with a retained key instead of allocating and comparing a type-name string on every read. A stale or missing entity still returns None. There is no separate equipment-only type read.
After the registry is available, resolve the type keys your Part needs once and retain them. host.entity_type_keys() enumerates that registry; key.id(host) explicitly requests its canonical namespaced name. Name resolution returns an owned diagnostic string and can allocate. Persist the name, never the scalar slot. For example, retain the zombie key at setup, then compare entity.kind(host) == Some(zombie_key) in a predicate.
The key derives Wire through its scalar slot: host decoding checks the registered slot, while a wasm guest carries the host-issued key without a separate name table.
This is a clean break from Option<String>: callers that need textual names must request .id(host) explicitly. UnspawnedMobRef::kind keeps its separate scoped Identifier/error contract, and block-entity type reads keep BlockEntityTypeKey.
Block states
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 immutable block metadata explicitly, without a Host. Local state ordinals retain their meaning when world numeric state IDs are reordered.
Use host.block_state_default(key) for a block's default state and host.block_in_tag(key, tag) for membership in a string tag name. On a restricted level host, schedule_block_tick(pos, key, delay) also takes a BlockKey.
host.block_states().states_of(key) returns Option<BlockStateRange> in immutable local ordinal order. It returns None before metadata is published, for an unknown block, or without a game-backed host. 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. LevelRef reads follow their 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 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.
Registry lookup and enumeration
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. Block enumeration lists each block once, not once per state. Build lookup tables from these lists at load time instead of resolving names per tick. A table is empty before its registry loads; registration-time RegistrationContext does not see any of them.
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.
fn resolve(host: &dyn mod_api::Host) {
if let Some(block) = host.block_key("minecraft:stone") {
assert_eq!(block.id(host), "minecraft:stone");
}
if let Some(effect) = host.effect_key("minecraft:speed") {
assert_eq!(effect.id(host), "minecraft:speed");
}
assert!(host.block_key("test:missing_block").is_none());
assert!(host.effect_key("test:missing_effect").is_none());
}These calls are also available on &dyn ServerHost and &dyn ClientHost. Both lookups return None before their registry completes, including for vanilla names.
Fluids and effects
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. 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, describes its appearance. 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 use 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 use strings.
Retain keys to avoid formatting identifiers on hot paths.
Matched recipe lookup
Use level.recipe_for(host, &recipe_type, &inputs) to find a matching recipe. 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. 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 be inspected and drawn. Unknown item keys and invalid/unrepresentable effect payloads refuse encoding; this is not a total conversion. Insertion and other world writes retain strict validation.
Owned values
Use API-owned values rather than importing engine or package-loader types.
| Value | Contract |
|---|---|
TooltipDisplay:: | Takes an API ItemStack; its effective tooltip component includes vanilla's implicit defaults. |
LootContext, LootStack | Own their facts. Candidate items use ItemKey; counts are signed. Ordered Option<Tag> patches preserve removals and NBT types; names are Text trees. Writeback is atomic. |
ItemBar, ItemRarity | Describe item resource properties. |
Side | Package metadata: Client or Both, not the executing logical HostSide. |
Suggestion | Construct with Suggestion::. Offsets are bytes; tooltip and int_ are writable. |
Block, Item | Registration declarations. Component patches are (String, Option<Tag>) entries; None removes a component. Content-file admission checks apply. |
BlockEntityTypeDecl | Declaration snapshot produced by r.block_. |
GuiDraw | GUI commands; DrawContext:: returns a GuiPaintError naming the op it could not draw (text conversion, an item slot, a texture or sprite), and draws nothing of that buffer. HUD hooks reject invalid writeback as a whole. |
ServerHost::game_rule(id) reads the one server-wide rule store without a LevelRef, including in server_about_to_start and server_starting. It returns Result<GameRuleValue, GameRuleReadError>; an unknown identifier gives GameRuleReadError::UnknownRule. ServerHost::game_rules() lists every available rule and its current value by namespaced id. Both native and wasm mods can use these reads. Saved values and a new world's create-screen choices are installed before the first server hook, without firing game_rule_changed for loading. Level reads use the same store once the requested level exists.
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. Use the boolean-key getter for a retained BoolGameRuleKey.
GameRuleDecl records a mod's rule name, category and GameRuleDefault: either Bool(value) or Int { default, min, max }. Category references resolve after all declarations; invalid declarations refuse installation without a partial table.
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.
Text::validate() checks tree/payload bounds and profile fields without cloning; validate_depth() is the component-only preflight. NaN/infinity and unpaired UTF-16 are 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 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; match every case explicitly. Component records such as Text and TextStyle are #[non_exhaustive]: use their constructors and accessors rather than external struct literals, and leave room for additional fields when destructuring. 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 displays the fallback text itself; parsing and native constructors follow the same rule.
Particle identities
Request a ParticleKey with Registrar::particle_key and retain it. Every parameter-family ParticleOptions constructor takes its key; use simple(key) for a simple particle. Unknown forward references refuse publication of the whole particle registry. Retained keys resolve to vanilla or custom named sprite providers without parsing identifiers per read.
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 load-owned item table. The game applies the returned block state.
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 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) tags.blocks(tag_key) and tags.fluids(tag_key) return registered keys in vanilla's member order. Unknown tags return false or empty lists. Clients read the tags sent by their server. Membership reads return None before authoritative tags are applied 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 enumeration returns BlockKey values, including blocks no mod requested. An unresolved member returns None for the entire list, not a partial result. The engine TagRegistry, StackData, StackView and DisplayContext are not API types.
Scoped Parts
Hooks scoped to a block, block entity, item or menu belong to BlockPart, BlockEntityPart, ItemPart or MenuPart, respectively. BlockEntityPart is also a BlockPart. Attach a Part to react to your own content; use a global Hooks event when you need to react to every matching object.
- Scoped methods have no
Hooksmethod. Objects without Parts are not called. - Parts run in dispatch order; cancellation or replacement skips later Parts.
- A corresponding global event runs before Parts; its cancellation skips them.
- Attaching the same Part type twice to one object, an invalid key declaration, or an unnamespaced ID in other Part registrations refuses startup with diagnostics naming the mods.
- Parts take
&selfand requireSend + Sync. A Part panic adds, part <type>to the mod and hook attribution.
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 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. Use DamageContainer setters to edit damage and cooldown; sequencing is game-owned.
ItemResource::damageable, foil and repairable delegate to the game's 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 return Ok(None). Result objects retain their components patch. These helpers are reload-time reads, not per-tick JSON parsers.
KeyConflictContext, FireworkShape and JarInputsError are API-owned values. JarInputsError carries owned diagnostics and the original-jar identity.
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



