Skip to content

sfsf.h

Jump to bottom
muddykat-tech edited this page Aug 15, 2024 · 9 revisions

The following documentation is out of date and applies to version 3.1.0-alpha

Overview

The sfsf.h header file defines the interface for the Spellforce Spell Framework (SFSF). This framework provides developers with a set of functions and structures to interact with the Spellforce game engine and create custom spell types and spell logic.

Key Components:

  1. initializeModule: This function initializes the SFSF module and prepares it for use.
  2. registerSpellTypeHandler: Allows developers to register custom handlers for spell types.
  3. registerEffectHandler: Enables registration of custom handlers for spell effects.
  4. apiSpellFunctions: API functions related core spell functionalities
  5. apiToolboxFunctions: Toolbox functions for dealing damage, setting and checking flags and more.
  6. apiFigureFunctions: Functions for managing and manipulating game figures statistics and behavior.
  7. logWarning: Function for logging warning messages.
  8. logError: Function for logging error messages.

Purpose:

The sfsf.h class serves as the primary interface for developers to extend and customize the spell functionality within the Spellforce game. By leveraging the functions and structures provided by this class, developers can create new spell types, define custom spell behaviors, and integrate them seamlessly into the game environment.

Usage:

Developers can include the sfsf.h header file in their projects to gain access to the functionality provided by the Spellforce Spell Framework. By utilizing the exposed functions and structures, developers can implement complex spell logic.

initializeModule

The initializeModule function initializes the Spellforce Spell Framework module and prepares it for use.

Parameters

  • framework: A pointer to an instance of the SpellforceSpellFramework structure, which contains various function pointers and APIs required for interacting with the Spellforce game engine.

Example Usage

#include "sfsf.h"

SpellforceSpellFramework *sfsf;

extern "C" __declspec(dllexport) void InitModule(SpellforceSpellFramework* framework) {
    sfsf = framework;
}

Description

The initializeModule function initializes the Spellforce Spell Framework module and prepares it for use. It sets up global variables and function pointers required for interacting with the Spellforce game engine.

This function is called just after the Spellforce Spell Framework detects your mod file, and is required for the initialization of a mod.

registerSpellTypeHandler

The registerSpellTypeHandler function is used to register custom handlers for specific spell types within the Spellforce game engine. This function allows developers to define custom logic for handling the casting and execution of spells.

Parameters

  • spell_index: The ID of the spell type for which the handler is being registered. This parameter corresponds to the spell index within the active_spell_list array.
  • handler: A pointer to the custom handler function that will be invoked when casting spells of the specified type.

Example Usage

// Using a SpellforceSpellFramework pointer you can access this function.
// Example id used is for the spell icestrike (or iceburst in game).
sfsf->registerSpellTypeHandler(0xe, &custom_spelltype_handler);

Example Handler

In order to create a VALID handler you need to have at least the following

void __thiscall custom_spelltype_handler(SF_CGdSpell * _this, uint16_t spell_index) {
  //Effect ID is the spell_job (links to custom_spelleffect_handler)
  _this->active_spell_list[spell_index].spell_job = 0xf2; 

  // Required for the spell to be initialized as active
  sfsf->apiSpellFunctions->initializeSpellData(_this, spell_index, SPELL_TICK_COUNT);
}

registerEffectHandler

The registerEffectHandler function enables registration of custom handlers for spell effects within the Spellforce game engine.

Parameters

  • effect_index: The ID of the spell effect for which the handler is being registered. This parameter corresponds to the job_id of a spell
  • handler: A pointer to the custom handler function that will be invoked when applying the specified spell effect.

Example Usage

#include  "../api/sf_data_utilities.h"
#include  "../api/sfsf.h"

extern  "C"  __declspec(dllexport) void  InitModule(SpellforceSpellFramework* framework) {
  // The job_id or effect_index used is a new id that is not used in the vanilla game
  // this id should be the same as the spell_job id if you want this to be assigned to that spelltype.
  sfsf->registerEffectHandler(0xf2, &custom_spelleffect_handler);
}

Example Handler

void  __thiscall  custom_spelleffect_handler(SF_CGdSpell  *  _this, uint16_t  spell_index) {
  // Required for the handler to know that it's active, without this it will call the function on loop.
  sfsf->apiSpellFunctions->addToXDataList(_this->SF_CGdXDataList, spell_index, SPELL_TICK_COUNT, 1);
  sfsf-apiSpellFunctions->setEffectDone(_this, spell_index, 0);
}

apiSpellFunctions

The apiSpellFunctions section provides API functions related to core spell functionalities, required for initializing spell data and more.

The Example usages here will eventually be moved into their own page, while the deprecated functions will eventually be moved into a separate api.

Functions

 - initializeSpellData(SF_CGdSpell* spell, uint16_t spell_id, SpellDataKey key);
 - setXData(SF_CGdSpell *, uint16_t, uint8_t, uint32_t);
 - setEffectDone(SF_CGdSpell* spell, uint16_t spell_id, uint16_t unk);
 - /*deprecated*/ addToXDataList(SF_CGdXDataList* list, uint16_t spell_id, SpellDataKey key, uint32_t value)
 - /*deprecated*/ getChanceToResistSpell(void* unk, uint16_t source, uint16_t target, SF_SpellEffectInfo effect_info);
 - /*deprecated*/ getRandom(AutoClass14 *_this, uint16_t max);

