Ramjet.toml

server.properties keeps the vanilla keys. Everything else that is specific to Ramjet lives in ramjet.toml, next to it in the server directory (--config <file> points somewhere else).

The file creates and completes itself

• Missing file: it is written on the first start with every key at its default, grouped in [sections], with a comment above each key.
• Keys missing (an older file after an update): only the missing keys are inserted, with their comments, into their sections. Your values, comments, formatting and order are never changed, and a table the file lacks is appended at the end.
• Unknown keys produce a warning and are kept. Invalid or out-of-range values produce a warning and the default is used for that key (the text stays as you wrote it).
• The file is written atomically (a temporary file, then a rename). Changes apply on the next start.

Precedence

1. Command line: --workers, --memory-profile, --plugins <dir>, --verbose, and --set section.key=value for any key (repeatable, e.g. --set worldgen.burst_workers=6). An invalid value on the command line stops the server with exit code 2.
2. Environment variables (MC_GEN_BURST, MC_MEMORY_PROFILE, … listed in the tables): kept for tests and benchmarks. An invalid value is reported and ignored.
3. ramjet.toml.
4. The built-in default.

At startup the server logs every setting that differs from its default together with where the value came from. The legacy memory-profile and worker-threads keys of server.properties still work while ramjet.toml leaves the setting at its default.

Test-only hooks (MC_FORCE_SWEEP, MC_MEM_SITES, RAMJET_TEST_*, MC_BOT_*, …) are environment-only and not settings.

Reference

The tables list the default the file is generated with. A default written as hardware threads - N depends on the machine the server runs on. The reference covers every key the server reads; the sections below follow the file’s [sections].

[cpu]

CPU count the thread pools are sized for.

Key	Default	Meaning
threads	0	CPUs the server sizes its thread pools for (0 = auto: the process affinity and the container CPU quota, like Java’s availableProcessors). [0..1024]

[memory]

Memory profile, trimming and the memory governor. The profile decides how many chunk workers generate at once and whether buffers are pooled.

Key	Default	Meaning
profile	"low"	low: few generating workers, nothing pooled, caches trimmed when idle (~30-40 MB). throughput: all cores, pooled buffers. One of: low, throughput. Environment: MC_MEMORY_PROFILE.
trim_idle_seconds	30	Hand freed heap memory (and, low profile, the untouched pages of the working set) back to the OS once no chunk work (loads, generation, saves) has started for this long; once per idle period, not on a timer (0 = never). Bursts trim their heap when they end anyway. [0..86400]
trim_max_players	4	Low profile: skip the idle working-set trim while more than this many players are in the game. [0..100000]
deflate_idle_per_level	2	Idle libdeflate compressors (per level) and decompressors kept for reuse; the rest are freed when returned (0 = keep none). [0..64]
limit_mb	0	Memory the process must stay under, in MiB (0 = auto: the container / job limit, cgroup memory.max). Derives the chunk worker cap, the chunk work-in-flight budget and the low profile when those are left at auto, and drives the pressure governor. Set it on a host that does not expose its limit to the process. [0..1048576]
file_reserve_mb	28	Linux: memory kept free of anon usage for the process’s file-backed pages (its executable’s text, libraries and mapped files), in MiB. The reserve is the larger of this and the measured file-backed bytes, capped at a third of the limit; the thresholds are percentages of the limit less it. Ignored on Windows. [0..1024]
pressure_high_pct	75	Usage (percent of the effective limit: the limit less the file reserve) from which the governor holds back chunk work beyond the chunks nearest to the players, halves the work-in-flight budget, releases idle chunk packets, unloads without the grace period and trims the heap once a second. Default 75, or 65 for limits up to 256 MiB (when left at the default). [10..99]
pressure_critical_pct	88	Usage from which chunk work runs one unit at a time (nearest first) and the rebuildable caches are dropped; saves are never held back. Levels are left 5 points below their threshold (hysteresis). Chunks are only delayed, never skipped. Default 88, or 80 for limits up to 256 MiB (when left at the default). [11..100]
pressure_unload_grace_ticks_high	0	Grace period (ticks) before an unload while the governor is high, in place of unload_delay_ticks (the shorter of the two applies, so this never lengthens it). Ring and border chunks wait it after the scan has picked them. [0..1200000]
pressure_unload_grace_ticks_critical	0	Grace period (ticks) before an unload while the governor is critical (the shorter of this and unload_delay_ticks applies). [0..1200000]
pressure_scan_lap_ticks	4	Ticks for the border / generation ring scan to visit every holder once while the governor is high (critical: a quarter of this, at least 1). Normal pressure uses the same lap (4): an unload leaves within a few ticks of its release. The scan’s cost per tick is holders / lap. [1..64]
adaptive_radius	true	Under sustained critical memory pressure the chunks each player holds shrink one step at a time: the border band keeps one ring, then the held square goes from simulation distance + 2 to + 1 and to + 0 (the chunks beyond are released once the client has them), then the player’s simulation distance drops (the last step, observable), most isolated player first. Undone in reverse order below the high line. Needs chunks.view_only_beyond_simulation.
min_simulation_distance	3	The lowest effective simulation distance the adaptive radius may cut a player to (the last step of the shedding). Beyond it nothing is shed. [2..32]
shed_escalate_seconds	5	Seconds at one shedding step before the next one is taken, while the governor is critical. [1..3600]
shed_restore_seconds	15	Seconds at one shedding step before it is undone, while the usage is below the high line (normal). [1..3600]
unload_cache_kb	4096	Bytes (KiB) of the encoded NBT of recently saved chunks kept in memory, so a chunk demanded again soon loads from them instead of the region file (LRU; dropped when the chunk is saved or cleared again). 0 = off; the critical pressure level always drops it. [0..1048576]
arena_page_kb	8	Chunk arena page size in KiB: 4, 8 or 16 (other values round down). A page goes back when its last blob goes, so smaller pages drain in smaller pieces, but each retired page keeps a larger uncarved tail. Read once at startup. Windows only. [4..16]
arena_waste_ratio	1.25	A chunk arena region is compacted once its pages hold more than this multiple of its live bytes (plus four pages). Windows only. [1.0..16.0]
arena_sparse_page	0.75	An arena page at most this share live is sparse: compaction moves the unshared blobs of a chunk out of it. Windows only. [0.05..1.0]

