Development Tutorial

1. Concept of Loops

The flow chart of the major looping logics in Sands of Salzaar

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.

The flow chart of executing an event

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).

Reference File of Configuration Table: valuebundle/default.xml

The file format is .xml, and the file can include multiple referenced Excel files.

Parameter	Allow Empty Parameter	Description
file	No	The names of the configuration tables of your MOD. This file is located in the Excel directory of this MOD project. filename extension is required.

Mapping-Rule File of Configuration Table: valuebundle/INDEX.xml

The file format is .xml, and the file can convert multiple referenced Excel files.

Parameter	Allow Empty Parameter	Description
reg	No	Corresponds to the file of mapping rules, located under directory data/regV2
from	No	The names of the configuration tables of your MOD. This file is located in the Excel directory of this MOD project. Filename extension is required.

Mapping File of Resource Path: Interface/overrides.txt

The file is a common text file, one mapping rule per line.

Please refer to 5.4 Resource Management for more details.

3. Configuration Table

3.1 Basic Principles of Config Tables

In Sands of Salzaar, we use the configuration tables to fill in contents. In these tables, you can set different values, configure formulas, write a story, design a logic jump, or configure the paths of resources that are referred to.

Configuration tables are independent excel files, which can be packed up as xml files or executable binary files (values files) with the help of the tools in the HSFramework.

The flow chart of packing configuration files

As the flow chart has shown above, the process of development is:

· MOD developer edits their configuration tables (excel)

Note: the reg file is our default syntax restriction files of Excel. MOD developer does not need to edit it.

· Run the packing tools to generate executable files (values).

· Run the game client to debug the MOD package.

Please pay special attention:

· Microsoft Excel is recommended for editing configuration tables;

· Each data has its own restriction for syntax and format. If the input is wrong, you will probably encounter errors in the second (pack) or the third (run) stage. Please pay attention to the error information;

· Do not leave empty rows amid the Excel tables for no reason. Otherwise, it might cause unknown errors;

· We do not suggest you make a high number of changes and then debug them all at once, which makes it hard to locate the roots of errors. Therefore, we recommend you to start debugging after making a few changes. It is easier to identify and fix issues this way.

· As players’ saves depend on the definitions in the configuration tables, please DO NOT delete specific IDs in the tables. If the IDs are deleted, players who are using the relevant MODs might have their saves corrupted (since the deleted IDs cannot be found). The correct way is to mark the old data as “obsolete” and start a new line to define a new ID.

3.2 Data Type

Data type refers to the format of the data we write in a specific line in an Excel file.

This format is defined in the reg file (please see the sample project, and refer to the definitions of types of different files under the path data/regV2).

Common formats are as follow:

int—integer

float—floating point（decimal point）

string—character string

If there are format errors in the Excel file, you will encounter an error report when packing.

3.3 Variables and Conditional Expressions

Please pay special attention: when editing scripts, you must use halfwidth (aka common English) punctuations!!!

A conditional expression group consists of multiple conditional expressions like " [%condition%] [=]1", connected by symbols such as “|” (or) and “&” (and). “&” (and) has a higher priority than “|” (or). When both sides of a conditional expression are integers, a comparison between them will be returned as a result by default. Otherwise, we have to use character strings to make the comparison, and this method only supports the use of [=] and [<>].

E.g. “[%result_code%][=]1| [%player_money%][>=]100” means that directives will be executed when the result is “1” or the player has 100 coins, while “[%player:level%][>=]3& [%player_money%][>]100” means that directives will be executed when the player is at least Lv.3 and has more than 100 coins.

Note: Due to a historical reason, both [%xxxx%] and [$xxxx$] can be used in the configuration in Excel.

Regarding conditional expressions, you can refer to the configurations in different kinds of trigger.xls.

3.4 Event Directive Syntax

Please pay special attention: when editing scripts, you must use half-size punctuation!!!

We use “*” to separate directives and parameters and “#” for separations between parameters. Since a high amount of chat directives are being used, we are allowed to disregard chat directives when coding.

When transferring an event by default, certain environment variables will be imported. Developers can adopt different coding methods such as CUR_ROLE and [%tagrole%] to use the variables.

For detailed directives, please refer to the appendix—Directive Instruction

3.5 Other Hidden Syntax of Config Tables

Some configuration tables have their hidden syntax. If you fill in the wrong syntax content, there might not be an error report when packing, but errors will occur when you run the game. Please refer to our different sample Excel files when filling in the tables. 

3.6 Principles of MOD Config Tables

Every Excel file has its ID. If there are repeated IDs, the newly loaded MOD will override the previous one. Thus, it is possible to use MODs to change the game. For example, we can look at a definition in C Initial Setting Table.xls of the standard game.

“init_pos” is the respawning point in the wild rift outside Redstone Keep: 980, -1246

You can create an initial setting table in your MOD to rewrite the key string “init_pos”, which changes the game’s initial respawning point .

4. Resource Management

4.1 Overview on MOD Resource Management

Resources refer to the images, audios, models, animations, special effects, and other content we might be using in the game.

Sands of Salzaar uses a global namespace for resources. Each resource corresponds to a unique fall path. You can define the “rewriting rules” of resources in your MOD to change the old resource or add a new one.

You can define the rewriting rules in Interface/overrides.txt.

For example, “ABS\Audio\*>:\Buildsource\Audios\* ” represents all content that was originally in the directory ABS\Audios and was later added to BuildSource\Audio (or has overwritten the original content in BuildSource\Audio).

You can define or rewrite the specific rules under ABS or RES in this text file. Specific file reference, as well as Wildcard characters, is supported (for example, “*” represents “all”).

For the current collection of resources in Sands of Salzaar, please refer to the Comparison Table of All Resources.

4.2 Import RES Resource via Standard File System

All files under RES will be copied to the default game-release directory of Steam when the MOD is created. It works in both Simple MOD projects and Professional MOD projects.

4.3 Import ABS Resource in Unity

Every directory under ABS will be packed into a single assetbundle by default. This is only possible with a Professional MOD project, and you need to use Unity to build the MOD.

5. Audio Management

Please wait for more updates.

6. Face Editor

You can use the face editing materials in the game to change the appearance of NPCs. In Sands of Salzaar Mod Editor-Face Editor, you can do face editing with the current materials.

捏脸工具启动位置示意

The location of the Face Editor

Internal data of face editing is here:

捏脸工具导出示意

In the highlighted textbox, click “import” to view other appearances. After you finish face editing, you can copy and paste this data (as character appearance information) to the corresponding configuration table.

7. Skill Editing

You can edit the Skill Configuration table and rewrite Assets/BuildSource/SkillData/*.txt to realize skill editing. For detailed rules, please refer to Directive Instruction—Skill Directive Editing.

You can do real-time editing and debugging in the Skill Editor.

8. 3D Model and Animation

Function not supported now. Professional MOD project needed.

9. Particle Effect

Function not supported now. Professional MOD project needed.

10. Map Editor

Please wait for more updates.