more nil

lua/client/client.lua

@@ -267,7 +267,7 @@ fk.client_callback["AddPlayer"] = function(jsonData)
   -- jsonData: [ int id, string screenName, string avatar ]
   -- when other player enter the room, we create clientplayer(C and lua) for them
   local data = json.decode(jsonData)
-  local id, name, avatar, gameData = data[1], data[2], data[3]
+  local id, name, avatar = data[1], data[2], data[3]
   local player = fk.ClientInstance:addPlayer(id, name, avatar)
   local p = ClientPlayer:new(player)
   table.insert(ClientInstance.players, p)

lua/client/i18n/zh_CN.lua

@@ -140,7 +140,7 @@ FreeKill使用的是libgit2的C API，与此同时使用Git完成拓展包的下
   ["OK"] = "确定",
   ["Cancel"] = "取消",
   ["End"] = "结束",
-  ["Quit"] = "退出",
+  -- ["Quit"] = "退出",
   ["BanGeneral"] = "禁将",
   ["ResumeGeneral"] = "解禁",
   ["Death audio"] = "阵亡",

lua/core/card.lua

@@ -136,8 +136,8 @@ end
 --- 克隆特定卡牌并赋予花色与点数。
 ---
 --- 会将skill/special_skills/equip_skill继承到克隆牌中。
----@param suit Suit @ 克隆后的牌的花色
+---@param suit Suit|nil @ 克隆后的牌的花色
----@param number integer @ 克隆后的牌的点数
+---@param number integer|nil @ 克隆后的牌的点数
 ---@return Card @ 产品
 function Card:clone(suit, number)
   local newCard = self.class:new(self.name, suit, number)
@@ -402,7 +402,7 @@ end
 
 --- 获取卡牌对应Mark的数量。
 ---@param mark string @ 标记
----@return integer
+---@return any
 function Card:getMark(mark)
   local ret = (self.mark[mark] or 0)
   if (not self:isVirtual()) and next(self.mark) == nil then
@@ -430,7 +430,7 @@ end
 
 --- 比较两张卡牌的花色是否相同
 ---@param anotherCard Card @ 另一张卡牌
----@param diff boolean @ 比较二者相同还是不同
+---@param diff boolean|nil @ 比较二者相同还是不同
 ---@return boolean 返回比较结果
 function Card:compareSuitWith(anotherCard, diff)
   if self ~= anotherCard and table.contains({ self.suit, anotherCard.suit }, Card.NoSuit) then

lua/core/game_mode.lua

@@ -10,7 +10,6 @@
 ---@field public maxPlayer integer @ 最大玩家数
 ---@field public rule TriggerSkill @ 规则（通过技能完成，通常用来为特定角色及特定时机提供触发事件）
 ---@field public logic fun() @ 逻辑（通过function完成，通常用来初始化、分配身份及座次）
----@field public surrenderFunc fun()
 ---@field public whitelist string[]|nil @ 白名单
 ---@field public blacklist string[]|nil @ 黑名单
 local GameMode = class("GameMode")
@@ -19,7 +18,6 @@ local GameMode = class("GameMode")
 ---@param name string @ 游戏模式名
 ---@param min integer @ 最小玩家数
 ---@param max integer @ 最大玩家数
----@param filter string @ 过滤卡包，格式参考exppattern
 function GameMode:initialize(name, min, max)
   self.name = name
   self.minPlayer = math.max(min, 2)

lua/core/player.lua

@@ -103,10 +103,10 @@ end
 
 --- 设置角色、体力、技能。
 ---@param general General @ 角色类型
----@param setHp boolean @ 是否设置体力
+---@param setHp boolean|nil @ 是否设置体力
----@param addSkills boolean @ 是否增加技能
+---@param addSkills boolean|nil @ 是否增加技能
 function Player:setGeneral(general, setHp, addSkills)
-  self.general = general
+  self.general = general.name
   if setHp then
     self.maxHp = general.maxHp
     self.hp = general.hp
@@ -182,7 +182,7 @@ end
 
 --- 为角色设置Mark至指定数量。
 ---@param mark string @ 标记
----@param count integer @ 为标记删除的数量
+---@param count integer|nil @ 为标记删除的数量
 function Player:setMark(mark, count)
   if count == 0 then count = nil end
   if self.mark[mark] ~= count then
