版本：bleeding-edge 🩸

包指南

包是你服务器的片段/组件，能够包含 Lua 脚本以与游戏进行交互、定义加载屏幕或地图。

文件夹结构

所有包都必须放置在服务器的 Packages/ 目录下。每个包都是该目录下的一个文件夹。

它们可以包含以下文件夹：Server、Client 和 Shared。当客户端连接时，只有 Client 和 Shared 文件夹会被发送并加载到客户端。

每个包含 Lua 脚本的包都必须在 Server、Client 或 Shared 文件夹中包含一个名为 Index.lua 的文件。这是包在加载时唯一会被触发的文件，该文件负责引入其他文件并启动你的功能。

Server Folder
NanosWorldServer.exe
Packages/
├── my-package-01/
│	├── Server/
│	│   ├── Index.lua
│	│   └── *.lua
│	├── Client/
│	│   └── *.lua
│	├── Shared/
│	│   └── *.lua
│	└── Package.toml
├── my-package-02/
│	├── Package.toml
│	└── ...
├── my-package-loading-screen-01/
│	├── index.html
│	├── Package.toml
│	└── ...
Assets/
Config.toml

注意

包文件夹名称也是其唯一标识符（用于 Config.toml、需求项和资源库），因此必须为小写，且仅包含字母、数字和 -（例如 my-awesome-package），最多 64 个字符。

提示

想知道包及其 Server/、Client/ 和 Shared/ 脚本是以什么顺序加载的吗？请查阅包加载与 Lua 环境指南。

包配置

包文件夹的根目录下有一个名为 Package.toml 的配置文件，在此文件中我们可以设置与该包相关的所有相关设置。每种包类型都有其专有的配置文件格式。

它们都共享相同的 [meta] 标头，其中包含以下设置：

_meta.toml
loading...

See full example on GitHub

设置	描述
`title`	易读的名称
`author`	贡献者
`version`	版本 - 采用 SemVer 格式 `X.Y.Z`

包类型

我们共有 5 种类型的包：script、game-mode、map、loading-screen 和 c-module，每种类型都具有特定的功能和独特的用途：

`script`

Script 是一种普通的包类型，可以加载 Lua 脚本文件，你可以根据需要加载任意数量的 script 包。它们在服务器 Config.toml 的 packages 条目中进行定义。

Package.toml
loading...

See full example on GitHub

`game-mode`

GameModes 类似于 script 包，但你一次只能加载一个 game-mode 包。它们在 Config.toml 的 game_mode 条目中进行定义。

当你在创建无法与其他完整游戏包一起加载的完整游戏时，会使用它们。

Package.toml
loading...

See full example on GitHub

`loading-screen`

Loading Screen 是一种特殊的包类型，在玩家加载期间加载，用于将自定义加载屏幕显示为 HTML。它们在 Config.toml 的 loading_screen 条目中进行定义。

它的根目录下必须包含一个 index.html 文件。欲了解更多信息，请参阅加载屏幕。

Package.toml
loading...

See full example on GitHub

`map`

Map 是一种特殊的包类型，它定义了地图条目的配置。它们在 Config.toml 的 map 条目中进行定义。

它包含了 script 的所有功能，同样能够执行脚本。此外，它还用于加载地图，并可选择在其 Package.toml 中原生定义自定义数据和生成点。

Package.toml
loading...

See full example on GitHub

提示

由于 nanos world 服务器无法感知虚幻引擎或其资产，我们需要以某种方式告诉服务器地图中可脚本控制的部分在哪里，例如生成点、道具位置、武器位置等。

推荐的做法是在你的地图包的 Server/Index.lua 中实现所有道具、武器和载具的生成位置，并在 Package.toml 文件中定义所有玩家的生成点。

`c-module`

C Module 是另一种特殊的包，能够在 Lua 虚拟机中加载二进制的 C 模块。

欲了解更多信息，请参阅 C Module。

Package.toml
loading...

See full example on GitHub

设置细节

