Configuration

Every key in saturn.yml with its default, what it changes, which keys currently have no effect, and how to reload the file live.

The file

Saturn keeps all of its settings in saturn.yml in the server's folder. It is created early in startup if it does not exist. Combat and tracker values start at vanilla behaviour.

Apply changes without a restart:

/serverconfig server

This re-reads the whole file. Most changes apply straight away; the exceptions are network.flush-mode and the sentry section, noted below. See Commands and permissions.

Sections

Section	What it covers
`core`	The startup log line.
`combat`	Which combat profile applies where, and each profile's values. See Combat profiles.
`network`	Entity tracker timing and network flushing for the whole server.
`world`	Per-world combat profile and tracker overrides.
`performance`	Tab-list ping interval, locator bar updates and the combat history cap.
`debug`	Currently has no effect.
`sentry`	Optional error reporting to your own Sentry project.

core

Key	Default	Description
`startup-banner`	`true`	When `true`, Saturn logs one line on startup with its version, the Minecraft version, the Paper build, the default combat profile and the number of knockback profiles. When `false`, it logs a shorter ready line.

combat

Key	Default	Description
`default-profile`	`MODERN_1_21`	The profile used when no override below matches. `MODERN_1_21` or `CUSTOM`.
`per-world`	`{}`	Map of world name to profile.
`per-dimension`	`{}`	Map of dimension ID, such as `minecraft:the_nether`, to profile.
`per-game-mode`	`{}`	Map of the attacker's game mode, such as `survival`, to profile.
`profiles.modern-1-21`	vanilla values	Values for `MODERN_1_21`.
`profiles.custom`	`{}`	Values for `CUSTOM`. Any key left out uses the vanilla value.

The order in which these are checked, and every profile key, are on Combat profiles.

network

Key	Default	Description
`tracker-forced-teleport-interval-ticks`	`-1`	Ticks between forced full position updates for each tracked entity. `-1` or `0` keeps vanilla, which is 400 ticks.
`tracker-minimum-displacement-squared`	`-1.0`	How far an entity must move, in blocks squared, before the server sends a position update. `-1` or `0` keeps vanilla, about `7.6E-6`. Larger values send fewer movement packets, and movement looks choppier.
`tcp-no-delay`	`true`	Currently has no effect.
`flush-mode`	`batched`	`batched` keeps Paper's behaviour. `consolidated` also merges flushes of queued packets once a player is in game, which can add up to one pass of the network thread's queue in latency. Logins always use Paper's behaviour. Any other value logs a warning and uses `batched`.

A new flush-mode applies to players who join after the change. Players already online keep the mode they joined with.

world

world.per-world holds one block per world name. Each block can set:

Key	Default	Description
`combat-profile`	`null`	The combat profile for this world. Checked after `combat.per-world`.
`tracker.forced-teleport-interval-ticks`	`-1`	Overrides the network value for this world. `-1` or `0` uses the network value.
`tracker.minimum-displacement-squared`	`-1.0`	Overrides the network value for this world. `-1` or `0` uses the network value.

saturn-world-defaults.yml shows the shape of one block. Saturn never reads that file; copy its contents under world.per-world.<world-name> in saturn.yml.

saturn.yml

world:
  per-world:
    arena:
      combat-profile: CUSTOM
      tracker:
        forced-teleport-interval-ticks: 100
        minimum-displacement-squared: -1.0

performance

Key	Default	Description
`tablist-update-interval-ticks`	`-1`	Ticks between refreshes of the ping shown in the tab list. `-1` or `0` keeps vanilla, which is 600 ticks. Lower values update ping more often and send more packets.
`coalesce-waypoint-updates`	`true`	When `true`, a player's locator bar updates are sent once after each movement packet is handled, instead of every time their position changes while handling it. `false` keeps vanilla behaviour.
`combat-tracker-max-entries`	`128`	The most combat entries each entity keeps during continuous combat. The oldest are dropped first, and death messages come out the same as with every entry kept. `-1` or `0` turns Saturn's cap off; Paper's own cap, `misc.max-tracking-combat-entries` in `paper-global.yml`, still applies.

debug

Key	Default	Description
`enabled`	`false`	Currently has no effect.

sentry

Saturn can send server errors to a Sentry project you own. This is the error-tracking service, not Scala's Sentry staff plugin. Nothing is sent until you set a DSN.

Key	Default	Description
`dsn`	`''`	Your Sentry project's DSN. Empty turns reporting off. The `SENTRY_DSN` environment variable, when set, is used instead.
`environment`	`production`	The environment name attached to every report.
`min-level`	`WARN`	The lowest log level that is reported. Use a log level name: `DEBUG`, `INFO`, `WARN`, `ERROR` or `FATAL`. An unknown name means `WARN`.

saturn.yml

sentry:
  dsn: 'https://[email protected]/0'
  environment: production
  min-level: ERROR

What is sent:

Log entries at or above min-level that carry an exception are sent as reports. Each report is tagged with the Minecraft version, the build commit, the thread, and the plugin the error came from when Saturn can tell.
Warnings and errors without an exception are attached to later reports as context, not sent on their own.
The same error repeating within 60 seconds is sent once; the next report of it says how many repeats were skipped.

The sentry section is read once at startup. Restart the server after changing it; /serverconfig does not apply it.

Keys with no effect

Some keys in saturn.yml are read but do not change anything yet. Changing them is harmless:

network.tcp-no-delay
debug.enabled
In each combat profile: knockback.slowdown, knockback.fix-w-tap, hit.same-tick-attacks-enabled, hit.knockback-distance-check, hit.damage-smoothing-factor, the three shield.damage-reduction-* keys, sprint.reset-on-hit and sprint.w-tap-fix

Two profile keys need care. shield.enabled: false does not stop shields from blocking damage, and attack.alternate-sprint-knockback-input: true turns off the sprint knockback bonus. Details are on Combat profiles.