araxiaonline/docs
3
0
Fork 0
mirror of https://github.com/araxiaonline/docs.git synced 2026-06-13 03:32:31 -04:00
Code Issues Packages Projects Releases Wiki Activity

Added Corpse and new method from generation

Browse Source
This commit is contained in:
Ben Carter
2024-03-08 18:19:24 -05:00
parent 6758ad6294
commit 55fe882c42
4 changed files with 814 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/classes/Aura.md
View File

@@ -548,3 +548,56 @@ Finally, we send a message to the player using `SendBroadcastMessage` to let the
If the aura was applied to someone else, we set the maximum duration of the aura to its normal value of 10 minutes.
## SetStackAmount
Change the stack amount of the aura on the unit. If the `amount` is greater than or equal to the current number of stacks, the aura's duration will be reset to the maximum duration.
### Parameters
- amount: number - The new stack amount for the aura.
### Example Usage
In this example, we'll create a script that increases the stack amount of a specific aura when a player kills a creature. If the stack amount reaches 10 or more, the aura's duration will be reset, and the player will receive a bonus reward.
```typescript
const AURA_ENTRY = 12345;
const BONUS_ITEM_ENTRY = 67890;
const BONUS_ITEM_COUNT = 5;
const OnCreatureKill: creature_event_on_creature_death = (event: number, creature: Creature, killer: Unit): void => {
if (killer instanceof Player) {
const player = killer as Player;
const aura = player.GetAura(AURA_ENTRY);
if (aura) {
const currentStacks = aura.GetStackAmount();
const newStacks = currentStacks + 1;
aura.SetStackAmount(newStacks);
if (newStacks >= 10) {
player.AddItem(BONUS_ITEM_ENTRY, BONUS_ITEM_COUNT);
player.SendBroadcastMessage("Congratulations! You have reached 10 stacks and received a bonus reward!");
}
} else {
player.AddAura(AURA_ENTRY, player);
}
}
};
RegisterCreatureEvent(CreatureEvents.CREATURE_EVENT_ON_CREATURE_DEATH, (...args) => OnCreatureKill(...args));
```
In this script:
1. We define constants for the aura entry, bonus item entry, and bonus item count.
2. When a creature is killed by a player, we check if the killer is a Player instance.
3. We retrieve the specific aura from the player using `GetAura()`.
4. If the aura exists on the player:
- We get the current stack amount using `GetStackAmount()`.
- We calculate the new stack amount by adding 1 to the current stack amount.
- We update the aura's stack amount using `SetStackAmount()`.
- If the new stack amount is greater than or equal to 10:
- We add the bonus item to the player's inventory using `AddItem()`.
- We send a broadcast message to the player informing them of the bonus reward.
5. If the aura doesn't exist on the player, we add the aura to the player using `AddAura()`.
This script encourages players to hunt creatures and rewards them with a bonus item when they reach a certain number of stacks on the specific aura.

270
docs/classes/Corpse.md Normal file
View File

