Game Events

Crea uses an event system to allow for actions to be listened to and provide custom logic. All events use the GameEvent interface which we will go over some below.

Event Types

While all events share the same interface, they are used in many places.

Global game events are used with game.events which is technically an EventComponent. This allows for new events to be added easily and listened to by name.

game.events['player_respawn'].invoke(player)
# elsewhere...
game.events['player_respawn'].listen(player)

The EventComponent is an actual component that can be added to any Entity and consequently any entity can invoke and listen to events on itself. This is used for many things such as when an entity is interacted with it uses the event ‘interact’.

entity.event['interact'].listen(self.interact)

Sometimes a GameEvent is used directly. This is typically for when a system or component has a specific event it wants to invoke. Such as in the ResearchComponent at mods/core/component/research.py we use a GameEvent for when a new item is discovered.

self.onDiscovered = GameEvent()
# Elsewhere in ResearchComponent
self.onDiscovered.invoke(content.id)

# Somewhere completely different we can listen to this.
entity.research.onDiscovered.listen(self.handleDiscovered)

Using Events

The GameEvent interface is fairly straight-forward with GameEvent.listen() and GameEvent.invoke() being the two most important functions.

When listening to an event it is important to ensure the event handler signature properly matches the arguments that are provided to the event’s invoke.

Note

The return value from an event handler tells the GameEvent if it should remove the handler or not. Return True to remove the handler or return nothing to keep it.

def playerCreated(player):
    player.entity.inventory.addBag(0, PlayerTuning.STARTING_BAG_SIZE)

def register():
    game.events["player_created"].listen(playerCreated)

def unregister():
    game.events["player_created"].remove(playerCreated)

You’ll see we also need to call GameEvent.remove() when we are done with it. This is especially important with global events when Game.onUnregistration() is invoked.

Note

Always be sure to remove an event when it is no longer needed!

Global Game Events

auri_tree_grown(entity)

Called when an Auri tree becomes fully grown.

Parameters:entity (Entity) – The Auri tree entity.
backup_saves(*paths)

Called when saved file(s) need to be backed up. This only happens once per session when the game is exiting.

Parameters:paths – An arbitrary argument list of paths.
character_saved(player)

Called when a player character has been saved to disk.

Parameters:player (Player) – The player that was just saved.
client_input_ready(client)

Called when a player’s input has been initialized. This can be used to manipulate the input such as adding new core.system.input.InputStateHandler.

Parameters:client (core.system.input.ClientInput) – The client input that is now ready.
control_change(controllerType, name, controlCode)

Called when a control input value is changed.

Parameters:
  • controllerType (core.system.input.ControllerTypes) – The
  • name (str) – The name of the control that is changing. This is the key used in the controls in settings.
  • controlCode (Keyboard, Joy or JoyCombo) – The new controller code that will be used.
create_realm(realm)

Called when a realm has been created. This includes realms created during load.

Parameters:realm (Realm) – The newly created realm.
create_talent(talent)

Called when a talent is being created for a player.

Parameters:talent (Talent) – The newly created talent.
crystal_activated(player, travelPlayer, self.crystals[uid])

Called when a Way Crystal has been activated by a player.

Parameters:
  • player (Player) – The player that activated the crystal.
  • travelPlayer (core.system.travel.TravelPlayer) – The TravelPlayer that belongs to the player activating the crystal.
  • crystalId (int) – The entity ID of the activated crystal.
damage_item(entity, isDestroyed)

Called when a placed item has been damaged (being collected).

Parameters:
  • entity (Entity) – The item being damaged.
  • isDestroyed (bool) – Whether the item has been destroyed (turned to a drop item).
dropped_collected(entity, item)

Called when a player collects a dropped item.

Parameters:entity (Entity) – The Player entity that collected the dropped item.
Para InventoryItem item:
 The dropped item that was collected.
dropped_expired(realm, entity)

Called when a dropped item has expired and will be removed.

Parameters:
  • realm (Realm) – The realm the dropped item existed in.
  • entity (Entity) – The entity of the dropped item.
exit_game()

Called when the game is being exited by the window being closed.

gather_tile(player, tileComponent, entity, tilePosition)

Called when a tile is being gathered by a player.

Parameters:
  • player (Player) – The player gathering the tile.
  • tileComponent (TileComponent) – The tile that is being gathered.
  • entity (Entity) – The dropped item entity of the tile.
  • tilePosition (TileVector) – The position of the gathered tile.
