OpenAdhoc is an open-source re-implementation of the proprietary "Adhoc" scripting language used in Gran Turismo games. OpenAdhoc allows logic-based modding as seen on the GT6 Spec II Mod and GT4 Randomizer/Spec II, among other fan projects currently in development.

This repository contains compilable game scripts re-created from originally compiled ones. This allows source-code level editing for scripts that have been successfully reverse-engineered in Adhoc-based GT games.
GT4 Prologue, GT4, Tourist Trophy, GT HD, GT5 Prologue, GTPSP, GT5, GT6, GT Sport, and all games in between them are in the scope of OpenAdhoc.

Scripts operate nearly as the whole of game logic, while the executable mostly serves as the engine and exposes libraries to the script interface. The games use a system of "projects" to divide the major menu types. Each game mode is made out of a project folder containing the Adhoc logic script(s) (.adc), the UI definition script (.mproject), and assets: localization files, textures, models, and animations packaged into container files (.gpb).

Adhoc Toolchain version 1.3.5 is required to compile game scripts. The tool itself is command line-based without a native GUI, however it does have a VS Code Extension, and a Python GUI wrapper for streamlined usage / workflow.

• adhoc build -i path:\to\.yaml\project\file -o path:\to\output\.adc\file
  or
  
• adhoc build -i path:\to\.ad\source\file -o path:\to\output\.adc\file -v Adhoc Version (5,7,10,12, etc.)
  or
  
• "Run Build Task (CTRL+SHIFT+B)" with the VS Code Adhoc Extension on any source file or project file.
  or
  
• Use the Python wrapper script for a straightforward GUI to send commands to the program.

For more details refer to the Adhoc Page on the Modding Hub.

• To contribute to OpenAdhoc, the 1st step is to disassemble an original adhoc script (.adc), arriving at an intermediate translation of the bytecode that is understandable enough to convert into full source code.
• The Adhoc toolchain allows disassembling scripts into an assembly-like text form. Most scripts contain symbols which are mandatory and thus allows reconstructing code back into source. Very rarely did syntax have to be made up to support specific adhoc features due to no original source reference, so the documentation is the code.
• To disassemble a script, run the following command: adhoc path:\to\.adc\file
  

Translation

• Understanding how to read the disassembly can be challenging at first.
• Play around with adhoc first. Learn the basics, the language, and more. Compile basic code, investigate the disassembly, optionally have GT6 run your code using TinyWeb, through RPCS3
• Refer to the repository for examples of matching code.
• Translating by hand is a time-consuming and a somewhat steep process, but it is still far easier than decompiling matching assembly language.
• Once you understand Adhoc well to the point where you know the bytecode, can reverse projects manually yourself and know general compilation process inside-out, you may train an AI model to translate the disassembly for you by having it help you edit code that's already translated, and attempt to have it decompile disassembly every so often. The key to training it is providing a lot of adhoc source code, and over many separate chats over time. It needs to learn the format of adhoc much moreso than the disassembly. This can take a very long time before it gets any good, but if it does it can make short work of even the largest scripts.
  

// 1st column is the hex location of the instruction in the binary file.
// 2nd column is the source line number.
// 3rd one is the instruction index for the current code frame.
// Rest is instruction contents.

// *FUNCTION_DEFINE is a new function declaration, equivalent to 'function onActivate(context) {
1A4E| 118| 30| FUNCTION_DEFINE - onActivate(context) '
> Instruction Count: 43 (1A7F)<br>
> Stack Size: 6 - Variable Heap Size: 7 - Variable Heap Size Static: =Variable Heap Size<br>

// Evaluating a module path. Equivalent to 'Slide::slide'
1A87| 109|  0| VARIABLE_PUSH: Slide,slide,`Slide::slide`, Static:2
1AB0| 109|  1| EVAL

// Accessing the isPlaying attribute of above path, so 'Slide::slide.isPlaying'
1AB5| 109|  2| ATTRIBUTE_PUSH: `isPlaying`<br>
1AC5| 109|  3| EVAL<br>

// Calling it. So we're making a call with 0 arguments, so we have: 'Slide::slide.isPlaying()'
1ACA| 109|  4| `CALL: ArgCount=0`<br>
1AD3| 109|  5| EVAL<br>

// This is a unary operator so we want to check if the above is false. Essentially this is 'if (!Slide::slide.isPlaying()) { ...'
// The JUMP_IF_FALSE index essentially is the end of the if block.
1AD8| 109|  6| UNARY_OPERATOR: ! (`!`)
1AE0| 109|  7| JUMP_IF_FALSE: Jump To Func Ins 39

// NOPs are used in earlier versions whenever a curly bracket was used in the original source code. This would have allowed a debugger to step through it.
1AE9| 110|  8| NOP

// Making yet another call, this time with one argument. Equivalent to 'main::sound.play("ok")'
1AEE| 111|  9| VARIABLE_PUSH: main,sound,main::sound, Static:3
1B15| 111| 10| EVAL<br>
1B1A| 111| 11| ATTRIBUTE_PUSH: play
1B25| 111| 12| EVAL<br>
1B2A| 111| 13| STRING_CONST: ok
1B33| 111| 14| CALL: ArgCount=1
1B3C| 111| 15| EVAL<br>
1B41| 111| 16| POP_OLD  // We aren't doing anything about the return value so it is being POP'ed.