@@ -192,7 +192,7 @@ end
 
 --- 获取角色对应Mark的数量。
 ---@param mark string @ 标记
----@return integer
+---@return any
 function Player:getMark(mark)
   return (self.mark[mark] or 0)
 end
@@ -217,7 +217,7 @@ end
 --- 将指定数量的牌加入玩家的对应区域。
 ---@param playerArea PlayerCardArea @ 玩家牌所在的区域
 ---@param cardIds integer[] @ 牌的ID，返回唯一牌
----@param specialName string @ 私人牌堆名
+---@param specialName string|nil @ 私人牌堆名
 function Player:addCards(playerArea, cardIds, specialName)
   assert(table.contains({ Player.Hand, Player.Equip, Player.Judge, Player.Special }, playerArea))
   assert(playerArea ~= Player.Special or type(specialName) == "string")
@@ -233,7 +233,7 @@ end
 --- 将指定数量的牌移除出玩家的对应区域。
 ---@param playerArea PlayerCardArea @ 玩家牌所在的区域
 ---@param cardIds integer[] @ 牌的ID，返回唯一牌
----@param specialName string @ 私人牌堆名
+---@param specialName string|nil @ 私人牌堆名
 function Player:removeCards(playerArea, cardIds, specialName)
   assert(table.contains({ Player.Hand, Player.Equip, Player.Judge, Player.Special }, playerArea))
   assert(playerArea ~= Player.Special or type(specialName) == "string")
@@ -303,12 +303,25 @@ function Player:hasDelayedTrick(card_name)
 end
 
 --- 获取玩家特定区域所有牌的ID。
----@param playerAreas PlayerCardArea|nil @ 玩家牌所在的区域
+---@param playerAreas PlayerCardArea|PlayerCardArea[]|string|nil @ 玩家牌所在的区域
 ---@param specialName string|nil @私人牌堆名
 ---@return integer[] @ 返回对应区域的所有牌对应的ID
 function Player:getCardIds(playerAreas, specialName)
   local rightAreas = { Player.Hand, Player.Equip, Player.Judge }
   playerAreas = playerAreas or rightAreas
+  if type(playerAreas) == "string" then
+    local str = playerAreas
+    playerAreas = {}
+    if str:find("h") then
+      table.insert(playerAreas, Player.Hand)
+    end
+    if str:find("e") then
+      table.insert(playerAreas, Player.Equip)
+    end
+    if str:find("j") then
+      table.insert(playerAreas, Player.Judge)
+    end
+  end
   assert(type(playerAreas) == "number" or type(playerAreas) == "table")
   local areas = type(playerAreas) == "table" and playerAreas or { playerAreas }
 
@@ -404,14 +417,14 @@ end
 ---@param other Player @ 其他玩家
 ---@param num integer @ 距离数
 function Player:setFixedDistance(other, num)
-  print(self.name .. ": fixedDistance is deprecated. Use fixed_func instead.")
+  --print(self.name .. ": fixedDistance is deprecated. Use fixed_func instead.")
   self.fixedDistance[other] = num
 end
 
 --- 移除玩家与其他角色的固定距离。
 ---@param other Player @ 其他玩家
 function Player:removeFixedDistance(other)
-  print(self.name .. ": fixedDistance is deprecated. Use fixed_func instead.")
+  --print(self.name .. ": fixedDistance is deprecated. Use fixed_func instead.")
   self.fixedDistance[other] = nil
 end
 
@@ -506,7 +519,7 @@ end
 
 --- 增加玩家使用特定牌的历史次数。
 ---@param cardName string @ 牌名
