VillagerLobotimizer

A Minecraft Paper plugin that improves server performance by turning off villagers' AI when they're confined to trading halls.

• Automatically detects when villagers are trapped in trading halls
• Disables AI for trapped villagers to improve server performance
• Maintains villager trading functionality while AI is disabled
• Automatically refreshes villager trades on a configurable schedule with randomization support
• Profession-specific restock sounds and level-up celebrations
• Optimized job site detection for better performance
• Night-time trade refresh functionality
• Allows naming villagers to control their behavior ("nobrain", "alwaysbrain")
• Debug mode for troubleshooting
• Command system for checking villager status and managing the plugin

• /lobotomy info - Shows statistics about lobotomized and active villagers
• /lobotomy debug - Shows detailed information about the villager you're looking at
• /lobotomy debug <entity> - Shows detailed information about a specific villager
• /lobotomy debug toggle - Toggles debug mode
• /lobotomy wake - Manually restores AI to the villager you're looking at
• /lobotomy reload - Reloads the configuration and applies changes to all villagers

#Configuration version - DO NOT MODIFY MANUALLY
config-version: 4

#List of names that will always keep villagers active (case-insensitive)
always-active-names:
  - "alwaysbrain"

#Interval between trapped checks, in ticks, for active villagers
check-interval: 150

#Interval between trapped checks, in ticks, for inactive villagers
inactive-check-interval: 150

#Interval between villager trade restocks, in milliseconds
restock-interval: 540000

#Range (in milliseconds) before restock-interval to start random restock checks. If set to 0, restocking is not randomized. If equal to or greater than restock-interval, restock will always occur.
restock-random-range: 0

#Whether to only lobotomize villagers with jobs
only-lobotomize-villagers-with-professions: false

#Whether to only lobotomize villagers that have been traded at least once
only-lobotomize-villagers-with-experience: false

#Whether to lobotomize villagers in boats/minecarts. Does not apply to villagers riding on non-vehicle entities like horses.
always-lobotomize-villagers-in-vehicles: false

#Whether to make lobotomized villagers silent. When enabled, villagers will be muted when their AI is disabled.
silent-lobotomized-villagers: false

#The sound to play when a villager restocks. Leave empty ("") for default sounds.
#A list of sounds can be found at https://jd.papermc.io/paper/1.21.6/io/papermc/paper/registry/keys/SoundEventKeys.html
#Use the name found in the description column, e.g. "entity.villager.celebrate" for the sound played when a villager restocks.
restock-sound: ""

#The sound played when a villager is leveled up. Leave empty ("") for no sound.
level-up-sound: "entity.villager.celebrate"

#Debug mode. Prints debug messages to the console.
debug: false

#Chunk debug mode. Prints debug messages related to chunks
chunk-debug: false

#To ignore villagers stuck in doors, set this to true.
ignore-villagers-stuck-in-doors: false

#To not lobotomize villagers surrounded by non-solid blocks, set this to true.
ignore-non-solid-blocks: false

#To check if there is a roof above a villager before lobotomizing, set this to true
check-roof: true

#Create teams for debugging purposes. This will create colored teams for inactive and active villagers. We use this to color their glowing effect.
create-debug-teams: false

#Disable the update checker. You can disable this if you don't want to be notified about updates.
disable-update-checker: false

#Disable chunk forced Villager updating. This'll disable changes to blocks in a chunk from triggering Villagers in the chunk to be updated.
disable-chunk-villager-updates: false

#Prevent trading with unlobotomized villagers. When enabled, players can only trade with villagers that have been lobotomized.
prevent-trading-with-unlobotomized-villagers: false

#Persist lobotomized state across chunk unloads. When enabled, villagers that are lobotomized will remain lobotomized when their chunk is unloaded and reloaded.
#This prevents lag spikes from villagers needing to be re-evaluated and re-lobotomized after chunk loads.
persist-lobotomized-state: true

#Enable Sentry error tracking to help developers identify and fix bugs. See "Privacy & Telemetry" section below for details.
enable-sentry: true

