Yasui

Server optimization plugin for Paper 1.21.8. Reduces tick time by caching expensive operations while keeping AI and collision behavior vanilla.

Requirements: Paper 1.21.8, Java 21+

Start parameters:

-XX:+EnableDynamicAgentLoading -Djdk.attach.allowAttachSelf=true

With full JDK.

Features

Hopper Optimizer

Caches container fullness state to short-circuit redundant isFullContainer() checks during hopper transfers.

• NMS hook that short-circuits repeated full checks (tiny TTL cache)

Note: The NMS hook uses JVM attach. If attach is disabled, the hook will be inactive.

Villager POI Cache

Reduces POI search overhead by caching job site locations and AcquirePoi searches.

• Caches job site positions from villager brain memory
• Restores cached POI when villager loses job site memory
• AcquirePoi search cache (NMS hook, short TTL)
• PoiCompetitorScan POI type cache (NMS hook, short TTL)
• PoiAccess lookup cache for findAny/findClosest (NMS hook, short TTL)
• PoiManager getType/exists cache (NMS hook, short TTL)
• Validates POI block existence before restoration
• Optional hot-chunk PDC persistence and static-villager backoff for trade farms

Note: The AcquirePoi and PoiCompetitorScan hooks use JVM attach. If attach is disabled, the caches will be inactive.

Entity Distance Cache

Categorizes entities by distance to nearest player for quick near/distant checks.

• NEAR (<32 blocks) or DISTANT (>32 blocks) classification
• Periodic distance recalculation
• No tick freezing - all entities continue normal behavior

Hot Chunk Detection & Adaptive Caches

Detects hot areas by mob density and scales cache behavior without changing vanilla AI logic.

• Hot chunks are 16x16 by default, with optional area-radius aggregation (e.g., radius 1 = 3x3 chunks) to catch larger farms
• Heat is a [0,1] value that decays each scan and spikes based on mob density
• In hot chunks, pathfinding + POI caches (AcquirePoi/Competitor/PoiAccess/PoiType) scale linearly by heat
• Villagers in hot chunks can persist POI cache via PDC and skip scans if static
• Reuses Entity Distance Cache snapshots to avoid extra main-thread scans (optional)

Pathfinding Cache

Caches recent pathfinding results to avoid repeated createPath() work within a short TTL.

• NMS hook caches path results per navigation instance
• Keeps AI behavior unchanged (only reuses identical results)
• Invalidates paths when mob/target move past thresholds or when chunk epochs change

Note: This hook also uses JVM attach. If attach is disabled, the cache will be inactive.

Natural Spawner Cache

Reduces NaturalSpawner block state lookups by reusing recent results and skipping redundant chunk checks.

• NMS hook reuses spawn check block states with a short TTL
• Avoids extra getChunkIfLoadedImmediately calls when the spawn chunk is already known
• Invalidates on chunk epoch updates

Note: This hook also uses JVM attach. If attach is disabled, the cache will be inactive.

Installation

./gradlew clean build
cp build/libs/Yasui-mc1.21.8-*-reobf.jar /path/to/server/plugins/

Config generates at plugins/yasui/config.yml on first run.

Configuration

optimizations:
  hopper:
    enabled: true
    full-cache-enabled: true
    full-cache-ttl-ticks: 2
    full-cache-negative-enabled: false
    full-cache-negative-ttl-ticks: 1
    full-cache-invalidate-on-event: true

  villager-poi:
    enabled: true
    restore-job-site: true
    acquire-poi-cache:
      enabled: true
      ttl-ticks: 100
      ttl-jitter-ticks: 10
      max-entries: 20000
      cache-empty-results: false
      predicate-aware: false
      source-bucket-size: 2
      fallback-on-insufficient: false
      renew-on-hit: false
    competitor-scan-cache:
      enabled: true
      ttl-ticks: 2
      ttl-jitter-ticks: 1
      max-entries: 10000
      cache-empty-results: false
      renew-on-hit: false
    poi-lookup-cache:
      enabled: true
      ttl-ticks: 100
      ttl-jitter-ticks: 10
      max-entries: 20000
      cache-empty-results: false
      predicate-aware: true
      source-bucket-size: 2
      renew-on-hit: false
    poi-type-cache:
      enabled: true
      ttl-ticks: 100
      ttl-jitter-ticks: 10
      max-entries: 20000
      cache-empty-results: true
      predicate-aware: true
      renew-on-hit: false

  chunk-epoch:
    enabled: true

  entity-spread:
    enabled: true
    scan-interval: 100          # ticks
    near-distance: 32           # blocks

  pathfinding-cache:
    enabled: true
    ttl-ticks: 3
    ttl-jitter-ticks: 1
    max-entries-per-nav: 4
    mob-move-threshold: 0
    target-move-threshold: 1
    negative-ttl-ticks: 0

  natural-spawner:
    enabled: true
    blockstate-cache-ttl-ticks: 1
    blockstate-cache-max-entries: 20000

  hot-chunks:
    enabled: true
    scan-interval: 40
    mob-threshold: 16
    area-radius: 1
    use-entity-spread-snapshots: true
    snapshot-max-age-ms: 10000
    heat-decay: 0.85
    min-heat: 0.15
    villager-pdc:
      enabled: true
    villager-static:
      enabled: true
      stable-ticks: 100
      move-threshold: 0.1
      scan-interval-ticks: 200
    pathfinding-cache:
      enabled: true
      ttl-ticks: 8
      ttl-jitter-ticks: 3
      mob-move-threshold: 1
      target-move-threshold: 2
      negative-ttl-ticks: 0
    acquire-poi-cache:
      enabled: true
      ttl-ticks: 200
      ttl-jitter-ticks: 20
      renew-on-hit: true
    competitor-scan-cache:
      enabled: true
      ttl-ticks: 20
      ttl-jitter-ticks: 10
      renew-on-hit: true
    poi-lookup-cache:
      enabled: true
      ttl-ticks: 200
      ttl-jitter-ticks: 20
      renew-on-hit: true
    poi-type-cache:
      enabled: true
      ttl-ticks: 200
      ttl-jitter-ticks: 20
      renew-on-hit: true

