-
Notifications
You must be signed in to change notification settings - Fork 2
ThpsQScriptEd
ThpsQScripted is meant to be a fast and lightweight qScript editor. Main goal for this project is to fully support the original Neversoft qScript syntax.
Disclaimer: This tool is not ready for production. Do not edit important files without a backup. This tool is provided as is and there are no any guarantees given. Use this tool at your own risk.
- random inside another random - aka random(@random(@x @y) @z)
- newer thug+ random
- thug2+ ifs with offset
- thug2+ endswitch?
Report bugs if found any, but please make sure it's the actual tool bug and not a missing closing bracket. provide a minimum viable script to reproduce the problem in your report.
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 basically an advanced general-purpose replacement for ideas behind trigger files of Apocalypse engine, used for NodeArrays in early THPS games.
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.
Unfortunately, while most THPS games are using the same qScript, it evolved over time and some new features were added, making new scripts incompatible with older games.
- THPS3 has the most limited support and the most basic set of opcodes. while some opcode were reserved for specific operations, they were not implemented yet.
- THPS4 introduced math operators (+, -, *, /, <, >, =>, >=), comma separators, switch/case clause, etc. Basically, all the stuff meant to be there from the beginning.
- THUG changed binary format of Random clause.
- THUG2 introduced additional if/else clause with offsets.
WARNING, this feature wasn't implemented properly QScripted analyzes imported script and sets the compatibility level of current script. This also affects the way some specific opcodes (like random) will be saved to QB. User can (and should) track current script level by checking the bottom right corner of the application. It is only updated on import/export. If user works with a specific game, it is recommended to change Minimum QB mode to the corresponding value. It will ensure that correct export options for the game are chosen.
Please note that this only tracks script level on the opcode level. It doesn't check if a function exists in traget game exe or if you're passing correct params, etc. Synctatically correct script is not guaranteed to work in the actual game as there are more factors.
Working with QScripted
File -> Open: Fires a dialog window to locate a Q or QB file. Bound to Ctrl+O File -> Save: Fires a dialog window to save Q file under current name. Does not compile in QB. Bound to Ctrl+S File -> Save As: Same as Save, but will always ask for a file name. File -> Compile: Compiles current script to QB, saves source to Q and creates backup file, if enabled. Bound to F5 File -> Exit: Closes the application. Bound to Alt+F4.
Tools -> Dump hashes in text: creates a CSV file of the current symbol cache. Tools -> Dump hashes in QB: creates a QB file of the current symbol cache. Tools -> Clear global cache: purges everything from symbol cache. Tools -> Parse NodeArray: Reads nodearray from current script (if available) to allow some extended editing. In progress. Tools -> Brute: Allows user to brute force a certain checksum. Takes millions of years. In progress. Tools -> Grep: Selects all lines containing certain text within. Default values include scripts and gaps. Tools -> Settings: Opens QScripted settings window. Tools -> Rollback: This submenu allows user to pick an earlier version of the script, if any availble. Works if backups are enabled.
Editor -> Word wrap: Toggle word wrap in main text editor. It is not advised to have it turned on due to performance reasons. Editor -> Font...: Allows user to change text editor font and text size. Editor -> Theme dropdown list: Allows user to change editor's color theme. Editor -> Hide scripts list: Toggles the script list on the left side.
Help -> Manual: Opens this document. Help -> About: Brief application info.
Send to external editor: opens up current script text in an external editor, if chosen.
Import
Apply cosmetic fixes: on import, changes text formatting slighty. Adds extra line feeds between scripts, adds extra line feed between } and { (useful in nodearrays) and more. Prefer tab for nesting: Uses TAB symbol for nesting instead of spaces. By default 2 spaces are added. Prefer symbolic operators: (not, or, and) will be imported as (!, ||, &&). Uppercase keywords: every keyword will be uppercase (i.e. SCRIPT instead of script) Show angle values in degrees: will convert radian angles to degrees Round angles (may lose precision): this option will round angle value to 2 decimal places. Without this option turned on, 180 degrees will be presented as 180.00001
Export
Use short new line symbol: picks between 0x01 and 0x02 opcodes for line feeds. Doesn't really make any change so it is recommended to use 0x01 aka the short one. It is known however, that thps3 is more strict with line feeds in 0x02 mode. Save symbols in a separate file: with this option turned on, current symbol cache will be saved as a .sym.qb file instead if being dumped along with the script. Remove trailing line feeds: this will remove multiple line feeds from compiled file. This occurs when you have comments or empty lines in your code. Keep in mind that if this option is turned off, every line feed in script will be added to the compiled file, which may be useful for formatting if you're not planning to save q files.
Behaviour
Backup Q sources: enables backups for Q files, required for rollback feature. Always load Q source if available: with this option on, the existing Q file will be opened automatically if you'll try to decompile QB.
External editor
User can choose an external editor to edit the script. Click Browse... button, locate your text editor executable and confirm your choice. If editor is chosen, Send to extrenal editor menu item is available.
Minimum QB mode
Sets up the minimum QB compatibility mode on export.
vadru for awesome thps modding stuff. inoX for writing THQBEditor (assisted by vadru). TnT for bringing attention to THPS 2003 BAK files. everyone who ever contributed to the QB format.