Block parts
From Sunrise's modding bookead8a1e
On this page
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.
Light emission
BlockPart::light_emission supplies positional light for blocks that declare dynamic_light: true. It runs on both sides with a read-only host. Return Some(level) to replace the state's emission or None to keep it.
| Rule | Behavior |
|---|---|
| Eligibility | Every state of a block declaring dynamic_ is queried; other blocks are not. |
| Calls | Chunk arrival, block edits and LevelRef:: query emission. |
| Caching | Light workers read the stored answer; they do not call your Part. Call check_ when data your answer depends on changes. |
| Thread | The callback runs on the thread that owns the level. |
| Range | Values above 15 are clamped to 15 before entering the light queue. |
| Client updates | A server light update queries each affected section's cells at most once per cell per update. |
| Exclusions | The block's own rendered light, ambient occlusion and mob-spawn rules use the state's light instead. |
Keep the callback a pure function of the level, position and state, without side effects.
Path classification
BlockPart::block_path_type answers for event.state at event.pos, with a read-only host for the owning level. Return Some(PathType) to replace the whole static classification, even for air, or None to use vanilla. The same state may answer differently by position. This is separate from is_pathfindable, which remains state-only. The server caches the final static classification in 4096 direct-mapped positional slots shared by its AI workers, including Open for missing navigation-region chunks. A collision replaces a slot. A matching sendBlockUpdated notification clears it: ordinary writes require an actual state change, UPDATE_CLIENTS and full chunk status at least BLOCK_TICKING; direct block-entity notifications clear even unchanged state. Time, /reload, chunk load and chunk unload do not clear it. Keep the answer deterministic for that lifetime. Neighbour and mob-specific adjustments are not stored in this cache; existing per-search evaluator caches remain.
BlockPart::adjacent_block_path_type answers for a neighbour at its own event.pos; event.path_type is that neighbour's classified type, not the node's type. Return Some to end the scan immediately, even if the answer equals the node's current type. Return None to retain that neighbour's fluid and vanilla contribution. Neighbours are visited in x, y, z order, each from -1 to 1, excluding the node's own column. No mob is supplied to either query. A panicking callback is contained and falls back to the default. Vanilla water contributes through its classified path type, so a solid waterlogged block remains Blocked rather than producing WaterBorder. Custom fluids keep their default WaterBorder contribution. This deliberately differs from NeoForge's raw-water default to preserve exact vanilla behavior for vanilla content.
Connections
BlockPart::can_be_connected_to lets the block beside a fence, a wall, or iron bars or a pane answer whether that connector connects to it. The event names your block's pos and state, the connector state, its vanilla rule (kind), the direction from your block toward the connector and face_solid, whether your block's face toward it is sturdy. Return Some(true) to connect, Some(false) to refuse, or None to keep vanilla's rule.
| Rule | Behavior |
|---|---|
| Order | Vanilla's rule, then your block's answer, then the connector's own connects_, which starts from that answer and has the last word. |
| Calls | When the connector is placed and each time it settles its shape toward your block, on authoritative servers. |
| Walls | A connected wall side is still low or tall from the block above it. |
| Panics | A panicking part is contained with a warning, and vanilla's answer is used. |
Answer from the event without touching the world: the level host is read-only.
State changes
BlockPart::on_block_state_change hears a block change from event.old to event.new at event.pos, at the end of a Level.setBlock that held. The parts of the old state's block hear it, then, when the block changed, the parts of the new state's block; event.state names the state whose parts are asked. The host is a read-only LevelSide.
| Rule | Behavior |
|---|---|
| Moment | After the client update, the neighbour updates and the neighbours' shape updates: a fence beside new stone already shows its connection. A write made inside those updates is heard after the updates it queued itself, so its neighbours are settled too; several such writes are heard in the order they happened. |
| Replaced writes | A write whose on_ replaced the block is not heard; the write that replaced it is. |
| Sides | Servers hear every changed write with event.predicted: false. Clients hear server updates, applied local predictions (including breaks and placements), settled corrections and piston replays. |
| Predictions | Applied local writes are heard immediately with event.predicted: true. Server updates at predicted positions stay held and unheard until acknowledgement. A confirmation of the same state has no second event; a denial is heard once from the predicted state to the server's with predicted: false. |
| Not heard | Equal-state writes, unapplied guesses made while deciding an action, and world generation's writes. |
| Cost | Without a listener, one flag check; no event or level adapter is built. |
block_ | The global server hook hears a change earlier, right after the state is written, and also for replaced writes. |
| Panics | A panicking part is contained with a warning. |
Rotation
BlockPart::rotate answers how a structure template turns your block as it places it: world generation's structures, /place template, the structure block, jigsaw blocks and the host's template snapshots. event.state is already mirrored, event.pos is where it goes and event.rotation the template's turn. event.rotated starts at the game's own turned state; set it to another state of the same block, for example context.state_with_property(event.state, "facing", "north").
Jigsaw connector discovery is different from block placement: matching and expansion read the connector's plain rotated state, without calling BlockPart::rotate, as StructureTemplate.getJigsaws does in vanilla. The template palette still depends on the read position: the origin for candidate matching, the piece's real origin for expansion. Named start anchors likewise use the palette at the position where they are sampled. The actual template block writes still call the rotation Part at their placed world positions.
| Rule | Behavior |
|---|---|
| Context | A worldgen Part method: a WorldgenHost on the worldgen workers or the server thread, no Host, no writes. Keep it a pure function of the event. |
| Refusals | A state of another block, or one the game does not have, is refused with a warning; the game's state is placed. |
| Mirroring | Stays the game's: vanilla's table, or the template's for a mod block. |
| Panics | A panicking part is contained with a warning, and the game's state is placed. |
Landing writes
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.
Storage changes
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. Hook version 2 also lets an automation block entity watch another position without polling or attaching Parts to every possible source block type. Its Part calls observer.watch_contents(host, source_pos, true) on its live BlockEntityRef; false unregisters. The source is in the observer's level and need not be loaded. Registration is idempotent and joins the current transaction: abort restores the previous watches. An observer without a subscribing BlockPart returns ContentsWatchError::NotSubscribed; a stale or unwritable observer returns Stale. A block entity temporarily taken for its own tick can still register.
event.observer is None for the source's own Parts and Some(observer) for a watcher. The event's level, position and state always describe the changed source, not the observer. Source Parts run first, then a snapshot of watching observers in registration order, each one's subscribing Parts in their usual order. Registration changes made in a callback affect the next notice; an observer invalidated before its turn is skipped. A self-watch never duplicates the source callback. Removal, replacement and chunk unload discard the observer's watches. Reload alone does not restore them: the Part must call watch_contents again. Watches are runtime state, never saved. Unloading the source does not cancel watches of its position.
The backing contents are already written, before dirty/comparator updates. Game-held vanilla container writes coalesce their implicit notice per backing block at root commit. Explicit BlockEntityRef::set_changed notifies immediately, even inside a transaction and for unchanged contents; abort does not retract it. Raw mod-owned storage writes and restores synthesize no notification. A double container notifies each component, not again for the other half's comparator refresh. A listener's writes still apply, but its backing block does not re-enter; another block notifies normally. Entity/menu placeholder coordinates are not block notices. Explicit notices may read tentative items:
#[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::sunrise_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,
});
}
}Crop fertility and farmland hydration
Two BlockPart methods let a block change what vanilla's crops and farmland ask of the blocks around them. Both run on an authoritative server with a read-only LevelHost, and a block with no part answers as vanilla does.
BlockPart::is_fertile is asked for the soil of a growing crop. On its random tick a crop, stem or pitcher crop asks each of the 3 × 3 blocks under it, but only a block in #minecraft:grows_crops: a block outside the tag is never asked. fertile starts as vanilla's answer, moisture > 0, and the contract is collect: set it to decide. A fertile block adds 3 to the growth speed and any other tagged block 1 (a quarter of either off-centre).
BlockPart::can_be_hydrated belongs to a farmland block. On the farmland's random tick the game scans the 9 × 2 × 9 box from its position (x and z from −4 to 4, y 0 and 1) in x, then y, then z order, and asks only at a position whose fluid is not empty, passing the fluid (FluidState) and its position. The contract is replace:
| Answer | Meaning |
|---|---|
Some(true) | This position waters the farmland; the first one ends the scan and moisture goes to 7. |
Some(false) | This position does not water it, whatever the fluid. |
None | Vanilla's rule for this position: a fluid in #minecraft:water. |
Rain on the block above, the watered-area ticket, moisture changes and drying out are unchanged. With no part on the farmland the scan is vanilla's. Bookshelf slot-occupancy flags and the last-interacted slot are transactional storage bookkeeping, not notification effects. Aborting restores them with the items. Changed observers, comparator ticks and data-send requests already issued still survive that abort.
Fluid faces beside a block
Client BlockPart methods change how a fluid draws its faces against your block. They are collect: set the field to decide. They depend on the block state and the fluid alone, so the client asks them on its own thread for every state and fluid when it joins a world and on ClientHost::refresh_render_visibility, as it asks block_render_visibility, and the meshing workers read the answers from a table. They never run per frame, and the level and position are not arguments. event.fluid is the fluid as it is asked: a source at amount 8, or a flowing fluid at amount 7, not falling. Water's and lava's flowing forms are fluids of their own, so a part can answer each.
BlockPart::should_hide_adjacent_fluid_face answers whether your block hides the face a fluid beside it draws toward it. event.direction points from the fluid to your block, so Direction::Up is the top of a fluid under your block. hidden starts false. Vanilla's tests still apply first: a fluid beside the same fluid, or behind a face that occludes it, draws no face there whatever the answer.
BlockPart::should_display_fluid_overlay answers whether a fluid's side beside your block uses the fluid's overlay sprite (water's water_overlay) instead of its flowing sprite. overlay starts with vanilla's test: true beside a block of vanilla's HalfTransparentBlock class (glass among them) or LeavesBlock class, and for a content block, its template's class. A fluid with no overlay sprite, such as lava, draws its flowing sprite whatever the answer.
With no part answering either method, nothing is asked, the tables are empty and fluids draw exactly as vanilla's.
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



