nukkit-mot.yml

Advanced Nukkit-MOT server configuration. Settings are grouped and sorted by category.

For standard Minecraft server settings, see server.properties.

performance-settings (Performance Settings)

async-workers

Data Type	Default Value
String	auto

number of async worker threads

if set to auto, it will try to automatically detect the number of cores and use that

virtual-threads

Data Type	Default Value
Boolean	on

use virtual threads for async tasks that opt in via the scheduler API

requires Java 21 or newer, the setting has no effect on older Java versions

tasks that do not opt in keep running on the async-workers pool

auto-tick-rate

Data Type	Default Value
Boolean	on

allow the server to automatically change level tick rate to maintain 20 ticks per second

auto-tick-rateon

Simulated tick time = 90 ms

20 ms200 ms

TPS stays at 20 — the overloaded world ticks less often instead (tickRate rises).

Server TPS20 / 20

World tick speed10/s · tickRate = 2

auto-tick-rate-limit

Data Type	Default Value
Integer	20

how much the server can temporary drop tick rate

base-tick-rate

Data Type	Default Value
Integer	1

default tick rate

1 = 20 ticks per second, 2 = 10 ticks per second, etc.

recommended to keep it as default (1)

always-tick-players

Data Type	Default Value
Boolean	off

Always tick players

thread-watchdog

Data Type	Default Value
Boolean	on

enable a task that checks if the server is frozen and kills it

useful if you have an auto restart script or the server runs on a panel with this feature

thread-watchdog-tick

Data Type	Default Value
Integer	60000

Milliseconds the watchdog waits, if the Nukkit-MOT main thread is suspended for more than 60000 milliseconds, a fatal error is thrown and execution is terminated

do-level-gc

Data Type	Default Value
Boolean	on

do level garbage collection between ticks

ticks-per-autosave

Data Type	Default Value
Integer	6000

how often world autosave task runs

in ticks, 20 ticks = 1 second

level-auto-compaction

Data Type	Default Value
Boolean	on

enable automatic LevelDB compaction for worlds

level-auto-compaction-ticks

Data Type	Default Value
Integer	36000

how often the automatic LevelDB compaction task runs

in ticks, 20 ticks = 1 second (default: 36000 = 30 minutes)

leveldb-cache-mb

Data Type	Default Value
Integer	64

Sets the maximum chunk data cache size per world to reduce disk I/O.

Consider increasing this value if you have plenty of RAM and only a few large worlds. Consider decreasing it if you have many worlds and limited RAM.

use-native-leveldb

Data Type	Default Value
Boolean	off

use native leveldb implementation

enable-spark

Data Type	Default Value
Boolean	off

Enabling Spark for Performance Analysis

See: https://spark.lucko.me/docs

network-settings (Network Settings)

nethernet

NetherNet (WebRTC) transport settings, runs alongside RakNet

NetherNet is the WebRTC-based transport Bedrock Edition uses to succeed RakNet: clients 1.21.90+ can join over it (starting with restricted networks where plain UDP is blocked), and since Bedrock 1.26.50 it is the client's default transport. Nukkit-MOT listens on both transports at once — legacy clients keep RakNet, NetherNet clients join over HTTP signaling + WebRTC

The two transports use the network like this:

• Signaling over TCP on server-port (RakNet keeps the UDP side) — open server-port for TCP in the firewall, otherwise NetherNet players cannot connect at all
• Media (game traffic) over UDP — shares server-port's UDP side (19132) with RakNet by default, relayed in-process from the RakNet socket, so no extra port is needed; pin a standalone media port (e.g. 19134), a port window, or 0 for system-assigned ports via server-udp-ports, which also explains what to do when media UDP is unreachable

19132

19133

19134

TCP

NetherNet signaling

—

—

UDP

RakNet + NetherNet media (relayed)

IPv6 listener (off by default)

—

listening by defaultnot used by default

Monitoring: /status prints a NetherNet block covering the last 10 minutes (joins accepted, ICE connections, completed handshakes); /status full adds media traffic, drop counters and shared-port relay statistics. The block is hidden while NetherNet is disabled.

network-settings:
  nethernet:
    enabled: true
    ice-servers: []
    identity-file: keys/nethernet-identity.pem
    identity-domain: ''

enabled

Data Type	Default Value
Boolean	on

Enabled by default alongside RakNet

