Starfield Script Extender (SFSE)

By default, CodeGenerator throws an exception if the generated code exceeds the initial maxSize. In AutoGrow mode, the library automatically reallocates and expands the memory.

Important Requirements:

1. You must call ready() before calling getCode() to resolve jump instruction addresses.
2. In AutoGrow mode, 64-bit relative addressing [rip] is not supported.
3. If you need to maintain a pointer to a specific offset within the code, store the offset using getSize() before calling ready(), then access it via getCode() + offset after ready() returns.

struct Code : Xbyak::CodeGenerator {
   Code()
     : Xbyak::CodeGenerator(<default memory size>, Xbyak::AutoGrow)
   {
      // assembly here
   }
 };

Code c;
c.ready(); // Mandatory call

SFSE is compatible with the latest version of Starfield available on Steam.

Note: The MS Store/Gamepass version of Starfield is not supported.

To generate machine code, inherit from Xbyak::CodeGenerator. Inside the class methods, write x86/x64 assembly using a syntax similar to NASM. After calling the method, use getCode() to retrieve the generated code and cast it to a function pointer for execution.

By default, assembly errors are reported via exceptions.

struct MyCode : Xbyak::CodeGenerator {
    MyCode() : CodeGenerator(4096) {}

    void generate() {
        mov(eax, 123);
        ret();
    }
};

// Usage
MyCode c;
c.generate();
using FuncType = void (*)();
FuncType f = (FuncType)c.getCode();
f();

To build SFSE, clone the repository and use CMake to configure and build the project. The build process generates a Visual Studio solution file located at sfse/build/umbrella.sln.

git clone https://github.com/ianpatt/sfse
cmake -B sfse/build -S sfse
cmake --build sfse/build --config Release

Xbyak is a header-only C++ library for x86 (IA-32) and x64 (AMD64, x86-64) JIT assembly. To use it, include xbyak.h and xbyak_bin2hex.h in your project. Ensure they are in the same directory or added to your include path.

On Linux, you can use make install to copy the headers to /usr/local/include/xbyak.

# On Linux
make install

If you want to compile with -fno-exceptions (using gcc/clang), define XBYAK_NO_EXCEPTION. In this mode, errors are reported via Xbyak::GetError() instead of exceptions.

If Xbyak::GetError() returns a non-zero value, an error occurred. You must manually reset the error state using Xbyak::ClearError(). Note that CodeGenerator::reset() calls ClearError() automatically.

// Define this during compilation
// -DXBYAK_NO_EXCEPTION

if (Xbyak::GetError() != 0) {
    // Handle error
    Xbyak::ClearError();
}

By default, CodeGenerator sets the JIT region to read/write/execute (RWX). If you want to follow a stricter security model (e.g., generating in RW and then switching to RX for execution), use the following methods:

1. Initialize with Xbyak::DontUseProtect to keep the region RW during generation.
2. Call setProtectModeRE() to switch to read/execute mode before running the code.
3. Call setProtectModeRW() to return to read/write mode.

For AutoGrow mode, use readyRE() instead of ready() to switch to read/execute mode.

struct Code : Xbyak::CodeGenerator {
    Code() : CodeGenerator(4096, Xbyak::DontUseProtect) {
        mov(eax, 123);
        ret();
    }
};

Code c;
c.setProtectModeRE(); // Switch to read/exec

The loader can be customized using an .ini file. One primary configuration option is RuntimeName, which allows you to specify a custom executable name if you are not using the default (e.g., Starfield.exe).

If you specify a RuntimeName that does not match the actual executable found in the directory, the loader will fail with an error. To revert to default behavior, remove the RuntimeName line from your .ini file.

Labels can be defined using strings or the Label class.

String-based Labels:

• Define: L("label_name");
• Jump: jmp("label_name");
• For long jumps (where relative address exceeds 8 bits), use T_NEAR: jmp("label_name", T_NEAR);
• Use hasUndefinedLabel() to check if a jump target exists.

Label Class:

• Define: Label label1; L(label1);
• Jump: jmp(label1);
• Assign: assignL(dstLabel, srcLabel); (assigns the address of srcLabel to dstLabel).
• Get Address: label.getAddress(); (returns 0 if undefined).

Local Labels: Wrap code in inLocalLabel() and outLocalLabel() to allow duplicate label names in different scopes.