Configuration du serveur

Tout ce que vous devez savoir pour configurer votre serveur !

Fichier de configuration du serveur

Le fichier de configuration du serveur Config.toml Ce fichier sera toujours remplacé par le bon modèle après le chargement du serveur.

tip

nanos world Config files use TOML (Tom's Obvious, Minimal Language), please refer to https://github.com/toml-lang/toml for more information and syntax.

Config.toml

loading...

See full example on GitHub

Paramètres détaillés

The Config file is split into a few sections. Each one is described below with its type, default value and accepted range.

note

The server rewrites Config.toml on every startup, after applying the Command Line Parameters and validating each value. Any comment you add, unknown key, or out-of-range value will be discarded or reset, the log will tell you exactly which setting got reset and to what.

[discover]

How your server presents (and announces) itself.

Paramètre	Type	Par défaut	Description
name	string	"nanos world server"	Name of the Server, as displayed in the Server List
description	string	""	Description of the Server. Clamped to 200 characters
language	string	"global"	Country code (e.g. br, us, de) used to display a country flag in the server list
ip	string	"0.0.0.0"	Address the server binds to, for both the game socket and the built-in HTTP Server. We recommend leaving it 0.0.0.0, which binds to every interface
port	integer	7777	Server main Port, used for both game traffic (UDP) and the built-in HTTP Server (TCP). Range 1024 - 65535
query_port	integer	7778	Server query Port (UDP), used by the Server List and by query tools. Range 1024 - 65535, and must be different from port
announce	boolean	true	Whether to announce the server in the Server List. A non-announced server is still joinable through Direct Connect
dedicated_server	boolean	true	true runs a Dedicated Server: requires port forwarding and gives the fastest connection. false runs it as P2P, which hands out a fake IP for players to connect through Steam Datagram Relay, no port forwarding needed, but higher latency, and the send rate is capped at 1024 KB/s by the relay service regardless of max_send_rate

[general]

Paramètre	Type	Par défaut	Description
max_players	integer	64	Max amount of players allowed to join. Range 1 - 999
password	string	""	Password required to connect. Leave it blank for no password required
	string	""	Server authentication token, used to authorize Vault downloads, through the CLI, through --auto_download, and when fetching Packages/Assets you own
banned_ids	string list	[]	List of banned nanos account IDs. Banned players are rejected at connection time

[game]

Paramètre	Type	Par défaut	Description
map	string	"default-blank-map"	map package to load. See Map & Level
game_mode	string	""	game-mode package to load, you can only load one game-mode at once
packages	string list	[]	script packages to load
assets	string list	[]	Additional Asset Packs to force loading, on top of the ones the loaded Packages/Map already require
loading_screen	string	""	loading-screen package to load, you can only load one loading-screen at once

[custom_settings]

A free-form table of your own values, made available to every Package through Server.GetCustomSettings(). Values can be strings, integers, floats or booleans.

[custom_settings]
    max_props = 1000
    enable_pvp = true
    welcome_message = "have fun!"

game-modes can declare which Custom Settings they accept, so they show up in the New Game screen, see Custom Settings. The whole table can also be passed on the command line with --custom_settings "max_props = 1000, enable_pvp = true".

[debug]

Paramètre	Type	Par défaut	Description
log_level	integer	1	Which Log level to output: 1 normal, 2 debug, 3 verbose. Levels 2 and 3 are noisy, use them to investigate a problem, not in production
async_log	boolean	true	Writes logs from a separate thread, which is faster. Set it to false when debugging a crash, so the last lines before the crash are guaranteed to be flushed
profiling	boolean	false	Enables Performance Profiling Logs, which report how long each internal operation took. Useful to find what is making your server tick slow. Can also be toggled at runtime with the profiling console command

[optimization]

Paramètre	Type	Par défaut	Description
max_tick_rate	integer	30	Server Tick in Hz, how many times per second the server loop runs. Range 15 - 120. Everything (network receive/send, Lua events, timers, etc) happens inside this loop, so a higher value is more responsive but multiplies CPU usage. 30 Hz means the server has 33ms to do all its work per tick, we recommend leaving it 30
max_sync_rate	integer	30	Max actors sync rate in Hz, how often actors location/rotation/velocity are synchronized. Range 1 - 30, and naturally limited by max_tick_rate. This value is also sent to the clients, so they sync back at the same rate. Lowering it is the cheapest way to cut bandwidth on servers with many moving actors, at the cost of less precise movement
max_send_rate	integer	1024	Max network send rate per client, in KB/s. Range 128 - 16384. Recommended setting to the lowest value that still fits your traffic, higher rates may negatively impact the server performance when having players with bad connections. P2P servers are capped to 1024 KB/s by Steam Datagram Relay. Can be changed at runtime with the max_send_rate console command
max_file_transfer_rate	integer	1024	Max file transfer rate per client, in KB/s, how fast Packages and Assets files are pushed to a connecting player. Range 128 - max_send_rate; anything above max_send_rate is clamped down to it. Lower it to keep downloads from starving the gameplay traffic of players already in game
compression	integer	1	Compression level applied to several networking operations. 0 disables it, 1 is the fastest and already provides a good compression, 9 is the slowest but has the highest compression ratio. See Compression below
distance_optimization	integer	4	Reduces synchronization of actors that are far away from each player. 0 disables it, 4 is a good middle term, 9 is the most aggressive. See Distance Optimization below

Compression

The server compresses (deflate) whole payload blocks before they go on the wire. The compression setting is the deflate level used: 0 disables it entirely, 1-9 trade CPU for ratio.

Scripts can read it with Server.GetCompressionLevel().

What gets compressed

Data	When it is compressed
Package client files: everything under a Package's Client/ and Shared/ folders, plus the generated Package.toml	Once, when the Package is loaded. The compressed copy is what stays in memory and is served to every player, over both socket transfer and HTTP
Client requirements: the manifest of every file (name, hash, size) a joining player must have	Rebuilt whenever Packages/Assets change
Loaded assets list	Rebuilt whenever Asset Packs change
Entity construction data: the scripting part of an entity's state (its Values, custom data) sent when a player needs to spawn it	Rebuilt whenever that entity's data changes
Server networked values: the table set with Server.SetValue(key, value, true), sent to joining players	Rebuilt whenever a value changes
Remote event parameters: big tables sent with Events.Call/BroadcastRemote()	Per call

Files whose extension is already a compressed format are skipped, since deflating them again only burns CPU: .png, .jpg, .jpeg, .webp, .webm, .gif, .ogg, .mp3, .mp4, .zip, .rar, .7z, .woff2.

tip

Set log_level = 2 to see per-group summaries (Compressed Package 'x' Client Files from 4.2 MB to 900.1 KB (78.6%)), or log_level = 3 to get a line for every single block that gets compressed.

Distance Optimization

For each player, and for each actor being synchronized, the server computes a relevancy based on the distance between them:

relevancy = clamp(100 - ((distance_in_units / 1000) - 1) * distance_optimization * multiplier, 0, 100)

The relevancy is the percentage of ticks in which that actor's snapshots are actually sent to that player: 100 means always, 0 means never.

Relevancy by distance across all levels:

Distance	Lvl. 1	Lvl. 2	Lvl. 3	Lvl. 4	Lvl. 5	Lvl. 6	Lvl. 7	Lvl. 8	Lvl. 9
1,000 units	100%	100%	100%	100%	100%	100%	100%	100%	100%
5,000 units	96%	92%	88%	84%	80%	76%	72%	68%	64%
10,000 units	91%	82%	73%	64%	55%	46%	37%	28%	19%
20,000 units	81%	62%	43%	24%	5%	0%	0%	0%	0%
30,000 units	71%	42%	13%	0%	0%	0%	0%	0%	0%
40,000 units	61%	22%	0%	0%	0%	0%	0%	0%	0%

And the distance at which an actor stops being synchronized entirely:

Level	1	2	3	4	5	6	7	8	9
Cut-off distance	101,000	51,000	35,000	26,000	21,000	18,000	16,000	14,000	13,000

note

This only throttles unreliable traffic, such as movement snapshots and transient actions (e.g. Jump). Reliable data (spawning and destroying entities, remote events, value changes) is always delivered in full, no matter the distance.

Scripting can bias the formula per entity with Actor:SetDistanceOptimizationMultiplier() and per player with Player:SetDistanceOptimizationMultiplier(), both multipliers are applied together. A value below 1 keeps the actor relevant for longer (use it for something that must stay smooth at range, like a scaled up actor or character), above 1 culls it sooner, and 0 makes it always relevant.

The level can also be changed while the server is running with the distance_optimization console command.

Logo Image

It is possible to have a custom image to be displayed in the server list. For that, add a file called Server.jpg besides the server executable with the logo you wish. The recommended size is 300x150.

tip

You can pass a JPG image URL to --logo parameter to download and use a image from the web instead of placing it physically in the folder.

note

Server Logo feature is only available for for Dedicated Servers.

Map & Level

The Map (or Level) is defined in the Server's config file, this map will be loaded when the player joins the server in the client side.

To configure a map, please refer to Packages Guide to create a Map Package pointing to the correct Asset.

nanos world counts on (for now) 4 built-in maps: default-blank-map, default-empty-map, default-ocean-map and default-testing-map which can be used in your server without needing to download any Package/Asset Pack.

Server Console

Built-in Commands

Command	Parameters	Description
chat	\<message>	Sends a chat message
clear		Clears the console
kick	\<player_id> \<reason>	Kicks a player by it's ID
map	\<map_path>	Reloads all Packages and reconnect the Players in new Map
restart		Restarts the server, reloading all Packages and reconnecting the Players
stop		Stops the server
players		Lists all Players connected
password	\<new_password>	Changes the server password
profiling	\<0-1>	Enables/Disables Performance Profiling Logs for debugging
log_level	\<1-3>	Changes the log level
max_send_rate	\<128-16384>	Changes the max send rate per client
max_file_transfer_rate	\<128-max_send_rate>	Modifie le taux de transfert de fichier maximum par client
distance_optimization	\<0-9>	Sets the distance optimization level
package run	\<package_name> \<lua_code>	Runs a code in a Package
package reload all		Reloads all Packages and restarts the Lua Virtual Machine
package reload	\<package_names...>	Reloads Packages
package unload	\<package_names...>	Unloads Packages
package load	\<package_names...>	Loads Packages
package hotreload	\<package_names...>	Reloads all files but keeps the memory as is

Custom Commands

It is possible to define custom commands as well, for that please refer to Console.RegisterCommand().

Command Line Parameters

It is possible to override the Server Configuration with Command Line Parameters.

Paramètre	Value Type	Description
--name	string	Server name
--description	string	Server description
--logo	string	Server Logo (downloads the image in-memory)
--password	string	Mot de passe du serveur
--ip	string	Server IP
--playtest	flag	Launches the server with the Playtest APPID (so you can play with a Playtest access)
--map	string	Map to load
--port	1024-65535	Server port
--query_port	1024-65535	Server Query port (must be different than server port)
--announce	0 or 1	If announce in master list
--game_mode	string	Server game-mode
--loading_screen	string	Server loading-screen
--packages	string list	Server packages
--assets	string list	Server assets
--token	string	Server authorization token
--max_players	1-999	Max allowed players
--dedicated_server	0 or 1	If to start as a Dedicated Server or P2P
--async_log	0 or 1	If to use async or sync logs (async provides better performance) Default is 1
--log_level	1, 2 or 3	If to use Normal 1, Debug 2 or Verbose 3 logs
--custom_settings	toml string	A list of Custom Settings to be passed to scripting in toml format
--compression	0-9	Sets the compression level to use in some networking operations 0 disables it, 1 is the fastest and 9 is the slower but highest compression ratio See Compression
--save	flag	If to save the passed parameters in Config.toml
--profiling	flag	Enables Performance Profiling Logs for debugging
--auto_download	flag	Automatically downloads Packages and Assets from Vault if needed
--use_vault_assets_lean	flag	Only downloads the Asset Pack's .toml configuration files from Vault
--log_show_thread	flag	Shows the current running thread of each outputted log
--max_tick_rate	15-120	Sets the server max tick rate in Hz (ticks per second)
--max_sync_rate	1-30	Sets the max actors sync rate in Hz (syncs per second), naturally limited by max_tick_rate
--max_send_rate	128-16384	Sets the server max send rate per client in KB/s
--max_file_transfer_rate	128-16384	Sets the server max file transfer rate per client in KB/s This must be smaller than max_send_rate
--distance_optimization	0-9	Sets the distance optimization level to improve network usage by reducing sync from distant actors 0 disables it, 4 is a good middle term, 9 is the most aggressive See Distance Optimization
--thread_pool_count	0-any	Sets the number of threads initialized to execute async operations (e.g. from HTTP, Database, File) Default is 8 (or the number of CPU cores) and 0 disables the pool and always start a new thread for each async operation
--enable_unsafe_libs	flag	Enables executing the methods os.execute, os.rename, os.remove, os.exit, os.getenv, os.tmpname, os.setlocale, dofile, loadfile and all io.* on server side Caution: those methods may allow malicious operations to run on your server, make sure you know what you are doing

tip

Flag Value Types don't require any argument, just pass the parameter like --parameter.

One-liner Server Configuration

With Command Line Parameters and Command Line Interface (CLI), it is also possible to automate the full server installation, here's an example:

Windows

Installs all needed Packages (this will install needed Assets as well), then starts the server with all configs set:

./NanosWorldServer.exe --cli install package sandbox battlefield-kill-ui ts-fireworks-tools

./NanosWorldServer.exe --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "nanos-world::TestingMap" --game_mode "sandbox" --packages "battlefield-kill-ui,ts-fireworks-tools" --port 7777 --query_port 7778 --max_players 32 --logo "https://i.imgur.com/vnB8CB5.jpg"

Or, just start the server passing with all configs set and auto downloads the packages and assets if needed:

./NanosWorldServer.exe --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "nanos-world::TestingMap" --game_mode "sandbox" --packages "battlefield-kill-ui,ts-fireworks-tools" --port 7777 --query_port 7778 --max_players 32 --auto_download 1 --logo "https://i.imgur.com/vnB8CB5.jpg"

Linux

Installs all needed Packages (this will install needed Assets as well), then starts the server with all configs set:

./NanosWorldServer.sh --cli install package sandbox battlefield-kill-ui ts-fireworks-tools

./NanosWorldServer.sh --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "nanos-world::TestingMap" --game_mode "sandbox" --packages "battlefield-kill-ui,ts-fireworks-tools" --port 7777 --query_port 7778 --max_players 32 --logo "https://i.imgur.com/vnB8CB5.jpg"

Or, just start the server passing with all configs set and auto downloads the packages and assets if needed:

./NanosWorldServer.sh --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "nanos-world::TestingMap" --game_mode "sandbox" --packages "battlefield-kill-ui,ts-fireworks-tools" --port 7777 --query_port 7778 --max_players 32 --auto_download 1 --logo "https://i.imgur.com/vnB8CB5.jpg"

Common Console Messages and Errors

Server Tick too/extreme high! Verify the server performance! Server got stuck for Xms...

It means the server got stuck for X milliseconds. The warning (yellow) is not something to worry about, but too many messages in red could mean your server infrastructure is not that good or your scripting code is not that optimized.

Usually the server runs at 33 ticks per second (or the value configured at Config.toml), the server runs in an infinite loop in that frequency, and inside that loop all server operations are executed, such as receiving and sending network packets, triggering lua events, executing functions or callbacks, and so on.

If a single tick takes more than 33 milliseconds, this warning will appear up.

tip

In some shared VPS, this warning may appear up more frequently due how the VPS handles the scaling of it's machines, sometimes the provider may think your VPS is "idle" (due nanos world server using extremely low CPU) and may decrease your processing power, causing this warning show up as well.

Lua Stack Error: Should be X, is Y...

This is an internal error and should not supposed to happen. Those are guards set around our Lua Scripting implementation to prevent bad things from happening. If this error appears it means a implementation bug happened. Please communicate immediately with the devs, and if possible how to reproduce that!

...Was it supposed to happen?

Those FATAL errors usually shouldn't happen, if you experience any, please let us know.