hit_tile(entity, realm, tileComponent, tileLayer.type, tilePosition, brokeTile)

Called when an entity hits a tile to harvest it.

Parameters:
  • entity (Entity) – The entity that hit the tile. This can be a player or some other entity like a projectile.
  • realm (Realm) – The realm the tile exists in.
  • tileComponent (TileComponent) – The tile that is being hit.
  • layerType (Layer) – The type of layer the tile belongs to.
  • tilePosition (TileVector) – The position of the tile.
  • brokeTile (bool) – Whether this tile was destroyed or not.
load_biomes(biomes)

Called when requesting all possible biomes to use during world generation. Append new biomes to the provided list.

Parameters:biomes (list) – Empty list for which Biome instances should be added.
merchant_wares(wares, daily)

Called when the merchant wares have been setup. These lists may be modified but cannot exceed core.tuning.NpcTuning.MERCHANT.MAX_WARES and core.tuning.NpcTuning.MERCHANT.MAX_DAILY.

Parameters:
  • wares (list of InventoryItem) – The default wares the merchant NPC has for sale.
  • daily (list of InventoryItem) – The daily items the merchant NPC has for sale.
npc_price_notice()

Called when the NPC prices should be recalculated. NPC prices are calculated in mods.core.npc.getNpcPrice().

obsidian_created(realm, tilePosition, waterAmount, lavaAmount)

Called when obsidian is created by having water and lava mix.

Parameters:
  • realm (Realm) – The realm that the obsidian was created in.
  • tilePosition (TileVector) – The tile position that the obsidian was created in.
  • waterAmount (int) – The amount of water that was in the cell when obsidian was created.
  • lavaAmount (int) – The amount of lava that was in the cell when obsidian was created.
pause_change(isPaused)

Called when the game’s paused state changes.

Parameters:isPaused (bool) – If the game is paused now or not.
perform_physics(entities, timestepTime)

Called when a physics step is about to be performed on a set of entities.

Parameters:
  • entities (EntitySet) – The set of entities
  • timestepTime (int) – The amount of time the physics simulation is set forward.
placed_entity(entity)

Called when an entity is placed down with PlacementHandler.createPlacement().

Parameters:entity (Entity) – The entity that was just placed.
player_created(player)

Called when a new character has been created through character creation.

Parameters:player (Player) – The newly created player.
player_joined(player)

Called immediately when a player joins the world before the player has fully loaded.

Parameters:player (Player) – The player who just joined.
player_left(player)

Called when a player leaves the world.

Parameters:player (Player) – The player who just left.
player_ready(player)

Called on the server when it has been notified that the client has received all data for their character. This should be used when needing to send data to client’s that is dependent on the player data.

Parameters:player (Player) – The player that has just joined and is ready.
player_respawn(player)

Called when a player has finished respawning at their attuned crystal.

Parameters:player (Player) – The player that has finished respawning.
player_revive(player)

Called when a player is revived at their fallen position.

Parameters:player (Player) – The player that was just revived.
player_spawn(player)

Called when a player has finished joining the game and has spawned in the world.

Parameters:player (Player) – The player that just joined.
populate_treasure(player, chest, groups)

Called when a treasure chest is about to be populated with loot.

Parameters:
  • player (Player) – The player that is opening the treasure chest.
  • chest (str) – The type of the chest that is being populated. This is generally the content name of the chest.
  • groups (list of core.system.treasure.TreasureActiveGroup) – The loot groups that the treasure chest will be populated with.
registration_finished()

Called after game registration has completely finished. This means all mods have registered and should be initialized.

setup_body(template, identifier)

Called when a body content is nearly finished being setup. This allows for manipulation on the body content before it is finalized.

Parameters:
  • template (core.template.template.Template) – The body content template.
  • identifier (str) – The unique body identifier that is being created.
tick()

Called when the game ticks is triggered. This occurs every 3 seconds.

tile_changed(tileLayer, position, previousId, tileId)

Called when a tile has changed.

Parameters:
  • tileLayer (TileLayer) – The layer that the tile has changed on.
  • position (TileVector) – The position of that changed tile.
  • previousId (int) – The tile ID of the tile before it was changed.
  • tileId (int) – The new tile ID of the changed tile.
world_created(world)