Hot Chunk Heat Model

pressure = min(1.0, mobCount / mobThreshold)
heat = heat * heatDecay
heat = max(heat, pressure)

mobCount is per-chunk when area-radius = 0, otherwise it is the summed count across the (2r+1)x(2r+1) area. Heat is clamped to [0,1] and cools down by heat-decay every scan.

Linear scaling for hot-chunk caches:

effective = base + round((hot - base) * heat)

This linearly interpolates between the base value and the hot value as heat rises.

Tuning Notes

• Pathfinding caches are safest with short TTLs; paths are tied to the current terrain + target position.
• For static farms, conservative mob-move-threshold values are 1-2 blocks (3-4 only if movement is constrained and terrain is static).
• Large thresholds or long TTLs can keep stale paths around; chunk-epoch invalidation helps but cannot catch every dynamic change.

Commands

All commands require yasui.admin permission (OP by default).

Command	Description
/yasui status	Show optimizer statistics
/yasui reload	Reload configuration
/yasui info	Show plugin information

Status Output

=== Yasui Optimization Status ===
Hopper Optimizer: Enabled
  Active Hoppers: 342
  Full Cache Hits/Misses (1h): 423/12
  Full Cache Stores/Invalidations (1h): 2341/56
  NMS Full-Check Hook: Active

Villager POI Cache: Enabled
  Cached POIs: 87
  Job Site Restores (1h): 23/45
  Restore Candidates (1h): 312
  POI Search Cache: 156
  POI Search Hits/Misses (1h): 37/112
  AcquirePoi Hook: Active
  POI Competitor Cache: 72
  POI Competitor Hits/Misses (1h): 412/98
  CompetitorScan Hook: Active
  POI Lookup Cache: 98
  POI Lookup Hits/Misses (1h): 821/44
  PoiAccess Hook: Active
  POI Type Cache: 410
  POI Type Hits/Misses (1h): 913/50
  POI Exists Hits/Misses (1h): 402/33
  PoiManager Hook: Active

Entity Distance Cache: Enabled
  Near Entities: 45 (full vanilla)
  Distant Entities: 1203 (cached distance)
  Tracked Entities: 1248

Pathfinding Cache: Enabled
  Cache Hits/Misses (1h): 418/93
  Cache Stores (1h): 347
  NMS Path Cache Hook: Active

Hot Chunk Tracker: Enabled
  Hot Chunks: 6 (tracked: 18) / 423 Total Chunk Loaded
  Max Heat: 0.92 (min heat: 0.15)
  Mob Threshold: 16 (scan 40t, radius 1)
  Top Hot Chunks:
    - world c(12,34) b(192,544) heat=0.92 mobs=6 area=44
  Hot Boosts: Pathfinding On | AcquirePoi On | Competitor On | PoiLookup On | PoiType On
  Tick Groups: 2 (tick once every 2t, hot-only)
  Villager PDC: Enabled
  Villager Static: Enabled (stable 100t, scan 200t)

Building

./gradlew clean build

Output:

• build/libs/Yasui-*-reobf.jar - Production (reobfuscated)
• build/libs/Yasui-*.jar - Development (Mojang mappings)

Technical Notes

• Uses NMS hooks (JVM attach) for hopper, pathfinding, and AcquirePoi caching
• PoiAccess/PoiManager hooks rely on the same attach mechanism
• Caches are TTL-based and use weak maps where appropriate
• Chunk epoch tracker invalidates caches on block/POI changes
• Hot chunk counts/area aggregation run async; world snapshots happen on main thread
• Hot chunk cache boosts scale linearly by heat; area-radius aggregates adjacent chunks
• Tick group PDC assignment is batched across ticks to minimize main-thread load

License

See LICENSE file.