----@param num integer @ 次数
+---@param num integer|nil @ 次数
 function Player:addCardUseHistory(cardName, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -521,7 +534,7 @@ end
 --- 设定玩家使用特定牌的历史次数。
 ---@param cardName string @ 牌名
 ---@param num integer @ 次数
----@param scope integer @ 查询历史范围
+---@param scope integer|nil @ 查询历史范围
 function Player:setCardUseHistory(cardName, num, scope)
   if cardName == "" and num == nil and scope == nil then
     self.cardUsedHistory = {}
@@ -543,7 +556,7 @@ end
 
 --- 增加玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param num integer @ 次数
+---@param num integer|nil @ 次数
 function Player:addSkillUseHistory(skill_name, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -557,8 +570,8 @@ end
 
 --- 设定玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param num integer @ 次数
+---@param num integer|nil @ 次数
----@param scope integer @ 查询历史范围
+---@param scope integer|nil @ 查询历史范围
 function Player:setSkillUseHistory(skill_name, num, scope)
   if skill_name == "" and num == nil and scope == nil then
     self.skillUsedHistory = {}
@@ -590,7 +603,7 @@ end
 
 --- 获取玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param scope integer @ 查询历史范围
+---@param scope integer|nil @ 查询历史范围
 function Player:usedSkillTimes(skill_name, scope)
   if not self.skillUsedHistory[skill_name] then
     return 0
@@ -808,16 +821,16 @@ function Player:prohibitDiscard(card)
   return false
 end
 
----@field SwitchYang number @ 转换技状态阳
+--转换技状态阳
 fk.SwitchYang = 0
----@field SwitchYin number @ 转换技状态阴
+--转换技状态阴
 fk.SwitchYin = 1
 
 --- 获取转换技状态
 ---@param skillName string @ 技能名
 ---@param afterUse boolean|nil @ 是否提前计算转换后状态
 ---@param inWord boolean|nil @ 是否返回文字
----@return number @ 转换技状态
+---@return number|string @ 转换技状态
 function Player:getSwitchSkillState(skillName, afterUse, inWord)
   if afterUse then
     return self:getMark(MarkEnum.SwithSkillPreName .. skillName) < 1 and (inWord and "yin" or fk.SwitchYin) or (inWord and "yang" or fk.SwitchYang)

lua/core/skill_type/attack_range.lua

@@ -4,7 +4,6 @@
 local AttackRangeSkill = StatusSkill:subclass("AttackRangeSkill")
 
 ---@param from Player
----@param to Player
 ---@return integer
 function AttackRangeSkill:getCorrect(from)
   return 0

lua/core/skill_type/max_cards.lua

@@ -3,19 +3,16 @@
 ---@class MaxCardsSkill : StatusSkill
 local MaxCardsSkill = StatusSkill:subclass("MaxCardsSkill")
 
----@param from Player
+---@return integer|nil
----@return integer
 function MaxCardsSkill:getFixed(player)
   return nil
 end
 
----@param from Player
 ---@return integer
 function MaxCardsSkill:getCorrect(player)
   return 0
 end
 
----@param from Player
 ---@param card Card
 ---@return boolean
 function MaxCardsSkill:excludeFrom(player, card)

lua/core/skill_type/view_as.lua

@@ -18,7 +18,7 @@ function ViewAsSkill:cardFilter(to_select, selected)
 end
 
 ---@param cards integer[] @ ids of cards
----@return card
+---@return Card|nil
 function ViewAsSkill:viewAs(cards)
   return nil
 end

lua/core/util.lua

@@ -48,7 +48,7 @@ function table:forEach(func)
   end
 end
 
----@param func fun(element, index, array)
+---@param func fun(element, index, array): any
 function table:every(func)
   for i, v in ipairs(self) do
     if not func(v, i, self) then
@@ -58,7 +58,7 @@ function table:every(func)
   return true
 end
 
----@param func fun(element, index, array)
+---@param func fun(element, index, array): any
 function table:find(func)
   for i, v in ipairs(self) do
     if func(v, i, self) then
@@ -70,7 +70,7 @@ end
 
 ---@generic T
 ---@param self T[]
----@param func fun(element, index, array)
+---@param func fun(element, index, array): any
 ---@return T[]
 function table.filter(self, func)
   local ret = {}
@@ -82,7 +82,7 @@ function table.filter(self, func)
   return ret
 end
 
----@param func fun(element, index, array)
+---@param func fun(element, index, array): any
 function table:map(func)
   local ret = {}
   for i, v in ipairs(self) do

lua/fk_ex.lua

@@ -162,14 +162,14 @@ function fk.CreateTriggerSkill(spec)
 end
 
 ---@class ActiveSkillSpec: UsableSkillSpec
----@field public can_use fun(self: ActiveSkill, player: Player, card: Card): boolean
+---@field public can_use fun(self: ActiveSkill, player: Player, card: Card): boolean|nil
----@field public card_filter fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_targets: integer[]): boolean
+---@field public card_filter fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_targets: integer[]): boolean|nil
----@field public target_filter fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_cards: integer[], card: Card): boolean
+---@field public target_filter fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_cards: integer[], card: Card): boolean|nil
----@field public feasible fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): boolean
+---@field public feasible fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): boolean|nil
 ---@field public on_use fun(self: ActiveSkill, room: Room, cardUseEvent: CardUseStruct): boolean|nil
