DEV Community: Gustavo Lopes

Programming with GDExtension: High-Performance C++ in Godot 4 (Part #1)

Gustavo Lopes — Mon, 16 Feb 2026 13:34:00 +0000

When it comes to game development in Godot, GDScript is the primary language in 90% of cases. It is simple, direct, easy to learn, and—most importantly—it is the language specifically designed for the engine. However, it isn't the only option. For instance, we have C#, which offers better performance in certain contexts, more language features, and vast libraries, making it a popular choice for those migrating from Unity. But what about C++?

Using C++ in Godot is the definitive choice for those seeking maximum performance, as it is the very language the engine was built in. Historically, this required recompiling the entire engine every time a modification was made—a complex process that made development extremely slow and tedious. Today, however, we have a much more practical and flexible solution: GDExtension. In this guide, we will focus on exactly that: how to create C++ code for your Godot projects and the essential concepts you need to master.

What exactly is GDExtension?

In simple terms, GDExtension is the official interface for Godot 4 that allows us to register classes written in C++ (or other languages) as if they were native Godot classes. In practice, it functions as a dynamic library. You compile your C++ logic separately using the API as a base, and Godot loads your binary at runtime. You can visualize GDExtension as a USB flash drive for Godot, where the engine is the computer; it allows you to "plug in" and utilize your custom C++ code.

The primary advantage is, of course, performance. If you have a heavy algorithm—such as complex physics processing, AI, or manipulation of large volumes of data—moving it to C++ can result in a massive speed gain compared to GDScript. Furthermore, it opens the door to the vast ecosystem of existing C and C++ libraries, such as OpenCV or SQLite.

The Trade-offs: Complexity and Workflow

There are, however, disadvantages to consider. The first is complexity. Beyond C++ itself being more difficult than GDScript, setting up the environment is undoubtedly more involved than simply opening the editor and coding. You will have to deal with compilers, build scripts, and a slower development cycle. You’ll need to configure significantly more within your C++ classes before they can be tested or read by GDScript.

Finally, you must compile your code for every operating system you intend to target. Unlike GDScript, where the same code is accepted across multiple platforms, C++ is platform-specific. The dynamic library you generate is only compatible with the target platform you choose, meaning you must recompile for different systems and, in specific cases, adapt the code to ensure it functions correctly.

Organizing the Workspace

Setting up GDExtension for the first time is the most labor-intensive part, but once completed, the process is repeatable. In this overview, we focus on the official path using godot-cpp to understand the foundation of how everything works.

If you prefer a more direct path, there are frameworks like Projekt J.E.N.O.V.A. that attempt to make C++ in Godot as simple as using GDScript. These tools offer "one-click" environment setups and hot-reloading. However, such frameworks act as an abstraction layer; you become dependent on their specific systems, which may not track Godot’s updates as quickly and can be harder to debug if something breaks.

One final consideration, this guide assumes a basic understanding of C++ and compilation tools. It is not a C++ tutorial, but rather a map of the Godot integration process.

Phase 1: Configuring godot-cpp

The configuration process is divided into two phases: the one-time setup of godot-cpp, and the ongoing development cycle of your own code.

For the setup, we need two essential tools: a C++ compiler and the SCons build tool (the same one Godot uses). On Linux, the compiler is usually included, while SCons is easily installed via package managers.

# Ubuntu
sudo apt install scons
# Arch Linux
sudo pacman -S scons

On Windows, tools like MSYS2, Cygwin or the Visual Studio Build Tools to provide the necessary environment.

Once the tools are ready, we need access to the godot-cpp repository, which contains the official bindings. The best method is to add this as a Git submodule in your project directory using git submodule add, ensuring you select the branch that matches your Godot version (e.g., branch 4.6 for Godot 4.6).

# Add the submodule (replace '4.6' with your version)
git submodule add -b 4.6 https://github.com/godotengine/godot-cpp.git
# Also, if you are cloning the repository, remember to use this command:
git submodule update --init --remote --recursive

After downloading, you must compile the bindings using your engine’s specific API information. By running the Godot executable with the command --dump-extension-api, you generate an extension_api.json file. This file contains the "blueprint" of how Godot works internally. Copy this JSON into the godot-cpp folder and run scons. This processes the JSON to generate the C++ code that "mirrors" Godot, resulting in a static library that serves as your project's foundation.

# 1. Export the engine API
./godot.exe --dump-extension-api

# 2. Move it to the bindings folder
mv extension_api.json godot-cpp/

# 3. Compile the bindings
cd godot-cpp
scons platform=[insert-platform] custom_api_file=extension_api.json

Phase 2: The Development Cycle

With the configuration complete, we move to the project itself. A clean folder structure is recommended: a folder for the Godot project, the godot-cpp folder, and a src folder for your C++ source code.

my_gdextension_project/
├── godot-cpp/          # The engine bindings (Git submodule)
├── src/                # Your C++ source code (.cpp and .h files)
├── SConstruct          # The build script that ties it all together
└── project/            # Your actual Godot Project folder

Also, is important to note that, when creating C++ code with GDExentesion, there is three important steps:

1 - Creating classes
2 - Registering class data with "bind_methods"
3 - Registering the classes in Godot with ClassDB

1. Creating Classes

In the src folder, every class you wish to expose to Godot requires a header (.h) for definitions and a source file (.cpp) for logic. When defining a class, such as GDExample, it must inherit from a Godot class (like Sprite2D).

#pragma once

// We include the base class we want to inherit from
#include <godot_cpp/classes/sprite2d.hpp>
#include <godot_cpp/core/class_db.hpp>

namespace godot {

class GDExample : public Sprite2D {
    // This macro is mandatory for all GDExtension classes. 
    // It allows Godot to handle type-checking and inheritance internally.
    GDCLASS(GDExample, Sprite2D);

private:
    // Internal variables for our logic
    double time_passed;
    double amplitude;
    double time_emit;

protected:
    // This is where we register our properties, methods, and signals to Godot
    static void _bind_methods();

public:
    GDExample();
    ~GDExample();

    // Standard Godot virtual function for frame-by-frame logic
    void _process(double delta) override;

    // Setters and Getters for the 'amplitude' property
    void set_amplitude(const double p_amplitude);
    double get_amplitude();

    // Example methods for logic and scene interaction
    int sum_two_numbers(int a, float b);
    void test_function();
};

} // namespace godot

Crucially, you must use the GDCLASS(GDExample, Sprite2D) macro to allow Godot to manage the class.

Binding data

You also declare standard node functions like _process or _ready, along with a mandatory static function called _bind_methods. This is where the magic happens: it is in _bind_methods that you tell Godot which functions, properties, and signals are recognized by the editor.

#include "gdexample.h"
#include <godot_cpp/classes/engine.hpp>
#include <godot_cpp/variant/utility_functions.hpp>
#include <godot_cpp/classes/scene_tree.hpp>

using namespace godot;

// _bind_methods is where we register our C++ code with Godot's internal ClassDB.
// If you don't bind a method here, Godot (and GDScript) won't know it exists.
void GDExample::_bind_methods() {

    // 1. REGISTERING METHODS
    // D_METHOD provides the name Godot will use and the names of the parameters.
    ClassDB::bind_method(D_METHOD("get_amplitude"), &GDExample::get_amplitude);
    ClassDB::bind_method(D_METHOD("set_amplitude", "p_amplitude"), &GDExample::set_amplitude);

    // 2. CREATING PROPERTIES (The @export equivalent)
    // This allows you to edit "amplitude" directly in the Godot Inspector.
    // We define the type (FLOAT), the name, and the Hint (a slider from 0 to 100).
    ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "amplitude", PROPERTY_HINT_RANGE, "0,100,0.1"), 
                 "set_amplitude", "get_amplitude");

    // Registering our custom math and utility functions
    ClassDB::bind_method(D_METHOD("test_function"), &GDExample::test_function);
    ClassDB::bind_method(D_METHOD("sum_two_numbers", "number1", "number2"), &GDExample::sum_two_numbers);

    // 3. REGISTERING SIGNALS
    // This allows our C++ node to broadcast events that GDScript can listen to.
    // Here we define a signal "position_changed" that sends the Node itself and its new Vector2.
    ADD_SIGNAL(MethodInfo("position_changed", 
               PropertyInfo(Variant::OBJECT, "node"), 
               PropertyInfo(Variant::VECTOR2, "new_pos")));
}

