Skip to content

Commit

Permalink
docs(Core): improve several functions documentation (#19677)
Browse files Browse the repository at this point in the history 
* initial release

* fix reviews

* fix some typo and add new documetations for MotionMaster

* new update and fix the cli-codestyle

* fix typo

* fix reviews
  • Loading branch information
@Grimdhex
Grimdhex committed Aug 28, 2024
1 parent f2e1a97 commit 2f85097
Show file tree
Hide file tree
Showing 7 changed files with 193 additions and 89 deletions.
3 changes: 3 additions & 0 deletions src/server/game/AI/CoreAI/UnitAI.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,9 @@ SpellCastResult UnitAI::DoCastAOE(uint32 spellId, bool triggered)
return me->CastSpell((Unit*)nullptr, spellId, triggered);
}

/**
* @brief Cast the spell on a random unit from the threat list
*/
SpellCastResult UnitAI::DoCastRandomTarget(uint32 spellId, uint32 threatTablePosition, float dist, bool playerOnly, bool triggered, bool withTank)
{
if (Unit* target = SelectTarget(SelectTargetMethod::Random, threatTablePosition, dist, playerOnly, withTank))
Expand Down
52 changes: 27 additions & 25 deletions src/server/game/AI/CoreAI/UnitAI.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,14 +198,14 @@ class UnitAI
virtual ~UnitAI() {}

virtual bool CanAIAttack(Unit const* /*target*/) const { return true; }
virtual void AttackStart(Unit* /*target*/);
virtual void AttackStart(Unit* /*target*/); /// @brief Use to start attacking a target. Called just before JustEngagedWith()
virtual void UpdateAI(uint32 /*diff*/) = 0;

virtual void InitializeAI() { if (!me->isDead()) Reset(); }

virtual void Reset() {};

// Called when unit is charmed
/// @brief Called when unit is charmed
virtual void OnCharmed(bool apply) = 0;

// Pass parameters between AI
Expand Down Expand Up @@ -258,16 +258,16 @@ class UnitAI
}
}

// Select the best (up to) <num> targets (in <targetType> order) from the threat list that fulfill the following:
// - Not among the first <offset> entries in <targetType> order (or SelectTargetMethod::MaxThreat order,
// if <targetType> is SelectTargetMethod::Random).
// - Within at most <dist> yards (if dist > 0.0f)
// - At least -<dist> yards away (if dist < 0.0f)
// - Is a player (if playerOnly = true)
// - Not the current tank (if withTank = false)
// - Has aura with ID <aura> (if aura > 0)
// - Does not have aura with ID -<aura> (if aura < 0)
// The resulting targets are stored in <targetList> (which is cleared first).
/** @brief Select the best (up to) <num> targets (in <targetType> order) from the threat list that fulfill the following:
* - Not among the first <offset> entries in <targetType> order (or SelectTargetMethod::MaxThreat order, if <targetType> is SelectTargetMethod::Random).
* - Within at most <dist> yards (if dist > 0.0f)
* - At least -<dist> yards away (if dist < 0.0f)
* - Is a player (if playerOnly = true)
* - Not the current tank (if withTank = false)
* - Has aura with ID <aura> (if aura > 0)
* - Does not have aura with ID -<aura> (if aura < 0)
* The resulting targets are stored in <targetList> (which is cleared first).
*/
void SelectTargetList(std::list<Unit*>& targetList, uint32 num, SelectTargetMethod targetType, uint32 position = 0, float dist = 0.0f, bool playerOnly = false, bool withTank = true, int32 aura = 0);

// Select the best (up to) <num> targets (in <targetType> order) satisfying <predicate> from the threat list and stores them in <targetList> (which is cleared first).
Expand Down Expand Up @@ -345,7 +345,7 @@ class UnitAI

/**
* @brief Called when the unit enters combat
* (NOTE: Creature engage logic should NOT be here, but in JustEngagedWith, which happens once threat is established!)
* @note NOTE: Creature engage logic should NOT be here, but in JustEngagedWith, which happens once threat is established!)
*
* @todo Never invoked right now. Preparation for Combat Threat refactor
*/
Expand All @@ -358,42 +358,44 @@ class UnitAI
*/
virtual void JustExitedCombat() { }

