Revscriptsys (EventCallback)

Event Callback Usage Guide

The EventCallback system is a way to dynamically bind C++ functions to be triggered by specific events within the game. It's an elegant and flexible way to add custom behavior to various parts of your application.

Event Callback Types

Event callbacks are available for several categories of game entities, such as Creature, Player, Party, and Monster.

In the above list, each function is prefixed with (bool) or (void). This annotation indicates the expected return type of the function:

• (bool): The function should return a boolean value (true or false). The return value can affect the program flow on the C++ side. For example, if the function returns false, the execution of the associated function on the C++ side is immediately stopped.
• (void): The function does not return any value. It just performs an action and then terminates.

These are the functions available to use

• (bool) creatureOnChangeOutfit
• (bool) creatureOnAreaCombat
• (bool) creatureOnTargetCombat
• (void) creatureOnHear
• (void) creatureOnDrainHealth
• (bool) partyOnJoin
• (bool) partyOnLeave
• (bool) partyOnDisband
• (void) partyOnShareExperience
• (bool) playerOnBrowseField
• (void) playerOnLook
• (void) playerOnLookInBattleList
• (void) playerOnLookInTrade
• (bool) playerOnLookInShop
• (bool) playerOnMoveItem
• (void) playerOnItemMoved
• (void) playerOnChangeZone
• (void) playerOnChangeHazard
• (bool) playerOnMoveCreature
• (void) playerOnReportRuleViolation
• (void) playerOnReportBug
• (bool) playerOnTurn
• (bool) playerOnTradeRequest
• (bool) playerOnTradeAccept
• (void) playerOnGainExperience
• (void) playerOnLoseExperience
• (void) playerOnGainSkillTries
• (void) playerOnRemoveCount
• (void) playerOnRequestQuestLog
• (void) playerOnRequestQuestLine
• (void) playerOnStorageUpdate
• (void) playerOnCombat
• (void) playerOnInventoryUpdate
• (void) monsterOnDropLoot
• (void) monsterOnSpawn
• (void) npcOnSpawn

Event Callback Usage

To use the EventCallback system, you first need to create an instance of EventCallback, then define the functions you want to trigger on specific events. Once done, register your callback to make it active.

Below are examples for each category of game entities:

Creature Callback

local callback = EventCallback()

function callback.creatureOnAreaCombat(creature, tile, isAggressive)
	-- custom behavior when a creature enters combat area
	return true
end

callback:register()

Player Callback

local callback = EventCallback()

function callback.playerOnLook(player, position, thing, stackpos, lookDistance)
	-- custom behavior when a player looks at something
end

callback:register()

Party Callback

local callback = EventCallback()

function callback.partyOnJoin(party, player)
	-- custom behavior when a player joins a party
end

callback:register()

Monster Callback

local callback = EventCallback()

function callback.monsterOnSpawn(monster, position)
	-- custom behavior when a monster spawns
end

callback:register()

Npc Callback

local callback = EventCallback()

function callback.npcOnSpawn(npc, position)
	-- custom behavior when a npc spawns
end

callback:register()

Boolean Event Callbacks

Some event callbacks are expected to return a boolean value. The return value plays a crucial role in determining the flow of the program on the C++ side.

If the callback returns false, the execution of the associated function on the C++ side is stopped immediately. This allows you to use Lua scripting to introduce custom conditions for the execution of C++ functions.

Here is an example of a boolean event callback:

local callback = EventCallback()

function callback.creatureOnAreaCombat(creature, tile, isAggressive)
	-- if the creature is not aggressive, stop the execution of the C++ function
	if not isAggressive then
		return false
	end

	-- custom behavior when an aggressive creature enters a combat area
	return true
end

callback:register()

In this example, when a non-aggressive creature enters a combat area, the creatureOnAreaCombat function returns false, stopping the associated function on the C++ side.

Multiple Callbacks for the Same Event

You can define multiple callbacks for the same event type. This allows you to encapsulate different behaviors in separate callbacks, making your code more modular and easier to manage.

It also allows you to use the same callback in different parts of your Lua scripts. All the registered callbacks for a specific event are triggered when that event occurs.

Here is an example of defining multiple callbacks for the creatureOnAreaCombat event:

Example 1

local example1 = EventCallback()

function example1.creatureOnAreaCombat(creature, tile, isAggressive)
	-- custom behavior 1 when a creature enters combat area
end

example1:register()

Example 2

local example2 = EventCallback()

function example2.creatureOnAreaCombat(creature, tile, isAggressive)
	-- custom behavior 2 when a creature enters combat area
end

example2:register()