While enabled, signaling shares server-port over TCP and media shares its UDP side by default (relayed in-process from the RakNet socket — pin a standalone port like 19134 via server-udp-ports if you prefer; 0 reverts media to system-assigned ports)

Set to false to run RakNet only — the TCP signaling endpoint and the media port disappear, nothing else changes

ice-servers

Data Type	Default Value
List<String>	[]

Extra ICE STUN/TURN servers, e.g. stun:stun.l.google.com:19302

TURN credentials go in the URL: turn:user:pass@host:port?transport=udp

Add a TURN relay when players behind symmetric NAT cannot establish a direct media path — see server-udp-ports for the full media-unreachable checklist

identity-file

Data Type	Default Value
String	keys/nethernet-identity.pem

Operator identity PEM file, generated on first start, keep it

Changing it makes all returning players re-confirm the trust prompt

Running several servers? Share one identity file across them to present as the same operator

identity-domain

Data Type	Default Value
String

Operator name in the client trust prompt, empty uses the MOTD

Display text only — it can be changed at any time without replacing the identity key

zlib-provider

Data Type	Default Value
Integer	2

select zlib provider

0 = ZlibOriginal, 1 = ZlibSingleThreadLowMem, 2 = ZlibThreadLocal

default: 2

warning

Using other providers may negatively impact server performance.

Each thread keeps its own Deflater — no repeated allocation, no lock contention.

compression-level

Data Type	Default Value
Integer	5

Zlib compression level for sent packets (0-9)

higher = more cpu usage but less bandwidth usage

chunk-compression-level

Data Type	Default Value
Integer	7

Zlib compression level for chunk data (0-9)

higher = more cpu usage but smaller chunk packets

compression-threshold

Data Type	Default Value
Integer	256

don't compress batch packets smaller than this (Zlib only)

compression-threshold = 256

02564 KB256 KB

Packets smaller than the threshold are sent at compression level 0 — i.e. uncompressed.

use-snappy-compression

Data Type	Default Value
Boolean	off

Use Snappy compression for packets

rak-packet-limit

Data Type	Default Value
Integer	2000

A number of datagram packets each address can send within one RakNet tick (10ms)

IPs exceeding this limit will be temporarily banned

rak-cookie-mode

Data Type	Default Value
String	active

RakNet cookie mode for connection security. Available values:

Value	Description
active	Key is generated and managed by the server. Handles and responds to ID_OPEN_CONNECTION_REQUEST_1 with a stateless cookie (default)
offloaded	Key is unknown. Ignores ID_OPEN_CONNECTION_REQUEST_1. On ID_OPEN_CONNECTION_REQUEST_2, verifies timestamp is recent. Signature is ignored
offloaded_psk	Key is known. Ignores ID_OPEN_CONNECTION_REQUEST_1. On ID_OPEN_CONNECTION_REQUEST_2, verifies timestamp is recent and checks cookie signature
off	Accepts any cookie at ID_OPEN_CONNECTION_REQUEST_2
none	No cookie is sent or expected. The RakNet protocol version cannot be recovered in this mode
stateless	Handles the full cookie handshake and recovers the RakNet protocol version from the cookie, but does not validate the signature

note

If you cannot join the server (especially when using a proxy), try setting this to offloaded.

For backward compatibility, true is treated as active and false is treated as off.

timeout-milliseconds

Data Type	Default Value
Integer	25000

how long should the server wait before kicking player if no response from the client

in milliseconds, 1000 milliseconds = 1 second

note

This timeout bounds the login phase of both RakNet and NetherNet sessions, and also bounds the NetherNet WebRTC handshake phase.

Set it to 0 to disable the login timeout; the NetherNet WebRTC handshake then still falls back to 30 seconds.

query-plugins

Data Type	Default Value
Boolean	off

include list of plugins in query (enable-query=on)

use-waterdog

Data Type	Default Value
Boolean	off

Attempt to get the real IP of clients provided by WaterdogPE

See: https://waterdog.dev/

viaproxy-username-prefix

Data Type	Default Value
String

Username prefix for ViaProxy connections

enable-proxy-protocol

Data Type	Default Value
Boolean	off

Enables HAProxy Proxy Protocol v2 parsing for UDP proxies such as FRP.

