Cosmos

Cosmos is a server jar built on Leaf, with builds for Minecraft 1.21.4, 1.21.8, 1.21.11, 26.1.2, 26.2 and 26.3. It loads Paper and Bukkit plugins and reads the same config files, so you swap the jar and keep your worlds, plugins and configs. Versions lists the builds and the few things that differ between them.

On top of Leaf it cuts the tick cost of packed mobs, villagers and redstone, and uses less memory. Measured against Paper 26.2 with the same JVM flags, a villager farm ticked 9.9 times faster and redstone 6.5 times faster. The numbers and what was changed are under Performance.

It also includes admin tools you would otherwise add as plugins: a setup wizard that tunes your configs on first start, a lag analyzer that shows what is using the tick, a laggy chunk finder, a lag shield that trims view distance while the server struggles, a gamerules menu, a plugin manager that reloads plugins without a restart, a resource pack reload, a config check, a staff disguise and a world downloader block. Mob profiles, check intervals and per-world settings let you tune how much work each kind of mob and each world gets.

Permissions#

Commands#

If a plugin already owns /tps, /ping, /disguise, /plugman or another of these names, the plugin keeps it and the console logs which one. The Cosmos command still works as /leaf <command>, for example /leaf disguise Notch.

Configuration#

Cosmos reads the same files as Leaf and Paper: server.properties, bukkit.yml, spigot.yml, purpur.yml, config/paper-global.yml, config/paper-world-defaults.yml and config/leaf-global.yml. Its own settings are in config/leaf-global.yml, next to Leaf's.

/leaf admin reload applies most Cosmos settings without a restart. The exceptions are marked "Restart" in the tables. Changes to server.properties, bukkit.yml, spigot.yml, purpur.yml and the Paper files need a restart, except the resource pack lines in server.properties, which /leaf admin resourcepack reload applies.

Loader settings#

cosmos-loader.yml sits next to CosmosLoader.jar and is created on the first start.

Environment variables override the file: COSMOS_LICENSE for the key, COSMOS_MINECRAFT_VERSION, COSMOS_AUTO_UPDATE and COSMOS_LOADER_AUTO_UPDATE. The key can also be passed as -Dcosmos.license=YOUR-KEY.

Dashboard settings#

misc:
  dashboard:
    enabled: true
    url: "https://cosmos.blazez.lol"
    allow-changes: true
    server-name: ""

Lag analyzer settings#

performance:
  lag-analyzer:
    share-link: true

/leaf admin reload applies changes right away.

Lag shield settings#

performance:
  lag-shield:
    enabled: true
    trigger-mspt: 45.0
    recover-mspt: 30.0
    trigger-seconds: 10
    recover-seconds: 60
    startup-grace-seconds: 60
    step: 1
    min-view-distance: 6
    min-simulation-distance: 4
    notify-staff: true
    disabled-worlds: []

Auto-update settings#

misc:
  plugin-auto-update:
    enabled: true
    channel: release
    timeout-seconds: 30
    keep-backups: 3
    exclude: []
    install-missing: true
    install:
    - viaversion
    - viabackwards
    - viarewind
    - geyser-spigot
    - floodgate
    sources: {}

Plugin manager settings#

misc:
  plugin-manager:
    enabled: true
    safe-jar-replace: true
    watch-jars: true
    auto-reload: false
    include-dependents: true
    ignored-plugins: []

Mob profile settings#

performance:
  entity-profiles:
    enabled: false
    villagers:
      ai-interval: 1
      dab: true
    hostile:
      ai-interval: 1
      dab: true
    passive:
      ai-interval: 1
      dab: true
    water:
      ai-interval: 1
      dab: true
    bosses:
      ai-interval: 1
      dab: false
    protection:
      enabled: true
      named-mobs: true
      plugin-spawned: true
      pets: true
      npcs: true
      plugin-tagged: false
      types: []

The profiles are villagers, hostile, passive, water and bosses. enabled, ai-interval and dab can be set per world. /leaf admin reload applies changes right away.

Check interval settings#

performance:
  check-intervals:
    equipment: 1
    fluid: 1
    activation: 1

Protected mobs are always checked every tick. All three can be set per world, and /leaf admin reload applies them right away.

Per-world settings#

Cosmos settings apply to every world. To change some of them for one world, create config/leaf-worlds.yml with a section per world folder name and the same keys as in leaf-global.yml:

world_nether:
  performance:
    entity-profiles:
      enabled: true
      hostile:
        ai-interval: 2
lobby:
  gameplay-mechanisms:
    mob-spawning:
      mode: disabled
    hoppers:
      enabled: false

These keys can be set per world:

Other keys in the file are ignored, and the console and /leaf admin check list them. /leaf admin reload reloads the file. Paper, Purpur and Spigot already have their own per-world settings in their world config files.

Config check settings#

Disguise settings#

Knockback sync settings#

gameplay-mechanisms:
  knockback-sync:
    enabled: true
    ping-interval-ticks: 5
    combat-ticks: 30
    spike-threshold-ms: 20
    ping-offset-ms: 25
    max-ground-distance: 1.3

/leaf admin reload applies changes right away.

Projectile settings#

gameplay-mechanisms:
  projectiles:
    remove-player-spread: true
    wind-charges-hit-projectiles: true
    wind-charge-self-boost: false
    wind-charge-self-boost-min-pitch: 60.0
    entity-hitbox-margin: -1.0
    safe-pearl-landing: false

/leaf admin reload applies changes right away.

Item shadowing settings#

gameplay-mechanisms:
  item-shadowing:
    enabled: false
    trigger: double-click
    items:
    - totem_of_undying
    containers:
    - barrel
    - chest
    - trapped_chest
    max-ghosts-per-item: 3

