ThpsQScriptEd\Understanding qScript

Return to ThpsQScriptEd

qScript is a scripting language created by Neversoft for THPS game series. It was in use since the original release of THPS3 and was later used in most Neversoft games and derivatives of their engine (i.e. Disney's Skate Adventure, GUN, Guitar Hero, etc). The logic behind the script language was to let programmers change the game behaviour without changing actual low-level C++ code. Game parses compiled script files at runtime and calls various game functions corresponding to the scenario described in loaded scripts. This basically allows players to mod the game.

qScript was an advanced general-purpose replacement for the trigger files approach in the Apocalypse engine, used for NodeArrays in early THPS games.

We know what the original language looked like due to several developer oversights. Japanese version of THPS4 contains some debug scripts, likely being localized for the market. It was erroneously saved with .BAK extension and successfully dumped to the master copy of the game. Another leak is the THUG1 source code, containing the source of all scripts in the game.

On the data level, qScript compiles to a binary bytecode file with a qb extension (probably stands for Q binary). There is a set of operations available, bound to specific opcodes. The basic structure of the file is as follows:

opcode_struct
{
    byte opcode
    [xx bytes optional opcode data defined by opcode type]
}

do { read opcode_struct }
while opcode != 0

For example, a new function is declared with a "script" keyword, which is converted into byte 0x23 and the end of function is declared with "endscript" keyword, converted into 0x24.