版本：最新版 - a1.156.0 ⚖️

服务器配置

配置服务器所需了解的一切！

服务器配置文件

服务器配置文件 Config.toml 在服务器首次启动时会自动生成。在服务器加载后，该文件将始终被正确的模板覆盖。

提示

nanos world 配置文件使用 TOML（Tom's Obvious, Minimal Language），有关更多信息和语法，请参阅 https://github.com/toml-lang/toml。

Config.toml
loading...

See full example on GitHub

设置细节

配置文件分为几个部分。下面将逐一描述每个部分，包括其类型、默认值和可接受范围。

备注

服务器在每次启动时都会重写 Config.toml，此操作发生在应用命令行参数并校验每个值之后。你添加的任何注释、未知键或超出范围的值都将被丢弃或重置，日志会明确告诉你哪个设置被重置以及重置成了什么值。

`[discover]`

你的服务器如何展示（和通告）自身。

设置	类型	默认值	描述
`name`	`string`	`"nanos world server"`	服务器名称，显示在服务器列表中
`description`	`string`	`""`	服务器描述。限制为 200 个字符
`language`	`string`	`"global"`	国家/地区代码（例如 `br`、`us`、`de`），用于在服务器列表中显示国家/地区旗帜
`ip`	`string`	`"0.0.0.0"`	服务器绑定的地址，同时用于游戏套接字和内置 HTTP 服务器。我们建议保持 `0.0.0.0` 不变，它会绑定到所有网络接口
`port`	`integer`	`7777`	服务器主端口，同时用于游戏流量（UDP）和内置 HTTP 服务器（TCP）。范围 `1024` - `65535`
`query_port`	`integer`	`7778`	服务器查询端口（UDP），供服务器列表和查询工具使用。范围 `1024` - `65535`，且必须与 `port` 不同
`announce`	`boolean`	`true`	是否在服务器列表中公布该服务器。未公布的服务器仍然可以通过直接连接加入
`dedicated_server`	`boolean`	`true`	`true` 表示运行专用服务器：需要端口转发，提供最快的连接速度。 `false` 表示以 P2P 模式运行，它会分配一个虚拟 IP，让玩家通过 Steam 数据报中继连接，无需端口转发，但延迟更高，并且无论 `max_send_rate` 如何设置，中继服务都会将发送速率限制在 `1024` KB/s

`[general]`

设置	类型	默认值	描述
`max_players`	`integer`	`64`	允许加入的最大玩家数量。范围 `1` - `999`
`password`	`string`	`""`	连接所需的密码。留空表示不需要密码
`token`	`string`	`""`	服务器身份验证令牌，用于授权资源库下载、通过 CLI 操作、通过 `--auto_download` 参数，以及获取你拥有的包/资产时使用
`banned_ids`	`string list`	`[]`	被封禁的 nanos 账户 ID 列表。被封禁的玩家在连接时会被拒绝

`[game]`

设置	类型	默认值	描述
`map`	`string`	`"default-blank-map"`	要加载的地图包。参见地图与关卡
`game_mode`	`string`	`""`	要加载的游戏模式包，一次只能加载一个游戏模式
`packages`	`string list`	`[]`	要加载的脚本包
`assets`	`string list`	`[]`	除已加载的包/地图所需资源之外，额外强制加载的资产包
`loading_screen`	`string`	`""`	要加载的加载屏幕包，一次只能加载一个加载屏幕

`[custom_settings]`

一个自由格式的自定义值表，通过 Server.GetCustomSettings() 向每个包提供。值可以是字符串、整数、浮点数或布尔值。

[custom_settings]
    max_props = 1000
    enable_pvp = true
    welcome_message = "玩得开心！"

游戏模式可以声明它们接受哪些自定义设置，这样它们就会显示在“新游戏”屏幕中，请参阅自定义设置。整个表也可以通过命令行传递，例如 --custom_settings "max_props = 1000, enable_pvp = true"。

`[debug]`

设置	类型	默认值	描述
`log_level`	`integer`	`1`	要输出的日志级别：`1` 普通，`2` 调试，`3` 详细。级别 `2` 和 `3` 输出信息较多，请仅在排查问题时使用，不要在生产环境中启用
`async_log`	`boolean`	`true`	从独立线程写入日志，速度更快。在调试崩溃问题时将其设置为 `false`，以确保崩溃前的最后几行日志被完整写入
`profiling`	`boolean`	`false`	启用性能分析日志，报告每个内部操作所花费的时间。有助于找出导致服务器刻变慢的原因。也可以在运行时通过 `profiling` 控制台命令切换

