Kinetic is a performance and gameplay optimizer for Paper servers (1.21+).
It reduces lag by intelligently pacing AI, merging entities, throttling packets, and streamlining server mechanics — all without requiring forks or coremods.
Some features optionally integrate with ProtocolLib for advanced packet handling. If ProtocolLib is not present and protocollib-required is enabled in the config, packet-level modules are automatically disabled.
Key Features
-
Entity, Item, and XP Merging
- Configurable stack sizes per mob type, material, or XP orb.
- Optional holograms showing
{amount}, {name}, {material}, {type}.
- Supports per-player culling so holograms vanish with their owners.
-
Dynamic AI Budgeter (DAB)
- Distance- and priority-aware AI pacing.
- TPS adaptation and jitter injection to prevent lag spikes.
- Hard-freeze system for entities far from players, with FOV/LOS heuristics.
-
Spawn Controls
- Soft per-chunk caps by category.
- TPS guards to deny spawns when the server dips below thresholds.
- Far-distance denial for spawns beyond player activity zones.
-
Hopper & Block Optimizations
- Batch hopper moves with per-tick caps.
- Slow down fluid updates, plant growth, leaf decay, and piston actions when far from players.
-
Packet Throttling (ProtocolLib required)
- Hide far entities, throttle sounds and particles, pace chunk streaming, idle compression.
- Reduce client load while preserving gameplay correctness.
-
Plugin-Only Entity Culling
- Uses
Player#hideEntity/showEntity with per-tick budgets.
- Hologram integration ensures consistency per player.
How It Works
| Subsystem |
Goal |
Techniques |
| Merging |
Reduce entity counts |
Merge mobs, items, and XP; configurable stack sizes and holograms |
| AI Budgeting |
Smooth per-tick load |
Distance weighting, action multipliers, TPS scaling, jitter, freezing |
| Spawns |
Prevent runaway entities |
Per-chunk caps, TPS-based denial, distance denial |
| Blocks/Hoppers |
Contain redstone/machine costs |
Hopper batching, piston caps, growth/decay pacing |
| Packets |
Cut bandwidth + client strain |
Far-entity hiding, sound/particle throttles, chunk pacing, metadata limits |
| Tracker |
Safe plugin-side culling |
Player-based hide/show with hologram integration |
Example: AI Budgeting Curve
With activation-dist-mod: 8 and power: 2.0, entities closer than 8 blocks tick nearly every game tick, while distant ones tick less often. The curve is non-linear, favoring nearby mobs:
Distance (blocks) | Relative Tick Rate
------------------|-------------------
0–8 | 100%
16 | ~50%
32 | ~25%
64+ | ~10% or frozen (if enabled)
This ensures combat mobs feel responsive, while passive or far-away mobs consume little CPU.
Configuration
The config.yml is fully commented and modular.
Key modules include:
merging – entity/item/xp stacking & holograms.dab – Dynamic AI Budgeter with freeze, FOV/LOS, exemptions.spawns – caps, TPS guards, far-distance rules.hoppers, blocks – pacing & batching of technical mechanics.packets – packet throttling (requires ProtocolLib).tracker – plugin-only per-player visibility.performance – global tick budget distribution.
Installation
- Place the
Kinetic.jar in plugins/.
- Start the server to generate the default
config.yml.
- Tune modules to fit your playerbase and server type.
- Install ProtocolLib if you want advanced packet features.
Compatibility
- Requires Paper 1.21+.
- Packet features require ProtocolLib.
- All other systems run plugin-only, no forks or patches required.
Why Kinetic?
Unlike lightweight stackers or one-off optimizers, Kinetic is modular, safe, and scalable.
It unifies common lag-reduction patterns into a coherent system with per-world budgets, per-player visibility, and adaptive pacing tied to TPS.
The result: smoother gameplay, higher tick rates, and a cleaner server without compromising mechanics.
License & Contribution
- Open an issue for bugs, performance reports, or feature requests.
- Contributions are welcome through PRs or config recipe sharing.
- License information is provided in the repository.
Spoiler
```
version: 1
# This is the main configuration for Kinetic. Comments explain what each option does,
# expected units/ranges, and any trade-offs.
# Proximity & Nearest-Player Cache (Module 1)
# Grid-based cache used by the Budget Engine and other modules to quickly
# approximate nearest-player distances. See design doc §6.1.
proximity:
cell-size: 32 # blocks per grid cell
move-threshold: 1.25 # min player movement to trigger cell update
neighbor-radius-cells: 2 # how many neighbor rings to search for players
track-cross-world: false # if false, only same-world players are considered
# Dynamic AI Budgeter (Module 3). Paces AI actions to fit within a tick budget.
dab:
enabled: true
activation-dist-mod: 8 # distance multiplier to consider entities "active" relative to players
power: 2.0 # non-linear shaping for priority decay; higher skews toward nearby entities
base-period-ticks: 1 # default period between AI ticks when unconstrained
min-period-ticks: 1 # lower bound; never schedule AI more frequently than this
max-period-ticks: 40 # upper bound; never delay AI beyond this
blacklist-entities: [] # EntityType names that are always throttled (even if whitelisted)
whitelist-entities: [] # If non-empty, only these EntityTypes are considered by the budgeter
exempt-nametagged: true # Named mobs are treated as important; less likely to be throttled
exempt-tamed: true # Tamed mobs are treated as important; less likely to be throttled
# Per-World Budget System - Advanced resource allocation per world
per-world-budgets:
enabled: false # Enable separate budget pools per world
default-budget: 2500 # Default budget for worlds not explicitly configured
worlds: # Specific world budget overrides
# world: 5000 # Example: higher budget for main world
# world_nether: 1500 # Example: lower budget for Nether
# world_the_end: 1000 # Example: minimal budget for End
# Player-Specific Exemptions - Advanced player bypass system
player-exemptions:
enabled: false # Enable individual player exemption system
exempt-ops: true # Operators are automatically exempt
exempt-names: # Specific player names to exempt
# - "AdminPlayer"
# - "BuilderUser"
exempt-permissions: # Permissions that grant exemption
- "Kinetic.budget.exempt"
# - "staff.moderator"
exempt-patterns: # Regex patterns for player names (case-insensitive)
# - "^Admin.*" # All players starting with "Admin"
# - ".*Builder$" # All players ending with "Builder"
hard-freeze:
enabled: false
min-player-distance: 64 # entities beyond this distance may be frozen (AI stopped)
recheck-period-ticks: 40 # cadence to re-evaluate freeze eligibility
max-entities-per-tick: 400 # upper bound on entities processed per pass
fov:
enabled: true
fov-degrees: 110 # player field-of-view size for visibility consideration
require-los: true # require line-of-sight when determining visibility
max-distance: 96 # max distance for FOV checks
wake-on-damage:
enabled: true
duration-ticks: 80 # temporarily unfreeze when damaged
always-active-types: [] # EntityTypes never frozen; e.g., VILLAGER if desired
per-action-multipliers:
PATHFIND: 1.0
TARGET: 1.2
BREED: 2.0
REPLENISH: 2.0
ANGER: 1.5
tps-adaptation:
enabled: true
threshold: 18.5 # below this TPS, increase throttling aggressiveness
multiplier: 1.5 # scale applied to periods when TPS under threshold
jitter:
enabled: true
percent: 0.1 # randomize periods slightly to avoid burst alignment
cleanup-interval-ticks: 1200 # periodic purge of internal bookkeeping
# Spawn controls. Provides soft per-chunk caps and distance/TPS guards.
spawns:
enabled: true
per-chunk-soft-cap:
MONSTER: 70 # approximate soft caps per chunk category
CREATURE: 50
WATER_AMBIENT: 30
tps-guard:
enabled: true
threshold: 18.5 # below this TPS, deny a portion of otherwise-allowed spawns
denial-percent: 0.35 # fraction of spawns denied when below threshold (0..1)
far-deny:
enabled: true
min-player-dist: 96 # deny spawns farther than this from any player
merging:
entities:
enabled: false
# Merge search radius (blocks) around the spawn for compatible mobs.
radius: 8.0
# Max stack size per entity unless overridden in per-type below.
max-stack-size: 32
# Also set a custom name like "Zombie x8" on the stacked mob (optional visual).
show-name: true
# Do not stack mobs that already have a custom name.
skip-named: true
# Optional allow/deny controls. If whitelist is non-empty, only those types will stack.
# Types are Bukkit EntityType names, e.g., ZOMBIE, SKELETON, CREEPER, etc.
whitelist-types: []
blacklist-types: [VILLAGER, ENDER_DRAGON, WITHER, WARDEN, ELDER_GUARDIAN, IRON_GOLEM] # never stack these types
# Per-type overrides
per-type:
SLIME:
max-stack-size: 8
MAGMA_CUBE:
max-stack-size: 8
hologram:
enabled: true
# Vertical offset above the entity. Adjust per version/model.
offset: 0.75
# Base format when no per-type override is set.
# Placeholders:
# - {amount}: stack size (supports styles below)
# - {type}: Bukkit EntityType pretty name (e.g., "Zombie")
format: "x{amount}"
# Formatting style for {amount}: plain | thousands | compact
# - plain: 1200
# - thousands: 1,200
# - compact: 1.2k
format-style: plain
# Optional per-entity-type overrides. Keys are Bukkit EntityType names.
# Example:
# per-type:
# ZOMBIE: "{type} x{amount}"
# SKELETON: "{type} x{amount}"
per-type: {}
items:
enabled: true
# Merge search radius (blocks) for item entities.
radius: 2.5
# If true, only items with identical metadata (lore, enchants, model data) stack together.
respect-metadata: true
# Perform nearby scan in a background-friendly way; world mutations still on main thread.
async-scan: true
# Allow item entities on the ground to exceed vanilla stack size (inventory stacks unaffected).
allow-oversize: false
# Cap for an item entity's merged count (visual + physics). Inventory stacks are unaffected.
max-entity-stack: 512
hologram:
enabled: true
# Vertical offset above the entity. Adjust per version/model.
offset: 0.75
# Base format when no per-material override is set.
# Placeholders:
# - {amount}: stack size (supports styles below)
# - {material}: Bukkit Material pretty name (e.g., "Diamond")
# - {name}: item display name if present, else {material}
format: "x{amount}"
# Formatting style for {amount}: plain | thousands | compact
format-style: plain
# Optional per-material overrides. Keys are Bukkit Material names.
# Example:
# per-material:
# DIAMOND: "{name} x{amount}"
# COBBLESTONE: "{material} x{amount}"
per-material: {}
xp:
enabled: true
# Merge search radius (blocks) for XP orbs.
radius: 3.0
# Maximum vanilla XP orb size when splitting/merging (typical max value is 11).
max-orb-size: 11
hologram:
enabled: true
offset: 0.75
# Placeholders:
# - {amount}: total xp value (supports styles below)
# - {type}: constant "XP"
format: "{amount} xp"
# Formatting style for {amount}: plain | thousands | compact
format-style: plain
blocks:
# Pacing for block updates to prevent cascades when far from players.
# Higher cooldowns reduce churn but delay propagation.
physics-cooldown-ticks: 3
# Slow down fluid updates when far from players to reduce server load.
throttle-fluids: true
# Leaves decay pacing: immediate | defer | defer_far. defer_far delays when not near players.
leaves-decay: defer_far
# Plant growth pacing: immediate | defer | defer_far.
plant-growth: defer_far
pistons:
# Limit concurrent piston actions per tick to mitigate lag machines.
limit-per-tick: 2
# Detect and inhibit piston engine patterns. May affect redstone contraptions; use with care.
anti-engines: false
hoppers:
# Hopper optimization module: batch and cap item moves to reduce per-tick cost.
enabled: true
# Batch pulls/pushes in this tick window for better locality.
batch-window-ticks: 4
# Global cap of item moves per tick across all hoppers.
max-moves-per-tick: 128
# Radius around hopper to scan for item entities to suck in.
pickup-scan-radius: 1.0
async:
# Size of worker thread pool for safe async tasks. Typically = CPU cores / 2..cores.
worker-threads: 2
# Enhanced WorkerPool Configuration
core-threads: 4 # Core number of worker threads
max-threads: 8 # Maximum worker threads when busy
max-queue-size: 100 # Maximum queued tasks before rejection
# Task timeout and performance settings
task-timeout-ms: 30000 # Default task timeout (30 seconds)
keep-alive-time-ms: 60000 # Thread keep-alive time (1 minute)
queue-warning-threshold: 0.8 # Queue utilization warning threshold (80%)
# Monitoring and health checks
monitoring:
enabled: true # Enable comprehensive monitoring
health-check-interval-ms: 300000 # Periodic health checks (5 minutes)
# Fallback execution when pool is overloaded
fallback-execution: true # Execute rejected tasks on main thread as fallback
# Performance tuning
allow-core-timeout: true # Allow core threads to timeout and terminate
thread-priority-offset: -1 # Thread priority offset from normal (-1 = slightly lower)
packets:
# Packet-level optimizations. Some features require ProtocolLib.
enabled: false
# If true, features that need ProtocolLib will be disabled when missing.
protocollib-required: true
hide-far-entities:
# Hide entities beyond max-distance from the player to reduce client load (server-authoritative).
enabled: true
# Distance threshold in blocks.
max-distance: 96
# Never hide player entities.
exempt-players: true
# Never hide tamed mobs owned by the player.
exempt-tamed: true
sound-throttle:
# Limits repeated identical sounds per tick to reduce spam.
enabled: true
# Per-player cap of sound packets per tick before throttling kicks in.
max-per-tick: 5
# Optional spatial de-duplication: limit repeated identical-location sounds per tick
de-duplicate:
enabled: true
bucket-radius: 8
max-per-bucket: 2
particle-throttle:
# Limits particle packet rate by cluster.
enabled: true
# Maximum packets per nearby cluster per tick.
max-per-cluster: 20
chunk-streaming:
# Paces chunk data packets to avoid bursts on join/fast travel.
enabled: true
# Allow more chunks per tick to prevent starving initial render or fast travel
max-per-tick: 8
# Do not throttle chunk packets for new players to guarantee world bootstrap
warmup-ticks: 200
prioritize-player-heading: true
# Only enable pacing when TPS is under this threshold
tps-guard:
enabled: true
threshold: 18.5
# Gradually ramp per-player allowance after warm-up to avoid burst
ramp:
enabled: true
base: 4
max: 8
step: 1
period-ticks: 40
metadata-rate-limit:
# Rate-limits frequent entity metadata updates; whitelist critical indices to avoid desync.
enabled: false
# Minimum ticks between metadata updates per entity.
interval-ticks: 5
# Metadata indices to always pass (bypass rate limit) to avoid desync on critical state.
# Common indices: 0=flags, 1=air, 2=custom name, 3=custom name visible, 4=silent, 5=no gravity, etc.
# Adjust per-version as needed. Leave empty to not bypass anything.
whitelist-indexes: [0, 1]
player-idle-compression:
# When player idle past threshold, scale down loud/visual packet budgets.
enabled: true
# Seconds of inactivity before considered idle.
idle-threshold-seconds: 60
# When a player is idle past the threshold, scale down per-tick packet caps
sound-scale: 0.5 # 0.05..1.0, multiplied with sound max-per-tick
particle-scale: 0.5 # 0.05..1.0, multiplied with particle max-per-cluster
performance:
# Global work budget per tick (internal units). Lower = stricter throttle.
tick-budget-per-tick: 5000
priorities:
# Relative share of the budget per subsystem. Higher = more time allocated.
AI: 40
HOPPERS: 30
PHYSICS: 30
shared-budget:
# When enabled, unused budget in one subsystem can be borrowed by others.
enabled: false
AI: 40
debug:
# Extra logging for diagnostics; increases console spam.
verbose: false
# Probability [0..1] to sample events for telemetry when enabled.
sampling-rate: 0.05
# Enable in-game admin commands for debugging.
commands-enabled: true
# Plugin-level entity visibility culling (approx async tracker behavior)
tracker:
visibility:
enabled: false
radius: 96.0
exempt-players: true
include-types: [] # if non-empty, only these Bukkit EntityType names are considered
exclude-types: [ITEM_FRAME, PAINTING] # never considered for hide/show decisions
max-players-per-tick: 4
# Upper bound on hide/show ops processed per tick across all tracked players.
max-ops-per-tick: 400
# How often to run the visibility pass.
period-ticks: 20
# If true, hologram ArmorStands will also be hidden/shown per-player following the same rules.
# This prevents holograms from rendering for entities that are culled for that player.
integrate-holograms: true
# Region profiles & integrations
regions:
worldguard:
# List of WorldGuard region IDs where packet suppression is bypassed
exempt-packets: []
# TickService Configuration
tick-service:
# TPS Monitoring Settings
tps-monitoring:
# Enable real-time TPS monitoring and calculation
enabled: true
# TPS threshold below which warnings are issued (default: 15.0)
warning-threshold: 15.0
# Health Check Settings
health-checks:
# Enable comprehensive health monitoring of the tick service
enabled: true
# Maximum allowed missed ticks before triggering health warnings (default: 100)
max-missed-ticks: 100
```
暂无评论，抢个沙发吧~