Documentation

Getting started

Tickwise is a drop-in replacement for Paper. If your server runs Paper today, switching takes about as long as a restart. This guide covers installing it, moving an existing server over, and tuning it.

Requirements

  • Minecraft 1.21.8 or newer.
  • Java 21 or newer. Run java -version to check.
  • A server that already runs Paper, or a fresh folder for a new one.
  • A Tickwise purchase on BuiltByBit.

Installation

  1. Download the jar. Get the build that matches your Minecraft version from your BuiltByBit purchases page.
  2. Put it in your server folder. For a new server, create an empty folder and place the jar inside.
  3. Start the server. Use the same start command you'd use for Paper:
java -Xms4G -Xmx4G -jar tickwise-1.21.8.jar --nogui

Set -Xms and -Xmx to the memory your host gives you. On the first start, accept the EULA in eula.txt and start again.

Migrating from Paper

Your worlds, plugins and Paper configs stay where they are. Only the jar changes.

  1. Back up your server. Copy the whole folder, worlds included. Keep the backup until you're happy with Tickwise.
  2. Stop the server with stop so the worlds save cleanly.
  3. Swap the jar. Replace your Paper jar with the Tickwise jar, or point your start script at it.
  4. Start it up. Tickwise reads your existing paper-global.yml and paper-world-defaults.yml, and adds tickwise-global.yml alongside them.
mv paper.jar paper.jar.bak
cp tickwise-1.21.8.jar server.jar
java -Xms4G -Xmx4G -jar server.jar --nogui
Going back to Paper? Stop the server and swap the jars back. If you changed how worlds are stored on disk, restore your backup instead.

Configuration

Tickwise's own settings live in the tickwise section at the top of tickwise-global.yml. The defaults are safe for most servers. Change a value, then restart the server to apply it.

# tickwise-global.yml (example values)
tickwise:
  auto-throttle:
    enabled: true
  farm-limits:
    hoppers-per-chunk: 64
    mobs-per-chunk: 40
  discord-alerts:
    enabled: true
    webhook: "https://discord.com/api/webhooks/..."

Not sure what to change? Use a preset instead of editing by hand.

Owner tools

Lag finder

Run /tickwise lag to see what's using the most of your tick right now. Discord alerts use the same lag finder, so an alert shows the same breakdown you'd see in game.

Auto-throttle

Auto-throttle checks your server's health once a second. When TPS starts to drop, it steps in on its own so the server stays playable, then backs off once things recover.

Farm limits

Set a maximum number of hoppers and mobs per chunk. Once a chunk reaches its limit, new ones are blocked there, so one oversized farm can't drag down the whole server.

Discord alerts

Paste a Discord webhook URL into the config and Tickwise posts a lag report to that channel when the server starts to struggle. /tickwise lag can send a test alert so you can check the webhook works.

Presets

Presets are tuned sets of settings for common server types. List them, preview exactly what a preset will change, then apply it. Tickwise backs up your config files before writing anything, and presets only use options that are marked stable.

Benchmarks

Every number we publish comes from runs where Tickwise, Paper and Leaf share the same setup:

  • Same hardware. One machine, nothing else running on it.
  • Same world. A copy of one pre-generated world, reset before every run.
  • Same plugins. One plugin set with identical configs.
  • Same load. Simulated players joining in steps, measured at each step.

We record MSPT (milliseconds per tick), TPS and heap usage. A server holds 20 TPS as long as MSPT stays under 50.

The first public results and the scripts to run them yourself are coming soon. The chart on the homepage uses placeholder data until then.

Troubleshooting

A plugin doesn't work

First check that the plugin works on Paper for the same Minecraft version. If it does, turn off the async options one at a time and restart. If one of them fixes it, tell us which one on Discord.

MSPT is higher than expected

Install spark, run /spark profiler during busy hours for a few minutes, then /spark profiler --stop. Send us the link it gives you.

The server won't start

Check that you're on Java 21 or newer and that the jar matches your Minecraft version. Then send us logs/latest.log.

Support

Open a ticket in our Discord and include:

  • Your BuiltByBit username.
  • Your Minecraft and Tickwise versions.
  • logs/latest.log, and a spark profile if it's a performance issue.