`[optimization]`

设置	类型	默认值	描述
`max_tick_rate`	`integer`	`30`	服务器刻（Hz），即服务器循环每秒运行的次数。范围 `15` - `120`。所有操作（网络接收/发送、Lua 事件、计时器等）都在这个循环内发生，因此更高的值响应更快，但 CPU 使用率也会成倍增加。 `30` Hz 意味着服务器每个刻有 `33ms` 来完成所有工作，我们建议保持 `30`
`max_sync_rate`	`integer`	`30`	最大 Actor 同步频率（Hz），即 Actor 的位置/旋转/速度被同步的频率。范围 `1` - `30`，且自然受限于 `max_tick_rate`。该值也会发送给客户端，因此它们会以相同的频率进行同步回传。降低该值是减少拥有大量移动 Actor 的服务器带宽消耗的最经济方式，代价是移动精度会有所降低
`max_send_rate`	`integer`	`1024`	最大网络发送速率，按每个客户端计算，单位为 KB/s。范围 `128` - `16384`。建议设置为能满足你流量需求的最低值，较高的速率在玩家网络连接不佳时可能会对服务器性能产生负面影响。 P2P 服务器受 Steam 数据报中继限制，上限为 `1024` KB/s。可以在运行时通过 `max_send_rate` 控制台命令更改
`max_file_transfer_rate`	`integer`	`1024`	最大文件传输速率，按每个客户端计算，单位为 KB/s，即包和资产文件推送给连接中玩家的速度。范围 `128` - `max_send_rate`；任何高于 `max_send_rate` 的值都会被限制到该值。降低该值可以防止下载任务抢占已在游戏中的玩家的游戏流量
`compression`	`integer`	`1`	应用于多种网络操作的压缩级别。 `0` 表示禁用，`1` 速度最快且已能提供良好的压缩效果，`9` 速度最慢但压缩率最高。请参见下文压缩
`distance_optimization`	`integer`	`4`	减少对距离每个玩家较远的 Actor 的同步。 `0` 表示禁用，`4` 是较好的中间值，`9` 是最激进的设置。请参见下文距离优化

Compression

服务器在将整个负载块发送到网络之前会对其进行压缩（deflate）。 compression 设置决定了使用的 deflate 级别：0 完全禁用，1-9 以 CPU 换取压缩率。

脚本可以通过 Server.GetCompressionLevel() 读取该值。

会被压缩的内容

数据	压缩的时机
包客户端文件：包中 `Client/` 和 `Shared/` 文件夹下的所有内容，以及生成的 `Package.toml` 文件	一次，在包被加载时。压缩后的副本会保留在内存中，并通过套接字传输和 HTTP 两种方式提供给每个玩家
客户端需求：连接玩家必须拥有的每个文件的清单（名称、哈希值、大小）	每当包/资产发生变化时重新构建
已加载资产列表	每当资产包发生变化时重新构建
实体构造数据：实体状态的脚本部分（其值、自定义数据），在玩家需要生成该实体时发送	每当该实体的数据发生变化时重新构建
服务器网络值：通过 `Server.SetValue(key, value, true)` 设置的表，发送给加入的玩家	每当值发生变化时重新构建
远程事件参数：通过 Events.Call/BroadcastRemote() 发送的大表数据	每次调用时

扩展名已经是压缩格式的文件会被跳过，因为再次压缩它们只会浪费 CPU 资源：.png、.jpg、.jpeg、.webp、.webm、.gif、.ogg、.mp3、.mp4、.zip、.rar、.7z、.woff2。

提示

设置 log_level = 2 可以查看每组压缩摘要（例如 Compressed Package 'x' Client Files from 4.2 MB to 900.1 KB (78.6%)），设置 log_level = 3 则会对每个被压缩的数据块输出一行日志。

距离优化

对于每个玩家以及每个正在被同步的 Actor，服务器会根据它们之间的距离计算一个相关性值：

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

相关性表示该 Actor 的快照实际发送给该玩家的刻百分比：100 表示总是发送，0 表示从不发送。

不同级别下基于距离的相关性：

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

