Villager Cycle

A Quality of Life mod for Minecraft Fabric that adds a button to villager trading screens, allowing you to refresh their trades before making any purchases.

Features

• Cycle Trades Button: Customizable button above the villager trading GUI
• Draggable Button Position: Reposition the button via drag screen
• Real-Time Updates: Trade offers refresh instantly without closing the GUI
• Keybind Support: Keyboard and mouse button bindings for all mod functions
• Configurable Cycle Limits: Set limits on how many times trades can be cycled (per villager)
• Wandering Trader Support: Optional feature (operator-controlled on servers)
• Smart Validation: Only works on valid villagers (must have profession, not traded with)
• Server-Side Security: All validation happens server-side
• Anti-Exploit Protection: Clears trade input slots to prevent item duplication

Installation

1. Download from Releases
2. Place .jar in your .minecraft/mods folder
3. Required: Fabric API (version matched to your MC version)
4. Recommended: Cloth Config 20.0.149+ (enhanced config UI, not available for MC 26.1)
5. Recommended: ModMenu 16.0.0+ (in-game config access)
6. Launch Minecraft with Fabric Loader 0.18.4+

How to Use

1. Open a villager's trading interface
2. Click the "Cycle Trades" button (or use the keybind)
3. The villager's Level 1 trades will regenerate with new offers

Configuration

Config File Location

• Windows: %appdata%\.minecraft\config\villagercycle.json
• macOS: ~/Library/Application Support/minecraft/config/villagercycle.json
• Linux: ~/.minecraft/config/villagercycle.json

Options

{
  "enableCycleButton": true,
  "allowWanderingTraders": false,
  "showSuccessMessage": true,
  "showWanderingTraderSuccessMessage": true,
  "villagerCycleLimit": -1,
  "wanderingTraderCycleLimit": 1,
  "buttonOffsetX": 6,
  "buttonOffsetY": -25,
  "buttonWidth": 100,
  "buttonHeight": 20
}

| Option | Default | Description |
|--------|---------|-------------|
| enableCycleButton | true | Show/hide the cycle button |
| showSuccessMessage | true | Show villager cycle success message (client-side) |
| showWanderingTraderSuccessMessage | true | Show wandering trader success message (client-side) |
| allowWanderingTraders | false | Enable wandering trader cycling (operator only on servers) |
| villagerCycleLimit | -1 | Max cycles per villager: -1=unlimited (operator only on servers) |
| wanderingTraderCycleLimit | 1 | Max cycles per wandering trader: -1=unlimited (operator only on servers) |
| buttonOffsetX/Y | 6/-25 | Button position offset from GUI |
| buttonWidth/Height | 100/20 | Button dimensions (pixels) |

Keybinds

All keybinds are unbound by default. Set them in Options → Controls → Villager Cycle.

Supports both keyboard keys and mouse buttons (e.g., Mouse Button 4/5).

| Keybind | Function |
|---------|----------|
| Toggle Button Visibility | Show/hide the cycle button |
| Open Button Position Screen | Open drag screen to reposition button |
| Open Config Screen | Open the mod configuration screen |
| Reload Config File | Reload config from disk |
| Cycle Trades | Cycle trades while in merchant screen (keyboard or mouse) |

Singleplayer vs Multiplayer

• Singleplayer: All features available with full control over all settings.
• Multiplayer: Operator permission (level 4) required for:
  • Allow Wandering Traders toggle
  • Villager Cycle Limit
  • Wandering Trader Cycle Limit

Success message toggles are client-side — each player controls their own preference.

Limitations

• Only works on villagers not yet traded with
• Only works on villagers with valid professions (not Nitwits/Unemployed)
• Only refreshes Level 1 trades (experience level 0)
• Items in trade slots are returned to inventory when cycling

Technical Requirements

• Minecraft: 1.21.9, 1.21.10, 1.21.11, or 26.1
• Fabric Loader: 0.18.4+
• Java: 21+ (Java 25+ for MC 26.1)
• Fabric API: Required (version matched to your MC version)
• Cloth Config: Optional, recommended (not available for MC 26.1 as of late)
• ModMenu: Optional, recommended

License

MIT License — Free to include in modpacks.

Support

Open an issue on GitHub for bugs or suggestions.

Author

Created by Partacus-SPQR