Features

Everything FeatherMC adds to Paper

Each feature below says what it does, what it is set to on a fresh server, and how much of it a player could ever notice.

Far-mob AI throttle Anti-lag-machine caps TNT guard Launch scripts Spark Tuning guide Compatibility

On by defaultpaper-world-defaults.yml

Far-mob AI throttle

Mob AI is one of the most expensive things a server does, and most of it runs for mobs no one is looking at. FeatherMC turns on Paper's goal-selector throttle by default, so mobs outside activation range re-plan what to do every 20 ticks (once a second) instead of every tick.

Only affects mobs outside activation range, where no player is near enough to see them react.
Mobs near players run full AI, exactly as before.
Biggest gains on worlds with lots of loaded but unwatched mobs.

Running AI farms that work with nobody nearby? Set the value to disabled for those worlds.

config/paper-world-defaults.yml

entities:
  behavior:
    # FeatherMC default. Paper ships this as "disabled".
    # Measured in ticks. Use "disabled" for player-less AI farms.
    inactive-mob-goal-selector-throttle-rate: 20

On by defaultOnly affects abuse

Anti-lag-machine caps

A well known way to take a server down is to pack thousands of arrows, pearls or XP orbs into one chunk. The chunk saves fine, then stalls the server every time it loads. FeatherMC ships per-chunk save limits so that pile never makes it to disk.

Caps of 16 per type, per chunk, for the entities these machines rely on.
Normal play does not come close to these counts.
Override any value per world, or set it to -1 to remove the cap.

config/paper-world-defaults.yml

chunks:
  # FeatherMC defaults. Paper ships these as -1 (no limit).
  entity-per-chunk-save-limit:
    arrow: 16
    ender_pearl: 16
    experience_orb: 16
    fireball: 16
    small_fireball: 16
    snowball: 16

Off by defaultfeather.yml

TNT mass-detonation guard

"Orbital strike" cannons drop hundreds of primed TNT on one spot at once. Even on a fast server that is a huge spike, and it flattens whatever is underneath. When the guard is on, a TNT that is about to explode checks its surroundings. If too many primed TNT are packed around it, that cluster is removed instead of detonating.

Only TNT inside the radius is removed. Ordinary TNT use, mining and small cannons are unaffected.
Off by default, so a fresh server keeps vanilla behaviour.
Lives in feather.yml in the server root, FeatherMC's own config file. Edit and restart to apply.

feather.yml

# Guards against mass-TNT "orbital strike" detonations.
mass-destruction:
  # When true, a dense cluster of primed TNT is deleted
  # just before it explodes. OFF by default.
  prevent-tnt-mass-detonation: true
  # How many primed TNT within the radius counts as mass.
  threshold: 100
  # Radius in blocks checked around a TNT about to explode.
  radius: 8.0

Invisible to playersstart.sh / start.bat

Low-pause launch scripts

The garbage collector is picked when Java starts, before the server reads any config file. That is why this toggle lives in the launch script and not in a YAML file. FeatherMC includes scripts for Linux, macOS and Windows with one switch.

performance (default): generational ZGC. Uses spare RAM to collect concurrently, so pauses stay well under a millisecond regardless of heap size.
conservative: Aikar's tuned G1 flags, the long-standing community standard. Better raw throughput on smaller heaps.

Both also pre-touch the heap and ignore plugins that call System.gc().

start.sh (Linux / macOS)

# How much memory to give the server.
MEMORY="10G"

# performance = low-pause ZGC (default)
# conservative = Aikar's tuned G1
GC_MODE="performance"

# Your FeatherMC jar
JAR="feather-release.jar"

start.bat (Windows)

rem performance = low-pause ZGC (default)
rem conservative = Aikar's tuned G1
set GC_MODE=performance

rem Your FeatherMC jar
set JAR=feather-release.jar

Built in

Spark, ready to go

You can't fix lag you can't see. The spark profiler ships inside the FeatherMC jar, so every server can measure itself from the first boot. Use it before and after any config change to check the change actually helped.

Need world pre-generation as well? Chunky is a separate plugin and is not bundled. Drop it into plugins/ and it works as normal.

in-game or console

/spark tps           # current TPS and MSPT
/spark health        # tick, CPU and memory overview
/spark profiler      # start/stop a CPU profile, get a web report
/spark heapsummary   # what is using RAM, by class

FEATHER-TUNING.md

A tuning guide that tells you the cost

Most optimization guides list settings. FeatherMC's guide grades every one by what players can feel, so you choose your trade on purpose. The honest headline: the biggest RAM lever is how many chunks are loaded, and that one players do notice.

Invisible No gameplay change. Apply freely.
Near-invisible Only matters under abuse, a crash, or a rare edge case.
Perceptible Real gameplay or visual change. Where the big RAM wins live. Opt in only.

Setting	Tier
`network-compression-threshold: 256`	Invisible
`chunks.max-auto-save-chunks-per-tick`	Invisible
`misc.region-file-cache-size: 128`	Near-invisible
`misc.redstone-implementation: ALTERNATE_CURRENT`	Near-invisible
`view-distance` lowered	Perceptible
`simulation-distance` lowered	Perceptible

Drop-in

Rebranded where you look, Paper where plugins look

FeatherMC shows its own name in the console, /version, the server list and the client's F3 screen. Everything a plugin or tool might depend on is left alone.

Packages stay io.papermc.paper and org.bukkit.
Brand ID stays papermc:paper, so compatibility checks pass.
Config filenames, Paper NBT data keys, CLI flags and the /paper command are unchanged.

Developer docs

Where	Shows
Console, `/version`, F3, server list	FeatherMC
`Bukkit.getName()`	FeatherMC
Brand ID	`papermc:paper`
Java packages	`io.papermc.paper`
Config files	`config/paper-*.yml` + `feather.yml`

Try it on your server

Back up, swap the jar, and compare with /spark tps before and after.

Download FeatherMC Config reference