Example Usage

#include "sf_data_utilities.h"
#include "sfsf.h"

void  __thiscall  custom_spelltype_handler(SF_CGdSpell  *  _this, uint16_t  spell_index) {
  // Example usage inside a spelltype handler
  // initializeSpellData should not be used outside of a spelltype handler.
  sfsf->apiSpellFunctions->initializeSpellData(_this, spell_index, SPELL_TICK_COUNT);
  
  // An alternative to this function is to use setXData
  // However the vanilla game only ever set's the data to '0'
  // Hence we wrapped setXData into initializeSpellData.
  sfsf->apiSpellFunctions->setXData(_this, spell_index, SPELL_TICK_COUNT, 0);
}
#include "sf_data_utilities.h"
#include "sfsf.h"

void  __thiscall  custom_spelleffect_handler(SF_CGdSpell  *  _this, uint16_t  spell_index) {
  // This function is required for any spell data you initialized inside of the spelltype handler.
  sfsf->apiSpellFunctions->addToXDataList(_this->SF_CGdXDataList, spell_index, SPELL_TICK_COUNT, 1);

  // This function will check the chance the target has to resist a spell
  // It requires the source and target index and some effect info
  // These structures are from the sf_data_utilities.h file
  SF_GdSpell *spell = &_this->active_spell_list[spell_index];
  uint16_t t_index = spell->target.entity_index;
  uint16_t s_index = spell->source.entity_index;
  
  SF_SpellEffectInfo effect_info;
  effect_info.spell_id = spell->spell_id;
  effect_info.job_id = spell->spell_job;
  
  unit32_t c sfsf->apiSpellFunctions->getChanceToResistSpell(_this->unkn2, s_index, t_index, effect_info);
  
  // the getRandom function will return a valud between 1 and the max value, in this case '100'
  uint16_t random_roll = sfsf->apiSpellFunctions->getRandom(_this->OpaqueClass, 100);
  
  // Required for the effect to be complete and also allow the for spell to be reapplied to the target.
  sfsf->apiSpellFunctions->setEffectDone(_this, spell_index, 0);
}

apiToolboxFunctions

The apiToolboxFunctions section provides access to specific functions for manipulating figures, this api may be expanded to include toolbox functions for objects, or it may be collapsed into the figure functions api.

Functions

 - dealDamage(SF_CGdFigureToolBox *toolbox, uint16_t source, uint16_t target, uint32_t damage, uint32_t is_spell_damage, uint32_t p5, uint32_t p6);

Example Usage

#include "sf_data_utilities.h"
#include "sfsf.h"

void  __thiscall  custom_spelleffect_handler(SF_CGdSpell  *  _this, uint16_t  spell_index) {
  // Deals Damage to the target
  sfsf->apiToolboxFunctions->dealDamage(_this->SF_CGdFigureToolBox, s_index, t_index, damage, 1, 0, 0);
}

apiFigureFunctions

The apiFigureFunctions section provides functions for managing and manipulating game figures' statistics and behavior.

Functions

 - isAlive(SF_CGdFigure* figure, uint16_t target);
 - setWalkSpeed(SF_CGdFigure* figure, uint16_t target, uint16_t value);
 - /*untested*/ addAction(SF_CGdFigure* figure, uint16_t target, void* maybe_action);  
 - /*untested*/ addBonusMultToStatistic(SF_CGdFigure* figure, StatisticDataKey key, uint16_t target, uint8_t value); 
 - /*deprecated*/ addBonusMult(FigureStatistic statistic, uint8_t value);

Example Usage

#include "sf_data_utilities.h"
#include "sfsf.h"

void  __thiscall  custom_spelleffect_handler(SF_CGdSpell  *  _this, uint16_t  spell_index) {
  // Check if Target is Alive!
  SF_GdSpell *spell = &_this->active_spell_list[spell_index];
  uint16_t target_index = spell->target.entity_index;
  uint16_t isAlive = sfsf->apiFigureFunctions->isAlive(_this->SF_CGdFigure, target_index);
  
  // Set Walk Speed of Target to 200%
  sfsf->apiFigureFunctions->setWalkSpeed(_this->SF_CGdFigure, target_index, 200);
  sfsf->apiFigureFunctions->addBonusMultToStatistic(_this->SF_CGdFigure, WISDOM, source_index, 2);
}

logWarning

The logWarning function is used for logging warning messages within the Spellforce game engine.

Function Signature

void logWarning(const char* message)

Example Usage

logWarning("Message to print");

Example output

[WARNING] Message to print

logError

The logError function is used for logging error messages, it also gets the last error number

Function Signature

void logError(const char* message)

Example Usage

logError("Message to print");

Example output

[ERROR] Message to print [Last Error: 126]

Clone this wiki locally