版本：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

注意

Package folder names are also their unique identifier (used in Config.toml, requirements and the Vault), so they must be lowercase and contain only letters, numbers and - (e.g. my-awesome-package), with max 64 characters.

提示

Wondering in which order Packages and their Server/, Client/ and Shared/ scripts are loaded? Check the Package Loading & Lua Environment guide.

包配置

包在包文件夹的根目录下有一个名为 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`	Whether to load all the static meshes placed in the map level as entities on the client side (accessible through scripting). Only enable it if your Package needs to use them, as it costs performance
`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.jpg 的文件，并附上你希望的图片。推荐尺寸为 300x150。

提示

包图片仅在你的包不在资源库中时才会被使用。此外，不推荐上传带有 Package.jpg 文件的包，因为这没有被使用，且只会臃肿包的大小。

文件夹结构​

包配置​

包类型​

script​

game-mode​

loading-screen​

map​

c-module​

设置细节​

自定义设置​

类型列表​

使用示例​

自定义数据​

使用示例​

忽略客户端文件夹​

徽标图片​

文件夹结构

包配置

包类型

`script`

`game-mode`

`loading-screen`

`map`

`c-module`

设置细节

自定义设置

类型列表

使用示例

自定义数据

使用示例

忽略客户端文件夹

徽标图片