包指南

包是你服务器的片段/组件，能够包含 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.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	开启此项后，当该包卸载时，会销毁由其生成的所有实体
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() 方法进行访问。

类型列表

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

自定义数据

地图可以在 [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 文件的包，因为这没有被使用，且只会臃肿包的大小。