From 638d90c4f0592f9b7fb8be32435914ec620ee046 Mon Sep 17 00:00:00 2001 From: Algent Date: Wed, 9 Sep 2026 00:52:19 +0200 Subject: [PATCH] feat: add saw strength API --- JAVA_MIGRATION.md | 9 ++-- JAVA_MIGRATION_ABI_INVENTORY.md | 5 ++ JAVA_MIGRATION_CONSUMER_AUDIT.md | 16 ++++-- JAVA_MIGRATION_DIVERGENCES.md | 2 + JAVA_MIGRATION_HANDOFF.md | 17 +++---- JAVA_MIGRATION_MANUAL_CHECKS.md | 1 + docs/API.md | 7 +-- docs/api/SAW_STRENGTH.md | 49 +++++++++++++++++++ docs/migration/HISTORY.md | 24 +++++++++ .../scala/codechicken/microblock/ItemSaw.java | 14 +++++- .../ItemSawCharacterizationTest.java | 19 ++++++- .../examples/SawStrengthExample.java | 14 ++++++ 12 files changed, 154 insertions(+), 23 deletions(-) create mode 100644 docs/api/SAW_STRENGTH.md create mode 100644 src/test/java/codechicken/microblock/examples/SawStrengthExample.java diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index d37179a..5443365 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -64,7 +64,7 @@ The phase checklists include recurring verification rules, historical work and c | Workstream | Remaining deliverables | Gate | | --- | --- | --- | -| Complete the supported Java surface | Physical-client validation of the documented illuminated microblock example; supported saw-strength customization for Iguana; finish the audited reflection/legacy-use map | Next FMP milestone; direct typed calls and documented override behavior, without requiring consumer reflection | +| Complete the supported Java surface | Physical-client validation of the documented illuminated microblock example; keep the completed audited reflection/legacy-use map current as consumer revisions change | Direct typed calls and documented override behavior are available for the identified FMP-side gaps; physical-client evidence remains | | Migrate consumers and adopt releases | Patch GuideNH/Schematica to their documented APIs; migrate ProjectRed's external trait and other Scala/helper users, including OpenComputers, ProjectBlue and ForgeRelocationFMP; direct Galacticraft integration; Et Futurum/Iguana migrations; UtilitiesInExcess enumeration and `mat`/`material` fix; complete the full adoption ledger beyond these hotspots | Source patches, released versions and actual target-pack jars must all be recorded; reference checkouts are not migrated | | Measure and improve performance | Fresh realistic profiles, ranked candidates, bounded improvements and repeated paired measurements; distinguish FMP implementation gains from migrated-consumer gains and report variability/regressions | Phase 4b starts when API/extension workloads are stable; it can overlap consumer adoption | | Validate releases | Complete client rendering/particles/lighting/interaction and integration checklist; old-world, multiplayer, movement and preview checks; packaged/obfuscated artifacts on supported runtimes; optional-mod absent/present loading; actual patched-world MCPC hook where supported | Automated Forge tests do not replace physical-client/full-pack evidence; repeat affected checks after consumer migration and Scala removal | @@ -738,7 +738,7 @@ does not close a row, and scans must distinguish a consumer's own Scala code fro | Schematica | Private Scala-mangled field `codechicken$multipart$MultiPartRegistry$$typeMap`, cast to `scala.collection.mutable.Map` | `MultiPartRegistry.getPartFactory(String)` is implemented; [guide and example](docs/api/FACTORY_LOOKUP.md). Schematica replaces map/Option lookup with the public method and retains its microblock creation/rejection policy | FMP lookup ready; consumer patch/release/adoption pending | | GuideNH | Companion `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | Direct Java tile generation/loading, microblock creation and existing `block()` / `meta()` access are documented/tested; [typed material query](docs/api/MATERIAL_ACCESS.md). Remove reflection/accessor mixins when migrating | These FMP paths ready; broader consumer migration/release/adoption pending | | Et Futurum Requiem | Mutable static `int[] ButtonPart.metaSideMap` and `sideMetaMap` must stay public and mutable | `ButtonPart.setOrientation(int, ForgeDirection)` is implemented and documented; Et Futurum adopts it | FMP API ready; consumer patch/release/adoption pending | -| IguanaTweaksTConstruct | Private `ItemSaw.harvestLevel` field name and type | FMP exposes a supported harvest-level setter; Iguana uses it | After step 1 | +| IguanaTweaksTConstruct | Private `ItemSaw.harvestLevel` field name and type | `ItemSaw.setHarvestLevel(int)` is implemented and documented; Iguana uses it before ForgeMicroblock post-init | FMP API ready; consumer lifecycle/source patch, release and adoption pending | | Galacticraft | Selects the first public method named `registerMaterial` without checking its signature, so FMP cannot add any overload of that name | Call `registerMaterial` directly from gated compatibility code; exact-signature reflection is an interim hardening option | Existing public API; consumer migration can start | | UtilitiesInExcess | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | Both call sites read only the name, so `materialCount()` from Phase 9.1 plus the existing `materialName(int)` covers them; no material object is needed | After Phase 9.1, before it enters the pack | | UtilitiesInExcess | Not an FMP constraint, but a shipping hazard: the server factory reads NBT key `material` while `MaterialBasedPart.save` writes `mat` | Fix on the UtilitiesInExcess side; FMP must not special-case it | Immediately; no FMP change needed | @@ -789,8 +789,9 @@ UtilitiesInExcess's `extrautils:*` aliases; there is no legacy-conversion risk i - [ ] Fix the UtilitiesInExcess `mat`/`material` key mismatch and its `getIdMap()` use before it enters the pack. - [x] Add supported button-orientation mapping for Et Futurum as additive API, preserving the legacy arrays; [guide and example](docs/api/BUTTON_ORIENTATIONS.md). Consumer migration/release/adoption remain pending. -- [ ] Add the supported harvest-level setter needed by Iguana as additive API. Schematica and GuideNH's identified - FMP-side replacements are complete; their consumer migrations remain pending. +- [x] Add the supported harvest-level setter needed by Iguana, preserving the legacy field name/type; + [guide and example](docs/api/SAW_STRENGTH.md). Iguana must finish changes before ForgeMicroblock post-init so its + cached maximum sees the final saw tiers. Consumer migration/release/adoption remain pending. - [x] Provide Schematica's registered-factory lookup without exposing the mutable map: `getPartFactory(String)`, with identity/missing-name checks, exact public reflection, a compiling example and the retained private field. This does not complete Schematica's consumer migration. diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index 44ef42b..e3ed3c7 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -171,6 +171,11 @@ keeps the two direction maps consistent; [guide](docs/api/BUTTON_ORIENTATIONS.md `metaSideMap` and `sideMetaMap` fields retain their exact names, types and modifiers for old releases. Removing or narrowing them still waits for a migrated Et Futurum release, target-pack adoption and a fresh reflective-source scan. +`ItemSaw.setHarvestLevel(int): void` now replaces Iguana's private-field write; [guide](docs/api/SAW_STRENGTH.md). +The existing private `harvestLevel: int` field remains for old releases and shares storage with the setter. It loses +only `ACC_FINAL`, which makes the supported mutation explicit and keeps reflective writes working. Removal still +waits for an Iguana release, target-pack adoption and a fresh scan. + ## Consequences for the migration plan 1. Phase 8 (Scala runtime removal) should be reclassified as deferred, not scheduled. Decision 4 is answered. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 0ad93e2..c066768 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -406,7 +406,7 @@ added to compatibility CI before it enters the pack. | AE2 Fluid Craft | Reflects `TileMultipart` and registers Waila part providers | Tile class name and `jPartList`/provider behavior reached by AE2 | | GT5U | Detects `TileMultipart`, iterates `jPartList`, and finds a ProjectRed `GatePart` to expose its screwdriver slot | Tile identity, Java list view/order, part instance identity | | EnderCore | Tests items with `instanceof ItemSaw` for durability display | `ItemSaw` class identity and inheritance | -| IguanaTweaksTConstruct | Creates saws through `MicroblockProxy`, reads saw methods, accesses proxy companions, and reflectively mutates private `ItemSaw.harvestLevel` | Proxy methods and `MODULE$`, `Saw`/`ItemSaw` identity, exact `harvestLevel: int` field name/type | +| IguanaTweaksTConstruct | Creates saws through `MicroblockProxy`, reads saw methods, accesses proxy companions, and reflectively mutates private `ItemSaw.harvestLevel` | Proxy methods and `MODULE$`, `Saw`/`ItemSaw` identity, exact `harvestLevel: int` field name/type until adoption; `setHarvestLevel(int)` is the supported replacement | | Et Futurum Requiem | Reflectively gets and mutates static `int[] ButtonPart.metaSideMap` and `sideMetaMap` to add floor and ceiling orientation | Exact class and mutable static field names/types until migration; `ButtonPart.setOrientation` is the supported replacement | ## Source-only hazards that must be added to the compatibility checklist @@ -419,7 +419,7 @@ requirements: | Schematica | `MultiPartRegistry$.MODULE$`; field `codechicken$multipart$MultiPartRegistry$$typeMap` of Scala mutable-map shape; exact generator/load methods | FMP schematic tile reconstruction disables itself or returns no preview | | GuideNH | Companion-only generator methods; `partList_$eq(Seq)`; `BlockMicroMaterial.block` and `.meta` mixin fields | Missing/incorrect guide preview, material export, or part statistics | | Et Futurum | Static mutable `ButtonPart.metaSideMap` and `sideMetaMap`, both `int[]`, until direct API adoption | FMP buttons attach with pre-fix orientation behavior | -| Iguana | Private `ItemSaw.harvestLevel` field | Existing saw cutting strengths are not adjusted | +| Iguana | Private `ItemSaw.harvestLevel` field until direct setter adoption | Existing saw cutting strengths are not adjusted | | Galacticraft | Reflection by method name only for `registerMaterial` | Galacticraft micro-material registration is skipped after a caught exception | | Waila | `BlockMultipart` string plus tile NBT `parts`/part `id` | No multipart HUD data | @@ -427,8 +427,9 @@ These need targeted runtime tests or explicit downstream patches. They cannot be **Current branch:** `ConsumerReflectionCompatibilityTest` freezes the GuideNH, Et Futurum, Iguana, and Galacticraft member shapes above. `ButtonOrientationFunctionalTest` also freezes Et Futurum's exact array mutation and all-face -placement, then verifies the supported typed replacement. Schematica's registry lookup has its own live-view regression -test. The manual client checks remain necessary for end-to-end integration behavior. +placement, then verifies the supported typed replacement. `ItemSawCharacterizationTest` runs Iguana's exact boxed +field mutation and the direct setter against shared storage. Schematica's registry lookup has its own live-view +regression test. The manual client checks remain necessary for end-to-end integration behavior. ## Data and ordering contracts @@ -531,6 +532,7 @@ tied to a released minimum dependency version. Unlisted contracts remain governe | `MicroblockGenerator$.create(MicroblockClass, int, boolean)` exact reflection and private shape copy | GuideNH `7d8fb44e77b9`: `getMicroblockGeneratorCreate`, `promoteMicroblockToClient` | Existing static `MicroblockGenerator.create` with the same parameter types/order; recreate family/material and restore encoded shape through public API | Source patch/release pending; guide/example tested on server, physical client and custom shape-setter overrides require adoption checks | No migrated pack version verified; retain companion singleton and exact descriptor | | Private `BlockMicroMaterial.block` / `meta` accessor mixin and reflective material query | GuideNH `7d8fb44e77b9`: `AccessorBlockMicroMaterial`, `resolvePrimaryMicroblockId` | Direct `jPartList()`, `Microblock.material()`, `getMaterial(int)`, `BlockMicroMaterial.block()` / `meta()`; [typed example](docs/api/MATERIAL_ACCESS.md) | Source patch/release pending; remove mixin, retain export filtering/failure policy, validate getter overrides and optional loading | No migrated pack version verified; retain private fields | | Reflective mutation of `ButtonPart.metaSideMap` / `sideMetaMap` | Et Futurum Requiem `78a5744dfd33`: `compat.CompatMisc.runModHooksInit` | Two direct `ButtonPart.setOrientation(int, ForgeDirection)` calls; [mapping and lifecycle guide](docs/api/BUTTON_ORIENTATIONS.md) | FMP API/example complete; consumer source patch and first released version pending | Retain both public mutable arrays until the migrated release is in the target pack and a fresh scan confirms no legacy access | +| Reflective mutation of private `ItemSaw.harvestLevel` | IguanaTweaksTConstruct `2bc09889d3e2`: `modcompat.fmp.IguanaFMPCompat.postInit` | Read `harvestLevel()` and call `setHarvestLevel(int)`; [state and lifecycle guide](docs/api/SAW_STRENGTH.md) | FMP API/example complete; consumer source/lifecycle patch and first released version pending | Retain the private field until the migrated release is in the target pack; ensure Iguana runs before ForgeMicroblock post-init and rescan for legacy access | | `NormalOcclusionTest$.apply(Traversable, Traversable)` | OpenComputers `2c00f79be24b`: `common.block.Cable.canConnectFromSideFMP`, `server.network.Network.canConnectFromSideFMP` | `NormalOcclusionTest.testBoxes(ownBounds.asJava, otherBounds)`; `otherBounds` already comes from Java `getOcclusionBoxes()` | Source patch and release pending; retain side/color/face filtering | No migrated pack version verified; retain the companion and descriptor | | `NormalOcclusionTest$.apply(Traversable, Traversable)` | ForgeRelocationFMP `49a810b8c63b`: `FramePart.occlusionTest` | `NormalOcclusionTest.testBoxes(boxes.asJava, getOcclusionBoxes)`; retain combined normal/partial/collision boxes and caller order | Source patch and release pending; preserve temporary face bounds and replacement protocol | No migrated pack version verified; retain the companion and descriptor | @@ -539,6 +541,12 @@ freezes Et Futurum's exact four array writes and all-face placement before the A the two maps one-to-one and validates inputs, while the Java example compiles against the dev artifact without Scala or reflection. The reference checkout remains unchanged; no consumer migration, release or target-pack adoption is claimed. +Saw-strength evidence is under ignored `run/migration-saw-strength-reference/`. Baseline commit `098e747` reproduces +Iguana's boxed reflective field mutation before the API addition. The supported setter updates the same value used by +the getter, recipes and renderer without changing durability; the private field remains for old releases. Iguana's +source patch must also order its post-init before ForgeMicroblock's cached maximum calculation. The reference checkout +remains unchanged; no consumer migration, release or target-pack adoption is claimed. + Evidence for the FMP addition is under ignored `run/migration-material-enumeration-reference/`. The original reference-compiled Scala consumer still exercises the companion and tuple-array descriptor. The new compiling Java example has no Scala imports or bytecode references. Runtime checks cover initialized ID lookup and handshake order; diff --git a/JAVA_MIGRATION_DIVERGENCES.md b/JAVA_MIGRATION_DIVERGENCES.md index 4733360..5953364 100644 --- a/JAVA_MIGRATION_DIVERGENCES.md +++ b/JAVA_MIGRATION_DIVERGENCES.md @@ -191,6 +191,8 @@ These are accepted once for the migration, not repeated for every otherwise equi than synthetic Scala methods; signatures and dispatch remain available. - The private scratch `ThreadLocal` fields on `MicroblockGenerator$` and `MultipartGenerator$` lose `ACC_FINAL` so their public Scala-trait setters can still replace storage. +- The private `ItemSaw.harvestLevel` field loses `ACC_FINAL` so `setHarvestLevel(int)` can update the same storage as + the retained getter and old Iguana reflection. Its name, type and visibility remain unchanged. - TickScheduler's private Scala scheduler types become package-private static nested Java classes, retaining their binary names. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 0616195..5ee8999 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -63,21 +63,20 @@ have Java loading replacements, but consumer source changes, other reflection/ex adoption remain pending. Checkouts remain reference-only. The installed `+719` pack scan retains the `+678` floor: 27 consumers, 35 inherited types, 255 members, 76 other types and 20 strings. -**Next priority: close the Java API gaps in Phases 2 and 9 and map consumer migrations in Phase 10.** Reuse the existing -Java surface; supply missing capabilities, precise contracts, migration guidance and compiling examples. Cover -subclass/override behavior and generated extensions as well as ordinary calls. ProjectRed's illuminated microblocks -are the representative external extension case. Consumer mods may remain Scala internally while adopting this API. -The next bounded candidate is a supported saw-strength setter for Iguana, replacing its reflection into private -`ItemSaw.harvestLevel`. Other audited reflection use cases remain separate work. +**Next priority: move the completed FMP-side Java replacements into Phase 10 consumer patches and releases.** Reuse +the documented Java surface and preserve each consumer's lifecycle, state and failure policy. ProjectRed's illuminated +microblocks remain the representative external extension case. Consumer mods may remain Scala internally while +adopting this API. The next bounded source migration can replace Iguana's `ItemSaw.harvestLevel` reflection with the +supported setter and order that work before ForgeMicroblock post-init; its supplied checkout remains reference-only. Converter registration/lifecycle and stable tile capability access guidance are complete. The illuminated microblock example supplies the representative Java extension, but physical-client construction, connector-dependent halos, lighting and consumer adoption still need their recorded checks. Progress: all ten Phase 9.1 table rows and Phase 9.2's internal markers are complete, plus Schematica registry lookup, staged Java tile generation, microblock creation, typed material access, the Java illuminated extension example, slot -refresh, custom Java tile-trait authoring and button orientation mapping. Iguana's saw-strength access is the remaining -bounded FMP-side reflection replacement. Consumer patches, releases and pack adoption still precede final Scala -removal and client/pack release validation. +refresh, custom Java tile-trait authoring, button orientation mapping and saw-strength mutation. The identified +FMP-side reflection gaps now have typed replacements; consumer patches, releases and pack adoption still precede +final Scala removal and client/pack release validation. Extra Utilities remains an active supported consumer. UtilitiesInExcess is the intended replacement, but the support switch awaits approval and actual target-pack adoption. Retain existing contracts until those gates pass. The diff --git a/JAVA_MIGRATION_MANUAL_CHECKS.md b/JAVA_MIGRATION_MANUAL_CHECKS.md index 286ddd4..b8f4a53 100644 --- a/JAVA_MIGRATION_MANUAL_CHECKS.md +++ b/JAVA_MIGRATION_MANUAL_CHECKS.md @@ -76,6 +76,7 @@ entries complete. | [ ] | Load and render a schematic containing an ordered mixed multipart tile | Every part appears in the preview in the saved order; the integration does not silently disable itself | Schematica private registry-map reflection, `MicroblockClass.create`, and tile NBT reconstruction | | [ ] | Open a GuideNH scene containing a multipart tile and export its part/material data | The preview, material data and part statistics are complete | companion reflection, `MicroblockGenerator$.create`, `Microblock.microClass/material/shape`, `partList_$eq`, and `BlockMicroMaterial` mixin fields | | [ ] | Place FMP buttons on every supported face with Et Futurum loaded | Button orientation matches the fixed vanilla behavior | supported `ButtonPart.setOrientation`; legacy arrays until consumer adoption | +| [ ] | With Iguana harvest-level tweaks enabled, inspect and use the Stone, Iron, Diamond, Ardite, Cobalt and Manyullyn saws against materials spanning their configured tiers | Tooltips, saw textures and cutting recipes use the remapped tier; weaker saws do not gain the cached strongest-saw exemption | supported `ItemSaw.setHarvestLevel`; legacy field until consumer adoption | | [ ] | Use OpenComputers **3D Printer** to make a **3D Print** with different off/on shapes that both fit beside a cover; place it with the cover and right-click to toggle | Its slots are rebuilt without losing, hiding or disconnecting either part | external mutation of `TSlottedTile.v_partMap` plus `bindPart` | | [ ] | Move the same composite tile using a ProjectRed **Frame Motor** with MCFrames **Frame** blocks, then a **Matter Manipulator MKIII** in move mode | Coordinates, part-to-tile references, generated interfaces and rendering remain correct after `onMoved` | ForgeRelocationFMP / MatterManipulator live multipart move lifecycle | | [ ] | Inspect a mixed multipart tile with Waila | Providers receive every saved part ID and show the expected part data | reflected block identity and tile NBT `parts`/`id` layout | diff --git a/docs/API.md b/docs/API.md index 064b5e8..bed17a2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -30,6 +30,7 @@ Existing reflective binaries remain supported until consumer release and pack ad | Add aggregate or lifecycle behavior to generated multipart tiles | `registerTrait(marker, trait)` — [custom Java tile traits, stable capabilities and transformer constraints](api/CUSTOM_TILE_TRAITS.md) | | Refresh slots after a stored part changes shape | `refreshPartSlots(TMultiPart)` — [ownership, equality and notification responsibilities](api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) | | Add material-specific behavior to generated microblocks | `registerTrait(String)` and `IGeneratedMaterial` — [illuminated Java extension, compilation and side contracts](api/MICROBLOCK_EXTENSIONS.md) | +| Change an existing FMP saw's cutting strength | `ItemSaw.setHarvestLevel(int)` — [state, lifecycle and Iguana migration](api/SAW_STRENGTH.md) | | Read/index/search a tile's parts | `jPartList()` — [part collection ownership and order](api/PART_TRAVERSAL.md#collection-ownership-and-ordering) | | Run callbacks while skipping detached parts | `forEachPart(Consumer)` — [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) | | Rebuild parts on an already prepared composite tile | `loadPartList(Collection)` — [part loading](api/PART_LOADING.md) | @@ -117,9 +118,9 @@ ProjectRed adoption remain open. [Converter registration and lifecycle](api/BLOC tested. [Stable tile capability access](api/TILE_TRAIT_ACCESS.md) covers safe Java calls, ProjectRed redstone queries and OpenComputers slot refresh. [Custom Java tile-trait authoring](api/CUSTOM_TILE_TRAITS.md) covers registration, stable capabilities, lifecycle/state rules and transformer constraints with generated Forge coverage. Supported -[button orientation mapping](api/BUTTON_ORIENTATIONS.md) replaces Et Futurum's reflective array mutation. The Iguana -saw-strength setter remains the audited FMP-side reflection gap. ProjectRed's existing Scala traits remain supported -until adoption. +[button orientation mapping](api/BUTTON_ORIENTATIONS.md) replaces Et Futurum's reflective array mutation. Supported +[saw-strength mutation](api/SAW_STRENGTH.md) replaces Iguana's private-field access. ProjectRed's existing Scala +traits remain supported until adoption. All ten entries in the plan's Phase 9.1 API table have Java replacements. That table is a bounded list of signatures; the broader API, extension and consumer adoption work above remains open. diff --git a/docs/api/SAW_STRENGTH.md b/docs/api/SAW_STRENGTH.md new file mode 100644 index 0000000..157e55a --- /dev/null +++ b/docs/api/SAW_STRENGTH.md @@ -0,0 +1,49 @@ +# Saw cutting strength + +[Java API index](../API.md) + +`ItemSaw.setHarvestLevel(int)` changes an existing FMP saw's cutting strength without reflection. The value is read +by `harvestLevel()`, `getCuttingStrength(ItemStack)` and `getMaxCuttingStrength()`, so recipes and FMP's 3D saw +renderer observe the same updated tier. + +IguanaTweaksTConstruct can replace its private-field lookup and write with direct calls: + +```java +ItemSaw saw = (ItemSaw) item; +int oldStrength = saw.harvestLevel(); +int updatedStrength = HarvestLevelTweaks.getUpdatedHarvestLevel(oldStrength); +saw.setHarvestLevel(updatedStrength); +``` + +The [compiling example](../../src/test/java/codechicken/microblock/examples/SawStrengthExample.java) contains the +setter call. Keep FMP-typed code in an optional compatibility class loaded only after the usual mod-presence and +supported-version checks. + +## State and lifecycle + +The setter changes only cutting strength. It does not recalculate the saw's durability or alter existing item-stack +damage. This matches Iguana's current post-construction field mutation. The integer is intentionally unrestricted, +like the constructor and legacy field; the consumer owns its tier mapping. + +FMP calculates `MicroMaterialRegistry.getMaxCuttingStrength()` once during ForgeMicroblock post-initialization. +Startup integrations that add or relevel saws must finish first so the cached maximum sees the final tiers. Iguana's +optional ordering should therefore include `before:ForgeMicroblock` while retaining its existing FMP presence gate. +Call the setter on the main initialization thread, before recipes can be used. + +The method is specific to `ItemSaw`. Other `Saw` implementations may derive strength from each `ItemStack` and do +not promise mutable global strength. + +## Legacy compatibility + +The private `harvestLevel: int` field remains in place for existing Iguana releases. It is mutable so the supported +setter and legacy reflection update the same storage. New integrations should use the public getter and setter and +should not catch and ignore API failures. + +Removing the private field still requires a released Iguana migration, target-pack adoption and a fresh consumer +scan. The source patch, release and pack update are downstream work; the reference checkout was not modified. + +## Validation + +The baseline test reproduces Iguana's boxed reflective read/write on the untouched implementation. Regression tests +run both that path and the direct setter, checking the public getter, stack cutting strength, maximum saw strength and +unchanged durability. A pack with Iguana still needs the recorded cutting-tier check before release. diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index a79c4f6..89fdbf6 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -2200,3 +2200,27 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m SHA-256. Evidence: `run/migration-button-orientation-reference/`. - Next bounded task: expose supported saw-strength customization for Iguana. Consumer adoption, physical-client/full-pack checks and measured performance remain separate gates. + +### 2026-09-09 — Supported saw-strength mutation + +- Inspected IguanaTweaksTConstruct `2.7.12` at `2bc09889d3e2`. Its post-init loop reads and writes the private + `ItemSaw.harvestLevel` field with boxed reflection, then uses the changed value for cutting and tooltips. The + supplied checkout remains reference-only. +- Committed baseline `098e747` before the production change. Its JVM test reproduces that exact field access and + freezes updated getter, stack-specific cutting, maximum-strength and unchanged-durability behavior. +- Added `ItemSaw.setHarvestLevel(int)` and a compiling Java example. The setter updates the existing private field; + its name, `int` type and visibility remain for old Iguana releases. The field loses `ACC_FINAL`, recorded as an + intentional classfile divergence, so the public and legacy paths share one mutable value. +- FMP caches the process-wide maximum saw strength during ForgeMicroblock post-init. Iguana currently orders itself + after `ForgeMultipart` but not relative to `ForgeMicroblock`, while it both relevels and adds saws in post-init. + Its migration must also run before ForgeMicroblock's post-init, for example with optional `before:ForgeMicroblock` + ordering, so weaker remapped saws cannot inherit a stale strongest-saw exemption. +- Normal formatting/checkstyle/build/Forge validation passes with **575 JVM / 289 Forge** tests, zero failures, + errors or skips. The example targets Java 8 against the dev artifact without Scala or reflection, and all 150 local + API documentation links resolve. +- The packaged inventory remains **444 classes** and **17 ScalaSignature payloads**. All **3,764 existing method + bodies** are unchanged and exactly one public method is added; only the documented private-field modifier changes. + All **134 generated dumps** match the baseline by name and SHA-256. Evidence: + `run/migration-saw-strength-reference/`. +- The identified FMP-side reflection gaps now have typed replacements. Next work moves to consumer source patches, + releases and target-pack adoption, alongside the outstanding physical-client and measured-performance gates. diff --git a/src/main/scala/codechicken/microblock/ItemSaw.java b/src/main/scala/codechicken/microblock/ItemSaw.java index 4ba5569..fe0edf6 100644 --- a/src/main/scala/codechicken/microblock/ItemSaw.java +++ b/src/main/scala/codechicken/microblock/ItemSaw.java @@ -8,7 +8,7 @@ import codechicken.lib.config.ConfigTag; public class ItemSaw extends Item implements Saw { - private final int harvestLevel; + private int harvestLevel; public ItemSaw(ConfigTag sawTag, int harvestLevel) { this.harvestLevel = harvestLevel; @@ -21,10 +21,22 @@ public class ItemSaw extends Item implements Saw { setCreativeTab(CreativeTabs.tabTools); } + /** @return the current cutting strength */ public int harvestLevel() { return harvestLevel; } + /** + * Changes the cutting strength used by recipes and the saw renderer. This does not change the durability selected + * when the saw was constructed. Startup integrations that change saw tiers must finish before ForgeMicroblock + * post-initialization, when {@link MicroMaterialRegistry#getMaxCuttingStrength()} is calculated. + * + * @param harvestLevel the new cutting strength + */ + public void setHarvestLevel(int harvestLevel) { + this.harvestLevel = harvestLevel; + } + @Override public boolean hasContainerItem() { return true; diff --git a/src/test/java/codechicken/microblock/ItemSawCharacterizationTest.java b/src/test/java/codechicken/microblock/ItemSawCharacterizationTest.java index 850b292..bcb8eca 100644 --- a/src/test/java/codechicken/microblock/ItemSawCharacterizationTest.java +++ b/src/test/java/codechicken/microblock/ItemSawCharacterizationTest.java @@ -35,6 +35,7 @@ import org.objectweb.asm.tree.MethodNode; import codechicken.lib.config.ConfigFile; import codechicken.lib.config.ConfigTag; import codechicken.lib.render.CCModel; +import codechicken.microblock.examples.SawStrengthExample; class ItemSawCharacterizationTest { @@ -43,7 +44,8 @@ class ItemSawCharacterizationTest { "getContainerItem(Lnet/minecraft/item/ItemStack;)Lnet/minecraft/item/ItemStack;", "getCuttingStrength(Lnet/minecraft/item/ItemStack;)I", "harvestLevel()I", - "hasContainerItem()Z"); + "hasContainerItem()Z", + "setHarvestLevel(I)V"); private static final Set RENDERER_METHODS = signatures( "blade()Lcodechicken/lib/render/CCModel;", "handle()Lcodechicken/lib/render/CCModel;", @@ -68,7 +70,7 @@ class ItemSawCharacterizationTest { Field harvestLevel = ItemSaw.class.getDeclaredField("harvestLevel"); assertSame(int.class, harvestLevel.getType()); assertTrue(Modifier.isPrivate(harvestLevel.getModifiers())); - assertTrue(Modifier.isFinal(harvestLevel.getModifiers())); + assertFalse(Modifier.isFinal(harvestLevel.getModifiers())); assertEquals(1, ItemSaw.class.getDeclaredFields().length); assertTrue(Modifier.isPublic(ItemSawRenderer.class.getModifiers())); @@ -133,6 +135,19 @@ class ItemSawCharacterizationTest { assertEquals(maxDamage, saw.getMaxDamage()); } + @Test + void supportedSetterMatchesTheLegacyMutation(@TempDir Path directory) { + ItemSaw saw = saw(directory, "supported", 2, null); + int maxDamage = saw.getMaxDamage(); + + SawStrengthExample.updateStrength(saw, 5); + + assertEquals(5, saw.harvestLevel()); + assertEquals(5, saw.getCuttingStrength(new ItemStack(saw))); + assertEquals(5, saw.getMaxCuttingStrength()); + assertEquals(maxDamage, saw.getMaxDamage()); + } + @Test void damagesContainerOnlyWhenTheSawIsDamageable(@TempDir Path directory) { ItemSaw damageableSaw = saw(directory, "damageable", 2, 20); diff --git a/src/test/java/codechicken/microblock/examples/SawStrengthExample.java b/src/test/java/codechicken/microblock/examples/SawStrengthExample.java new file mode 100644 index 0000000..738b81f --- /dev/null +++ b/src/test/java/codechicken/microblock/examples/SawStrengthExample.java @@ -0,0 +1,14 @@ +package codechicken.microblock.examples; + +import codechicken.microblock.ItemSaw; + +/** Compiling example for docs/api/SAW_STRENGTH.md. */ +public final class SawStrengthExample { + + private SawStrengthExample() {} + + /** Applies a consumer's remapped harvest level to an existing FMP saw. */ + public static void updateStrength(ItemSaw saw, int harvestLevel) { + saw.setHarvestLevel(harvestLevel); + } +}