Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ excluded from the release JAR.

## Content and operation

MMDLib standalone definitions register all 17 legacy block IDs and four legacy item IDs under
MMDLib XML machine definitions (the twelve machines) and standalone definitions (the other
blocks and items) register all 17 legacy block IDs and four legacy item IDs under
`steamadvantage`. The art and translations originate in SA2; texture paths,
blockstates, models, enchantments, recipes, mining tags, and loot use 1.21.1 formats.
There is a SteamAdvantage creative tab.
Expand All @@ -40,8 +41,8 @@ There is a SteamAdvantage creative tab.
| Geothermal boiler | Gains heat beside lava or magma, boils water after reaching operating temperature |
| Oil boiler | Burns 100 mB aliquots of tagged liquid fuel, consumes water, outputs steam |
| Steam tank | Stores 1,000,000 mB steam; comparator reports fill level |
| Steam furnace | Three independent vanilla smelting lanes; fuel heats the furnace, steam increases heating |
| Rock crusher | Uses MMDLib `mmdlib:crushing` recipes; 125 processing ticks at 150 mB steam/tick |
| Steam furnace | Three independent smelting lanes on steam alone; each smelts at the recipe's cooking time, 2000 mB steam per 200 ticks |
| Rock crusher | Runs every MMDLib `mmdlib:crushing` recipe; 125 ticks and 18,750 mB steam per item |
| Steam drill | Mines in its facing direction, extends a damaging drill shaft, retains drops, follows adjacent steam track at range/obstruction |
| Steam elevator | Redstone raises the platform and passengers; removing power retracts it; 16-block search range |
| Steam still | Runs PA3 distilling recipes with persisted progress and output |
Expand Down Expand Up @@ -125,7 +126,8 @@ The integration suite checks all machine registrations, capabilities, NBT
persistence, steam filtering, boiler fuel/energy/water use, redstone behavior,
PA3 pipe delivery, pumping conservation, crushing and blocked-output behavior,
three furnace lanes, drill movement/inventory preservation, elevator movement,
valve operation, distillation ratios, and musket loading/firing.
valve operation, distillation ratios, imports of saves from before the XML machine
port, and musket loading/firing.

The development client completed resource reload and atlas creation without
SteamAdvantage missing-model or missing-texture warnings. Actual in-world
Expand Down
3 changes: 3 additions & 0 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ implementation and its relevant gameplay checks are complete.
- Looks up the mined block's item in MMDLib's live crushing recipes, matching
the steam crusher's recipe type. Uses the recipe's complete output when
present; otherwise uses normal unenchanted diamond-pickaxe drops.
- Removed in 3.2.0: with Mineralogy's runtime c:cobblestones tag every rock
crushed to gravel, so the drill now always returns normal block drops,
like Electric Advantage's laser drill.
- Checks all output slots together before mining spends steam or advances
progress. Insufficient space preserves the block and pauses mining until
the entire result fits; recipe output replaces rather than adds to loot.
Expand Down
2 changes: 1 addition & 1 deletion build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ if (project.hasProperty('gameTests')) {
}
}
}
tasks.named('jar') { exclude '**/SteamGameTests*', 'data/steamadvantage/structure/empty.nbt', 'data/steamadvantage/recipe/test_slow_distillation.json', 'data/c/tags/fluid/oil.json', 'mmdlib/standalone/block/test_large_steam_tank.json', 'mmdlib/screen/test_large_steam_tank.xml' }
tasks.named('jar') { exclude '**/SteamGameTests*', 'data/steamadvantage/structure/empty.nbt', 'data/steamadvantage/recipe/test_slow_distillation.json', 'data/c/tags/fluid/oil.json', 'mmdlib/machine/test_large_steam_tank.xml', 'data/steamadvantage/legacy_saves/**' }
tasks.named('sourcesJar') { exclude '**/SteamGameTests*' }
tasks.named('javadoc') { exclude '**/SteamGameTests*' }
}
Expand Down
161 changes: 88 additions & 73 deletions docs/mmdlib-integration.md
Original file line number Diff line number Diff line change
@@ -1,84 +1,99 @@
# MMDLib integration

