# Test Mod Transform

> Test that Retromod correctly transforms mods for a target Minecraft version. Use when verifying transforms work, testing new shims, or debugging mod compatibility. Use when this capability is needed.

- Skill: `tomevault-io/test-mod-transform` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/test-mod-transform`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/test-mod-transform/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/test-mod-transform

---


# Test Mod Transform

Systematically test that Retromod transforms and loads mods correctly.

## Quick Test Flow

1. **Get test mods.** Download from Modrinth API or use existing mods:
   ```bash
   # Search Modrinth
   curl -s 'https://api.modrinth.com/v2/search?query=<name>&facets=%5B%5B"categories:<loader>"%5D%5D'

   # Get versions
   curl -s 'https://api.modrinth.com/v2/project/<slug>/version?loaders=%5B"<loader>"%5D&limit=5'

   # Download
   curl -sL -o mod.jar "<download-url>"
   ```

2. **Analyze with CLI**:
   ```bash
   mvn -f pom.xml exec:java -Dexec.mainClass="com.retromod.cli.RetromodCli" \
     -Dexec.args="analyze '/path/to/mod.jar'" -q
   ```
   Check: Mod ID, Target MC, Mod Loader, Complexity Score

3. **Transform with CLI**:
   ```bash
   mvn -f pom.xml exec:java -Dexec.mainClass="com.retromod.cli.RetromodCli" \
     -Dexec.args="batch '/path/to/mods-folder' --aot" -q
   ```

4. **Verify metadata patching.** Extract and check the patched metadata:
   ```bash
   # For NeoForge/Forge
   jar xf transformed.jar META-INF/neoforge.mods.toml
   grep -A5 '"minecraft"' META-INF/neoforge.mods.toml

   # For Fabric
   jar xf transformed.jar fabric.mod.json
   cat fabric.mod.json | python3 -m json.tool
   ```

5. **Runtime test.** Deploy and launch:
   - Copy mod to `retromod-input/` in game directory
   - Launch with the target MC version + loader
   - Check `logs/latest.log` for Retromod transform messages
   - Check if the mod appears in the mod list
   - Check for crashes in the log

## What to Verify

### Metadata Patching
- [ ] Minecraft version constraint accepts the target version
- [ ] Non-core dependencies are optional (won't crash if missing)
- [ ] Forge/NeoForge version range is permissive
- [ ] Fabric API constraint is `"*"`

### Bytecode Transform
- [ ] No `NoSuchMethodError` at runtime
- [ ] No `NoClassDefFoundError` at runtime
- [ ] No `AbstractMethodError`
- [ ] Mod features work (GUI, blocks, items, etc.)

### Mixin Compatibility
- [ ] No `MixinApplyError` about missing targets
- [ ] Mixin config JSON has correct entries

## Game Directories

- **macOS**: `~/Library/Application Support/minecraft/`
- **Linux**: `~/.minecraft/`
- **Windows**: `%APPDATA%/.minecraft/`

### Folder Structure
```
.minecraft/
├── mods/
│   ├── retromod-1.0.0-rc.1+26.1.jar    (Retromod itself)
│   ├── retromod-input/                      (Drop old mods here)
│   │   ├── old-mod-1.20.jar
│   │   └── processed/                       (Originals moved here after transform)
│   ├── retromod-backups/                    (Backups of in-place transforms)
│   └── retromod-output/                     (CLI batch output)
├── versions/
│   ├── fabric-loader-0.18.4-26.1-pre-2/
│   └── neoforge-26.1.0.0-alpha.6+snapshot-2/
├── logs/
│   └── latest.log                           (Check for [Retromod] messages)
└── config/
    └── retromod/
        ├── config.json
        └── aot-cache/
```

## Good Test Mods by Complexity

### Simple (should always work)
- MouseTweaks, AppleSkin, Dynamic FPS, Mod Menu (old versions)

### Medium (usually works)
- Jade/HWYLA, Lithium, NoChatReports, NotEnoughCrashes

### Complex (may need force_translate_complex)
- JEI, Sodium, Iris, VoiceChat, Create, Waystones

### Cross-version (tests shim chains)
- Sodium 1.16.5 (tests 1.16→...→26.1 chain)
- Lithium 1.18.2 (tests 1.18→...→26.1 chain)
- Iris 1.20.6 (tests 1.20→...→26.1 chain)

## Important Notes
- Always keep the original mod JAR. Transforms are one-way
- Use `force_translate_complex: true` in config for complex mods
- The CLI `aot --force` flag overrides complexity warnings
- NeoForge mods already use Mojang names. They mainly need metadata patching, not bytecode transforms
- Fabric mods need intermediary→Mojang name remapping for 26.1+

---
> Source: [Bownlux/Retromod](https://github.com/Bownlux/Retromod) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-29 -->