meta data for this page

📚 文件扩展及规范

沙盘引擎 程序及模组目录内包含许多文件，本文将列出部分关键文件进行说明介绍。

📒 Mod.JSON 配置文件

此文件放置每个模组的独立配置项，此文件应保持存在且有效。

📘 配置示例

{
	"Name": "Introduce&Demo",
	"Author": "SandtableEngine",
	"Info": "SandtableEngine official introduce demo",
	"Version": "1.0",
	"Font": "TsangerYuYangT",
	"DefaultLanguage": "English",
	"Website": "mp-gamer.com",
	"NetworkPort": 8192,
	"NetDownload": true,
	"LastTime": "0" //Auto
}

📘 配置项说明

不同配置项拥有不同的作用，有些配置项是可以留空的。

配置项 功能说明
Name 模组的标准名称（建议使用英文+固定名称）
（模组名称的多语言可使用Language机制实现）
Author 模组作者
Info 模组信息（介绍）
Version 模组版本（仅显示及记录作用，无匹配验证）
自V0.8版本开始，由于自动下载机制的更新，不再验证模组Version是否相同
Font 模组字体名称（可使用引擎内置字体或模组外部字体）
DefaultLanguage 模组默认语言（如果模组内Language/不存在和EngineLanguage相同的语言，则优先使用DefaultLanguage，通常建议设置为English）
Website 模组官方网站
NetworkPort 服务器主机端口号（默认值：8192）
只有在脚本层面未指定明确端口参数时（忽略参数），才会优先使用此处设定
注意：通常建议优先使用此属性，而不是直接在脚本指定端口，这样也可兼容于LAN服务器的搜索
NetShareMode
（已过时） 		主机模组共享模式（默认值：1）
此功能对于部分开发者比较重要，详情参考《模组主机共享模式》

📒 Local.JSON 配置文件

此文件放置每个模组的独立本地配置项，引擎每次载入模组后自动生成及修改。

此文件通常保存非关键的记录信息，例如：上次载入时间、上次主机UUID等。

📘 配置项说明

不同配置项拥有不同的作用，多数是由引擎动态修改的，玩家通常无需修改。

配置项 功能说明
LastTime 模组上次运行时间，由引擎自动赋值
LastLicense 上次License.txt文件的哈希记录，避免重复显示窗口
LastPlayerUUID 上次运行此模组的玩家UUID，判断是否为新玩家

📒 Startup.JSON 配置文件

此文件为模组可选的附带文件，允许为模组提供一些前置文本数据。

每次加载模组或者切换场景时，都会自动更新读取最新的数据。

注意：Startup.json文件不会由服务器同步至客户端，此文件永远是本地的。

文件作用：允许开发者通过GetGlobalVars("Startup")获取此文件内的所有文本（内容只读，且文本内容不限于json格式，即使内部是一串诗歌也没有问题）。

通过此属性的机制，开发者可扩展实现许多前置功能（例如：专用服务端的前置配置，房间名、端口号、房间最大人数等）。

📘 简单示例

沙盘引擎 默认没有提供专用服务器的启动配置文件。

这就导致专用服务器建立的服务器无法获取自定义配置，开发者可能希望制作一个json | txt表的方式，以在每次建立专用服务器时模组知道该如何设置服务器名称、最大人数，自定义端口等配置。

如果有其他类似的相关需求，均可以利用此机制来做前置配置文件。

📘 示例步骤

  1. 在模组根目录建立或打开Startup.json文件，准备修改

  2. 将此文件内容修改成自己可解析的模式，这里可以使用json文本方式，根据需求自行编写一套数据表 

    {
    "HostName": "Sandtable Engine Server",
    "Map": "helloworld",
    "MaxPlayers": 100,
    "Password": "",
    "RconPassword": ""
}

  3. 确认正确编写后，在Main场景的启动事件中，使用GetGlobalVars("Startup")获取到Startup.json内的文本信息，并转成自己想要的格式（如果是标准json文本，则会自动反序列化）

  4. 使用获取后的内容，按需求来编写逻辑代码 

    function OnScriptLoad()
{
    if(IsServerMode())
    {
        //因为示例是json文本，所以会自动序列化，可直接使用属性
        let startup = GetGlobalVars("Startup");
        DLog(startup.HostName); //"Sandtable Engine Server"
    }
}

  5. 因为GetGlobalVars()是模组全局生效的，所以可以在不同场景一直使用

📘 其他补充

  • 相关API：SetGlobalVars()不可写入Startup的内容，这是只读的

  • 如果有特殊需求，Startup类文件可以同时在Mod目录存在多个，可在启动时使用启动参数-startup_XX进行重定义

  • 启动参数：-startup_XX可用于在启动游戏时指定运行Mod目录下的其他文件，最终作为模组Startup的重定向读取

📒 Script/_Config.JSON 配置文件

此文件通常位于模组脚本子目录内，用于配置此脚本组目录的相关前置选项。

此配置文件是可选的，如果不需要相关功能，可以删除此文件。

📘 配置示例

{
	"DefaultMap": "",
	"Plugins": [
		"PlayerCharacterTag",
		"PlayerCharacterMarker",
		"AdminSystem"
	],
	"MapSnapshot": {
		"Style": 0,
		"WorldTime": 10
	}
}
配置Key 说明
DefaultMap 强制设定当前脚本组的地图（优先级最高）
通常适用于主菜单场景（避免额外的二次加载）
Plugins 加载的Plugin插件
MapSnapshot 地图快照生成相关
大型地图生成会消耗较多性能，如果游戏确实不需要地图，可以设置Style = -1以禁用自动生成

📒 私有同步文件

当玩家作为主机服务器时，会自动将模组必要文件同步给新玩家（自动执行），有些情况下，可能不希望某些文件被同步。

默认情况下，主机目录Mod\Host下所有文件都不会被同步。

除此之外，可以将希望私有的文件加以_private后缀，换句话说，任何包含_private字段的路径文件都不会被同步。