More lua functions MD

docs/lua_functions/AddSkill.md

@@ -1,22 +1,18 @@
-### Function: AddSkill(param1, param2, param3, param4, param5, param6, param7)
+Function: AddSkill(Spawn, SkillID, CurrentVal, MaxVal, MoreToAdd)
 
-**Description:**
-Placeholder description.
+Description: Grants a new skill to the specified player. If the player does not already have the skill in their skill list, this will add it (usually at base level).
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: unknown - Unknown type.
-- `param3`: unknown - Unknown type.
-- `param4`: int32 - Integer value.
-- `param5`: int16 - Short integer value.
-- `param6`: int16 - Short integer value.
-- `param7`: bool - Boolean value (true/false).
+Parameters:
 
-**Returns:** None.
+    Spawn: Spawn – The player to grant the skill to.
+    SkillID: Int32 – The ID of the skill to add.
+    CurrentVal: Int16 – The current value the player will have in the skill.
+    MaxVal: Int16 – The max skill the player can receive with the current skill.
+    MoreToAdd: Boolean – When set to true, we skip sending the skill packet, expecting to send yet another skill with AddSkill.
 
-**Example:**
+Returns: If successfully adding the skill we will return true, otherwise we return false noting the player already has the skill.
 
-```lua
--- Example usage
-AddSkill(..., ..., ..., ..., ..., ..., ...)
-```
+Example:
+-- For SkillID refer to the skills table https://github.com/emagi/eq2emu/blob/main/docs/data_types/skills.md
+-- Example usage (teach the player the “Gnollish” language skill)
+AddSkill(Player, GNOLLISH_LANGUAGE_SKILL_ID)

docs/lua_functions/AddSpawnProximity.md

@@ -1,21 +1,37 @@
-### Function: AddSpawnProximity(param1, param2, param3, param4, param5, param6)
+Function: AddSpawnProximity(Spawn, SpawnValue, SpawnType, Radius, EnterFunction, LeaveFunction)
 
-**Description:**
-Placeholder description.
+Description: Used on NPC's/Objects/Widgets to track other NPC's/Objects/Widgets entering proximity.  SpawnValue is the database id or location id based on the SpawnType.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: int32 - Integer value.
-- `param3`: int8 - Small integer or boolean flag.
-- `param4`: float - Floating point value.
-- `param5`: string - String value.
-- `param6`: string - String value.
+Parameters:
 
