Skip to content

SRD: Figure Functions

Jump to bottom
Teekius edited this page Jan 5, 2025 · 10 revisions

This page provides an overview of Spellforce Framework functions and types which can be used to manipulate behavior and statistics of the game figures (aka units).

These functions are taken from the sf_figure_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_figure_functions.h. The figure functions can be accessed using figureAPI-> prefix, provided this group was previously initialized. In order to initialize the figure functions you should,

  1. Initalize a pointer to the figure functions within the global scope of your project. This is done as follows: FigureFunctions *figureAPI;

  2. Assign this pointer the address of the figure functions within the main structure of the Spellforce Framework. Usually this is done as part of InitModule function after the framework was initialized. This is done in the following way: figureAPI = sfsf->figureAPI;

Functions

addAction

This function is used to force a figure to make a specific action. However, this function isn't fully implemented yet, further clarification needed.

Parameters:

figure: Pointer to the Figure global object.
target: The target index of a figure.
maybe_action: Unclear, probably the action to be added to a figure. [Further reverse-engineering required]

Function Signature:

bool addAction(SF_CGdFigure *figure, uint16_t target, void *maybe_action);

Example Usage:





addBonusMult


Parameters:


statistic: The pointer to the figure's statistic (attribute) structure.

value: The percentage to increase the figure's attribute by. The percentage is stored as an integer, and it's limited by [-127;128] span.


Function Signature:


uint8_t addBonusMult(FigureStatistic *statistic, uint8_t value);


Example Usage:






addBonusMultToStatistic


This function can be used to add a percentage bonus to the figure's statistic (attribute) such as Armor, Magic Resistance, Strength, Wisdom, etc. The percentage is represented as an integer number ranging from -127 to 128 (int8_t). The game engine automatically recalculates the figure's statistic whenever the bonus multiplier was added.


This function is additive, whenever you activate it again, the new value will be added on the top of the already existing bonus.


The same function can be used to decrease figure's statistic by percentage, to do so you should add the negative value instead of positive.


Parameters:


figure: The pointer to the Figure global object.

key: The statistic data key to which the bonus multiplier will be added.

target: The target index of a figure which statistic must be increased.

value: The percentage to increase the figure's attribute by. The percentage is stored as an integer, and it's limited by [-127;128] span.


Function Signature:


void addBonusMultToStatistic(SF_CGdFigure *figure, StatisticDataKey key, uint16_t target, int8_t value);


Example Usage:


figureAPI->addBonusMultToStatistic(_this->SF_CGdFigure, ARMOR, target_index, recalc_value);




decreaseHealth


This function can be used to decrease the current health of a figure by certain amount.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a figure which health will be decreased.

amount: The integer the health will be decreased by.


Function Signature:


void decreaseHealth(SF_CGdFigure *figure, uint16_t figure_id, uint16_t amount);


Example Usage:


figureAPI->(_this->SF_CGdFigure, target_index, fire_damage);




getAggroValue


This function can be used to check the aggressiveness value the source figure has towards the target.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a source figure which aggressiveness we want to check.

target_index: The index of a figure towards which we want to check the aggressiveness of the source figure.


Function Signature:


uint16_t getAggroValue(SF_CGdFigure *, uint16_t figure_id, uint16_t target_index);


Example Usage:


figureAPI->getAggroValue(_this->SF_CGdFigure, source_index, target_index);




getCurrentHealth


This function can be used to obtain a figure's current health.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a figure health of which we want to obtain.


Function Signature:


uint16_t getCurrentHealth(SF_CGdFigure *figure, uint16_t figure_id);


Example Usage:


uint16_t current_health = figureAPI->getCurrentHealth(_this->CGdFigure, target_index);




getCurrentMaxHealth


This function is used to obtain figure's maximum health.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a figure maximum health of which we want to obtain.


Function Signature:


uint16_t getCurrentMaxHealth(SF_CGdFigure *figure, uint16_t figure_id);


Example Usage:


uint16_t max_health = figureAPI->getCurrentMaxHealth(_this->CGdFigure, target_index);




getCurrentMaxMana


This function can be used to obtain the figure's maximum mana.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a figure for which we want to obtain the maximum mana.


Function Signature:


uint16_t getCurrentMaxMana(SF_CGdFigure *figure, uint16_t figure_id);


Example Usage:


uint16_t max_mana = figureAPI->getCurrentMaxMana(_this->CGdFigure, target_index);




getJob


This function can be used to learn the figure's current job.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of a figure which job we want to obtain.


Function Signature:


uint16_t getJob(SF_CGdFigure *figure, uint16_t figure_id);


Example Usage:


figureAPI->getJob(_this->CGdFigure, target_index);




getManaCurrent


This function can be used to retrieve the current amount of figure's mana.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of the figure for which we want to retrieve the current amount of mana.


Function Signature:


uint16_t getManaCurrent(SF_CGdFigure *figure, uint16_t figure_id);


Example Usage:


uint16_t current_mana = figureAPI->getManaCurrent(_this->CGdFigure, target_index);




getPosition


This function can be used to obtain an object X-Y coordinates and write them into SF_Coord structure.


Parameters:


figure: Pointer to the Figure global object.

position: Pointer to the structure that saves X-Y coordinates.

figure_id: The index of a figure which coordinates we want to know.


Function Signature:


SF_Coord getPosition(SF_CGdFigure *figure, SF_Coord *position, uint16_t figure_id);


Example Usage:


SF_Coord figure_position = figureAPI->getPosition(_this->SF_CGdFigure, &cast_center, source_index);




getSpellJobStartNode


This function can be used to obtain the index of the starting node of the spell job.


Parameters:


figure: Pointer to the Figure global object.

figure_index: The index of the figure affected with a spell which job's starting node index we want to obtain.


Function Signature:


uint16_t getSpellJobStartNode(SF_CGdFigure *figure, uint16_t figure_index);


Example Usage:


starting_node = figureAPI->getSpellJobStartNode(_this->SF_CGdFigure, target_index) 




getTargetAction


This function can be used to learn what activity the figure is currently doing.


Parameters:


figure: Pointer to the Figure global object.

action: Pointer to the action structure which stores target action.

figure_id: The target index of a figure which action we want to obtain.


Function Signature:


SF_SGtFigureAction *getTargetAction(SF_CGdFigure *figure, SF_SGtFigureAction *action, uint16_t figure_id);


Example Usage:


figureAPI->getTargetAction(_this->CGdFigure, &action, source_index);




getWeaponStats


Parameters:


figure: Pointer to the Figure global object.
stats_in: Pointer to the structure that stores weapon statistics.
figure_id: The index of the figure wielding the weapon which statistics we want to obtain.


Function Signature:


SF_CGdFigureWeaponStats *getWeaponStats(SF_CGdFigure *figure, SF_CGdFigureWeaponStats *stats_in, uint16_t figure_id);


Example Usage:


SF_CGdFigureWeaponStats weapon_statistics = figureAPI->getWeaponStats(_this->CGdFigure, weapon_statistics, source_index);




isAlive


This function can be used to check whether a figure is alive.


Parameters:


figure: Pointer to the Figure global object.

target: The target index of a figure being checked.


Function Signature:


bool isAlive(SF_CGdFigure *figure, uint16_t target);


Example Usage:


boolean alive = figureAPI->isAlive(_this->CGdFigure, source_index);




isFlagSet


This function can be used to check whether the certain flag was raised over a figure.


Parameters:


figure: Pointer to the Figure global object.

figure_index: The index of a figure for which we're going to check the flag.

flag: The flag to check.


Function Signature:


bool isFlagSet(SF_CGdFigure *figure, uint16_t figure_index, GdFigureFlags flag);


Example Usage:


boolean figure_invulnerable = figureAPI->isFlagSet(_this->battleData.CGdFigure, target_index, UNKILLABLE);




rescaleHealth