以及 Actor 完全停止同步的距离：

Level	`1`	`2`	`3`	`4`	`5`	`6`	`7`	`8`	`9`
截止距离	101,000	51,000	35,000	26,000	21,000	18,000	16,000	14,000	13,000

备注

这仅限制不可靠流量，例如移动快照和瞬时动作（如跳跃）。可靠数据（生成和销毁实体、远程事件、值变更）无论距离多远，始终完整传送。

脚本可以通过 Actor:SetDistanceOptimizationMultiplier() 按实体调整公式，通过 Player:SetDistanceOptimizationMultiplier() 按玩家调整，两个乘数会共同生效。值低于 1 会使 Actor 在更长时间内保持相关性（适用于需要在远距离保持平滑的对象，如放大的 Actor 或角色），高于 1 会更快地剔除它，而 0 则使其始终保持相关性。

该级别也可以在服务器运行期间通过 distance_optimization 控制台命令进行更改。

徽标图片

可以在服务器列表中显示自定义图片。为此，请在服务器可执行文件旁边添加一个名为 Server.jpg 的文件，并配上你想要的徽标。推荐尺寸为 300x150。

提示

你可以向 --logo 参数传递一个 JPG 图片的 URL，以便从网络下载并使用图片，而无需将其物理放置在文件夹中。

备注

服务器徽标功能仅适用于专用服务器。

地图与关卡

地图（或关卡）在服务器的配置文件中定义，当玩家在客户端加入服务器时，该地图将被加载。

要配置地图，请参考包指南来创建一个指向正确资产的地图包。

nanos world（目前）自带 4 张内置地图：default-blank-map、default-empty-map、default-ocean-map 和 default-testing-map，这些地图可以在你的服务器中直接使用，无需下载任何包/资产包。

服务器控制台

内置命令

命令	参数	描述
`chat`	`\<message>`	发送一条聊天消息
`clear`		清空控制台
`kick`	`\<player_id> \<reason>`	根据 ID 踢出玩家
`map`	`\<map_package>`	Changes the map to another map Package, reloading all Packages and reconnecting the Players
`restart`		重启服务器，重新加载所有包并重新连接玩家
`stop`		停止服务器
`players`		列出所有已连接的玩家
`password`	`\<new_password>`	更改服务器密码
`profiling`	`\<0-1>`	启用/禁用用于调试的性能分析日志
`log_level`	`\<1-3>`	更改日志级别
`max_send_rate`	`\<128-16384>`	更改每个客户端的最大发送速率
`max_file_transfer_rate`	`\<128-max_send_rate>`	更改每个客户端的最大文件传输速率
`distance_optimization`	`\<0-9>`	设置距离优化级别
`package run`	`\<package_name> \<lua_code>`	在一个包中运行代码
`package reload all`		重新加载所有包并重启 Lua 虚拟机
`package reload`	`\<package_names...>`	重新加载包
`package unload`	`\<package_names...>`	卸载包
`package load`	`\<package_names...>`	加载包
`package hotreload`	`\<package_names...>`	重新加载所有文件，但保持内存当前状态不变

自定义命令

也可以定义自定义命令，请参考 Console.RegisterCommand()。

命令行参数

可以使用命令行参数来覆盖服务器配置。

