ncs2nss - A New NCS Decompiler

[lachjames 24]

Hi

I've spent the last month working on a new decompiler for NCS code, and I'm ready to share my work in progress with you all. It works properly on many scripts, but there are still situations where it produces incorrect code (but the issues are usually relatively minor).

I started this project both because an updated, open source NCS decompiler would be useful to me, and also to learn more about decompilation theory. It's a fascinating topic - I plan to create a YouTube video series on decompilation, using this code as an example. It's also meant to be a reference for others who want to implement an NCS decompiler for themselves (e.g. in C++ for the xoreos-tools project), or for those who want to learn decompilation in general - although NCS is a relatively simple language to decompile (for many reasons, discussed in the GitHub readme), I use very little in the way of "heuristics" and have based my algorithms mostly on the famous 1994 Cifuentes thesis "Reverse Compilation Techniques". I'll keep you all updated if you're interested in any educational content I produce based on this project.

Relative to DeNCS, my code has some new features (some implemented fully, some still in the works), including:
 - Detecting if-else if-else if-...-else chains and not using nested ifs (done)
 - Doesn't have any problems with ACTION assignments to global variables (DeNCS fails on this, which is one of the main reasons some K1 scripts don't work in DeNCS) (done)
 - Handles recursion gracefully using a technique I came up with (which I believe might be novel) (WIP but mostly done)
 - Detecting includes and using the source code from the game's NSS files rather than the decompiled code (WIP)

It works quite well, but it's not perfect yet and there are issues (take a look at the GitHub README for more information). Please be very careful if you want to use this for your mods, and (if possible) decompile scripts with the original DeNCS as well to check for consistency. If in doubt, I'd trust DeNCS over my decompiler for now.

You can find the complete source code on GitHub at https://github.com/lachjames/ncs2nss as well as instructions on using the decompiler if you'd like to give it a try.

I'd be very grateful for any suggestions or issues anyone would like to raise I'm aware that other decompiler projects are currently in the works, and I'd be more than happy to work with anyone who would like to work with me.

I've licensed the code under GPL 3.0; my understanding (I'm not a lawyer) is that you are welcome to use the code for anything as long as you open source that code too. At the very least, this is my intent. This is the same license xoreos-tools uses, so it seems reasonable. This project relies on xoreos-tools for disassembly; Windows binaries are included in the xt/ folder (but I intend to remove this before any official release, or at least work with @DrMcCoy to make this automatically update to the latest version of xoreos-tools).

 

[DrMcCoy 40]

On 7/22/2020 at 9:09 AM, lachjames said:

I've licensed the code under GPL 3.0 [...] This is the same license xoreos-tools uses, so it seems reasonable

Technically, this is not quite correct. xoreos-tools is GPLv3+, with the additional "or later" term. I.e. "licensed under the terms of the GNU General Public License version 3 or (at your option) any later version", as it's stated in the README.md and the comment-header of all source files.

The reason this exists is so that code can be upgraded from one GPL to the next version without having to ask every contributor for approval.

You don't specify that in ncs2nss, so with just the GPLv3 license text, this code is by default GPLv3 exclusive. There's no separate full license text for the variant, it's part of §14, you only have to state this intend (preferably with that exact phrasing) where you say that the code is GPLv3.

(Best practice is also that you add a small blurb to the top of all source files stating the license, just to make sure that it's absolutely clear. You can see an approach in all xoreos project source files, for example. Then again, it's also best practice to explictly state the copyright holder in all files, but I've outsourced this into the AUTHORS file and only reference that file in the comment header.)