GDExample::GDExample() {
    // Initialize our variables with default values.
    time_passed = 0.0;
    amplitude = 10.0;
    time_emit = 0.0;
}

GDExample::~GDExample() {
    // Clean up if necessary.
}

void GDExample::_process(double delta) {
    // IMPORTANT: Check if we are inside the editor.
    // If we don't do this, the script will run and move the node while you are designing!
    if (godot::Engine::get_singleton()->is_editor_hint()) return;

    time_passed += delta;

    // A simple trigonometric movement pattern (Swaying motion)
    Vector2 new_position = Vector2(
        amplitude + (amplitude * sin(time_passed * 2.0)),
        amplitude + (amplitude * cos(time_passed * 1.5))
    );

    // We call the native Godot 'set_position' method
    set_position(new_position);

    // 4. EMITTING SIGNALS
    // We use a timer logic to emit our custom signal once every second.
    time_emit += delta;
    if (time_emit > 1.0) {
        emit_signal("position_changed", this, new_position);
        time_emit = 0.0;
    }
}

// GETTERS AND SETTERS
// Required for the Property system to work.
void GDExample::set_amplitude(const double p_amplitude) {
    amplitude = p_amplitude;
}

double GDExample::get_amplitude() {
    return amplitude;
}

// EXAMPLE: Basic data processing
int GDExample::sum_two_numbers(int a, int b) {
    return a + b;
}

