DeerFolia · Entity throttling

What the file controls

The Kaiiju entity throttler reads config/kaiiju-entity-throttling.yml. For each selected entity type, the file sets a normal update limit and a removal threshold in each Folia region:

• Entities at or below limit keep normal per-tick updates.
• Entities above limit still exist. The throttler skips some updates.
• Entities above removal are removed over time.
• Entity types that are not in the file are not limited by this file.

The count is per region. It is not a server-wide count across all worlds. Folia regions change with player and chunk activity. This file is not a global mob cap.

Default format

The core creates a file similar to this when you enable the feature for the first time:

ZombifiedPiglin:
  limit: 1000
  removal: 3000

Axolotl:
  limit: 1000
  removal: 3000

Each entity type is a named section. Use a name printed in the core startup log. Examples include ZombifiedPiglin, Axolotl, Villager, IronGolem, Item, and ExperienceOrb. Match the capitalization. Do not add a Minecraft namespace, underscores, or an Entity suffix.

Fields

Field	Requirement	Meaning
limit	At least 1	Number of that entity type in one region that keeps normal per-tick updates.
removal	-1 or greater than limit	Start gradual removal above this count. -1 disables removal by this threshold but keeps throttling.

If removal is less than or equal to limit and is not -1, startup logs an error. The core replaces it with limit * 10. Set a valid value instead of relying on this correction.

Tuning a farm

Entity throttling can affect AI, movement, pickup, breeding, attacks, and drops. Tune one use case at a time:

1. Add an entry only for an entity type that creates pressure in the target region.
2. Set limit to the count required by the test area.
3. Set removal well above limit to allow short peaks.
4. Observe entity count, CPU, TPS, and farm output for 10–20 minutes.
5. Remove the entry or disable the master switch when behavior is wrong.

Do not give Villager, Item, Player, or every mob a very low limit to reduce CPU. Trading halls, item sorters, farms, and player actions can make a healthy server look overloaded.

Errors and rollback

• The core logs and skips unknown entity names.
• The core ignores limits below 1.
• A YAML syntax error prevents normal loading.
• Restart the complete server after every change.
• Restore the whole file when you roll back. Do not delete one error line and continue with an unknown state.

If you are unsure whether to limit an entity, set kaiiju-entity-throttling to false in deer-folia.yml. Check whether the symptom disappears. Restore one tested entry at a time.