From 56b70c34a7c8301198a93da51fa52dbc9e012b45 Mon Sep 17 00:00:00 2001 From: Emagi Date: Wed, 14 May 2025 09:46:52 -0400 Subject: [PATCH] More lua functions MD --- docs/lua_functions/AddSkill.md | 30 +++++------- docs/lua_functions/AddSpawnProximity.md | 48 ++++++++++++------- docs/lua_functions/AddSpawnSpellBonus.md | 36 +++++++------- docs/lua_functions/AddSpellTimer.md | 42 +++++++++------- docs/lua_functions/AddWard.md | 35 +++++++------- docs/lua_functions/AddWaypoint.md | 27 ++++++----- docs/lua_functions/BlurVision.md | 25 ++++------ docs/lua_functions/ClearHate.md | 25 ++++------ docs/lua_functions/CloseDoor.md | 23 ++++----- docs/lua_functions/FlashWindow.md | 24 +++++----- docs/lua_functions/GetShardCharID.md | 20 ++++---- .../lua_functions/GetShardCreatedTimestamp.md | 21 ++++---- docs/lua_functions/IsPlayer.md | 16 +++---- docs/lua_functions/RemoveWaypoint.md | 23 +++++---- docs/lua_functions/SendWaypoints.md | 21 ++++---- 15 files changed, 206 insertions(+), 210 deletions(-) diff --git a/docs/lua_functions/AddSkill.md b/docs/lua_functions/AddSkill.md index 1469eb0..875ed31 100644 --- a/docs/lua_functions/AddSkill.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/AddSpawnProximity.md b/docs/lua_functions/AddSpawnProximity.md index b131da6..6d72da7 100644 --- a/docs/lua_functions/AddSpawnProximity.md +++ b/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 diff --git a/docs/lua_functions/AddSpawnSpellBonus.md b/docs/lua_functions/AddSpawnSpellBonus.md index 7cb6c0b..123319d 100644 --- a/docs/lua_functions/AddSpawnSpellBonus.md +++ b/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(..., ..., ..., ..., ..., ..., ..., ...) -``` diff --git a/docs/lua_functions/AddSpellTimer.md b/docs/lua_functions/AddSpellTimer.md index 7eea051..e20d6c4 100644 --- a/docs/lua_functions/AddSpellTimer.md +++ b/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 \ No newline at end of file diff --git a/docs/lua_functions/AddWard.md b/docs/lua_functions/AddWard.md index 4dd1899..40c1bd1 100644 --- a/docs/lua_functions/AddWard.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/AddWaypoint.md b/docs/lua_functions/AddWaypoint.md index 1c66867..5167629 100644 --- a/docs/lua_functions/AddWaypoint.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/BlurVision.md b/docs/lua_functions/BlurVision.md index 8df8147..bfab6c8 100644 --- a/docs/lua_functions/BlurVision.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/ClearHate.md b/docs/lua_functions/ClearHate.md index 36e1cd5..0fecbcb 100644 --- a/docs/lua_functions/ClearHate.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/CloseDoor.md b/docs/lua_functions/CloseDoor.md index 8121ed8..ef2003c 100644 --- a/docs/lua_functions/CloseDoor.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/FlashWindow.md b/docs/lua_functions/FlashWindow.md index 1a53bc6..b61a828 100644 --- a/docs/lua_functions/FlashWindow.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/GetShardCharID.md b/docs/lua_functions/GetShardCharID.md index e7fe440..c43e052 100644 --- a/docs/lua_functions/GetShardCharID.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/GetShardCreatedTimestamp.md b/docs/lua_functions/GetShardCreatedTimestamp.md index 1660ccc..775b424 100644 --- a/docs/lua_functions/GetShardCreatedTimestamp.md +++ b/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 \ No newline at end of file diff --git a/docs/lua_functions/IsPlayer.md b/docs/lua_functions/IsPlayer.md index e0d6d98..75cc02b 100644 --- a/docs/lua_functions/IsPlayer.md +++ b/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 \ No newline at end of file diff --git a/docs/lua_functions/RemoveWaypoint.md b/docs/lua_functions/RemoveWaypoint.md index 0d68bcb..6fea0ec 100644 --- a/docs/lua_functions/RemoveWaypoint.md +++ b/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) \ No newline at end of file diff --git a/docs/lua_functions/SendWaypoints.md b/docs/lua_functions/SendWaypoints.md index c500472..6ba23a2 100644 --- a/docs/lua_functions/SendWaypoints.md +++ b/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) \ No newline at end of file