From 3a5f3a3b8dca1f2e7c0b14420d7d0942accb3d4a Mon Sep 17 00:00:00 2001 From: Algent Date: Wed, 9 Sep 2026 15:51:14 +0200 Subject: [PATCH] docs: add consumer recompile release notes --- docs/API.md | 4 ++ docs/RELEASE_NOTES.md | 110 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/RELEASE_NOTES.md diff --git a/docs/API.md b/docs/API.md index bed17a2..0ca5f0d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -8,6 +8,10 @@ Consumers can use the Java surface without importing Scala types. FMP still reta compatibility bridges, and some extension contracts still need migration. A Scala-authored mod can adopt the Java API without converting the rest of its code to Java. +**Rebuilding an existing mod against this branch? Read the [release notes](RELEASE_NOTES.md) first.** Shipped binaries +keep working, but recompiling has three classes of break, and the trait-composition one compiles cleanly and changes +behavior at runtime. + ## Direct calls and optional integration The intended consumer API uses direct typed public calls, without reflection, private-field mixins or Scala diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md new file mode 100644 index 0000000..c0115f8 --- /dev/null +++ b/docs/RELEASE_NOTES.md @@ -0,0 +1,110 @@ +# Release notes — the Java port + +ForgeMultipart's implementation moved from Scala to Java. This page is for mod authors who depend on FMP. + +**If you ship a compiled jar and do not rebuild it, nothing here affects you.** Every runtime interface, method +descriptor and reflective name the audited consumers use was preserved deliberately, and the retained Scala bridges +still link. The compatibility ledger for what did change is [JAVA_MIGRATION_DIVERGENCES.md](../JAVA_MIGRATION_DIVERGENCES.md). + +**If you rebuild against the new dev jar, read on.** Recompiling is the case that breaks, and one class of break is +silent. There are three kinds, in descending order of how badly they fail. + +## 1. Linkage errors: the generated tile traits + +Six types were Scala traits, which compile to an interface plus a `$class` helper. They are now concrete Java classes +in the dev jar. Forge's transformer rewrites them back into interfaces at load time, so **existing binaries are +unaffected** — they already call interface methods, and the runtime type is still an interface. + +Source compiled against the untransformed dev jar is the problem. `javac` and `scalac` see a class, emit +`invokevirtual` or `getfield`, and the JVM then rejects it against the runtime interface. + +| Type | Recompiled call fails with | +| --- | --- | +| `scalatraits.TRedstoneTile` | `IncompatibleClassChangeError` | +| `scalatraits.TSlottedTile` | `NoSuchFieldError` on `v_partMap` | +| `scalatraits.TTileChangeTile` | `IncompatibleClassChangeError` | +| `scalatraits.TFluidHandlerTile` | `IncompatibleClassChangeError` | +| `scalatraits.TRandomDisplayTickTile` | `IncompatibleClassChangeError` | +| `TileMultipartClient` | `IncompatibleClassChangeError` | + +**The fix is to target the stable capability interface instead of the raw dev-jar class.** These are supported, have +unchanged binary shapes, and work on both the old and new FMP: + +Note the package: the types that break are in `codechicken.multipart.scalatraits`, the replacements are not. + +| Instead of | Use | +| --- | --- | +| `scalatraits.TRedstoneTile.openConnections(side)` | `codechicken.multipart.IRedstoneTile.openConnections(side)` | +| casting to `scalatraits.TSlottedTile` and writing `v_partMap` | `codechicken.multipart.TileMultipart.refreshPartSlots(part)` | +| reading `scalatraits.TSlottedTile.partMap(slot)` | `codechicken.multipart.TileMultipart.partMap(slot)` | + +`refreshPartSlots` clears value-equal entries from the live array and dispatches the bind chain once. Keep your own +validation and state change before the call, and your sound, notification, description and scheduling order after it. +See [stable tile capability access](api/TILE_TRAIT_ACCESS.md) for the full contract and worked examples. + +### Known affected consumers + +Confirmed still present on each project's default branch: + +| Mod | Call site | Member | +| --- | --- | --- | +| ProjectRed | `transmission/redwires.scala` | `TRedstoneTile.openConnections` | +| OpenComputers | `integration/fmp/PrintPart.scala` | `TSlottedTile.v_partMap` | + +`TTileChangeTile`, `TFluidHandlerTile` and `TRandomDisplayTickTile` have no known consumer references. + +## 2. Silent behavior changes: recompiled Scala trait composition + +**This is the dangerous one — it compiles cleanly and does the wrong thing at runtime.** + +A Java interface cannot supply a Scala trait's class supertype or its linearization. When a superclass method and an +interface default both apply, the superclass wins. So recompiling `extends TMultiPart with TCuboidPart` silently +selects `TMultiPart`'s empty methods instead of the cuboid implementations, and your part loses its collision boxes +rather than failing to build. + +Where the implementation is now an interface default, forward explicitly: + +| Trait | What to do when recompiling | +| --- | --- | +| `TCuboidPart` | Extend `JCuboidPart`, or forward subparts, collision boxes and breaking rendering to its statics | +| `TNormalOcclusion` | Combine `NormalOcclusionTest.apply(this, other)` with the intended super chain explicitly. Audit existing `super.occlusionTest` calls: they no longer route through the old trait | +| `TIconHitEffects` | Forward `addHitEffects` and `addDestroyEffects` to `IconHitEffects` | +| `TItemMultiPart` | Forward `onItemUse` to `JItemMultiPart`; the inherited `Item` method otherwise wins | +| `TRandomUpdateTick` | Implement `onWorldJoin` as `TickScheduler.loadRandomTick(this)` | +| `TScheduledPacketPart` | Forward `read` to `TScheduledPacketPart.readMask(this, packet)` | +| `ScratchBitSet` | Implement both methods and the storage accessors, and initialize storage explicitly | + +Previously compiled calls into **retained** `$class` bridges still link; this applies only to recompilation. + +## 3. Compile errors: Scala source syntax + +These fail loudly at build time, so they are the safe category. Existing bytecode keeps working. + +- An `object` used as a value needs `X$.MODULE$` where the companion is retained. Static forwarders alone do not + supply a singleton value. +- Application sugar becomes an explicit `.apply(...)`, e.g. `NormalOcclusionTest.apply(...)`. +- `x.partList(i)` becomes `x.partList.apply(i)`. +- Scala property assignment needs the Java `_$eq(...)` method, e.g. `renderID`, `loadingWorld`, microblock `shape`. +- `Tuple2` members typed `Boolean` in Scala arrive as `Object` and need a cast. +- Scala 2.11 will not adapt a lambda to `Function1[_, BoxedUnit]`, so `operate { p => ... }` needs an explicit + `AbstractFunction1`. Prefer the Java `forEachPart(Consumer)` entry point. +- The Face, Corner, Edge and Post bounds facades are Java static array getters now, so they need an extra empty + argument list before the index. +- `ByteCodeReader.advance(length)(value)` becomes `advance(length, value)`. +- `ASMImplicits` no longer provides implicit or value-class syntax; call the retained `$extension` entry points + explicitly. +- `ASMMixinFactory` constructor and `construct` arguments need an explicit Scala `Seq`, not varargs. + +One runtime trap that is not a compile error: **do not call a side-only Scala object's static facade from common +Java.** `MultipartProxy.postInit()` exists in the raw jar but inherits `@SideOnly(CLIENT)`, so Forge strips the +forwarder on a dedicated server and the call fails with `NoSuchMethodError`. Call `MultipartProxy$.MODULE$.postInit()` +as the Scala reference did. + +## Adopting the Java API + +You do not have to convert your mod to Java. A Scala mod can call the Java surface directly, and the documented +entry points compile with no Scala on the classpath. Start at the [Java API index](API.md). + +Direct typed calls are the intended end state. Reflection snippets in older guides are legacy interoperability +options, not the migration target. For optional integration, isolate FMP-typed code in a compatibility class loaded +only after mod-presence and version checks, and test both the absent and present cases.