[Feat] Explore switching from Hyxin to MixinTale

[derrickmehaffy]

Scope

Investigate replacing Hyxin (SpongePowered Mixin bootstrap) with MixinTale as the bytecode patching framework for HyperProtect-Mixin.

1. MixinTale is purpose-built for Hytale — not a port of SpongePowered Mixin
2. Its "zero runtime dependency" model (handlers are copied into target classes) eliminates cross-classloader issues that are fundamental to how Hyxin/Sponge Mixin works on Java 21+
3. Compile-time annotation processing (mixintale.index.json) replaces runtime reflection scanning — faster startup, earlier error detection
4. Deterministic transform ordering with configurable priority, plus a fail-soft mode (report vs fatal), are both improvements over Sponge Mixin defaults
5. Mod JARs go in Mods/ instead of earlyplugins/ — MixinTale-Bootstrap is the only early plugin needed

Implementation Details

Current Hyxin surface area in HyperProtect-Mixin:

• manifest.json: "Hyxin": { "Configs": ["hyperprotect.mixin.json"] } section
• hyperprotect.mixin.json: SpongePowered Mixin config listing 22 interceptor classes
• HyperProtectConfigPlugin.java: Implements IMixinConfigPlugin (OrbisGuard coexistence, per-mixin gating)
• build.gradle: compileOnly "curse.maven:hyxin-1405491:7399430" dependency via CurseMaven
• 22 interceptor classes using SpongePowered annotations: @Mixin, @Redirect, @Shadow, @Unique, @At

MixinTale annotation mapping (SpongePowered → MixinTale):

SpongePowered Mixin	MixinTale Equivalent	Notes
@Mixin(Target.class)	@Patch(Target.class)	1:1 rename
@Redirect + @At(INVOKE)	@RedirectCall or @WrapCall	RedirectCall replaces callsite; WrapCall wraps via Operation<R>
@Shadow	@Accessor	Generates field/method access into private members
@Unique	N/A	Not needed — handlers are copied into target, no name collision risk
@Inject (HEAD)	@Prefix	Execute at method start
@Inject (RETURN)	@Postfix	Execute at method end, can modify @Result
N/A	@Replace	Full method body replacement (no Sponge equivalent without Overwrite)

Migration approach:

1. Add mixintale-api as compile dependency, mixintale-processor as annotation processor
2. Port each interceptor one-by-one — the bridge API and verdict protocol remain unchanged
3. Replace HyperProtectConfigPlugin (IMixinConfigPlugin) with MixinTale's priority/ordering system for OG coexistence
4. Replace hyperprotect.mixin.json with auto-generated mixintale.index.json
5. Update manifest.json to remove the "Hyxin" section
6. Update installation docs: MixinTale-Bootstrap in EarlyPlugins/, HyperProtect-Mixin moves to Mods/
7. Verify all 20 hooks + 22 interceptors work identically

Key concern — @Redirect equivalence:
HyperProtect-Mixin makes heavy use of @Redirect to intercept specific method calls within target methods (e.g., redirecting removeBlock() inside performPickupByInteraction()). MixinTale's @RedirectCall uses owner/name/desc + ordinal for callsite selection. Need to verify this provides equivalent precision for all 22 interceptor injection points, especially multi-redirect chains like HarvestInterceptor (5 redirects in one method).

Risks and Alternatives

Risks:

1. Redirect precision — HyperProtect-Mixin uses multi-stage @Redirect chains within single methods (e.g., HarvestInterceptor has 5 redirects in performPickupByInteraction). MixinTale's @RedirectCall callsite selection (owner/name/desc/ordinal) needs to support equivalent targeting. If ordinal selection doesn't cover all cases, some interceptors may need architectural changes.
2. OrbisGuard coexistence — Current HyperProtectConfigPlugin uses IMixinConfigPlugin.shouldApplyMixin() to disable 17 conflicting mixins when OG is detected. MixinTale's equivalent gating mechanism needs evaluation — may need to use priority ordering or conditional patching.
3. Ecosystem maturity — Hyxin uses SpongePowered Mixin which has years of battle-testing across Minecraft modding. MixinTale is newer and Hytale-specific. Bugs or edge cases in the weaver could affect server stability.
4. Breaking change for server operators — Moving from earlyplugins/ to Mods/ changes the installation workflow. Existing users would need to move their JAR.
5. MixinTale-Bootstrap still requires --accept-early-plugins — so the flag requirement doesn't go away, though server operators no longer need to place HyperProtect-Mixin itself in early plugins.

Alternatives:

1. Stay on Hyxin — The current setup works, Hyxin is stable, and SpongePowered Mixin is proven. Migration is only worth it if MixinTale's classloader isolation model solves real pain points.
2. Dual support — Maintain both Hyxin and MixinTale builds during a transition period. Adds maintenance burden but reduces risk.
3. Wait for maturity — Monitor MixinTale adoption in the Hytale community before committing. If other major mods adopt it, the ecosystem benefit increases.

References and Media

• MixinTale GitHub: https://github.com/Traktool/MixinTale
• Hyxin CurseForge: https://www.curseforge.com/hytale/mods/hyxin
• Current Hyxin dependency in build.gradle: compileOnly "curse.maven:hyxin-1405491:7399430"
• SpongePowered Mixin (upstream): https://github.com/SpongePowered/Mixin
• HyperProtect-Mixin interceptor inventory: 22 mixin classes across 7 categories (building, items, containers, combat, entities, commands/logging, interaction)

Confirmation Checklist

• I have checked the existing issues for duplicates.
• I agree to follow this project's Code of Conduct.