// Called at any Damage to any victim (before damage apply)
/// @brief Called at any Damage to any victim (before damage apply)
virtual void DamageDealt(Unit* /*victim*/, uint32& /*damage*/, DamageEffectType /*damageType*/) { }

// 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
/** @brief Called at any Damage from any attacker (before damage apply)
*
* @note It use for recalculation damage or special reaction at damage
* for attack reaction use AttackedBy called for non DOT damage in Unit::DealDamage also
*/
virtual void DamageTaken(Unit* /*attacker*/, uint32& /*damage*/, DamageEffectType /*damagetype*/, SpellSchoolMask /*damageSchoolMask*/) {}

// Called when the creature receives heal
/// @brief Called when the creature receives heal
virtual void HealReceived(Unit* /*done_by*/, uint32& /*addhealth*/) {}

// Called when the creature power updates
/// @brief Called when the creature power updates
virtual void OnPowerUpdate(Powers /*power*/, int32 /*updateVal*/, int32 /*gain*/, uint32 /*currPower*/) {}

// Called when the unit heals
/// @brief Called when the unit heals
virtual void HealDone(Unit* /*done_to*/, uint32& /*addhealth*/) {}

// Called during damage calculations
/// @brief Called during damage calculations
virtual void OnCalculateMeleeDamageReceived(uint32& /*damage*/, Unit* /*attacker*/) {}
virtual void OnCalculateSpellDamageReceived(int32& /*damage*/, Unit* /*attacker*/) {}

// Called during calculation when receiving periodic healing or damage (DoT or HoT)
/// @brief Called during calculation when receiving periodic healing or damage (DoT or HoT)
virtual void OnCalculatePeriodicTickReceived(uint32& /*damage*/, Unit* /*attacker*/) {}

void AttackStartCaster(Unit* victim, float dist);

SpellCastResult DoAddAuraToAllHostilePlayers(uint32 spellid);
SpellCastResult DoCast(uint32 spellId);
SpellCastResult DoCast(Unit* victim, uint32 spellId, bool triggered = false);
SpellCastResult DoCastSelf(uint32 spellId, bool triggered = false) { return DoCast(me, spellId, triggered); }
SpellCastResult DoCastSelf(uint32 spellId, bool triggered = false) { return DoCast(me, spellId, triggered); } /// @brief To specify the caster as target if the spell is self-cast
SpellCastResult DoCastToAllHostilePlayers(uint32 spellid, bool triggered = false);
SpellCastResult DoCastVictim(uint32 spellId, bool triggered = false);
SpellCastResult DoCastAOE(uint32 spellId, bool triggered = false);
SpellCastResult DoCastRandomTarget(uint32 spellId, uint32 threatTablePosition = 0, float dist = 0.0f, bool playerOnly = true, bool triggered = false, bool withTank = true);

// Cast spell on the top threat target, which may not be the current victim.
/// @brief Cast spell on the top threat target, which may not be the current victim.
SpellCastResult DoCastMaxThreat(uint32 spellId, uint32 threatTablePosition = 0, float dist = 0.0f, bool playerOnly = true, bool triggered = false);

float DoGetSpellMaxRange(uint32 spellId, bool positive = false);
Expand All @@ -405,7 +407,7 @@ class UnitAI
static AISpellInfoType* AISpellInfo;
static void FillAISpellInfo();

// Called when a summon reaches a waypoint or point movement finished.
/// @brief Called when a summon reaches a waypoint or point movement finished.
virtual void SummonMovementInform(Creature* /*creature*/, uint32 /*motionType*/, uint32 /*point*/) { }

virtual void sGossipHello(Player* /*player*/) {}
Expand Down
60 changes: 40 additions & 20 deletions src/server/game/Entities/Creature/Creature.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1945,11 +1945,21 @@ bool Creature::CanStartAttack(Unit const* who) const
return IsWithinLOSInMap(who);
}