----@field public about_to_effect fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean
+---@field public about_to_effect fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean|nil
 ---@field public on_effect fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean|nil
----@field public on_nullified fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean
+---@field public on_nullified fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean|nil
 ---@field public prompt fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): string
 
 ---@param spec ActiveSkillSpec
@@ -211,12 +211,12 @@ function fk.CreateActiveSkill(spec)
 end
 
 ---@class ViewAsSkillSpec: UsableSkillSpec
----@field public card_filter fun(self: ViewAsSkill, to_select: integer, selected: integer[]): boolean
+---@field public card_filter fun(self: ViewAsSkill, to_select: integer, selected: integer[]): boolean|nil
----@field public view_as fun(self: ViewAsSkill, cards: integer[])
+---@field public view_as fun(self: ViewAsSkill, cards: integer[]): Card|nil
 ---@field public pattern string
----@field public enabled_at_play fun(self: ViewAsSkill, player: Player): boolean
+---@field public enabled_at_play fun(self: ViewAsSkill, player: Player): boolean|nil
----@field public enabled_at_response fun(self: ViewAsSkill, player: Player): boolean
+---@field public enabled_at_response fun(self: ViewAsSkill, player: Player, response: boolean): boolean|nil
----@field public before_use fun(self: ViewAsSkill, player: ServerPlayer)
+---@field public before_use fun(self: ViewAsSkill, player: ServerPlayer, use: CardUseStruct)
 ---@field public prompt fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): string
 
 ---@param spec ViewAsSkillSpec
@@ -267,8 +267,8 @@ function fk.CreateViewAsSkill(spec)
 end
 
 ---@class DistanceSpec: StatusSkillSpec
----@field public correct_func fun(self: DistanceSkill, from: Player, to: Player)
+---@field public correct_func fun(self: DistanceSkill, from: Player, to: Player): integer|nil
----@field public fixed_func fun(self: DistanceSkill, from: Player, to: Player)
+---@field public fixed_func fun(self: DistanceSkill, from: Player, to: Player): integer|nil
 
 ---@param spec DistanceSpec
 ---@return DistanceSkill
@@ -285,10 +285,10 @@ function fk.CreateDistanceSkill(spec)
 end
 
 ---@class ProhibitSpec: StatusSkillSpec
----@field public is_prohibited fun(self: ProhibitSkill, from: Player, to: Player, card: Card)
+---@field public is_prohibited fun(self: ProhibitSkill, from: Player, to: Player, card: Card): boolean|nil
----@field public prohibit_use fun(self: ProhibitSkill, player: Player, card: Card)
+---@field public prohibit_use fun(self: ProhibitSkill, player: Player, card: Card): boolean|nil
----@field public prohibit_response fun(self: ProhibitSkill, player: Player, card: Card)
+---@field public prohibit_response fun(self: ProhibitSkill, player: Player, card: Card): boolean|nil
----@field public prohibit_discard fun(self: ProhibitSkill, player: Player, card: Card)
+---@field public prohibit_discard fun(self: ProhibitSkill, player: Player, card: Card): boolean|nil
 
 ---@param spec ProhibitSpec
 ---@return ProhibitSkill
@@ -306,8 +306,8 @@ function fk.CreateProhibitSkill(spec)
 end
 
 ---@class AttackRangeSpec: StatusSkillSpec
----@field public correct_func fun(self: AttackRangeSkill, from: Player)
+---@field public correct_func fun(self: AttackRangeSkill, from: Player, to: Player): number|nil
----@field public within_func fun(self: AttackRangeSkill, from: Player, to: Player)
+---@field public within_func fun(self: AttackRangeSkill, from: Player, to: Player): boolean|nil
 
 ---@param spec AttackRangeSpec
 ---@return AttackRangeSkill
@@ -328,9 +328,9 @@ function fk.CreateAttackRangeSkill(spec)
 end
 
 ---@class MaxCardsSpec: StatusSkillSpec
