diff --git a/src/game/CreatureAI.h b/src/game/CreatureAI.h index 2a49d501d..251696f76 100644 --- a/src/game/CreatureAI.h +++ b/src/game/CreatureAI.h @@ -67,111 +67,211 @@ class MANGOS_DLL_SPEC CreatureAI virtual ~CreatureAI(); ///== Information about AI ======================== - virtual void GetAIInformation(ChatHandler& /*reader*/) {} + /** + * This funcion is used to display information about the AI. + * It is called when the .npc aiinfo command is used. + * Use this for on-the-fly debugging + * @param reader is a ChatHandler to send messages to. + */ + virtual void GetAIInformation(ChatHandler& reader) {} ///== Reactions At ================================= - // Called if IsVisible(Unit *who) is true at each *who move, reaction at visibility zone enter - virtual void MoveInLineOfSight(Unit *) {} + /** + * Called if IsVisible(Unit* pWho) is true at each (relative) pWho move, reaction at visibility zone enter + * Note: The Unit* pWho can be out of Line of Sight, usually this is only visibiliy (by state) and range dependendend + * Note: This function is not called for creatures who are in evade mode + * @param pWho Unit* who moved in the visibility range and is visisble + */ + virtual void MoveInLineOfSight(Unit* pWho) {} - // Called for reaction at enter to combat if not in combat yet (enemy can be NULL) - virtual void EnterCombat(Unit* /*enemy*/) {} + /** + * Called for reaction at enter to combat if not in combat yet + * @param pEnemy Unit* of whom the Creature enters combat with, can be NULL + */ + virtual void EnterCombat(Unit* pEnemy) {} - // Called for reaction at stopping attack at no attackers or targets + /** + * Called for reaction at stopping attack at no attackers or targets + * This is called usually in Unit::SelectHostileTarget, if no more target exists + */ virtual void EnterEvadeMode() {} - // Called at reaching home after evade + /** + * Called at reaching home after MoveTargetHome + */ virtual void JustReachedHome() {} // Called at any heal cast/item used (call non implemented) - virtual void HealBy(Unit * /*healer*/, uint32 /*amount_healed*/) {} + // virtual void HealBy(Unit * /*healer*/, uint32 /*amount_healed*/) {} - // Helper functions for cast spell - virtual CanCastResult CanCastSpell(Unit* pTarget, const SpellEntry *pSpell, bool isTriggered); + /** + * Called at any Damage to any victim (before damage apply) + * @param pDoneTo Unit* to whom Damage of amount uiDamage will be dealt + * @param uiDamage Amount of Damage that will be dealt, can be changed here + */ + virtual void DamageDeal(Unit* pDoneTo, uint32& uiDamage) {} - // Called at any Damage to any victim (before damage apply) - virtual void DamageDeal(Unit * /*done_to*/, uint32 & /*damage*/) {} + /** + * Called at any Damage from any attacker (before damage apply) + * Note: Use for recalculation damage or special reaction at damage + * for attack reaction use AttackedBy called for not DOT damage in Unit::DealDamage also + * @param pDealer Unit* who will deal Damage to the creature + * @param uiDamage Amount of Damage that will be dealt, can be changed here + */ + virtual void DamageTaken(Unit* pDealer, uint32& uiDamage) {} - // Called at any Damage from any attacker (before damage apply) - // Note: it for recalculation damage or special reaction at damage - // for attack reaction use AttackedBy called for not DOT damage in Unit::DealDamage also - virtual void DamageTaken(Unit * /*done_by*/, uint32 & /*damage*/) {} + /** + * Called when the creature is killed + * @param pKiller Unit* who killed the creature + */ + virtual void JustDied(Unit* pKiller) {} - // Called when the creature is killed - virtual void JustDied(Unit *) {} + /** + * Called when the corpse of this creature gets removed + * @param uiRespawnDelay Delay (in seconds). If != 0, then this is the time after which the creature will respawn, if = 0 the default respawn-delay will be used + */ + virtual void CorpseRemoved(uint32& uiRespawnDelay) {} - // Called when the creature summon is killed - virtual void SummonedCreatureJustDied(Creature* /*unit*/) {} + /** + * Called when a summoned creature is killed + * @param pSummoned Summoned Creature* that got killed + */ + virtual void SummonedCreatureJustDied(Creature* pSummoned) {} - // Called when the creature kills a unit - virtual void KilledUnit(Unit *) {} + /** + * Called when the creature kills a unit + * @param pVictim Victim that got killed + */ + virtual void KilledUnit(Unit* pVictim) {} - // Called when owner of m_creature (if m_creature is PROTECTOR_PET) kills a unit - virtual void OwnerKilledUnit(Unit *) {} + /** + * Called when owner of m_creature (if m_creature is PROTECTOR_PET) kills a unit + * @param pVictim Victim that got killed (by owner of creature) + */ + virtual void OwnerKilledUnit(Unit* pVictim) {} - // Called when the creature summon successfully other creature - virtual void JustSummoned(Creature* ) {} + /** + * Called when the creature summon successfully other creature + * @param pSummoned Creature that got summoned + */ + virtual void JustSummoned(Creature* pSummoned) {} - // Called when the creature summon successfully a gameobject - virtual void JustSummoned(GameObject* ) {} + /** + * Called when the creature summon successfully a gameobject + * @param pGo GameObject that was summoned + */ + virtual void JustSummoned(GameObject* pGo) {} - // Called when the creature summon despawn - virtual void SummonedCreatureDespawn(Creature* /*unit*/) {} + /** + * Called when a summoned creature gets TemporarySummon::UnSummon ed + * @param pSummoned Summoned creature that despawned + */ + virtual void SummonedCreatureDespawn(Creature* pSummoned) {} - // Called when hit by a spell - virtual void SpellHit(Unit*, const SpellEntry*) {} + /** + * Called when hit by a spell + * @param pCaster Caster who casted the spell + * @param pSpell The spell that hit the creature + */ + virtual void SpellHit(Unit* pCaster, const SpellEntry* pSpell) {} - // Called when spell hits creature's target - virtual void SpellHitTarget(Unit*, const SpellEntry*) {} + /** + * Called when spell hits creature's target + * @param pTarget Target that we hit with the spell + * @param pSpell Spell with which we hit pTarget + */ + virtual void SpellHitTarget(Unit* pTarget, const SpellEntry* pSpell) {} - // Called when the creature is target of hostile action: swing, hostile spell landed, fear/etc) - virtual void AttackedBy(Unit* attacker); + /** + * Called when the creature is target of hostile action: swing, hostile spell landed, fear/etc) + * @param pAttacker Unit* who attacked the creature + */ + virtual void AttackedBy(Unit* pAttacker); - // Called when creature is spawned or respawned (for reseting variables) + /** + * Called when creature is respawned (for reseting variables) + */ virtual void JustRespawned() {} - // Called at waypoint reached or point movement finished - virtual void MovementInform(uint32 /*MovementType*/, uint32 /*Data*/) {} + /** + * Called at waypoint reached or point movement finished + * @param uiMovementType Type of the movement (enum MovementGeneratorType) + * @param uiData Data related to the finished movement (ie point-id) + */ + virtual void MovementInform(uint32 uiMovementType, uint32 uiData) {} - // Called if a temporary summoned of m_creature reach a move point - virtual void SummonedMovementInform(Creature* /*summoned*/, uint32 /*motion_type*/, uint32 /*point_id*/) {} + /** + * Called if a temporary summoned of m_creature reach a move point + * @param pSummoned Summoned Creature that finished some movement + * @param uiMotionType Type of the movement (enum MovementGeneratorType) + * @param uiData Data related to the finished movement (ie point-id) + */ + virtual void SummonedMovementInform(Creature* pSummoned, uint32 uiMotionType, uint32 uiData) {} - // Called at text emote receive from player - virtual void ReceiveEmote(Player* /*pPlayer*/, uint32 /*text_emote*/) {} + /** + * Called at text emote receive from player + * @param pPlayer Player* who sent the emote + * @param uiEmote ID of the emote the player used with the creature as target + */ + virtual void ReceiveEmote(Player* pPlayer, uint32 uiEmote) {} ///== Triggered Actions Requested ================== - // Called when creature attack expected (if creature can and no have current victim) - // Note: for reaction at hostile action must be called AttackedBy function. - virtual void AttackStart(Unit *) {} + /** + * Called when creature attack expected (if creature can and no have current victim) + * Note: for reaction at hostile action must be called AttackedBy function. + * Note: Usually called by MoveInLineOfSight, in Unit::SelectHostileTarget or when the AI is forced to attack an enemy + * @param pWho Unit* who is possible target + */ + virtual void AttackStart(Unit* pWho) {} - // Called at World update tick - virtual void UpdateAI(const uint32 /*diff*/) {} + /** + * Called at World update tick, by default every 100ms + * This setting is dependend on CONFIG_UINT32_INTERVAL_MAPUPDATE + * Note: Use this function to handle Timers, Threat-Management and MeleeAttacking + * @param uiDiff Passed time since last call + */ + virtual void UpdateAI(const uint32 uiDiff) {} ///== State checks ================================= - // Is unit visible for MoveInLineOfSight - virtual bool IsVisible(Unit *) const { return false; } - - // called when the corpse of this creature gets removed - virtual void CorpseRemoved(uint32 & /*respawnDelay*/) {} + /** + * Check if unit is visible for MoveInLineOfSight + * Note: This check is by default only the state-depending (visibility, range), NOT LineOfSight + * @param pWho Unit* who is checked if it is visisble for the creature + */ + virtual bool IsVisible(Unit* pWho) const { return false; } // Called when victim entered water and creature can not enter water + // TODO: rather unused virtual bool canReachByRangeAttack(Unit*) { return false; } ///== Helper functions ============================= + + /// This function is used to do the actual melee damage (if possible) bool DoMeleeAttackIfReady(); - CanCastResult DoCastSpellIfCan(Unit* pTarget, uint32 uiSpell, uint32 uiCastFlags = 0, ObjectGuid uiOriginalCasterGUID = ObjectGuid()); + + /// Internal helper function, to check if a spell can be cast + CanCastResult CanCastSpell(Unit* pTarget, const SpellEntry* pSpell, bool isTriggered); + + /** + * Function to cast a spell if possible + * @param pTarget Unit* onto whom the spell should be cast + * @param uiSpell ID of the spell that the creature will try to cast + * @param uiCastFlags Some flags to define how to cast, see enum CastFlags + * @param OriginalCasterGuid the original caster of the spell if required, empty by default + */ + CanCastResult DoCastSpellIfCan(Unit* pTarget, uint32 uiSpell, uint32 uiCastFlags = 0, ObjectGuid OriginalCasterGuid = ObjectGuid()); ///== Fields ======================================= - // Pointer to controlled by AI creature + /// Pointer to the Creature controlled by this AI Creature* const m_creature; }; struct SelectableAI : public FactoryHolder, public Permissible { - SelectableAI(const char *id) : FactoryHolder(id) {} }; @@ -198,4 +298,5 @@ enum Permitions typedef FactoryHolder CreatureAICreator; typedef FactoryHolder::FactoryHolderRegistry CreatureAIRegistry; typedef FactoryHolder::FactoryHolderRepository CreatureAIRepository; + #endif diff --git a/src/shared/revision_nr.h b/src/shared/revision_nr.h index c848c1261..095fa69f3 100644 --- a/src/shared/revision_nr.h +++ b/src/shared/revision_nr.h @@ -1,4 +1,4 @@ #ifndef __REVISION_NR_H__ #define __REVISION_NR_H__ - #define REVISION_NR "11775" + #define REVISION_NR "11776" #endif // __REVISION_NR_H__