[worldgen]

Chunk generation: worker threads, the join / teleport burst, priorities, structure caches and tick-thread budgets.

Key	Default	Meaning
workers	0	Chunk worker threads for generation, lighting and saving (0 = auto: hardware threads - 2). –workers overrides it. [0..256]
burst_workers	hardware threads - 4	Workers that may generate at once while a player joins or teleports (0 = fixed 3, the old low profile). Default: hardware threads - 4. [0..256] Environment: MC_GEN_BURST.
idle_workers	3	Workers that generate at once outside a join / teleport burst (low memory profile). [1..256]
burst_threshold	24	Chunks a player is waiting for from which generation counts as a burst. [1..1000000]
priority_below_normal	true	Run generation tasks at below-normal OS priority so the tick thread and the network win the CPU. Environment: MC_GEN_PRIORITY.
chunk_priority_by_distance	true	Serve entering chunks nearest first (false = plain enumeration order, for A/B measurements). Environment: MC_CHUNK_PRIORITY.
noise_simd	"auto"	SIMD noise sampling; the output is bit-identical either way. auto: only where it is faster. One of: auto, on, off. Environment: MC_NOISE_SIMD.
dispatch_depth	4	Generation tasks kept dispatched per allowed worker (queued or running until the tick thread integrates them): the workers idle when the tick thread is away longer than the queue holds; each queued result costs ~100-200 KB until integrated. [1..64] Environment: MC_DISPATCH_DEPTH.
eager_dependencies	true	Dispatch terrain / decoration tasks before the results they need have been integrated; the worker waits for the result of the other worker (bounded by chain_wait_ms) instead of handing the step back to the tick thread. Environment: MC_EAGER_DEPS.
chain_wait_ms	8.0	Floor of a worker’s total wait budget for in-flight dependencies (it follows the measured terrain job time, at most 50 ms) before the step goes back to the tick thread; 0 = never wait. [0.0..100.0]
density_slab_rows	16	Evaluate the terrain density in y slabs of this many rows (cache resident intermediates; same output). 0 = the whole chunk at once. [0..4096] Environment: MC_DENSITY_SLAB_ROWS.
surface_specialize	true	Run the material rules below the preliminary surface through per-y-range specialised programs (same output; false = the plain interpreter). Environment: MC_SURFACE_SPECIALIZE.
surface_columns	true	Phase 3: walk every column of the surface build over a contiguous copy of its blocks instead of the y-major terrain buffer (same output; false = the reference loop).
carver_fast	true	Phase 3: cave ellipsoids carve one run of bits per column instead of testing every y, and the carving mask is applied by word-wise run scans (same output; false = the reference loops).
fill_fast	true	Phase 3: the terrain block loop scans the air above the aquifer’s highest level for solid blocks 16 densities at a time instead of asking the aquifer per block (same output; false = the reference loop).
heightmap_copy	true	Phase 3: a decoration stores the feature world’s live heightmaps into the chunks it wrote instead of re-priming them from the blocks, and reads them back in bulk (same output; false = prime_heightmaps).
poll_budget_ms	4.0	Tick-thread time per tick for integrating finished generation results (idle pump). [0.0..1000.0]
phase_poll_budget_ms	2.0	Same, for the pumps between the tick phases. [0.0..1000.0]
template_reload_budget_mb	4	MB of reloaded structure templates kept for reuse (byte-bounded LRU; templates are re-read from the datapack when evicted). At its default: 4 MB, 2 MB in the low memory profile. [0..4096]
template_cache_budget_mb	0	MB of structure templates the jigsaw expansion and the place commands keep in a byte-bounded LRU (copies are re-read when evicted). 0 = the profile’s default (low 1, throughput unbounded). [0..4096]
structure_start_cache_mb	16	MB of structure start lists kept with their pieces, LRU; the budget applies to each dimension’s start cache. At its default: 16 MB, 4 MB in the low memory profile. Evicted starts regenerate from the seed when a placement needs them; a start with placed state not yet saved is never evicted. The summaries of every start stay in memory whatever this is. [0..4096]
scratch_idle_seconds	5	Seconds without chunk work (generation, decoration, light, packet encoding) after which the workers’ scratch (pipelines, feature worlds, buffer pools, light solve scratch, deflate handles) is freed; the next use rebuilds it. Once per idle period; 0 = never. [0..86400]

