Skip to content

TRLE Script Compiler v1.1.0 - now supports #include, #define

Choose a tag to compare

@ActiveMath ActiveMath released this 16 Jul 02:07
· 7 commits to master since this release

This release adds some new features which were not present in the original Core Design script compiler, therefore allowing the user more flexibility while creating level (and, possibly, language) scripts.


First and foremost, the #include preprocessor directive is now supported. Such a feature can be very useful in large, collaborative level-building efforts where multiple builders maintain their own per-level scripts i.e. the individual (or perhaps more) [Level] script chunks. It can be a tedious task to transfer these files to other builders only so that the final script could be compiled by copying and pasting the chunks themselves into a single, monolithic script file.
This directive can eliminate these problems simply by allowing every builder to send in their own text files consisting of a single (or more, depending on how many levels they are working on) [Level] chunk to the team member who is in charge of final script compiling. Then, all the pieces come together simply by using #include like this:

(inside the main script.txt, created by the script maintainer)

#include "gameOptions.txt"
#include "gameLanguages.txt"

[Title]
Level=       ...

#include "teamMember1_levels.txt"
#include "teamMember2_levels.txt"
...
#include "teamMemberN_levels.txt"

In this fashion, repetitive work consisting of copy-pasting was completely avoided in favour of simply instructing the preprocessor that certain text-files should be placed at their respective positions within script.txt. Another useful corollary to this approach is that, should any future changes arise to any of the builder's level scripts, the only thing they need to do in order to get everything updated is to change their "teamMemberN_levels.txt" files and send them over to the script maintainer who will then simply recompile script.txt, without having to deal with the hassle of copy-pasting once and possibly making mistakes that way.

Further notes: nesting of #include directives is supported, but the user must make sure that they do not generate any cyclic dependencies i.e. situations where one file includes another, and the latter also includes the former! In case that happens, program behaviour is undefined and will likely end with a stack overflow and a crash. All the file names must not contain the comma character.

The next and last feature added to this version is the ability to create user-defined macros, i.e. #define statements within (both gameflow and language) scripts. Macros can ease builders in writing common script blocks, be it on a level-wide or game-wide scale.
For example, throughout a project, a builder may tend to repeat certain script commands and their respective arguments. Instead of having to type in the same text blocks over and over again for many levels, the builder could tackle this issue by using the #include directive, however that is an impractical solution because it would require using a large number of very small text files describing every such scripting situation.

A better solution is to use user-defined statements, such as KEY_APPEARANCE , which would subsequently, when processed by the script preprocessor, be substituted with their corresponding meaning, assigned by the builder. This way, the builder does not have to think hard about the arguments or the command name every time when writing that repetitive command or argument(s) in question.

The #define macro follows the syntax of the C programming language (just as #include does) with the only limitation being the inability to use anything else than the form: #define x y, where x and y are strings that can contain arbitrary characters except white spaces and commas. The strings must not be zero-length.
This allows the builder to store entire command statements within a macro and simply use the macro in the script whenever they want to use the corresponding command. The advantage here is also that they can easily change the corresponding command once and not have to go in and manually correct each and every appearance of the command inside the script file(s).
A point worth noting is that comments can freely be used as usual to denote what exactly is on the builder's mind, to leave to-do lists etc. Moreover, macros can be re-defined simply by repeating the same command, just with a different second string.
E.g.:

...
[Level]
#define cloudColour   160,160,192,7   ;experiment with this...
#define levelPuzzle1    Key=1,Token,$0013,$0200,$4000,$0000,$0000,$0002
#define loadCam         69395,-4283,29278,72285,-4304,29773,2    ;todo: check in-game for real coords

Name=             My Little Level
Layer1=            cloudColour
levelPuzzle1
LoadCamera=     loadCam
Level=               DATA\TUT1,107

[Level]
#define cloudColour  128,128,128,-8     ;re-definition of a previously defined macro

Layer1= cloudColour
...

Finally, a special case exists for writing macros. Namely, when the builder wishes to decouple a previously assigned string from a certain macro, they can use the following syntax: #define x x, where x is the previous macro assignee.
Knowing this, the builder can create scripts such as:

...
#define ENABLED DISABLED

[Level]
Name=             Playable Tutorial Level
Legend=           The year 2000, somewhere in Egypt...
Horizon=           ENABLED      ;the horizon doesn't show in Playable Tutorial Level and subsequent levels
...

;some levels later
#define ENABLED ENABLED
[Level]
Name=       Coastal Ruins
Horizon=            ENABLED           ;the horizon shows in Coastal Ruins and subsequent levels
Layer1=     128,128,128,-8
...

Using macros, the user was able to save themselves from the mundane task of editing a potentially large portion of the script file in order to change a single ENABLED line to DISABLED. After a certain number of levels, the user wanted to revert back to allow things to be ENABLED in subsequent levels; they used #define ENABLED ENABLED in order to achieve that.

Further notes: the following construction is allowed:

#define x y
#define y z   ;now, both letters x and y are going to be replaced by z anywhere in the following text

However, constructions such as these are forbidden and will result in undefined program behaviour:

#define x y
#define y x

Combining both #include and #define statements within the same (gameflow or script) file is supported.
The preprocessor will first process all the #includes, followed by all the #defines. This implies that all the user-defined macros defined prior to #include-ing a certain file will carry over to that included file, unless the user precedes the #include statement with the appropriate #define x x macros, as explained above.