/leaf admin reload applies changes right away.

Anti map stealer settings#

misc:
  anti-map-stealer:
    enabled: true
    action: kick
    notify-staff: true
    kick-message: '&cWorld downloaders are not allowed on this server.'
    blocked-channels:
    - 'wdl:'

/leaf admin reload applies changes right away.

Perf watcher settings#

performance:
  perf-watcher:
    enabled: true
    sample-interval-ms: 50
    listener-timings: true
    history-hours: 24
    alerts:
      enabled: true
      mspt: 50.0
      seconds: 10
      cooldown-seconds: 300
      notify-staff: true
      discord-webhook: ''

/leaf admin reload applies changes right away.

Combat settings#

gameplay-mechanisms:
  combat:
    old-knockback:
      enabled: false
      horizontal: 0.4
      vertical: 0.4
      friction: 2.0
      vertical-limit: 0.4
      extra-horizontal: 0.5
      extra-vertical: 0.1
    sword-blocking:
      enabled: false
      damage-reduction: 0.5
    disable-attack-cooldown:
      enabled: false
      attack-speed: 40.0
    old-golden-apples: false
    old-sharpness: false
    old-armor: false
    disable-netherite-knockback-resistance: false
    mace-max-fall-distance: -1.0
    bow-boosting: false
    fix-offhand-ghost-blocks: false
    fix-right-click-attack-cooldown: false
    dont-send-zero-knockback: false
    armor-durability-multiplier: 1.0

Critical hit damage is a Purpur setting: gameplay-mechanics.player.critical-damage-multiplier in purpur.yml, 1.5 by default.

/leaf admin reload applies changes right away.

Limiter settings#

performance:
  limiters:
    redstone:
      enabled: false
      max-milliseconds-per-region: 5.0
      region-size: 512
    max-item-merges-per-tick: -1
    excess-vehicles:
      minecarts: false
      boats: false
      limit: 32
    dont-save-snowballs: false
    chunk-unloads:
      min-per-tick: 50
      fraction: 0.05

/leaf admin reload applies changes right away.

Entity control settings#

performance:
  entity-control:
    frozen-entities: []
    disable-goals: []
    disable-mob-ai: false
    update-intervals: []
    tracking-ranges: []
    chunk-loading-entities: []

Entity types are written like zombie or minecraft:zombie.

/leaf admin reload applies changes right away. update-intervals and tracking-ranges apply to entities that load after the reload.

Packet cut settings#

performance:
  packet-cuts:
    particles:
      fall: false
      death: false
      block-break: false
      bubble-column: false
      spawner: false
    sounds:
      shoulder-parrots: false
      piglin-anger: false
      swimming: false
      shield: false
      pistons: false

/leaf admin reload applies changes right away.

Structure settings#

gameplay-mechanisms:
  structures:
    disabled-structures: []
    mineshaft-min-y: 'off'
    stronghold-min-y: 'off'
    stronghold-max-y: 'off'

Only chunks generated after the change are affected. /leaf admin reload applies changes right away.

Spawner settings#

These keys sit next to Leaf's own spawner settings and only apply when gameplay-mechanisms.spawner-settings.enabled is true.

gameplay-mechanisms:
  spawner-settings:
    spawn-count: -1
    max-nearby-entities: -1
    required-player-range: -1
    spawn-range: -1

A spawner keeps the values it was given the next time it ticks, like Leaf's spawn delays. /leaf admin reload applies changes right away.

Mob spawning settings#

gameplay-mechanisms:
  mob-spawning:
    mode: normal

/leaf admin reload applies changes right away. Set the spawn limits in bukkit.yml to 0 as well, so the server skips the natural spawning work. The setup's DISABLED and SPAWN EGGS ONLY options do both.

Hopper settings#

gameplay-mechanisms:
  hoppers:
    enabled: true

/leaf admin reload applies changes right away.

Leaf decay settings#

gameplay-mechanisms:
  leaf-decay:
    speed: 100

/leaf admin reload applies changes right away.

Manual chunk saving settings#

misc:
  manual-chunk-saving:
    enabled: false
    worlds:
    - '*'

/leaf admin reload applies changes right away.

Resource pack settings#

misc:
  resource-pack:
    compute-sha1: true
    save-sha1: true
    send-to-online-players: true
    max-download-size-mb: 250

/leaf admin reload applies changes right away.

Network settings#

network:
  transport: auto
  proxy-packet-ids: false

Fix settings#

fixes:
  load-chunks-from-newer-versions: false
  max-pending-chat-messages: 4096

/leaf admin reload applies changes right away.

Performance settings#

Defaults that differ from Leaf and Paper#

The four config defaults only go into files Cosmos creates. If you move a Leaf or Paper server over, your existing files keep their values. Change them by hand, or run the setup wizard for the redstone engine. The worker thread count applies to every server that leaves worker-threads at -1. All five need a restart.

Alternate Current sends redstone updates in a fixed order instead of vanilla's location-based order. Almost every build works the same, but contraptions that rely on vanilla update order can behave differently.

Versions#

Cosmos has a build for Minecraft 26.3, 26.2, 26.1.2, 1.21.11, 1.21.8 and 1.21.4. Each build has every feature on this page. These differences come from the Leaf version underneath:

The setup wizard always changes the settings your build has.

Install#

The Cosmos loader is the recommended way to run Cosmos. It is a small jar that checks your license, downloads the Cosmos build for your Minecraft version and starts it. On every restart it installs the newest build on its own, so you never swap jars by hand. See Loader for how it works.