[world]

Saved world handling.

Key	Default	Meaning
backup_before_upgrade	true	Copy the whole world folder (as <world>pre<version>_backup) before a world from an older data version is upgraded. Needs free disk space of the world’s size. Environment: MC_WORLD_BACKUP.

[chunks]

Chunk loading, saving and unloading rates, the storage tier sweep, view streaming, and what a freshly generated chunk may cost the tick thread.

Key	Default	Meaning
unload_delay_ticks	0	Grace period before a chunk without a ticket is unloaded (0: it leaves in the next tick). [0..1200000]
max_unloads_per_tick	64	Chunks unloaded per tick at most. [1..100000]
autosave_interval_ticks	6000	Ticks between autosaves of a loaded chunk (0 = only on unload and save-all). [0..100000000]
max_saves_per_tick	64	Chunks snapshotted for saving per tick at most. [1..100000]
max_saves_in_flight	512	Background save jobs outstanding at most (unloads wait beyond this). [1..1000000]
max_loads_in_flight	256	Anvil loads outstanding at most. [1..1000000]
inflight_memory_mb	0	Memory a dimension may hold in chunk work in flight (jobs dispatched and not integrated, loads, the stored light of loaded chunks waiting for their light prep, saves not yet written), estimated per job: dispatch pauses at the budget and resumes as the tick thread and the IO thread drain it. 0 = the profile’s default (low 24, throughput 256). [0..65536]
max_registrations_per_pump	128	Chunks registered with the world per tick at most. [1..1000000]
full_per_tick	32	Chunks that may become FULL (ticking, spawning) per tick; the rest wait (0 = unbounded). [0..1000000]
full_budget_ms	3.0	Tick-thread time per tick for the listeners of fresh chunks (0 = unbounded). [0.0..1000.0]
integrate_budget_ms	2.5	Tick-thread time per tick for integrating finished chunk loads and generation results; the rest waits for the next tick, in order (0 = unbounded). [0.0..1000.0]
integrate_min_per_tick	4	Finished results integrated per tick at least, however long they take (so a small budget still makes progress). [1..1000000]
tick_budget_ms	6.0	Tick-thread time per game tick for ALL chunk work of one dimension: the in-tick pumps, the integration, dispatch and FULL promotion (the rest runs in the idle time between ticks; 0 = unbounded). [0.0..1000.0]
post_process_budget_ms	2.0	Tick-thread time per tick for the post-processing (settling fluids, plants and block shapes) of chunks entering the ticking set; a chunk’s marks continue on the next tick (0 = unbounded). [0.0..1000.0]
unload_per_tick_burst	16	Unloads per tick while a join / teleport burst is pending. [0..100000]
unload_budget_ms_burst	2.0	Tick-thread time per tick for unloads during a burst. [0.0..1000.0]
unload_budget_ms	3.0	Tick-thread time per tick for unloads and autosave snapshots outside a burst (0 = unbounded; at least 4 unloads go per tick). [0.0..1000.0]
unload_drain_ticks	40	Unloads per tick grow with the backlog so that the chunks waiting for their unload are gone within this many ticks (never fewer than max_unloads_per_tick; 0 = the fixed caps only). [0..1000000]
autosave_budget_us	500	Tick-thread time per tick the autosave snapshots get of their own (microseconds) when the unloads spent the shared unload budget (0 = the shared budget only, one snapshot per tick at least). [0..1000000]
unload_in_idle	true	Unload due chunks in the idle time between ticks as well (the tick’s own unload budget is unchanged); a teleport storm is then drained with time the tick thread had nothing to do in.
unload_burst_backlog	1024	Unload backlog (chunks waiting for their unload) above which a pending join / teleport burst unloads with the normal budget (unload_budget_ms) instead of the 2 ms burst budget (0 = always the burst budget). [0..100000000]
unload_hold_near_priority	4	Chunks nearer a player than this (Chebyshev distance) are never held back by the far-ring hold. [0..254]
unload_hold_backlog	1500	While more chunks than this wait for their unload (and something is in flight), generation of the chunks beyond unload_hold_near_priority waits, so a teleport’s old area is freed before the new one is loaded (0 = off; at most 100 ticks per hold). [0..100000000]
unload_skip_grace_on_teleport	true	A view change that releases at least 64 chunks (a far teleport) unloads them without the unload_delay_ticks grace period.
ring_keep_distance	1	Generation ring: a partially generated chunk (terrain / features) that no pending step needs is saved and dropped, and loads again when demanded. A chunk within this many chunks of a registered or acquired chunk stays loaded: 1 keeps only the feature ring (decorated, always kept), 2 also keeps the terrain ring. The hysteresis against walking churn is the unload grace (unload_delay_ticks) and the scan lap, not this value. 0 = keep the whole ring (the old behaviour). [0..4]
border_keep_distance	1	Border band: a registered chunk that no player holds and that is more than this many chunks from every acquired chunk is saved and dropped after the unload grace, and loads again when it comes back into the band. 1 keeps the chunks next to the acquired area (what the light of the acquired area reads, and the minimum); 2 also keeps the next ring, which closes the light gap for commands that edit the outer band. 0 = keep every registered chunk the demand rings reach (the old behaviour). [0..4]
sweep_chunks_per_tick	8	Storage tier sweep: chunks visited per tick, round robin (packs idle sections and light layers, expands hot spots, freezes chunks nobody simulates; 0 = off). [0..100000]
sweep_lap_seconds	20	Storage tier sweep: a full lap over the holders takes at most this many seconds (the per-tick count rises with the holder count; the time budget still bounds every tick). 0 = sweep_chunks_per_tick flat. [0..100000]
sweep_budget_us	200	Tick-thread time per tick for the storage tier sweep, in microseconds (0 = unbounded). [0..1000000]
sweep_hot_reads_per_tick	1.0	A packed section read more often than this per tick (sampled reads, 1 in 16 is counted) is expanded to the fast layout; random ticks stay below it. [0.0..100000.0]
packed_write_hot_threshold	16	A packed block section written at least this many times per second (over the window since its last sweep visit) is expanded to the hot layout by the sweep; 64 writes to one section within one tick expand it at once (bulk edits). 0 = sustained writes never expand it. [0..100000]
hot_section_idle_seconds	10	Storage tier sweep: a hot block section that has not been written for this many seconds is packed on its next visit, however many laps that takes (0 = the lap rule: packed after two sweep visits without an edit). [0..100000]
hidden_freeze_idle_seconds	30	Storage tier sweep: a packed block section of a ticking chunk that no sweep saw read for this many seconds, and that is solid rock (no air, no fluid, no randomly ticking block), is frozen to the cold tier; a read thaws it on the next sweep (0 = off). [0..100000]
cold_nonticking_seconds	2	Storage tier sweep: a loaded chunk that no player simulates freezes its block sections once they have been unwritten for this many seconds (its light goes cold at the same visit), instead of at the next lap of the sweep. A chunk that enters or leaves the ticking set is visited at once; its tick caches are dropped on the same visits and its cached packets are released after this idle time (0 = off: the lap alone). [0..100000]
pack_on_worker	true	Generation jobs pack the chunks they have finished with (a decoration’s last write, a light prep) while they own them, so new terrain does not wait for the storage sweep to rest packed (false = only the packs of the terrain and LIGHT_INIT steps).
pack_proto_chunks	true	The terrain job of a decorated world packs the new chunk before it waits for its neighbours’ decorations (a terrain-stage chunk is not written until a neighbour decorates, and its sections rest packed meanwhile; false = they stay hot until the sweep).
packet_wait_ticks	4	Ticks a viewer’s chunk send waits for the background rebuild of a chunk packet whose cache is behind an edit before the tick thread builds it itself (the chunk stays pending meanwhile; 0 = build at once on the tick thread). [0..1000]
packet_keep_ticks	200	Low memory profile: a loaded chunk’s cached packet (~6 KB) is released after this many ticks without a viewer asking for it and rebuilt in the background for the next one (the same bytes; vanilla builds every chunk packet at send time). 0 = keep every packet. [0..1000000]
view_ops_per_tick	512	Chunk acquire / release calls the players’ view changes may make per tick, shared by every player (each gets at least 32): a far teleport owes ~2,100 of them (view 10) and they run over the following ticks, the player’s own chunks first, instead of all in the tick of the teleport. [32..1000000]
view_only_beyond_simulation	true	A chunk a player sees beyond the simulation square (simulation-distance + 2) is released by the server once the client has it, unless a non-player entity in it is in tracking range of the player: the client keeps it (no forget packet), the server keeps no chunk state for it, and it is loaded again when the player comes closer (no resend). Block and light updates still reach the client while it has the chunk. false = every chunk in the view stays loaded.
view_stream_window	256	View streaming: at most this many view-only chunks (beyond the simulation square) per player are demanded at a time, until the client has them and their view hold is released; the rest of the view waits, nearest first (vanilla’s send order). With memory.limit_mb set the window is at most 64 at high pressure and 16 at critical. [1..1000000]