// EXAMPLE: Interacting with the Scene Tree
void GDExample::test_function() {
    // Printing to the Godot Output console
    godot::UtilityFunctions::print("Hello from C++!");

    // Accessing another node relative to this one (just like get_node in GDScript)
    godot::Sprite2D* child_node = get_node<godot::Sprite2D>("Sprite2D");
    godot::UtilityFunctions::print("Found child node: ", child_node);

    // Accessing Groups (extremely useful for game logic)
    Array nodes = get_tree()->get_nodes_in_group("MyGroup");
    godot::UtilityFunctions::print("Nodes in group 'MyGroup': ", nodes);
}

3. Registration and Compilation

Next, you need an entry point for your library, typically called register_types. This file contains an initialization function where you use ClassDB to register each class you've created. This step is what makes your C++ class actually appear in the "Add Node" list inside Godot.

register_types.h

/**
 * @file register_types.h
 * @brief Module initialization and registration for the GDExtension plugin.
 */

#pragma once

#include <godot_cpp/core/class_db.hpp>

using namespace godot;

/**
 * @brief Initializes the GDExtension module at the specified initialization level.
 * 
 * This function is called by Godot Engine during plugin initialization. It registers
 * all custom classes, methods, and properties defined in this GDExtension with the
 * Godot ClassDB, making them available in the editor and at runtime.
 * 
 * @param p_level The initialization level at which classes should be registered
 *                (e.g., MODULE_INITIALIZATION_LEVEL_SCENE for scene-related classes).
 */
void initialize_example_module(ModuleInitializationLevel p_level);

/**
 * @brief Uninitializes the GDExtension module at the specified initialization level.
 * 
 * This function is called by Godot Engine during plugin cleanup. It should perform
 * any necessary cleanup operations for the module.
 * 
 * @param p_level The initialization level at which cleanup should occur.
 */
void uninitialize_example_module(ModuleInitializationLevel p_level);

register_types.cpp

#include <gdexample.h>
#include <godot_cpp/core/class_db.hpp>

// This function is called by Godot when the extension is loaded
void initialize_example_module(ModuleInitializationLevel p_level) {
    // We only want to register our classes at a specific 'level' 
    // (the Scene level is where Nodes live).
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
        return;
    }

    // This makes 'GDExample' appear in the "Create New Node" menu
    ClassDB::register_class<GDExample>();
}

// This function is called when the extension is unloaded
void uninitialize_example_module(ModuleInitializationLevel p_level) {
    // Cleanup code goes here if necessary
}
extern "C" {
  // Initialization.
  GDExtensionBool GDE_EXPORT                                                       example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}
}

To compile, you create an SConstruct file at the project root. This file acts as a build script that configures the compilation and links your code with the godot-cpp library. Once you run scons at the root, it generates the final binary—a .dll for Windows or a .so for Linux.

#!/usr/bin/env python
import os
import sys

# We import error printing from SCons methods to keep output clean
from methods import print_error

# --- CONFIGURATION AREA ---
# Change these names to match your specific project
folder_name = "godot-cpp-example"
library_name = "GodotCppExample"
project_dir = "game_project" # This is the folder where your Godot 'project.godot' lives

# Initialize the SCons environment
localEnv = Environment(tools=["default"], PLATFORM="")

# Load custom build options (like compiler flags) if a 'custom.py' exists
customs = ["custom.py"]
customs = [os.path.abspath(path) for path in customs]

opts = Variables(customs, ARGUMENTS)
opts.Update(localEnv)

# Generate a 'help' text for when you run 'scons --help'
Help(opts.GenerateHelpText(localEnv))

env = localEnv.Clone()

# --- SAFETY CHECK ---
# Before we try to compile, we make sure the user didn't forget the submodules.
if not (os.path.isdir("godot-cpp") and os.listdir("godot-cpp")):
    print_error("""The 'godot-cpp' bindings are missing!
You likely forgot to initialize Git submodules. Run this command:

    git submodule update --init --recursive""")
    sys.exit(1)

# --- THE BUILD PROCESS ---

# 1. We call the SConstruct file inside godot-cpp to prepare the base bindings
env = SConscript("godot-cpp/SConstruct", {"env": env, "customs": customs})

# 2. Tell SCons where our source code is
env.Append(CPPPATH=["src/"])
sources = Glob("src/*.cpp") # This automatically finds all .cpp files in the src folder

# 3. Handle Documentation (Godot 4.3+)
# If you are making an editor plugin, this compiles your XML documentation into the binary
if env["target"] in ["editor", "template_debug"]:
    try:
        doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
        sources.append(doc_data)
    except AttributeError:
        print("Skipping class reference: targeting a pre-4.3 Godot baseline.")