1. Install Java 25 for the 26.x builds, or Java 21 or newer for the 1.21.x builds. Cosmos does not start on older Java versions.
2. In the BlazeZ Discord, open your edition's channel in the Cosmos category and pick your Minecraft version from the menu. You get your license key there. Your key is also on your dashboard.
3. Download CosmosLoader.jar.
4. Stop the server and back up your world folders and configs.
5. Replace your Paper, Purpur or Leaf jar with CosmosLoader.jar. Your plugins, configs and worlds stay as they are.
6. Start the server once. The loader creates cosmos-loader.yml and stops. Put your key in it as license-key: "YOUR-KEY".
7. Start the server with the recommended start script. The loader picks up your Minecraft version from the world, or asks for it in the console once, then downloads Cosmos and starts it.
8. On the first start Cosmos downloads ViaVersion, ViaBackwards, ViaRewind, Geyser and Floodgate into plugins/ if they are missing, unless the server runs behind a proxy. To skip that, create config/leaf-global.yml with misc.plugin-auto-update.install-missing: false before the first start.
9. Join as an op. The intro plays and the setup wizard opens.

To run a Cosmos jar without the loader, pick your version in the Discord channel and use the download link you get with your key, or download it from your dashboard. Start that jar instead of CosmosLoader.jar, and put the key in license.yml next to it as license-key: YOUR-KEY, or pass it as -Dcosmos.license=YOUR-KEY or in the COSMOS_LICENSE environment variable. Without a valid key the server stops during startup. A jar started this way does not update itself.

Recommended start script#

#!/bin/bash
MAX_RAM="${MAX_RAM:-4G}"
export MALLOC_ARENA_MAX=2
exec java -Xms512M -Xmx"$MAX_RAM" \
  -XX:+UseG1GC \
  -XX:+UseCompactObjectHeaders \
  -XX:+UseTransparentHugePages \
  -XX:+UseStringDeduplication \
  -XX:G1PeriodicGCInterval=10000 \
  -XX:MinHeapFreeRatio=10 \
  -XX:MaxHeapFreeRatio=25 \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=130 \
  -jar CosmosLoader.jar --nogui

If you run a Cosmos jar without the loader, change CosmosLoader.jar to that jar. Set the heap with MAX_RAM, for example MAX_RAM=8G ./start.sh. Compact object headers make every object smaller, and together with transparent huge pages they lowered tick time by 14 to 20% in our tests. The periodic GC and the heap free ratios hand unused heap back to the system, so the process uses less memory while the server is quiet.

-XX:+UseTransparentHugePages only exists on Linux, and -XX:+UseCompactObjectHeaders only exists on Java 24 and newer. On Windows or macOS remove the huge pages line, and on Java 21 remove the compact object headers line, because Java refuses to start with an unknown flag.

Loader#

CosmosLoader.jar is what you start. On each start it:

1. Reads your key and Minecraft version from cosmos-loader.yml.
2. Checks the key with the Cosmos update server and gets the newest build for your version. Your license only unlocks the editions you bought: the 1.21.x edition for 1.21.4, 1.21.8 and 1.21.11, the 26.x edition for 26.1.2, 26.2 and 26.3.
3. Downloads the build when it is newer than the installed one, checks it against the signed release and keeps it in cosmos-loader/cache/. Older builds for that version are deleted. When nothing changed it starts right away.
4. Starts Cosmos in the same Java process, so your start script flags and the console work as usual. The license check inside Cosmos still runs.

The update server reply is signed, and the loader refuses a reply or a jar that does not match. If the update server cannot be reached, the loader starts the build it installed last. If no build is installed yet, the server stops with a message instead.

To change Minecraft version, set minecraft-version in cosmos-loader.yml and restart. The loader downloads that version's build. Back up your world first, Minecraft cannot load a world saved by a newer version.

Dashboard#

Your dashboard at cosmos.blazez.lol/dashboard puts your key, your builds and your servers on one page. Log in with the Discord account you bought Cosmos with. Without an edition on your account it opens as a demo with sample data.

The same dashboard is also a panel in the BlazeZ portal at portal.blazez.lol/panel/cosmos, next to the panels of your other BlazeZ plugins. Overview, Performance, Settings and Tips are pages in its sidebar, and your linked servers are listed under them. It opens for Discord accounts that own a Cosmos edition or have a Cosmos key.

Every server running Cosmos with your key links to the dashboard on its own within a minute of starting. It connects out over HTTPS, so there is nothing to install and no port to open. Linked servers get the Performance, Settings and Tips tabs. See Dashboard settings to rename a server, stop changes from the dashboard or turn the link off.

A linked server sends its TPS, tick times, CPU, memory, world, chunk and entity counts, perf watcher data, lag analysis reports, setup choices and leaf-global.yml values. Values whose names contain webhook, token, secret, password or dsn are never sent. It also sends its Java version, the -X and -XX start flags, the operating system, and plugin names and versions. Changes from the dashboard are signed, and the server ignores anything that is not.

First-run setup#

Until setup is done, every player with leaf.command.leaf.setup (ops by default) gets a short intro when they join. If the server has no operators yet, the first player to join gets the intro and the setup instead. Only that player can run it, they don't become an operator, and the access ends when setup is done. They are moved to a temporary void world, a camera flies past the Cosmos logo and two boards, and then they stand frozen on a platform while the setup wizard opens. Clicking the hologram or running /setup reopens the wizard. Their game mode is locked while the intro runs, so /gamemode is refused until setup is applied or skipped. When setup is applied or skipped, they return to the spot, game mode and flight state they joined with, and the void world leafplus_intro is deleted.

All intro text is in config/leaf-intro.yml. Set enabled: false there to skip the intro. Ops then get a clickable chat reminder on join instead, until setup is done.

Setup wizard#

/setup opens the wizard. The first screen asks what the server is for:

Each page shows three questions, one per row, with the recommended option for your server type already picked. The picked option glows. Click another option to pick it instead, or click the question on the left to keep your current setting for it. NEXT PAGE moves on and the last page opens the review. Keeping the recommended picks, a practice server is set up in 5 clicks and a survival server in 7.

Hover an option to see what it changes, how much performance it gains, and whether it is the recommended pick or your current setting. When you run /setup again and choose the same server type, the pages start from your current settings instead of the recommendations.

Questions a practice server doesn't get keep their current setting. The answers are written to server.properties, bukkit.yml, spigot.yml, purpur.yml, config/paper-world-defaults.yml and config/leaf-global.yml.

The review lists every pick. Click one to go back to its page. CANCEL leaves every file as it is. APPLY copies each file it is about to change into leaf-setup-backups/<date>-<time>/, writes the new values, and applies view distance, simulation distance, mob spawning, far mob AI, whether hoppers run and manual chunk saving right away. Everything else takes effect after a restart, which the chat report tells you.

Practice servers#

Practice, duel and minigame servers run on fixed maps, so they don't need mob spawning, working hoppers or autosaves. The Practice server type in the setup turns all three off. Each one is its own setting in config/leaf-global.yml:

Manual chunk saving#

With manual saving on, autosave, chunk unloading and server stops skip the chunks of the listed worlds and the entities in them. Anything players build or break resets once that area unloads or the server restarts, so arenas clean themselves up. Player data, gamerules, time and the world border still save as usual.

To keep changes to a map, make them, then run /save <world> or /save all before you leave the area. Everything loaded in that world is saved at once. /save-all skips manual worlds and reminds you to use /save, and the console lists the manual worlds at startup.

Lag analyzer#

/leaf admin analyze records what the server's tick threads are doing every 5 milliseconds for 30 seconds, then opens a report. Run it while the lag is happening. /leaf admin analyze 120 records for two minutes, open shows the last report again, share gives the last report's share link again and cancel stops a running one.

The top row shows TPS, average and peak tick time, how much of the 50 ms tick budget is used, CPU, memory, players and worlds. The second row shows the seven categories that used the most tick time, such as Villagers, Hoppers, Redstone, Collisions or Chunk Generation. Hover one to see its share. Percentages are shares of busy tick time, so idle time between ticks doesn't count.

The buttons below open every category, the plugins that used tick time, the hottest methods, the laggy chunks found during the same run, and suggestions. RUN AGAIN repeats the analysis with the same length.

A plugin is charged for every sample where its code is running, found by its main class package. Time inside a plugin is listed under that plugin, not under the vanilla category around it.

Suggestions come from what the report found: tick spikes at 20 TPS, heavy hoppers, dropped items, entities, villagers, collisions, redstone, entity tracking, mob spawning, random ticks, chunk generation, autosave, more than one anticheat, a single plugin over 5% of the tick, chunks over 1 ms per tick, and heap over 90%. Each one names the setting or build to look at.

From the console the same report prints as text.

Share links#

When a report is ready, the chat also gets a link like https://portal.blazez.lol/cosmos/report/<id>. Click it to open the full report in a browser, or send it to whoever helps you with the lag. The page shows the same numbers, categories, plugins, suggestions, laggy chunks and hot methods as the menu.

• The link has a random id and isn't listed anywhere, so only people you give it to can open it.
• It works for 30 days, then the report is deleted.
• Uploading sends the report only: the numbers, plugin names, world names and chunk coordinates in it. No player names, IPs or configs.
• Turn it off with share-link: false in Lag analyzer settings. Reports then stay on the server.

Laggy chunks#

/leaf admin lagchunks measures how much tick time every chunk costs for 10 seconds, split into entities, block entities, random ticks and scheduled block ticks. The 10 worst chunks are listed in chat with their cost per tick, location and the main cause, such as villager, hopper or Redstone and block ticks.

Hover a line for the breakdown and click it to teleport there. Players also get a menu with all results, up to 100 chunks. /leaf admin lagchunks tp 3 teleports you to the third chunk and open shows the last result again.

Lag shield#

The lag shield watches the average tick time. When it stays at or above 45 ms for 10 seconds in a row, it lowers view distance and simulation distance in every world by one chunk. If the server keeps lagging, it lowers them again every 10 seconds, down to 6 and 4 chunks. Once tick time stays at or below 30 ms for 60 seconds, it raises them one chunk, and again after each further 60 seconds until they are back to normal.

Players see fog closer while the shield is active, and fewer mobs and farms tick far from them. A world whose normal distance is already at or below the minimum is not touched. The shield changes distances only while the server runs, so a restart always starts from your configured values.

Staff with leaf.lagshield.notify get a chat message on every change, for example "Lag shield lowered view and simulation distance by 2 chunks, MSPT 45.1 ms." /lagshield reset restores normal distances right away, and /lagshield off turns the shield off and saves that in config/leaf-global.yml. The thresholds are in Lag shield settings.

Server info#

/tps shows the server's state in one panel.

Pregeneration#

/leaf admin pregen 5000 generates every chunk up to 5000 blocks from block 0, 0 in your current world, as a square. Add a world name to pick another world. The square is centered on 0, 0, not on spawn or the world border. Only one pregeneration runs at a time.

Progress shows in chat and the console every 10 seconds with chunks done, speed and time left. /leaf admin pregen status shows the latest numbers and cancel stops after the regions in progress. Chunks are saved as they unload, so run save-all when it finishes.

It uses every CPU thread by default and pauses while more than 20000 chunks are loaded. Both limits are in config/leaf-global.yml under misc.fast-world: pregen-threads (0 is all threads), pregen-in-flight-per-thread (16) and pregen-max-loaded-chunks (20000). Worlds in the MCA region format pregenerate about 35% faster than Linear.