[entities]

Entity loading.

Key	Default	Meaning
load_budget_ms	3.0	Tick-thread time per tick for adding the saved entities of freshly loaded chunks to the world, whole chunks in load order; the rest follows in the next ticks (vanilla adds them asynchronously too). 0 = unlimited. [0.0..1000.0]

[light]

Lighting of chunks and block edits.

Key	Default	Meaning
async_updates	true	Apply the light updates of block changes on a worker thread (vanilla’s light thread) and build the light packets there; the tick thread only snapshots the edited chunks and installs the result. false = on the tick thread (A/B, tests). Environment: MC_LIGHT_ASYNC.
verify	false	Verification harness: gameplay sky / block light reads and one settled chunk per light pass are compared with a fresh solve of their 3x3 blocks; mismatches are counted and the first ones logged. Debugging only (a solve per sample). Environment: MC_LIGHT_VERIFY.
persist	false	Save the light of chunks (isLightOn + the light sections). false = chunks are saved without light and vanilla recomputes it on load: smaller saves and no light arrays in memory on load. Light stored in older saves is recomputed (not read) while this is off. Environment: MC_LIGHT_PERSIST.

[network]

Transport: IO threads, connection limits and compression level.

Key	Default	Meaning
io_threads	0	Network IO threads (0 = auto: hardware threads / 4, at least 1). [0..256]
max_connections	10000	Open connections at most; excess ones are closed at accept (0 = unlimited). [0..10000000]
max_accepts_per_ip_per_second	0	Connection attempts per source IP per second (0 = off; 5-10 is sensible for public servers). [0..100000]
max_outbound_backlog_ms	10000	Kick a client whose oldest unsent byte is older than this (0 = off). [0..3600000]
compression_level	1	libdeflate level for packets and chunks. The compression threshold stays in server.properties. [1..12]