SteamAdvantage is a consumer and showcase of MMDLib's public standalone APIs.
It does not declare a synthetic material to register machines or crafting parts.

## Content path
SteamAdvantage is a consumer and showcase of MMDLib's public APIs. Its twelve machines are
MMDLib XML machine definitions (MMDLib 2.0.3 or later); its other blocks and items are MMDLib
standalone plans. It declares no synthetic material.

## Machines

Each machine is `src/main/resources/mmdlib/machine/<block id>.xml`. MMDLib registers its block,
item, block-entity type, capabilities, screen, recipe type and JEI catalyst, and generates its
blockstate, item model and loot table from the XML. All of them extend the abstract
`steamadvantage:steam_base` (hardness, pickaxe, required tool), which extends
`mmdlib:base_machine` (redstone and side-configuration drawers, recovery capsule, base screen).

MMDLib's generated resource pack sits below mod resources, so SteamAdvantage must not ship its
own blockstate, item model or loot table for a machine. A machine's `appearance` names a model
that is not `block/<id>`, so SteamAdvantage's models are `block/<id>_model`.

| Machine | Work | Tanks (index order) | Items |
| --- | --- | --- | --- |
| Coal / oil / electric / geothermal boiler | `*BoilerProcessor` | steam, water, (oil: fuel) | coal: fuel |
| Steam tank | `SteamTankProcessor` | steam | |
| Steam switch | `SteamValveProcessor` | steam | |
| Steam pump | `PumpProcessor` | steam, product | |
| Steam-powered still | `StillProcessor` | steam, product, input | |
| Steam elevator | `ElevatorProcessor` | steam | |
| Steam drill | `DrillProcessor` (six-way facing) | steam | 5 outputs |
| Steam crusher | MMDLib recipe lane + `RecipeMachineSensor` | steam | input, 5 outputs |
| Steam furnace | three MMDLib recipe lanes + `RecipeMachineSensor` | steam | 3 inputs, 3 outputs |

Custom processors extend `SteamProcessor` (a `StoredProcessor`). It provides the steam helpers,
SA2's rule that a machine stops while it receives any redstone signal (the elevator uses the
signal instead), and the comparator reading every machine XML selects with
`<redstone comparator-source="steamadvantage/comparator"/>`. Machine state (burn timers,
temperature, drill depth, elevator position, distillation batches) is processor state.
Admission rules that tags cannot express (furnace fuel, the config-selected oil fuel tag, still
inputs from Power Advantage's distilling recipes) are `filter-processor` bindings on processors
that implement `StorageAdmission`.

The crusher and furnace use MMDLib recipe processors with recipe types declared in their XML:

- `steamadvantage:steam_crushing`, from `recipes.SteamCrushingRecipes`: every MMDLib crushing
recipe, 125 ticks and 18,750 mB of steam per item by default.
- `steamadvantage:steam_smelting`, from `recipes.SteamSmeltingRecipes`: every smelting recipe at
its own cooking time, with MMDLib's FE price converted to steam (a 200-tick recipe costs
2000 mB). The furnace's three lanes bind `input`/`output` to their own slots and share the
steam tank.

Authored recipe JSON with a generated recipe's ID replaces it. `RecipeMachineSensor` supplies
their comparator reading (input fullness) and lets a working furnace melt snow above it.

### Block entity

`machines.SteamMachineEntity` extends `DefinedMachineEntity` and is registered for every machine
with `MachineContent.registerEntityFactory` in the mod constructor. It:

- imports saves from before the XML port (`migrateMachineData`): each processor's
`importLegacy` copies the top-level keys it used (`Burn`, `Temperature`, `Depth`...) into its
state, the pre-2.0.2 `Energy` key becomes `energy`, and `legacySlots` maps the old shared
nine-slot inventory onto each machine's declared slots (unplaced contents, such as the
retired furnace fuel slot, go to recovery). Storage keeps the `Items` and `Fluids` keys and
the old tank order;
- holds recipe machines while they are powered (`processingAllowed`);
- clears the drill pipe when a drill is removed (`dropContents`, which MMDLib never calls on chunk
unload) or turned (`setBlockState`), and skips dropping contents while a drill moves itself
along a track.

### Screens

Machine XML screens extend MMDLib's base machine screen: generated, interactive tank gauges,
generated slot groups and recipe progress, a pause button, and the redstone and
side-configuration drawers. XML machine screens bind to `DefinedMachineEntity`, so the extra
displays SteamAdvantage adds in a machine's `machine` region (burn meter, heat gauge, drill
depth, distillation progress, help text) read processor state through static helpers,
`value="zone.moddev.mc.SteamAdvantage.machines.SteamScreens#burnTime"` and so on.

## Other content

1. `mmdlib/block/*.json` and `mmdlib/item/*.json` select public implementation factories.
2. `mmdlib/standalone/block/*.json` and `mmdlib/standalone/item/*.json` declare instances.
3. MMDLib's startup loader discovers and validates those files.
4. `init.ContentFactories` registers public `BlockImplementation`, `ItemImplementation`,
and `BlockEntityFactory` contracts.
5. `init.ModContent` queues only this namespace's standalone plans on
`RuntimeContentRegistrar`, then passes its own block-entity `DeferredRegister` to every
`BlockEntityHandle` the registrar prepared. It has no block or item registers.
6. MMDLib creates the blocks and paired items, and gives each machine block a prepared
`BlockEntityBinding`. `MachineBlock` delegates construction and ticking to
`MaterialEntityBlock`.
7. `MachineSettings.CODEC` validates behavior selection and storage capacities. Each machine
type has its own ID matching its block and XML screen.

The library registrar also provides the creative tab. Capability storage/roles, transfer
operations, `MachineCapabilities` registration and crushing recipes use MMDLib.

A test-only standalone tank changes capacity to 2,345,678 mB and inventory size to 12.
It registers, persists and exposes its fluid through XML-bound getters without adding a
Java registration or material definition. Its data and screen are excluded from releases.

## GUI

Twelve machine-specific XML files live under `mmdlib/screen/`. Each declares its slots,
gauges, progress indicators, labels and tooltips, and its file name matches the machine's
block-entity type, which is how MMDLib finds it. SteamAdvantage contains no menu, screen,
renderer, layout or synchronization code:

| Concern | Provided by MMDLib |
| --- | --- |
| Schema, reading, getter binding, layout | `gui.load`, `gui.model`, `gui.layout` |
| Menu, slots, shift-click, opening | `gui.runtime.MachineMenu`, `ScreenRuntime`, `BlockEvents.openMenu` |
| Value synchronization | `gui.runtime.ScreenNetwork`, `ScreenValues`, `ScreenSnapshots` |
| Screen and gauge rendering | `gui.client.MachineScreen`, `GaugeRenderer` |