Fast world#

misc.fast-world.enabled: true makes the dimensions listed in misc.fast-world.dimensions (minecraft:overworld by default) use Cosmos's own lightweight generator. Its terrain has hills, oceans, beaches, plains, forests, deserts and snow, with ores and trees. For these worlds /leaf admin pregen writes region files directly on worker threads instead of loading each chunk. Restart after changing it.

Gamerules menu#

/gamerules lists every gamerule of your current world, 14 per page. Add a world name to open another world.

• On or off rules: click to switch them.
• Number rules: left-click adds 1 and right-click subtracts 1. Hold Shift for steps of 10, or 1000 once the value is 1000 or more.
• Press your drop key (Q) on a rule to reset it to its default.
• ALL WORLDS applies your changes to every world that has the rule. SWITCH WORLD shows the next world.

Each change is confirmed in your action bar.

Disguise#

/disguise <username> switches you to another player's account on this server, without logging out. You get that account's name, skin and UUID, and with it the inventory, location and stats it has saved on this server. Your own account's progress stays saved under your account. /undisguise switches you back.

• While disguised you have the permissions and OP status of the account you switched to. /disguise and /undisguise always keep working for you.
• In online mode the name must be a real Minecraft account. In offline mode any valid name works.
• You can't switch to an account that is online on this server, or to your own.
• If the real owner joins, you are switched back to your own account and the disguise is removed.
• Disguises stay through relogs and restarts until you undisguise. They are stored in config/leaf-disguises.json.
• The disguise only exists on this server. Your proxy and other servers still see your real account.

With misc.disguise.allow-others: true, staff with leaf.command.disguise.others can run /disguise <player> <username> and /undisguise <player>. A player who is offline switches on their next login. Set misc.disguise.action-bar: true to remind disguised players in their action bar.

If another plugin such as LibsDisguises owns /disguise, use /leaf disguise and /leaf undisguise.

Knockback sync#

When you hit a player, the server works out the knockback from where it last saw them. With ping, that view is a moment old. A player who is about to land still counts as in the air, so the hit only keeps their falling speed, while on their own screen they already landed and expect to be knocked up. Knockback sync fixes that.

While players fight, Cosmos measures each one's ping with a small ping packet every few ticks. When a player is hit in the air, Cosmos simulates their fall against that ping. If they reach the ground before the knockback reaches them, they get the same knockback as a hit on the ground.

• Only player hits change. Mobs, projectiles and explosions keep vanilla knockback.
• Players with low ping are not affected, because the server already sees them where they are.
• Players who are rising after a jump, flying, gliding, swimming, climbing, riding or stuck in cobwebs keep vanilla knockback.
• Hits in a fast combo keep vanilla knockback, because the player is still moving from the last hit.
• If the KnockbackSync plugin is installed, Cosmos leaves knockback to the plugin.

The settings are in Knockback sync settings.

Projectiles#

In vanilla every thrown or shot projectile gets a small random spread, so a pearl thrown straight up drifts off to the side and a second throw never follows the same line. Cosmos removes that spread for players: pearls, wind charges, snowballs, potions, arrows and tridents leave in exactly the direction you look.

Vanilla wind charges also pass through ender pearls and other projectiles. In Cosmos they collide and burst on them. A pearl caught by a wind charge lands right there: you are teleported to the pearl and the burst launches you up from that spot, so a pearl thrown straight up followed by a wind charge takes you high into the air. Arrows stuck in blocks, fishing hooks and firework rockets are not hit.

With wind-charge-self-boost on, a wind charge thrown downward while you are in the air bursts at your feet instead of flying to the ground. It gives the same push as a wind charge jump off the ground, so you can stay in the air longer before a mace or spear hit. It is off by default because it changes how wind charges thrown down at players below you work. Players on the ground, in water, riding, or flying in creative are not affected.

Your movement is still added to the throw, like in vanilla. To turn that off too, set misc.disable-relative-projectile-velocity to true in config/paper-world-defaults.yml. The settings are in Projectile settings.

Item shadowing#

In older Minecraft versions, item shadowing put the same item in two places at once. Technical players use it for immortality machines: the totem in your hand is shadowed into a barrel, a comparator reads the barrel, and when the totem pops the barrel empties, the redstone pulls an ender pearl stasis chamber and you get teleported home. Mojang patched it, and the old setups need update suppression. Cosmos brings it back with one click.

1. Turn it on with enabled: true in Item shadowing settings.
2. Open a barrel or chest and double-click the totem in your inventory. A ghost of it appears in the container and your totem stays where it was.
3. With trigger: swap-key or both, you can also hover an empty slot of the container and press the totem's hotbar number key, or the swap hands key (F) for the totem in your offhand.
4. With trigger: shift-double-click or all, shift-click the totem twice quickly instead. A single shift-click still moves the totem into the container, a moment later than usual.

What a ghost does:

• Comparators read it like a real item. One totem in a barrel gives a signal of 1.
• When the real totem pops, breaks or is used up, every ghost of it disappears at once and the comparators turn off. This also works when the ghost's chunk isn't loaded.
• Moving your totem around your inventory, to your offhand or into another container keeps the link. Relogging and restarts keep it too.
• One item can have ghosts in up to max-ghosts-per-item containers, so a single totem can run several machines.

Ghosts can't be used to dupe:

• Clicking a ghost makes it fade away.
• Hoppers can't pull ghosts, and breaking or blowing up the container drops nothing.
• A ghost totem doesn't protect anyone, even if a plugin moves it somewhere else.

Players need leaf.itemshadowing.use, which everyone has by default.

Leaf decay#

