📚 脚本开发及API

本文档篇幅较长且相当重要，开发之前务必预览至少一次！

📒 索引

📒 前置概念

沙盘引擎 脚本采用世界脚本&客户端脚本”二合一的开发方式。

引擎每次加载世界场景时，将加载一个整体脚本组（World.js + Client.js），前者负责实现世界主要逻辑（服务端），后者负责实现客户端逻辑。

📘 脚本分配指引

在设计脚本时，应该做好世界脚本及客户端脚本的功能责任分配，避免出现过度相互依赖的情况，有助于后续的版本开发和日常维护。

常规情况下，应优先考虑世界脚本API来实现主要逻辑，需要客户端本地相关的内容，才在客户端脚本进行设计和实现。

📘 功能开发的常规步骤

1. 需求分析：确定想要实现的功能，对其进行简单的描述

   例如：想要设计和实现一个赛车的玩法，需要清楚规则是什么，路线是什么，哪些车参赛，人数怎么安排，比赛怎么进行等

2. 设计：根据需求分析，在开发层面进行抽象、分类和归纳，总结出需要存在哪些数据，功能，流程

   例如：设计赛车的路线由一个个点连接组成，参赛者用列表统一管理，参赛车有什么属性、功能，人数限制的功能描述，什么时候在什么地方会发生什么事（流程）等

3. 实现：用具体的代码和环境等来实现以上的设计（也就是编写代码）

   例如：赛车的路线用Checkpoint（检查点）来实现，参赛者用数组的方式实现存储，以及自定义的各种函数来实现具体的功能等等

4. 调试：开发的最后一步，及时发现异常，确保项目能正常运行

   例如：从使用者角度，对各个功能进行实际的上手测试（黑盒测试）；从开发者角度，对代码可能存在的隐患和边界条件进行实际的上手测试（白盒测试）

📒 脚本文件

沙盘引擎的所有模组脚本均在模组目录下Script/XXX目录。

其中入口脚本有两个，分别是World.js与Client.js。

📘 加载子脚本

实际开发过程中，特别是针对设定复杂的游戏，显然只有两个脚本文件是不利于开发者逻辑清晰的。

模组允许开发者使用API加载其他脚本，开发者可以根据情况自行分配多个子脚本，帮助开发者提高开发效率。

LoadScript("newscript.js");
LoadScript("Func/Functions.js");

任何新建的子脚本必须放置在Script目录内（或子目录），放置后的子脚本必须通过API进行加载脚本，否则没有作用（抛砖引玉，可通过此机制实现模块化开发）。

📘 脚本加密

在 沙盘引擎 模组开发中，无论是世界脚本还是客户端脚本，都将被放置在模组目录中，因此模组的脚本源代码是透明的。

由于JavaScript脚本的透明性，如果不希望别人查看自己的脚本，可以通过网络上的混淆、加密工具进行加密，但是务必确保源文件的备份，否则可能是不可逆的，建议只在确认打包之前进行一次混淆，本地测试阶段并不需要混淆和加密。

注意：由于 沙盘引擎 的联机自动同步机制，即使在开发过程中，也可能有玩家会连接到当前服务器，并且会自动下载最新的模组全部文件（包括脚本），因此如果不希望其他人进入，可以提前设置服务器密码或相关权限。

📘 本体思维扩展

通过了解，沙盘引擎两个主要入口脚本Client.js和World.js分别有各自的激活场景和作用。

这其实也可以扩展出一些其他思维，比如你有版权或用户隐私方面的顾虑或其他打算，你完全可以进行C\S客户端和服务端的分别开发和打包。

也就是说，客户端如果没有“建立主机服务器”的需求，完全可以将World.js留空或删除，实现网游化的开发。

例如：可能开发者不想让任何人都能架设服务器，那么就只需将World.js连同工程单独拷贝出来一份，很简单的形成了单独的“服务端”。

因为开发者发布给玩家的模组本体可以不包含世界脚本（World.js），所以玩家无法建立服务器（客户端也不应该有开启服务器的UI接口），因此只能进行加入游戏，而加入游戏是可以不需要世界脚本的。

📘 开放性利弊分析

由于JavaScript本身语言的透明性，无法进行二进制等真正意义的编译打包，尽管上面介绍了混淆加密工具的方式，但仍然会有小概率可能会被修改。

无论如何，最终版本进行混淆和加密或许是有必要的，否则可能会出现一些预期之外的情况。

考虑到类似这样的情况，尽管官方会按照初版发布时间和大众意愿评定来进行区分和保护正版模组，但如果开发者抛开混淆和加密仍然有困扰，可以考虑本文其他的扩展方法，综合判定是否要进行“独立服务端”的开发方式等。

📒 脚本框架及来源

沙盘引擎 游戏本体是基于Unity进行开发的，引擎中动态编译解析JavaScript脚本的功能来源于PuerTS框架（致敬）。

尽管引擎脚本是以JavaScript作为编译基础的，但引擎代码的设计思维来自于松鼠语言脚本（另外一个脚本语言）。

📒 脚本API文档指南

有关脚本API文档将被分成几个主要部分，分别是原生及通用代码、客户端代码（Client）、世界端代码（World）。

公开范围内所有的Event（事件）、Property（属性）、Function（方法）等代码都将在以上三个文档内记录呈现。

Timer.Create() [√]
timer.Create() [×] //no instance function
 
Timer.Repeat == 0 [×] //No static property
timer.Repeat == 0 [√]

function OnPlayerJoin( player )
{
 
}

📘 脚本API文档标题

由于引擎主要功能是由World、Client两个主类下的众多子类实现控制的，所以脚本文档采用了XXX 类参考的命名方式。

也就是说，例如查找关于世界脚本下的玩家方法，那么应该前往世界脚本——Player 类参考进行查找。

除此之外，每个类型参考文档内拥有多个H1、H2标题进行分类，通常会按照以下命名进行区分。

📒 脚本编写及编译

沙盘引擎使用JavaSciprt作为开发脚本语言，所以开发者可通过任何文本编辑器进行脚本编写。

脚本开发时并不需要专门的IDE以及编译器，只需要进行增删查改及修改后的保存“文本”即可，重新建立世界（重连、重载）时将会自动动态编译。

📒 脚本开发基础入门

《沙盘引擎》的开发初衷就是为了精简开发流程以及代码的复杂程度，所以实际上对模组脚本的基础开发并不需要非常过硬的编程技术。

如果开发者曾对Pawn、Squirrel或其他编程语言有相关经验，甚至不需要完全学习JavaScript，只需掌握基础的语法使用即可开始体验。

📘 事件和函数

事件（Event）：表示某件事情开始发生，客户端和世界端可能有不同的事件（也有部分是几乎一样的，可通用）

函数（Function）：执行一段引擎内置的代码，以来实现某个功能（例如PlaySound API在某处执行播放声音的功能）

//此处表示事件：当玩家加入到服务器
function OnPlayerJoin( player )
{
	//以下是“事件”下的“函数”
	DLog(player.Name + " joined."); //DLog是一个引擎下内置的方法（SE.DLog）
    Message(player.Name + " joined server."); //Message就是一个World.Message函数
}

📘 默认类空间

为了脚本开发思路更加清晰，所以引擎采用了必要类名前缀的调用方式，实际上类似于命名空间的概念，。