-**Returns:** None.
+    Spawn: Spawn – The central entity defining the proximity area.
+    SpawnValue: UInt32 – 
+    SpawnType: UInt8 – SPAWNPROXIMITY_DATABASE_ID = 0, SPAWNPROXIMITY_LOCATION_ID = 1
+    Radius: Float – The radius (in meters) of the proximity zone around the spawn.
+    EnterFunction: String – The name of the function to call when a player enters the radius.
+    LeaveFunction: String – The name of the function to call when a player leaves the radius.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-AddSpawnProximity(..., ..., ..., ..., ..., ...)
-```
+Example:
+
+-- Example script taken from SpawnScripts/TimorousDeep/aHaoaeranpoacher.lua (2630018)
+-- Poacher attacks Crabs when In Range, using the v = SpawnValue, SpawnType = 1 (Location ID), Radius = 5.
+local crablist = { 35182, 34566, 34575, 34752, 34873, 35006, 35182, 35355, 35470, 35506, 35527, 35535, 35544, 35550, 35551, 35554, 35555, 35581, 35635, 35698, 35768, 35818, 35848, 35867, 35889, 35918, 35943, 35948, 35951, 35960, 35971, 35981 }; -- array with crabs location ID's
+function prespawn(NPC)
+	for k, v in ipairs(crablist) do
+		AddSpawnProximity(NPC, v,  1, 5, "InRange", "OutRange")
+	end
+end
+
+function InRange(NPC)
+local crab = GetSpawn(NPC, 2630018)
+	if crab ~= nil then
+		Attack(NPC, crab)
+	end
+end
+   
+
+function OutRange(NPC)
+ -- do whatever out of range
+end

docs/lua_functions/AddSpawnSpellBonus.md

@@ -1,23 +1,23 @@
-### Function: AddSpawnSpellBonus(param1, param2, param3, param4, param5, param6, param7, param8)
+Function: AddSpawnSpellBonus(Spawn, BonusType, Value)
 
-**Description:**
-Placeholder description.
+Description: Used only in a Spell Script.  Applies a spell bonus or modifier to the specified spawn, versus AddSpellBonus applying to all targets of the Spell. This could be things like increased stats, mitigation, damage, etc., as defined by BonusType.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: unknown - Unknown type.
-- `param3`: unknown - Unknown type.
-- `param4`: unknown - Unknown type.
-- `param5`: unknown - Unknown type.
-- `param6`: unknown - Unknown type.
-- `param7`: int16 - Short integer value.
-- `param8`: unknown - Unknown type.
+Parameters:
 
-**Returns:** None.
+    Spawn: Spawn – The entity to receive the bonus.
+    BonusType: UInt16 – The type of bonus to apply (as defined in game constants, e.g., a particular stat or resist).  These are based on the item stat types.
+    Value: SInt32 – The value of the bonus to add (could be absolute or percentage depending on type).
 
-**Example:**
+Returns: None.
+
+Example:
+-- See item stat types for BonusType ID's: https://raw.githubusercontent.com/emagi/eq2emu/refs/heads/main/docs/data_types/item_stat_types.md
+-- Spell Script Example usage (increase NPC's defense by 50 temporarily during spell's lifetime)
+function cast(Caster, Target)
+    AddSpawnSpellBonus(Target, 106, 50.0)
+end
+
+function remove(Caster, Target)
+    RemoveSpawnSpellBonus(Target)
+end
 
-```lua
--- Example usage
-AddSpawnSpellBonus(..., ..., ..., ..., ..., ..., ..., ...)
-```

docs/lua_functions/AddSpellTimer.md

@@ -1,23 +1,29 @@
-### Function: AddSpellTimer(param1, param2, param3, param4, param5, param6, param7, param8)
+Function: AddSpellTimer(DelayMS, FunctionName, Caster, Target)
 
-**Description:**
-Placeholder description.
+Description: Used only in a Spell Script.  Schedules a call to a function (by name) in the spawn’s script after a specified delay in milliseconds. This is typically used within NPC scripts to create timed events (like delayed attacks or actions) without blocking the main thread.
 
-**Parameters:**
-- `param1`: int32 - Integer value.
-- `param2`: unknown - Unknown type.
-- `param3`: unknown - Unknown type.
-- `param4`: unknown - Unknown type.
-- `param5`: unknown - Unknown type.
-- `param6`: string - String value.
-- `param7`: Spawn - The spawn or entity involved.
-- `param8`: Spawn - The spawn or entity involved.
+Parameters:
 
-**Returns:** None.
+    DelayMS: Int32 – The delay in milliseconds before the function is called.
+    FunctionName: String – The name of the function in the NPC’s Lua script to call when the timer expires.
+    Caster: Spawn – The source spawn who was the caster/originator.
+    Target: Spawn – The target spawn who will be included as a secondary argument
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-AddSpellTimer(..., ..., ..., ..., ..., ..., ..., ...)
-```
+Example:
+-- taken from Spells/Commoner/Knockdown.lua
+-- Timer argument taken from spell data in the database, after Timer elapses we call RemoveStunBlur
+function cast(Caster, Target, Timer)
+if not IsEpic(Target) then
+        PlayAnimation(Target, 72)
+		AddControlEffect(Target, 4)
+        BlurVision(Target, 1.0)
+        AddSpellTimer(Timer, "RemoveStunBlur")
+    end
+end
+
+function RemoveStunBlur(Caster, Target)
+    RemoveControlEffect(Target, 4)
+    BlurVision(Target, 0)
+end

docs/lua_functions/AddWard.md

@@ -1,24 +1,21 @@
-### Function: AddWard(param1, param2, param3, param4, param5, param6, param7, param8, param9)
+Function: AddWard(WardAmount, KeepWard, WardType, DamageTypes, DamageAbsorptionPct, DamageAbsorptionMaxHealthPct, RedirectDamagePct, MaxHitCount)
 
-**Description:**
-Placeholder description.
+Description: Used in a Spell Script.  Applies a protective ward to all spell targets of the spell. A ward absorbs a certain amount of incoming damage before it expires. This function creates a new ward on the target with the given value.
 
-**Parameters:**
-- `param1`: int32 - Integer value.
-- `param2`: unknown - Unknown type.
-- `param3`: int8 - Small integer or boolean flag.
-- `param4`: int8 - Small integer or boolean flag.
-- `param5`: int8 - Small integer or boolean flag.
-- `param6`: int32 - Integer value.
-- `param7`: int32 - Integer value.
-- `param8`: int32 - Integer value.
-- `param9`: int32 - Integer value.
+Parameters:
 
