DeerFolia · Configuration

File structure

Use the following structure as a reference. The server adds comments to the generated file. If the generated file contains a different key, follow the generated file.

dynamic-activation-brain:
  enabled: true
  start-distance: 12
  activation-distance-mod: 8
  maximum-activation-prio: 20

async-pathfinding:
  enabled: true
  async-pathfinding-keep-alive: 60
  async-pathfinding-max-threads: 20

kaiiju-entity-throttling: true

network-optimizations:
  optimized-var-int: true
  optimized-frame-encoding: true

lithium-optimize:
  enabled: true
  allocations: true
  ai: true
  collections: true
  entity: true
  math: true
  world: true

poi-optimizations:
  enabled: true
  golem-spawn-check-interval: 200
  secondary-poi-sensor-interval: 80
  village-distance-cache-duration: 100
  golem-spawn-player-distance-limit: 128

afk-network-optimization:
  enabled: true
  afk-threshold-ticks: 1200
  afk-enter-message: "&7[AFKNet] &eYou are now AFK. &7DeerFolia will temporarily suppress non-essential packets to save bandwidth."
  afk-exit-message: "&7[AFKNet] &aWelcome back! &7During this AFK session, you saved &b{saved_traffic} &7of traffic and up to &b{saved_bandwidth} &7of bandwidth. &aThanks for helping the server save costs!"
  count-look-changes-as-activity: true
  resync-on-resume: true
  stats-enabled: true
  suppression-whitelist-categories: []
  max-suppressed-bytes-before-category-resync: -1

Dynamic Activation of Brain

This group makes distant entities update their AI less often. It reduces work when no player is observing the area.

Key	Default	Meaning
enabled	true	Master switch. Set it to false to use the upstream activation cadence.
start-distance	12	Distance at which activation frequency begins to fall.
activation-distance-mod	8	Distance-decay parameter. A lower value reduces distant-entity work earlier or more strongly.
maximum-activation-prio	20	Maximum interval. A distant entity is evaluated at least once every 20 ticks.

If a mob farm, villager hall, or redstone machine shows delay, lower activation-distance-mod or increase start-distance. Change one value at a time. Test the affected area.

Async Pathfinding

This group runs selected pathfinding work in asynchronous tasks. It reduces the chance that pathfinding blocks the current region tick.

Key	Default	Meaning
enabled	true	Master switch for async pathfinding.
async-pathfinding-keep-alive	60	Maximum active lifetime of a path task, in ticks.
async-pathfinding-max-threads	20	Async path pool size. DeerFolia uses virtual threads. The value does not reserve one physical core per thread.

Start with 10–20 threads. Too few threads can queue work. Too many threads can increase scheduling and GC pressure. If pathfinding is unstable or CPU or GC usage changes sharply, lower the pool size first. Restart after changing these options.

Kaiiju Entity Throttling

kaiiju-entity-throttling is the master switch. See Entity throttling for the file format. When the value is false, DeerFolia does not use limits in kaiiju-entity-throttling.yml. You can keep the file for later use. Test each limit before you add it.

Network Optimizations

This group has no separate enabled switch:

Key	Default	Effect
optimized-var-int	true	Optimize VarInt reads and writes for packet length fields.
optimized-frame-encoding	true	Optimize network frame encoding and reduce outbound preparation work.

These options affect internal packet handling. They should not change player-facing features. If a proxy, compression plugin, or protocol problem appears, disable one option at a time on a test copy.

Lithium Optimize

This group uses selected Lithium server optimizations. It adapts them to Folia’s region-threaded model. enabled is the master switch. The other keys select groups:

Key	Main purpose
allocations	Reduce temporary allocations in frequently called paths.
ai	Optimize entity AI iteration.
collections	Use lighter collection access in entity attribute paths.
entity	Skip unnecessary entity work and client-only particle logic.
math	Use simpler math paths that the JVM can optimize.
world	Optimize world generation, weather, and freeze paths.

Restart the server after changing any option in this group. These options are not the complete Lithium feature set. They do not replace optimizations from Paper, Folia, or Moonrise. If entity, redstone, or weather behavior is wrong, set enabled to false on a test server before you change sub-options.

POI Optimizations

This group changes villager Point of Interest checks. The values use ticks or blocks:

Key	Default	Meaning
enabled	true	POI optimization master switch.
golem-spawn-check-interval	200	Minimum interval between iron golem checks for one villager.
secondary-poi-sensor-interval	80	Minimum interval between secondary POI scans.
village-distance-cache-duration	100	Village-distance cache duration.
golem-spawn-player-distance-limit	128	Skip part of the golem check when no player is within this distance.

For a large villager area, start with the defaults and observe CPU usage. If an iron farm or workstation area depends on timing, lower the relevant interval or set enabled to false for a comparison.

AFK Network Optimization

When a player is inactive for the configured time, DeerFolia suppresses selected non-essential clientbound packets. It resynchronizes required state when the player becomes active. This saves bandwidth. It does not stop world logic for the player.

Key	Default	Meaning
enabled	true	AFK network suppression master switch.
afk-threshold-ticks	1200	Enter AFK after this number of inactive ticks.
count-look-changes-as-activity	true	Treat look-only rotation as activity.
resync-on-resume	true	Resend nearby chunks and tracked entities when activity resumes. Keep this enabled.
stats-enabled	true	Accumulate data used by /afknetstats.
suppression-whitelist-categories	[]	Categories that still pass while AFK.
max-suppressed-bytes-before-category-resync	-1	Per-player, per-category byte threshold. -1 disables forced refresh before activity resumes.

The supported categories are:

• chunk-stream: chunks, light, and chunk-batch data;
• block-updates: block, multi-block, and block-entity updates;
• entity-stream: entity creation, movement, metadata, equipment, and attributes;
• world-effects: sounds, particles, explosions, and world events;
• ui-stream: BossBar, Title, TabList, scoreboard, map, and other UI synchronization.

Use the lower-case keys in suppression-whitelist-categories. Startup normalizes case, removes duplicates, and ignores unknown categories.

Entry and exit messages support legacy colors such as &7 and &a and hex colors such as &#55FFFF. Use these placeholders:

Placeholder	Available in	Meaning
{player}	entry and exit	Player name.
{saved_traffic}	exit	Traffic saved during the AFK session.
{saved_bandwidth}	exit	Peak bandwidth saved during the AFK session.

Clear a message value to disable that notification. An administrator can view totals with:

/afknetstats
/afknetstats <player>

The command requires administrator permission. If a player sees a short desynchronization, check that resync-on-resume is true before you add categories to the whitelist.