void Creature::setDeathState(DeathState s, bool despawn)
/**
* @brief A creature can be in 4 different states: Alive, JustDied, Corpse, and JustRespawned. The cycle follows the next order:
* - Alive: The creature is alive and has spawned in the world
* - JustDied: The creature has just died. This is the state just before his body appeared
* - Corpse: The creature has been removed from the world, and this corpse has been spawned
* - JustRespawned: The creature has just respawned. Follow when the corpse disappears and the respawn timer is finished
*
* @param state Specify one of 4 states above
* @param despawn Despawn the creature immediately, without waiting for any movement to finish
*/
void Creature::setDeathState(DeathState state, bool despawn)
{
Unit::setDeathState(s, despawn);
Unit::setDeathState(state, despawn);

if (s == DeathState::JustDied)
if (state == DeathState::JustDied)
{
_lastDamagedTime.reset();

Expand All @@ -1960,10 +1970,10 @@ void Creature::setDeathState(DeathState s, bool despawn)
if (GetMap()->IsDungeon() || isWorldBoss() || GetCreatureTemplate()->rank >= CREATURE_ELITE_ELITE)
SaveRespawnTime();

SetTarget(); // remove target selection in any cases (can be set at aura remove in Unit::setDeathState)
SetTarget(); // remove target selection in any cases (can be set at aura remove in Unit::setDeathState)
ReplaceAllNpcFlags(UNIT_NPC_FLAG_NONE);

Dismount(); // if creature is mounted on a virtual mount, remove it at death
Dismount(); // if creature is mounted on a virtual mount, remove it at death

setActive(false);

Expand All @@ -1985,10 +1995,8 @@ void Creature::setDeathState(DeathState s, bool despawn)

Unit::setDeathState(DeathState::Corpse, despawn);
}
else if (s == DeathState::JustRespawned)
else if (state == DeathState::JustRespawned)
{
//if (IsPet())
// setActive(true);
SetFullHealth();
SetLootRecipient(nullptr);
ResetPlayerDamageReq();
Expand Down Expand Up @@ -2016,6 +2024,9 @@ void Creature::setDeathState(DeathState s, bool despawn)
}
}

/**
* @param force Force the respawn by killing the creature.
*/
void Creature::Respawn(bool force)
{
if (force)
Expand All @@ -2040,7 +2051,7 @@ void Creature::Respawn(bool force)
}

bool allowed = !IsAIEnabled || AI()->CanRespawn(); // First check if there are any scripts that prevent us respawning
if (!allowed && !force) // Will be rechecked on next Update call
if (!allowed && !force) // Will be rechecked on next Update call
return;

ObjectGuid dbtableHighGuid = ObjectGuid::Create<HighGuid::Unit>(m_creatureData ? m_creatureData->id1 : GetEntry(), m_spawnId);
Expand Down Expand Up @@ -2082,8 +2093,7 @@ void Creature::Respawn(bool force)

setDeathState(DeathState::JustRespawned);

// MDic - Acidmanifesto
// Do not override transform auras
// MDic - Acidmanifesto: Do not override transform auras
if (GetAuraEffectsByType(SPELL_AURA_TRANSFORM).empty())
{
CreatureModel display(GetNativeDisplayId(), GetNativeObjectScale(), 1.0f);
Expand All @@ -2102,7 +2112,7 @@ void Creature::Respawn(bool force)
{
//reset the AI to be sure no dirty or uninitialized values will be used till next tick
AI()->Reset();
TriggerJustRespawned = true;//delay event to next tick so all creatures are created on the map before processing
TriggerJustRespawned = true; //delay event to next tick so all creatures are created on the map before processing
}

uint32 poolid = m_spawnId ? sPoolMgr->IsPartOfAPool<Creature>(m_spawnId) : 0;
Expand All @@ -2120,7 +2130,7 @@ void Creature::Respawn(bool force)
UpdateObjectVisibility(false);

}
else // the master is dead
else // the master is dead
{
ObjectGuid targetGuid = sObjectMgr->GetLinkedRespawnGuid(dbtableHighGuid);
if (targetGuid == dbtableHighGuid) // if linking self, never respawn (check delayed to next day)
Expand Down Expand Up @@ -2148,7 +2158,7 @@ void Creature::ForcedDespawn(uint32 timeMSToDespawn, Seconds forceRespawnTimer)
if (IsAlive())
setDeathState(DeathState::JustDied, true);

// Xinef: set new respawn time, ignore corpse decay time...
// Xinef: Set new respawn time, ignore corpse decay time...
RemoveCorpse(true);

if (forceRespawnTimer > Seconds::zero())
Expand Down Expand Up @@ -2194,8 +2204,6 @@ void Creature::InitializeReactState()
SetReactState(REACT_PASSIVE);
else
SetReactState(REACT_AGGRESSIVE);
/*else if (IsCivilian())
SetReactState(REACT_DEFENSIVE);*/
}