参数	值类型	描述
`--name`	string	服务器名称
`--description`	string	服务器描述
`--logo`	string	服务器徽标（在内存中下载图片）
`--password`	string	服务器密码
`--ip`	string	Address the server binds to
`--steam_app`	`game` 或 `playtest`	Which Steam App the server runs as. Players can only join servers running the same Steam App they are playing on Default is `playtest`
`--map`	string	Map Package to load
`--port`	1024-65535	服务器端口
`--query_port`	1024-65535	服务器查询端口（必须与服务器端口不同）
`--announce`	0 or 1	Whether to announce the server in the Server List
`--game_mode`	string	服务器游戏模式
`--loading_screen`	string	服务器加载屏幕
`--packages`	string list	服务器包
`--assets`	string list	服务器资产
`--token`	string	服务器授权令牌
`--max_players`	1-999	最大允许玩家数
`--dedicated_server`	0 or 1	是否作为专用服务器或点对点启动
`--async_log`	0 or 1	是否使用异步或同步日志（异步提供更好的性能）默认为 `1`
`--log_level`	1, 2 or 3	是否使用普通 `1`、调试 `2` 或详细 `3` 日志
`--custom_settings`	toml string	以 toml 格式传递给脚本的一组自定义设置
`--compression`	0-9	设置在某些网络操作中使用的压缩级别 `0` 表示禁用，`1` 速度最快，`9` 速度最慢但压缩率最高参见压缩
`--save`	flag	是否将传递的参数保存到 Config.toml 中
`--profiling`	flag	启用用于调试的性能分析日志
`--auto_download`	flag	如果需要，自动从资源库下载包和资产
`--use_vault_assets_lean`	flag	仅从资源库下载资产包的 .toml 配置文件
`--log_show_thread`	flag	显示每条输出日志当前运行的线程
`--max_tick_rate`	15-120	设置服务器最大刻速率（Hz，即每秒刻数）
`--max_sync_rate`	1-30	设置最大 Actor 同步率（Hz，即每秒同步次数），自然受限于 `max_tick_rate`
`--max_send_rate`	128-16384	设置每个客户端的服务器最大发送速率（KB/s）
`--max_file_transfer_rate`	128-max_send_rate	Sets the server max file transfer rate per client in KB/s Values above `max_send_rate` are clamped down to it
`--distance_optimization`	0-9	设置距离优化级别，通过减少远处 Actor 的同步来改善网络使用率 `0` 表示禁用，`4` 是较好的中间值，`9` 是最激进的设置参见距离优化
`--thread_pool_count`	0-any	设置初始化用于执行异步操作的线程数（例如来自 HTTP、Database、File 的操作）默认为 `8`（或 CPU 核心数），设置为 `0` 将禁用线程池并始终为每个异步操作启动一个新线程
`--enable_unsafe_libs`	flag	允许在服务器端执行 `os.execute`、`os.rename`、`os.remove`、`os.exit`、`os.getenv`、`os.tmpname`、`os.setlocale`、`dofile`、`loadfile` 以及所有 `io.*` 方法警告：这些方法可能会允许恶意操作在你的服务器上运行，请确保你完全了解自己在做什么

提示

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

信息

Two special parameters must be passed as the first argument:

--cli runs the Command Line Interface instead of starting the server, e.g. ./NanosWorldServer.exe --cli install package sandbox.
--tracy (Linux only, through NanosWorldServer.sh) starts the server build with the Tracy Profiler integration. On Windows, run NanosWorldServerTracy.exe instead.

单行命令服务器配置

利用命令行参数和命令行界面 (CLI)，还可以自动化整个服务器安装过程，示例如下：

Windows
Linux

安装所有需要的包（这也会自动安装所需的资产），然后以配置好的所有选项启动服务器：

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

./NanosWorldServer.exe --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "default-testing-map" --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"

或者，直接启动服务器并传递所有配置，如果需要，它会自动下载包和资产：

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

安装所有需要的包（这也会自动安装所需的资产），然后以配置好的所有选项启动服务器：

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

./NanosWorldServer.sh --name "nanos world Amazing Sandbox" --description "Awesome Sandbox Server" --map "default-testing-map" --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"

或者，直接启动服务器并传递所有配置，如果需要，它会自动下载包和资产：

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

常见的控制台消息和错误

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

这意味着服务器卡顿了 X 毫秒。警告（黄色）并不需要过度担心，但如果出现过多红色的消息，则可能意味着你的服务器基础设施不够好，或者你的脚本代码优化不足。

By default the server runs at 30 ticks per second (or the max_tick_rate configured in the 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.

At 30 ticks per second, each tick has about 33 milliseconds to do all its work. If a single tick takes longer than that, this warning will show up.

提示

在某些共享 VPS 中，由于 VPS 处理其机器伸缩的方式，此警告可能会更频繁地出现。有时服务商可能会认为你的 VPS 处于“闲置”状态（因为 nanos world 服务器占用的 CPU 极低）并可能会降低你的处理能力，从而导致出现此警告。

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

这是一个内部错误，本不应该发生。这些是在我们的 Lua 脚本实现周围设置的保护机制，以防止更坏的事情发生。如果出现此错误，意味着发生了实现上的漏洞。请立即与开发者联系，并在可能的情况下提供重现方法！

`...Was it supposed to happen?`

这些 FATAL 错误通常不应该发生，如果你遇到任何此类错误，请告诉我们。