----@field public correct_func fun(self: MaxCardsSkill, player: Player)
+---@field public correct_func fun(self: MaxCardsSkill, player: Player): number|nil
----@field public fixed_func fun(self: MaxCardsSkill, player: Player)
+---@field public fixed_func fun(self: MaxCardsSkill, player: Player): number|nil
----@field public exclude_from fun(self: MaxCardsSkill, player: Player, card: Card)
+---@field public exclude_from fun(self: MaxCardsSkill, player: Player, card: Card): boolean|nil
 
 ---@param spec MaxCardsSpec
 ---@return MaxCardsSkill
@@ -352,11 +352,11 @@ function fk.CreateMaxCardsSkill(spec)
 end
 
 ---@class TargetModSpec: StatusSkillSpec
----@field public bypass_times fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player)
+---@field public bypass_times fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): boolean|nil
----@field public residue_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player)
+---@field public residue_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): number|nil
----@field public bypass_distances fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player)
+---@field public bypass_distances fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): boolean|nil
----@field public distance_limit_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player)
+---@field public distance_limit_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): number|nil
----@field public extra_target_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card)
+---@field public extra_target_func fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card): number|nil
 
 ---@param spec TargetModSpec
 ---@return TargetModSkill
@@ -385,8 +385,8 @@ function fk.CreateTargetModSkill(spec)
 end
 
 ---@class FilterSpec: StatusSkillSpec
----@field public card_filter fun(self: FilterSkill, card: Card, player: Player)
+---@field public card_filter fun(self: FilterSkill, card: Card, player: Player): boolean|nil
----@field public view_as fun(self: FilterSkill, card: Card, player: Player)
+---@field public view_as fun(self: FilterSkill, card: Card, player: Player): Card|nil
 
 ---@param spec FilterSpec
 ---@return FilterSkill
@@ -402,7 +402,7 @@ function fk.CreateFilterSkill(spec)
 end
 
 ---@class InvaliditySpec: StatusSkillSpec
----@field public invalidity_func fun(self: InvaliditySkill, from: Player, skill: Skill)
+---@field public invalidity_func fun(self: InvaliditySkill, from: Player, skill: Skill): boolean|nil
 
 ---@param spec InvaliditySpec
 ---@return InvaliditySkill

lua/lib/debugger.lua

@@ -24,6 +24,7 @@
 	* Properly handle being reentrant due to coroutines.
 ]]
 
+---@diagnostic disable
 -- notify 汉化 并根据fk/lua 5.4实际情况魔改
 
 local dbg

lua/lib/inspect.lua

@@ -1,6 +1,6 @@
 local _tl_compat; if (tonumber((_VERSION or ''):match('[%d.]*$')) or 0) < 5.3 then local p, m = pcall(require, 'compat53.module'); if p then _tl_compat = m end end; local math = _tl_compat and _tl_compat.math or math; local string = _tl_compat and _tl_compat.string or string; local table = _tl_compat and _tl_compat.table or table
 local inspect = {Options = {}, }
-
+---@diagnostic disable
 
 
 

lua/server/ai/ai.lua

@@ -8,7 +8,7 @@
 ---@field public player ServerPlayer
 ---@field public command string
 ---@field public jsonData string
----@field public cb_table table<string, fun(jsonData: string)>
+---@field public cb_table table<string, fun(self: AI, jsonData: string)>
 local AI = class("AI")
 
 function AI:initialize(player)

lua/server/gameevent.lua

@@ -15,13 +15,13 @@
 ---@field public interrupted boolean @ 事件是否是因为被强行中断而结束的
 local GameEvent = class("GameEvent")
 
----@type fun(self: GameEvent)[]
+---@type (fun(self: GameEvent): boolean|nil)[]
 GameEvent.functions = {}
 
----@type fun(self: GameEvent)[]
+---@type (fun(self: GameEvent): boolean|nil)[]
 GameEvent.cleaners = {}
 
----@type fun(self: GameEvent)[]
+---@type (fun(self: GameEvent): boolean|nil)[]
 GameEvent.exit_funcs = {}
 
 local function wrapCoFunc(f, ...)
@@ -45,6 +45,11 @@ function GameEvent:initialize(event, ...)
   self.interrupted = false
 end
 