The block-entity class `SteamMachine` extends MMDLib's `machine.neoforge.BaseMachine`, which
implements `gui.runtime.ScreenHost` and owns persistence through a `MachineInventoryLifecycle`
(items under `Items`, fluids under `Fluids`, the electric boiler's buffer under `energy`; older
saves' `Energy` is still read). Machine state such as burn time and drill depth stays top-level
through `saveMachineData`/`loadMachineData`, and broken machines drop their items through
`BaseMachine.dropContents`. `screenItems()` exposes its `ItemStorage` (so roles and filters
apply to clicks and shift-click) and
`screenRecipeSlots()` names the crusher and furnace recipe inputs for optional JEI transfer.
Right-click goes through the `steamadvantage:use_machine` handler declared in
`mmdlib/extension/machines.json`: fluid containers act on the machine's tanks first, otherwise
`BlockEvents.openMenu` opens the XML screen.

Remaining SteamAdvantage-side code that MMDLib has no equivalent for: the comparator reading in
`MachineBlock` (MMDLib's comparator support does not yet read block-entity getters) and the
fluid-container interaction above. Moving the machines to MMDLib's XML machine definitions, as
Power Advantage 3.2 has, waits on MMDLib support for six-way facing (the drill) and for
processor-supplied slot and tank filters.

Each machine also declares MMDLib automation groups (`SteamMachine.automationGroups`): item
fuel/input/output groups where a machine has them, and steam, water or input, fuel and product
tanks. Every face of a group starts at the group's role, which matches the access SA3 always
exposed. The item, fluid and energy capabilities registered in `ModContent` read each face's mode
from these groups, so side settings gate pipes and hoppers and are saved under `automation`.
Because `BaseMachine.screenAutomation()` returns these groups, every machine screen gets MMDLib's
built-in side-configuration drawer, coloured group outlines on its slots, and add-on and filter
slots per group (Power Advantage's fluid intake and output pumps work there). Fluid and energy
groups name their screen gauge, which is highlighted while the group is selected. Installed
add-ons drop as items when a machine is broken.
2. `mmdlib/standalone/block/*.json` and `mmdlib/standalone/item/*.json` declare the pipes, track,
drill bit, platform, pump shaft, components and musket.
3. `init.ContentFactories` registers their `BlockImplementation`, `ItemImplementation` and
`BlockEntityFactory` contracts; `init.ModContent` queues this namespace's standalone plans on
`RuntimeContentRegistrar` and registers the pipes' capabilities.

## Verification

The GameTest suite checks the XML-declared versus hidden slots, output-role protection,
shift-click routing, host removal, rejection of mismatched screen definitions, codec validation,
payload round trips for numbers exceeding `long`, decimals and fluid amounts, and layout of every
screen through MMDLib.
The GameTest suite covers each machine's behavior, comparator readings (real comparators
included), automation sides and their persistence, Power Advantage pump add-ons, menu slot
roles and shift-click, rejection of mismatched screen definitions, an XML-only variant machine
(a GameTest-only tank that extends `steam_tank`), and imports of saves written by the pre-XML
entity, kept as SNBT fixtures in `src/gameTest/resources/data/steamadvantage/legacy_saves`.

An opt-in client fixture copies the disposable GameTest world and opens each of the twelve
screens through the actual block interaction. It checks synchronized getters, verifies that
each translated layout fits, captures each rendered screen, and shuts down automatically:
An opt-in client fixture copies the disposable GameTest world, opens each of the twelve screens
through the actual block interaction, checks that each layout fits and has its gauges, captures
each rendered screen, and shuts down automatically:

```sh
./gradlew -PgameTests runGameTestServer --offline
Expand Down
6 changes: 3 additions & 3 deletions gradle.properties
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Example: 1.0.0. 1 21 01 2 notice the minecraft version hidden there at the end?
# and the 2 means it's for NeoForge while 1 is Forge and I suspect if we did Fabric mods 3 would be for that.
# (This also helps for bug reports as the version number gives us a clue as to what version of Minecraft the bug happened on)
mod_version = 3.1.0.121012
mod_version = 3.2.0.121012
mod_name = SteamAdvantage
mod_id = steamadvantage
mod_archive_name = SteamAdvantage
Expand All @@ -24,8 +24,8 @@ minecraft_version_range = [1.21.1,1.21.2)
neoforge_version = 21.1.265
neoforge_version_range = [21.1.265,21.2)
loader_version_range = [4,)
mmdlib_version = 2.0.2.121012+Neo
mmdlib_version_range = [2.0.2,3)
mmdlib_version = 2.0.3.121012+Neo
mmdlib_version_range = [2.0.3,3)
poweradvantage_version = 3.2.0.121012+Neo
poweradvantage_version_range = [3.2.0,4)

Expand Down
Loading