# 4. Handle Naming Conventions
# Different OS's have different naming rules (e.g., .dll vs .so). 
# This logic ensures the filename is formatted correctly for Godot.
suffix = env['suffix'].replace(".dev", "").replace(".universal", "")
lib_filename = "{}{}{}{}".format(env.subst('$SHLIBPREFIX'), library_name, suffix, env.subst('$SHLIBSUFFIX'))

# 5. The Compilation Step
# This actually triggers the compiler to create the Shared Library (binary)
library = env.SharedLibrary(
    "bin/{}/{}".format(env['platform'], lib_filename),
    source=sources,
)

# --- THE INSTALLATION STEP ---
# Instead of manually copying files, we tell SCons to automatically 'Install' 
# the new binary directly into our Godot project's addons folder.
# This makes the development loop much faster!
copy = env.Install("{}/addons/{}/bin/{}/".format(project_dir, folder_name, env["platform"]), library)

# Set the library and the copy operation as the default action when 'scons' is run
default_args = [library, copy]
Default(*default_args)

3. The .gdextension File

The final step is telling Godot how to load your newly compiled binary. You do this by creating a simple text file with the .gdextension extension (e.g., my_project.gdextension).

Before we look at the file content, it is important to understand where this file sits. Typically, you want a clean separation between your C++ workspace and your Godot project files:

my_gdextension_project/
├── godot-cpp/          # The engine bindings (Git submodule)
├── src/                # Your C++ source code (.cpp and .h files)
├── SConstruct          # The build script that ties it all together
└── project/            # Your actual Godot Project folder
    ├── project.godot
    ├── main.tscn
    └── bin/            # Where your compiled binaries and .gdextension live
        ├── my_project.gdextension
        ├── libgdexample.windows.debug.x86_64.dll
        └── libgdexample.windows.release.x86_64.dll

Observation: The deliberate omission of the "addons" folder (unlike in the Scons file) in this example, serves a purpose: to emphasize that Godot does not mandate placing the .gdextension file within the "addons" directory, which is the expectation for GDScript plugins.

This file acts as a manifest. It contains a [configuration] section pointing to your C++ entry point and a [libraries] section that maps specific platforms and build targets to the correct file paths.

Understanding Build Targets

It is important to understand that you will typically deal with two types of builds:

Debug Builds: These are used during development and inside the Godot Editor. They include extra symbols that make debugging easier and allow the engine to give you descriptive error messages if the C++ code crashes.
Release Builds: These are optimized for performance. They are smaller and faster because they strip away the debugging "clutter," and they are what you will actually distribute to your players.

Here is how you would set up your .gdextension file to handle both:

[configuration]
# This must match the entry function name defined in your registration file (register_types.cpp)
entry_symbol = "example_library_init"
compatibility_minimum = "4.6"
reloadable=true # add this to integrate hot-reload inside the editor!

[libraries]
# We map specific operating systems to the resulting compiled files.
# 'res://' points to the root of your Godot project folder.
# but you can also use relative paths.
windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so"
macos.debug.x86_64 = "res://bin/libgdexample.macos.template_debug.x86_64.dylib"

Why separate them?

By defining both debug and release paths, Godot is smart enough to swap the libraries automatically. When you are working in the editor, it uses the debug version. When you click Export Project and uncheck "Export with Debug," Godot will automatically bundle the release version of your C++ code, ensuring your players get the best possible performance.

But most importantly, when Godot sees the .gdextension file, it loads the correct binary for your platform, and your C++ classes are dynamically linked. They will appear in the editor ready to be used like any native node.

Observation: If your classes don't appear immediatly in the editor, reload the current project, and make sure during development to activate "hot reload" for a better developer experience.

Conclusion

You now understand the fundamental flow of GDExtension. This is only the beginning of the journey. While the initial setup is the steepest hurdle, the performance rewards and architectural flexibility are significant.

In a future deep-dive, we will explore the more complex challenges of GDExtension, including available macros, documenting classes for the editor, and—most importantly—a performance comparison to see exactly how much speed is gained when migrating a GDScript plugin over to C++.

Link to the repository:
https://github.com/GuaraProductions/Godot-GDExtension-minimalist-example

Resurrecting a 25-Year-Old Horror Game: How I Ported 'Fiend' to Modern Systems

Gustavo Lopes — Tue, 13 Jan 2026 13:20:36 +0000

1 - Introduction

Game restoration is more than just a technical challenge; it is an essential act of preservation. Video games are a unique blend of art and complex engineering, but unlike movies or books, they can become stuck to the configurations they were born on. Just like software, a video game project risks becoming "abandonware" if its fundamental components—such as supporting libraries—become obsolete and are not adequately maintained.