When a trusted proxy sends a valid PPv2 header, Nukkit-MOT replaces the proxy source address with the real client address. This allows IP-based logs, bans, and plugins to see the player's real IP instead of the proxy IP.

warning

Enable this only when your server is behind a compatible UDP proxy. Whitelisted proxy sources must send a valid PPv2 header.

proxy-protocol-whitelist

Data Type	Default Value
List<String>	["127.0.0.1/32", "::1/128"]

List of trusted proxy source IPs or CIDR ranges allowed to send Proxy Protocol headers.

Use proxy addresses here, not player addresses. Examples: 127.0.0.1/32, 10.0.0.0/8, 203.0.113.5/32, ::1/128

note

Both IPv4/CIDR and IPv6/CIDR entries are supported.

IPv6 local addresses are trusted by default.

If the list is empty, all source IPs are trusted for Proxy Protocol, which is less secure.

Headerless or invalid packets coming from a whitelisted source will be dropped.

chunk-settings (Chunk Settings)

sending-per-tick

Data Type	Default Value
Integer	4

how many chunks can be sent per tick

ticking-per-tick

Data Type	Default Value
Integer	40

how many chunks can be ticked per tick

ticking-radius

Data Type	Default Value
Integer	3

radius of chunks around players to get ticked

generation-queue-size

Data Type	Default Value
Integer	8

how many chunks can be waiting for generation

generation-population-queue-size

Data Type	Default Value
Integer	8

how many chunks can be waiting for population

light-updates

Data Type	Default Value
Boolean	on

Light updates

clear-chunk-tick-list

Data Type	Default Value
Boolean	on

Allow the server to clear the list chunkTickList that tracks which chunks need logical updates after each game tick is completed.

This can help optimize server performance by preventing unnecessary computations, especially in the case of large servers or when there are many chunks to manage.

spawn-threshold

Data Type	Default Value
Integer	56

how many chunks need to be loaded before player spawns

cache-chunks

Data Type	Default Value
Boolean	off

save chunks to memory for faster sending

async-chunks

Data Type	Default Value
Boolean	on

enable asynchronous chunk sending

this can improve the performance a lot when lots of chunks are being sent to players on different versions

it's recommended to keep this enabled

async-chunkson

max-pending-chunk-writes

Data Type	Default Value
Integer	128

maximum number of pending chunk writes per world before chunk unloading pauses (backpressure)

max-pending-chunk-writes = 128

3264128256

Write pressure = 10/s

4/s40/s

When the queue reaches the limit, chunk unloading pauses until the disk catches up (backpressure). Raise the write pressure above the drain rate (12/s) to see it in action.

entity-settings (Entity Settings)

spawn-eggs

Data Type	Default Value
Boolean	on

Enable spawn eggs, allowing entity spawning via spawn eggs

mob-ai

Data Type	Default Value
Boolean	on

Enable creature AI

auto-spawn-task

Data Type	Default Value
Boolean	on

enable task for auto spawning of mobs and animals

spawning works by the server's difficulty setting

note: spawn-animals, spawn-mobs or both must be enabled if you want anything to be spawned

despawn-task

Data Type	Default Value
Boolean	on

enable despawning of mobs and animals without a name tag

note

there are special cases such as the ender dragon, withers and villagers that do not despawn

ticks-per-spawns

Data Type	Default Value
Integer	200

how often entity auto spawn task runs

in ticks, 20 ticks = 1 second

ticks-per-despawns

Data Type	Default Value
Integer	12000

how long entities live

in ticks, 20 ticks = 1 second

world-settings (World Settings)

nether

Data Type	Default Value
Boolean	on

Generate Nether world

end

Data Type	Default Value
Boolean	on

Generate End world

vanilla-portals

Data Type	Default Value
Boolean	on

Vanilla portals

portal-ticks

Data Type	Default Value
Integer	80

Ticks required for the player to trigger the portal

multi-nether-worlds

Data Type	Default Value
List

if you need multiple nether worlds, list worlds which should have their own nethers here, otherwise using the default nether world

anti-xray-worlds

Data Type	Default Value
List

list of worlds where the experimental built-in anti xray is enabled

example: [world, survival, factions]

do-not-tick-worlds

Data Type	Default Value
List

list of worlds where random block ticking is disabled

this disables plants growing, leaves decaying, dirt turning into grass, falling blocks etc.

you may want to add your lobby and minigame worlds here

entity-spawning-disabled-worlds