bool Creature::HasMechanicTemplateImmunity(uint32 mask) const
Expand Down Expand Up @@ -2357,8 +2365,7 @@ SpellInfo const* Creature::reachWithSpellCure(Unit* victim)
float range = spellInfo->GetMaxRange(true);
float minrange = spellInfo->GetMinRange(true);
float dist = GetDistance(victim);
//if (!isInFront(victim, range) && spellInfo->AttributesEx)
// continue;

if (dist > range || dist < minrange)
continue;
if (spellInfo->PreventionType == SPELL_PREVENTION_TYPE_SILENCE && HasUnitFlag(UNIT_FLAG_SILENCED))
Expand All @@ -2370,7 +2377,9 @@ SpellInfo const* Creature::reachWithSpellCure(Unit* victim)
return nullptr;
}

// select nearest hostile unit within the given distance (regardless of threat list).
/**
* @brief Select nearest hostile unit within the given distance (regardless of threat list).
*/
Unit* Creature::SelectNearestTarget(float dist, bool playerOnly /* = false */) const
{
if (dist == 0.0f)
Expand All @@ -2386,7 +2395,9 @@ Unit* Creature::SelectNearestTarget(float dist, bool playerOnly /* = false */) c
return target;
}

// select nearest hostile unit within the given attack distance (i.e. distance is ignored if > than ATTACK_DISTANCE), regardless of threat list.
/**
* @brief Select nearest hostile unit within the given attack distance (i.e. distance is ignored if > than ATTACK_DISTANCE), regardless of threat list.
*/
Unit* Creature::SelectNearestTargetInAttackDistance(float dist) const
{
if (dist < ATTACK_DISTANCE)
Expand Down Expand Up @@ -2780,6 +2791,9 @@ void Creature::SendZoneUnderAttackMessage(Player* attacker)
sWorld->SendGlobalMessage(&data, nullptr, (attacker->GetTeamId() == TEAM_ALLIANCE ? TEAM_HORDE : TEAM_ALLIANCE));
}

/**
* @brief Set in combat all units in the dungeon/raid. Affect only units with IsAIEnabled.
*/
void Creature::SetInCombatWithZone()
{
if (IsAIEnabled)
Expand Down Expand Up @@ -3146,6 +3160,9 @@ bool Creature::IsImmuneToKnockback() const
return cinfo && (cinfo->flags_extra & CREATURE_FLAG_EXTRA_IMMUNITY_KNOCKBACK);
}

/**
* @brief Enable or disable the creature's walk mode by removing: MOVEMENTFLAG_WALKING. Infom also the client
*/
bool Creature::SetWalk(bool enable)
{
if (!Unit::SetWalk(enable))
Expand All @@ -3157,6 +3174,9 @@ bool Creature::SetWalk(bool enable)
return true;
}

/**
* @brief Enable or disable the creature's fly mode by adding or removing: MOVEMENTFLAG_FLYING. Infom also the client
*/
bool Creature::SetDisableGravity(bool disable, bool packetOnly /*= false*/, bool updateAnimationTier /*= true*/)
{
//! It's possible only a packet is sent but moveflags are not updated
Expand Down
Loading

0 comments on commit 2f85097

Please sign in to comment.