Called when the world has been created. This includes when a world is being loaded or connected to.

Parameters:world (World) – The created world.
world_loaded(world)

Called when the world has finished loading and all systems are ready.

Parameters:world (World) – The loaded world.
world_saved(world, asynchronous)

Called after the world has been saved. Handle this whenever you need to save some data unassociated.

Parameters:
  • world (World) – The world that is being saved.
  • asynchronous (bool) – If the world is being saved asynchronously.
world_unloaded(world)

Called when The world has been exited and is about to be fully unloaded.

Parameters:world (World) – The world being exited.

Call Events

Some events are invoked to support handlers changing the state of things. This is achieved with core.helper.callEvent() which provides a special interface for this.

callEvent(eventName, player, *args, **kwargs)

Invokes the named event for both the player entity (player.entity.events[eventName]) as well as a global event (game.event[eventName]). Any provided keyword arguments are automatically packed up into a core.helper.AttrDict (results) which is passed to the event handlers and returned. Values in results can be modified by other handlers so prefer it over the the provided argument unless you want to use the original value.

The event handlers resulting signature is: handler(player, results, *args, **kwargs)

Parameters:
  • eventName (str) – The name of the event to be invoked.
  • player (Player or None) – The player to invoke the event on. None can be provided to only invoke a global event. None is still passed to the global event though.
  • args (list) – Arbitrary argument list that the event will be invoked with.
  • kwargs – Keyword arguments that will be packed in results and passed to the event handler.
Returns:

The results that was passed to the event handlers containing the keyword arguments.
Return type:

core.helper.AttrDict

Note

Remember that all handlers need to include results in the signature!

accuracy_check(player, attacker, target, accuracy=accuracy, evasion=evasion)

Called to support accuracy and evasion being manipulated before the accuracy is fully calculated.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity being targeted for this attack.
  • accuracy (int) – The attacker’s accuracy stat.
  • evasion (int) – The target’s evasion stat.
apply_damage(player, target, origin, damage=damage, isCritical=isCritical, knockback=knockback)

Called when damage is about to be applied to an entity.

Parameters:
  • player (Player) – Provided if the target is a player otherwise None
  • target (Entity) – The entity that will take damage.
  • origin (Vector) – The positional origin of the attack.
  • damage (int) – The amount of damage that will be taken.
  • isCritical (bool) – Whether the damage is considered a critical hit or not.
Param int knockback:
 

The amount of knockback the attack has.
can_hit_tile(player, tileComponent, tilePosition, canHit=canHit)

Called when checking to see if a player can hit a tile.

Parameters:
  • player (Player) – The player trying to hit a tile.
  • tileComponent (TileComponent) – The TileComponent of the tile.
  • tilePosition (TileVector) – The position of the tile.
  • canHit (bool) – Whether the tile can be hit or not.
completed_dungeon(player, dungeon)

Called when a player has completed exploring through an entire dungeon.

Parameters:
  • player (Player) – The player whom completed the dungeon.
  • dungeon (core.dungeon.Dungeon) – The completed dungeon.
craft_adjust_catalyst(player, chaosCraft, amount=amount)

Called when the catalyst amount is being modified during chaos crafting.

Parameters:
  • player (Player) – The player performing the chaos crafting.
  • chaosCraft (core.ui.craft.ChaosCraft) – The container of all chaos crafting data.
  • amount (int) – The amount the catalysts will be changed by.
craft_adjust_chaos(player, chaosCraft, amount=amount)

Called when the chaos amount is being modified during chaos crafting.

Parameters:
  • player (Player) – The player performing the chaos crafting.
  • chaosCraft (core.ui.craft.ChaosCraft) – The container of all chaos crafting data.
  • amount (int) – The amount the chaos will be changed by.
craft_adjust_quality(player, chaosCraft, amount=amount)

Called when the quality amount is being modified during chaos crafting.

Parameters:
  • player (Player) – The player performing the chaos crafting.
  • chaosCraft (core.ui.craft.ChaosCraft) – The container of all chaos crafting data.
  • amount (int) – The amount the quality will be changed by.
craft_finish(player, craft, quantity, result, item, remainder)

Called when a player finishes crafting an item.

Parameters:
  • player (Player) – The player crafting the item.
  • craft (CraftComponent) – The craft component from the crafted item.
  • quantity (int) – The quantity of the crafted item.
  • result (CraftResult) – The CraftResult used for the crafted item.
  • item (InventoryItem) – The crafted item.
  • remainder (int) – The quantity of the item that could not fit into the player’s inventory.
