Development Tutorial
目录
1. Concept of Loops
As shown above, the core loop of the game is “Trigger + Event”.
Trigger is a collection of specific conditions, and event is a collection of directives to be executed.
As players continuously participate in different events, the in-game time elapses. Some events happen at certain moments, and then a set of directives will be carried out—this is the major looping logic of the game.
In an event, all relevant directives will be executed entirely by order-one after another. You can define a conditional jump-to statement at the end of the loop, which allows the event to jump to different results.
2. Project Configuration
Standard Project Configuration File: Config/default.json
After configuration, files in .json format will be created, and the key parameters are shown below.
In the following diagram, if the “Valid Range” is Story (type=Story), then the parameter can only be used in scenario MODs.
| Parameter | Allow Empty Parameter | Valid Range | Description |
| type | No | Plugin/Story | MOD Type, Plugin, Scenario |
| name | No | Plugin/Story | MOD Name |
| desc | Yes | Plugin/Story | MOD Description |
| tags | Yes | Plugin/Story | The label that describes the game genre shown to players on Steam. If there are multiple labels, please use a half-size semicolon—”;:” and type English characters only.
Scenarios Maps Items Characters Skills Appearance BattleUnits Rules Audios Cheating |
| start_scene | Yes | Story | The beginning scene (face editing by default); optional:
0: CG of Sands of Salzaar 1: Character Creation（default option if there is no parameter） 2: Sandbox Scene. You need to customize the main character (only available when the parameter type is “Story”) |
| include_main_game | Yes | Story | Decide whether you want to use the resources in the main project of the game (only available when the parameter type is “Story”)
0: do not use any data 1: use all data of Sands of Salzaar（default） 2: only use basic data（recommended for independent story）
|
| homepage_background | Yes | Story | Change the background image on the main menu. The full file path of the image is required. This is only available in a scenario MODs. |
| audioControllerAdditional | Yes | Plugin/Story | This is only available in the Professional MOD project.
Full path of the audio middleware is required. (please refer to the example; the parameter can be left empty). |
配置表引用文件 valuebundle/default.xml
格式为xml，可以包含多个include元素
| 参数 | 是否可为空 | 描述 |
| file | 否 | 本MOD需要包含的配置表文件名，此文件位于本Mod工程的Excel目录下。需要包含扩展名。 |
配置表规则映射文件 valuebundle/INDEX.xml
格式为xml，可以包含多个convert元素
| 参数 | 是否可为空 | 描述 |
| reg | 否 | 对应映射规则reg文件，位于data/regV2下 |
| from | 否 | 本MOD需要包含的配置表文件名，此文件位于本Mod工程的Excel目录下。需要包含扩展名。 |
资源路径映射文件 Interface/overrides.txt
格式为普通文本文件，每行一个映射规则
具体写法见5.4资源管理。
三、配置表
1、配置表原理概述
《部落与弯刀》中，使用配置表来进行内容的填写。配置表中可以是各项数值设定、公式的配置，剧情和各种跳转逻辑的编写，或者资源引用路径的配置。
配置表是一些独立的excel文件，通过HSFramework提供的工具打包成xml或可执行的二进制文件(values文件)。具体流程为：
如上图，开发流程为：
1、MOD开发者修改配置表（excel）
(1) 注：reg为我们默认提供的excel语法约束文件，MOD开发者不需要修改
2、运行打包工具生成可执行文件（values）
3、启动游戏客户端对mod包进行调试
请特别注意：
1、修改配置表推荐使用wps工具；
2、配置表中各项数据有自己的语法和格式要求，一旦输入出错，很可能在上图的2（打包）或3（运行）环节出错。请注意报错信息；
3、Excel中请不要留无意义的空行空列，可能会导致未知错误；
4、不建议大量修改然后一次性测试，否则很难定位问题所在。建议少量修改后随即测试，方便第一时间排查解决问题；
5、由于玩家存档会依赖于配置表中的定义，所以不要对配置表中指定ID进行删除，这样导致的结果会是使用本MOD的玩家，既有存档可能会损坏（因为找不到这个被删除的ID了）。正确的做法是将老的数据标记为过期，新建一行作为新的ID来定义；
2、数据类型
数据类型设置具体excel的一行中，我们可以填入的数据格式。
这个格式在reg文件中定义（参考样例工程的data/regV2下的各个文件中type的定义）
常用的格式如下
int 整数
float 浮点数（小数）
string 字符串
如果在excel中填写出错，则打包时会报错。
3、变量和条件表达式
特别注意：脚本编辑时注意所有特殊符号必须为半角！！！
条件表达式组由多个形如" [%condition%][=]1"这样的条件表达式组成，以符号"|"(或) 或 符号”&”(与)进行连接，”&”(与)的优先级大于"|"(或)的优先级，当条件表达式左右值均为整数字符时，将返回其数值大小的比较结果，否则只能执行字符串比较切仅支持[=]和[<>]两种判定。
例如: [%result_code%][=]1| [%player_money%][>=]100 表示当结果为1或玩家身上有100金钱时执行
而 [%player:level%][>=]3& [%player_money%][>]100 表示玩家等级大于等于3并且身上的金钱大于100时执行
注：由于历史原因，目前游戏实际excel填写中，[%xxxx%]和[$xxxx$]没有区别，都可以使用。
条件表达式可以参考各个 XXX触发器.xls 中的相关配置。
4、事件指令语法
特别注意：脚本编辑时注意所有特殊符号必须为半角！！！
指令和参数使用*分割，参数之间一般使用#分割。由于对话指令大量被使用，我们在编写时允许省去对话指令的填写。
在默认调用事件时，会传入当前的一些环境变量。开发者可以使用诸如CUR_ROLE、[%tagrole%]等写法来使用变量。
具体指令请参考附录：全指令说明
5、其他配置表隐含语法
一些配置表中会有自己的隐含语法，如果填写不对，在打包时不一定报错，但在运行游戏时会有相关错误。具体请参考我们的各种样例excel来进行填写。
6、MOD的配置表工作原理
各个excel中都包含自己的ID，如果有重复的ID，则后加载的MOD会覆盖之前的。这样也就为MOD修改游戏有了可能，例如标准游戏中《C初始设定表.xls》中定义了
“init_pos”为红石城外峡谷出生点:980,-1246
则可以在MOD中添加一个初始设定表，重写“init_pos”这个KEY，就可以实现修改游戏初始出生位置的功能。
四、资源管理
1、MOD资源管理概述
资源指游戏中使用到的图片、音乐、模型、动作、特效等等。
《部落与弯刀》游戏使用全局统一的资源命名空间，每一个资源对应唯一的全路径。你可以在MOD中定义资源的“重写规则”，从而实现替换或者新增资源的功能。
你可以在Interface/overrides.txt定义这个重写规则
比如ABS\Audio\*>:\Buildsource\Audios\* 代表的是本MOD下的ABS\Audios目录下的所有内容，覆盖或添加到原BuildSource\Audios下所有内容（如果原来有相同文件则覆盖，否则新增）
你可以在这里定义重写ABS或RES下的具体规则，支持通配符（如*代表所有），也支持具体指定文件。
现有部落与弯刀的资源集合请参考全资源对照表。
2、通过标准文件系统导入RES资源
默认RES下所有的文件都将在生成MOD时拷贝到发布目录，在简易MOD工程和专业级MOD工程下，都会生效。
3、在Unity下导入ABS资源
默认ABS下每个目录都会被打包成一个单独的assetbundle包，
只有在专业级MOD工程，在unity下启动打包MOD才可以生效。
五、音频管理
待编写
六、捏脸工具
你可以使用部落与弯刀的捏脸素材对NPC的外貌进行修改，在MOD编辑器-捏脸工具中可以进行自有组合捏脸。
捏脸的内部数据位于此：
在此文本框编辑后，点击导入可以查看其他的捏脸。
捏脸后复制此段代码，即可作为角色的外貌信息导出粘贴到对应的配置表中。
七、技能编辑
技能通过修改技能配置表以及重写 Assets/BuildSource/SkillData/*.txt 实现，具体规则请见《全指令说明-技能命令编辑说明》
可以通过技能编辑器进行实时编辑和调试
八、3D模型和动作
待支持，需要专业级MOD工程
九、粒子特效
待支持，需要专业级MOD工程
十、地图编辑器
待编写