-**Returns:** None.
+    WardAmount: UInt32 – The amount of damage the ward can absorb.
+    KeepWard: Boolean – The amount of damage the ward can absorb.
+    WardType: UInt8 – The amount of damage the ward can absorb. Options: ALL = 0, Physical Only = 1, Magical Only = 2.
+    DamageTypes: UInt8 – The amount of damage the ward can absorb.  If Ward is Magical Only then 0 allows any Magical or select a Damage Type: https://github.com/emagi/eq2emu/blob/main/docs/data_types/damage_types.md
+    DamageAbsorptionPct: UInt32 – The amount of damage the ward can absorb.  Max of 100.
+    DamageAbsorptionMaxHealthPct: UInt32 – The amount of damage the ward can absorb.  Max of 100.
+    RedirectDamagePct: UInt32 – The amount of damage the ward can absorb.
+    MaxHitCount: Int32 – The player or NPC to protect with the ward.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-AddWard(..., ..., ..., ..., ..., ..., ..., ..., ...)
-```
+Example:
+
+-- Example usage (shield the player with a 500 hp point ward)
+AddWard(500)

docs/lua_functions/AddWaypoint.md

@@ -1,18 +1,19 @@
-### Function: AddWaypoint(param1, param2, param3)
+Function: AddWaypoint(Player, Name, X, Y, Z)
 
-**Description:**
-Placeholder description.
+Description: Adds a guiding waypoint to a Player with the Name for the description at X, Y, Z coordinates.  You can add multiple waypoints and then send waypoints.  Refer to RemoveWaypoint(Player, Name) to remove an existing waypoint.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: string - String value.
-- `param3`: int32 - Integer value.
+Parameters:
 
-**Returns:** None.
+    Player: Spawn – The Player to which to provide the waypoint.
+	Name: String - The name / description of the waypoint.
+    X: Float – The X coordinate of the waypoint.
+    Y: Float – The Y coordinate (vertical) of the waypoint.
+    Z: Float – The Z coordinate of the waypoint.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-AddWaypoint(..., ..., ...)
-```
+Example:
+
+-- Add a waypoint to the client and send the waypoints
+AddWaypoint(Player, "Lets go here!", 102.5, -12.3, 230.0)
+SendWaypoints(Player)

docs/lua_functions/BlurVision.md

@@ -1,20 +1,15 @@
-### Function: BlurVision(param1, param2, param3, param4, param5)
+Function: BlurVision(Spawn, Intensity)
 
-**Description:**
-Placeholder description.
+Description: For use in Spell Script or against a Spawn directly.  Sets the intensity of drunkness on the player.  When used in Spell Script applies to all Spell Targets.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: unknown - Unknown type.
-- `param3`: unknown - Unknown type.
-- `param4`: unknown - Unknown type.
-- `param5`: float - Floating point value.
+Parameters:
 
-**Returns:** None.
+    Spawn: Spawn – The player whose vision to affect.
+    Intensity: Float – Intensity of the player being drunk, setting to 0.0 will mean player is not drunk.  The higher the more extreme the screen distortion.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-BlurVision(..., ..., ..., ..., ...)
-```
+Example:
+
+-- Example usage (blur player's vision while under a drunken effect)
+BlurVision(Player, 0.5)

docs/lua_functions/ClearHate.md

@@ -1,20 +1,15 @@
-### Function: ClearHate(param1, param2, param3, param4, param5)
+Function: ClearHate(NPC, Hated)
 
-**Description:**
-Placeholder description.
+Description: Removes the `Hated` target on the NPC's hate list.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: unknown - Unknown type.
-- `param3`: unknown - Unknown type.
-- `param4`: unknown - Unknown type.
-- `param5`: Spawn - The spawn or entity involved.
+Parameters:
 
-**Returns:** None.
+    NPC: Spawn – The NPC whose hate list should be cleared.
+    Hated: Spawn – The hated target that is to be removed from the hate list.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-ClearHate(..., ..., ..., ..., ...)
-```
+Example:
+
+-- Example usage (an NPC stops attacking/hating Target)
+ClearHate(NPC, Target)

docs/lua_functions/CloseDoor.md

@@ -1,18 +1,15 @@
-### Function: CloseDoor(param1, param2, param3)
+Function: CloseDoor(DoorSpawn, DisableCloseSound)
 
-**Description:**
-Placeholder description.
+Description: Closes an open door spawn, playing its closing animation and sound.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: unknown - Unknown type.
-- `param3`: bool - Boolean value (true/false).
+Parameters:
 