As a passionate computer scientist and an avid gamer, I always dreamed of the chance to dive into and help preserve the source code of older games. That opportunity finally arrived when I came across the source code for the survival horror title, Fiend, originally released in 2001. This game holds a special place for me. Although not a classic or the best of its time, it was one of the first horror games I ever played.

My goal was ambitious: to take source code written for Windows 98/XP and make it run natively on modern 64-bit Linux and Windows 10/11.

This wasn't just a simple "recompile." It required modernizing a lot of components of the codebase. I replaced the outdated audio library, fixed memory corruption bugs that had been sleeping for 20 years, and built a CI/CD pipeline using GitHub Workflows, and more. This ensures that every time I change the code, the game is automatically built and tested, guaranteeing it won't break again in the future.

This post documents the game's revitalization, the technical challenges, and aims to highlight this influential, lost relic that is, in a way, very influential to a major video game company's history.

But first, let's start with some context.

2 - What is "Fiend"?

To understand the restoration, you first have to understand the subject. Fiend is a top-down survival horror game released in 2001 by GripDesign—the alias of Thomas Grip, who would go on to co-found Frictional Games.

If you have played Amnesia: The Dark Descent or SOMA, you can see the DNA of those games right here in Fiend. It features a heavy Lovecraftian atmosphere, limited resources, and a combination of psychological horror and combat.

The story is as follows: you play as Nick Cane, a researcher sent to the small mining town of Lauder. What starts as a routine mineral survey quickly spirals into a nightmare as you uncover an ancient evil buried beneath the town.

If you like to see a full playthrough of the game here is a link for it.

Also, for more information on some of Frictional Games' lesser-known projects, such as Fiend, visit this page, on the official website.

2.1 - The Tech Stack (2001 Era):

The game was a technical marvel for a one-man team in 2001, featuring real-time lighting and particle effects. It was built using:

Language: C (The grandfather of modern systems programming).

Graphics: Allegro 3.9.3 (A famous game programming library from the 90s/2000s).

Audio: FMOD (A powerful sound engine still used today, though the 2001 version is ancient history).

But most impressive of all, alongside the game there is also a Map Editor. The restoration project also includes the restoration of the Map Editor as well.

This isn't just a tool for drawing walls; it is a complete development environment for the game. It allows you to design map layouts, define collision data, place items, and add complex logic like triggers and events. By fixing the editor, I ensured that users can not only play Fiend but also study how it was put together—or even create their own mods and stories (if they so desire).

With the project’s current state being explained, it becomes clear as day as to why the game is “unplayable” in its current state. This boils down to three main factors: the dependence on the closed-source FMOD library, the choice of programming language, and the use of an obsolete game programming framework.

3 - Getting it to boot

And so, let’s get started into the process of revitalizing this game, with the first step being, getting it to run. Surprisingly, the project featured a functional CMake setup. It was designed to automatically detect essential libraries on the user's system, particularly Allegro and FMOD binaries, allowing anyone to clone and build the repository with a single command. Nevertheless, crucial architectural decisions for the project still needed to be made.

The game was originally built on Allegro 3.9.3, a library from the late 90s. While the modern standard is Allegro 5, upgrading to it was impossible without rewriting the entire game. Allegro 5 fundamentally changes how input works, moving from a "polling" system (checking if a key is down right now) to an "event queue" system (waiting for the OS to report a key press). To bridge this gap, I chose Allegro 4.4.3. This version is modern enough to compile on 2025 Linux and Windows, but retains the legacy architecture the code expects, requiring only minor updates to deprecated math functions and updating the CMake to link to the "math.h" header.

