Architecture

Server & Plugins

🖥️ Server & Plugins#

Software Hierarchy#

Rule: Start from Paper/Purpur, not Spigot, unless you have a specific compatibility constraint.

JVM Arguments (Aikar’s Flags)#

java -Xms10G -Xmx10G \
  -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:SurvivorRatio=32 -XX:MaxTenuringThreshold=1 \
  -XX:+PerfDisableSharedMem -XX:+AlwaysPreTouch \
  -jar purpur.jar nogui

Tips:

• Always set -Xms = -Xmx (prevents resizing lag)
• Leave 1-2GB RAM for the OS

Configuration Tweaks#

server.properties#

bukkit.yml#

spigot.yml#

paper-global.yml#

Purpur — Extra Config#

Purpur adds purpur.yml on top of all Paper config:

Useful built-in commands: /purpur reload · /purpur version · /ping · /uptime · /tpsbar · /compass

Purpur Installation#

Requires Java 21+:

# Latest build for a version
curl -fsSL "https://api.purpurmc.org/v2/purpur/1.21.5/latest/download" -o purpur.jar
java -Xms4G -Xmx4G -jar purpur.jar --nogui

Spark Profiling#

Paper 1.21+ bundles Spark:

/spark profiler start --timeout 600

Inspect hot paths (plugins, entities, tasks). Tune root cause, not random knobs.

World Pregeneration (Chunky)#

#1 Lag Killer — generate chunks before players explore:

chunky radius 5000
chunky start
chunky progress    # check status
chunky pause       # pause if needed
chunky continue

Nether: chunky world world_nether && chunky start

❌ Common Anti-Patterns#

• Enabling many gameplay toggles at once
• Treating config packs as universal truths
• Skipping pregen and blaming plugins for chunk lag
• Giving broad wildcard perms to regular players
• Running updates without rollback artifacts

✅ Production Checklist#

• Java 21+, startup script with sane memory headroom
• Configs tracked in git
• Spark baseline report captured
• Chunky pregen done for active worlds
• Purpur feature toggles documented by intent
• Permission model audited
• Rollback JAR + config snapshot ready

Dynmap Optimization#

Map Plugin Comparison#

Dynmap Tuning#

# Quality vs speed (vlowres = 16x faster than hires)
deftemplatesuffix: vlowres

# Image format (JPG > PNG for storage)
image-format: jpg
image-quality: 80

# Disable lag factories
render-triggers:
  - chunkgenerated
  # - playermove    ← DISABLE
  # - blockplaced   ← DISABLE
  - join
  - quit

# Throttle
renderinterval: 1.0
tiles-rendered-at-once: 1

External Webserver (Critical)#

NEVER use the internal webserver for public servers:

disable-webserver: true
json-file: true
webpath: /var/www/html/dynmap

Serve via Nginx with tile caching (expires 7d).

Dynmap Commands#

• /dynmap pause all — before heavy server activity
• /dynmap purgequeue — clear backed-up queue
• /dynmap fullrender world — run overnight in screen

Plugin Architecture Best Practices#

Project Layout#

src/main/java/com/example/myplugin/
  MyPlugin.java
  bootstrap/
  command/
  listener/
  service/
  domain/
  infra/
  config/

Gradle (Kotlin DSL) Baseline#

repositories {
  maven("https://repo.papermc.io/repository/maven-public/")
}
dependencies {
  compileOnly("io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT")
  testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
  testImplementation("com.github.seeseemelk:MockBukkit-v1.21:4.63.0")
}
java {
  toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

Lifecycle Discipline#

• onLoad: Minimal setup only, avoid Bukkit API
• onEnable: Register listeners/commands, init services, validate config
• onDisable: Cancel tasks, flush state, close DB/HTTP resources
• Never rely on /reload — full restart is the only supported path

Threading Rules#

• World/entity/block mutations: main thread (Paper) or correct context (Folia)
• DB/HTTP/files: async
• Never: Thread.sleep() on main thread, blocking I/O on sync tasks
• Always: async-to-sync pattern for DB → UI updates

Folia Support#

# paper-plugin.yml
folia-supported: true

Only enable after real validation. Use entity scheduler for entity-bound work, region scheduler for location-bound work.

PDC (PersistentDataContainer)#

NamespacedKey key = new NamespacedKey(plugin, "custom-tier");
item.editPersistentDataContainer(pdc -> pdc.set(key, PersistentDataType.INTEGER, 3));

• Reuse NamespacedKey objects
• Use getOrDefault for null-safe reads
• PDC is NOT auto-copied between holders

Security Checklist#

• Validate command args strictly
• Cooldowns for heavy commands
• Per-player/IP rate limits
• HTTP timeouts + retries with jitter
• Secrets in env vars, never hardcoded