Groundworks

Players

• A Stretch is paid from the held stack first, then from the rest of the main inventory, and hands what it replaces back into the slot its charge freed: when it takes the held stack's last item, what it replaces lands in the hand, not in the first empty slot. Otherwise it joins a stack of its own before an empty slot, as before. (#36)
• Fast Replace. A plain click with a block on a placed block of the same Replace group puts the held block in its place, and the preview draws it blue before you click. It costs one of the held block and hands the replaced one back, into your hand when that was the last. A sneak-click places beside instead, and a held Raise or Lower height leaves a replace where you aim. When there is no room for what comes back, the click is refused and you are told why. No vanilla block is in a group yet. (#31)
• A Fast Replace that can't go through changes nothing and tells you why: it is refused where you may not build, in adventure mode, outside the world, in spawn protection or in a claim, and where an entity stands in the new block's way, and it never places beside instead. A creative player pays nothing for a replace, is handed nothing back, and is never refused for room. (#32)
• Fast Replace keeps the replaced block's orientation: the new block faces the way the old one did, and the preview shows it, unless you turned the held block with Rotate, which re-orients the replace and stays on the stack. (#33)
• A pack developer groups vanilla blocks for Fast Replace with block tags under groundworks:replace_group/: each tag is one Replace group, and a plain click with one of its blocks on another replaces it. A datapack adds or changes a tag, remove included, and a reload takes effect. A block in two tags belongs to the first by id, and the log warns once. Groundworks ships no tag, so a vanilla install sees no replace until a pack adds one; a group a mod states in code claims its blocks first. (#34)

Consumers

• FastReplace.group(Identifier, Predicate<? super Block>) states a Replace group: its blocks replace one another on a plain click, through the held item's own plan, asked with a place context whose clicked block counts as replaceable so that the plan lands on the aimed block (ADR 0008). Placements.isReplacing(BlockPlaceContext) tells an item's plan it is planning a replace, and its context has no Raise height. Only the main hand's BlockItem replaces, and a replace is drawn whether or not its block is opted in. The library carries out the click, not the item's own place: it charges one held item, swaps the block, calls setPlacedBy and the placed-block trigger, and hands the old block's item back. An item whose plan puts no block in the aimed block's place is refused as Refusal.FastReplace.PLANS_ELSEWHERE, and no room for the refund as Refusal.FastReplace.NO_ROOM_TO_RETURN. (#31)
• Refusal.FastReplace.MAY_NOT_BUILD refuses a replace where the player may not build at a position its plan puts a block, or where a protection mod cancels the place event, which the library fires on the click for each placed position of a replace that would otherwise go through, and never in the plan the preview asks. Where the player may not build, it wins over every other refusal of a replace, the item's own included. (#32)
• A replace's plan carries the old block's orientation: the block at the aimed position takes each facing, axis or rotation it shares with the block it replaces, the properties Rotate turns, as the same Property object and never by name, and any other property stays what the item's plan made of it. No other property is copied, since one may count what a block holds, as a double slab's type does, or name a part of a block that spans two; a Consumer whose blocks keep more sets it in its own plan or builder. A Rotate turn held on the stack skips the copy, so the item's plan, asked with the turned look, is the new state. Only the aimed position is copied; a plan with other positions keeps the item's states there. (#33)
• FastReplace.group(Identifier, Predicate<? super Block>, ReplaceBuilder) states a Replace group whose replace spans several blocks: a ReplaceBuilder plans the whole replace from the held stack, the aimed position and the old state, with every position it swaps, the state at each and which it replaces, and says what the replace hands back, by default the aimed block's item. It plans nothing where it makes no replace, and the click is the item's own. The builder decides which members replace which, the aimed block's own kind included, and its plan is used as it is, with no orientation copied. A plan that replaces a position it puts no block at is refused as Refusal.FastReplace.LEAVES_A_GAP, since a replace swaps and never clears; a builder's own refusal is told through its message. One held item is charged and one refund handed back for the whole plan, and the library lays it as it lays the item's, each position swapped in the plan's order. (#35)