• Name a villager with "nobrain" to force it to always be lobotomized
• Name a villager with "alwaysbrain" to prevent it from ever being lobotomized (configurable in always-active-names)

The plugin features an enhanced sound system:

• Default restock sounds: When restock-sound is left empty, villagers will play default sounds when restocking
• Customizable sounds: You can override the default sounds by specifying a custom sound in the configuration
• Sound reference: A complete list of available sounds can be found in the Paper API documentation
• Level-up celebrations: Villagers play celebration sounds when they level up their trades

This plugin uses two services to help improve quality and fix bugs:

The plugin uses bStats to collect anonymous usage statistics, including:

• Number of servers using the plugin
• Number of players on those servers
• Server software (Paper, Purpur, etc.)
• Plugin version distribution

This data helps us understand how the plugin is used and prioritize development efforts. All data is anonymous and publicly viewable at bStats Plugin Page.

Opt-out: You can disable bStats globally in plugins/bStats/config.yml by setting enabled: false.

The plugin uses Sentry to automatically report errors and exceptions, helping developers identify and fix bugs proactively.

What data is collected:

• Exception stack traces and error messages
• Server type and version (Paper, Purpur, Folia, etc.)
• Minecraft version, Bukkit API version, and Java version
• Plugin version
• Thread information and task scheduling context

What data is NOT collected:

• Player names, UUIDs, or any player-identifiable information
• Chat messages or commands
• World data, coordinates, or block information
• Server IP address or hostname
• Any personally identifiable information (PII)

All error data is anonymized and used solely for debugging purposes.

Opt-out: Set enable-sentry: false in config.yml to disable error reporting.

• Paper (or its forks) 1.21.6+
• Java Development Kit (JDK) 21 for development

1. Download the latest release from Modrinth, Hangar, or CurseForge
2. Place the .jar file in your server's plugins folder
3. Restart your server or use a plugin manager to load the plugin
4. Configure the plugin settings in plugins/VillagerLobotimizer/config.yml if needed

• Java Development Kit (JDK) 21
• Gradle (wrapper included)

1. Clone the repository

   git clone https://github.com/mja00/VillagerLobotimizer.git
   cd VillagerLobotimizer

2. Build the plugin

   ./gradlew build

   The built plugin will be in build/libs/VillagerLobotimizer-<version>.jar

The project uses the run-paper plugin to easily test changes:

./gradlew runServer

This will download a Paper server for Minecraft 1.21.5 and start it with the plugin installed.

You can publish to Hangar, Modrinth, and CurseForge using the same shaded artifact built by shadowJar.

• Hangar:

  ./gradlew publishPluginPublicationToHangar

  Requires HANGAR_API_KEY in the environment. The task auto-detects whether the current commit is tagged to decide Release vs Snapshot.

• Modrinth:

  ./gradlew modrinth

  Requires MODRINTH_TOKEN in the environment. Optionally set the project id/slug via Gradle property:

  ./gradlew modrinth -Pmodrinth.projectId=villagerlobotomy

  Game versions are published for 1.21.6, 1.21.7, and 1.21.8. Tagged commits publish a Release; otherwise a Snapshot-like Beta with a short git hash suffix.

• Publish everywhere (Hangar + Modrinth):

  ./gradlew publishAll

• CurseForge:

  CURSEFORGE_TOKEN=… \
  CURSEFORGE_GAME_VERSIONS="1.21.11,26.1,26.1.1,26.1.2,26.2,26.3" \
  CURSEFORGE_JAR="$(ls build/libs/VillagerLobotimizer-*.jar)" \
  ./scripts/publish-curseforge.sh

  CurseForge is published by scripts/publish-curseforge.sh, not Gradle: project 1601723 only accepts CurseForge's legacy flat "Minecraft" version list (typeID 1), which the CurseForgeGradle plugin cannot emit. The script resolves those IDs and uploads via the API. Keep CURSEFORGE_GAME_VERSIONS in sync with modrinthGameVersions in build.gradle.kts. In CI the release workflow runs this automatically (Release on a tag, otherwise Beta).

If you encounter any issues, please report them on GitHub.

This project is licensed under the MIT License - see the LICENSE file for details.