craft_quality(player, craft, quality=quality, maxQuality=maxQuality)

Called to support quality and max quality of crafting items to be manipulated.

Parameters:
  • player (Player) – The player crafting the item.
  • craft (CraftComponent) – The craft component of the item being crafted.
  • quality (int) – The initial calculated quality.
  • maxQuality (int) – The maximum value the quality can be. This defaults to 0.
craft_start(player, craft, quantity, materials)

Called when starting to craft an item.

Parameters:
  • player (Player) – The player crafting the item.
  • craft (CraftComponent) – The craft component of the item being crafted.
  • quantity (int) – The quantity of the crafted item.
  • materials (list of InventoryItem) – The materials being used to craft the item.
deal_critical_damage(player, attacker, target, data, isCritical=isCritical, criticalFactor=criticalFactor)

Called when calculating if an attack should be critical or not.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity being targeted for this attack.
  • data (core.combat.AttackData) – The data used for the attack.
  • isCritical (bool) – Whether the attack should be critical or not.
  • criticalFactor – The multiplier used on the damage if the attack ends up being critical.
deal_damage_end(player, attacker, target, data, isCritical, damage)

Called at the end of calculations when the attacker about to deal damage to the target.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity being targeted for this attack.
  • data (core.combat.AttackData) – The data used for the attack.
  • isCritical (bool) – Whether the attack should be critical or not.
  • damage (int) – The amount of damage that will be dealt.
deal_damage_start(player, attacker, target, data)

Called at the start of calculations when the attacker about to deal damage to the target.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity being targeted for this attack.
  • data (core.combat.AttackData) – The data used for the attack.
deal_damage(player, attacker, target, data, isCritical, damage=damage)

Called towards the end of calculations when the attacker about to deal damage to the target. This supports the amount of damage being changed.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity being targeted for this attack.
  • data (core.combat.AttackData) – The data used for the attack.
  • isCritical (bool) – Whether the attack should be critical or not.
  • damage (int) – The amount of damage that will be dealt.
descent_damage(player, damage=damage)

Called when a player will take fall damage.

Parameters:
  • player (Player) – The player taking damage.
  • damage (int) – The amount of damage the player will take.
done_casting(player, talent, skillTuning, cost=cost)

Called when a player finishes casting a skill.

Parameters:
  • player (Player) – The player casting a skill.
  • talent (Talent) – The talent the spell is from.
  • skillTuning (core.helper.AttrDict) – The tuning data for the skill (See core.tuning.skill).
  • cost (int) – The stamina that will be consumed from the skill.
drop_rate_modifier(player, entity, modifier=modifier)

Called when calculating the drop rate modifier for a defeated enemy.

Parameters:
  • player – Always None.
  • entity (Entity) – The defeated enemy.
  • modifier (float) – The drop rate modifier - 1.0 is 100%.
enter_dungeon(player, dungeon)

Called when a player has entered a dungeon.

Parameters:
  • player (Player) – The player who entered the dungeon.
  • dungeon (core.dungeon.Dungeon) – The dungeon the player entered.
exit_dungeon(player, dungeon)

Called when a dungeon is exited regardless of how.

Parameters:
  • player (Player) – The player who exited the dungeon.
  • dungeon (core.dungeon.Dungeon) – The dungeon the player exited.
gain_tp(player, talent, amount=amount)

Called when a player will gain talent points.

Parameters:
  • player (Player) – The player gaining the talent points.
  • talent (Talent) – The talent the points will be gained for.
  • amount (int) – The amount of talent points that will be gained.
gain_xp(player, amount=amount)

Called when a player will gain experience points.

Parameters:
  • player (Player) – The player gaining the experience points.
  • amount (int) – The amount of experience points that will be gained.
get_research_level(player, craftLevel, bonus=bonus)

Called when calculating the player’s current research level.

Parameters:
  • player (Player) – The player the research level is being calculated for.
  • craftLevel (int) – The player’s craft Talent level.
  • bonus (int) – The bonus levels that should be added to the research level.
harvest_power(player, toolComponent, power=power)

Called when calculating the player’s harvest power.

Parameters:
  • player (Player) – The player we’re calculating the harvest power for.
  • toolComponent (ToolComponent) – The component for the tool the player is using.
  • power (int) – The amount of harvest power.