Data Type	Default Value
List

list of worlds where entity auto spawning is not allowed

example: [lobby, pvp, creative]

load-all-worlds

Data Type	Default Value
Boolean	on

Load all worlds

auto-save-disabled-worlds

Data Type	Default Value
List

Worlds where level auto-save is disabled

worlds

Data Type	Default Value
Map

Custom world configurations. Each entry defines a world with its own generator, seed and generator settings.

Example:

worlds:
  my_world:
    generator: normal
    seed: 12345
    generator-settings: ""
  my_flat_world:
    generator: flat
    seed: 0
    generator-settings: ""

Each world entry supports:

• generator - World generator type (default: normal)
• seed - World seed (default: 0)
• generator-settings - Generator specific settings (default: empty)

player-settings (Player Settings)

save-player-data

Data Type	Default Value
Boolean	on

if enabled, saving player data by their uuid in the format NukkitX uses and automatically converting player data in the old format to the new format

do not disable if new player data exists

save-player-data-by-uuid

Data Type	Default Value
Boolean	on

if enabled, saving player data by their uuid in the format NukkitX uses and automatically converting player data in the old format to the new format

do not disable if new player data exists

persona-skins

Data Type	Default Value
Boolean	on

persona skins allowed

note

default steve skin will show if disabled

enabling do-not-limit-skin-geometry may be required for some persona skins to be usable

skin-change-cooldown

Data Type	Default Value
Integer	15

Skin change cooldown in seconds

do-not-limit-skin-geometry

Data Type	Default Value
Boolean	on

disables maximum skin geometry size checks

may be required for some persona skins to be usable

do-not-limit-interactions

Data Type	Default Value
Boolean	off

disables a hack which is used to limit right click interaction spamming by client

space-name-mode

Data Type	Default Value
String	ignore

Handling player names with spaces

deny - Players with names containing spaces are prohibited from entering the server

ignore - Ignore spaces in player names (default)

replace - Replace spaces in player names with "_"

note

For backward compatibility, the aliases disabled (= deny) and replacing (= replace) are still accepted.

xp-bottles-on-creative

Data Type	Default Value
Boolean	on

allow players to throw experience bottles on creative

stop-in-game

Data Type	Default Value
Boolean	off

allow op to use /stop command in game

op-in-game

Data Type	Default Value
Boolean	on

allow op to use /op command to op other players in game

debug-settings (Debug Settings)

debug-level

Data Type	Default Value
Integer	1

set a higher value (1-3) if you want more debug logging

ansi-title

Data Type	Default Value
Boolean	off

Enable to display server occupancy information in Windows CMD title

deprecated-verbose

Data Type	Default Value
Boolean	on

Verbose API deprecations

call-data-pk-send-event

Data Type	Default Value
Boolean	on

you can disable DataPacketSendEvent for better performance if none of your plugins uses it

call-batch-pk-send-event

Data Type	Default Value
Boolean	on

you can disable BatchPacketsEvent for better performance if none of your plugins uses it

call-entity-motion-event

Data Type	Default Value
Boolean	on

If no plugin uses it, you can disable EntityMotionEvent for better performance

block-listener

Data Type	Default Value
Boolean	on

enable checks used for snow and iron golems, monster egg stone etc.

automatic-bug-report

Data Type	Default Value
Boolean	on

enable automatic bug reports

update-notifications

Data Type	Default Value
Boolean	on

notify operators about new Nukkit MOT releases on join

bstats-metrics

Data Type	Default Value
Boolean	on

enable bStats metrics

https://bstats.org/plugin/server-implementation/Nukkit/

data collected anonymously: server software (Nukkit MOT), player count, players game versions, xbox auth required, Java version, operating system, cpu arch & core count, host country

hastebin-token

Data Type	Default Value
String

Hastebin token for generating debug links

See: https://www.toptal.com/developers/hastebin/documentation

game-feature-settings (Game Feature Settings)

achievements

Data Type	Default Value
Boolean	on

enable player achievements

announce-player-achievements

Data Type	Default Value
Boolean	on

broadcast achievement earned messages to all players

bed-spawnpoints

Data Type	Default Value
Boolean	on

allow players to set spawn point using beds and respawn anchors

explosion-break-blocks

Data Type	Default Value
Boolean	on

enable explosion damage to blocks