When a tree loses its logs, its leaves decay on random ticks, so most of them are gone within a few minutes. speed in Leaf decay settings slows down only that: at 25 leaves take about four times as long, and at 0 they never decay on their own. Unlike lowering the random tick speed gamerule, crops, grass, ice and everything else that uses random ticks keep their normal speed. Decaying leaves still drop saplings and apples, and leaves placed by players never decay, like in vanilla.

Anti map stealer#

World downloader mods save every chunk the server sends into a single-player copy of your map. Cosmos spots them when they register their plugin channels with the server, right after the player joins.

• With action: kick, the player is kicked with the kick message before they can save anything.
• With action: disable, the player stays and Cosmos sends the downloader its own "downloads disabled" setting, so its download button stops working.
• Staff with leaf.antimapstealer.notify get a chat message naming the player, and the console logs the channel that matched.
• Players without a downloader are never touched, including modded clients with minimaps or other mods.
• Give leaf.antimapstealer.bypass to players who are allowed to download the map, for example a builder backing up their own work.

Out of the box it blocks World Downloader, including older clients that join through ViaVersion. To block another mod, add its plugin channel to blocked-channels. The settings are in Anti map stealer settings.

Perf watcher#

The lag analyzer profiles the server when you ask it to. The perf watcher runs all the time in the background, so when the server lagged an hour ago you can still see why.

• It samples the tick threads 20 times a second and splits the tick time between plugins and server work such as entities, redstone and chunk loading.
• It times every plugin event listener and scheduler task on the tick thread, so each plugin gets a cost in milliseconds per tick and the event that costs it the most.
• Every minute is saved with its average and peak tick time, players, entities, loaded chunks and the costliest plugins. The last 24 hours are kept across restarts in cache/cosmos-perf-history.json.
• When ticks stay slower than 50 ms for 10 seconds, it raises a lag spike alert with the top causes. Staff with leaf.perfwatcher.notify get it in chat, the console logs it, and it can be posted to a Discord webhook.

/leaf admin perf opens the menu: the server right now, the last hour and the last 24 hours, lag spikes and the top cause. From there you can open the plugin costs, an hour by hour history and every recent lag spike, or start a 30 second deep scan with the lag analyzer. From the console the same command prints the plugin costs, and /leaf admin perf history or /leaf admin perf spikes print the other lists.

SAVINGS in the menu, or /leaf admin perf savings, shows the work Cosmos skipped in the last minute and since the start: AI decisions, frozen entity ticks, equipment, fluid and activation checks, item merges the limiter held back, redstone updates it delayed, vehicles it removed and pearl landings it moved. It also counts the mobs in each profile and how many are on slower AI right now. Savings work even with the perf watcher turned off.

The settings are in Perf watcher settings.

Legacy combat#

Every combat option is off by default, so a server keeps vanilla combat until you turn one on. Together they bring back 1.8 PvP on a modern server:

• Old knockback replaces knockback from hits with the 1.8 formula and lets you tune it. Players get the upward push even when they are hit in the air. Knockback sync is not used while it is on, because the 1.8 formula doesn't depend on the ground.
• Sword blocking lets players right-click with a sword to block half the damage. While they block, a shield is put in their empty off hand and removed as soon as they stop, switch items or close the game. That shield can't be moved, dropped or kept, and axes don't disable it.
• No attack cooldown gives players an attack speed of 40, so every hit lands at full strength. Turning it off again puts their attack speed back to vanilla.
• Old golden apples, old Sharpness and old armor restore the 1.8 numbers.
• Mace cap stops mace smashes from growing past a fall distance you choose.
• Bow boosting lets an arrow hit its own shooter, so a Punch bow launches you again.
• Fixes for ghost blocks from off hand placement, right-clicks resetting the attack cooldown, and zero-strength hits stopping a player's movement.

The settings are in Combat settings.

Lag limiters#

Limiters stop lag machines and huge farms from taking the whole server down. All of them are off by default.

• Redstone limiter: each area of the world (512 by 512 blocks by default) gets a budget of tick time per tick for redstone and block updates. A clock or contraption that goes over it has its remaining updates skipped for that tick, and the console names the spot once a minute.
• Item merge cap: limits how many dropped item stacks try to merge each tick, which helps when a farm drops thousands of items.
• Excess vehicles: removes empty minecarts or boats that are crammed into one spot by the dozen.
• Snowball saving: snowballs in flight are not saved, so a snowball lag machine is gone after a restart.
• Chunk unloads: sets how many chunks unload per tick when many are waiting.

The settings are in Limiter settings.

Entity control#

Entity control gives you a per-type switch for the costly parts of entities, for example on a lobby with hundreds of armor stands or an event map full of mobs:

• Freeze entity types completely, or only remove their AI goals.
• Turn off mob AI for every mob.
• Send position updates less often for some types, or show them from a shorter distance.
• Make projectiles such as arrows or snowballs keep the chunks they fly through loaded.

The settings are in Entity control settings.

Packet cuts#

Particles and sounds cost bandwidth for every player who sees them. Packet cuts stop the server from sending the ones most players don't miss: landing dust, death puffs, other players' block-break effects, bubble column splashes, spawner flames, shoulder parrots, angry piglins, swimming, shields and pistons. Each one is its own switch and all are off by default.

The settings are in Packet cut settings.

Structures and spawners#

• Turn off any structure in newly generated chunks, for example trial chambers.
• Keep mineshafts and strongholds inside a height range. They are moved as a whole, so their layout stays intact.
• Set spawn count, nearby mob cap, player range and spawn range for every spawner, next to Leaf's spawner delays.

The settings are in Structure settings and Spawner settings.

Proxy packet IDs#