With the graphics sorted, I hit a wall with the audio. The game relied on an ancient version of FMOD that is incompatible with modern Linux. Rather than getting stuck in "dependency hell," I used a standard development tactic called feature flagging. By wrapping all audio code in pre-processor directives (#ifdef USE_FMOD), I made the sound system optional during the first stages of development.

// Example of how I silenced the audio engine
void PlaySound(int id, int vol, int pan, int freq) {
    #ifdef USE_FMOD
        // Original code: only compiles if FMOD is found
        FSOUND_PlaySound(channel, sound_data[id].sample);
    #else
        // If FMOD is missing, do nothing (game runs silently)
        return; 
    #endif
}

This allowed the compiler to ignore the missing library and build a silent—but functional—version of the game so I could focus on stability.

After this point, the game was actually initializing, but there were still a lot of issues that made it crash on startup. One of them is that I had to hard-code the system locale to "C" (standard English). The game crashed on systems using languages like Portuguese or German because the fscanf function tries to use commas for decimals instead of dots.

// Storing the user's original locale
char *old_locale = setlocale(LC_NUMERIC, NULL);

// Forcing the game to use "." for decimals (English Standard)
setlocale(LC_NUMERIC, "C");

// ... Parsing code runs here ...

// Restoring the user's locale
setlocale(LC_NUMERIC, old_locale);

This fix was important, because a lot of data was being read from .txt files with important information, like for example, the data for the weapons of the game.

After fixing that (and some logic issues inside the game), I faced the most complex challenge yet: Binary Compatibility. The game saved maps by dumping raw memory structures to disk. In 2001, on 32-bit systems, memory pointers were 4 bytes. On my 64-bit Linux machine, they are 8 bytes.

This size mismatch meant the game was reading garbage data. To fix this, I wrote a custom loader that reads the files field-by-field, manually discarding the old 32-bit pointers to realign the data.

// The Fix: Manual Field Reading & Skipping 32-bit Pointers
fread(&temp_map->num_of_lights, sizeof(int), 1, f);

// On 32-bit Windows, the next 4 bytes were a pointer.
// On 64-bit Linux, we don't need that old address, so we skip it.
fseek(f, 4, SEEK_CUR); // Skip 32-bit pointer

With these fixes, the game was finally playable—albeit silent.

4 - Fixing memory issues

After the initial port, I felt confident to work on the audio. The game compiled, the graphics rendered, and I could walk around the first map. But when I switched the compiler from "Debug" mode to "Release" (turning on optimizations like -O2), the game immediately crashed.

This is a classic problem in C programming. Debug builds often add "padding" around variables that can accidentally hide memory errors. Release builds remove that padding, causing those sleeping bugs—often called "Heisenbugs"—to wake up and crash the application.

To hunt them down, I needed a memory debugger.

4.1 - The Tool Selection: Valgrind vs. AddressSanitizer

My initial strategy for memory checking involved Valgrind, a tool I was already familiar with. It works by executing the program within a virtual environment, thoroughly inspecting every single instruction. While remarkably comprehensive, this approach comes with a severe performance hit, slowing execution by a factor of 20 to 50.

The issue with Valgrind in this context was immediate: its drastic slowdown made it unusable for a real-time game. The resulting frame rate was so poor that I couldn't even navigate the menus to access the very bugs I was trying to find.

Consequently, I switched to AddressSanitizer (ASAN). Rather than virtualizing the CPU, ASAN integrates error-checking code directly into the program during the compilation process. This makes it significantly more efficient, reducing the slowdown to only about 2x. This much faster performance finally allowed me to play the game at a manageable frame rate while ASAN monitored for errors in the background.

The moment I launched the game with ASAN active, the console instantly filled with red text. The 2001 original code was quickly exposed as being full of "ticking time bombs."

4.2 - "Off-by-One" Error and Unitialized Memory

The most severe bug—the one causing the crashes—was hidden in the Line-of-Sight (LOS) system. The game uses an array to track light sources, defined with a size of 18. However, the loop iterating through this array was written to go from 0 to 18.

In C, an array of size 18 has indices 0 through 17. Accessing index 18 means you are reading/writing memory that doesn't belong to that array.

// The Bug: Iterating too far
// 'l' goes up to 18, but array size is 18 (indices 0-17)
if(l < 18) { 
    light_source[l] = ...; // Writes to invalid memory at index 18!
}

// The Fix: Stop at 17
if(l < 17) {
    light_source[l] = ...; 
}

ASAN flagged this as a "Global Buffer Overflow". This single byte of corruption was overwriting adjacent memory, destabilizing the entire engine during map transitions.

A similar bug caused loops to iterate using MAX_OBJECT_NUM instead of the actual number of objects (map->num_of_objects), leading to uninitialized memory access.

// BEFORE (heap buffer overflow):
for (i = 0; i < MAX_OBJECT_NUM<; i++) {
    // Accesses beyond allocated memory!
}

// AFTER (correct bounds):
for (i = 0; i < map->num_of_objects; i++) {
    // Uses dynamic bounds to stay within the allocated heap space
}

4.3 The Dangers of sprintf

The original code heavily relied on sprintf to generate save filenames. This function is dangerous because it doesn't check if the text fits into the destination buffer. ASAN detected multiple stack-buffer overflows where the game tried to write long map names into small variables.

I replaced these unsafe calls with strncpy, which forces a limit on how many characters can be copied, ensuring we never write past the end of the buffer.

// BEFORE (unsafe)
sprintf(temp.map_name, "%s", map->name);

// AFTER (safe)
strncpy(temp.map_name, map->name, sizeof(temp.map_name)-1);
temp.map_name[sizeof(temp.map_name) - 1] = "\0";

4.4 Memory Leaks and Double-Free

Due to the significant memory consumption of storing many in-game images as bitmaps, which would make simultaneous rendering challenging, the game employs an efficient strategy: Allegro's Run-Length Encoding (RLE) Sprites. This method is particularly effective for simpler images that feature large, uniform areas of color. By replacing repeated pixel data, RLE reduces both the size of the image files and the time required to draw them, making the rendering process much faster.

The core issue is twofold: while the game correctly converts the bitmap to RLE and cleans it up, the RLE Sprites are never cleaned up, not even during transitions.

void release_objects(void) {
    for (i = 0; i < num_of_objects; i++) {
        for (j = 0; j < object_info[i].num_of_frames; j++) {

            if (!object_info[i].angles || object_info[i].door) {
                // Single bitmap - free it
                if (object_info[i].pic[j][0].data) {
                    destroy_bitmap(object_info[i].pic[j][0].data);
                }
            } 
            else if (object_info[i].additive) {
                // Additive objects - free angle bitmaps
                for (k = 0; k < num_angles; k++) {
                    if (object_info[i].pic[j][k].data) {
                        destroy_bitmap(object_info[i].pic[j][k].data);
                    }
                }
            } 
            else {
                // Normal objects - free RLE sprites (MEMORY LEAK FIX)
                for (k = 0; k < num_angles; k++) {
                    if (object_info[i].rle_pic[j][k]) {
                        destroy_rle_sprite(object_info[i].rle_pic[j][k]);
                    }
                }
            }

        }
    }
}

Second, in specific scenarios, flawed boolean logic leads to the same memory data being freed multiple times, which results in a Double-Free Error.

// BEFORE (double-free):
// Loading logic:
else if(object_info[i].additive) {
    // Bitmaps NOT freed
    else {
        // Normal objects (includes trans without additive)
        // Bitmaps FREED here
    }
}

// Cleanup logic (MISMATCH):
else if(object_info[i].additive || object_info[i].trans) {
    // Tries to free bitmaps AGAIN!
}

// AFTER (correct):
// Cleanup now matches loading:
else if(object_info[i].additive) {
    // Only additive objects, matches loading
}

4.5 Results

There were some other errors, but it would take a lot more context to explain them, but in short, by the end of this phase, I had fixed:

3 Buffer Overflows
1 Heap Corruption (The LOS bug)
2 Memory Leaks
1 Double-Free Error

With these fixes, the game was now stable in Release mode, and running without a single report from AddressSanitizer.

5 - Replacing FMOD

By this point, the game was playable and stable, but it was completely silent. The final challenge was to restore the atmosphere that makes a horror game scary: the sound.

The game originally used FMOD, but trying to link a 2001 audio library to a 2025 operating system was a dead end. I needed a replacement that was modern, open-source, and easy to integrate. I chose miniaudio.

5.1 - The Choice: Why Miniaudio?

Unlike FMOD, miniaudio simplifies the development process as it only requires a single file (miniaudio.h) to be dropped into the project, eliminating the need for complex installation. Since the game's audio requirements were minimal—solely focused on playback, looping, and volume control—miniaudio was the perfect fit. The library also offers native support for essential features like mixing, volume management, and resource handling across Linux, Windows, and other platforms.

5.2 - The Wrapper: Faking the Old System

With the API issue resolved, the central challenge shifted to integrating the new library without rewriting the existing sound-playing code. To achieve this, I introduced a Wrapper API (audio.c). This wrapper acts as an intermediary, translating calls from the existing game code, which uses generic functions like PlaySound(), into the necessary miniaudio instructions. This strategic approach allowed for a fundamental change in the underlying audio engine while successfully preserving the original game logic.

5.3 - The Crisis: The ".it" vs ".wav" Corruption

The original music assets were stored in the legacy Impulse Tracker (.it) format, dating back to the 1990s. Jeffrey Lim ('Pulse') created Impulse Tracker in 1995 as the spiritual successor to Scream Tracker 3. It quickly gained popularity within the demoscene and independent game development community due to its advanced features, including full 32-channel support, new note effects, and superior sample handling. Since miniaudio lacks support for .it files, all these assets were converted to the standard .wav format.

The change in file format, however, led to a significant issue. The map files, which contain the binary data defining the game levels, had specific references to files ending in the ".it" extension. Initially, I attempted a simple find-and-replace operation within the map files, changing text like "music.it" to "music.wav."

This action caused widespread corruption. Because the ".wav" extension (4 characters) is one character longer than ".it" (3 characters), the replacement shifted every subsequent byte in the binary file by one position. In a densely packed binary file structure, even a single-byte shift turns valid data—such as door triggers—into unusable garbage.

5.4 - The Solution: The Map Editor Tool

I realized I couldn't edit the raw files safely. I had to do it logically. Since I had already restored the Map Editor in Phase 1, I used it to build a migration tool.

I wrote a script inside the editor to Load a map (reading the data into correct memory structures).
The script then finds every string ending in .it and safely replaces it with .wav in memory.
Finally, it Saves the map back to disk.

Because the editor knows how to write the file structure correctly, it handled the size difference automatically, preventing the "bit shift" corruption. With this final fix, the game was complete: stable, modernized, and fully audible.

6 - CI/CD - Making the game Cross-Platform

With the game stable and audible, I wanted to ensure it stayed that way. I set up a CI/CD pipeline using GitHub Actions. The goal was simple: every time I push code, a cloud server should automatically compile the game for both Linux and Windows, bundle the assets, and publish a release. Also I wanted to bundle with the game all the required libraries, so that everything the game needed to run was packaged with the final product.

The Linux build was straightforward—just a standard ubuntu-latest container installing necessary packages via apt and compiling the allegro library with only necessary components. The Windows build, however, turned into a nightmare.

6.1 - The Windows Problem

I initially tried to compile the Windows version using modern tools (latest GCC/MinGW). It failed miserably. The game would crash every single time on the title screen.

I realized that Allegro 4 and the 2001 code were tightly coupled to the specific behavior of older compilers and APIs. Achieving the desired outcome required essential changes to the entire build process.

First, I manually installed an older version, MinGW 6.3.0, which I sourced from SourceForge, instead of installing the compiler through the use of the MSYS2’s package manager.

The second major hurdle was the incompatibility of modern Windows SDKs with the specific DirectDraw interfaces used by Fiend. This necessitated tracking down the original DirectX 8 SDK, which was eventually located in the archives of the official Allegro website.

Finally, a custom step was incorporated into the pipeline script. This step forcibly extracts the archaic SDK and injects its necessary header and library files directly into the path recognized by the MinGW compiler.

# A snippet of the "Digital Archaeology" in build.yml
- name: Injecting DX8 into MinGW...
  run: |
    Copy-Item -Path "C:\DX8\include\*" -Destination "C:\mingw32\include" -Recurse -Force
    Copy-Item -Path "C:\DX8\lib\*" -Destination "C:\mingw32\lib" -Recurse -Force

6.2 - The "Text Test" Debugging

I only figured out the problem's root cause after I put together a small, focused test program just for checking out how text rendering worked in Allegro. When compiled with modern GCC, it failed. When compiled with the legacy stack, it worked. This confirmed that the issue wasn't my code—it was the toolchain.

#include <allegro.h>
#include <stdio.h>

int main(void)
{
    printf("Starting Allegro font test\n");
    allegro_message("[LOG] Starting Allegro font test\n");
    allegro_init();
    printf("After init\n");
    install_keyboard();
    set_color_depth(32);

    allegro_message("[LOG] Attempting to set graphics mode...\n");
    if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
        allegro_message("[ERROR] Failed to set graphics mode!\n%s", allegro_error);
        return 1;
    }
    allegro_message("[LOG] Graphics mode set successfully.\n");

    allegro_message("[LOG] Using Allegro's built-in font.\n");
    clear_to_color(screen, makecol(0,0,0));
    allegro_message("[LOG] Screen cleared. Attempting to render text...\n");
    textout_centre_ex(screen, font, "Text test in Windows Allegro", 320, 240, makecol(255,255,255), -1);
    allegro_message("[LOG] Text rendering attempted.\n");

    allegro_message("[LOG] Waiting for key press...\n");
    readkey();

    allegro_message("[LOG] Exiting.\n");
    allegro_exit();
    return 0;
}
END_OF_MAIN()

