Mixin Guide

Mixin Configuration Guide

Purpose: Guide for configuring Mixins in Architectury multi-loader projects.

How it works: This skill is automatically activated when you mention tasks related to:

• Adding new Mixin classes
• Configuring Mixin files for Fabric or NeoForge
• Debugging Mixin-related errors (InvalidInjectionException, refMap issues)
• Setting up build configuration for Mixins

Simply describe what you want to do, and Claude will reference the appropriate guidance from this skill.

Critical: Loader-Specific Mixin Configurations (2025-12-02)

Problem: Fabric and NeoForge require different Mixin configurations due to mapping differences.

Loader-Specific Mixin Files

• Fabric: fabric/src/main/resources/chronodawn-fabric.mixins.json

  • Must include "refmap": "common-common-refmap.json"
  • Required for Mojang → Intermediary mapping conversion in production
  • Referenced in fabric.mod.json

• NeoForge: neoforge/src/main/resources/chronodawn-neoforge.mixins.json

  • Must NOT include refMap property
  • Uses Mojang mappings directly in development environment
  • Referenced in META-INF/neoforge.mods.toml

• Common: common/src/main/resources/chronodawn.mixins.json

  • No refMap property
  • Excluded from both JARs via build.gradle exclude rules
  • Kept for reference only

Adding New Mixins

When adding new Mixin classes:

1. Create Mixin class in common/src/main/java/com/chronodawn/mixin/
2. Update both loader-specific configs:
   • Add to chronodawn-fabric.mixins.json (with refMap)
   • Add to chronodawn-neoforge.mixins.json (without refMap)
3. Do NOT modify chronodawn.mixins.json (excluded from builds)

Build Configuration

Fabric (fabric/build.gradle):

processResources {
    from(project(':common').sourceSets.main.resources) {
        exclude 'chronodawn.mixins.json'  // Exclude common config
    }
}
shadowJar {
    exclude 'chronodawn.mixins.json'  // Also exclude from shadow JAR
}

NeoForge (neoforge/build.gradle):

from(project(":common").sourceSets.main.resources) {
    exclude "chronodawn.mixins.json"  // Already configured
}

Why This Separation is Necessary

• Fabric (Production): Runs with Intermediary mappings → needs refMap to translate method names
• NeoForge (Development): Runs with Mojang mappings → refMap causes InvalidInjectionException
• Root Cause: Architectury Loom generates refMap using Intermediary mappings, incompatible with NeoForge's Mojang mappings

Reference: Commit 77958c0 (fix: separate loader-specific Mixin configs)

Troubleshooting

InvalidInjectionException in NeoForge

Symptom: Mixin injection fails in NeoForge but works in Fabric.

Cause: NeoForge Mixin config includes refMap property.

Solution: Remove "refmap" from chronodawn-neoforge.mixins.json.

Mixin Not Applied

Symptom: Mixin class exists but doesn't apply at runtime.

Checklist:

1. Verify Mixin class is in chronodawn-fabric.mixins.json (for Fabric)
2. Verify Mixin class is in chronodawn-neoforge.mixins.json (for NeoForge)
3. Check Mixin config is referenced in fabric.mod.json / neoforge.mods.toml
4. Verify build excludes chronodawn.mixins.json from JARs

RefMap Missing in Production

Symptom: Fabric mod works in dev but crashes in production with refMap errors.

Cause: Missing "refmap": "common-common-refmap.json" in chronodawn-fabric.mixins.json.

Solution: Add refMap property to Fabric Mixin config.

Last Updated: 2025-12-08 Maintained by: Chrono Dawn Development Team