[plugins]

C# plugins (off by default). --plugins <dir> turns them on for one run.

Key	Default	Meaning
enabled	false	Load C# plugins (needs the built managed runtime). –plugins <dir> turns this on for one run.
directory	"plugins"	Folder with the plugins (<Name>/<Name>.dll), relative to the working directory.
hot_reload	true	Reload a plugin when its files change.
allow_source	true	Compile .cs plugins (single files or source folders) with Roslyn at runtime. They run with the same full trust as dlls; false refuses them.

[permissions]

Permission checks for vanilla commands.

Key	Default	Meaning
enforce_vanilla_nodes	"warn"	Vanilla commands and the permission table (minecraft.command.<name> nodes): off = the operator level alone; warn = the level decides and a line is logged where the table would answer differently; on = the table decides where it has an answer. One of: off, warn, on.
server_id	0	The server id of the context tuple (permission rules can name a server of a network). 0 for a standalone server. [0..254]

[access]

Limits on the ban lists and the player profile file that plugins may change.

Key	Default	Meaning
max_ban_entries	10000	Most entries that scripts may add to banned-players.json and to banned-ips.json (each list). A script’s new ban beyond it is refused; replacing one is kept; expired entries make room. Operator bans are never refused. Entries loaded from the file count until an operator writes them again. [1..10000000]
max_ban_bytes	4194304	Most bytes (key, reason, source and name or address) of the entries that scripts may add to each ban list. A script’s new ban beyond it is refused, as with max_ban_entries. [1..1073741824]
max_profiles	10000	Most players in playerprofiles.json (first join and last seen times). A new player beyond it evicts the one seen least recently. [1..10000000]

