Add reservation-aware machine processing and a playable companion mod

.github/workflows/build_status.yml

@@ -50,3 +50,59 @@ jobs:
           retention-days: 14
           path: |
             build/libs/*.jar
+
+      - name: Upload test reports and game test logs
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: check-reports
+          path: |
+            build/reports/tests/
+            build/gametest/logs/
+            build/companion-gametest/logs/
+          if-no-files-found: ignore
+
+  gui-smoke:
+    name: Client GUI smoke test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gradle/actions/wrapper-validation@v6
+      - uses: actions/setup-java@v6
+        with:
+          distribution: 'microsoft'
+          java-version: ${{ env.JAVA_VERSION }}
+      - uses: gradle/actions/setup-gradle@v6
+
+      - name: Install Xvfb and Mesa
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb libgl1-mesa-dri
+
+      # Run the companion before the library smoke, which injects test sources into main output.
+      - name: Companion GUI smoke test
+        timeout-minutes: 20
+        run: xvfb-run -a ./gradlew runCompanionClientSmoke
+
+      - name: GUI smoke test with JEI
+        timeout-minutes: 20
+        run: xvfb-run -a ./gradlew runClient -I scripts/gui-smoke.init.gradle
+
+      - name: GUI smoke test without JEI
+        timeout-minutes: 20
+        run: xvfb-run -a ./gradlew runClient -PwithoutJei -I scripts/gui-smoke.init.gradle
+
+      - name: Upload client logs and screenshots
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: gui-smoke-logs
+          path: |
+            build/companion-client-smoke/logs/
+            build/companion-client-smoke/screenshots/
+            build/gui-smoke/logs/
+            build/gui-smoke/screenshots/
+            build/gui-smoke-without-jei/logs/
+            build/gui-smoke-without-jei/screenshots/
+          if-no-files-found: ignore

.github/workflows/publish.yml

@@ -45,9 +45,10 @@ jobs:
 
       - name: Read gradle.properties
         run: |
-          # Keeps the CurseForge ID defined in one place.
+          # Keep the CurseForge ID and archive name defined in gradle.properties.
           prop() { grep -E "^$1\s*=" gradle.properties | cut -d= -f2- | tr -d '[:space:]'; }
           echo "CURSEFORGE_ID=$(prop curseforge_id)" >> "$GITHUB_ENV"
+          echo "MOD_ARCHIVE_NAME=$(prop mod_archive_name)" >> "$GITHUB_ENV"
 
       - name: Build and test
         run: |
@@ -70,10 +71,11 @@ jobs:
         with:
           github-token: ${{ github.token }}
           version: ${{ env.TAG }}
-          # Main jar first so it becomes the primary file, sources/javadoc attached as extras.
+          # Exact release filenames exclude companion jars and stale versions.
           files: |
-            build/libs/!(*-@(sources|javadoc)).jar
-            build/libs/*-@(sources|javadoc).jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}.jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}-sources.jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}-javadoc.jar
 
       - name: Publish to CurseForge
         if: env.HAS_CURSEFORGE == 'true' && env.CURSEFORGE_ID != ''
@@ -84,8 +86,9 @@ jobs:
           curseforge-id: ${{ env.CURSEFORGE_ID }}
           version: ${{ env.TAG }}
           files: |
-            build/libs/!(*-@(sources|javadoc)).jar
-            build/libs/*-@(sources|javadoc).jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}.jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}-sources.jar
+            build/libs/${{ env.MOD_ARCHIVE_NAME }}-${{ env.TAG }}-javadoc.jar
           loaders: |
             neoforge
           environment: client | server

build.gradle

@@ -163,6 +163,9 @@ configurations.named('runtimeTestCompileOnly') {
     extendsFrom configurations.compileOnly
 }
 
+// Optional playable examples, packaged separately from MMDLib.
+apply from: 'scripts/companion.gradle'
+
 // Javadoc for extenders and maintainers: `./gradlew javadoc` (output in build/docs/javadoc).
 // Records and fluent builders are described in prose, so per-parameter tags are not required.
 tasks.named('javadoc', Javadoc) {

docs/block-entities.md

@@ -95,7 +95,8 @@ prepared handle. MMDLib does not create or attach that register:
 
 ```java
 // During construction, before registry events:
-var types = DeferredRegister.<BlockEntityType<?>>create(Registries.BLOCK_ENTITY_TYPE, MODID);
+var types = DeferredRegister.<BlockEntityType<?>>create(
+        net.minecraft.core.registries.Registries.BLOCK_ENTITY_TYPE, MODID);
 types.register(modBus);
 // After definitions have been queued, still before registry events:
 registrar.blockEntityHandles().values().forEach(handle -> handle.register(types));
@@ -126,8 +127,138 @@ public CrusherBlock create(BlockContext context) {
 ```
 
 The block delegates `newBlockEntity` and `getTicker` to `binding.prepared()`, as
-`MaterialEntityBlock` does, and reads `binding.type()` only after registration (for
-example when a block entity is created), never in its constructor.
+`MaterialEntityBlock` does. It also overrides `onRemove` as `MaterialEntityBlock` does: without
+it, `DropsContents` is never called and nothing reports the missing hook. It reads `binding.type()` only after registration (for example
+when a block entity is created), never in its constructor.
+
+## Machine features
+
+The separately packaged [machine companion](machine-companion.md) provides playable examples of
+the processor, a one-slot converter, shared lanes and a creative power source.
+
+A `FeatureHost` runs a machine's `MachineFeature`s, such as a `RecipeProcessor`, and saves each
+under its key. The block entity ticks it from `serverTick` with `features.tick(level)`, and saves
+and loads it through a `DynamicOps`, after the storages, since a processor checks the loaded
+contents against its saved cycle:
+
+```java
+final FeatureHost features = new FeatureHost(this::setChanged).add(processor);
+
+// saveAdditional
+tag.put("features", features.save(registries.createSerializationContext(NbtOps.INSTANCE)));
+// loadAdditional, after the storages
+features.load(registries.createSerializationContext(NbtOps.INSTANCE), tag.get("features"));
+```
+
+**Running recipes.** A `RecipeProcessor` is built from a feature key, a machine recipe type and a
+`MachineInventory`, and added to the host; the block entity's ticker calls `features.tick(level)`:
+
+```java
+final RecipeProcessor processor = new RecipeProcessor("work", MyRecipes.CRUSHING, inventory);
+final FeatureHost features = new FeatureHost(this::setChanged).add(processor);
+
+// The factory's server-side ticker:
+BlockEntityTicker<CrusherEntity> ticker =
+    (level, pos, state, entity) -> entity.features.tick(level);
+```
+
+`status()` is one of: `IDLE`, no cycle is running; `RUNNING`, a cycle is running; `STALLED`, a
+cycle is waiting for energy and keeps its progress and reservations; `BLOCKED`, a cycle has run its
+time but cannot finish, say an input was taken, and retries each tick; and `PAUSED`, held by an
+interrupt. `progress()` and `time()` give the ticks done and the ticks the cycle takes, for a
+screen; `time()` is 0 when idle or paused.
+
+On `/reload` a running cycle finishes as planned, and the next cycle uses the new recipes.
+
+Failed recipe searches retry every 20 ticks while inventory revisions stay unchanged. Built-in
+item/fluid groups report changes to contents, rules and reservations, so new inputs or freed output
+space trigger a search on the next tick. Custom groups can implement `SlotGroup.revision()` for the
+same response; the periodic retry also catches recipe reloads and changes in untracked groups.
+Running cycles and consecutive successful cycles are not delayed.
+
+**Interrupting.** `interrupt()` stops the processor from drawing energy and starts nothing new
+until `resume()`; `paused()` says whether it is held. It works without power and whatever the
+status. It also releases the running cycle's reservations, so the items it locked can be taken
+out. This is the trap for players: an unpowered machine keeps its inputs and outputs locked, and
+the only ways to get them back are an interrupt or breaking the block. A mod should give the
+player a button, an `Element.Button` in the screen XML with a `gui-click` handler (see
+[GUI screens](gui-screens.md)) that calls `interrupt()` or `resume()`. Resuming reserves the paused
+recipe again if it still can. Progress is kept only if that recipe still exists, can reserve its
+inputs and output space again, and has the same `time`; otherwise progress resets.
+
+**Groups.** The processor reaches storage through the inventory's group keys. Groups in one
+inventory must not overlap: use one key for each set of slots or tanks. Multiple processor lanes
+can share that inventory and reserve the same slot, provided enough unreserved inputs and output
+space remain; each lane holds only its own share of the slot's plan.
+
+A machine with one slot for both input and output must use one key for both. For a different-item
+product, the cycle must also consume the entire stack: a recipe turning 1 iron into 1 gold cannot
+start with 2 iron in the slot, because the leftover iron blocks the gold (`NO_ROOM`). A slot limit
+of 1 makes that recipe usable without asking players to remove surplus iron. A product that stacks
+with the remaining input can share the slot, subject to its limit.
+
+**Clearing.** When replacing a block, `/setblock` and `/fill` normally call `Clearable.tryClear` on
+its block entity first, which is how a chest's contents vanish instead of dropping. A
+block entity with `DropsContents` that should do the same also implements `Clearable`, and
+empties its storages (and their plans) in `clearContent()`. Without it, the command drops the
+contents. Both commands' `destroy` mode destroys the old block before clearing, so its contents
+still drop even when the block entity implements `Clearable`.
+
+Call `RecipeProcessor.reset()` on each lane before clearing storage: it releases that lane's plans
+and clears progress, the remembered recipe and pause state. Fresh inputs can then start new work.
+Use `interrupt()` for a player-requested pause that should keep its place, not for clearing a machine.
+
+**Dropping contents.** A block entity of a `MaterialEntityBlock` (which includes `mmdlib:machine`)
+that implements `DropsContents` has `dropContents(level, pos)` called on the server when its block
+is broken or replaced by another block, but not when only its state changes. Usually it is
+`items.dropAll(level, pos)`. Reserved items are still in their slots, so nothing else needs to be
+given back.
+
+Custom blocks can call `DropsContents.onRemove(state, level, pos, replacement)` before their
+superclass removal hook to use the same server-only, different-block guard.
+
+**Syncing to clients.** Nothing is sent to clients unless the block entity opts in. A feature that
+should be readable on the client, for a renderer, particles or a tooltip, returns true from
+`syncsToClient()`; `RecipeProcessor` does. The block entity then wires `FeatureSync`:
+
+```java
+final FeatureHost features =
+    new FeatureHost(this::setChanged, () -> FeatureSync.send(this)).add(processor);
+
+@Override
+public CompoundTag getUpdateTag(HolderLookup.Provider registries) {
+  return FeatureSync.updateTag(features, registries);
+}
+
+@Override
+public Packet<ClientGamePacketListener> getUpdatePacket() {
+  return ClientboundBlockEntityDataPacket.create(this);
+}
+
+@Override
+protected void loadAdditional(CompoundTag tag, HolderLookup.Provider registries) {
+  super.loadAdditional(tag, registries);
+  if (FeatureSync.read(features, tag, registries)) return;
+  // the usual loading
+}
+```
+
+The host sends at most once every 10 ticks (`FeatureHost.SYNC_INTERVAL`), and always sends the
+latest change. Storages are not part of the update.
+
+A feature controls what clients get with two methods. `clientState()` is the state to send, by
+default what `state()` saves; a feature overrides it for a moment clients shouldn't see.
+`restoreOnClient(state)` takes it on, by default as `restore`. `RecipeProcessor` overrides the
+second to copy only its status, pause flag, progress and time, because a client has no storage
+contents to check a cycle against, and never reserves anything.
+
+On the client, `processor.status()` and `processor.time()` are current. `processor.progress()` is
+as of the last status change, so a progress bar reads it from a screen getter instead; screens keep
+their own getter sync (see [GUI screens](gui-screens.md#wiring-a-machine)). While paused, `time()`
+is 0, so a bar must not divide by it without checking.
+
+`FeatureSync.read` goes by the tag's key, not the side: a `/data merge` that includes the key
+runs `restoreOnClient` on the server.
 
 ## Deferred registration and block hooks
 

docs/capabilities.md

@@ -6,8 +6,8 @@ directly, and automation gets per-face views of it.
 
 | Class | Wraps | Main points |
 |---|---|---|
-| `ItemStorage` | `ItemStackHandler` | Per-slot `Role`, filter, limit; `insertResult` for products; `dropAll` |
-| `FluidStorage` | several `FluidTank`s as one `IFluidHandler` | Per-tank `Role`, capacity, filter; `tank(i)` for the machine |
+| `ItemStorage` | `ItemStackHandler` | Per-slot `Role`, filter, limit; `insertResult` for products; `dropAll`; reservations |
+| `FluidStorage` | several `FluidTank`s as one `IFluidHandler` | Per-tank `Role`, capacity, filter; `tank(i)` for the machine; reservations |
 | `EnergyBuffer` | `IEnergyStorage` | `long` internally; `int` values clamped for other mods; transfer rates |
 | `SideConfig` | | Per-face `IoMode`, stored relative to the machine's front; codec |
 | `MachineCapabilities` | `RegisterCapabilitiesEvent` | One-line registration with per-side modes |
@@ -37,6 +37,37 @@ directly, and automation gets per-face views of it.
   machine facing up or down, `TOP` is the north side. `RelativeFace.facing(state)` reads the
   `facing` or `horizontal_facing` property, and defaults to north when the state has neither.
 
+## Reservations
+
+`ItemStorage` and the client menu handler share `PlannedItemHandler` for insertion, extraction and
+capacity rules. Item and fluid storages use `ReservationPlans` for plan merging, release and
+transaction rollback. Direct content setters remain available to the owning machine and save loading.
+
+Custom menu handlers and wrappers can implement `ReservedSlots`, including `plan(slot)`, to publish
+the same snapshots as `ItemStorage`. During a click, menu slots expose only unreserved items to
+vanilla; outside the interaction, rendering and synchronization still show the full stack. A number
+key or offhand swap can therefore move the free portion without moving reserved items.
+
+A machine that runs a recipe over many ticks can reserve what the recipe needs. `ItemStorage`
+keeps one `SlotPlan` per slot and `FluidStorage` one `TankPlan` per tank: how much the machine will
+take from it, and what it will add. `RecipeProcessor` makes and releases the plans itself; a mod
+that runs its own cycles uses `reserve(slot, plan)`, `release(slot, plan)` and `plan(slot)`
+(`tank` for fluids). A slot or tank with no plan behaves exactly as without this feature.
+
+What a plan does to the calls on the storage:
+
+| Call | With a plan |
+|---|---|
+| `extractItem`, `drain` | Never goes below the reserved amount. 50 iron with 1 reserved gives up 49 |
+| `insertItem`, `fill` | Accepted only if the slot still ends up as one legal stack within its limit after the machine takes and adds what it planned, and the stack in the slot now can hold it |
+| `insertResult` | Obeys the plan like `insertItem`; it skips roles and filters, not reservations |
+| `tank(i)` | Its `fill` and `drain` obey the tank's plan |
+| `isItemValid` | Answers for the planned end state, so a hopper is not offered what would break the plan |
+| `setStackInSlot`, `setFluid` | Still bypass the plan. They stay available for undoing a transaction and loading a save, and they are the one way to break a running cycle |
+
+Plans are not saved by the storages. A feature saves its own cycle and puts the plans back when it
+loads, so load the storages first.
+
 ## Example
 
 ```java