设置	包类型	描述
`force_no_map_package`	`script` `game-mode`	启用此项将强制不加载地图包（如果有）
`auto_cleanup`	`script` `game-mode` `map`	开启此项后，当该包卸载时，会销毁由其生成的所有实体
`load_level_entities`	`script` `game-mode` `map`	是否将放置在地图关卡中的所有静态网格体作为实体加载到客户端（可通过脚本访问）。仅在你的包需要使用它们时启用此选项，因为这会消耗性能
`compatibility_version`	`script` `game-mode` `map`	创建此包时的游戏版本（`major.minor`），用于在发生破坏性更改时授予向后兼容性。参见此处
`packages_requirements`	`script` `game-mode` `map`	此包所使用的包依赖项列表，需要先加载这些依赖项
`assets_requirements`	`script` `game-mode` `map`	加载此包时需要加载的资产包
`compatible_game_modes`	`script` `map`	兼容/推荐与此包一起工作的游戏模式列表
`compatible_maps`	`game-mode`	兼容/推荐与此游戏模式一起工作的地图列表
`custom_settings`	`game-mode`	在启动新游戏时可以设置的、或通过命令行传递给服务器的自定义设置列表。参见此处
`map_asset`	`map`	地图资产的资产路径，格式为 `[ASSET_PACK]::[ASSET_KEY]`
`spawn_points`	`map`	生成点列表，格式为 `{ location = "Vector()", rotation = "Rotator()" }, ...`，可以通过 Server.GetMapSpawnPoints() 进行访问
`enable_water_buoyancy`	`map`	如果你的地图使用了水体插件（Water Plugin），是否在 Actor 上启用浮力组件 - 在不需要它的地图上禁用它可以获得额外的性能
`custom_data`	`map`	加载此地图时可以访问的自定义数据列表。参见此处

自定义设置

GameModes 可以在 [custom_settings] 部分定义自定义设置，以便在通过主菜单创建新游戏时进行设置，或者在通过命令 --custom_settings "var1 = value1, var2 = value2, ..." 启动服务器时进行设置。

定义的值可以通过 Server.GetCustomSettings() 方法进行访问。

每个设置都声明为 key = { ... }，其中的表描述了它在“新游戏”屏幕中应如何显示和校验：

属性	类型	描述
`label`	`string`	为此设置显示的易读名称
`type`	`string`	下方类型列表中的其中一种
`description`	`string`	设置旁显示的帮助文本
`default`	`boolean`\|`integer`\|`floating`\|`string`	默认值，必须与设置的 `type` 匹配
`options`	`string[]`	仅供 `select` 类型使用：下拉列表中显示的值列表

类型列表

类型	描述
`boolean`	可切换的复选框
`integer`	整数数值
`floating`	浮点数值
`select`	显示为下拉列表的字符串值列表
`text`	文本框

使用示例

[custom_settings]
	max_props = { label = "Max Props", type = "integer", description = "maximum amount of props players can spawn", default = 1000 }
	enable_pvp = { label = "Enable PVP", type = "boolean", description = "whether to enable PVP or not", default = true }
	welcome_message = { label = "Welcome Message", type = "text", description = "message shown to players when they join", default = "have fun!" }
	game_mode = { label = "Game Mode", type = "select", description = "which ruleset to use", default = "Classic", options = [ "Classic", "Hardcore", "Free for All" ] }

然后，这些设置会通过 Server.GetCustomSettings() 暴露给每个包，该方法返回以设置名称和原始值为键值的表：

local settings = Server.GetCustomSettings()

Console.Log(settings.max_props) -- 1000
Console.Log(settings.game_mode) -- "Classic"

它们也可以在不修改 Package.toml 的情况下被重写，无论是在通过主菜单创建新游戏时，还是直接在命令行中传递它们，后者的优先级高于“新游戏”屏幕和 Package.toml 的默认值：

--custom_settings "max_props = 500, enable_pvp = false, game_mode = 'Hardcore'"

自定义数据

地图可以在 [custom_data] 部分定义自定义数据。

当此地图包加载时，定义的值会被加载，并且可以通过 Server.GetMapConfig() 方法进行访问。

使用示例

[custom_data]
	my_key = 123
	my_another_key = "你好世界！"
	my_array = [ "whoa", "yeah", 123 ]

忽略客户端文件夹

有时你希望忽略某些文件夹，不将它们发送给客户端（例如，来自 Node.js HTML 的自动生成文件夹）。

要让服务器忽略它，你只需要在该文件夹的根目录下添加一个 .ignore 文件即可。就这么简单 😉。

徽标图片

你还可以设置一张自定义图片，以便在资源库中显示。为此，在 Package.toml 旁边添加一个名为 Package.webp 或 Package.jpg 的文件，放入你想要的图像。推荐尺寸为 300x150。

提示

仅当你的包不在商店中时，才会使用本地包图像。另外，不建议上传包含图像文件的包，因为该图像不会被使用，只会增加 .zip 大小。

文件夹结构​

包配置​

包类型​

script​

game-mode​

loading-screen​

map​

c-module​

设置细节​

自定义设置​

类型列表​

使用示例​

自定义数据​

使用示例​

忽略客户端文件夹​

徽标图片​

文件夹结构

包配置

包类型

`script`

`game-mode`

`loading-screen`

`map`

`c-module`

设置细节

自定义设置

类型列表

使用示例

自定义数据

使用示例

忽略客户端文件夹

徽标图片