Merge pull request #6205 from LandSandBoat/lls/interaction-quest

[LLS] Annotate Interaction files (Quests), add TQuest type, fix issues identified

scripts/globals/interaction/actions/action.lua

@@ -1,8 +1,10 @@
 -----------------------------------
 ----- Action base class
 -----------------------------------
+---@class TInteractionAction
 Action = {}
 
+---@enum Action.Priority
 Action.Priority =
 {
     Ignore = 1,
@@ -13,6 +15,7 @@ Action.Priority =
     Progress = 1000,
 }
 
+---@enum Action.Type
 Action.Type =
 {
     LambdaAction = 0,
@@ -26,6 +29,8 @@ Action.Type =
     NoAction = 8,
 }
 
+---@param type Action.Type
+---@return TInteractionAction
 function Action:new(type)
     local obj = {}
     setmetatable(obj, self)
@@ -34,51 +39,63 @@ function Action:new(type)
     return obj
 end
 
+---@param player CBaseEntity
+---@param targetEntity CBaseEntity
+---@return integer
 function Action:perform(player, targetEntity)
     -- Functionality is implemented in the specific sub-classes
     return self.returnValue
 end
 
+---@param priorityArg Action.Priority|integer
+---@return TInteractionAction
 function Action:setPriority(priorityArg)
     self.priority = priorityArg
     return self
 end
 
+---@return TInteractionAction
 function Action:progress()
     -- Set highest priority for action
     return self:setPriority(Action.Priority.Progress)
 end
 
+---@return TInteractionAction
 function Action:replaceDefault()
     -- Always prefer this over falling back to default in lua file
     return self:setPriority(Action.Priority.ReplaceDefault)
 end
 
 -- Perform the action as a Progress priority, and then default back to event
+---@return TInteractionAction
 function Action:importantEvent()
     self.priority = Action.Priority.Progress
     self.secondaryPriority = Action.Priority.Event
     return self
 end
 
 -- After the first time the action is performed, it will have a lower priority
+---@return TInteractionAction
 function Action:importantOnce()
     self.priority = Action.Priority.Event
     self.secondaryPriority = Action.Priority.Default
     return self
 end
 
 -- Only do this action once per zone, unless there's nothing else to do
+---@return TInteractionAction
 function Action:oncePerZone()
     self.secondaryPriority = Action.Priority.Ignore
     return self
 end
 
+---@return TInteractionAction
 function Action:openDoor()
     self.returnValue = -1
     return self
 end
 
+---@return TInteractionAction
 function Action:open()
     return self:openDoor()
 end

scripts/globals/interaction/actions/event.lua

@@ -3,8 +3,13 @@
 -----------------------------------
 require('scripts/globals/interaction/actions/action')
 
+---@class TInteractionEvent : TInteractionAction
+---@field id integer
+---@field options integer[]|table[]
 Event = Action:new(Action.Type.Event)
 
+---@param eventId integer
+---@param ... integer|table
 function Event:new(eventId, ...)
     local obj = {}
     setmetatable(obj, self)
@@ -16,6 +21,8 @@ function Event:new(eventId, ...)
     return obj
 end
 
+---@param player CBaseEntity
+---@param targetEntity CBaseEntity
 function Event:perform(player, targetEntity)
     if self.isCutscene and player.startCutscene then
         player:startCutscene(self.id, unpack(self.options))
@@ -26,6 +33,7 @@ function Event:perform(player, targetEntity)
     return self.returnValue
 end
 
+---@return TInteractionEvent
 function Event:cutscene()
     self.isCutscene = true
     return self

scripts/globals/interaction/actions/keyitem.lua

@@ -3,8 +3,12 @@
 -----------------------------------
 require('scripts/globals/interaction/actions/action')
 
+---@class TInteractionKeyItem : TInteractionAction
+---@field id integer
 KeyItemAction = Action:new(Action.Type.KeyItem)
 
+---@param keyItemId xi.keyItem
+---@return TInteractionKeyItem
 function KeyItemAction:new(keyItemId)
     local obj = {}
     setmetatable(obj, self)
@@ -14,6 +18,8 @@ function KeyItemAction:new(keyItemId)
     return obj
 end
 
+---@param player CBaseEntity
+---@param targetEntity CBaseEntity
 function KeyItemAction:perform(player, targetEntity)
     return npcUtil.giveKeyItem(player, self.id)
 end

scripts/globals/interaction/actions/lambdaaction.lua

@@ -3,8 +3,13 @@
 -----------------------------------
 require('scripts/globals/interaction/actions/action')
 
+---@class TInteractionLambdaAction : TInteractionAction
+---@field actionFunc function
+---@field priority Action.Priority|integer
 LambdaAction = Action:new(Action.Type.LambdaAction)
 
+---@param actionFunc function
+---@param prio Action.Priority|integer
 function LambdaAction:new(actionFunc, prio)
     local obj = {}
     setmetatable(obj, self)

scripts/globals/interaction/actions/message.lua

@@ -3,15 +3,26 @@
 -----------------------------------
 require('scripts/globals/interaction/actions/action')
 
+---@class TInteractionMessage: TInteractionAction
+---@field messageType Message.type
+---@field id integer
+---@field npcId integer?
+---@field options integer[]
+---@field face integer?
 Message = Action:new(Action.Type.Message)
 
+---@enum Message.type
 Message.Type =
 {
     Text    = 1,
     Special = 2,
     Name    = 3,
 }
 
+---@param messageId integer
+---@param messageType Message.type?
+---@param ... integer?
+---@return TInteractionMessage
 function Message:new(messageId, messageType, ...)
     local obj = {}
     setmetatable(obj, self)
@@ -23,6 +34,8 @@ function Message:new(messageId, messageType, ...)
     return obj
 end
 
+---@param player CBaseEntity
+---@param targetEntity CBaseEntity
 function Message:perform(player, targetEntity)
     if self.messageType == Message.Type.Special then
         player:messageSpecial(self.id, unpack(self.options))

scripts/globals/interaction/actions/noaction.lua

@@ -6,6 +6,7 @@
 -----------------------------------
 require('scripts/globals/interaction/actions/action')
 
+---@class TInteractionNoAction : TInteractionAction
 NoAction = Action:new(Action.Type.NoAction)
 
 function NoAction:new(prio)

scripts/globals/interaction/actions/sequence.lua

@@ -4,6 +4,8 @@
 require('scripts/globals/interaction/actions/action')
 require('scripts/globals/interaction/actions/message')
 
+---@class TInteractionSequence : TInteractionAction
+---@field __nextAction any
 Sequence = Action:new(Action.Type.Sequence)
 
 -- Parse out a sequence from a table of actions.
@@ -28,6 +30,7 @@ function Sequence:new(unparsedSequence)
     local id = nil
     for _, entry in ipairs(unparsedSequence) do
         if entry.text then
+            ---@type TInteractionMessage
             local newLast = Message:new(entry.text)
             last.__nextAction = newLast
             last = newLast
@@ -47,11 +50,15 @@ function Sequence:new(unparsedSequence)
         -- Waits can be part of the other action
         if entry.wait then
             local newLast = { type = Action.Type.Wait, milliseconds = entry.wait }
+            -- TODO: Find a more elegant way to handle the inject field warnings
+            ---@diagnostic disable-next-line inject-field
             last.__nextAction = newLast
             last = newLast
         end
     end
 
+    -- TODO: Find a more elegant way to handle the inject field warnings
+    ---@diagnostic disable-next-line inject-field
     last.__nextAction = { type = Action.Type.Release }
 
     obj.id = id