[scripting]

Where C# plugins run and the limits of the plugin worker process.

Key	Default	Meaning
mode	"remote"	Where C# plugins run: remote (the sandboxed worker process) or off. One of: remote, off.
worker_path	""	Worker for mode remote: the ramjet-script executable next to the server, or with a launcher Mc.Scripting.Worker.dll (empty = that default).
launcher_path	""	Linux: sandbox launcher (ramjet-script-launch) the worker starts through, with dotnet. Empty = start the worker directly. Production builds always use the launcher that ships with it. Ignored on Windows.

[scripting.ipc]

Messages between the engine and the plugin worker: waits and budgets.

Key	Default	Meaning
ring_bytes	4194304	Size of each engine <-> worker ring (two per worker). Must be a multiple of 8. [1048576..1073741824]
event_budget_us	5000	Longest wait for a plugin’s answer to a cancellable or mutable event; on expiry the event keeps its default. [1..10000000]
warmup_budget_us	250000	How long the engine waits for the plugin worker the first time it sends each event type or command check: the plugins’ code runs (and is compiled) for the first time then. Later ones use event_budget_us. [1..10000000]
command_budget_us	250000	Longest wait for a plugin command to finish running (a player’s command runs to the end, as for in-process plugins; the first run also compiles the plugin’s code). Requirements and suggestions use event_budget_us. [1..10000000]
tick_end_grace_us	250000	How long the engine waits for the plugin worker to end a tick before it counts as stalled (the worker is restarted). Past tick_budget_us the tick is only slow, with a warning. [1..10000000]
command_tick_budget_us	500000	Time per tick the plugin command runs together may wait (command_budget_us each): a run after it is spent fails at once. Three runs in a row that time out mute the worker’s command runs for 5 s. [1..10000000]
tick_budget_us	20000	Time per tick the engine spends waiting for the worker (awaited events together, then the tick end). [1..10000000]
log_per_second	200	Log lines the engine writes for the worker per second; the rest are dropped and counted. [1..100000]
ready_budget_us	60000000	Longest time from the worker’s HelloAck to its ready state (its plugins are loaded by then). [1000000..600000000]
max_command_nodes	65536	Command nodes (and their trampolines) the workers’ command trees may make in this server process, over every worker restart: they are never freed, so this bounds their memory. A plugin’s command beyond it is refused. [512..16777216]

[scripting.channels]

Plugin messaging channels.

Key	Default	Meaning
per_player_per_tick	64	Messages one client may send on a channel a plugin listens on per tick (a message beyond it is dropped and counted). [1..10000]
incoming_bytes_per_tick	262144	Bytes of client messages forwarded to the plugins per tick, all players together (beyond it messages are dropped and counted). [0..16777216]
send_bytes_per_tick	262144	Bytes plugins may send to clients per tick (Player.SendPluginMessage beyond it returns false). [0..16777216]

[scripting.packets]

Packets a plugin sends or observes, and the entity ids it may hold.

Key	Default	Meaning
observe_per_player	512	Observe copies of packets (the plugin’s Packets.On in observe mode) sent per player per tick; the rest are dropped and counted. [1..65536]
observe_per_window	8192	Observe copies of packets sent per tick, all players together. [1..1048576]
send_bytes_per_player	16384	Bytes of packets a plugin sends (Packets.Send) to one player per tick; a packet beyond it is not sent. [1..1048576]
send_bytes_per_window	262144	Bytes of packets a plugin sends per tick, all players together. [1..16777216]
max_virtual_ids	4096	Entity ids a plugin’s worker may hold at once (Packets.AllocateEntityId): the fake entities it has spawned on clients. [16..65536]
mute_after	3	Intercepts of one packet type that get no verdict within the budget, in total, before that type’s intercepts stop (until the worker restarts). [1..1000]

[scripting.worker]

The plugin worker process.

Key	Default	Meaning
memory_mb	0	Memory limit of the worker in MiB (0 = none). Windows: enforced by the job object; Linux: not enforced by the engine yet (launcher). [0..1048576]
max_entities	10000	Entities the worker may create at once (ecs_entity_create); they are destroyed when the worker goes away. [0..1000000]
restart_per_minute	5	Worker restarts allowed per minute (with backoff) before scripting stays off until the server restarts. [1..1000]

[scripting.visuals]

Holograms, NPCs and fake blocks shown by plugins.