Behind a proxy, every packet the server sends is compressed, and the proxy has to look inside to know which packet it is. With network.proxy-packet-ids: true, Cosmos writes each compressed packet's ID in front of the compressed data. BlazeVelocity reads it and passes the packet on to the player without unpacking it.

• It only turns on for players who join through BlazeVelocity with backend-packet-ids = true in blazevelocity.toml, which is the default. Cosmos and BlazeVelocity agree on it during login, so any other proxy, or a BlazeVelocity with it off, gets normal packets.
• It needs Velocity modern forwarding, which BlazeVelocity uses when player-info-forwarding-mode = "modern".
• Players see no difference. The proxy uses less CPU because it skips the unpacking.

The setting is in Network settings.

Plugin auto-update#

On every start, before plugins load, Cosmos checks ViaVersion, ViaBackwards and ViaRewind on Modrinth and Geyser and Floodgate on GeyserMC. Newer builds replace the old jars in the same start, and missing plugins from the install list are downloaded. It checks each file's hash, never installs an older build than the one you have, and keeps the replaced jars in plugin-backups/<plugin>/.

The console logs every result, for example Installed ViaVersion 5.12.0. or ViaVersion is up to date (5.12.0).. ViaBackwards and ViaRewind are installed only together with ViaVersion, which they need. A download that takes longer than timeout-seconds is dropped and logged as timed out, for example Could not install Geyser: timed out, and startup continues. The next start tries again.

Plugin auto-update doesn't run on a server behind a proxy, which means settings.bungeecord: true in spigot.yml or proxies.velocity.enabled: true in config/paper-global.yml. ViaVersion and Geyser belong on the proxy there, so nothing is updated or installed and the console logs Plugin auto-update is skipped because this server runs behind a proxy.

To keep another Modrinth plugin updated, add it under sources with its plugin name in lower case:

misc:
  plugin-auto-update:
    sources:
      luckperms: "modrinth:luckperms"

The updater always takes the newest file of the project, so only add plugins whose latest release supports your Minecraft version. To stop updates for one plugin, add it to exclude. To stop them all, set enabled: false.

Mob profiles#

Cosmos sorts every mob into a profile:

Each profile has its own AI rate. A vanilla mob picks new goals and targets every second tick and keeps doing what it already chose in between. With ai-interval: 2 it picks every fourth tick, with 4 every eighth. Walking toward a target it already chose stays smooth, so players mostly notice mobs reacting a little later. With dab: true and far mob AI turned on (performance.dab.enabled), mobs in the profile also decide less often the further they are from players, scaled by the other performance.dab settings.

Protection#

Named mobs, pets, NPCs and mobs spawned by plugins are protected, plus any types in protection.types. Protected mobs always run at the vanilla rate, far mob AI skips them, entity control can't freeze them or turn off their AI, and the check intervals check them every tick. This keeps custom bosses, pets and NPCs from plugins such as MythicMobs, Citizens and pet plugins working. Protection is on even while profiles are off. /leaf admin perf savings shows how many mobs are in each profile, including protected ones.

Check intervals#

Mobs re-check their armor, check for water and lava, and the activation range wakes up mobs near players, every tick by default. Check interval settings spread those checks out. Players and protected mobs are always checked every tick, and a mob that is already in water or lava keeps its fluid checks every tick.

Suffocation and line of sight already have intervals in Gale's config: small-optimizations.reduced-intervals.check-stuck-in-wall in config/gale-world-defaults.yml (10 by default) and small-optimizations.reduced-intervals.update-entity-line-of-sight in config/gale-global.yml (4 by default).

Config check#

/leaf admin check reads your configs and lists settings that are risky or fight each other, world by world: simulation distance above view distance, mob AI turned off, very low item merge limits, long AI or check intervals, parallel world ticking, a region format other than MCA, too little memory, and mistakes in leaf-worlds.yml. Warnings are red and notes gray. The same check runs 2 seconds after every start and logs the warnings.

Tuning map#

Where to change common performance and gameplay knobs:

Plugin manager#

Cosmos runs every plugin from a private copy of its jar in cache/cosmos-plugins/. You can upload a new jar over the old one in plugins/ while the server runs, from SFTP or a panel file manager. The running plugin keeps working without zip file closed or NoClassDefFoundError errors, and the new jar is used on the next reload or restart. On Windows the jars in plugins/ are no longer locked either.

/plugman opens a menu with every plugin and every jar in plugins/ that is not loaded. Click a plugin to reload, disable, enable or unload it, or click a jar to load it. Disable and unload ask to confirm first and list the plugins they affect. Every action is also a command, see Commands.

A reload also reloads the plugins that hook into the target:

• plugins that list it under depend or softdepend, or that it lists under loadbefore
• plugins that registered services with its classes, like LuckPerms and Essentials for Vault
• plugins that loaded any of its classes

They unload together and load back in the startup order, so their hooks point at the new classes and services. Unload and disable work the same way. /plugman info <plugin> shows the list under "Needed by". Set include-dependents: false to act on one plugin only.

When a jar in plugins/ changes or a new jar appears, staff with leaf.pluginmanager.notify get a chat message such as Essentials changed on disk, 2.21.0 to 2.22.0. Click to reload it. and the console logs the same. The notice waits until the file stops changing, so a half-uploaded jar is never loaded. With auto-reload: true the plugin reloads on its own instead.

A reload starts the plugin fresh, the same as a restart does for that plugin, so anything it only keeps in memory is reset. Some plugins print a /reload warning when they load after startup. Two kinds of plugins need a restart:

• Paper plugins with a bootstrapper (bootstrapper: in paper-plugin.yml) only load at startup. You can unload them, but loading them again needs a restart.
• A plugin that generates one of your worlds can't be disabled or unloaded.

