Creating a Modding API for Spellforce 1
In this post I'll be documenting my time working on the Spellforce Spell Framework, it's like a smaller version of Forge for Minecraft, a framework that allows mod developers to access functionality that would previously require Code Injection.
Introduction
SpellForce: The Order of Dawn," released in 2003, integrates real-time strategy (RTS) with role-playing game (RPG) elements. Players assume the role of a Rune Warrior in the world of Eo, tasked with restoring balance amidst cosmic conflict. The game offers a blend of RPG mechanics like character progression and skill acquisition with RTS elements such as base building and army management.
However, the game's modding support has been limited, hindering the community's ability to expand and enhance the game. Our objective is to create a framework tailored for the SpellForce Platinum Edition Public Beta version available on Steam.
To achieve this, a thorough understanding of the Spellforce codebase is necessary. We have chosen to use Ghidra, an open-source tool developed by the NSA for reverse engineering.
Given the complexity of the task, we will initially focus on enabling fully custom spells.
This project involves collaboration with UnSchtalch and Shovel_Knight, who are assisting in the development of the framework. UnSchtalch invited me to join the project for help with the frameworks structure and design.
Why do we need Ghidra
Ghidra proves indispensable in our project due to the significant portion of the game's logic being hard coded, approximately 75%. It allows us to identify memory regions crucial for our purposes, enabling us to analyze and intervene in the execution flow.
The Starting Point
Embarking on a new project can often feel daunting, but we approached it with a clear focus: our primary objective was to establish the framework for loading mods. Defining what constitutes a mod for our purposes and determining its structure and language were among our initial considerations. This naturally led us to contemplate how we could effectively implement mod loading into our system.
As we're using C and C++ for the modding framework's development, it followed that mods would be authored in these languages. Recognizing that SpellForce is exclusively available for the Windows OS, we identified the LoadLibrary function as a key tool. This function grants the capability to dynamically load a DLL file, an essential feature for integrating mods seamlessly into the game.
With these fundamental decisions made, we gained a clear understanding of what defines a mod within our framework and outlined the basic steps involved in creating one.
Identification and Annotation
An important part of using ghidra to it's full effect is to take the time to identify and annotate parts of the codebase, as an example, below we have two snippets of code, one with annotation and the other without.
Annotated
Not Annotated
Something crucial to note is that even though the first example hasn't been fully annotated, the annotations and identification that has already been done and some of the clues within the code itself help us Identify the purpose of that particular function.
Based on the Annotated function EraseFigure, being identified to belong to the same class, and the hard coded debug string, it can be intuited that the unknown Function has some baring toward removing figures from clans. Figures in this context are NPC Units.
And furthermore as both functions belong to AutoClass17, it may be appropriate to rename AutoClass17 to something more appropriate, However something crucial to this is understanding the context in which the function are called, as I'm not certain how the class is used, hence I'd need to investigate the use case of these functions before annotating them.
Regardless this is but a small part of the process of identifying and annotating SpellForce.
An Example of SFSF in use.
Something that has not been possible in Spellforce modding was the creation of Custom Effects that link to a Custom Spell Type, As an example of something completely new and not possible without injecting code is an Area of Effect variant of the spell Life Tap, which damages an enemy and heals the caster.
In the below example @UnSchtalch my fellow developer created such a spell, using the API we provided with the Spellforce Spell Framework, this ensures that a developer no longer needs to inject code to create new spell effects and more.
The Current State of SFSF
As can be intuited, the Spellforce Spell Framework is Functional, but by no means is it complete; The framework while able to fulfill it's purpose still has some ways to go, My team and I need to export more API functions to allow for further spell customization, and doing so means understanding the codebase further using Ghidra. The current Goal of a release version of SFSF would be the ability to completely recreate any vanilla spell available in the game, and in doing so we give mod developers the tools needed to create never before seen spells.
For those interested in SFSF, you can access it on github via the link below.
