服务器配置
配置服务器所需了解的一切！
服务器配置文件
服务器配置文件 Config.toml 在服务器首次启动时会自动生成。在服务器加载后，该文件将始终被正确的模板覆盖。
nanos world 配置文件使用 TOML（Tom's Obvious, Minimal Language），有关更多信息和语法，请参阅 https://github.com/toml-lang/toml。
loading...
设置细节
配置文件分为几个部分。下面将逐一描述每个部分，包括其类型、默认值和可接受范围。
服务器在每次启动时都会重写 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 | 2048 | 最大网络发送速率，按每个客户端计算，单位为 KB/s。范围 128 - 16384。建议设置为能满足你流量需求的最低值，较高的速率在玩家网络连接不佳时可能会对服务器性能产生负面影响。 P2P 服务器受 Steam 数据报中继限制，上限为 1024 KB/s。可以在运行时通过 max_send_rate 控制台命令更改 |
max_file_transfer_rate | integer | 2048 | 最大文件传输速率，按每个客户端计算，单位为 KB/s，即包和资产文件推送给连接中玩家的速度。范围 128 - max_send_rate；任何高于 max_send_rate 的值都会被限制到该值。降低该值可以防止下载任务抢占已在游戏中的玩家的游戏流量 |
distance_optimization | integer | 4 | 减少对距离每个玩家较远的 Actor 的同步。 0 表示禁用，4 是较好的中间值，9 是最激进的设置。请参见下文距离优化 |
压缩
服务器在将整个负载块发送到网络上之前，总是会对其进行压缩（deflate），且此行为不可配置。只压缩一次并缓存以发送给每位玩家的数据（包文件、客户端需求、已加载资产）使用更高的压缩级别以获得更好的压缩率，而在运行时频繁压缩的数据（实体数据、服务器值、远程事件参数）则使用更快的压缩级别。
会被压缩的内容
| 数据 | 压缩的时机 |
|---|---|
包客户端文件：包中 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 目前有 3 个内置地图：default-blank-map、default-empty-map 和 default-ocean-map，可在你的服务器中使用，无需下载任何包/资产包。 default-playground-map（推荐）和较旧的 default-testing-map 都是资源库包，当它们被用作地图时，服务器会自动下载它们。
服务器控制台
内置命令
| 命令 | 参数 | 描述 |
|---|---|---|
chat | \<message> | 发送一条聊天消息 |
clear | 清空控制台 | |
kick | \<player_id> \<reason> | 根据 ID 踢出玩家 |
map | \<map_package> | 将地图更改为另一个地图包，重新加载所有包并重新连接玩家 |
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 | 服务器绑定的地址 |
--steam_app | game 或 playtest | 服务器作为哪个 Steam 应用运行。玩家只能加入与其正在运行的 Steam 应用版本相同的服务器 默认为 playtest |
--map | string | 要加载的地图包 |
--port | 1024-65535 | 服务器端口 |
--query_port | 1024-65535 | 服务器查询端口（必须与服务器端口不同） |
--announce | 0 or 1 | 是否在服务器列表中公布该服务器 |
--game_mode | string | 服务器游戏模式 |
--loading_screen | string | 服务器加载屏幕 |
--packages | string list | 服务器包 |
--assets | string list | 服务器资产 |
--token | string | 服务器授权令牌 |
--max_players | 1-999 | 最大允许玩家数 |
--dedicated_server | 0 or 1 | 是否作为专用服务器或 P2P 启动 |
--async_log | 0 or 1 | 是否使用异步或同步日志（异步提供更好的性能） 默认为 1 |
--log_level | 1, 2 or 3 | 是否使用普通 1、调试 2 或详细 3 日志 |
--custom_settings | toml string | 以 toml 格式传递给脚本的一组自定义设置 |
--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 | 设置服务器向每个客户端传输文件的最大速率（KB/s） 高于 max_send_rate 的值会被强制限制为该值 |
--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.*、整个 debug 库，以及加载预编译的 Lua 字节码（通过 load 或作为包文件）。还需要加载 C 模块包注意：这些方法可能允许恶意操作在你的服务器上运行，请确保你清楚自己在做什么 |
Flag 值类型不需要任何参数，只需像 --profiling 这样传递参数即可。
--cli 必须作为第一个参数传入：它会运行命令行界面而不是启动服务器，例如 ./NanosWorldServer.exe --cli install package sandbox。
Tracy Profiler 集成不再需要单独的构建版本或旧的 --tracy 参数：每个服务器都已内置。
单行命令服务器配置
利用命令行参数和命令行界面 (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-playground-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-playground-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-playground-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-playground-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 毫秒。警告（黄色）并不需要过度担心，但如果出现过多 红色 的消息，则可能意味着你的服务器基础设施不够好，或者你的脚本代码优化不足。
默认情况下，服务器以每秒 30 刻（或 Config.toml 中配置的 max_tick_rate）运行。服务器在该频率下以无限循环形式运行，在该循环内部会执行所有服务器操作，例如接收和发送网络数据包、触发 Lua 事件、执行函数或回调等等。
在每秒 30 刻的情况下，每个刻大约有 33 毫秒的时间来完成其所有工作。如果单个刻耗时超过该时间，系统将显示此警告。
在某些共享 VPS 中，由于 VPS 处理其机器伸缩的方式，此警告可能会更频繁地出现。有时服务商可能会认为你的 VPS 处于“闲置”状态（因为 nanos world 服务器占用的 CPU 极低）并可能会降低你的处理能力，从而导致出现此警告。
Lua Stack Error: Should be X, is Y...
这是一个内部错误，本不应该发生。这些是在我们的 Lua 脚本实现周围设置的保护机制，以防止更坏的事情发生。如果出现此错误，意味着发生了实现上的漏洞。请立即与开发者联系，并在可能的情况下提供重现方法！
...Was it supposed to happen?
这些 FATAL 错误通常不应该发生，如果你遇到任何此类错误，请告诉我们。