Skip to content

SRD: Iterator Functions

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

This page provides an overview of Spellforce Framework functions and types which are used to work with an internal engine class known as Iterator. Iterator provides a set of functions which perform calculations necessary to simulate Area-of-Effect logic of the spells and abilities.

Iterator is an opaque class. The framework doesn't provide access to Iterator's internal structure and methods. Iterator accepts the area it must work with, and returns the index of every object located within it.

The functions which allow to interact with Iterator are taken from the sf_iterator_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_iterator_functions.h. The iterator functions can be accessed using iteratorAPI-> prefix, provided this group was previously initialized. In order to initialize the iterator functions you should,

  1. Allocate a pointer to the iterator functions within the global scope of your project. This is done as follows: IteratorFunctions *iteratorAPI;

  2. Assign this pointer the address of the iterator 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: iteratorAPI = sfsf->iteratorAPI;

Functions

buildingIteratorInit

This function is used to initialize the iterator which works with the buildings in a given area.

Parameters:
iterator: The pointer to the building iterator which must be initialized.
x_start: The minimum X coordinate determining the area of effect the given iterator will work with.
y_start: The minimum Y coordinate determining the area of effect the given iterator will work with.
x_end: The maximum X coordinate determining the area of effect the given iterator will work with.
y_end: The maximum Y coordinate determining the area of effect the given iterator will work with.

Function Signature:

void buildingIteratorInit(CGdBuildingIterator *iterator, uint16_t x_start, uint16_t y_start, uint16_t x_end, uint16_t y_end);

Example Usage:

iteratorAPI->buildingIteratorInit(&iterator_memory, 0x0, 0x0, 0x3ff, 0x3ff);

buildingIteratorSetPointers

[The reverse-engineering of the data types related to this function hasn't been fully completed yet, that means that currently this function is unable to be used. Sorry for possible inconveniences.]

Parameters:

iterator: The pointer to the building iterator which must be affected.
SF_CGdBuilding: The pointer to the Building global object.
AutoClass22: The purpose of this argument is currently unknown. Pass it as 0 for safe use.
CGdWorld: The pointer to the World global object.

Function Signature:

void buildingIteratorSetPointers(CGdBuildingIterator *iterator, void *SF_CGdBuilding, void *AutoClass22, void *CGdWorld);

Example Usage:

iteratorAPI->buildingIteratorSetPointers(&building_iterator, &building, &unused, &world);

disposeFigureIterator

This function should be used to dispose of the figure iterator that is no longer in use to release the memory allocated for it.

Parameters:

iterator: The figure iterator to be disposed.

Function Signature:

void disposeFigureIterator(CGdFigureIterator iterator);

Example Usage:

iteratorAPI->disposeFigureIterator(figure_iterator);

figureIteratorInit

This function can be used to set the area of the figure iterator and and get it started.

This function is deprecated. Please, use setupFigureIterator instead.

Parameters:

iterator: The pointer to the figure iterator that will be initialized.
x_start: The minimum X coordinate determining the area of effect the given iterator will work with.
y_start: The minimum Y coordinate determining the area of effect the given iterator will work with.
x_end: The maximum X coordinate determining the area of effect the given iterator will work with.
y_end: The maximum Y coordinate determining the area of effect the given iterator will work with.

Function Signature:

void figureIteratorInit(CGdFigureIterator *iterator, uint16_t x_start, uint16_t y_start, uint16_t x_end, uint16_t y_end);

Example Usage:

NB: This function is deprecated. Please, use setupFigureIterator instead.

iteratorAPI->figureIteratorInit(&iterator_memory, 0x0, 0x0, 0x3ff, 0x3ff);

figureIteratorSetPointers

This function was used to link the iterator with other game objects which are necessary for area of effect calculations. However, its functionality is made to be part setupFigureIterator now.

Parameters:

iterator: The pointer to the building iterator which must be affected.
SF_CGdBuilding: The pointer to the Building global object.
AutoClass22: The purpose of this argument is currently unknown. Pass it as 0 for safe use.
CGdWorld: The pointer to the World global object.

Function Signature:

void figureIteratorSetPointers(CGdFigureIterator *iterator, SF_CGdFigure *figure, void *AutoClass22, void *CGdWorld);

Example Usage:

This function is deprecated. Please, use setupFigureIterator instead.

iteratorAPI->figureIteratorSetPointers(&figure_iterator, _this->SF_CGdFigure, _this->unkn3, _this->SF_CGdWorld);

getNextBuilding

This function can be used to get the next building within the building iterator.

Parameters:

_this: The pointer to the building iterator which is currently processed.

Function Signature:

uint16_t getNextBuilding(CGdBuildingIterator *_this);

Example Usage:

building_index = iteratorAPI->getNextFigure(&building_iterator);

getNextFigure

This function is used to get the next figure with the figure iterator.

Parameters:

iterator: The pointer to the figure iterator which is currently processed.

Function Signature:

uint16_t getNextFigure(CGdFigureIterator *iterator);

Example Usage:

target_index = iteratorAPI->getNextFigure(&figure_iterator);

iteratorSetArea

This function is used to set the area in which the given iterator will search for targets.

Parameters:

iterator: The pointer to the iterator that is currently being initialized.
position: The pointer to the SF_Coord structure representing the center coordinates of the iterator.
radius: The iterator radius measured in game units.

Function Signature:

void iteratorSetArea(CGdFigureIterator *iterator, SF_Coord *position, uint16_t radius);

Example Usage:

iteratorAPI->iteratorSetArea(&figure_iterator, &cast_center, earthquake_radius);

setupFigureIterator

This function is used to initialize a new figure iterator.

Parameters:

iterator: The pointer to the iterator that must be initialized.
spell: The pointer to the Spell global object need by the iterator to retrieve data about the game world.

Function Signature:

void setupFigureIterator(CGdFigureIterator *iterator, SF_CGdSpell *spell);

Example Usage:

iteratorAPI->setupFigureIterator(&figure_iterator, _this);

Types

CGdFigureIterator

This type represents an iterator which works with the objects in the game world such as figures.

typedef struct __attribute__((packed))
{
	uint32_t ftable_ptr;
	CGdTileIterator_data data;
} CGdFigureIterator;

CGdBuildingIterator

This type represents an iterator which works with the objects in the game world such as buildings.

typedef struct __attribute__((packed))
{
	uint32_t btable_ptr;
	CGdTileIterator_data data;
} CGdBuildingIterator;

Clone this wiki locally