This function can be used in order to maintain the same ratio of current and maximum health after changing the figure's maximum health.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of the figure which health we're going to rescale.

max_health: The new maximum health value.


Function Signature:


void rescaleHealth(SF_CGdFigure *figure, uint16_t figure_id, uint16_t max_health);


Example Usage:


figureAPI->rescaleHealth(_this->SF_CGdFigure, target_index, max_health);




rescaleMana


This function can be used in order to maintain the same ratio of current and maximum mana after changing the figure's maximum mana.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of the figure which mana we're going to rescale.

max_mana: The new maximum mana value.


Function Signature:


void rescaleMana(SF_CGdFigure *figure, uint16_t figure_id, uint16_t max_mana);


Example Usage:


figureAPI->rescaleMana(_this->SF_CGdFigure, target_index, max_mana);




setAggroValue


This function can be used to adjust (increase or decrease) the amount of aggressiveness of one figure towards another.


Parameters:


figure: Pointer to the Figure global object.

figure_id: The index of the source figure which aggressiveness value we're going to change.

target_index: The index of the target figure towards which we're going to change the source aggressiveness value.
aggroValue: The new aggro value.

unkn: Currently unknown, pass it as 0 for safe use.


Function Signature:


void setAggroValue(SF_CGdFigure *, uint16_t figure_id, uint16_t target_index, uint16_t aggroValue, uint32_t unkn);


Example Usage:


figureAPI->setAggroValue(_this->CGdFigure, target.entity_index, source_index, 12000, 0);




setJobToDoCount


This function can be used to assign a new job to a figure.


Parameters:


figure: Pointer to the Figure global object.

target_index: The target index of a figure.

value: The index of a new job. The possible indexes are stored inside of Figure Jobs enum.


Function Signature:


void setJobToDoCount(SF_CGdFigure *figure, uint16_t target_index, uint16_t value);


Example Usage:


figureAPI->setJobToDoCount(_this->CGdFigure, target_index, kGdJobPunch);




setTask


This function can be used to assign a new task to a figure.


Parameters:


_figure: Pointer to the Figure global object.

figure_index: The index of the figure for which to set the task.

figureTask: The index of the task to be assigned to the figure. It can be accessed via CGdFigureTask enum.


Function Signature:


void setTask(SF_CGdFigure *_figure, uint16_t figure_index, CGdFigureTask figureTask);


Example Usage:


figureAPI->setJobToDoCount(_this->CGdFigure, target_index, TASK_PET);




setWalkSpeed


Parameters:


figure: Pointer to the Figure global object.

target: The index of a figure which speed we want to set.
value: The new speed value.


Function Signature:


bool setWalkSpeed(SF_CGdFigure *figure, uint16_t target, uint16_t value);


Example Usage:


figureAPI->setWalkSpeed(_this->SF_CGdFigure, source_index, 200);




subMana


This function is used to decrease the figure's current mana.


Parameters:


_this: Pointer to the Figure global object.

figure_index: The index of a figure which mana we're going to decrease.

amount: The amount we're going to subtract from the figure's mana.


Function Signature:


void subMana(SF_CGdFigure *_this, uint16_t figure_index, uint32_t amount);


Example Usage:


figureAPI->subMana(_this->CGdFigure, target_index, mana_left);


Enums


CGdFigureTask


    TASK_WORKER = 2,
    TASK_WOODCUTTER = 3,
    TASK_QUARRY = 4,
    TASK_MINE = 5,
    TASK_FORGE = 6,
    TASK_HERO = 9,
    TASK_MAINCHAR = 10,
    TASK_NPC = 11,
    TASK_PET = 12,
    TASK_HUNTING_LODGE = 14,
    TASK_MERCHANT = 17


StatisticDataKey


    ARMOR,
    AGILITY,
    CHARISMA,
    DEXTERITY,
    HEALTH,
    INTELLIGENCE,
    MANA_STUFF,
    STAMINA,
    STRENGTH,
    WISDOM,
    RESISTANCE_FIRE,
    RESISTANCE_ICE,
    RESISTANCE_MENTAL,
    RESISTANCE_BLACK,
    WALK_SPEED,
    FIGHT_SPEED,
    CAST_SPEED


