pixelmon-perf

Performance tuning for Pixelmon on a busy server: Pokemon far from players stop thinking, nearby Pokemon think less often, and the spawner scans fewer blocks. Players should not notice anything except a faster server.

What it does

• Proximity gate: wild Pokemon more than 48 blocks from every player run no AI at all (no pathfinding, no goal checks). Flying and airborne Pokemon are exempt, so they never fall.
• Wander: wild Pokemon look for a new wander path about every 6 seconds instead of every 1.5, and A* explores half as many nodes.
• Goal throttling: most Pixelmon AI checks run every other tick. The "avoid players" check for timid Pokemon runs once a second.
• Goal pruning: removes AI goals that can never fire (follow-trainer goals on wild Pokemon, attack goals on non-aggressive species).
• Smaller spawn scan: the normal spawner scans a 3-block radius and 15 blocks up and down instead of Pixelmon's 5 and 25. Legendary and boss spawning are not changed.
• Optional, off by default: hibernation (skip whole ticks for far-away Pokemon, keeping a slow pulse so they still despawn) and a global tick throttle.
• Never touches owned Pokemon that players have sent out when hibernation.skip_owned is on, and never touches flight-critical goals.

Server-side only.

Where it runs: events. On main it was replaced by the third-party PixelmonOptimizer, because the two overlap heavily (proximity gating, spawn scan size, goal throttling, pathfinding cost). Do not run both on one server.

How players use it

Players do not interact with this mod.

Staff guide

There are no commands. Tune it in the config and watch MSPT. The repo's benchmark tooling (bench-run in the ops repo) is the way to compare settings.

Configuration

config/pixelmonperf-server.toml. NeoForge reloads the file when it changes on disk, and the mod logs pixelmon-perf config refreshed: ... when it picks the change up. If you do not see that line, restart.

Section	Key settings	Default
wander_goal	execution_chance (higher = less often), horizontal_radius, vertical_radius	120, 10, 7
avoid_entities_goal	throttle_rate (ticks)	20
other_goals	throttle_rate (1 = off)	2
proximity_gate	enabled, range, check_interval_ticks	on, 48, 20
pathfinder	max_visited_nodes_multiplier	0.5
goal_pruning	strip_wild_owner_goals, strip_non_aggressive_target_goals, throttle_tempt_goal	all on
hibernation	enabled, range, skip_owned, despawn_pulse_ticks	off, 48, true, 60
tick_throttle	enabled, rate	off, 2
normal_spawn_slice	enabled, horizontal_slice_radius, vertical_slice_radius	on, 3, 15

tick_throttle visibly slows movement and battle response; use it only in an emergency. With hibernation on, keep despawn_pulse_ticks so far-away Pokemon still despawn.

Data and storage

None.

Troubleshooting

Symptom	Cause	Fix
Flying Pokemon fall or get stuck	A version before 1.16.0	Use 1.16.0 or later
Pokemon stand still near the edge of view	Proximity gate range smaller than the view distance players use	Raise proximity_gate.range
Fewer spawns in caves or high places	Spawn scan too small	Raise normal_spawn_slice.vertical_slice_radius
Far-away Pokemon never despawn	Hibernation on with a huge despawn_pulse_ticks	Keep it near 60
Both this and PixelmonOptimizer installed	Overlapping changes	Remove one

Boot line: pixelmon-perf v1.7.0 loaded ... config at config/pixelmonperf-server.toml (the version in this message was not updated after 1.7.0; check the jar name for the real version).

Maintainer notes

• 1.7.0 caches config values in volatile static fields. Reading ModConfigSpec values every tick was a measurable regression.
• 1.10.0 to 1.16.0 fixed gameplay problems with flight: flight-critical goals are never touched, airborne Pokemon skip the gate, and 1.16.0 removed entity-class mixins that broke flying.
• The spawn-slice mixin (PlayerTrackingSpawnerMixin) changes only the normal spawner's scan, even though Pixelmon's wild.yml values are shared with the legendary and boss spawners.
• ThrottledGoal wraps goals to run canUse() every N ticks. PlayerProximityGate staggers its checks by entity id to spread load.

Building

./gradlew build

Output: build/libs/pixelmonperf-<version>.jar.

Full command, permission and config tables: Reference.