heal_entity(player, user, target, amount=amount)

Called when an entity is about to be healed.

Parameters:
  • player (Player) – Provided if the target is a player otherwise None
  • user (Entity) – The user who is healing the target.
  • target (Entity) – The entity that will be healed.
  • amount (int) – The amount the target will be healed for.
get_hunter_level(player, skillTuning, level=level)

Called to support changing the hunter skill level (Ore Hunter or Treasure Hunter).

Parameters:
  • player (Player) – The player who is using the hunter skill.
  • skillTuning (core.helper.AttrDict) – The tuning data for the skill (See core.tuning.skill).
  • level (int) – The final hunter level that will determine which ore or treasure to reveal.
kill_entity(player, attacker, target, data, damage, isCritical)

Called when an entity is killed by an attack.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity that was killed.
  • data (core.combat.AttackData) – The data used for the attack.
  • damage (int) – The amount of damage that will be dealt.
  • isCritical (bool) – Whether the attack should be critical or not.
npc_price(player, npc, price=price)

Called when calculating the price of an item an npc is selling.

Parameters:
  • player (Player) – The player the item price is being calculated for.
  • npc (str) – The content name (‘merchant’) of the NPC.
  • price (int) – The price of the item being determined.
on_block(player, attacker, target, shieldProficiency, reduction=reduction, threshold=threshold, staminaCost=staminaCost)

Called when an entity blocks an attack.

Parameters:
  • player (Player) – Provided if attacker is a player otherwise None.
  • attacker (Entity) – The entity performing the attack.
  • target (Entity) – The entity that is being attacked and is blocking.
  • shieldProficiency (int) – The shield proficiency of the blocker.
  • reduction (float) – The modifier used to reduce the damage - 1.0 is 100%.
  • threshold (int) – The maximum amount of damage that can be blocked.
  • staminaCost (int) – The amount of stamina to consume from blocking.
on_jump(player, jumpSpeed=jumpSpeed)

Called when a player jumps.

Parameters:
  • player (Player) – The player that is jumping.
  • jumpSpeed (float) – The speed at which the player is jumping.
on_land(player)

Called when the player lands on the ground.

Parameters:player (Player) – The player landing on the ground.
on_roll(player, cost=cost)

Called when a player performs a dodge roll.

Parameters:
  • player (Player) – The player that is dodge rolling.
  • cost (int) – The amount of stamina to consume from dodge rolling.
on_sp_recovery(player, time=time)

Called when a player stamina recovery timer will be reset. Upon expiration the player will begin recovering stamina.

Parameters:
  • player (Player) – The player that will begin recovering stamina.
  • time (int) – The amount of time (ms) until the player will begin recovering stamina.
ore_drop(player, droppedPosition=droppedPosition, scavengeLevel=scavengeLevel)

Called when a player has destroyed an ore tile using a tool.

Parameters:
  • player (Player) – The player that destroyed the ore tile.
  • position (Vector) – The position of the dropped item which is the center of the destroyed tile.
  • scavengeLevel (int) – The level of the player’s Scavenge skill.
player_death(player, damageSource, message=message)

Called when a player is killed.

Parameters:
  • player (Player) – The dead player.
  • damageSource (core.util.DamageSource) – The source of the damage that killed the player.
  • message (str) – The message that will be displayed.
research_item_scraps(player, content, scrapAmount=scrapAmount)

Called when the player researches an item using scraps.

Parameters:
  • player (Player) – The player doing the researching.
  • content (Content) – The content of the item that is being researched.
  • scrapAmount (int) – The number of scraps that will be consumed.
research_recipe(player, content)

Called when a new recipe has been learned through researching.

Parameters:
  • player (Player) – The player doing the researching.
  • content (Content) – The content of the recipe that was researched.
skill_interrupt(player, skillTuning, interrupt=interrupt)

Called when the player skill casting will be interrupted.

Parameters:
  • player (Player) – The player casting the skill.
  • skillTuning (core.helper.AttrDict) – The tuning data for the skill (See core.tuning.skill).
  • interrupt (bool) – Whether the skill should be interrupted or not. Defaults to True.
start_chaos_craft(player, item, maxCatalysts=maxCatalysts, skills=skills, passives=passives)

Called when a player starts chaos crafting.

