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