+-- 静态函数，实际定义在events/init.lua
+function GameEvent:translate(id)
+  error('static')
+end
+
 function GameEvent:__tostring()
   return string.format("<%s #%d>", GameEvent:translate(self.event), self.id)
 end
@@ -159,7 +164,7 @@ function GameEvent:clear()
       -- handle error, then break
       if not string.find(yield_result, "__manuallyBreak") then
         fk.qCritical(yield_result)
-        print(debug.traceback(co))
+        print(debug.traceback(clear_co))
       end
       coroutine.close(clear_co)
       break

lua/server/mark_enum.lua

@@ -2,36 +2,36 @@
 
 MarkEnum = {}
 
----@field StraightToWake string @ 跳过觉醒标记(值为技能名通过+连接)
+-- 跳过觉醒标记(值为技能名通过+连接)
 MarkEnum.StraightToWake = "_straight_to_wake"
 
----@field SwithSkillPreName string @ 转换技状态标记前缀（整体为前缀+转换技技能）
+--转换技状态标记前缀（整体为前缀+转换技技能）
 MarkEnum.SwithSkillPreName = "__switcher_"
----@field QuestSkillPreName string @ 使命技状态标记前缀（整体为前缀+使命技技能）
+--使命技状态标记前缀（整体为前缀+使命技技能）
 MarkEnum.QuestSkillPreName = "__questPre_"
 
----@field AddMaxCards string @ 增加标记值数量的手牌上限
+--增加标记值数量的手牌上限
 MarkEnum.AddMaxCards = "AddMaxCards"
----@field AddMaxCardsInTurn string @ 于本回合内增加标记值数量的手牌上限
+--于本回合内增加标记值数量的手牌上限
 MarkEnum.AddMaxCardsInTurn = "AddMaxCards-turn"
----@field MinusMaxCards string @ 减少标记值数量的手牌上限
+--减少标记值数量的手牌上限
 MarkEnum.MinusMaxCards = "MinusMaxCards"
----@field AddMaxCards string @ 于本回合内减少标记值数量的手牌上限
+--于本回合内减少标记值数量的手牌上限
 MarkEnum.MinusMaxCardsInTurn = "MinusMaxCards-turn"
 
----@field BypassTimesLimit string @ 使用牌无次数限制，可带清除标记后缀
+--使用牌无次数限制，可带清除标记后缀
 MarkEnum.BypassTimesLimit = "BypassTimesLimit"
----@field BypassDistancesLimit string @ 使用牌无距离限制，可带清除标记后缀
+--使用牌无距离限制，可带清除标记后缀
 MarkEnum.BypassDistancesLimit = "BypassDistancesLimit"
----@field BypassTimesLimitTo string @ 对其使用牌无次数限制，可带清除标记后缀
+--对其使用牌无次数限制，可带清除标记后缀
 MarkEnum.BypassTimesLimitTo = "BypassTimesLimitTo"
----@field BypassDistancesLimitTo string @ 对其使用牌无距离限制，可带清除标记后缀
+--对其使用牌无距离限制，可带清除标记后缀
 MarkEnum.BypassDistancesLimitTo = "BypassDistancesLimitTo"
----@field UncompulsoryInvalidity string @ 非锁定技失效，可带清除标记后缀
+--非锁定技失效，可带清除标记后缀
 MarkEnum.UncompulsoryInvalidity = "UncompulsoryInvalidity"
 
----@field TempMarkSuffix string[] @ 各种清除标记后缀
+--各种清除标记后缀
 MarkEnum.TempMarkSuffix = { "-phase", "-turn", "-round" }
 
----@field CardTempMarkSuffix string[] @ 卡牌标记版本的清除标记后缀
+---卡牌标记版本的清除标记后缀
 MarkEnum.CardTempMarkSuffix = { "-phase", "-turn", "-round", "-inhand" }

lua/server/room.lua

@@ -230,7 +230,7 @@ end
 --- 基本算是私有函数，别去用
 ---@param cardId integer
 ---@param cardArea CardArea
----@param integer owner
+---@param owner integer
 function Room:setCardArea(cardId, cardArea, owner)
   self.card_place[cardId] = cardArea
   self.owner_map[cardId] = owner