Parameters:
  • player (Player) – The player performing chaos crafting.
  • item (InventoryItem) – The item that is being crafted.
  • maxCatalysts (int) – The maximum number of catalysts that can be used.
  • skills (list of core.talent.craft.CraftSkill) – List of chaos skills that will be available to the player during this chaos crafting.
  • passives (list of core.template.surface.CraftSupportAttribute) – List of passives that are active during this chaos crafting.
tool_power(player, toolComponent, power=power)

Called when calculating a tool’s power.

Parameters:
  • player (Player) – The player we’re calculating the tool power for.
  • toolComponent (ToolComponent) – The component for the tool the player is using.
  • power (int) – The tool’s power.
translate_scroll(player, content)

Called when the player translates a recipe scroll.

Parameters:
  • player (Player) – The player translating the scroll.
  • content (Content) – The content of the scroll that is being translated.
travel_cost(player, travelPlayer, travelCrystal, cost=cost)

Called when calculating the Way Shard cost to travel to a Way Crystal.

Parameters:
  • player (Player) – The player we are calculating the cost for.
  • travelPlayer (core.system.travel.TravelPlayer) – The TravelPlayer that belongs to the player activating the crystal.
  • travelCrystal (core.system.travel.TravelCrystal) – The TravelCrystal that the cost is being calculated for.
  • cost (int) – The Way Shard cost being calculated to travel to the Way Crystal.

Entity Events

Below is a list of entity events that are triggered if supported.

can_collect(player, canCollect)

When provided this will allow a placed item to provide logic on when it can or cannot be collected.

Parameters:
  • player (Player) – The player that is attempting to collect the item.
  • canCollect (EventResult) – Stores whether the item can be collected or not using canCollect.result.
can_place_item(player, entity, item, canPerform)

When provided this checks to see if an item can be place in or on an entity.

Parameters:
  • player (Player) – The player attempting to place the item.
  • entity (Entity) – The entity the player is attempting to place the item on.
  • item (ToolItem) – The item the player is attempting to place. This is always an item and can be treated as an InventoryItem.
  • canPerform (EventResult) – Stores whether the item can be placed or not using canPerform.result.
can_remove_support(entity, realm, tileLayer, tilePosition, shouldCancel)

When provided this will be called when an attempt to remove a tile is made nearby the entity.

Parameters:
  • entity (Entity) – The entity that is nearby the tile.
  • realm (Realm) – The realm the entity and tile are in.
  • tileLayer (TileLayer) – The layer the tile is being removed from.
  • tilePosition (TileVector) – The position of the tile being removed.
  • shouldCancel (EventResult) – Whether we should cancel the removal or not.
close(player, entity)

Called when an entity with inventory is closed such as a player closing a treasure chest.

Parameters:
  • player (Player) – The player that is closing the inventory.
  • entity (Entity) – The entity the inventory belongs to.
clothe(player, entity, position)

Called when an NPC outfit is being placed onto a mannequin.

Parameters:
  • player (Player) – The player clothing the mannequin.
  • entity (Entity) – The mannequin that the outfit is being placed on.
  • position (Vector) – The cursor position where the player clicked.
collect(player, entity, position)

Called when a player attempts to collect an item. This is for special cases such as removing individual crafting station attachments.

Parameters:
  • player (Player) – The player collecting the item.
  • entity (Entity) – The entity the player is collecting.
  • position (Vector) – The cursor position where the player clicked.
interact(player, entity, position)

Called when a player interacts with an entity.

Parameters:
  • player (Player) – The player interacting with the entity.
  • entity (Entity) – The entity the player is interacting with.
  • position (Vector) – The cursor position where the player clicked.
place_item(player, entity, position)

Called when a player places an item in or on an entity. Use player.grabbed.item (ToolItem) for the item being placed.

Parameters:
  • player (Player) – The player placing the item.
  • entity (Entity) – The entity the player is placing the item on.
  • position (Vector) – The cursor position where the player clicked.
remove_support(entity, realm, tileLayer, tilePosition, forced, shouldCancel)

Called when the player is about to remove a tile that the entity is using as support.

Parameters:
  • entity (Entity) – The entity that is nearby the tile.
  • realm (Realm) – The realm the entity and tile are in.
  • tileLayer (TileLayer) – The layer the tile is being removed from.
  • tilePosition (TileVector) – The position of the tile being removed.
  • forced (bool) – Whether the tile is being forcefully removed.
  • shouldCancel (EventResult) – Whether we should cancel the removal or not. This is ignored if the removal is forced.
