JSRF-Decompilation/documentation/decompilingcpp.md

# Decompiling C++
Like most (all?) Xbox titles and most sixth-generation games more generally,
JSRF is not written in assembly or C as those before it were, but rather C++.
C++ introduces new features that both complicate the final machine code and
weaken the correspondence between said machine code and the original C++
source.

This guide will cover various C++ features appearing in JSRF, explaining how
they manifest in the game's executable and how to properly decompile them, to
the extent possible.  Basic familiarity with C features (e.g. functions,
structs) and how to decompile them is assumed.


## Name Mangling
(on the off chance you actually get symbol names, like from debug info; also
why symbol names don't match in objdiff)


## Classes
C++ classes evolve the C struct to associate the data structure with code,
which are called methods in this context.  Classes can also inherit from one or
more other classes, sharing their data members and access to their methods.
Certain special methods called constructors and destructors can also be added
to a class, and these can be called implicitly when an instance of a class goes
in or out of scope.  Classes can also have fields and methods marked as
private, but these permissions are usually completely erased during
compilation and don't need to be respected by a decompilation.

### `class` vs. `struct`
The `struct` keyword can still be used in C++ and is equivalent to `class`,
except that the former makes all members public by default and the latter makes
all private by default.  Since there's not much reason to make anything private
in a decompilation, one will usually use `struct` declarations in
decompilations rather than `class`.

```c++
// These two declarations are equivalent
class SomeClass {
public: // Makes everything after public
    float    someMemberVariable;
    unsigned anotherMemberVariable;
};

struct SomeStruct {
    float    someMemberVariable;
    unsigned anotherMemberVariable;
};
```

A reasonable way to implement an inherited struct in Ghidra is to define the
base class normally, and then define the child with a first member called
`super` of the parent class type.  Members specific to the child class can then
be inserted afterwards.

### Class Methods
Methods are functions declared within a class's namespace, like so:
```c++
class SomeClass {
    // Regular data members
    float    someMemberVariable;
    unsigned anotherMemberVariable;

    // Methods declared in class definition
    SomeClass(int anArgument); // Constructor
    ~SomeClass();              // Destructor

            void regularMethod(unsigned anArgument);
    virtual void virtualMethod(char *   anArgument);
    static  void staticMethod (char *   anArgument);

    // Can also provide entire definition in class
    float anotherMethod(float x) {
        this->someMemberVariable += x;
        return this->someMemberVariable;
    }
};

// Definition of a method declared in class
void SomeClass::regularMethod(unsigned anArgument) {
    this->anotherMemberVariable -= anArgument;
}
```

Methods can then be accessed and called with member access syntax, like
`classInstance.regularMethod(3)` and `instancePtr->anotherMethod(1.2)`.

Static methods are indistinguishable from regular functions in compiled code,
so they probably won't see much use in decompilations.  They don't have access
to the `this` pointer that other types of methods can use.

Regular methods are similar to regular functions, but have an implicit first
argument called `this` representing a pointer to the object that the method
was called from.  Some C++ implementations use a different calling convention
for method calls, such as Microsoft's implementation for the Xbox using the
`__thiscall` convention where the `this` pointer is passed in the ECX register
while all other arguments are passed on the stack.

Constructors and destructors function largely like regular methods, but
implicitly return the `this` pointer.

Virtual methods are methods that can be overridden on child classes.  They're
not called directly, but instead called through a hidden first member that
points to an array of method function pointers, usually called a vtable (Visual
C++ 7 calls it `` ClassName::`vftable' ``).  If a destructor specifically is
made virtual, additional "deleting destructors" may be generated as well, which
are methods taking one boolean argument that call the destructor and then,
depending on the argument, free the object's memory.

(TODO: how to implement methods and vtables in Ghidra)

### Inheritance
Child classes can be used in most places that their parent class can be used:
```c++
// Class inheriting from SomeStruct
struct SomeStructChild : SomeStruct {
    // Inherits these from SomeStruct:
    //     float    someMemberVariable;
    //     unsigned anotherMemberVariable;
    char * additionalMemberVariable;
};

// Could call this with either a SomeStruct* or SomeStructChild* argument
float getSomeMemberVariable(SomeStruct const * const ss) {
    return ss->someMemberVariable;
}
```


## The `new` and `delete` Operators
One way to allocate an object in C++ is using `new` and `delete`.  The former
can both allocate and construct the object, while the latter is analogous to
calling `free()`.  Each has a corresponding `operator new()`  or
`operator delete()` function called implicitly.

The generated code for a use of `new` with a constructor (like
`SomeStruct ss = new SomeStruct(7)`) performs the allocator and constructor
calls separately, roughly as follows (as it would appear in Ghidra; note that
Ghidra shows explicitly the passing of the `this` pointer):
```c++
SomeStruct *ss;
ss = (SomeStruct *)operator_new(0xc);
if (ss == NULL) {
    ss = NULL; // No, I'm not sure what the point of reassigning NULL is
}
else {
    SomeStruct::SomeStruct(7);
}
```


## Exception Handling