-**Returns:** None.
+    DoorSpawn: Spawn – The door object to close.
+    DisableCloseSound: Boolean - Default is false, when set to true, no door close sound will be made.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-CloseDoor(..., ..., ...)
-```
+Example:
+
+-- Example usage (close the door after some time or event)
+CloseDoor(CastleGate)

docs/lua_functions/FlashWindow.md

@@ -1,18 +1,16 @@
-### Function: FlashWindow(param1, param2, param3)
+Function: FlashWindow(Player, WindowName, FlashSeconds)
 
-**Description:**
-Placeholder description.
+Description: Causes a UI window to flash (usually its icon or border) on the client to draw attention. For example, flashing the quest journal icon when a new quest is added.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: string - String value.
-- `param3`: float - Floating point value.
+Parameters:
 
-**Returns:** None.
+    Player: Spawn – The player whose UI to affect.
+    WindowName: String – The window or UI element name to flash.
+    FlashSeconds: Float - Flash time of the window in seconds.
+	
+Returns: None.
 
-**Example:**
+Example:
 
-```lua
--- Example usage
-FlashWindow(..., ..., ...)
-```
+-- Example usage (flash the quest journal when a quest is updated for 2 seconds).
+FlashWindow(Player, "MainHUD.StartMenu.quest_journal", 2.0)

docs/lua_functions/GetShardCharID.md

@@ -1,16 +1,14 @@
-### Function: GetShardCharID(param1)
+Function: GetShardCharID(ShardID)
 
-**Description:**
-Placeholder description.
+Description: Given a spirit shard’s ID, returns the character ID of the player who owns that shard.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
+Parameters:
 
-**Returns:** None.
+    ShardID: Int32 – The shard’s unique ID.
 
-**Example:**
+Returns: Int32 – The character ID of the player to whom the shard belongs.
 
-```lua
--- Example usage
-GetShardCharID(...)
-```
+Example:
+
+-- Example usage (identify which player a shard belongs to, perhaps for a shard recovery NPC)
+local ownerCharID = GetShardCharID(shardSpawnID)

docs/lua_functions/GetShardCreatedTimestamp.md

@@ -1,16 +1,15 @@
-### Function: GetShardCreatedTimestamp(param1)
+Function: GetShardCreatedTimestamp(ShardID)
 
-**Description:**
-Placeholder description.
+Description: Returns the Unix timestamp (or similar) of when the spirit shard was created (i.e., the time of the player’s death that generated it).
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
+Parameters:
 
-**Returns:** None.
+    ShardID: Int32 – The spirit shard’s ID.
 
-**Example:**
+Returns: Int64 – The creation timestamp of the shard.
 
-```lua
--- Example usage
-GetShardCreatedTimestamp(...)
-```
+Example:
+
+-- Example usage (calculate how old a shard is for some mechanic)
+local shardTime = GetShardCreatedTimestamp(shardID)
+local ageSeconds = os.time() - shardTime

docs/lua_functions/IsPlayer.md

@@ -1,16 +1,16 @@
-### Function: IsPlayer(param1)
+### Function: IsPlayer(Player)
 
 **Description:**
-Placeholder description.
+Checks if Player is an actual Player or Spawn.
 
 **Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
+- `Player`: Spawn - The spawn or entity to check.
 
-**Returns:** None.
+Returns: Boolean – true if this spawn is a Player; false if not.
 
 **Example:**
 
-```lua
--- Example usage
-IsPlayer(...)
-```
+-- Example usage (NPC will attack stealthed players only if it can see invis)
+if IsPlayer(Target) or CanSeeInvis(NPC, Target) then
+    Attack(NPC, Target)
+end

docs/lua_functions/RemoveWaypoint.md

@@ -1,17 +1,16 @@
-### Function: RemoveWaypoint(param1, param2)
+Function: RemoveWaypoint(Player, WaypointIndex)
 
-**Description:**
-Placeholder description.
+Description: Removes the guiding waypoint for the Player.  SendWaypoints should also be sent after.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
-- `param2`: string - String value.
+Parameters:
 
-**Returns:** None.
+    Player: Spawn – The NPC whose waypoint path to modify.
+    Name: String - The name of the waypoint supplied originally when AddWaypoint was called.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-RemoveWaypoint(..., ...)
-```
+Example:
+
+-- Example usage (remove a previously added waypoint)
+RemoveWaypoint(Player, "PreviousWaypoint")
+SendWaypoints(Player)

docs/lua_functions/SendWaypoints.md

@@ -1,16 +1,15 @@
-### Function: SendWaypoints(param1)
+Function: SendWaypoints(Player)
 
-**Description:**
-Placeholder description.
+Description: Sends the Player the visual/guiding waypoints provided through AddWaypoint.
 
-**Parameters:**
-- `param1`: Spawn - The spawn or entity involved.
+Parameters:
 
-**Returns:** None.
+    Player: Spawn – The Player to update their waypoints by sending the packet update.
 
-**Example:**
+Returns: None.
 
-```lua
--- Example usage
-SendWaypoints(...)
-```
+Example:
+
+-- Add a waypoint to the client and send the waypoints
+AddWaypoint(Player, "Lets go here!", 102.5, -12.3, 230.0)
+SendWaypoints(Player)