SCRambl
Info
SCRambl is a high-level SCR language assembler with an advanced modular design which allows for a deep level of customisation. Compiled SCR scripts are often used by desktop and game software which read the file and execute the appropriate code internally, allowing an easy lower-level way of creating content. SCRambl supports both headered and headerless script compilations with a wide range of support for changing the way their code is generated. SCRambl also has many preprocessor features including macro support and preprocessor blocks which allow for improved code management and maintainability within large projects.
SCR
SCR is a conceptual language based on BASIC, which provides a fully featured scripting environment while maintaining a relatively low learning curve. This language is considered incomplete as many decisions have still not yet been made. SCRambl tries to allow for complete customisation of the SCR syntax through the use of definition files, enabling it to be easily updated, expanded or redone, so much as to allow SCRambl to be used for a wide range of coding styles, optimisation techniques and required usages.
Features
- Fast code parsing & compilation
- Advanced preprocessor
- High construct
- Easy syntax expansion & customisation
- Deeply customisable compilation
- Accurate default SCR syntax
- Fast hashing & lookups
- Syntax expandable from within scripts
- Macros, advanced preprocessor logic/integer expressions, preprocessor blocks
- Fully working string functionality including special character ability using escape sequences
- String escape sequences
- Error detection
- Useful warnings
- Variable scoping
- Configurable code optimisations
- Operators and command overloading
- Advanced configurable type matching and recognition system
- File including
- Project support
- Internal scripting engine
- More customisability
- Performance optimisations
- Customisable header compilation
I started out by building up SCRambl to build a simple native script, debug.sc, which is found in SA's data folder. Once it got over compiling that, I started to make a dent on compiling some native GTA III scripts, which it got through quite well (though I had to remove III specific commands as I haven't built a catalogue of them yet) but I never finished parsing those fully. Eventually I started writing a short script which I am constantly adding and taking bits from to test individual features (test-script.txt) and decompiling them in Sanny Builder to verify the results.
Here are some of the more impressive abilities...
In-script Command Registering and Overloading
#register_command 0EEE MY_COMMAND(i,f,f) MY_COMMAND(1, 0.5, 0.5) // compiles 0EE command #register_command 0FFF MY_COMMAND(f,f,f) MY_COMMAND 3.0 1.2 3.2
SCRambl allows you to define new script-specific commands which is great if you do something like hacking in a new opcode using the script or have added new opcodes using another project-specific file which you don't want to keep globally or wish to share easily. Since the command is defined in the script, no one you give the script to will have to edit any of their configuration files in order to add new opcodes. The syntax of the preprocessor command "register_command" is much like the commands.ini syntax with a few restrictions such as not being able to define an unknown/NOP command.
You can then use a newly registered command after it has been defined or overload it. The first use of MY_COMMAND compiles the 0EEE opcode, because it uses an integer for the first parameter. The second use compiles the 0FFF opcode, because it has a float instead. SCRambl searches through command overloads to find the most fitting one for the job. If the 0EEE variation didn't exist, writing an integer as the first parameter would compile the 0FFF variation using an integer for the float. You can do the same if the 0FFF variation didn't exist. However, a warning will be produced saying that converting a float to int may result in a loss of data.
Native Control Structures
VAR_INT counter REPEAT 5 counter WAIT 0 ENDREPEAT
Decompiled in SB3:
:NONAME_7 WAIT 0 $PLAYER_CHAR += 1 $PLAYER_CHAR > 5 GOTO_IF_FALSE @NONAME_7
Script Constant Support + Local Variable Scope + Arrays + Enumerators + Long Math Lines (lol)
#const
flval FLOAT 4.0
#endconst
{
LVAR_INT int_var int_arr[4] int_idx
LVAR_FLOAT float_var
int_arr[int_idx] = 69 // 1@(5@,4i) = 69
int_var = TRUE // 0@ = 1
int_var += 5 + 4 + timera + 2 + 1 // >> /*
0@ += 9
005A: 0@ += 32@ // (int)
0@ += 3
*/
int_var -= timera // 005A: 0@ += 32@ // (int)
int_var -= PAD1 // usage of an enumerator as a value
int_var = flval // 0062: 0@ -= 32@ // (int) (causes float-to-int warning)
float_var = flval // 6@ = 4.0
}
Built-in Model Constants + Macro's
#define DEFAULT_WAIT_TIME (250 + 5) // obviously DEFAULT_WAIT_TIME will be 255 #define INTERRUPT WAIT DEFAULT_WAIT_TIME // now we can write "WAIT 255" using the macro "INTERRUPT" #define SuperVar LVAR_STRING // yes, SCRambl will be able to turn SuperVars into a full compiler extension #if (defined(SuperVar)) + 2 == 3 // this returns true, so "WAIT 255" is produced instead of "WAIT 0" INTERRUPT #else WAIT 0 #endif INTERRUPT // of course, there are much better ways to use macros... SUPERVAR SVar // guess what? we just declared a SuperVar! easy as 1, 10, 11... get it? #define ADD_MALE_CHAR CREATE_CHAR DEFAULT_MALE_CHAR 0.0 0.0 0.0 CREATE_CHAR PEDTYPE_CIVMALE male01 0.0 0.0 0.0 male_char ADD_MALE_CHAR male_char
Decompiled in SB3:
WAIT 255 WAIT 255 CREATE_CHAR 4 #MALE01 0.0 0.0 0.0 $PLAYER_ACTOR CREATE_CHAR 4 #MALE01 0.0 0.0 0.0 $PLAYER_ACTOR
Pretty cool if I do say so myself...
The Manual
A manual is provided with each version of SCRambl, which documents the features in that version. The manual comes in HTML format, using JavaScript to make it easier to browse and read. This documentation has been tested working with the latest versions of Mozilla Firefox and Google Chrome.
An online copy of the documentation for latest version SCRambl can be found at: https://dl.dropboxus...3209/MANUAL.htm
