Explosion-Overhaul/docs/agent-handoff.md

# Agent Handoff

## Current State

The repository now contains a private NeoForge `21.1.225` / Minecraft `1.21.1` porting scaffold for Explosion Overhaul.

The Gitea runner has been used for:

- decompiling the upstream Forge `0.2.3.0` jar,
- publishing the decompiled output to `runner/decompiled-upstream`,
- running repeated NeoForge builds on `main`.

## Changes Made

- Added `.gitea/workflows/decompile.yml` to decompile the upstream jar on the runner.
- Added `.gitea/workflows/build.yml` to build with Java 21 on the runner.
- Added NeoForge ModDevGradle scaffold files.
- Imported decompiled Java sources under `src/main/java`.
- Imported upstream assets and resources under `src/main/resources`.
- Added `src/main/templates/META-INF/neoforge.mods.toml`.
- Applied first mechanical package migration from Forge packages to NeoForge packages.
- Repaired CFR control-flow artifacts in:
  - `AsyncCraterManager`
  - `BlockIndexManager`
- Updated the `ExplosionMixin` complex constructor injection descriptor for Minecraft `1.21.1` after a client bootstrap crash showed the old Forge `1.20.1` constructor target no longer exists.
- Updated `GameRendererBlurMixin` render callback and invoke descriptors for Minecraft `1.21.1` after the next client crash showed `GameRenderer#render` now receives `DeltaTracker, boolean`.
- Replaced client tick subscriber parameters that used the temporary `compat.TickEvent.ClientTickEvent` placeholder with NeoForge `ClientTickEvent.Post` after mod loading rejected non-Event subscriber parameters.
- Updated `ChannelLowpassMixin` to shadow `Channel#source` instead of the old obfuscated `f_83642_` field after the sound engine failed to apply the mixin.
- Fixed runner setup issues:
  - executable `gradlew`
  - tracked `gradle-wrapper.jar`
  - CurseMaven exclusive dependency lookup

## Verification

| Check | Result |
| --- | --- |
| `git diff --check` | PASS before last committed source fixes |
| `git diff --check` | PASS after NeoForge `21.1.225` metadata change and `ExplosionMixin` runtime crash fix |
| `git diff --check` | PASS after `GameRendererBlurMixin` runtime crash fix |
| `git diff --check` | PASS after client tick subscriber event migration |
| `git diff --check` | PASS after `ChannelLowpassMixin` source field migration |
| Gitea decompile workflow | PASS |
| Gitea build workflow | FAIL, now reaches Java API migration errors |

Latest checked build:

```text
Run ID: 165
Job ID: 166
Conclusion: failure
```

## Current Build Blockers

The remaining failures are real Forge-to-NeoForge/API-porting work, not runner setup:

- `RenderGuiOverlayEvent` no longer exists in the same form.
- `NetworkEvent.Context`, `NetworkRegistry`, and `SimpleChannel` need migration to NeoForge's 1.21 networking API.
- `ConfigScreenHandler` needs migration to the NeoForge config screen registration API.
- `DistExecutor` imports need replacement/removal for NeoForge 1.21.
- `@Mod.EventBusSubscriber` needs migration to NeoForge's event subscriber annotation.
- `ForgeRegistries` / `RegistryObject` usage needs migration to the modern NeoForge registry holders.

## Next Steps

1. Migrate registry classes first (`ModSounds`, `ModBlocks`, `ModItems`, `ModParticles`, `ModBlockEntities`, creative tabs).
2. Migrate packet registration and all packet handlers away from Forge `SimpleChannel` / `NetworkEvent.Context`.
3. Replace GUI overlay events and config screen registration.
4. Re-run the Gitea build after each API family rather than attempting all files at once.
5. Retest the client jar after the `ExplosionMixin` descriptor fix; the next crash, if any, should be a later runtime/API issue rather than the bootstrap constructor mismatch.
6. Retest the client jar after the `GameRendererBlurMixin` descriptor fix; the next crash, if any, should be the next stale mixin/API target.
7. Retest the client jar after the client tick event migration; the next crash, if any, should be a later mod-loading/runtime issue.
8. Retest the client jar after the `ChannelLowpassMixin` source field migration; watch for remaining audio mixin/accessor issues.

## Risks

- This is decompiled, All Rights Reserved upstream code. Keep the repo private and do not publish builds without permission.
- The port is large: after compile succeeds, runtime testing in a real NeoForge client will still be required for explosions, scan UI, audio effects, shaders, and mixins.