@@ -0,0 +1,270 @@
## GetGhostTime
Returns the time when the player died and spawned this corpse as a ghost.
### Parameters
None
### Returns
ghostTime: number - The time in milliseconds when the player became a ghost and spawned this corpse.
### Example Usage
This example demonstrates how to use the `GetGhostTime()` method to calculate the duration of a player's death and perform actions based on that duration.
```typescript
const LONG_DEATH_THRESHOLD = 5 * 60 * 1000; // 5 minutes in milliseconds
const OnPlayerResurrect: player_event_on_resurrect = (event: number, player: Player): void => {
const corpse = player.GetCorpse();
if (corpse) {
const ghostTime = corpse.GetGhostTime();
const currentTime = GetGameTime();
const deathDuration = currentTime - ghostTime;
if (deathDuration >= LONG_DEATH_THRESHOLD) {
// Player was dead for a long time
player.SendBroadcastMessage("You were dead for a long time. Here's a bonus item!");
player.AddItem(BONUS_ITEM_ENTRY, 1);
} else {
// Player had a short death duration
player.SendBroadcastMessage("You had a quick resurrection. No bonus this time!");
}
// Remove the corpse after resurrection
corpse.RemoveFromWorld(false);
corpse.Delete();
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_RESURRECT, (...args) => OnPlayerResurrect(...args));
```
In this example:
1. We define a constant `LONG_DEATH_THRESHOLD` to represent the duration threshold for considering a death as "long" (e.g., 5 minutes in milliseconds).
2. Inside the `OnPlayerResurrect` event handler, we retrieve the player's corpse using `player.GetCorpse()`.
3. If the corpse exists, we call `corpse.GetGhostTime()` to get the time when the player became a ghost and spawned the corpse.
4. We calculate the duration of the player's death by subtracting the ghost time from the current game time using `GetGameTime()`.
5. We compare the death duration with the `LONG_DEATH_THRESHOLD`:
- If the death duration is greater than or equal to the threshold, we consider it a long death and reward the player with a bonus item using `player.AddItem()`. We also send a broadcast message to the player informing them about the bonus.
- If the death duration is shorter than the threshold, we send a broadcast message to the player indicating that they had a quick resurrection and won't receive a bonus this time.
6. After handling the resurrection logic, we remove the corpse from the world using `corpse.RemoveFromWorld()` and delete it using `corpse.Delete()` to clean up.
7. Finally, we register the `OnPlayerResurrect` event handler using `RegisterPlayerEvent()` to be triggered whenever a player resurrects.
This example showcases how the `GetGhostTime()` method can be used to track the duration of a player's death and perform actions based on that duration, such as rewarding players for long deaths or providing different messages based on the resurrection speed.
## GetOwnerGUID
Returns the GUID (Globally Unique Identifier) of the player who owns the corpse. This method is useful for identifying the owner of a corpse and performing actions based on that information.
### Parameters
This method does not take any parameters.
### Returns
- `number`: The GUID of the player who owns the corpse.
### Example Usage
Here's an example of how to use the `GetOwnerGUID()` method to identify the owner of a corpse and perform actions based on that information:
```typescript
const OnPlayerDeath: player_event_on_death = (event: number, player: Player): void => {
const corpse = player.GetCorpse();
if (corpse) {
const ownerGUID = corpse.GetOwnerGUID();
const owner = GetPlayerByGUID(ownerGUID);
if (owner) {
// Check if the owner is in a specific guild
const guildId = 123; // Replace with the desired guild ID
if (owner.IsInGuild(guildId)) {
// Perform actions for guild members
owner.SendBroadcastMessage("As a guild member, your corpse will be automatically released in 30 seconds.");
owner.ResurrectPlayer(100, false);
corpse.Despawn(30 * 1000); // Despawn the corpse after 30 seconds
} else {
// Perform actions for non-guild members
owner.SendBroadcastMessage("Your corpse will remain at the location of your death. You can retrieve it manually.");
}
}
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_DEATH, OnPlayerDeath);
```
In this example:
1. When a player dies, the `OnPlayerDeath` event is triggered.
2. We retrieve the player's corpse using `player.GetCorpse()`.
3. If the corpse exists, we get the owner's GUID using `corpse.GetOwnerGUID()`.
4. We retrieve the owner player object using `GetPlayerByGUID(ownerGUID)`.
5. If the owner player is found, we check if they belong to a specific guild using `owner.IsInGuild(guildId)`.
- If the owner is a guild member, we send them a broadcast message indicating that their corpse will be automatically released in 30 seconds.
- We then resurrect the player with full health using `owner.ResurrectPlayer(100, false)`.
- Finally, we despawn the corpse after 30 seconds using `corpse.Despawn(30 * 1000)`.
6. If the owner is not a guild member, we send them a different broadcast message indicating that their corpse will remain at the location of their death and they can retrieve it manually.
This example demonstrates how to use the `GetOwnerGUID()` method to identify the owner of a corpse and perform different actions based on whether the owner belongs to a specific guild or not.
## GetType
Returns the type of the corpse. The type can be one of the following:
- `CORPSE_BONES`: The corpse is a skeleton and cannot be resurrected.
- `CORPSE_RESURRECTABLE_PVE`: The corpse can be resurrected and belongs to a player who died in PvE combat.
- `CORPSE_RESURRECTABLE_PVP`: The corpse can be resurrected and belongs to a player who died in PvP combat.
### Parameters
None
### Returns
[CorpseType](../Enums/CorpseType.md): The type of the corpse.
### Example Usage
This example demonstrates how to use the `GetType` method to determine if a player's corpse is resurrectable and display a message accordingly.
```typescript
const OnPlayerDeath: player_event_on_death = (event: number, player: Player, killer: Unit): void => {
const corpse = player.GetCorpse();
if (!corpse) {
return;
}
const corpseType = corpse.GetType();
switch (corpseType) {
case CorpseType.CORPSE_RESURRECTABLE_PVE:
SendMessageToPlayer(player, "Your corpse is resurrectable. You died in PvE combat.");
break;
case CorpseType.CORPSE_RESURRECTABLE_PVP:
SendMessageToPlayer(player, "Your corpse is resurrectable. You died in PvP combat.");
break;
case CorpseType.CORPSE_BONES:
SendMessageToPlayer(player, "Your corpse cannot be resurrected. It has decomposed into bones.");
break;
default:
SendMessageToPlayer(player, "Unknown corpse type.");
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_DEATH, OnPlayerDeath);
```
In this example:
1. When a player dies, the `OnPlayerDeath` event is triggered.
2. We retrieve the player's corpse using `player.GetCorpse()`.
3. If the corpse exists, we use the `GetType` method to determine the type of the corpse.
4. Based on the corpse type, we send an appropriate message to the player using `SendMessageToPlayer`:
- If the corpse is resurrectable and the player died in PvE combat, we send a message indicating that the corpse can be resurrected.
- If the corpse is resurrectable and the player died in PvP combat, we send a message indicating that the corpse can be resurrected.
- If the corpse has decomposed into bones and cannot be resurrected, we send a message informing the player about it.
- If the corpse type is unknown, we send a generic message.
This example showcases how the `GetType` method can be used to determine the type of a player's corpse and take different actions based on the corpse type.
## ResetGhostTime
Sets the corpse's "ghost time" to the current time. The ghost time is used to determine how long a ghost has been active for a player's corpse.
This method is useful when you want to manipulate the ghost duration of a corpse, such as extending or resetting the time until the corpse despawns.
### Parameters
None
### Returns
None
### Example Usage
In this example, we will reset the ghost time of a player's corpse when they die in a specific map. This can be useful if you want to give players more time to retrieve their corpse in certain areas.
```typescript
const MAP_ID_GHOSTLANDS = 530;
const GHOST_DURATION_EXTENSION = 60; // In seconds
const OnPlayerDeath: player_event_on_death = (event: number, player: Player): void => {
const mapId = player.GetMapId();
if (mapId === MAP_ID_GHOSTLANDS) {
const corpse = player.GetCorpse();
if (corpse) {
corpse.ResetGhostTime();
const ghostDuration = corpse.GetGhostTime() + GHOST_DURATION_EXTENSION;
corpse.SetGhostTime(ghostDuration);
player.SendBroadcastMessage(`Your corpse's ghost time has been extended by ${GHOST_DURATION_EXTENSION} seconds in Ghostlands.`);
}
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_DEATH, (...args) => OnPlayerDeath(...args));
```
In this script:
1. We define the specific map ID (Ghostlands) and the duration in seconds by which we want to extend the ghost time.
2. When a player dies, we check if they are in the Ghostlands map using `player.GetMapId()`.
3. If the player is in Ghostlands, we retrieve their corpse using `player.GetCorpse()`.
4. If the corpse exists, we reset its ghost time using `corpse.ResetGhostTime()`.
5. We then calculate the new ghost duration by adding the extension duration to the current ghost time.
6. We set the new ghost duration using `corpse.SetGhostTime(ghostDuration)`.
7. Finally, we send a message to the player informing them that their corpse's ghost time has been extended in Ghostlands.
This script ensures that players have an extended time to retrieve their corpse when they die in the Ghostlands map, providing a more forgiving gameplay experience in that specific area.
## SaveToDB
Saves the corpse to the database, ensuring that the corpse and its contents persist across server restarts or crashes.
### Parameters
This method does not take any parameters.
### Returns
This method does not return any value.
### Example Usage
This example demonstrates how to save a player's corpse to the database when they die, and then restore the corpse's contents to the player when they resurrect.
```typescript
const ITEM_ENTRY_HEARTHSTONE = 6948;
const OnPlayerDeath: player_event_on_death = (event: number, player: Player, killer: Unit) => {
const corpse = player.GetCorpse();
if (corpse) {
// Save the corpse to the database
corpse.SaveToDB();
}
}
const OnPlayerResurrect: player_event_on_resurrect = (event: number, player: Player) => {
const corpse = player.GetCorpse();
if (corpse) {
// Restore the player's items from the corpse
const itemCount = corpse.GetItemCount();
for (let i = 0; i < itemCount; i++) {
const item = corpse.GetItemByIndex(i);
if (item && item.GetEntry() !== ITEM_ENTRY_HEARTHSTONE) {
// Add the item to the player's inventory, excluding the Hearthstone
player.AddItem(item.GetEntry(), item.GetItemCount());
}
}
// Remove the corpse from the world and database
corpse.RemoveFromWorld();
corpse.DeleteFromDB();
}
}
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_DEATH, (...args) => OnPlayerDeath(...args));
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_RESURRECT, (...args) => OnPlayerResurrect(...args));
```
In this example:
1. When a player dies, the `OnPlayerDeath` event is triggered.
2. The script retrieves the player's corpse using `player.GetCorpse()`.
3. If the corpse exists, it is saved to the database using `corpse.SaveToDB()`, ensuring that the corpse and its contents are persisted.
4. When the player resurrects, the `OnPlayerResurrect` event is triggered.
5. The script retrieves the player's corpse again.
6. If the corpse exists, the script iterates through the items in the corpse using `corpse.GetItemCount()` and `corpse.GetItemByIndex(i)`.
7. For each item, excluding the Hearthstone (item entry 6948), the script adds the item to the player's inventory using `player.AddItem()`.
8. After restoring the items, the script removes the corpse from the world using `corpse.RemoveFromWorld()` and deletes it from the database using `corpse.DeleteFromDB()`.
This example showcases how to save a corpse to the database when a player dies and restore the corpse's contents to the player when they resurrect, providing a seamless experience across server restarts or crashes.

449
docs/classes/Player.md
View File

@@ -525,3 +525,452 @@ In this example:
6. If the player does not have Atiesh, we send a message informing them they do not possess the item.
7. Finally, we register the `OnLoginEquipAtiesh` function to the `PLAYER_EVENT_ON_LOGIN` event to check if the player can equip Atiesh when they log in.
## CanFly
Returns whether the player is able to fly or not. This is determined by the player's current location, form, and abilities.
### Parameters
None
### Returns
boolean - `true` if the player can currently fly, `false` otherwise.
### Example Usage
The following script demonstrates how to use the `CanFly()` method to check if a player is able to fly before performing a specific action. In this case, the script listens for the `PLAYER_EVENT_ON_COMMAND` event and checks if the player can fly when they use the `.fly` command. If the player can fly, it will toggle their flying state. If they cannot fly, it will send them a message indicating that they are unable to fly at their current location.
```typescript
const FLY_COMMAND = "fly";
const OnPlayerCommand: player_event_on_command = (event: number, player: Player, command: string, chatHandler: ChatHandler): boolean => {
if (command === FLY_COMMAND) {
if (player.CanFly()) {
if (player.IsFlying()) {
player.SetFlying(false);
chatHandler.SendSysMessage("You have stopped flying.");
} else {
player.SetFlying(true);
chatHandler.SendSysMessage("You are now flying!");
}
} else {
chatHandler.SendSysMessage("You cannot fly here.");
}
return false;
}
return true;
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_COMMAND, (...args) => OnPlayerCommand(...args));
```
In this example, the script registers the `PLAYER_EVENT_ON_COMMAND` event and checks if the player used the `.fly` command. If they did, it proceeds to check if the player can fly using the `CanFly()` method.
If `CanFly()` returns `true`, the script then checks the player's current flying state using `IsFlying()`. If the player is already flying, it will stop their flying state using `SetFlying(false)` and send them a message saying "You have stopped flying." If the player is not currently flying, it will set their flying state using `SetFlying(true)` and send them a message saying "You are now flying!"
If `CanFly()` returns `false`, meaning the player is unable to fly at their current location, the script will send them a message saying "You cannot fly here."
By using the `CanFly()` method, you can ensure that players are only able to toggle their flying state in appropriate locations, such as in outdoor areas where flying is permitted. This helps maintain game balance and prevents players from accessing unintended areas or exploiting game mechanics.
## CanParry
Returns a boolean value indicating whether the player can parry incoming attacks or not. This is determined by the player's class, level, and equipment.
### Parameters
None
### Returns
* boolean - Returns `true` if the player can parry attacks, `false` otherwise.
### Example Usage
In this example, we'll create a script that adjusts the player's parry chance based on their level and class.
```typescript
const adjustParryChance: player_event_on_update = (event: number, player: Player, diff: number) => {
const playerLevel = player.GetLevel();
const playerClass = player.GetClass();
let parryChanceBonus = 0;
if (playerClass === Classes.CLASS_WARRIOR || playerClass === Classes.CLASS_PALADIN || playerClass === Classes.CLASS_ROGUE) {
if (playerLevel >= 10 && playerLevel < 20) {
parryChanceBonus = 2;
} else if (playerLevel >= 20 && playerLevel < 30) {
parryChanceBonus = 4;
} else if (playerLevel >= 30) {
parryChanceBonus = 6;
}
}
if (player.CanParry()) {
const currentParryChance = player.GetFloatValue(PlayerFields.PLAYER_PARRY_PERCENTAGE);
const newParryChance = currentParryChance + parryChanceBonus;
player.SetFloatValue(PlayerFields.PLAYER_PARRY_PERCENTAGE, newParryChance);
player.SendMessage(`Your parry chance has been increased by ${parryChanceBonus}% based on your level and class.`);
} else {
player.SendMessage("Your class cannot parry attacks.");
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_UPDATE, (...args) => adjustParryChance(...args));
```
In this script:
1. We define a function called `adjustParryChance` that takes the player and the time difference as arguments.
2. We retrieve the player's level and class using the `GetLevel()` and `GetClass()` methods.
3. We initialize a variable called `parryChanceBonus` to store the bonus parry chance percentage.
4. We check if the player's class is Warrior, Paladin, or Rogue, and if so, we assign a parry chance bonus based on their level range.
5. We use the `CanParry()` method to check if the player can parry attacks.
6. If the player can parry, we retrieve their current parry chance percentage using `GetFloatValue(PlayerFields.PLAYER_PARRY_PERCENTAGE)`.
7. We calculate the new parry chance by adding the `parryChanceBonus` to the current parry chance.
8. We update the player's parry chance using `SetFloatValue(PlayerFields.PLAYER_PARRY_PERCENTAGE, newParryChance)`.
9. We send a message to the player informing them about the increased parry chance.
10. If the player cannot parry, we send a message indicating that their class cannot parry attacks.
Finally, we register the `adjustParryChance` function to the `PLAYER_EVENT_ON_UPDATE` event using `RegisterPlayerEvent`.
This script demonstrates how the `CanParry()` method can be used in combination with other player-related methods and events to create a more dynamic gameplay experience based on the player's class and level.
## CanShareQuest
This method checks if the player is able to share a quest with other players in a group.
### Parameters
* entryId: number - The ID of the quest to check if it can be shared.
### Returns
* boolean - Returns 'true' if the player can share the specified quest, 'false' otherwise.
### Example Usage
This example demonstrates how to use `CanShareQuest` to prevent players from joining a group if they have a specific quest that cannot be shared.
```typescript
const UNPARALLELED_POWER_QUEST_ID = 13373;
const onGroupInvite: player_event_on_group_invite = (event: number, player: Player, groupGuid: number, inviterGuid: number): void => {
const inviter = GetPlayerByGUID(inviterGuid);
if (!inviter) {
return;
}
const questId = UNPARALLELED_POWER_QUEST_ID;
if (player.HasQuest(questId) && !player.CanShareQuest(questId)) {
player.SendBroadcastMessage(`You cannot join the group because you have the quest "${GetQuestNameById(questId)}" which cannot be shared.`);
inviter.SendBroadcastMessage(`${player.GetName()} cannot join the group because they have the quest "${GetQuestNameById(questId)}" which cannot be shared.`);
player.DeclineGroup();
return;
}
// Other group invite logic...
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_GROUP_INVITE, (...args) => onGroupInvite(...args));
```
In this example:
1. We define a constant `UNPARALLELED_POWER_QUEST_ID` with the ID of the quest we want to check.
2. In the `onGroupInvite` event, we first check if the inviter exists using `GetPlayerByGUID`.
3. We store the quest ID in a variable `questId`.
4. We check if the player has the quest using `HasQuest` and if they can share it using `CanShareQuest`.
- If the player has the quest and cannot share it:
- We send a message to the player informing them that they cannot join the group due to the unshared quest.
- We send a message to the inviter informing them that the player cannot join the group due to the unshared quest.
- We decline the group invitation for the player using `DeclineGroup`.
- We return to prevent further execution of the event.
5. If the player can share the quest or doesn't have it, the event continues with other group invite logic.
This example showcases how `CanShareQuest` can be used to enforce quest sharing restrictions when players attempt to join a group.
## CanSpeak
Returns a boolean value indicating whether the player can currently communicate through chat.
### Parameters
None
### Returns
boolean - Returns `true` if the player can speak in chat, `false` otherwise.
### Example Usage
This example demonstrates how to use the `CanSpeak` method to prevent players from using certain chat commands if they are muted or silenced.
```typescript
// Custom chat command
const MY_CUSTOM_COMMAND = "mycmd";
// Function to handle the chat command
const handleChatCommand: player_event_on_chat = (event: number, player: Player, msg: string, type: number, lang: Language): void => {
// Check if the message starts with the custom command
if (msg.startsWith(MY_CUSTOM_COMMAND)) {
// Check if the player can speak
if (player.CanSpeak()) {
// Player can speak, process the command
// ...
// Example: Send a message to the player
player.SendBroadcastMessage("You used the custom command!");
} else {
// Player cannot speak, send an error message
player.SendBroadcastMessage("You are not allowed to use this command while muted or silenced.");
}
}
};
// Register the chat event handler
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_CHAT, (...args) => handleChatCommand(...args));
```
In this example:
1. We define a custom chat command `MY_CUSTOM_COMMAND`.
2. We create a function `handleChatCommand` to handle the chat event.
3. Inside the function, we check if the chat message starts with the custom command.
4. If it does, we use the `CanSpeak` method to check if the player can currently speak in chat.
- If the player can speak, we process the command and send a message to the player.
- If the player cannot speak (muted or silenced), we send an error message to the player.
5. Finally, we register the `handleChatCommand` function to be called whenever the `PLAYER_EVENT_ON_CHAT` event is triggered.
This example showcases how the `CanSpeak` method can be used to enforce chat restrictions and prevent muted or silenced players from using certain chat commands or features in the game.
## CanTitanGrip
Returns whether or not the player can use the Titan Grip ability.
### Returns
boolean - Returns `true` if the player can use Titan Grip, `false` otherwise.
### Example Usage
Handling an event where a Warrior attempts to equip two two-handed weapons:
```typescript
const ItemEquip : player_event_on_equip_item = (event: number, player: Player, item: Item) => {
// Check if the player is a Warrior
if (player.GetClass() !== Classes.CLASS_WARRIOR) {
return;
}
// Check if the equipped item is a two-handed weapon
if (item.GetInventoryType() === InventoryType.INVTYPE_2HWEAPON) {
// Get the item in the player's offhand slot
const offhandItem = player.GetItemByPos(InventorySlot.INVENTORY_SLOT_BAG_0, EquipmentSlots.EQUIPMENT_SLOT_OFFHAND);
// If the player has a two-handed weapon equipped in their offhand and they can't Titan Grip
if (offhandItem && offhandItem.GetInventoryType() === InventoryType.INVTYPE_2HWEAPON && !player.CanTitanGrip()) {
// Send a message to the player
player.SendBroadcastMessage("You can't equip two two-handed weapons without the Titan Grip ability.");
// Remove the offhand weapon
player.RemoveItem(InventorySlot.INVENTORY_SLOT_BAG_0, EquipmentSlots.EQUIPMENT_SLOT_OFFHAND, true);
}
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_EQUIP_ITEM, (...args) => ItemEquip(...args));
```
In this example, when a player equips an item, we first check if the player is a Warrior. If they are, we then check if the equipped item is a two-handed weapon. If it is, we get the item in the player's offhand slot and check if it's also a two-handed weapon. If the player has a two-handed weapon in their offhand and they can't use Titan Grip (determined by calling `CanTitanGrip()`), we send them a message indicating that they can't equip two two-handed weapons without the Titan Grip ability, and we remove the offhand weapon.
This script prevents Warriors from equipping two two-handed weapons unless they have the Titan Grip ability, providing a more authentic gameplay experience that adheres to the rules of the game.
## CanUninviteFromGroup
This method checks if the player has permission to uninvite other players from their current group. It takes into account factors such as the player's rank within the group and the group type (party or raid).
### Parameters
None
### Returns
boolean - Returns 'true' if the player has permission to uninvite others from the current group, 'false' otherwise.
### Example Usage
In this example, we create a command that allows a player to uninvite another player from their group, but only if they have the necessary permissions.
```typescript
// Define the command
const GroupUninviteCommand: player_gossip_event = (event: number, player: Player, receiver: Creature, message: string) => {
// Check if the player is in a group
if (!player.IsInGroup()) {
player.SendBroadcastMessage("You are not in a group.");
return;
}
// Check if the player has permission to uninvite others
if (!player.CanUninviteFromGroup()) {
player.SendBroadcastMessage("You do not have permission to uninvite players from the group.");
return;
}
// Get the name of the player to uninvite from the command arguments
const targetName = message.trim();
// Find the target player by name
const target = Player.GetPlayer(targetName);
if (!target) {
player.SendBroadcastMessage(`Player '${targetName}' not found.`);
return;
}
// Check if the target player is in the same group as the uninviting player
if (!player.IsInSameGroupWith(target)) {
player.SendBroadcastMessage(`Player '${targetName}' is not in your group.`);
return;
}
// Uninvite the target player from the group
target.UninviteFromGroup();
// Send a message to the group
player.GetGroup().SendGroupMessage(`${target.GetName()} has been uninvited from the group by ${player.GetName()}.`);
};
// Register the command
RegisterPlayerGossipEvent(100, (...args) => GroupUninviteCommand(...args));
```
In this script:
1. We first check if the player is actually in a group using `IsInGroup()`.
2. We then check if the player has permission to uninvite others using `CanUninviteFromGroup()`.
3. We get the name of the player to uninvite from the command arguments.
4. We attempt to find the target player by name using `Player.GetPlayer()`.
5. We check if the target player is in the same group as the uninviting player using `IsInSameGroupWith()`.
6. If all checks pass, we uninvite the target player from the group using `UninviteFromGroup()`.
7. Finally, we send a message to the group informing them of the uninvite action.
This script demonstrates how `CanUninviteFromGroup()` can be used in combination with other group-related methods to implement group management functionality in a mod.
## CanUseItem
Determines if the player can use a specific item or item entry. This method checks for class, level, skill, and other requirements.
### Parameters
* item: [Item](./item.md) - The item to check if the player can use
* entry: number - The item entry to check if the player can use
### Returns
* boolean - Returns 'true' if the player can use the item or item entry, 'false' otherwise.
### Example Usage
Prevent warriors from using wands and create a custom message:
```typescript
const WAND_ITEM_CLASS = 2;
const WAND_ITEM_SUBCLASS = 19;
const WARRIOR_CLASS_MASK = 1;
const OnUseItemStart: player_event_on_use_item = (event, player, item, cast) => {
if (player.GetClassMask() & WARRIOR_CLASS_MASK) {
const itemClass = item.GetClass();
const itemSubClass = item.GetSubClass();
if (itemClass == WAND_ITEM_CLASS && itemSubClass == WAND_ITEM_SUBCLASS) {
if (!player.CanUseItem(item)) {
player.SendBroadcastMessage("Warriors cannot use wands.");
player.SendEquipError(InventoryResult.EQUIP_ERR_CANT_DO_RIGHT_NOW, item);
return false;
}
}
}
return true;
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_USE_ITEM, OnUseItemStart);
```
In this example, when a warrior tries to use a wand, the script checks if the player can use the item using the `CanUseItem` method. If the player cannot use the item, it sends a custom broadcast message to the player, sends the appropriate equip error message, and prevents the item usage by returning false.
You can also use the `CanUseItem` method with an item entry:
```typescript
const ITEM_ENTRY_DARK_PORTAL = 184871;
const ITEM_ENTRY_MEDIVH_JOURNAL = 184875;
const OnLoginCheckItems: player_event_on_login = (event, player) => {
if (!player.CanUseItem(null, ITEM_ENTRY_DARK_PORTAL)) {
player.AddItem(ITEM_ENTRY_MEDIVH_JOURNAL);
player.SendBroadcastMessage("You found Medivh's Journal, which may help you to use the Dark Portal.");
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_LOGIN, OnLoginCheckItems);
```
In this example, when a player logs in, the script checks if the player can use the Dark Portal item using the `CanUseItem` method with the item entry. If the player cannot use the Dark Portal, the script adds Medivh's Journal to the player's inventory and sends a broadcast message hinting that the journal may help them use the Dark Portal.
## ClearComboPoints
Clears the player's combo points. This is useful for situations where you want to remove any existing combo points from the player, such as when they change targets or leave combat.
### Parameters
None
### Returns
None
### Example Usage
In this example, we'll create a script that clears the player's combo points when they leave combat. This ensures that the player starts fresh with zero combo points when entering a new combat encounter.
```typescript
const onLeaveCombat: player_event_on_leave_combat = (event: number, player: Player) => {
// Clear the player's combo points when leaving combat
player.ClearComboPoints();
// Notify the player that their combo points have been reset
player.SendBroadcastMessage("Your combo points have been reset.");
// You can also perform additional actions here, such as resetting other player states or buffs
// For example, you might want to remove a stealth buff if the player is a rogue
if (player.GetClass() == Classes.CLASS_ROGUE) {
player.RemoveAura(1784); // Stealth spell ID
}
// Or, you could apply a "well rested" buff if the player is in an inn or city
if (player.IsInCity() || player.IsInInn()) {
player.AddAura(20591, player); // Restful Sleep spell ID
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_LEAVE_COMBAT, (...args) => onLeaveCombat(...args));
```
In this script, we register the `onLeaveCombat` callback function to be triggered whenever the player leaves combat. Inside the callback, we perform the following actions:
1. Clear the player's combo points using `player.ClearComboPoints()`.
2. Send a broadcast message to the player informing them that their combo points have been reset.
3. Check if the player is a rogue using `player.GetClass()` and compare it with the `Classes.CLASS_ROGUE` constant. If the player is a rogue, we remove the stealth buff using `player.RemoveAura(1784)`, where `1784` is the spell ID for stealth.
4. Check if the player is in a city or inn using `player.IsInCity()` or `player.IsInInn()`. If the player is in either of these locations, we apply the "Restful Sleep" buff using `player.AddAura(20591, player)`, where `20591` is the spell ID for the buff.
This example demonstrates how you can use the `ClearComboPoints` method in combination with other player-related methods and game events to create more complex and immersive gameplay experiences. By resetting the player's combo points when leaving combat and performing additional actions based on their class and location, you can provide a more dynamic and personalized experience for each player.
## ClearHonorInfo
This method clears all the weekly honor status for the player, resetting their honor points, kills, and other related statistics. This can be useful for implementing custom PvP systems or resetting player progress on a weekly basis.
### Parameters
This method does not take any parameters.
### Returns
This method does not return any value.
### Example Usage:
In this example, we'll create a script that resets all online players' weekly honor status every Sunday at midnight.
```typescript
// Function to reset weekly honor status for all online players
function ResetWeeklyHonor() {
const players = GetPlayersInWorld();
for (const player of players) {
player.ClearHonorInfo();
player.SendBroadcastMessage("Your weekly honor status has been reset.");
}
}
// Function to check if it's Sunday at midnight
function IsSundayMidnight() {
const now = new Date();
return now.getDay() === 0 && now.getHours() === 0 && now.getMinutes() === 0;
}
// Register a server event to check for Sunday midnight every minute
RegisterServerEvent(ServerEvents.SERVER_EVENT_ON_UPDATE, () => {
if (IsSundayMidnight()) {
ResetWeeklyHonor();
}
});
```
In this script:
1. We define a function called `ResetWeeklyHonor` that retrieves all online players using `GetPlayersInWorld()`, then iterates through each player and calls the `ClearHonorInfo()` method to reset their weekly honor status. We also send a broadcast message to each player informing them of the reset.
2. We define a helper function called `IsSundayMidnight` that checks if the current date and time is Sunday at midnight (00:00).
3. We register a server event using `RegisterServerEvent` with the event type `ServerEvents.SERVER_EVENT_ON_UPDATE`. This event is triggered every server update tick (usually every few milliseconds).
4. Inside the event callback, we check if it's Sunday at midnight using the `IsSundayMidnight` function. If it is, we call the `ResetWeeklyHonor` function to reset the weekly honor status for all online players.
With this script in place, the server will automatically reset the weekly honor status for all online players every Sunday at midnight, providing a consistent and automated way to manage player progress in a custom PvP system.

42
docs/classes/Unit.md Normal file
View File

@@ -0,0 +1,42 @@
## AddAura
Adds an aura to the target unit based on the specified spell entry. The aura is applied as if it was cast by the current unit.
### Parameters
- spell: number - The spell entry ID of the aura to be added. You can find spell IDs in the `spell_template` table in the world database.
- target: [Unit](./unit.md) - The target unit to which the aura will be applied.
### Returns
- [Aura](./aura.md) - The aura object that was added to the target unit.
### Example Usage
In this example, we create a script that adds a random beneficial aura to a player when they kill a creature. The aura is chosen from a predefined list of spell IDs.
```typescript
const BENEFICIAL_AURAS = [1126, 21562, 13165, 13166, 13169, 28491, 28502, 40120, 40121, 40122];
const OnCreatureKill: player_event_on_kill_creature = (event: number, player: Player, creature: Creature) => {
const randomIndex = Math.floor(Math.random() * BENEFICIAL_AURAS.length);
const selectedAura = BENEFICIAL_AURAS[randomIndex];
const aura = player.AddAura(selectedAura, player);
if (aura) {
player.SendBroadcastMessage(`You have been granted the beneficial aura ${aura.GetSpellName()}!`);
} else {
console.log(`Failed to add aura ${selectedAura} to player ${player.GetName()}.`);
}
};
RegisterPlayerEvent(PlayerEvents.PLAYER_EVENT_ON_KILL_CREATURE, (...args) => OnCreatureKill(...args));
```
In this script:
1. We define an array `BENEFICIAL_AURAS` containing the spell IDs of various beneficial auras.
2. We register the `OnCreatureKill` event, which triggers when a player kills a creature.
3. Inside the event handler, we generate a random index using `Math.random()` and select a random aura from the `BENEFICIAL_AURAS` array.
4. We call `player.AddAura()`, passing the selected aura spell ID and the player itself as the target.
5. If the aura is successfully added (i.e., `aura` is not `null` or `undefined`), we send a broadcast message to the player informing them about the granted aura using `player.SendBroadcastMessage()`.
6. If the aura fails to be added, we log an error message using `console.log()`.
This script adds an element of surprise and reward for players when they kill creatures, granting them a random beneficial aura from a predefined list. The auras can provide various benefits such as increased stats, damage output, or defensive capabilities, enhancing the player's gameplay experience.