Key	Default	Meaning
max	512	Holograms and NPCs the plugins may have at once (each is an entity of the entity tracker: a pairing per viewer in range). [16..65536]
max_fake_blocks	1024	Fake blocks one player may be shown at once (a plugin’s per-player block overlay, re-sent with its chunk). [1..65536]

[scripting.presence]

The per-viewer tab list, nametag and objective overlay of plugins.

Key	Default	Meaning
max_teams_per_viewer	256	Overlay teams (nametag styles) one viewer may have at once; a new team beyond it is refused. [1..4096]
max_members_per_viewer	1024	Team memberships (targets with an overlay nametag) one viewer may have at once. [1..65536]
max_scores_per_viewer	1024	Scores on one viewer’s overlay objectives (below-name and list slots) at once. [1..65536]
max_fake_entries_per_viewer	80	Fake tab entries (layout slots) one viewer may have at once. [0..256]
max_packets_per_tick	512	Packets written for one viewer per tick; a viewer with more changes gets the rest on the next tick. [1..65536]
max_bytes_per_tick	65536	Encoded bytes written for one viewer per tick (on top of the packet count); the rest waits for the next tick. [1024..16777216]
max_bytes_per_viewer	131072	Charged bytes (source bytes plus 256 per JSON value) of the values one viewer’s overlay may hold at once; a set beyond it is refused. [1024..16777216]
max_objectives_per_viewer	8	Overlay objectives (list and below-name slots) one viewer may have at once. [1..256]

[scripting.http]

HTTP(S) requests the engine makes for plugins.

Key	Default	Meaning
enabled	true	Plugins may make HTTP(S) requests through the engine (Http.Client). false refuses them all.
ports	"80,443"	Ports plugin HTTP requests may use (comma separated, 1..65535).
allow_hosts	""	Host names plugins may reach (comma separated; empty = any name; a name covers its subdomains too). Addresses are always vetted: loopback, private, link-local and the other non-public ranges are never reached.
deny_hosts	""	Host names plugins may not reach (comma separated; subdomains included).
timeout_ms	10000	Total time of one plugin HTTP request, redirects included. [100..60000]
connect_timeout_ms	5000	Time to connect one plugin HTTP request. [100..30000]
max_request_bytes	262144	Largest request body a plugin may send. [0..524288]
max_response_bytes	524288	Largest response body handed to a plugin (also lowered to what one IPC record can carry, scripting.ipc.ring_bytes / 2). [1024..524288]
max_in_flight	8	Plugin HTTP requests in flight on the whole server. [1..64]
max_in_flight_per_plugin	4	Plugin HTTP requests in flight per plugin. [1..64]
max_requests_per_minute	120	Plugin HTTP requests one plugin may start per minute. [1..100000]
max_total_requests_per_minute	600	Plugin HTTP requests the whole server may start per minute, across all plugins. [1..1000000]
threads	2	I/O threads of the plugin HTTP client. [1..8]

[content]

Custom content: block states of custom blocks and the built-in resource pack server.