Resource pack reload#

The server resource pack comes from the resource-pack lines in server.properties, which Paper only reads on start. With Cosmos you change those lines, or upload a new pack under the same link, and run /leaf admin resourcepack reload:

1. Cosmos reads resource-pack, resource-pack-id, resource-pack-sha1, require-resource-pack and resource-pack-prompt again. The rest of server.properties stays as the server loaded it.
2. It downloads the pack and works out its sha1. When resource-pack-sha1 is empty or wrong, it writes the right one to server.properties, so you never copy a hash by hand.
3. Everyone online gets the new pack right away, and players who join later get it as usual.

A new file under the same link still reaches everyone, because its sha1 changed. A new resource-pack-id removes the old pack first, and an empty resource-pack removes the pack from everyone online. When nothing changed, nothing is sent. When the download fails, the current pack stays and the command says why.

Packs sent by plugins such as ItemsAdder or Nexo are separate and stay loaded. With require-resource-pack=true, a player who declines the new pack is kicked, the same as on join. /leaf admin resourcepack info shows the pack the server uses right now, and /leaf admin resourcepack send <player> sends it to one player again.

Performance#

Leaf already contains most performance work from Gale, Pufferfish, Purpur, SparklyPaper and Lithium. Cosmos adds its own changes on top:

• Entities: collision boxes are packed for crowded spaces and pushing uses a grid, so packed mob farms cost less. Idle mobs reuse their block lookups until something nearby changes, and looking up entities by type skips chunks that have none.
• Villagers: a villager that found no bed or job site waits longer before searching again (see Performance settings).
• Ticking: random ticks skip chunk sections with nothing to tick, and mob spawning looks up nearby players once per chunk.
• Redstone: Alternate Current is the default engine.
• World generation: on the 26.2 build the density function compiler is on, which made chunk generation about 30% faster with the same terrain. Chunk generation threads run at a lower OS priority on Linux, so generating doesn't slow the main thread.
• Memory: block shapes and block state data are shared, worldgen data is released sooner, and structure templates that haven't been used for 10 minutes are unloaded. Change that time with -Dleaf.structureTemplateExpireSeconds=<seconds>.
• Ports from DivineMC: /locate runs off the main thread, command blocks cache their parsed command, raid banners are cached, and goats skip work they don't need. Async chunk sending and parallel mob sensors are available as options.

Measured on the 26.2 build against Paper 26.2 with the same JVM flags:

The entity and redstone rows are main-thread tick cost in flat-world farm tests. Process memory uses the recommended start script. Your numbers depend on hardware, plugins and players.

Plugin compatibility#

Pet and custom mob plugins such as CombatPets give Allays, Frogs, Goats and other brain-driven mobs their own brains, which often leave out some of the memories vanilla mob AI reads. On Paper the mob throws Unregistered memory fetched and is removed on its first tick. Cosmos reads those memories as empty, so the mobs spawn and stay. Nothing to configure.

Some plugins clear the whole command map when they shut down or reload their commands. On Paper that removes every command on the server, so even stop and op answer Unknown or incomplete command. Cosmos removes only the commands of that plugin and logs <plugin> tried to clear every command on the server, so vanilla and other plugin commands keep working. /bukkit:reload still clears and rebuilds everything. Nothing to configure.

Troubleshooting#

Startup fails with UnsupportedClassVersionError. The server is running on Java older than 25 for a 26.x build, or older than 21 for a 1.21.x build. Check java -version on the machine or panel that starts the server.

The server stops during startup with a license message. The key is missing or wrong. With the loader, put it in cosmos-loader.yml as license-key: "<key>". Without the loader, put it in license.yml as license-key: <key>. You can also pass it with -Dcosmos.license=<key>.

The loader says a Minecraft version is not on your license. That version belongs to the edition you don't own. The message lists the versions your license unlocks. Set one of them as minecraft-version in cosmos-loader.yml.

The loader says the update server could not be reached. Without an installed build the server cannot start. Check that the machine can reach cosmos.blazez.lol over HTTPS, then start again. Once a build is installed, the loader boots it when the update server is down.

The loader says Cosmos needs a newer Java. Switch the server to the Java version it names. On Pterodactyl that is the Docker image under Startup.

/tps, /ping, /disguise or /plugman opens another plugin's command. That plugin registered the name first. Use /leaf tps, /leaf ping, /leaf disguise or /leaf plugman.

The console logs <plugin> tried to clear every command on the server. That plugin tried to remove every command, which on Paper breaks stop, op and the commands of every other plugin. Cosmos kept them and removed only the commands of that plugin. Update the plugin, or ask its author to unregister only its own commands.

/plugman reload says another plugin depends on the target and cannot be reloaded with it. That plugin uses a Paper bootstrapper or generates a world. Restart the server, or set include-dependents: false to reload the target alone.

A world that was opened on a newer Minecraft version won't load. A Cosmos build can't read chunks saved by a newer Minecraft version. Restore a backup from before the world was opened on the newer version, or use the Cosmos build for that version.

Java refuses to start with Unrecognized VM option 'UseCompactObjectHeaders'. That flag needs Java 24 or newer. Remove it from the start script when you run a 1.21.x build on Java 21.

/leaf admin resourcepack reload says it could not download the resource pack. The server downloads the pack itself to work out its sha1, so the link must work from the server machine and point straight at the zip file, not at a download page. Test it with curl -I <link> on that machine, or set compute-sha1: false and write the sha1 into server.properties yourself.

/leaf admin mspt says parallel world ticking is off. Per-world tick times need async.parallel-world-ticking.enabled: true in config/leaf-global.yml. /tps shows the server's tick times without it.