-
Notifications
You must be signed in to change notification settings - Fork 1
SRD: Toolbox Functions
This page provides an overview of Spellforce Framework functions which are used to manipulate figures (units) in a conventional way, meaningly, adhering to the same logic which the gameplay follows.
These functions are taken from the sf_toolbox_functions.h header file. Please, note that you don't need to include that header in your project. It is automatically included as part of the sfsf.h general interface.
This page is up-to date for version of the Spellforce Framework 1.02-beta.
Below listed all functions you can find in sf_toolbox_functions.h. The toolbox functions can be accessed using toolboxAPI-> prefix, provided this group was previously initialized. In order to initialize the toolbox functions you should,
-
Declare a pointer for the toolbox functions within global variables of your project. This is done as follows:
ToolboxFunctions *toolboxAPI; -
Assign this pointer the address of Toolbox Functions within the main structure of the Spellforce Framework. Usually this is done as part of
InitModulefunction after the framework was initialized. This is done in the following way:toolboxAPI = sfsf->toolboxAPI;
This function extends a spell instance to another figure. It makes the game engine regard both the source and new targets as affected by the same spell instance. The spell will be displayed in the UI of all affected units. Please note, this function does not automatically provide actual spell effect to the newly affected targets. In order to provide spell effect to them, the spell logic must be handled separately for each new target.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
figure_index: The index of the figure to which the spell is added.
spell_index: The index of the spell being added.
Function Signature:
void addSpellToFigure(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t figure_index, uint16_t spell_index);Example Usage:
toolboxAPI->addSpellToFigure(_this->SF_CGdFigureToolBox, target_index, spell_index);This function is used to spawn a given unit in the game world. The function allows to specify the coordinates of a spawn, the figure's faction, figure's type and other parameters (see below).
Once the function is completed, it will return the target index of a spawned unit.
Parameters:
_this: The pointer to the toolbox global object.
posX: The X position for the unit's spawn location.
posY: The Y position for the unit's spawn location.
owner: The figure ID of the unit's owner (summoner).
figure_type: The type of figure being added.
spawn_effect: The visual effect that occurs upon spawning.
npc_id: The unit ID according to GameData.
faction: The faction to which the unit belongs.
disable_ai: The AI switcher.
Function Signature:
uint16_t addUnit(SF_CGdFigureToolbox *_this, uint16_t posX, uint16_t posY, uint16_t owner, uint16_t figure_type, uint16_t spawn_effect, int npc_id, int faction, int disable_ai);Example Usage:
summon_index = toolboxAPI->addUnit(_this, real_pos.X, real_pos.Y, owner, creature_type, 0x13, 0, _this->CGdFigure->figures[master_index].faction, 0);This function is used to deal damage to a building. This function works the same as dealDamage, but must be used instead of dealDamage when damage targets a building.
Parameters:
CGdBuildingToolbox: The pointer to the building toolbox global object.
figure_id: The ID of the figure that is dealing damage.
building_id: The ID of the structure that is receiving damage.
damage: The amount of damage to be dealt.
is_spell_damage: A flag indicating whether the damage delivered should be regarded as spell damage.
Function Signature:
void buildingDealDamage(void *CGdBuildingToolBox, uint16_t figure_id, uint16_t building_id, uint16_t damage, uint32_t is_spell_damage);Example Usage:
if (target.entity_type == 2)
{
toolboxAPI->buildingDealDamage(_this->CGdBuildingToolBox, source_index, target.entity_index, damage, 0);
}This function is used in order to deal damage to a figure. This function works only to deal damage to units. In order to damage a building, you should use buildingDealDamage instead.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
source_index: The index of the figure that is dealing damage.
target_index: The index of the figure that is receiving damage.
damage: The amount of damage to be dealt.
is_spell_damage: A flag indicating whether the damage delivered should be regarded as spell damage.
param5: Currently unused. Pass it 0 for safety reasons.
param6: Currently unused. Pass it 0 for safety reasons.
Function Signature:
void dealDamage(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t source_index, uint16_t target_index, uint32_t damage, uint32_t is_spell_damage, uint32_t param5, uint32_t param6);Example Usage:
toolboxAPI->dealDamage(_this->SF_CGdFigureToolBox, source_index, target_index, spell_data.params[1], 1, 0, 0);This function is used check whether two figures are friendly towards each other. This function will return true if figures belong to the same faction and false for all other cases.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
source_index: The index of the source figure.
target_index: The index of the target figure.
Function Signature:
uint16_t figuresCheckFriendly(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t source_index, uint16_t target_index);Example Usage:
uint16_t isAlly = toolboxAPI->figuresCheckFriendly(_this->CGdFigureToolBox, source_index, target_index);This function is used check whether two figures are being hostile towards each other. This function will return true if figures are hostile to each other and false for all other cases.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
source_index: The index of the source figure.
target_index: The index of the target figure.
Function Signature:
uint16_t figuresCheckHostile(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t source_index, uint16_t target_index);Example Usage:
uint16_t isEnemy = toolboxAPI->figuresCheckHostile(_this->CGdFigureToolBox, source_index, target_index);This function is used check whether the two figures are neutral towards each other. This function will return true if figures belong to different factions, but aren't hostile to each other and false for all other cases.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
source_index: The index of the source figure.
target_index: The index of the target figure.
Function Signature:
uint16_t figuresCheckNeutral(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t source_index, uint16_t target_index);Example Usage:
uint16_t isNeutral = toolboxAPI->figuresCheckNeutral(_this->CGdFigureToolBox, source_index, target_index);This function is used to make a figure play animation corresponding to the certain activity. The full list of Job IDs can be checked here.
Parameters:
CGdFigureJobs: The pointer to the figure jobs global object.
figure_id: The ID of the figure for which the job is being set.
new_job: The ID of the job which must be assigned to the figure.
param_3: Currently unused. Pass it as 0 for safety reasons.
param_4: Currently unused. Pass it as 0 for safety reasons.
param_5: Currently unused. Pass it as 0 for safety reasons.
Function Signature:
void figureSetNewJob(void *CGdFigureJobs, uint32_t figure_id, uint32_t new_job, uint32_t param_3, uint32_t param_4, uint32_t param_5);Example Usage:
toolboxAPI->figureSetNewJob(_this->CGdFigureJobs, target_index, kGdJobWalkToObject, 1, 0, 0);This function finds the position closest to the sector and writes it to the variable of your choice.
Parameters:
_this: The pointer to the world toolbox global object.
param_1: The pointer to the starting coordinate from which to find the closest free position.
param_2: The pointer to the destination coordinate.
sector: The sector of the game world being considered for position finding.
return_value: The pointer where the closest free position will be stored.
Function Signature:
bool findClosestFreePosition(SF_CGdWorldToolBox* _this, SF_Coord *param_1, SF_Coord *param_2, uint16_t sector, SF_Coord *return_value);Example Usage:
toolboxAPI->findClosestFreePosition(_this->CGdWorldToolBox, &summon_pos, &offset, sector, &real_pos);This function is used to obtain the distance between two points in the world.
Parameters:
pointA: The pointer to SF_Coord variable that stores the X-Y coordinates of the first point.
pointB: The pointer to SF_Coord variable that stores the X-Y coordinates of the second point.
Function Signature:
uint32_t getDistance(SF_Coord *pointA, SF_Coord *pointB);Example Usage:
uint16_t distance = toolboxAPI->getDistance(&tower_position, &target_position);This function is used to retrieve the ID of a figure which occupies the specified X-Y coordinates.
Parameters:
CGdFigureToolbox: The pointer to the world toolbox global object.
posX: The figure X position.
posY: The figure Y position.
param3: Currently unused. Pass it as 0 for safety.
Function Signature:
uint16_t getFigureFromWorld(void *CGdWorldToolBox, uint16_t posX, uint16_t posY, uint32_t param3);Example Usage:
uint16_t target_index = toolboxAPI->getFigureFromWorld(_this->SF_CGdWorldToolBox, cell_x, cell_y, 0);Parameters:
CGdDoubleLinkedList: The pointer to the double linked list from which the next node is retrieved.
current_node: The current node from which the next node is being queried.
Function Signature:
uint16_t getNextNode(uint32_t *CGdDoubleLinkedList, uint16_t current_node);Example Usage:
spell_job_node = toolboxAPI->getNextNode(figureToolbox->CGdDoubleLinkedList, spell_job_node);This function returns the physical damage reduction amount provided to the figure by its armor rating. The reduction is expressed as percentage of damage total.
Note: Due to rounding specifics the reduction percentage must be applied to base damage according to the following formula: ((damage * reduction percentage) + 5000) / 10000.
Parameters:
SF_CGdFigureToolbox: The pointer to the figure toolbox global object.
source_index: The index of the figure that is dealing damage.
target_index: The index of the figure that is receiving damage.
action_id: The index of the spell type that is used to deal damage.
NB: Though intuitively it might seem other way, it's been specially tested. The result is that source index stands for attacker and target index stands for defender (the figure that is receiving damage).
Function Signature:
uint16_t getPhysDamageReduction(SF_CGdFigureToolbox *_this, uint16_t source_index, uint16_t target_index, uint16_t action_id);Example Usage:
uint16_t reduction_percent = toolboxAPI->getPhysDamageReduction(_this->SF_CGdFigureToolBox, source_index, target_index, kGdSpellLineRockBullet);NB: The percentage must be applied to damage in the following way, because of its rounding specifics:
damage = ((uint32_t)(damage * reduction_percent + 5000)) / 10000;This function can be used to obtain the index of a spell by its starting node.
Parameters:
CGdDoubleLinkedList: The pointer to the double linked list containing spell indices.
spell_job_start_node: The starting node for the spell job in the linked list.
Function Signature:
uint16_t getSpellIndexFromDLL(uint32_t *CGdDoubleLinkedList, uint16_t spell_job_start_node);Example Usage:
uint16_t spell_index = toolboxAPI->getSpellIndexFromDLL((uint32_t*) _this->battleData.CGdDoubleLinkList, spell_node);This function can be used to obtain the index of the spell of the given spell type. The function returns spell index of the first spell fitting the criteria, or 0 if there is no such spell.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
target_index: The index of the figure affected with the spell of the given type.
spell_line: The spell type ID to which the spell in query belongs.
last_known_index: The index of the last spell applied to the target figure. Better to pass it 0 for cases when you're unsure about.
Function Signature:
uint16_t getSpellIndexOfType(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t target_index, uint16_t spell_line, uint16_t last_known_index);Example Usage:
uint16_t shield_wall_spell_index = toolboxAPI->getSpellIndexOfType(_this->SF_CGdFigureToolBox, target_index, SHIELD_WALL_LINE, spell_index);This function can be used to check whether the figure is currently being the source of any spell with aura type.
Parameters:
_this: The pointer to the toolbox global object.
figure_id: The index of the figure which we're checking for having active aura.
Function Signature:
bool hasAuraActive (SF_CGdFigureToolbox *_this, uint16_t figure_id);Example Usage:
bool hasAura = toolboxAPI->hasAuraActive(_this->SF_CGdFigureToolBox, source_index);Description:
This function can be used to check whether the figure is currently affected with a spell of the given spell type. It returns 0 (false) for the unaffected figure and 1 for figure under effect of the given spell.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
figure_index: The index of the figure being checked for having the spell active.
spell_line_id: The spell type ID of the spell in check.
Function Signature:
uint32_t hasSpellOnIt(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t figure_index, uint16_t spell_line_id);Example Usage:
uint32 = hasShieldwall = toolboxAPI->hasSpellOnIt(_this->SF_CGdFigureToolBox, target_index, SHIELD_WALL_UNIVERSAL_LINE);This function is used to check whether the figure can be targeted with any actions, including attacks or spell casting.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
figure_index: The index of the figure which we are checking for being targetable.
Function Signature:
bool isTargetable(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t figure_index);Example Usage:
bool isTargetable = toolboxAPI->isTargetable(_this->SF_CGdFigureToolBox, target_index);This function can be used to check whether the unit fights in melee only. The function returns false if the unit fights in ranged and melee, and true if the unit fights in melee only.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
figure_index: The index of the figure which we are checking for being melee.
Function Signature:
bool isTargetable(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t figure_index);Example Usage:
bool isMelee = toolboxAPI->isUnitMelee(_this->SF_CGdFigureToolBox, target_index);This function can be used to remove the spell from the target figure. The game engine will regard the figure as unaffected with the given instance of a spell. Please note, this function doesn't stop the spell. It only removes it from the list of active spells over the figure.
The spell logic will continue to execute each tick until the spell terminates itself with the setEffectDone command. Additionally, any effect previously applied to the target must be removed separately.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
target_index: The index of a figure from which the spell will be removed.
spell_index: The index of a spell which has to be removed from the figure.
Function Signature:
uint32_t removeSpellFromList(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t target_index, uint16_t spell_index);Example Usage:
toolboxAPI->removeSpellFromList(_this->SF_CGdFigureToolBox, target_index, spell_index);Description:
This function should be used to recalculate unit's stats (health, mana, etc.) after any of its attributes have been modified with addBonusMultToStatistic command.
This function should be used in both cases: when the attribute has been altered and when it has been returned to its original value.
Parameters:
CGdFigureToolbox: The pointer to the toolbox global object.
figure_index: The index of the figure which statistics have to be adjusted.
Function Signature:
void rescaleLevelStats(SF_CGdFigureToolbox *CGdFigureToolbox, uint16_t figure_index);Example Usage:
toolboxAPI->rescaleLevelStats(_this->SF_CGdFigureToolBox, target_index);