Configuration

Basalt’s settings live in basalt.toml, in the folder Basalt is started from. The file is created on first start with every setting at its default and a comment above each one.

Build it instead

The config builder lets you set everything below with switches and dropdowns, then copy or download the finished basalt.toml.

How the file works

• It is TOML: one name = value per line. Text goes in quotes, lists in square brackets, true and false are written bare.
• Settings are read once, at startup. Restart Basalt after editing the file.
• A setting you leave out uses its default.
• A misspelled or unknown setting is an error: Basalt reports it and does not start, so a typo never silently does nothing.
• Two settings from older versions, vanilla_terrain and seed, no longer exist. If your file still has them, Basalt logs a warning and ignores them.
• When a new version of Basalt adds settings, they are appended to your file with their comments on the next start. Your own lines are not touched.
• Delete the file to get all defaults back.

server_name = "My Basalt"
world = "survival"
max_players = 30
view_distance = 10
gamemode = "survival"

General

Setting	Default	What it does
server_name	"Basalt"	The name shown in the server list.
world	"world"	The folder inside worlds/ to play. Created if it does not exist. See Worlds.
max_players	20	The most players allowed on at once.
gamemode	"survival"	The game mode a player gets the first time they join: "survival", "creative", "adventure" or "spectator".
force_gamemode	false	Puts every player in gamemode each time they join, not only the first time.
default_player_permission_level	"member"	The permission level of players not listed in permissions.json: "visitor", "member" or "operator". See Permissions, allowlist and bans.
allow_list	false	Only lets in players listed in allowlist.json. The allowlist on and allowlist off commands rewrite this line.
online_mode	true	Checks every player’s Xbox sign-in.
autosave_ticks	6000	Ticks between saving players and the world. 6000 ticks is five minutes.
enchant_bypass_limits	false	Lets /enchant and plugins put any enchantment on any item at any level up to 32767, ignoring vanilla’s maximum levels and conflicts. Off keeps vanilla’s rules.

Caution

With online_mode = false nobody’s identity is checked: anyone can join under any name and XUID, including an operator’s. Only turn it off where no one else can reach the machine.

Network

Setting	Default	What it does
signaling_port	19132	The TCP port clients use to start a connection.
media_port	19133	The UDP port game traffic uses.
advertised_addresses	[]	Public addresses to give clients when the host is behind NAT, for example ["203.0.113.10"].
compression_threshold	256	Packet batches smaller than this many bytes are sent uncompressed.
botnet_detection	true	Watches for several connections flooding packets at once. When three or more send over 300 packets a second together and look coordinated (they started together, send the same packet, share a subnet or have just connected), their addresses are disconnected and turned away for a minute.

World and simulation

Setting	Default	What it does
view_distance	8	The farthest chunk radius sent to a player, however far their client asks to see.
tick_distance	4	The chunk radius around each player where the world runs: mobs, random ticks such as crop growth, and the chunks kept for a while after a player leaves. At least 1; values above view_distance are treated as view_distance.
chunk_unload_delay	300	Seconds a chunk nobody is near stays loaded before it is saved and unloaded. The chunks around a player who leaves stay this long too, with what they dropped.
mob_ai	true	Runs mob AI: wandering, following, attacking and pathfinding. Off, mobs stand where they are, though they still fall, get pushed and can be hurt.
mob_ai_kinds	[]	Mobs that keep their AI while mob_ai is off, as "minecraft:zombie" or just "zombie".
max_threads	8	The most threads Basalt uses for connections and for chunk work. 0 uses as many as the machine has; a number above the machine’s count is lowered to it.
player_tick	true	Runs each player’s hunger: exhaustion, saturation, starving and the health food gives back. Off, players never get hungry and only heal by other means, which suits lobbies and kit servers.
client_side_chunk_generation_enabled	true	Tells clients they may generate the look of chunks beyond the ones Basalt sends.

Advice on choosing these values is on the Performance page.

Resource packs

Setting	Default	What it does
texturepack_required	false	Players must accept the packs in resource_packs/ to join; refusing disconnects them. The older name force_resource_packs is still accepted.
send_behaviour_packs	true	Also offers behaviour packs, which clients need for some addons. Resource packs are always offered.
resource_pack_chunk_size	262144	Bytes of a pack sent at a time (256 KiB).

See Resource packs.

Skins and graphics

Setting	Default	What it does
disable_custom_skins	false	Replaces skins made outside the Minecraft store and the character creator with the default skin.
disable_persona	false	Replaces character creator (persona) skins with the default skin.
skin_change_cooldown	30	Seconds a player must wait between changing skins in game. Changes made sooner are ignored.
force_skin_trusted	false	Treats every skin as trusted, whatever the client says about it.
disable_client_vibrant_visuals	false	Tells clients to use the next best graphics setting instead of Vibrant Visuals.

Plugin networking

These settings limit what plugins can do through @minecraft/server-net. See HTTP requests.

Setting	Default	What it does
script_net_enabled	true	Lets plugins make HTTP requests and open WebSockets.
script_net_allowed_hosts	[]	The hosts plugins may reach, as "discord.com", or "*.example.org" for any host under example.org. Empty allows any host. Host names are checked, not the addresses they resolve to.
script_net_max_body_bytes	8388608	The largest HTTP response body or WebSocket message a plugin takes in, in bytes (8 MiB).

Rate limits

Limits on what a single player’s client may send. rate_limit_enabled is the master switch: with it off, none of the limits in this table apply.

Setting	Default	What it does
rate_limit_enabled	true	Turns on the limits below.
max_inbound_packets_per_second	1500	Packets a player may send in a second. More is treated as flooding and disconnects them.
max_packets_per_tick	500	Packets a player may send in one 50 ms tick. Packets past the limit are dropped.
max_commands_per_second	10	Commands a player may send in a second; spamming more kicks them. 0 is no limit.
max_chat_per_second	2	Chat messages a player may send in a second; more are dropped. 0 is no limit.
max_form_responses_per_second	20	Form answers a player may send in a second; spamming more kicks them. 0 is no limit.
max_world_interaction_packets_per_second	0	Arm swings, sounds and other world interactions a player may send in a second; more are dropped. 0 is no limit.
max_movement_packets_per_second	40	Vehicle moves a riding player may send in a second; more are dropped. 0 is no limit.

Anti-cheat

Each check has its own switch, and all are on by default. With a check off, Basalt accepts what the client sends for that case. What each check looks for is described on the Anti-cheat page.

Setting	Default	What it does
anticheat_proxy	true	Disconnects players whose login shows the signs of a proxy rewriting it, with “Proxy Detected”.
anticheat_crash_packets	true	Drops packets made to crash other clients: eating events for food the player does not hold, sounds and emotes that are not real ones.
anticheat_fly	true	Pulls back players who jump again while already in the air with no way to fly.
anticheat_fast_break	true	Catches inputs that carry many ticks of block breaking at once.
anticheat_criticals	true	Gives no critical hit for a fall the player did not jump or step into.
anticheat_reach	true	Refuses blocks used, and players or mobs hit, through walls or from out of reach.
anticheat_inventory	true	Refuses moves into the armour slots made with old-style inventory transactions.
anticheat_self_hit	true	Drops a player’s hit on themselves, which an honest client never sends.
anticheat_scaffold	true	Refuses block placements that come far too fast to make by hand, or land on a face the player is not looking at.