FigureJobs


    kGdJobDefault = 0,
    kGdJobNone = 0,
    kGdJobGroupNothing = 1,
    kGdJobNothing = 1,
    kGdJobStepAside = 2,
    kGdJobGroupWalk = 2,
    kGdJobOfferMe = 3,
    kGdJobShrineWorkerCheckDrop = 4,
    kGdJobCarpenterWork = 5,
    kGdJobWalkToBasePoint = 6,
    kGdJobCastPreResolve = 7,
    kGdJobWalkToAttackMonument = 8,
    kGdJobCattleBreederWalkToDeliverGood = 9,
    kGdJobWoodCutterStoopToDropLog = 10,
    kGdJobCattleBreederCheckDrop = 11,
    kGdJobWoodCutterCheckDrop = 12,
    kGdJobGotoBuildingForWork = 13,
    kGdJobStartWorkAtBuilding = 14,
    kGdJobCattleBreederWalkHome = 15,
    kGdJobCorpseCollectorWalkToCorpse = 16,
    kGdJobBuilderWalkToBuildPos = 17,
    kGdJobBuilderBuild = 18,
    kGdJobCorpseCollectorSearchForWork = 19,
    kGdJobStoneMinerCheckDrop = 20,
    kGdJobMinerCheckResource = 21,
    kGdJobFarmerWalkToDeliverGood = 22,
    kGdJobWoodCutterSearchTree = 23,
    kGdJobWoodCutterWalkToTree = 24,
    kGdJobWoodCutterCheckTree = 25,
    kGdJobWoodCutterCutTree = 26,
    kGdJobWoodCutterWalkHome = 27,
    kGdJobClubMakerSearchForWork = 28,
    kGdJobMinerWalkToWork = 29,
    kGdJobStoneMinerStoopToDropStone = 30,
    kGdJobCorpseCollectorCheckCorpse = 31,
    kGdJobStoneMinerSearchStone = 32,
    kGdJobStoneMinerWalkToStone = 33,
    kGdJobStoneMinerCheckStone = 34,
    kGdJobStoneMinerCrushStone = 35,
    kGdJobStoneMinerWalkHome = 36,
    kGdJobClubMakerWork = 37,
    kGdJobGoto = 38,
    kGdJobWalkToTarget = 39,
    kGdJobHitTarget = 40,
    kGdJobDie = 41,
    kGdJobWarriorNothing = 42,
    kGdJobCast = 43,
    kGdJobCarpenterSearchForWork = 44,
    kGdJobMinerWalkHome = 45,
    kGdJobMinerCheckDrop = 46,
    kGdJobSmelterSearchForWork = 47,
    kGdJobSmelterWork = 48,
    kGdJobMinerWalkToDeliverGood = 49,
    kGdJobCarrierCheckDrop = 50,
    kGdJobGathererSearchResource = 51,
    kGdJobShrineWorkerSearchForWork = 52,
    kGdJobShrineWorkerWalkToMana = 53,
    kGdJobShrineWorkerTakeMana = 54,
    kGdJobShrineWorkerWalkHome = 55,
    kGdJobFoodWorkerSearchForWork = 56,
    kGdJobFoodWorkerWork = 57,
    kGdJobGathererWalkToResource = 58,
    kGdJobGathererCheckResource = 59,
    kGdJobGathererWork = 60,
    kGdJobGathererWalkHome = 61,
    kGdJobPriestSearchForWork = 62,
    kGdJobPriestWork = 63,
    kGdJobFarmerCheckDrop = 64,
    kGdJobFarmerCheckHarvest = 65,
    kGdJobGathererWalkToDeliverGood = 66,
    kGdJobGathererCheckDrop = 67,
    kGdJobEnterBuilding = 68,
    kGdJobExitBuilding = 69,
    kGdJobHunterCheckTarget = 70,
    kGdJobHitTargetRange1 = 71,
    kGdJobStoneMinerWalkToDeliverGood = 72,
    kGdJobWalkToObject = 73,
    kGdJobHitTargetRange2 = 74,
    kGdJobForesterCheckPlant = 75,
    kGdJobForesterSearchForWork = 76,
    kGdJobForesterWalkToWork = 77,
    kGdJobForesterPlant = 78,
    kGdJobForesterWalkHome = 79,
    kGdJobCorpseCollectorWalkHome = 80,
    kGdJobMeleeAbility = 81,
    kGdJobFarmerWaitForWork = 82,
    kGdJobOrcRegenerate = 83,
    kGdJobFarmerWalkToSow = 84,
    kGdJobFarmerSow = 85,
    kGdJobFarmerWalkHomeSow = 86,
    kGdJobCorpseCollectorCutCorpse = 87,
    kGdJobCorpseCollectorWalkToDeliverGood = 88,
    kGdJobFarmerWalkToHarvest = 89,
    kGdJobFarmerHarvest = 90,
    kGdJobFarmerWalkHomeHarvest = 91,
    kGdJobCorpseCollectorCheckDrop = 92,
    kGdJobWoodCutterWalkToDeliverGood = 93,
    kGdJobShrineWorkerCheckMana = 94,
    kGdJobFisherSearchForWork = 95,
    kGdJobFisherWalkToWork = 96,
    kGdJobFisherCheckResource = 97,
    kGdJobFisherWork = 98,
    kGdJobFisherWalkHome = 99,
    kGdJobFisherWalkToDeliverGood = 100,
    kGdJobFisherCheckDrop = 101,
    kGdJobWalkToPortal = 102,
    kGdJobPreCast = 103,
    kGdJobBuilderSearchForWork = 104,
    kGdJobReleaseDelay = 105,
    kGdJobPetIdle = 106,
    kGdJobPetWalkToMaster = 107,
    kGdJobAnimalIdle = 108,
    kGdJobAnimalWalkToNewPlace = 109,
    kGdJobWalkToNPC = 110,
    kGdJobCriticalHit = 111,
    kGdJobMinerSearchResource = 112,
    kGdJobMinerWork = 113,
    kGdJobMinerStoopToDropGood = 114,
    kGdJobFeignDeath = 115,
    kGdJob116 = 116,
    kGdJob117 = 117,
    kGdJob118 = 118,
    kGdJobSmithSearchForWork = 119,
    kGdJobSmithWork = 120,
    kGdJobHunterCheckCorpse = 121,
    kGdJobHunterCutCorpse = 122,
    kGdJobHunterCheckDrop = 123,
    kGdJobCorpseRot = 124,
    kGdJobManualWalkToTarget = 125,
    kGdJobHunterSearchForWork = 126,
    kGdJobHunterWalkToTarget = 127,
    kGdJobHunterHitTarget = 128,
    kGdJobHunterWalkToCorpse = 129,
    kGdJob130 = 130,
    kGdJob131 = 131,
    kGdJobHunterWalkHome = 132,
    kGdJobHunterWalkToDeliverGood = 133,
    kGdJobCattleBreederSearchForWork = 134,
    kGdJobCattleBreederFeed = 135,
    kGdJob136 = 136,
    kGdJobCorpseRotWithLoot = 137,
    kGdJobCastResolve = 138,
    kGdJobWalkToMaster = 139,
    kGdJobCheckBattleSleep = 140,
    kGdJobWalkToAttackBuilding = 141,
    kGdJobWarTowerIdle = 142,
    kGdJobGotHit = 143,
    kGdJobWalkBack = 144,
    kGdJobStrafeLeft = 145,
    kGdJobStrafeRight = 146,
    kGdJobStoop = 147,
    kGdJobStandup = 148,
    kGdJobStrike = 149,
    kGdJobStab = 150,
    kGdJobPunch = 151,


              


          



  
          

            


            
Clone this wiki locally