S4TickProc

S4TickProc callback function

An application-defined or library-defined callback function used with the ISettlers4Api::AddTickListener method. The library calls this function whenever the game is processing a tick. It can be used to delay local user events (events that are caused directly by the local player). It is also a good place to inject your own events to the event queue.

The LPS4TICKCALLBACK type defines a pointer to this callback function.

Syntax

HRESULT S4HCALL S4TickProc(
	DWORD dwTick, 
	BOOL bHasEvent, 
	BOOL bIsDelayed
);

Parameters

dwTick

The current tick the game is about to process.

bHasEvent

This parameter is not NULL if the game would like to dequeue an event for this tick. Otherwise it is NULL.

bIsDelayed

This parameter is TRUE if a S4TickProc in the current callback chain wants to not let the game dequeue an event this tick. Otherwise it is FALSE.

Return value

If the game has an event in the queue (bHasEvent != NULL) and you want to not let the game dequeue and process it this tick return TRUE. Otherwise return FALSE.

Remarks

You should not create an event this tick If bIsDelayed is TRUE. If it is not TRUE and you want to process an event, you should return TRUE.

You cannot cancel events with this callback. Register to the specific event e.g. use AddSettlerSendListener if you want to discard a settler send event.

This callback should be used if you intend to create events as the local player. Use it to e.g. command warriors. Basically anything the player can interact with the world is processed by this callback. See here for a list. Note that not all events on that list are actually issued by the player himself.

Example

Creating a local user event using the S4TickProc (e.g. destroying a building or commanding units)

HRESULT S4HCALL S4TickProc(DWORD dwTick, BOOL bHasEvent, BOOL bIsDelayed) {
    if (bIsDelayed) return FALSE; // someone is already requesting to create an event
    
    if (GetAsyncKeyState( 'G' )) { // check if the condition for creating an event is met
        CreateCustomEvent( dwTick ); // e.g. destroying a building or commanding units
        return TRUE; // prevent others from attaching an event, including the game itself
    }
    
    return FALSE; // we do not intend to create an event for this tick
}

Requirements

Minimum API Level	1
Target Edition	Any
Header	S4ModApi.h
Library	S4ModApi.lib
DLL	S4ModApi.dll

See also

ISettlers4Api

ISettlers4Api::AddTickListener