// ...
// Skipping ahead, we reach the bottom of the function. SET_STATE is used as flow control, and in this case indicates a return to parent frame/function.
// (in particular, 2 is equal to EVENTRESULT_FILTER, which is a ui define for input control and whether to process other events).
// If a return was not manually specified, the compiler will always insert one (otherwise the function would never actually return).
1C46| 117| 39| INT_CONST: 2 (0x02)`<br>
1C4F| 117| 40| POP_OLD`<br>
1C54| 117| 41| SET_STATE_OLD: State=RETURN (1)`<br>

function onActivate(context)
{
    if (!Slide::slide.isPlaying())
    {
        main::sound.play("ok");
        Slide::slide.doPlay();
        sensitive();
        SlideRoot.setFocus(Stop);
    }

    return EVENTRESULT_FILTER;
}

• One golden rule before anything: Always, always, always make sure that you are running the latest version of the toolchain.
• The 1st roadblock is squashing any mistakes in translating the disassembly if your translated code doesn't at least compile. You'll be on your own until you can get it to compile.
• Once you successfully compile it, the next step is to revise the translated code to get it to completely match the original compiled code. To do so, disassemble both the original .adc and your new .adc. Use the included GTAdhocCompare.py script in the Toolchain's scripts folder to diff them. This will output an html file letting you view both disassemblies side-by-side. Red highlights indicate missing logic, and green highlights indicate added logic. Revise your translated code until all relevant red and green highlights from the comparison are eliminated.
• Use the highlighted n link to navigate between differences, do not just scroll up or down to find mismatches. The n will jump to the next difference.
• You should compare built scripts in multiple passes. For the first pass, ensure that most things match by comparing with GTAdhocCompare.py. Next, compare with GTAdhoCompare.py with the -j argument. This also allows comparing jump instruction indices to make sure branches match aswell.
• The more passes the better. Human mistakes are expected such as typos, wrongly recognized branches, and so on. You can't expect to decompile correctly on the first try even if you are certain. You may still be left with dozens of mismatches you didn't pick up between passes.
• Refer to below for things that can be omitted or not.

• The logic should be perfectly matching. No typos, misnaming, anything that otherwise would make a script behave differently. Sometimes because of compiler differences it may not be possible, but the goal is to have the logic match nonetheless.
• All code of any kind should be present in the scripts; bugs should NOT be fixed but should always be marked with a // BUG: <comment> block. An example of this is usage of undeclared variables, typos.
• Usage of PROJECT and ROOT defines should be used everywhere to replace the current root name. Example: MyMenuRoot should be replaced with just ROOT (which should match the file name aswell).
• Usage of other defines must be used when applicable such as EVENTRESULT and PAD defines (list here)
• You should use preprocessor macros when the source code clearly shows use of one (i.e many statements on the same source line is a hint that a macro may've been used).
• Comments to help understand code in general are not needed but appreciated.
• GT4 and earlier - bool instructions did not exist, and are instead represented by a integer instruction instead. When applicable, try to recognize when bools are actually used (0 is false, 1 is true).

• Following line numbers - attempting to follow line numbers for code that may be stripped from undefined original preprocessor directives or missing comment blocks can leave holes in the source, therefore prefered not to follow line numbers for better readability. Please make sure that the code is pretty much written in the same style as the projects already on this repository.
• SOURCE_FILE instructions - These will be off due to path differences & the custom compiler emits them per file (on enter, and on exit to resume to the previous file). Earlier than GT5 had an issue in their compilers where SOURCE_FILE instructions were sometimes not emitted at the right spot.
• Logic order - It is common that scripts were written using such pattern: nil != myObject or "Dog" == myString. For readability, literals should always be on the right-hand side such as myObject != nil.
• LOGICAL_OR/LOGICAL_AND jump indices - The custom compiler may be slightly inaccurate when emitting these instructions. Namely the jump indices may look off (jumping to other LOGICAL_* rather than the end of a statement). This is okay to omit as the compiler does not implement short-circuit evaluation optimization like the original compiler does, but the way the instructions are executed will still produce the same result. However it does make it a little harder to make sure that the logic matches when both LOGICAL_AND and LOGICAL_OR's are used within the same statement, so make sure to review those instructions carefully!
• For GT5 and above, LEAVE instructions may be emitted that essentially cleanups local variables used within a statement (one is emitted at the end of any block statement } that should be clearing some variables). These may throw the jump indices a little, but as long as the logic still matches, this is okay to omit. GTAdhocCompare will not show leaves by default. The -j argument will not show them either, but may show a difference in jump indices. Make sure to review them. You can also use the -l argument to include LEAVE in the compare output.

Once your translated code is fully matching (or at least as close as possible), fork the repo, add your files to your fork, then make a pull request. In the Pull request conversation, add any relevant information about your new files. If you have any mistakes that you are unable to correct, point them out for review and suggestions. Preferably your projects should be already matching and thus doesn't need verification. Otherwise open an issue.

• August 2020 - Initial breakthrough in Adhoc, dissasembler built based on reverse-engineering
• September 2020 - Master Mod release for GT5 with hex-edited script code edits
• July 2021 - GT6 Spec II Mod release for GT6
• December 2021 - Breakthrough. GT Sport Closed Beta build dump, contained a few scripts in source and compiled formats which allowed to figure most of the syntax to be similar to Javascript and Python. Stack understanding later came thanks to a random thought by ddm999 and the first custom "hello world" script compilation within the GT6 Web Server successfully ran to completion.
• January 2022 - First fully recompiled project (boot).
• February 2022 <-> December 2022 - Dozens of projects successfully recreated.
• December 2022 - Source release.
• September 2025 - GT4 and GT PSP reach 100% matching Adhoc decompilation.

This project uses the GNU GENERAL PUBLIC LICENSE.

This project is not affiliated with "Polyphony Digital Inc." , "Gran Turismo", "GT", or any other projects by the aforementioned entities.