Key	Default	Meaning
state_file	"content/blocks.json"	File remembering which block state each custom block (Mc.Scripting.Content) uses, so a restart keeps the same state for the same block id.
pack_host_port	0	Port of the built-in web server that hands out the resource packs plugins build (ResourcePackHost.Publish). 0 = off: plugins then use their own URL. [0..65535]
pack_host_bind	"127.0.0.1"	Address the resource pack server listens on (127.0.0.1 = this machine only, 0.0.0.0 = every interface; set pack_host_url then).
pack_host_url	""	Base URL the clients use to reach the resource pack server (default http://<bind>:<port>).

[debug]

Logging and tracing aids.

Key	Default	Meaning
verbose	false	Debug logging (same as –verbose).
chunk_trace	false	Log slow ticks and chunk burst timings (cost split of a stall). Environment: MC_CHUNK_TRACE.
chunk_trace_file	""	File prefix for the per-task chunk trace (empty = off). Environment: MC_CHUNK_TRACE_FILE.
piece_trace	false	Log structure piece generation. Environment: MC_PIECE_TRACE.
system_profile_ticks	0	Every this many ticks, log the systems that took the most tick-thread time since the last report (0 = off). [0..72000]

[parallel]

Work items below these counts run inline on the tick thread instead of waking a worker.

Key	Default	Meaning
living_physics_min_items	128	Living bodies (physics::tick_living_bodies) below this count tick inline on the tick thread. [0..10000000]
player_physics_min_items	4	Player bodies (movement) below this count tick inline on the tick thread. [0..10000000]
tracker_sync_min_entities	1024	Tracked entities below this count are synced inline by the entity tracker (no worker is woken). [0..10000000]
mob_ai_min_items	32	Mobs below this count run their AI and post step inline on the tick thread. [0..10000000]
item_physics_min_items	128	Item entities below this count tick their physics inline on the tick thread. [0..10000000]
min_parallel_us	200	Adaptive parallel loops: a call site whose measured serial cost is below this many microseconds runs inline on the tick thread (no worker is woken). [0..1000000]

[engine]

The ECS engine.

Key	Default	Meaning
direct_dispatch	true	Immediate engine systems run one by one without the flecs pipeline; the others keep their pipeline runs. Off = one pipeline per phase.

[profiler]

The tick profiler behind the /profiler command.

Key	Default	Meaning
enabled	true	Tick profiler: per-system and per-bucket timings behind the /profiler command (a few adds per tick).
spike_ms	50.0	Ticks slower than this are kept (the last 20) by /profiler spikes. [1.0..100000.0]
report_dir	"debug/profiler"	Directory of the /profiler recording reports (relative to the server directory).
memory_world_s	0	Seconds between the chunk providers’ memory breakdowns in the profiler’s memory samples (one walk of every loaded chunk per dimension each time, tens of ms on the tick thread at 50 players: 0, the default, takes the world rows only at the end of the window; the process counters are read every second). [0..60]

[ticks]

Block ticking.

Key	Default	Meaning
random_tick_mode	"sampled"	sampled: per section the random ticks among the randomTickSpeed picks are drawn directly from vanilla’s distribution (same statistics, far fewer reads). vanilla: the pick-by-pick LCG loop (the exact vanilla sequence, for parity tests). One of: sampled, vanilla.
parallel_chunk_ticks	true	Random ticks and precipitation run on the job system workers over islands of entity-ticking chunks that are too far apart to interact in one tick; their global effects are applied on the tick thread afterwards in island order.
parallel_min_chunks	1024	Fewer entity-ticking chunks than this keep the serial chunk-tick loop (one player at simulation distance 10 is 441 chunks). [0..10000000]
parallel_island_margin	2	Cell size (chunks) of the island partition: chunks of different islands are more than this many chunks apart. 2 is enough for every vanilla random tick’s reach; larger merges more islands. [2..8]

[anti_xray]

Anti-xray (off by default): hides ores and other blocks in chunk packets until they are revealed.

Key	Default	Meaning
enabled	false	Anti-xray: chunk packets send the hidden blocks (below max_y, all six neighbours opaque) as the dimension’s filler (stone, deepslate below y 0, netherrack, end stone) until a change reveals them. Off = the vanilla bytes.
hidden_blocks	"minecraft:copper_ore, minecraft:deepslate_copper_ore, minecraft:iron_ore, minecraft:deepslate_iron_ore, minecraft:coal_ore, minecraft:deepslate_coal_ore, minecraft:lapis_ore, minecraft:deepslate_lapis_ore, minecraft:gold_ore, minecraft:deepslate_gold_ore, minecraft:redstone_ore, minecraft:deepslate_redstone_ore, minecraft:emerald_ore, minecraft:deepslate_emerald_ore, minecraft:diamond_ore, minecraft:deepslate_diamond_ore, minecraft:nether_gold_ore, minecraft:nether_quartz_ore, minecraft:ancient_debris"	Comma-separated block ids whose every state is hidden. Unknown ids are ignored.
max_y	64	Only blocks below this y are hidden (Paper’s max-block-height). [-2032..2031]
update_radius	2	Around a block change, the hidden blocks of the same chunk within this many blocks that are no longer enclosed are sent with their real state. [1..4]

[commands]

Vanilla command roots a plugin may take over.

Key	Default	Meaning
override	[]	Vanilla command roots a plugin may replace with its own command tree, with their redirect aliases: tp (also teleport), msg (also tell and w). Empty = none. One of: tp, msg.

[chat]

Chat mutes.

Key	Default	Meaning
mute_max_entries	4096	Most chat mutes the server keeps (chat-mutes.json in the server directory). A new mute beyond it is refused by chat_mute_set. [1..100000]
mute_notice	"You are muted ({remaining})."	The line a muted player gets when a chat message, /say, /me or /msg is refused. {remaining} is the time left (permanently for a mute with no expiry), {reason} the reason of the mute (empty when none).

Example

[memory]
profile = "throughput"      # all cores, pooled buffers: for 10+ players exploring new terrain

[worldgen]
burst_workers = 6           # fewer workers during a join / teleport burst

[plugins]
enabled = true
directory = "plugins"

See also server.properties and performance tuning.