use_gadget(player, realm, entity, position)

Called when a player uses a gadget.

Parameters:
  • player (Player) – The player using the gadget.
  • realm (Realm) – The realm that the player is in.
  • entity (Entity) – The entity of the gadget being used.
  • position (Vector) – The cursor position where the player clicked.

Player Events

Below is a list of events that are directly called on the player’s EventComponent.

cast_spell(spellTuning)

Called when the player casts a spell.

Parameters:spellTuning (core.helper.AttrDict) – The tuning data for the spell (See core.tuning.skill).
claim_imbue_output(item)

Called when the player claims the output item from an imbuing chamber.

Parameters:item (InventoryItem) – The output item.
completed_horde_realm(realm)

Called when the player completes a horde realm.

Parameters:realm (Realm) – The horde realm that the player completed.
deal_damage_invisible(target, data, isCritical, damage)

Called when the player deals damage to a target while invisible.

Parameters:
  • target (Entity) – The target of the player’s attack.
  • data (core.combat.AttackData) – The data used for the attack.
  • isCritical (bool) – Whether the attack should be critical or not.
  • damage (int) – The amount of damage that will be dealt.
equip_craft_station(entity, unequippedItem, item)

Called when the player equip an item on a crafting station.

Parameters:
  • entity (Entity) – The crafting station entity that is being equipped.
  • unequippedItem (InventoryItem) – The item that was unequipped from the crafting station. This will be empty if no item was equipped in the slot.
  • item (GrabbedItem) – The item being equipped to the crafting station.
expertise_level(level)

Called when the player’s Expertise skill level is changed.

:param int level The current Expertise level.

grabbed_enemy(player, hook, grapplerData, enemies)

Called when the player grabs an entity with a grappling hook.

Parameters:
  • player (Player) – The player grabbing the entity.
  • hook (Entity) – The entity of the grappling hook that is being shot out.
  • grapplerData (core.helper.AttrDict) – Container of all the grappler data. See core.template.grappler.Grappler for more details.
  • enemies (List of Entity) – The entities that were grabbed.
realm_change(player, previousRealm, realm)

Called when the player traveling to another realm.

Parameters:
  • player (Player) – The player traveling to another realm.
  • previousRealm (Realm) – The realm the player is traveling from.
  • realm (Realm) – The realm the player is traveling to.
use_delay(itemEntity, delay)

Called when the player uses an item and the player’s use delay timer is about to be set.

Parameters:
  • itemEntity (Entity) – The entity of the item being used.
  • delay (EventArg) – The amount of time the use delay timer will be set to.
used_item(itemEntity, quantity)

Called when the player uses an item.

Parameters:
  • itemEntity (Entity) – The entity of the item being used.
  • quantity (int) – The current quantity of the item that is being used.

Equipment Events

Below is a list of events that are called on pieces of equipment. All equipment attributes can be found in core.item.armor.attribute module.

charged(player, itemEntity, equipmentSlot, clientInput, inputType, position)

Called on the item with a ChargedAttackAttribute when it is being charged.

Parameters:
  • player (Player) – The player charging the item.
  • itemEntity (Entity) – The entity of the item being used.
  • equipmentSlot (str) – The equipment slot the item is in.
  • clientInput (core.system.input.ClientInput) – The input for the player.
  • inputType (core.util.InputTypes) – The type of input used.
  • position (Vector) – The cursor position of the player.
final_combo(player, itemEntity)

Called on the item when it performs the last attack in its attack combo.

Parameters:
  • player (Player) – The player using the item.
  • itemEntity (Entity) – The entity of the item being used.
hit_ally(player, target, itemEntity, entity)

Called when a wand projectile hits an ally.

Parameters:
  • player (Player) – The player using the item.
  • target (Entity) – The ally that was hit.
  • itemEntity (Entity) – The entity of the item being used.
  • entity (Entity) – The entity of the wand projectile.
post_weapon_use(player, itemEntity)

Called after a weapon is used.

Parameters:
  • player (Player) – The player using the item.
  • itemEntity (Entity) – The entity of the weapon used.
projectile_fired(entity)

Called when a projectile is fired from a bow or wand.

Parameters:entity (Entity) – The entity of the projectile shot.