Now, the repository works like a factory.

The repository functions as a build factory. For Linux, it performs a native build using bundled dependencies. Conversely, for Windows, it initiates a legacy environment to build the executable and bundle essential DLLs (such as libgcc and libstdc++).

The pipeline handles the automatic zipping and uploading of these builds as a release. This makes a fully playable, modern-compatible version of Fiend readily available for download, allowing anyone to use it without the need for compilation.

7 - Conclusion

So this conclude the process of how I restored the source code of the game “Fiend”. This was a highly enjoyable project that successfully refreshed my memory on various low-level concepts crucial for many programmers. Although I am sure that I may have missed some other interesting facts, I believe I grasped the most interesting points of the hole process.

To end this post I would like to answer a few questions that you may have about the project

How long did it took you to finish this project?

The project's completion time was approximately 50 days, or about a month and a half. However, as I took some breaks throughout the process, the precise number of working days is unknown.

Where did you get the original source code?

The original, unpatched code, was published by someone on Github, and can be found here. Please note this is the broken version and does not contain my necessary fixes.

Where I can download the game?

The modified source code and game binaries cannot be released at this time because the original 2001 license only allows for the game's distribution "in its original form."

I did find a repository claiming to allow "redistribution and use in source and binary forms, with or without modifications." However, the validity of this claim is uncertain, as it is not an official Frictional Games repository, nor does the individual who posted it appear to be affiliated with Frictional Games.

I have reached out to Thomas Grip (Frictional Games) to request permission to share this modernized port with the world. Until then, this post serves as a record of my journey into making this port.

Fingers crossed that we can bring Fiend back to the public soon! I will share any new project updates in a subsequent post here.

But that's about it, thank you for reading, and have a nice day!