@@ -311,7 +311,7 @@ end
 --- 获得当前房间中的所有玩家。
 ---
 --- 返回的数组的第一个元素是当前回合玩家，并且按行动顺序进行排序。
----@param sortBySeat boolean @ 是否无视按座位排序直接返回
+---@param sortBySeat boolean|nil @ 是否无视按座位排序直接返回
 ---@return ServerPlayer[] @ 房间中玩家的数组
 function Room:getAllPlayers(sortBySeat)
   if not self.game_started then
@@ -431,7 +431,7 @@ end
 --- 在设置之后，会通知所有客户端也更新一下标记的值。之后的两个相同
 ---@param player ServerPlayer @ 要被更新标记的那个玩家
 ---@param mark string @ 标记的名称
----@param value integer @ 要设为的值，其实也可以设为字符串
+---@param value any @ 要设为的值，其实也可以设为字符串
 function Room:setPlayerMark(player, mark, value)
   player:setMark(mark, value)
   self:doBroadcastNotify("SetPlayerMark", json.encode{
@@ -468,7 +468,7 @@ end
 --- 在设置之后，会通知所有客户端也更新一下标记的值。之后的两个相同
 ---@param card Card @ 要被更新标记的那张牌
 ---@param mark string @ 标记的名称
----@param value integer @ 要设为的值，其实也可以设为字符串
+---@param value any @ 要设为的值，其实也可以设为字符串
 function Room:setCardMark(card, mark, value)
   card:setMark(mark, value)
   if not card:isVirtual() then
@@ -531,7 +531,7 @@ end
 
 ---@param player ServerPlayer
 ---@param general string
----@param changeKingdom boolean
+---@param changeKingdom boolean|nil
 ---@param noBroadcast boolean|null
 function Room:setPlayerGeneral(player, general, changeKingdom, noBroadcast)
   if Fk.generals[general] == nil then return end
@@ -559,7 +559,7 @@ function Room:setDeputyGeneral(player, general)
 end
 
 ---@param player ServerPlayer @ 要换将的玩家
----@param new_general string|nil @ 要变更的武将，若不存在则变身为孙策，孙策也不存在则nil错
+---@param new_general string @ 要变更的武将，若不存在则变身为孙策，孙策也不存在则nil错
 ---@param full boolean|nil @ 是否血量满状态变身
 ---@param isDeputy boolean|nil @ 是否变的是副将
 ---@param sendLog boolean|nil @ 是否发Log
@@ -1376,7 +1376,7 @@ end
 ---@param top_limit integer[]|nil @ 置于牌堆顶的牌的限制(下限,上限)，不填写则不限
 ---@param bottom_limit integer[]|nil @ 置于牌堆底的牌的限制(下限,上限)，不填写则不限
 ---@param customNotify string|null @ 自定义读条操作提示
----@param prompt string|null @ 观星框的标题(暂时雪藏)
+--@param prompt string|null @ 观星框的标题(暂时雪藏)
 ---@param noPut boolean|null @ 是否进行放置牌操作
 ---@param areaNames string[]|null @ 左侧提示信息
 ---@return table<"top"|"bottom", integer[]>
@@ -1716,8 +1716,8 @@ end
 --- 询问玩家从AG中选择一张牌。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param id_list integer[] | Card[] @ 可选的卡牌列表
----@param cancelable boolean @ 能否点取消
+---@param cancelable boolean|nil @ 能否点取消
----@param reason string @ 原因
+---@param reason string|nil @ 原因
 ---@return integer @ 选择的卡牌
 function Room:askForAG(player, id_list, cancelable, reason)
   id_list = Card:getIdList(id_list)
@@ -1748,7 +1748,7 @@ end
 --- 告诉一些玩家，AG中的牌被taker取走了。
 ---@param taker ServerPlayer @ 拿走牌的玩家
 ---@param id integer @ 被拿走的牌
----@param notify_list ServerPlayer[] @ 要告知的玩家，默认为全员
+---@param notify_list ServerPlayer[]|nil @ 要告知的玩家，默认为全员
 function Room:takeAG(taker, id, notify_list)
   self:doBroadcastNotify("TakeAG", json.encode{ taker.id, id }, notify_list)
 end
@@ -1756,7 +1756,7 @@ end
 --- 关闭player那侧显示的AG。
 ---
 --- 若不传参（即player为nil），那么关闭所有玩家的AG。
----@param player ServerPlayer @ 要关闭AG的玩家
+---@param player ServerPlayer|nil @ 要关闭AG的玩家
 function Room:closeAG(player)
   if player then player:doNotify("CloseAG", "")
   else self:doBroadcastNotify("CloseAG", "") end
@@ -1880,7 +1880,7 @@ end
 ---@param skillName string @ 技能名
 ---@param cancelable boolean|null @ 是否可以取消选择
 ---@param flag string|null @ 限定可移动的区域，值为nil（装备区和判定区）、‘e’或‘j’
----@param no_indicate boolean @ 是否不显示指示线
+---@param no_indicate boolean|nil @ 是否不显示指示线
 ---@return integer[] @ 选择的玩家id列表，可能为空
 function Room:askForChooseToMoveCardInBoard(player, prompt, skillName, cancelable, flag, no_indicate)
   if flag then
@@ -2337,11 +2337,11 @@ function Room:responseCard(cardResponseEvent)
 end
 
 ---@param card_name string @ 想要视为使用的牌名
----@param subcards integer[] @ 子卡，可以留空或者直接nil
+---@param subcards integer[]|nil @ 子卡，可以留空或者直接nil
 ---@param from ServerPlayer @ 使用来源
 ---@param tos ServerPlayer | ServerPlayer[] @ 目标角色（列表）
----@param skillName string @ 技能名
+---@param skillName string|nil @ 技能名
----@param extra boolean @ 是否不计入次数
+---@param extra boolean|nil @ 是否不计入次数
 function Room:useVirtualCard(card_name, subcards, from, tos, skillName, extra)
   local card = Fk:cloneCard(card_name)
   card.skillName = skillName
@@ -2383,8 +2383,8 @@ end
 --- 让一名玩家获得一张牌
 ---@param player integer|ServerPlayer @ 要拿牌的玩家
 ---@param cid integer|Card @ 要拿到的卡牌
----@param unhide boolean @ 是否明着拿
+---@param unhide boolean|nil @ 是否明着拿
----@param reason CardMoveReason @ 卡牌移动的原因
+---@param reason CardMoveReason|nil @ 卡牌移动的原因
 function Room:obtainCard(player, cid, unhide, reason)
   if type(cid) ~= "number" then
     assert(cid and cid:isInstanceOf(Card))
@@ -2503,7 +2503,7 @@ end
 --- 令一名玩家失去体力。
 ---@param player ServerPlayer @ 玩家
 ---@param num integer @ 失去的数量
----@param skillName string @ 技能名
+---@param skillName string|nil @ 技能名
 ---@return boolean
 function Room:loseHp(player, num, skillName)
   return execGameEvent(GameEvent.LoseHp, player, num, skillName)

lua/server/serverplayer.lua

@@ -561,7 +561,7 @@ end
 ---@param pile_name string
 ---@param card integer|Card
 ---@param visible boolean
----@param skillName string
+---@param skillName string|nil
 function ServerPlayer:addToPile(pile_name, card, visible, skillName)
   local room = self.room
   room:moveCardTo(card, Card.PlayerSpecial, self, fk.ReasonJustMove, skillName, pile_name, visible)
@@ -668,10 +668,10 @@ function ServerPlayer:reset()
   if not self.faceup then self:turnOver() end
 end
 
----@param from ServerPlayer
+--@param from ServerPlayer
 ---@param tos ServerPlayer[]
 ---@param skillName string
----@param initialCard Card
+---@param initialCard Card|nil
 ---@return PindianStruct
 function ServerPlayer:pindian(tos, skillName, initialCard)
   local pindianData = { from = self, tos = tos, reason = skillName, fromCard = initialCard, results = {} }
@@ -759,6 +759,7 @@ end
 
 -- 神貂蝉
 
+---@param p ServerPlayer
 function ServerPlayer:control(p)
   if self == p then
     self.room:setPlayerMark(p, "@ControledBy", 0)

test/lua/lib/luaunit.lua

@@ -8,6 +8,7 @@ Based on initial work of Ryu, Gwang (http://www.gpgstudy.com/gpgiki/LuaUnit)
 License: BSD License, see LICENSE.txt
 ]]--
 
+---@diagnostic disable
 local os, io = os, io
 require("math")
 local M={}