[11776] Add documention for CreatureAI API

Signed-off-by: VladimirMangos <vladimir@getmangos.com>

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
+         * Called when the creature is killed
-        // for attack reaction use AttackedBy called for not DOT damage in Unit::DealDamage also
+         * @param pKiller Unit* who killed the creature
-        virtual void DamageTaken(Unit * /*done_by*/, uint32 & /*damage*/) {}
+         */
+        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.
+         * Called when creature attack expected (if creature can and no have current victim)
-        virtual void AttackStart(Unit *) {}
+         * 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; }
+         * Check if unit is visible for MoveInLineOfSight
-
+         * Note: This check is by default only the state-depending (visibility, range), NOT LineOfSight
-        // called when the corpse of this creature gets removed
+         * @param pWho Unit* who is checked if it is visisble for the creature
-        virtual void CorpseRemoved(uint32 & /*respawnDelay*/) {}
+         */
+        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<CreatureAI>, public Permissible<Creature>
 {
-
     SelectableAI(const char *id) : FactoryHolder<CreatureAI>(id) {}
 };
 
@@ -198,4 +298,5 @@ enum Permitions
 typedef FactoryHolder<CreatureAI> CreatureAICreator;
 typedef FactoryHolder<CreatureAI>::FactoryHolderRegistry CreatureAIRegistry;
 typedef FactoryHolder<CreatureAI>::FactoryHolderRepository CreatureAIRepository;
+
 #endif

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__