docs: add consumer recompile release notes

This commit is contained in:
Algent committed 2026-09-09 15:58:22 +02:00
1 parent ec0c8a1ed0
commit 3a5f3a3b8d
2 files changed
+114

No files matched your search

+4
View File
@@ -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
+110
View File
@@ -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.