affects all explosions such as tnt, creepers and end crystals

piston-push-limit

Data Type	Default Value
Integer	12

maximum number of blocks a single piston can move (1-64)

values outside the 1-64 range fall back to 12; bedrock edition uses 12

drop-spawners

Data Type	Default Value
Boolean	on

Drop spawners upon destruction

anvils-enabled

Data Type	Default Value
Boolean	on

enable anvils

vanilla-bossbars

Data Type	Default Value
Boolean	off

show boss bar for wither and ender dragon (experimental)

use-client-spectator

Data Type	Default Value
Boolean	on

Use client spectator

enable-experiment-mode

Data Type	Default Value
Boolean	on

Enable experiment mode

multiversion-min-protocol

Data Type	Default Value
Integer	0

Minimum protocol for multiversion

multiversion-max-protocol

Data Type	Default Value
Integer	-1

Maximum protocol for multiversion

enable-raw-ores

Data Type	Default Value
Boolean	on

Enable raw ores; when enabled, coarse copper, coarse iron, and raw gold drop from higher-version players

As of 1.17.0

enable-new-paintings

Data Type	Default Value
Boolean	on

Enable the new paintings added in version 1.21

enable-new-chicken-eggs-laying

Data Type	Default Value
Boolean	on

Enable new chicken eggs laying (Blue Egg & Brown Egg)

forced-safety-enchant

Data Type	Default Value
Boolean	on

Enable forced safety enchantments (up max lvl)

enable-vibrant-visuals

Data Type	Default Value
Boolean	on

Enable vibrant visuals effects support

enable-raytracing

Data Type	Default Value
Boolean	on

Enable raytracing support

temp-ip-ban-failed-xbox-auth

Data Type	Default Value
Boolean	off

Temporary ban failed Xbox authentication

strong-ip-bans

Data Type	Default Value
Boolean	off

Strong IP bans

check-op-movement

Data Type	Default Value
Boolean	off

enable movement checking for operators

vanilla-armor-reduction

Data Type	Default Value
Boolean	on

Use the vanilla armor damage reduction formula.

When enabled, damage reduction follows the vanilla Bedrock formula: a non-linear armor/toughness curve that accounts for the Breach enchantment, and a deterministic Enchantment Protection Factor (EPF) capped at 20 (no random multiplier). Damage modifiers are applied in the vanilla order: ARMOR → ARMOR_ENCHANTMENTS → RESISTANCE → ABSORPTION.

When disabled, the legacy linear formula is used instead: armor reduces damage × armorPoints × 4%, EPF is scaled by a random 50%–100% multiplier, and toughness/breach are ignored.

note

Keep this enabled unless you need to preserve pre-1.21 combat behavior for backwards compatibility.

vanilla-knockback-resistance

Data Type	Default Value
Boolean	on

Use the vanilla armor knockback resistance formula.

When enabled, each worn netherite armor piece resists 10% of incoming knockback (a full set resists 40%), matching vanilla Bedrock behavior. The total resistance is also synced to the client as an attribute, so client-side prediction matches the server.

When disabled, armor no longer contributes knockback resistance and players take knockback at full strength (legacy behavior). Knockback resistance from other sources, such as entity attributes set by plugins, is not affected.

netease-settings (NetEase Settings)

client-support

Data Type	Default Value
Boolean	off

Enable NetEase client support will allow NetEase players to enter the server

only-allow-netease-client

Data Type	Default Value
Boolean	off

Only NetEase players are allowed to enter the server, and after opening, Microsoft version players will be prohibited from entering the server, and only NetEase players will be allowed to join the server

custom-block-settings (Custom Block Settings)

auto-download-vanilla-palette

Data Type	Default Value
Boolean	on

Automatically download vanilla block palettes (vanilla_palette_*.nbt) from the official mirror when missing.

This is required for custom block support across multiple client protocol versions. Files are cached in the bin/ folder and verified with SHA256.

If disabled, you must manually prepare the palette files in the bin/ folder.

use-hashed-block-network-ids

Data Type	Default Value
Boolean	on

Send hashed block network IDs (blockNetworkIdsHashed) to 1.19.80+ clients, including NetEase clients, instead of legacy runtime IDs.

Enabled by default even without custom blocks; hashed IDs are persistent across versions.

note

No effect on protocol versions below 1.19.80.

Always forced on when custom blocks are registered.