diff --git a/lua/core/card.lua b/lua/core/card.lua
index 908b754a..4a292c86 100644
--- a/lua/core/card.lua
+++ b/lua/core/card.lua
@@ -21,10 +21,10 @@
 ---@field private _skillName string
 ---@field public skillNames string[] @ 虚拟牌的技能名们（一张虚拟牌可能有多个技能名，如芳魂、龙胆、朱雀羽扇）
 ---@field public skill Skill @ 技能（用于实现卡牌效果）
----@field public special_skills string[] | nil @ 衍生技能，如重铸
+---@field public special_skills? string[] @ 衍生技能，如重铸
 ---@field public is_damage_card boolean @ 是否为会造成伤害的牌
 ---@field public multiple_targets boolean @ 是否为指定多个目标的牌
----@field public is_derived bool @ 判断是否为衍生牌
+---@field public is_derived? boolean @ 判断是否为衍生牌
 local Card = class("Card")
 
 ---@alias Suit integer
@@ -136,8 +136,8 @@ end
 --- 克隆特定卡牌并赋予花色与点数。
 ---
 --- 会将skill/special_skills/equip_skill继承到克隆牌中。
----@param suit Suit|nil @ 克隆后的牌的花色
----@param number integer|nil @ 克隆后的牌的点数
+---@param suit? Suit @ 克隆后的牌的花色
+---@param number? integer @ 克隆后的牌的点数
 ---@return Card @ 产品
 function Card:clone(suit, number)
   local newCard = self.class:new(self.name, suit, number)
@@ -157,7 +157,7 @@ end
 --- 获取卡牌的ID。
 ---
 --- 如果牌是虚拟牌，则返回其第一张子卡的id，没有子卡就返回nil
----@return integer | nil
+---@return integer?
 function Card:getEffectiveId()
   if self:isVirtual() then
     return #self.subcards > 0 and self.subcards[1] or nil
@@ -236,7 +236,7 @@ function Card:matchPattern(pattern)
 end
 
 --- 获取卡牌花色并返回花色文字描述（如 黑桃、红桃、梅花、方块）或者符号（如♠♥♣♦，带颜色）。
----@param symbol bool @ 是否以符号形式显示
+---@param symbol? boolean @ 是否以符号形式显示
 ---@return string @ 描述花色的字符串
 function Card:getSuitString(symbol)
   local suit = self.suit
@@ -428,7 +428,7 @@ end
 
 --- 比较两张卡牌的花色是否相同
 ---@param anotherCard Card @ 另一张卡牌
----@param diff bool @ 比较二者相同还是不同
+---@param diff? boolean @ 比较二者相同还是不同
 ---@return boolean 返回比较结果
 function Card:compareSuitWith(anotherCard, diff)
   if self ~= anotherCard and table.contains({ self.suit, anotherCard.suit }, Card.NoSuit) then
diff --git a/lua/core/engine.lua b/lua/core/engine.lua
index c9d33f53..cf4a568a 100644
--- a/lua/core/engine.lua
+++ b/lua/core/engine.lua
@@ -167,7 +167,7 @@ end
 
 --- 向翻译表中加载新的翻译表。
 ---@param t table @ 要加载的翻译表，这是一个 原文 --> 译文 的键值对表
----@param lang string|nil @ 目标语言，默认为zh_CN
+---@param lang? string @ 目标语言，默认为zh_CN
 function Engine:loadTranslationTable(t, lang)
   assert(type(t) == "table")
   lang = lang or "zh_CN"
@@ -179,8 +179,9 @@ end
 
 --- 翻译一段文本。其实就是从翻译表中去找
 ---@param src string @ 要翻译的文本
-function Engine:translate(src)
-  local lang = Config.language or "zh_CN"
+---@param lang? string @ 要使用的语言，默认读取config
+function Engine:translate(src, lang)
+  lang = lang or (Config.language or "zh_CN")
   if not self.translations[lang] then lang = "zh_CN" end
   local ret = self.translations[lang][src]
   return ret or src
@@ -306,8 +307,8 @@ end
 ---
 --- 返回的牌是一张虚拟牌。
 ---@param name string @ 牌名
----@param suit Suit|nil @ 花色
----@param number integer|nil @ 点数
+---@param suit? Suit @ 花色
+---@param number? integer @ 点数
 ---@return Card
 function Engine:cloneCard(name, suit, number)
   local cd = self.all_card_types[name]
@@ -355,9 +356,9 @@ end
 ---
 --- 如果符合条件的武将不够，那么就不能保证能选出那么多武将。
 ---@param num integer @ 要选出的武将数量
----@param generalPool General[] | nil @ 选择的范围，默认是已经启用的所有武将
----@param except string[] | nil @ 特别要排除掉的武将名列表，默认是空表
----@param filter nil | fun(g: General): boolean @ 可选参数，若这个函数返回true的话这个武将被排除在外
+---@param generalPool? General[] @ 选择的范围，默认是已经启用的所有武将
+---@param except? string[] @ 特别要排除掉的武将名列表，默认是空表
+---@param filter? fun(g: General): boolean? @ 可选参数，若这个函数返回true的话这个武将被排除在外
 ---@return General[] @ 随机选出的武将列表
 function Engine:getGeneralsRandomly(num, generalPool, except, filter)
   if filter then
@@ -390,7 +391,7 @@ function Engine:getGeneralsRandomly(num, generalPool, except, filter)
 end
 
 --- 获取已经启用的所有武将的列表。
----@param except General[] | nil @ 特别指明要排除在外的武将
+---@param except? General[] @ 特别指明要排除在外的武将
 ---@return General[] @ 所有武将的列表
 function Engine:getAllGenerals(except)
   local result = {}
@@ -406,7 +407,7 @@ function Engine:getAllGenerals(except)
 end
 
 --- 获取当前已经启用的所有卡牌。
----@param except integer[] | nil @ 特别指定要排除在外的id列表
+---@param except? integer[] @ 特别指定要排除在外的id列表
 ---@return integer[] @ 所有卡牌id的列表
 function Engine:getAllCardIds(except)
   local result = {}
@@ -423,7 +424,7 @@ end
 
 --- 根据id返回相应的卡牌。
 ---@param id integer @ 牌的id
----@param ignoreFilter bool @ 是否要无视掉锁定视为技，直接获得真牌
+---@param ignoreFilter? boolean @ 是否要无视掉锁定视为技，直接获得真牌
 ---@return Card @ 这个id对应的卡牌
 function Engine:getCardById(id, ignoreFilter)
   if id == nil then return nil end
diff --git a/lua/core/game_mode.lua b/lua/core/game_mode.lua
index 1c05c510..c44f88b2 100644
--- a/lua/core/game_mode.lua
+++ b/lua/core/game_mode.lua
@@ -8,10 +8,10 @@
 ---@field public name string @ 游戏模式名
 ---@field public minPlayer integer @ 最小玩家数
 ---@field public maxPlayer integer @ 最大玩家数
----@field public rule nil|TriggerSkill @ 规则（通过技能完成，通常用来为特定角色及特定时机提供触发事件）
----@field public logic nil|fun() @ 逻辑（通过function完成，通常用来初始化、分配身份及座次）
----@field public whitelist string[]|nil @ 白名单
----@field public blacklist string[]|nil @ 黑名单
+---@field public rule? TriggerSkill @ 规则（通过技能完成，通常用来为特定角色及特定时机提供触发事件）
+---@field public logic? fun(): GameLogic @ 逻辑（通过function完成，通常用来初始化、分配身份及座次）
+---@field public whitelist? string[] @ 白名单
+---@field public blacklist? string[] @ 黑名单
 local GameMode = class("GameMode")
 
 --- 构造函数，不可随意调用。
diff --git a/lua/core/package.lua b/lua/core/package.lua
index 283295bc..be6f4af7 100644
--- a/lua/core/package.lua
+++ b/lua/core/package.lua
@@ -13,8 +13,8 @@
 ---@field public related_skills table<string, string> @ 对于额外技能而言的关联技能
 ---@field public cards Card[] @ 拓展包包含的卡牌
 ---@field public game_modes GameMode[] @ 拓展包包含的游戏模式
----@field public game_modes_whitelist string[]|nil @ 拓展包关于游戏模式的白名单
----@field public game_modes_blacklist string[]|nil @ 拓展包关于游戏模式的黑名单
+---@field public game_modes_whitelist? string[] @ 拓展包关于游戏模式的白名单
+---@field public game_modes_blacklist? string[] @ 拓展包关于游戏模式的黑名单
 local Package = class("Package")
 
 ---@alias PackageType integer
@@ -25,7 +25,7 @@ Package.SpecialPack = 3
 
 --- 拓展包的构造函数。
 ---@param name string @ 包的名字
----@param _type integer|nil @ 包的类型，默认为武将包
+---@param _type? integer @ 包的类型，默认为武将包
 function Package:initialize(name, _type)
   assert(type(name) == "string")
   assert(type(_type) == "nil" or type(_type) == "number")
diff --git a/lua/core/player.lua b/lua/core/player.lua
index abc604db..b1cb839f 100644
--- a/lua/core/player.lua
+++ b/lua/core/player.lua
@@ -121,8 +121,8 @@ end
 
 --- 设置角色、体力、技能。
 ---@param general General @ 角色类型
----@param setHp bool @ 是否设置体力
----@param addSkills bool @ 是否增加技能
+---@param setHp? boolean @ 是否设置体力
+---@param addSkills? boolean @ 是否增加技能
 function Player:setGeneral(general, setHp, addSkills)
   self.general = general.name
   if setHp then
@@ -202,7 +202,7 @@ end
 
 --- 为角色设置Mark至指定数量。
 ---@param mark string @ 标记
----@param count integer|nil @ 为标记删除的数量
+---@param count? integer @ 为标记删除的数量
 function Player:setMark(mark, count)
   if count == 0 then count = nil end
   if self.mark[mark] ~= count then
@@ -237,7 +237,7 @@ end
 --- 将指定数量的牌加入玩家的对应区域。
 ---@param playerArea PlayerCardArea @ 玩家牌所在的区域
 ---@param cardIds integer[] @ 牌的ID，返回唯一牌
----@param specialName string|nil @ 私人牌堆名
+---@param specialName? string @ 私人牌堆名
 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")
@@ -253,7 +253,7 @@ end
 --- 将指定数量的牌移除出玩家的对应区域。
 ---@param playerArea PlayerCardArea @ 玩家牌所在的区域
 ---@param cardIds integer[] @ 牌的ID，返回唯一牌
----@param specialName string|nil @ 私人牌堆名
+---@param specialName? string @ 私人牌堆名
 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")
@@ -323,8 +323,8 @@ function Player:hasDelayedTrick(card_name)
 end
 
 --- 获取玩家特定区域所有牌的ID。
----@param playerAreas PlayerCardArea|PlayerCardArea[]|string|nil @ 玩家牌所在的区域
----@param specialName string|nil @私人牌堆名
+---@param playerAreas? PlayerCardArea|PlayerCardArea[]|string @ 玩家牌所在的区域
+---@param specialName? string @私人牌堆名
 ---@return integer[] @ 返回对应区域的所有牌对应的ID
 function Player:getCardIds(playerAreas, specialName)
   local rightAreas = { Player.Hand, Player.Equip, Player.Judge }
@@ -370,7 +370,7 @@ end
 
 --- 通过ID检索获取玩家是否存在对应私人牌堆。
 ---@param id integer @ 私人牌堆ID
----@return string|null
+---@return string?
 function Player:getPileNameOfId(id)
   for k, v in pairs(self.special_cards) do
     if table.contains(v, id) then return k end
@@ -379,7 +379,7 @@ end
 
 --- 返回所有“如手牌般使用或打出”的牌。
 --- 或者说，返回所有名字以“&”结尾的pile的牌。
----@param include_hand bool @ 是否包含真正的手牌
+---@param include_hand? boolean @ 是否包含真正的手牌
 ---@return integer[]
 function Player:getHandlyIds(include_hand)
   include_hand = include_hand or include_hand == nil
@@ -403,7 +403,7 @@ end
 
 --- 检索玩家装备区是否存在对应类型的装备。
 ---@param cardSubtype CardSubtype @ 卡牌子类
----@return integer|null @ 返回卡牌ID或nil
+---@return integer? @ 返回卡牌ID或nil
 function Player:getEquipment(cardSubtype)
   for _, cardId in ipairs(self.player_cards[Player.Equip]) do
     if Fk:getCardById(cardId).sub_type == cardSubtype then
@@ -491,8 +491,8 @@ end
 ---
 --- 通过 二者位次+距离技能之和 与 两者间固定距离 进行对比，更大的为实际距离。
 ---@param other Player @ 其他玩家
----@param mode string|nil @ 计算模式(left/right/both)
----@param ignore_dead bool @ 是否忽略尸体
+---@param mode? string @ 计算模式(left/right/both)
+---@param ignore_dead? boolean @ 是否忽略尸体
 function Player:distanceTo(other, mode, ignore_dead)
   assert(other:isInstanceOf(Player))
   mode = mode or "both"
@@ -546,7 +546,7 @@ end
 
 --- 获取其他玩家是否在玩家的攻击距离内。
 ---@param other Player @ 其他玩家
----@param fixLimit number|null @ 卡牌距离限制增加专用
+---@param fixLimit? integer @ 卡牌距离限制增加专用
 function Player:inMyAttackRange(other, fixLimit)
   assert(other:isInstanceOf(Player))
   if self == other or (other and (other.dead or other:isRemoved())) or self:isRemoved() then
@@ -567,8 +567,8 @@ function Player:inMyAttackRange(other, fixLimit)
 end
 
 --- 获取下家。
----@param ignoreRemoved bool @ 忽略被移除
----@param num interger|nil @ 第几个，默认1
+---@param ignoreRemoved? boolean @ 忽略被移除
+---@param num? integer @ 第几个，默认1
 ---@return ServerPlayer
 function Player:getNextAlive(ignoreRemoved, num)
   if #Fk:currentRoom().alive_players == 0 then
@@ -591,8 +591,8 @@ function Player:getNextAlive(ignoreRemoved, num)
 end
 
 --- 获取上家。
----@param ignoreRemoved bool @ 忽略被移除
----@param num interger|nil @ 第几个，默认1
+---@param ignoreRemoved boolean @ 忽略被移除
+---@param num? integer @ 第几个，默认1
 ---@return ServerPlayer
 function Player:getLastAlive(ignoreRemoved, num)
   num = num or 1
@@ -602,7 +602,7 @@ end
 
 --- 增加玩家使用特定牌的历史次数。
 ---@param cardName string @ 牌名
----@param num integer|nil @ 次数
+---@param num? integer @ 次数
 function Player:addCardUseHistory(cardName, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -617,7 +617,7 @@ end
 --- 设定玩家使用特定牌的历史次数。
 ---@param cardName string @ 牌名
 ---@param num integer @ 次数
----@param scope integer|nil @ 查询历史范围
+---@param scope? integer @ 历史范围 全为nil意为清空
 function Player:setCardUseHistory(cardName, num, scope)
   if cardName == "" and num == nil and scope == nil then
     self.cardUsedHistory = {}
@@ -639,7 +639,7 @@ end
 
 --- 增加玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param num integer|nil @ 次数
+---@param num? integer @ 次数 默认1
 function Player:addSkillUseHistory(skill_name, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -653,8 +653,8 @@ end
 
 --- 设定玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param num integer|nil @ 次数
----@param scope integer|nil @ 查询历史范围
+---@param num? integer @ 次数 默认0
+---@param scope? integer @ 查询历史范围
 function Player:setSkillUseHistory(skill_name, num, scope)
   if skill_name == "" and num == nil and scope == nil then
     self.skillUsedHistory = {}
@@ -675,7 +675,7 @@ end
 
 --- 获取玩家使用特定牌的历史次数。
 ---@param cardName string @ 牌名
----@param scope integer|nil @ 查询历史范围
+---@param scope? integer @ 查询历史范围，默认Turn
 function Player:usedCardTimes(cardName, scope)
   if not self.cardUsedHistory[cardName] then
     return 0
@@ -686,7 +686,7 @@ end
 
 --- 获取玩家使用特定技能的历史次数。
 ---@param skill_name string @ 技能名
----@param scope integer|nil @ 查询历史范围
+---@param scope? integer @ 查询历史范围，默认Turn
 function Player:usedSkillTimes(skill_name, scope)
   if not self.skillUsedHistory[skill_name] then
     return 0
@@ -732,8 +732,8 @@ end
 
 --- 检索玩家是否有对应技能。
 ---@param skill string | Skill @ 技能名
----@param ignoreNullified bool @ 忽略技能是否被无效
----@param ignoreAlive bool @ 忽略角色在场与否
+---@param ignoreNullified? boolean @ 忽略技能是否被无效
+---@param ignoreAlive? boolean @ 忽略角色在场与否
 function Player:hasSkill(skill, ignoreNullified, ignoreAlive)
   if not ignoreAlive and self.dead then
     return false
@@ -767,7 +767,7 @@ end
 
 --- 为玩家增加对应技能。
 ---@param skill string | Skill @ 技能名
----@param source_skill string | Skill | nil @ 本有技能（和衍生技能相对）
+---@param source_skill? string | Skill @ 本有技能（和衍生技能相对）
 ---@return Skill[] @ got skills that Player didn't have at start
 function Player:addSkill(skill, source_skill)
   skill = getActualSkill(skill)
@@ -813,7 +813,7 @@ end
 
 --- 为玩家删除对应技能。
 ---@param skill string | Skill @ 技能名
----@param source_skill string | Skill | nil @ 本有技能（和衍生技能相对）
+---@param source_skill? string | Skill @ 本有技能（和衍生技能相对）
 ---@return Skill[] @ lost skills that the Player doesn't have anymore
 function Player:loseSkill(skill, source_skill)
   skill = getActualSkill(skill)
@@ -944,8 +944,8 @@ fk.SwitchYin = 1
 
 --- 获取转换技状态
 ---@param skillName string @ 技能名
----@param afterUse bool @ 是否提前计算转换后状态
----@param inWord bool @ 是否返回文字
+---@param afterUse? boolean @ 是否提前计算转换后状态
+---@param inWord? boolean @ 是否返回文字
 ---@return number|string @ 转换技状态
 function Player:getSwitchSkillState(skillName, afterUse, inWord)
   if afterUse then
diff --git a/lua/core/skill_type/active.lua b/lua/core/skill_type/active.lua
index fb7e7f61..643a8e47 100644
--- a/lua/core/skill_type/active.lua
+++ b/lua/core/skill_type/active.lua
@@ -53,9 +53,9 @@ end
 --- Determine whether a target can be selected by this skill(in modifying targets)
 --- only used in skill of players
 ---@param to_select integer @ id of the target
----@param selected nil|integer[] @ ids of selected targets
----@param user nil|integer @ id of the userdata
----@param card nil|Card @ helper
+---@param selected? integer[] @ ids of selected targets
+---@param user? integer @ id of the userdata
+---@param card? Card @ helper
 ---@param distance_limited boolean @ is limited by distance
 function ActiveSkill:modTargetFilter(to_select, selected, user, card, distance_limited)
   return false
diff --git a/lua/core/skill_type/max_cards.lua b/lua/core/skill_type/max_cards.lua
index 5f3cec5d..295d3970 100644
--- a/lua/core/skill_type/max_cards.lua
+++ b/lua/core/skill_type/max_cards.lua
@@ -3,7 +3,7 @@
 ---@class MaxCardsSkill : StatusSkill
 local MaxCardsSkill = StatusSkill:subclass("MaxCardsSkill")
 
----@return integer|nil
+---@return integer?
 function MaxCardsSkill:getFixed(player)
   return nil
 end
diff --git a/lua/core/skill_type/trigger.lua b/lua/core/skill_type/trigger.lua
index 89ff283c..83b890f9 100644
--- a/lua/core/skill_type/trigger.lua
+++ b/lua/core/skill_type/trigger.lua
@@ -101,7 +101,7 @@ end
 ---@param target ServerPlayer @ Player who triggered this event
 ---@param player ServerPlayer @ Player who is operating
 ---@param data any @ useful data of the event
----@return bool
+---@return boolean?
 function TriggerSkill:use(event, target, player, data) end
 
 function TriggerSkill:canWake(event, target, player, data)
diff --git a/lua/core/skill_type/view_as.lua b/lua/core/skill_type/view_as.lua
index cd59f8f3..b8e695e9 100644
--- a/lua/core/skill_type/view_as.lua
+++ b/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|nil
+---@return Card?
 function ViewAsSkill:viewAs(cards)
   return nil
 end
diff --git a/lua/core/util.lua b/lua/core/util.lua
index d1f7f352..ded584c7 100644
--- a/lua/core/util.lua
+++ b/lua/core/util.lua
@@ -360,7 +360,7 @@ end
 
 ---@generic T
 ---@param self T[]
----@param n integer|nil
+---@param n? integer
 ---@return T|T[]
 function table:random(n)
   local n0 = n
diff --git a/lua/fk_ex.lua b/lua/fk_ex.lua
index 681b3c54..449ec452 100644
--- a/lua/fk_ex.lua
+++ b/lua/fk_ex.lua
@@ -75,26 +75,26 @@ local function readStatusSpecToSkill(skill, spec)
 end
 
 ---@class UsableSkillSpec: UsableSkill
----@field public max_phase_use_time nil|integer
----@field public max_turn_use_time nil|integer
----@field public max_round_use_time nil|integer
----@field public max_game_use_time nil|integer
+---@field public max_phase_use_time? integer
+---@field public max_turn_use_time? integer
+---@field public max_round_use_time? integer
+---@field public max_game_use_time? integer
 
 ---@class StatusSkillSpec: StatusSkill
 
----@alias TrigFunc fun(self: TriggerSkill, event: Event, target: ServerPlayer, player: ServerPlayer, data: any):bool
+---@alias TrigFunc fun(self: TriggerSkill, event: Event, target: ServerPlayer, player: ServerPlayer, data: any): boolean?
 ---@class TriggerSkillSpec: UsableSkillSpec
----@field public global bool
----@field public events nil|Event | Event[]
----@field public refresh_events nil|Event | Event[]
----@field public priority nil|number | table<Event, number>
----@field public on_trigger nil|TrigFunc
----@field public can_trigger nil|TrigFunc
----@field public on_cost nil|TrigFunc
----@field public on_use nil|TrigFunc
----@field public on_refresh nil|TrigFunc
----@field public can_refresh nil|TrigFunc
----@field public can_wake nil|TrigFunc
+---@field public global? boolean
+---@field public events? Event | Event[]
+---@field public refresh_events? Event | Event[]
+---@field public priority? number | table<Event, number>
+---@field public on_trigger? TrigFunc
+---@field public can_trigger? TrigFunc
+---@field public on_cost? TrigFunc
+---@field public on_use? TrigFunc
+---@field public on_refresh? TrigFunc
+---@field public can_refresh? TrigFunc
+---@field public can_wake? TrigFunc
 
 ---@param spec TriggerSkillSpec
 ---@return TriggerSkill
@@ -170,16 +170,16 @@ function fk.CreateTriggerSkill(spec)
 end
 
 ---@class ActiveSkillSpec: UsableSkillSpec
----@field public can_use nil|fun(self: ActiveSkill, player: Player, card: Card): bool
----@field public card_filter nil|fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_targets: integer[]): bool
----@field public target_filter nil|fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_cards: integer[], card: Card): bool
----@field public feasible nil|fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): bool
----@field public on_use nil|fun(self: ActiveSkill, room: Room, cardUseEvent: CardUseStruct): bool
----@field public about_to_effect nil|fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): bool
----@field public on_effect nil|fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): bool
----@field public on_nullified nil|fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): bool
----@field public mod_target_filter nil|fun(self: ActiveSkill, to_select: integer, selected: integer[], user: integer, card: Card, distance_limited: boolean): bool
----@field public prompt nil|string|fun(self: ActiveSkill, selected_cards: integer[], selected_targets: integer[]): string
+---@field public can_use? fun(self: ActiveSkill, player: Player, card: Card): boolean?
+---@field public card_filter? fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_targets: integer[]): boolean?
+---@field public target_filter? fun(self: ActiveSkill, to_select: integer, selected: integer[], selected_cards: integer[], card: Card): boolean?
+---@field public feasible? fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): boolean?
+---@field public on_use? fun(self: ActiveSkill, room: Room, cardUseEvent: CardUseStruct): boolean?
+---@field public about_to_effect? fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean?
+---@field public on_effect? fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean?
+---@field public on_nullified? fun(self: ActiveSkill, room: Room, cardEffectEvent: CardEffectEvent): boolean?
+---@field public mod_target_filter? fun(self: ActiveSkill, to_select: integer, selected: integer[], user: integer, card: Card, distance_limited: boolean): boolean?
+---@field public prompt? string|fun(self: ActiveSkill, selected_cards: integer[], selected_targets: integer[]): string
 ---@field public interaction any
 
 ---@param spec ActiveSkillSpec
@@ -222,13 +222,13 @@ function fk.CreateActiveSkill(spec)
 end
 
 ---@class ViewAsSkillSpec: UsableSkillSpec
----@field public card_filter nil|fun(self: ViewAsSkill, to_select: integer, selected: integer[]): bool
----@field public view_as fun(self: ViewAsSkill, cards: integer[]): Card|nil
----@field public pattern nil|string
----@field public enabled_at_play nil|fun(self: ViewAsSkill, player: Player): bool
----@field public enabled_at_response nil|fun(self: ViewAsSkill, player: Player, response: boolean): bool
----@field public before_use nil|fun(self: ViewAsSkill, player: ServerPlayer, use: CardUseStruct)
----@field public prompt nil|string|fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): string
+---@field public card_filter? fun(self: ViewAsSkill, to_select: integer, selected: integer[]): boolean?
+---@field public view_as fun(self: ViewAsSkill, cards: integer[]): Card?
+---@field public pattern? string
+---@field public enabled_at_play? fun(self: ViewAsSkill, player: Player): boolean?
+---@field public enabled_at_response? fun(self: ViewAsSkill, player: Player, response: boolean): boolean?
+---@field public before_use? fun(self: ViewAsSkill, player: ServerPlayer, use: CardUseStruct)
+---@field public prompt? string|fun(self: ActiveSkill, selected: integer[], selected_cards: integer[]): string
 
 ---@param spec ViewAsSkillSpec
 ---@return ViewAsSkill
@@ -278,8 +278,8 @@ function fk.CreateViewAsSkill(spec)
 end
 
 ---@class DistanceSpec: StatusSkillSpec
----@field public correct_func nil|fun(self: DistanceSkill, from: Player, to: Player): integer|nil
----@field public fixed_func nil|fun(self: DistanceSkill, from: Player, to: Player): integer|nil
+---@field public correct_func? fun(self: DistanceSkill, from: Player, to: Player): integer?
+---@field public fixed_func? fun(self: DistanceSkill, from: Player, to: Player): integer?
 
 ---@param spec DistanceSpec
 ---@return DistanceSkill
@@ -296,10 +296,10 @@ function fk.CreateDistanceSkill(spec)
 end
 
 ---@class ProhibitSpec: StatusSkillSpec
----@field public is_prohibited nil|fun(self: ProhibitSkill, from: Player, to: Player, card: Card): bool
----@field public prohibit_use nil|fun(self: ProhibitSkill, player: Player, card: Card): bool
----@field public prohibit_response nil|fun(self: ProhibitSkill, player: Player, card: Card): bool
----@field public prohibit_discard nil|fun(self: ProhibitSkill, player: Player, card: Card): bool
+---@field public is_prohibited? fun(self: ProhibitSkill, from: Player, to: Player, card: Card): boolean?
+---@field public prohibit_use? fun(self: ProhibitSkill, player: Player, card: Card): boolean?
+---@field public prohibit_response? fun(self: ProhibitSkill, player: Player, card: Card): boolean?
+---@field public prohibit_discard? fun(self: ProhibitSkill, player: Player, card: Card): boolean?
 
 ---@param spec ProhibitSpec
 ---@return ProhibitSkill
@@ -317,8 +317,8 @@ function fk.CreateProhibitSkill(spec)
 end
 
 ---@class AttackRangeSpec: StatusSkillSpec
----@field public correct_func nil|fun(self: AttackRangeSkill, from: Player, to: Player): number|nil
----@field public within_func nil|fun(self: AttackRangeSkill, from: Player, to: Player): bool
+---@field public correct_func? fun(self: AttackRangeSkill, from: Player, to: Player): number?
+---@field public within_func? fun(self: AttackRangeSkill, from: Player, to: Player): boolean?
 
 ---@param spec AttackRangeSpec
 ---@return AttackRangeSkill
@@ -339,9 +339,9 @@ function fk.CreateAttackRangeSkill(spec)
 end
 
 ---@class MaxCardsSpec: StatusSkillSpec
----@field public correct_func nil|fun(self: MaxCardsSkill, player: Player): number|nil
----@field public fixed_func nil|fun(self: MaxCardsSkill, player: Player): number|nil
----@field public exclude_from nil|fun(self: MaxCardsSkill, player: Player, card: Card): bool
+---@field public correct_func? fun(self: MaxCardsSkill, player: Player): number?
+---@field public fixed_func? fun(self: MaxCardsSkill, player: Player): number?
+---@field public exclude_from? fun(self: MaxCardsSkill, player: Player, card: Card): boolean?
 
 ---@param spec MaxCardsSpec
 ---@return MaxCardsSkill
@@ -363,11 +363,11 @@ function fk.CreateMaxCardsSkill(spec)
 end
 
 ---@class TargetModSpec: StatusSkillSpec
----@field public bypass_times nil|fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): bool
----@field public residue_func nil|fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): number|nil
----@field public bypass_distances nil|fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): bool
----@field public distance_limit_func nil|fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): number|nil
----@field public extra_target_func nil|fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card): number|nil
+---@field public bypass_times? fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): boolean?
+---@field public residue_func? fun(self: TargetModSkill, player: Player, skill: ActiveSkill, scope: integer, card: Card, to: Player): number?
+---@field public bypass_distances? fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): boolean?
+---@field public distance_limit_func? fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card, to: Player): number?
+---@field public extra_target_func? fun(self: TargetModSkill, player: Player, skill: ActiveSkill, card: Card): number?
 
 ---@param spec TargetModSpec
 ---@return TargetModSkill
@@ -396,8 +396,8 @@ function fk.CreateTargetModSkill(spec)
 end
 
 ---@class FilterSpec: StatusSkillSpec
----@field public card_filter nil|fun(self: FilterSkill, card: Card, player: Player): bool
----@field public view_as nil|fun(self: FilterSkill, card: Card, player: Player): Card|nil
+---@field public card_filter? fun(self: FilterSkill, card: Card, player: Player): boolean?
+---@field public view_as? fun(self: FilterSkill, card: Card, player: Player): Card?
 
 ---@param spec FilterSpec
 ---@return FilterSkill
@@ -413,7 +413,7 @@ function fk.CreateFilterSkill(spec)
 end
 
 ---@class InvaliditySpec: StatusSkillSpec
----@field public invalidity_func nil|fun(self: InvaliditySkill, from: Player, skill: Skill): bool
+---@field public invalidity_func? fun(self: InvaliditySkill, from: Player, skill: Skill): boolean?
 
 ---@param spec InvaliditySpec
 ---@return InvaliditySkill
@@ -428,11 +428,11 @@ function fk.CreateInvaliditySkill(spec)
 end
 
 ---@class CardSpec: Card
----@field public skill nil|Skill
----@field public equip_skill nil|Skill
----@field public special_skills string[] | nil
----@field public is_damage_card bool
----@field public multiple_targets bool
+---@field public skill? Skill
+---@field public equip_skill? Skill
+---@field public special_skills? string[]
+---@field public is_damage_card? boolean
+---@field public multiple_targets? boolean
 
 local defaultCardSkill = fk.CreateActiveSkill{
   name = "default_card_skill",
@@ -593,8 +593,8 @@ end
 
 ---@class PoxiSpec
 ---@field name string
----@field card_filter fun(to_select: int, selected: int[], data: any, extra_data: any): bool
----@field feasible fun(selected: int[], data: any, extra_data: any): bool
----@field post_select nil | fun(selected: int[], data: any, extra_data: any): int[]
----@field default_choice nil | fun(data: any, extra_data: any): int[]
----@field prompt nil | string | fun(data: any, extra_data: any): string
+---@field card_filter fun(to_select: int, selected: int[], data: any, extra_data: any): boolean?
+---@field feasible fun(selected: int[], data: any, extra_data: any): boolean?
+---@field post_select? fun(selected: int[], data: any, extra_data: any): int[]
+---@field default_choice? fun(data: any, extra_data: any): int[]
+---@field prompt? string | fun(data: any, extra_data: any): string
diff --git a/lua/lsp/qt.lua b/lua/lsp/qt.lua
index cc257f50..855e6f1a 100644
--- a/lua/lsp/qt.lua
+++ b/lua/lsp/qt.lua
@@ -13,7 +13,7 @@ function SPlayerList:append(e)end
 function SPlayerList:contains(e)end
 
 ---@param index integer
----@return fk.ServerPlayer | nil
+---@return fk.ServerPlayer
 function SPlayerList:at(index)end
 
 function SPlayerList:first()end
diff --git a/lua/server/ai/random_ai.lua b/lua/server/ai/random_ai.lua
index 1212c958..74271b8a 100644
--- a/lua/server/ai/random_ai.lua
+++ b/lua/server/ai/random_ai.lua
@@ -5,7 +5,7 @@ local RandomAI = AI:subclass("RandomAI")
 
 ---@param self RandomAI
 ---@param skill ActiveSkill
----@param card Card | nil
+---@param card? Card
 function RandomAI:useActiveSkill(skill, card)
   local room = self.room
   local player = self.player
diff --git a/lua/server/ai/smart_ai.lua b/lua/server/ai/smart_ai.lua
index 5cb34210..9d834459 100644
--- a/lua/server/ai/smart_ai.lua
+++ b/lua/server/ai/smart_ai.lua
@@ -82,15 +82,15 @@ end
 --===================================================
 
 ---@class UseReply
----@field card integer|string|nil @ string情况下是json.encode后
----@field targets integer[]|nil
+---@field card? integer|string @ string情况下是json.encode后
+---@field targets? integer[]
 ---@field special_skill string @ 出牌阶段空闲点使用实体卡特有
 ---@field interaction_data any @ 因技能而异，一般都是nil
 
----@param card integer|table|nil
----@param targets integer[]|nil
----@param special_skill string|nil
----@param interaction_data any
+---@param card integer|table
+---@param targets? integer[]
+---@param special_skill? string
+---@param interaction_data? any
 function SmartAI:buildUseReply(card, targets, special_skill, interaction_data)
   if type(card) == "table" then card = json.encode(card) end
   return {
@@ -106,7 +106,7 @@ end
 -- * 且原型为 { skill = skillName, subcards = integer[] }
 ----------------------------------------------------------
 
----@type table<string, fun(self: SmartAI, prompt: string, cancelable: bool, data: any): UseReply | nil>
+---@type table<string, fun(self: SmartAI, prompt: string, cancelable?: boolean, data: any): UseReply?>
 fk.ai_active_skill = {}
 
 smart_cb["AskForUseActiveSkill"] = function(self, jsonData)
@@ -133,7 +133,7 @@ end
 ---------------------------------------------------------
 
 --- 键是prompt的第一项或者牌名，优先prompt，其次name，实在不行trueName。
----@type table<string, fun(self: SmartAI, pattern: string, prompt: string, cancelable: bool, extra_data?: UseExtraData): UseReply|nil>
+---@type table<string, fun(self: SmartAI, pattern: string, prompt: string, cancelable?: boolean, extra_data?: UseExtraData): UseReply?>
 fk.ai_use_card = {}
 
 local defauld_use_card = function(self, pattern, _, cancelable, exdata)
@@ -173,7 +173,7 @@ end
 -------------------------------------
 
 -- 一样的牌名或者prompt做键优先prompt
----@type table<string, fun(self: SmartAI, pattern: string, prompt: string, cancelable: bool, extra_data: any): UseReply|nil>
+---@type table<string, fun(self: SmartAI, pattern: string, prompt: string, cancelable?: boolean, extra_data: any): UseReply?>
 fk.ai_response_card = {}
 
 local defauld_response_card = function(self, pattern, _, cancelable)
diff --git a/lua/server/gameevent.lua b/lua/server/gameevent.lua
index 2b2c494a..f7d3840b 100644
--- a/lua/server/gameevent.lua
+++ b/lua/server/gameevent.lua
@@ -135,8 +135,8 @@ end
 -- 从某个区间中，找出类型符合且符合func函数检测的至多n个事件。
 ---@param eventType integer @ 要查找的事件类型
 ---@param n integer @ 最多找多少个
----@param func fun(e: GameEvent): boolean @ 过滤用的函数
----@param endEvent GameEvent|nil @ 区间终止点，默认为本事件结束
+---@param func fun(e: GameEvent): boolean? @ 过滤用的函数
+---@param endEvent? GameEvent @ 区间终止点，默认为本事件结束
 ---@return GameEvent[] @ 找到的符合条件的所有事件，最多n个但不保证有n个
 function GameEvent:searchEvents(eventType, n, func, endEvent)
   local logic = self.room.logic
diff --git a/lua/server/gamelogic.lua b/lua/server/gamelogic.lua
index a1a5e5a4..d5669e05 100644
--- a/lua/server/gamelogic.lua
+++ b/lua/server/gamelogic.lua
@@ -328,8 +328,8 @@ function GameLogic:addTriggerSkill(skill)
 end
 
 ---@param event Event
----@param target ServerPlayer|nil
----@param data any|nil
+---@param target? ServerPlayer
+---@param data? any
 function GameLogic:trigger(event, target, data, refresh_only)
   local room = self.room
   local broken = false
diff --git a/lua/server/room.lua b/lua/server/room.lua
index b4a3676a..3e442976 100644
--- a/lua/server/room.lua
+++ b/lua/server/room.lua
@@ -264,7 +264,7 @@ end
 --- 基本算是私有函数，别去用
 ---@param cardId integer
 ---@param cardArea CardArea
----@param owner nil|integer
+---@param owner? integer
 function Room:setCardArea(cardId, cardArea, owner)
   self.card_place[cardId] = cardArea
   self.owner_map[cardId] = owner
@@ -282,8 +282,8 @@ function Room:getCardArea(cardId)
 end
 
 --- 获得拥有某一张牌的玩家。
----@param cardId integer | card @ 要获得主人的那张牌，可以是Card实例或者id
----@return ServerPlayer | nil @ 这张牌的主人，可能返回nil
+---@param cardId integer | Card @ 要获得主人的那张牌，可以是Card实例或者id
+---@return ServerPlayer? @ 这张牌的主人，可能返回nil
 function Room:getCardOwner(cardId)
   if type(cardId) ~= "number" then
     assert(cardId and cardId:isInstanceOf(Card))
@@ -345,7 +345,7 @@ end
 --- 获得当前房间中的所有玩家。
 ---
 --- 返回的数组的第一个元素是当前回合玩家，并且按行动顺序进行排序。
----@param sortBySeat bool @ 是否无视按座位排序直接返回
+---@param sortBySeat? boolean @ 是否无视按座位排序直接返回
 ---@return ServerPlayer[] @ 房间中玩家的数组
 function Room:getAllPlayers(sortBySeat)
   if not self.game_started then
@@ -367,7 +367,7 @@ function Room:getAllPlayers(sortBySeat)
 end
 
 --- 获得所有存活玩家，参看getAllPlayers
----@param sortBySeat bool
+---@param sortBySeat? boolean
 ---@return ServerPlayer[]
 function Room:getAlivePlayers(sortBySeat)
   if sortBySeat == nil or sortBySeat then
@@ -394,8 +394,8 @@ end
 
 --- 获得除一名玩家外的其他玩家。
 ---@param player ServerPlayer @ 要排除的玩家
----@param sortBySeat bool @ 是否要按座位排序？
----@param include_dead bool @ 是否要把死人也算进去？
+---@param sortBySeat? boolean @ 是否要按座位排序？
+---@param include_dead? boolean @ 是否要把死人也算进去？
 ---@return ServerPlayer[] @ 其他玩家列表
 function Room:getOtherPlayers(player, sortBySeat, include_dead)
   if sortBySeat == nil then
@@ -416,7 +416,7 @@ end
 --- 获得当前房间中的主公。
 ---
 --- 由于某些游戏模式没有主公，该函数可能返回nil。
----@return ServerPlayer | nil @ 主公
+---@return ServerPlayer? @ 主公
 function Room:getLord()
   local lord = self.players[1]
   if lord.role == "lord" then return lord end
@@ -433,7 +433,7 @@ end
 ---
 --- 如果牌堆中没有足够的牌可以获得，那么会触发洗牌；还是不够的话，游戏就平局。
 ---@param num integer @ 要获得的牌的数量
----@param from string|nil @ 获得牌的位置，可以是 ``"top"`` 或者 ``"bottom"``，表示牌堆顶还是牌堆底
+---@param from? string @ 获得牌的位置，可以是 ``"top"`` 或者 ``"bottom"``，表示牌堆顶还是牌堆底
 ---@return integer[] @ 得到的id
 function Room:getNCards(num, from)
   from = from or "top"
@@ -478,7 +478,7 @@ end
 --- 将一名玩家的mark标记增加count个。
 ---@param player ServerPlayer @ 要加标记的玩家
 ---@param mark string @ 标记名称
----@param count integer | nil @ 要增加的数量，默认为1
+---@param count? integer @ 要增加的数量，默认为1
 function Room:addPlayerMark(player, mark, count)
   count = count or 1
   local num = player:getMark(mark)
@@ -489,7 +489,7 @@ end
 --- 将一名玩家的mark标记减少count个。
 ---@param player ServerPlayer @ 要减标记的玩家
 ---@param mark string @ 标记名称
----@param count integer | nil @ 要减少的数量，默认为1
+---@param count? integer  @ 要减少的数量，默认为1
 function Room:removePlayerMark(player, mark, count)
   count = count or 1
   local num = player:getMark(mark)
@@ -517,7 +517,7 @@ end
 --- 将一张卡牌的mark标记增加count个。
 ---@param card Card @ 要被增加标记的那张牌
 ---@param mark string @ 标记名称
----@param count integer | nil @ 要增加的数量，默认为1
+---@param count? integer @ 要增加的数量，默认为1
 function Room:addCardMark(card, mark, count)
   count = count or 1
   local num = card:getMark(mark)
@@ -528,7 +528,7 @@ end
 --- 将一名玩家的mark标记减少count个。
 ---@param card Card @ 要被减少标记的那张牌
 ---@param mark string @ 标记名称
----@param count integer | nil @ 要减少的数量，默认为1
+---@param count? integer @ 要减少的数量，默认为1
 function Room:removeCardMark(card, mark, count)
   count = count or 1
   local num = card:getMark(mark)
@@ -563,6 +563,7 @@ function Room:removeTag(tag_name)
   self.tag[tag_name] = nil
 end
 
+---@return boolean
 local function execGameEvent(type, ...)
   local event = GameEvent:new(type, ...)
   local _, ret = event:exec()
@@ -571,8 +572,8 @@ end
 
 ---@param player ServerPlayer
 ---@param general string
----@param changeKingdom bool
----@param noBroadcast bool
+---@param changeKingdom? boolean
+---@param noBroadcast? boolean
 function Room:setPlayerGeneral(player, general, changeKingdom, noBroadcast)
   if Fk.generals[general] == nil then return end
   player.general = general
@@ -600,10 +601,10 @@ end
 
 ---@param player ServerPlayer @ 要换将的玩家
 ---@param new_general string @ 要变更的武将，若不存在则变身为孙策，孙策不存在变身为士兵
----@param full bool @ 是否血量满状态变身
----@param isDeputy bool @ 是否变的是副将
----@param sendLog bool @ 是否发Log
----@param maxHpChange bool @ 是否改变体力上限，默认改变
+---@param full? boolean @ 是否血量满状态变身
+---@param isDeputy? boolean @ 是否变的是副将
+---@param sendLog? boolean @ 是否发Log
+---@param maxHpChange? boolean @ 是否改变体力上限，默认改变
 function Room:changeHero(player, new_general, full, isDeputy, sendLog, maxHpChange, kingdomChange)
   local new = Fk.generals[new_general] or Fk.generals["sunce"] or Fk.generals["blank_shibing"]
 
@@ -641,7 +642,7 @@ end
 
 ---@param player ServerPlayer @ 要变更势力的玩家
 ---@param kingdom string @ 要变更的势力
----@param sendLog bool @ 是否发Log
+---@param sendLog? boolean @ 是否发Log
 function Room:changeKingdom(player, kingdom, sendLog)
   if kingdom == player.kingdom then return end
   sendLog = sendLog or false
@@ -683,7 +684,7 @@ end
 --- 向多名玩家广播一条消息。
 ---@param command string @ 发出这条消息的消息类型
 ---@param jsonData string @ 消息的数据，一般是JSON字符串，也可以是普通字符串，取决于client怎么处理了
----@param players ServerPlayer[] | nil @ 要告知的玩家列表，默认为所有人
+---@param players? ServerPlayer[] @ 要告知的玩家列表，默认为所有人
 function Room:doBroadcastNotify(command, jsonData, players)
   players = players or self.players
   for _, p in ipairs(players) do
@@ -695,8 +696,8 @@ end
 ---@param player ServerPlayer @ 发出这个请求的目标玩家
 ---@param command string @ 请求的类型
 ---@param jsonData string @ 请求的数据
----@param wait bool @ 是否要等待答复，默认为true
----@return string | nil @ 收到的答复，如果wait为false的话就返回nil
+---@param wait? boolean @ 是否要等待答复，默认为true
+---@return string @ 收到的答复，如果wait为false的话就返回nil
 function Room:doRequest(player, command, jsonData, wait)
   if wait == nil then wait = true end
   self.request_queue = {}
@@ -713,8 +714,8 @@ end
 
 --- 向多名玩家发出请求。
 ---@param command string @ 请求类型
----@param players ServerPlayer[]|nil @ 发出请求的玩家列表
----@param jsonData string|nil @ 请求数据
+---@param players? ServerPlayer[] @ 发出请求的玩家列表
+---@param jsonData? string @ 请求数据
 function Room:doBroadcastRequest(command, players, jsonData)
   players = players or self.players
   self.request_queue = {}
@@ -745,7 +746,7 @@ end
 ---@param command string @ 请求类型
 ---@param players ServerPlayer[] @ 要竞争这次请求的玩家列表
 ---@param jsonData string @ 请求数据
----@return ServerPlayer | nil @ 在这次竞争请求中获胜的角色，可能是nil
+---@return ServerPlayer? @ 在这次竞争请求中获胜的角色，可能是nil
 function Room:doRaceRequest(command, players, jsonData)
   players = players or self.players
   players = table.simpleClone(players)
@@ -819,9 +820,9 @@ function Room:delay(ms)
 end
 
 --- 向多名玩家告知一次移牌行为。
----@param players ServerPlayer[] | nil @ 要被告知的玩家列表，默认为全员
+---@param players? ServerPlayer[] @ 要被告知的玩家列表，默认为全员
 ---@param card_moves CardsMoveStruct[] @ 要告知的移牌信息列表
----@param forceVisible bool @ 是否让所有牌对告知目标可见
+---@param forceVisible? boolean @ 是否让所有牌对告知目标可见
 function Room:notifyMoveCards(players, card_moves, forceVisible)
   if players == nil or players == {} then players = self.players end
   for _, p in ipairs(players) do
@@ -913,7 +914,7 @@ end
 --- 播放某种动画效果给players看。
 ---@param type string @ 动画名字
 ---@param data any @ 这个动画附加的额外信息，在这个函数将会被转成json字符串
----@param players ServerPlayer[] | nil @ 要观看动画的玩家们，默认为全员
+---@param players? ServerPlayer[] @ 要观看动画的玩家们，默认为全员
 function Room:doAnimate(type, data, players)
   players = players or self.players
   data.type = type
@@ -965,7 +966,7 @@ end
 
 --- 播放技能的语音。
 ---@param skill_name nil @ 技能名
----@param index integer | nil @ 语音编号，默认为-1（也就是随机播放）
+---@param index? integer @ 语音编号，默认为-1（也就是随机播放）
 function Room:broadcastSkillInvoke(skill_name, index)
   fk.qCritical 'Room:broadcastSkillInvoke deprecated; use SPlayer:broadcastSkillInvoke'
   index = index or -1
@@ -988,7 +989,7 @@ end
 --- 与此同时，在战报里面发一条“xxx发动了xxx”
 ---@param player ServerPlayer @ 发动技能的那个玩家
 ---@param skill_name string @ 技能名
----@param skill_type string | nil @ 技能的动画效果，默认是那个技能的anim_type
+---@param skill_type? string @ 技能的动画效果，默认是那个技能的anim_type
 function Room:notifySkillInvoked(player, skill_name, skill_type)
   local bigAnim = false
   if not skill_type then
@@ -1049,11 +1050,11 @@ end
 --- 如果发动的话，那么会执行一下技能的onUse函数，然后返回选择的牌和目标等。
 ---@param player ServerPlayer @ 询问目标
 ---@param skill_name string @ 主动技的技能名
----@param prompt string|nil @ 烧条上面显示的提示文本内容
----@param cancelable bool @ 是否可以点取消
----@param extra_data table|nil @ 额外信息，因技能而异了
----@param no_indicate bool @ 是否不显示指示线
----@return boolean, table|nil
+---@param prompt? string @ 烧条上面显示的提示文本内容
+---@param cancelable? boolean @ 是否可以点取消
+---@param extra_data? table @ 额外信息，因技能而异了
+---@param no_indicate? boolean @ 是否不显示指示线
+---@return boolean, table?
 function Room:askForUseActiveSkill(player, skill_name, prompt, cancelable, extra_data, no_indicate)
   prompt = prompt or ""
   cancelable = (cancelable == nil) and true or cancelable
@@ -1112,13 +1113,13 @@ Room.askForUseViewAsSkill = Room.askForUseActiveSkill
 ---@param player ServerPlayer @ 弃牌角色
 ---@param minNum integer @ 最小值
 ---@param maxNum integer @ 最大值
----@param includeEquip bool @ 能不能弃装备区？
----@param skillName string|nil @ 引发弃牌的技能名
----@param cancelable bool @ 能不能点取消？
----@param pattern string|nil @ 弃牌需要符合的规则
----@param prompt string|nil @ 提示信息
----@param skipDiscard bool @ 是否跳过弃牌（即只询问选择可以弃置的牌）
----@param no_indicate bool @ 是否不显示指示线
+---@param includeEquip? boolean @ 能不能弃装备区？
+---@param skillName? string @ 引发弃牌的技能名
+---@param cancelable? boolean @ 能不能点取消？
+---@param pattern? string @ 弃牌需要符合的规则
+---@param prompt? string @ 提示信息
+---@param skipDiscard? boolean @ 是否跳过弃牌（即只询问选择可以弃置的牌）
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[] @ 弃掉的牌的id列表，可能是空的
 function Room:askForDiscard(player, minNum, maxNum, includeEquip, skillName, cancelable, pattern, prompt, skipDiscard, no_indicate)
   cancelable = (cancelable == nil) and true or cancelable
@@ -1192,10 +1193,10 @@ end
 ---@param targets integer[] @ 可以选的目标范围，是玩家id数组
 ---@param minNum integer @ 最小值
 ---@param maxNum integer @ 最大值
----@param prompt string|nil @ 提示信息
----@param skillName string|nil @ 技能名
----@param cancelable bool @ 能否点取消
----@param no_indicate bool @ 是否不显示指示线
+---@param prompt? string @ 提示信息
+---@param skillName? string @ 技能名
+---@param cancelable? boolean @ 能否点取消
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[] @ 选择的玩家id列表，可能为空
 function Room:askForChoosePlayers(player, targets, minNum, maxNum, prompt, skillName, cancelable, no_indicate)
   if maxNum < 1 then
@@ -1229,17 +1230,17 @@ end
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param minNum integer @ 最小值
 ---@param maxNum integer @ 最大值
----@param includeEquip bool @ 能不能选装备
----@param skillName string @ 技能名
----@param cancelable bool @ 能否点取消
----@param pattern string|nil @ 选牌规则
----@param prompt string|nil @ 提示信息
----@param expand_pile string|nil @ 可选私人牌堆名称
----@param no_indicate bool @ 是否不显示指示线
+---@param includeEquip? boolean @ 能不能选装备
+---@param skillName? string @ 技能名
+---@param cancelable? boolean @ 能否点取消
+---@param pattern? string @ 选牌规则
+---@param prompt? string @ 提示信息
+---@param expand_pile? string @ 可选私人牌堆名称
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[] @ 选择的牌的id列表，可能是空的
 function Room:askForCard(player, minNum, maxNum, includeEquip, skillName, cancelable, pattern, prompt, expand_pile, no_indicate)
   if minNum < 1 then
-    return nil
+    return {}
   end
   cancelable = (cancelable == nil) and true or cancelable
   no_indicate = no_indicate or false
@@ -1285,10 +1286,10 @@ end
 ---@param targets integer[] @ 选择目标的id范围
 ---@param minNum integer @ 选目标最小值
 ---@param maxNum integer @ 选目标最大值
----@param pattern string|nil @ 选牌规则
----@param prompt string|nil @ 提示信息
----@param cancelable bool @ 能否点取消
----@param no_indicate bool @ 是否不显示指示线
+---@param pattern? string @ 选牌规则
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 能否点取消
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[], integer
 function Room:askForChooseCardAndPlayers(player, targets, minNum, maxNum, pattern, prompt, skillName, cancelable, no_indicate)
   if maxNum < 1 then
@@ -1332,10 +1333,10 @@ end
 ---@param targets integer[] @ 选择目标的id范围
 ---@param minTargetNum integer @ 选目标最小值
 ---@param maxTargetNum integer @ 选目标最大值
----@param pattern string|nil @ 选牌规则
----@param prompt string|nil @ 提示信息
----@param cancelable bool @ 能否点取消
----@param no_indicate bool @ 是否不显示指示线
+---@param pattern? string @ 选牌规则
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 能否点取消
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[], integer[]
 function Room:askForChooseBoth(player, minCardNum, maxCardNum, targets, minTargetNum, maxTargetNum, pattern, prompt, skillName, cancelable, no_indicate)
   if minCardNum < 1 or minTargetNum < 1 then
@@ -1376,7 +1377,7 @@ end
 ---
 --- 同getNCards，抽出来就没有了，所以记得放回去。
 ---@param n number @ 数量
----@param position string|nil @位置，top/bottom，默认top
+---@param position? string @位置，top/bottom，默认top
 ---@return string[] @ 武将名数组
 function Room:getNGenerals(n, position)
   position = position or "top"
@@ -1399,7 +1400,7 @@ end
 
 --- 把武将牌塞回去（……）
 ---@param g string[] @ 武将名数组
----@param position string|nil @位置，top/bottom，默认bottom
+---@param position? string @位置，top/bottom，默认bottom
 ---@return boolean @ 是否成功
 function Room:returnToGeneralPile(g, position)
   position = position or "bottom"
@@ -1417,7 +1418,7 @@ end
 
 --- 抽特定名字的武将（抽了就没了）
 ---@param name string @ 武将name，如找不到则查找truename，再找不到则返回nil
----@return string | nil @ 抽出的武将名
+---@return string? @ 抽出的武将名
 function Room:findGeneral(name)
   for i, g in ipairs(self.general_pile) do
     if g == name or Fk.generals[g].trueName == Fk.generals[name].trueName then
@@ -1429,7 +1430,7 @@ end
 
 --- 自上而下抽符合特定情况的N个武将（抽了就没了）
 ---@param func fun(name: string):any @ 武将筛选函数
----@param n integer | nil @ 抽取数量，数量不足则直接抽干净
+---@param n? integer @ 抽取数量，数量不足则直接抽干净
 ---@return string[] @ 武将组合，可能为空
 function Room:findGenerals(func, n)
   n = n or 1
@@ -1449,7 +1450,7 @@ end
 ---@param player ServerPlayer @ 询问目标
 ---@param generals string[] @ 可选武将
 ---@param n integer @ 可选数量，默认为1
----@param noConvert bool @ 可否变更，默认可
+---@param noConvert? boolean @ 可否变更，默认可
 ---@return string|string[] @ 选择的武将
 function Room:askForGeneral(player, generals, n, noConvert)
   local command = "AskForGeneral"
@@ -1475,7 +1476,7 @@ function Room:askForGeneral(player, generals, n, noConvert)
 end
 
 --- 询问玩家若为神将、双势力需选择一个势力。
----@param players ServerPlayer[]|nil @ 询问目标
+---@param players? ServerPlayer[] @ 询问目标
 function Room:askForChooseKingdom(players)
   players = players or self.alive_players
   local specialKingdomPlayers = table.filter(players, function(p)
@@ -1521,7 +1522,7 @@ end
 ---@param target ServerPlayer @ 被选牌的人
 ---@param flag any @ 用"hej"三个字母的组合表示能选择哪些区域, h 手牌区, e - 装备区, j - 判定区
 ---@param reason string @ 原因，一般是技能名
----@param prompt string|nil @ 提示信息
+---@param prompt? string @ 提示信息
 ---@return integer @ 选择的卡牌id
 function Room:askForCardChosen(chooser, target, flag, reason, prompt)
   local command = "AskForCardChosen"
@@ -1567,7 +1568,7 @@ end
 ---@param max integer @ 最大选牌数
 ---@param flag any @ 用"hej"三个字母的组合表示能选择哪些区域, h 手牌区, e - 装备区, j - 判定区
 ---@param reason string @ 原因，一般是技能名
----@param prompt string|nil @ 提示信息
+---@param prompt? string @ 提示信息
 ---@return integer[] @ 选择的id
 function Room:askForCardsChosen(chooser, target, min, max, flag, reason, prompt)
   if min == 1 and max == 1 then
@@ -1619,7 +1620,7 @@ end
 ---@param poxi_type string
 ---@param data any
 ---@param extra_data any
----@param cancelable nil|bool
+---@param cancelable? boolean
 ---@return integer[]
 function Room:askForPoxi(player, poxi_type, data, extra_data, cancelable)
   local poxi = Fk.poxi_methods[poxi_type]
@@ -1644,10 +1645,10 @@ end
 --- 询问一名玩家从众多选项中选择一个。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param choices string[] @ 可选选项列表
----@param skill_name string|nil @ 技能名
----@param prompt string|nil @ 提示信息
----@param detailed bool @ 选项详细描述
----@param all_choices string[]|nil @ 所有选项（不可选变灰）
+---@param skill_name? string @ 技能名
+---@param prompt? string @ 提示信息
+---@param detailed? boolean @ 选项详细描述
+---@param all_choices? string[] @ 所有选项（不可选变灰）
 ---@return string @ 选择的选项
 function Room:askForChoice(player, choices, skill_name, prompt, detailed, all_choices)
   if #choices == 1 and not all_choices then return choices[1] end
@@ -1668,11 +1669,11 @@ end
 ---@param choices string[] @ 可选选项列表
 ---@param minNum number @ 最少选择项数
 ---@param maxNum number @ 最多选择项数
----@param skill_name string|nil @ 技能名
----@param prompt string|nil @ 提示信息
----@param cancelable bool|nil @ 是否可取消
----@param detailed bool @ 选项详细描述
----@param all_choices string[]|nil @ 所有选项（不可选变灰）
+---@param skill_name? string @ 技能名
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 是否可取消
+---@param detailed? boolean @ 选项详细描述
+---@param all_choices? string[] @ 所有选项（不可选变灰）
 ---@return string[] @ 选择的选项
 function Room:askForCheck(player, choices, minNum, maxNum, skill_name, prompt, cancelable, detailed, all_choices)
   cancelable = (cancelable == nil) and true or cancelable
@@ -1695,8 +1696,8 @@ end
 --- 询问玩家是否发动技能。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param skill_name string @ 技能名
----@param data any|nil @ 未使用
----@param prompt string|nil @ 提示信息
+---@param data? any @ 未使用
+---@param prompt? string @ 提示信息
 ---@return boolean
 function Room:askForSkillInvoke(player, skill_name, data, prompt)
   local command = "AskForSkillInvoke"
@@ -1767,12 +1768,12 @@ end
 --- 观星完成后，相关的牌会被置于牌堆顶或者牌堆底。所以这些cards最好不要来自牌堆，一般先用getNCards从牌堆拿出一些牌。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param cards integer[] @ 可以被观星的卡牌id列表
----@param top_limit integer[]|nil @ 置于牌堆顶的牌的限制(下限,上限)，不填写则不限
----@param bottom_limit integer[]|nil @ 置于牌堆底的牌的限制(下限,上限)，不填写则不限
----@param customNotify string|null @ 自定义读条操作提示
----param prompt string|null @ 观星框的标题(暂时雪藏)
----@param noPut bool @ 是否进行放置牌操作
----@param areaNames string[]|null @ 左侧提示信息
+---@param top_limit? integer[] @ 置于牌堆顶的牌的限制(下限,上限)，不填写则不限
+---@param bottom_limit? integer[] @ 置于牌堆底的牌的限制(下限,上限)，不填写则不限
+---@param customNotify? string @ 自定义读条操作提示
+---param prompt? string @ 观星框的标题(暂时雪藏)
+---@param noPut? boolean @ 是否进行放置牌操作
+---@param areaNames? string[] @ 左侧提示信息
 ---@return table<"top"|"bottom", integer[]>
 function Room:askForGuanxing(player, cards, top_limit, bottom_limit, customNotify, noPut, areaNames)
   -- 这一大堆都是来提前报错的
@@ -1843,10 +1844,10 @@ end
 --- 询问玩家任意交换几堆牌堆。
 ---
 ---@param player ServerPlayer @ 要询问的玩家
----@param piles table<cardIds, integer[]> @ 卡牌id列表的列表，也就是……几堆牌堆的集合
+---@param piles table<string, integer[]> @ 卡牌id列表的列表，也就是……几堆牌堆的集合
 ---@param piles_name string[] @ 牌堆名，必须一一对应，否则统一替换为“牌堆X”
----@param customNotify string|null @ 自定义读条操作提示
----@return table<cardIds, integer[]>
+---@param customNotify? string @ 自定义读条操作提示
+---@return table<string, integer[]>
 function Room:askForExchange(player, piles, piles_name, customNotify)
   local command = "AskForExchange"
   piles_name = piles_name or Util.DummyTable
@@ -1947,13 +1948,13 @@ end
 -- * bypass_times: boolean
 --- 询问玩家使用一张牌。
 ---@param player ServerPlayer @ 要询问的玩家
----@param card_name string|nil @ 使用牌的牌名，若pattern指定了则可随意写，它影响的是烧条的提示信息
----@param pattern string|nil @ 使用牌的规则，默认就是card_name的值
----@param prompt string|nil @ 提示信息
----@param cancelable bool @ 能否点取消
+---@param card_name? string @ 使用牌的牌名，若pattern指定了则可随意写，它影响的是烧条的提示信息
+---@param pattern? string @ 使用牌的规则，默认就是card_name的值
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 能否点取消
 ---@param extra_data? UseExtraData @ 额外信息
----@param event_data CardEffectEvent|nil @ 事件信息
----@return CardUseStruct | nil @ 返回关于本次使用牌的数据，以便后续处理
+---@param event_data? CardEffectEvent @ 事件信息
+---@return CardUseStruct? @ 返回关于本次使用牌的数据，以便后续处理
 function Room:askForUseCard(player, card_name, pattern, prompt, cancelable, extra_data, event_data)
   if event_data and (event_data.disresponsive or table.contains(event_data.disresponsiveList or Util.DummyTable, player.id)) then
     return nil
@@ -2021,12 +2022,12 @@ end
 --- 询问一名玩家打出一张牌。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param card_name string @ 牌名
----@param pattern string|nil @ 牌的规则
----@param prompt string|nil @ 提示信息
----@param cancelable bool @ 能否取消
----@param extra_data any|nil @ 额外数据
----@param effectData CardEffectEvent|nil @ 关联的卡牌生效流程
----@return Card | nil @ 打出的牌
+---@param pattern? string @ 牌的规则
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 能否取消
+---@param extra_data? any @ 额外数据
+---@param effectData? CardEffectEvent @ 关联的卡牌生效流程
+---@return Card? @ 打出的牌
 function Room:askForResponse(player, card_name, pattern, prompt, cancelable, extra_data, effectData)
   if effectData and (effectData.disresponsive or table.contains(effectData.disresponsiveList or Util.DummyTable, player.id)) then
     return nil
@@ -2072,10 +2073,10 @@ end
 ---@param players ServerPlayer[] @ 要询问的玩家列表
 ---@param card_name string @ 询问的牌名，默认为无懈
 ---@param pattern string @ 牌的规则
----@param prompt string|nil @ 提示信息
----@param cancelable bool @ 能否点取消
----@param extra_data any|nil @ 额外信息
----@return CardUseStruct | nil @ 最终决胜出的卡牌使用信息
+---@param prompt? string @ 提示信息
+---@param cancelable? boolean @ 能否点取消
+---@param extra_data? any @ 额外信息
+---@return CardUseStruct? @ 最终决胜出的卡牌使用信息
 function Room:askForNullification(players, card_name, pattern, prompt, cancelable, extra_data)
   if #players == 0 then
     return nil
@@ -2110,8 +2111,8 @@ end
 --- 询问玩家从AG中选择一张牌。
 ---@param player ServerPlayer @ 要询问的玩家
 ---@param id_list integer[] | Card[] @ 可选的卡牌列表
----@param cancelable bool @ 能否点取消
----@param reason string|nil @ 原因
+---@param cancelable? boolean @ 能否点取消
+---@param reason? string @ 原因
 ---@return integer @ 选择的卡牌
 function Room:askForAG(player, id_list, cancelable, reason)
   id_list = Card:getIdList(id_list)
@@ -2132,7 +2133,7 @@ end
 --- 给player发一条消息，在他的窗口中用一系列卡牌填充一个AG。
 ---@param player ServerPlayer @ 要通知的玩家
 ---@param id_list integer[] | Card[] @ 要填充的卡牌
----@param disable_ids integer[] | Card[]|nil @ 未使用
+---@param disable_ids? integer[] | Card[] @ 未使用
 function Room:fillAG(player, id_list, disable_ids)
   id_list = Card:getIdList(id_list)
   -- disable_ids = Card:getIdList(disable_ids)
@@ -2142,7 +2143,7 @@ end
 --- 告诉一些玩家，AG中的牌被taker取走了。
 ---@param taker ServerPlayer @ 拿走牌的玩家
 ---@param id integer @ 被拿走的牌
----@param notify_list ServerPlayer[]|nil @ 要告知的玩家，默认为全员
+---@param notify_list? ServerPlayer[] @ 要告知的玩家，默认为全员
 function Room:takeAG(taker, id, notify_list)
   self:doBroadcastNotify("TakeAG", json.encode{ taker.id, id }, notify_list)
 end
@@ -2150,7 +2151,7 @@ end
 --- 关闭player那侧显示的AG。
 ---
 --- 若不传参（即player为nil），那么关闭所有玩家的AG。
----@param player ServerPlayer|nil @ 要关闭AG的玩家
+---@param player? ServerPlayer @ 要关闭AG的玩家
 function Room:closeAG(player)
   if player then player:doNotify("CloseAG", "")
   else self:doBroadcastNotify("CloseAG", "") end
@@ -2177,10 +2178,10 @@ end
 ---@param targetOne ServerPlayer @ 移动的目标1玩家
 ---@param targetTwo ServerPlayer @ 移动的目标2玩家
 ---@param skillName string @ 技能名
----@param flag string|null @ 限定可移动的区域，值为nil（装备区和判定区）、‘e’或‘j’
----@param moveFrom ServerPlayer|null @ 是否只是目标1移动给目标2
----@param excludeIds CardId[]|null @ 本次不可移动的卡牌id
----@return table<"card"|"from"|"to">|null @ 选择的卡牌、起点玩家id和终点玩家id列表
+---@param flag? string @ 限定可移动的区域，值为nil（装备区和判定区）、‘e’或‘j’
+---@param moveFrom? ServerPlayer @ 是否只是目标1移动给目标2
+---@param excludeIds? integer[] @ 本次不可移动的卡牌id
+---@return table<"card"|"from"|"to">? @ 选择的卡牌、起点玩家id和终点玩家id列表
 function Room:askForMoveCardInBoard(player, targetOne, targetTwo, skillName, flag, moveFrom, excludeIds)
   if flag then
     assert(flag == "e" or flag == "j")
@@ -2289,9 +2290,9 @@ end
 ---@param player ServerPlayer @ 要做选择的玩家
 ---@param prompt string @ 提示信息
 ---@param skillName string @ 技能名
----@param cancelable bool @ 是否可以取消选择
----@param flag string|null @ 限定可移动的区域，值为nil（装备区和判定区）、‘e’或‘j’
----@param no_indicate bool @ 是否不显示指示线
+---@param cancelable? boolean @ 是否可以取消选择
+---@param flag? string @ 限定可移动的区域，值为nil（装备区和判定区）、‘e’或‘j’
+---@param no_indicate? boolean @ 是否不显示指示线
 ---@return integer[] @ 选择的玩家id列表，可能为空
 function Room:askForChooseToMoveCardInBoard(player, prompt, skillName, cancelable, flag, no_indicate, excludeIds)
   if flag then
@@ -2753,11 +2754,11 @@ function Room:responseCard(cardResponseEvent)
 end
 
 ---@param card_name string @ 想要视为使用的牌名
----@param subcards integer[]|nil @ 子卡，可以留空或者直接nil
+---@param subcards? integer[] @ 子卡，可以留空或者直接nil
 ---@param from ServerPlayer @ 使用来源
 ---@param tos ServerPlayer | ServerPlayer[] @ 目标角色（列表）
----@param skillName string|nil @ 技能名
----@param extra bool @ 是否不计入次数
+---@param skillName? string @ 技能名
+---@param extra? boolean @ 是否不计入次数
 function Room:useVirtualCard(card_name, subcards, from, tos, skillName, extra)
   local card = Fk:cloneCard(card_name)
   card.skillName = skillName
@@ -2791,7 +2792,7 @@ end
 
 --- 传入一系列移牌信息，去实际移动这些牌
 ---@vararg CardsMoveInfo
----@return boolean
+---@return boolean?
 function Room:moveCards(...)
   return execGameEvent(GameEvent.MoveCards, ...)
 end
@@ -2799,8 +2800,8 @@ end
 --- 让一名玩家获得一张牌
 ---@param player integer|ServerPlayer @ 要拿牌的玩家
 ---@param cid integer|Card @ 要拿到的卡牌
----@param unhide bool @ 是否明着拿
----@param reason CardMoveReason|nil @ 卡牌移动的原因
+---@param unhide? boolean @ 是否明着拿
+---@param reason? CardMoveReason @ 卡牌移动的原因
 function Room:obtainCard(player, cid, unhide, reason)
   if type(cid) ~= "number" then
     assert(cid and cid:isInstanceOf(Card))
@@ -2828,8 +2829,8 @@ end
 --- 让玩家摸牌
 ---@param player ServerPlayer @ 摸牌的玩家
 ---@param num integer @ 摸牌数
----@param skillName string|nil @ 技能名
----@param fromPlace string|nil @ 摸牌的位置，"top" 或者 "bottom"
+---@param skillName? string @ 技能名
+---@param fromPlace? string @ 摸牌的位置，"top" 或者 "bottom"
 ---@return integer[] @ 摸到的牌
 function Room:drawCards(player, num, skillName, fromPlace)
   local drawData = {
@@ -2860,14 +2861,14 @@ function Room:drawCards(player, num, skillName, fromPlace)
 end
 
 --- 将一张或多张牌移动到某处
----@param card Card | Card[] @ 要移动的牌
+---@param card integer | Card | Card[] @ 要移动的牌
 ---@param to_place integer @ 移动的目标位置
 ---@param target ServerPlayer @ 移动的目标玩家
----@param reason integer|nil @ 移动时使用的移牌原因
----@param skill_name string|nil @ 技能名
----@param special_name string|nil @ 私人牌堆名
----@param visible bool @ 是否明置
----@param proposer integer | nil
+---@param reason? integer @ 移动时使用的移牌原因
+---@param skill_name? string @ 技能名
+---@param special_name? string @ 私人牌堆名
+---@param visible? boolean @ 是否明置
+---@param proposer? integer
 function Room:moveCardTo(card, to_place, target, reason, skill_name, special_name, visible, proposer)
   reason = reason or fk.ReasonJustMove
   skill_name = skill_name or ""
@@ -2917,9 +2918,9 @@ end
 --- 改变一名玩家的体力。
 ---@param player ServerPlayer @ 玩家
 ---@param num integer @ 变化量
----@param reason string|nil @ 原因
----@param skillName string|nil @ 技能名
----@param damageStruct DamageStruct|null @ 伤害数据
+---@param reason? string @ 原因
+---@param skillName? string @ 技能名
+---@param damageStruct? DamageStruct @ 伤害数据
 ---@return boolean
 function Room:changeHp(player, num, reason, skillName, damageStruct)
   return execGameEvent(GameEvent.ChangeHp, player, num, reason, skillName, damageStruct)
@@ -2938,7 +2939,7 @@ end
 --- 令一名玩家失去体力。
 ---@param player ServerPlayer @ 玩家
 ---@param num integer @ 失去的数量
----@param skillName string|nil @ 技能名
+---@param skillName? string @ 技能名
 ---@return boolean
 function Room:loseHp(player, num, skillName)
   return execGameEvent(GameEvent.LoseHp, player, num, skillName)
@@ -2987,8 +2988,8 @@ end
 --- 每个skill_name都是要获得的技能的名。如果在skill_name前面加上"-"，那就是失去技能。
 ---@param player ServerPlayer @ 玩家
 ---@param skill_names string[] | string @ 要获得/失去的技能
----@param source_skill string | Skill | null @ 源技能
----@param no_trigger bool @ 是否不触发相关时机
+---@param source_skill? string | Skill @ 源技能
+---@param no_trigger? boolean @ 是否不触发相关时机
 function Room:handleAddLoseSkills(player, skill_names, source_skill, sendlog, no_trigger)
   if type(skill_names) == "string" then
     skill_names = skill_names:split("|")
@@ -3070,8 +3071,8 @@ end
 ---@param card Card @ 改判的牌
 ---@param player ServerPlayer @ 改判的玩家
 ---@param judge JudgeStruct @ 要被改判的判定数据
----@param skillName string|nil @ 技能名
----@param exchange bool @ 是否要替换原有判定牌（即类似鬼道那样）
+---@param skillName? string @ 技能名
+---@param exchange? boolean @ 是否要替换原有判定牌（即类似鬼道那样）
 function Room:retrial(card, player, judge, skillName, exchange)
   if not card then return end
   local triggerResponded = self.owner_map[card:getEffectiveId()] == player
@@ -3121,9 +3122,9 @@ end
 
 --- 弃置一名角色的牌。
 ---@param card_ids integer[] @ 被弃掉的牌
----@param skillName string|nil @ 技能名
+---@param skillName? string @ 技能名
 ---@param who ServerPlayer @ 被弃牌的人
----@param thrower ServerPlayer|nil @ 弃别人牌的人
+---@param thrower? ServerPlayer @ 弃别人牌的人
 function Room:throwCard(card_ids, skillName, who, thrower)
   if type(card_ids) == "number" then
     card_ids = {card_ids}
@@ -3143,7 +3144,7 @@ end
 --- 重铸一名角色的牌。
 ---@param card_ids integer[] @ 被重铸的牌
 ---@param who ServerPlayer @ 重铸的角色
----@param skillName string|nil @ 技能名，默认为“重铸”
+---@param skillName? string @ 技能名，默认为“重铸”
 function Room:recastCard(card_ids, who, skillName)
   if type(card_ids) == "number" then
     card_ids = {card_ids}
@@ -3280,7 +3281,7 @@ function Room:useSkill(player, skill, effect_cb)
 end
 
 ---@param player ServerPlayer
----@param sendLog bool
+---@param sendLog? boolean
 function Room:revivePlayer(player, sendLog)
   if not player.dead then return end
   self:setPlayerProperty(player, "dead", false)
@@ -3355,7 +3356,7 @@ function Room:gameOver(winner)
 end
 
 ---@param card Card
----@param fromAreas CardArea[]|null
+---@param fromAreas? CardArea[]
 ---@return integer[]
 function Room:getSubcardsByRule(card, fromAreas)
   if card:isVirtual() and #card.subcards == 0 then
@@ -3374,9 +3375,9 @@ function Room:getSubcardsByRule(card, fromAreas)
 end
 
 ---@param pattern string
----@param num number|null
----@param fromPile string|null @ 查找的来源区域，值为drawPile|discardPile|allPiles
----@return cardId[]
+---@param num? number
+---@param fromPile? string @ 查找的来源区域，值为drawPile|discardPile|allPiles
+---@return integer[] @ id列表 可能空
 function Room:getCardsFromPileByRule(pattern, num, fromPile)
   num = num or 1
   local pileToSearch = self.draw_pile
@@ -3432,10 +3433,10 @@ function Room:getCardsFromPileByRule(pattern, num, fromPile)
   return cardPack
 end
 
----@param flag string|null
----@param players ServerPlayer[]|null
----@param excludeIds CardId[]|null
----@return PlayerId[] @ 可能为空
+---@param flag? string
+---@param players? ServerPlayer[]
+---@param excludeIds? integer[]
+---@return integer[] @ 玩家id列表 可能为空
 function Room:canMoveCardInBoard(flag, players, excludeIds)
   if flag then
     assert(flag == "e" or flag == "j")
@@ -3461,8 +3462,8 @@ end
 
 --- 现场印卡。当然了，这个卡只和这个房间有关。
 ---@param name string @ 牌名
----@param suit Suit|nil @ 花色
----@param number integer|nil @ 点数
+---@param suit? Suit @ 花色
+---@param number? integer @ 点数
 ---@return Card
 function Room:printCard(name, suit, number)
   local cd = Fk:cloneCard(name, suit, number)
diff --git a/lua/server/serverplayer.lua b/lua/server/serverplayer.lua
index edfb21a9..11b53b38 100644
--- a/lua/server/serverplayer.lua
+++ b/lua/server/serverplayer.lua
@@ -69,7 +69,7 @@ end
 --- *timeout* must not be negative. If nil, room.timeout is used.
 ---@param command string
 ---@param jsonData string
----@param timeout integer|nil
+---@param timeout? integer
 function ServerPlayer:doRequest(command, jsonData, timeout)
   self.client_reply = ""
   self.reply_ready = false
@@ -191,7 +191,7 @@ function ServerPlayer:waitForReply(timeout)
 end
 
 ---@param player ServerPlayer
----@param observe bool
+---@param observe? boolean
 function ServerPlayer:marshal(player, observe)
   local room = self.room
   if not room.game_started then
@@ -492,7 +492,7 @@ function ServerPlayer:gainAnExtraPhase(phase, delay)
   room:broadcastProperty(self, "phase")
 end
 
----@param phase_table Phase[]|nil
+---@param phase_table? Phase[]
 function ServerPlayer:play(phase_table)
   phase_table = phase_table or {}
   if #phase_table > 0 then
@@ -639,7 +639,7 @@ end
 ---@param pile_name string
 ---@param card integer|Card
 ---@param visible boolean
----@param skillName string|nil
+---@param skillName? string
 function ServerPlayer:addToPile(pile_name, card, visible, skillName)
   local room = self.room
   room:moveCardTo(card, Card.PlayerSpecial, self, fk.ReasonJustMove, skillName, pile_name, visible)
@@ -756,10 +756,9 @@ function ServerPlayer:reset()
 end
 
 --- 进行拼点。
----@param from ServerPlayer
 ---@param tos ServerPlayer[]
 ---@param skillName string
----@param initialCard Card|nil
+---@param initialCard? Card
 ---@return PindianStruct
 function ServerPlayer:pindian(tos, skillName, initialCard)
   local pindianData = { from = self, tos = tos, reason = skillName, fromCard = initialCard, results = {} }
@@ -769,7 +768,7 @@ end
 
 --- 播放技能的语音。
 ---@param skill_name string @ 技能名
----@param index integer | nil @ 语音编号，默认为-1（也就是随机播放）
+---@param index? integer @ 语音编号，默认为-1（也就是随机播放）
 function ServerPlayer:broadcastSkillInvoke(skill_name, index)
   index = index or -1
   self.room:sendLogEvent("PlaySkillSound", {
@@ -829,7 +828,7 @@ function ServerPlayer:isFakeSkill(skill)
 end
 
 ---@param skill string | Skill
----@param isPrelight bool
+---@param isPrelight? boolean
 function ServerPlayer:prelightSkill(skill, isPrelight)
   if type(skill) == "string" then skill = Fk.skills[skill] end
   assert(skill:isInstanceOf(Skill))
@@ -858,8 +857,8 @@ function ServerPlayer:prelightSkill(skill, isPrelight)
   self:doNotify("PrelightSkill", json.encode{ skill.name, isPrelight })
 end
 
----@param isDeputy bool
----@param no_trigger bool
+---@param isDeputy? boolean
+---@param no_trigger? boolean
 function ServerPlayer:revealGeneral(isDeputy, no_trigger)
   local room = self.room
   local generalName
diff --git a/lua/server/system_enum.lua b/lua/server/system_enum.lua
index 4a7d889b..3219e62c 100644
--- a/lua/server/system_enum.lua
+++ b/lua/server/system_enum.lua
@@ -4,45 +4,45 @@
 
 ---@class CardsMoveInfo
 ---@field public ids integer[]
----@field public from integer|null
----@field public to integer|null
----@field public toArea CardArea
----@field public moveReason CardMoveReason|nil
----@field public proposer integer|nil
----@field public skillName string|null
----@field public moveVisible bool
----@field public specialName string|null
----@field public specialVisible bool
+---@field public from? integer
+---@field public to? integer
+---@field public toArea? CardArea
+---@field public moveReason? CardMoveReason
+---@field public proposer? integer
+---@field public skillName? string
+---@field public moveVisible? boolean
+---@field public specialName? string
+---@field public specialVisible? boolean
 
 ---@class MoveInfo
 ---@field public cardId integer
 ---@field public fromArea CardArea
----@field public fromSpecialName string|null
+---@field public fromSpecialName? string
 
 ---@class CardsMoveStruct
 ---@field public moveInfo MoveInfo[]
----@field public from integer|null
----@field public to integer|null
+---@field public from? integer
+---@field public to? integer
 ---@field public toArea CardArea
 ---@field public moveReason CardMoveReason
----@field public proposer integer|null
----@field public skillName string|null
----@field public moveVisible bool
----@field public specialName string|null
----@field public specialVisible bool
----@field public drawPilePosition number|null @ 移至牌堆的索引位置，值为-1代表置入牌堆底，或者牌堆牌数+1也为牌堆底
+---@field public proposer? integer
+---@field public skillName? string
+---@field public moveVisible? boolean
+---@field public specialName? string
+---@field public specialVisible? boolean
+---@field public drawPilePosition? integer @ 移至牌堆的索引位置，值为-1代表置入牌堆底，或者牌堆牌数+1也为牌堆底
 
 ---@class PindianResult
 ---@field public toCard Card
----@field public winner ServerPlayer|null
+---@field public winner? ServerPlayer
 
 --- 描述和一次体力变化有关的数据
 ---@class HpChangedData
 ---@field public num integer @ 体力变化量，可能是正数或者负数
 ---@field public reason string @ 体力变化原因
 ---@field public skillName string @ 引起体力变化的技能名
----@field public damageEvent DamageStruct|nil @ 引起这次体力变化的伤害数据
----@field public preventDying bool @ 是否阻止本次体力变更流程引发濒死流程
+---@field public damageEvent? DamageStruct @ 引起这次体力变化的伤害数据
+---@field public preventDying? boolean @ 是否阻止本次体力变更流程引发濒死流程
 
 --- 描述跟失去体力有关的数据
 ---@class HpLostData
@@ -58,27 +58,27 @@ fk.IceDamage = 4
 
 --- DamageStruct 用来描述和伤害事件有关的数据。
 ---@class DamageStruct
----@field public from ServerPlayer|null @ 伤害来源
+---@field public from? ServerPlayer @ 伤害来源
 ---@field public to ServerPlayer @ 伤害目标
 ---@field public damage integer @ 伤害值
----@field public card Card | nil @ 造成伤害的牌
----@field public chain bool @ 伤害是否是铁索传导的伤害
----@field public damageType DamageType | nil @ 伤害的属性
----@field public skillName string | nil @ 造成本次伤害的技能名
----@field public beginnerOfTheDamage boolean | nil @ 是否是本次铁索传导的起点
+---@field public card? Card @ 造成伤害的牌
+---@field public chain? boolean @ 伤害是否是铁索传导的伤害
+---@field public damageType? DamageType @ 伤害的属性
+---@field public skillName? string @ 造成本次伤害的技能名
+---@field public beginnerOfTheDamage? boolean @ 是否是本次铁索传导的起点
 
 --- 用来描述和回复体力有关的数据。
 ---@class RecoverStruct
 ---@field public who ServerPlayer @ 回复体力的角色
 ---@field public num integer @ 回复值
----@field public recoverBy ServerPlayer|nil @ 此次回复的回复来源
----@field public skillName string|nil @ 因何种技能而回复
----@field public card Card|nil @ 造成此次回复的卡牌
+---@field public recoverBy? ServerPlayer @ 此次回复的回复来源
+---@field public skillName? string @ 因何种技能而回复
+---@field public card? Card @ 造成此次回复的卡牌
 
 ---@class DyingStruct
 ---@field public who integer
 ---@field public damage DamageStruct
----@field public ignoreDeath bool
+---@field public ignoreDeath? boolean
 
 ---@class DeathStruct
 ---@field public who integer
@@ -96,57 +96,57 @@ fk.IceDamage = 4
 ---@field public from integer
 ---@field public tos TargetGroup
 ---@field public card Card
----@field public toCard Card|null
----@field public responseToEvent CardUseStruct|null
----@field public nullifiedTargets integer[]|null
----@field public extraUse bool
----@field public disresponsiveList integer[]|null
----@field public unoffsetableList integer[]|null
----@field public additionalDamage integer|null
----@field public additionalRecover integer|null
----@field public customFrom integer|null
----@field public cardsResponded Card[]|null
----@field public prohibitedCardNames string[]|null
----@field public damageDealt table<PlayerId, number>|null
+---@field public toCard? Card
+---@field public responseToEvent? CardUseStruct
+---@field public nullifiedTargets? integer[]
+---@field public extraUse? boolean
+---@field public disresponsiveList? integer[]
+---@field public unoffsetableList? integer[]
+---@field public additionalDamage? integer
+---@field public additionalRecover? integer
+---@field public customFrom? integer
+---@field public cardsResponded? Card[]
+---@field public prohibitedCardNames? string[]
+---@field public damageDealt? table<PlayerId, number>
 
 ---@class AimStruct
 ---@field public from integer
 ---@field public card Card
 ---@field public tos AimGroup
 ---@field public to integer
----@field public subTargets integer[]|null
----@field public targetGroup TargetGroup|null
----@field public nullifiedTargets integer[]|null
+---@field public subTargets? integer[]
+---@field public targetGroup? TargetGroup
+---@field public nullifiedTargets? integer[]
 ---@field public firstTarget boolean
----@field public additionalDamage integer|null
----@field public additionalRecover integer|null
----@field public disresponsive bool
----@field public unoffsetableList bool
----@field public additionalResponseTimes table<string, integer>|integer|null
----@field public fixedAddTimesResponsors integer[]
+---@field public additionalDamage? integer
+---@field public additionalRecover? integer
+---@field public disresponsive? boolean
+---@field public unoffsetableList? boolean
+---@field public additionalResponseTimes? table<string, integer>|integer
+---@field public fixedAddTimesResponsors? integer[]
 
 ---@class CardEffectEvent
 ---@field public from integer
 ---@field public to integer
----@field public subTargets integer[]|null
+---@field public subTargets? integer[]
 ---@field public tos TargetGroup
 ---@field public card Card
----@field public toCard Card|null
----@field public responseToEvent CardEffectEvent|null
----@field public nullifiedTargets integer[]|null
----@field public extraUse bool
----@field public disresponsiveList integer[]|null
----@field public unoffsetableList integer[]|null
----@field public additionalDamage integer|null
----@field public additionalRecover integer|null
----@field public customFrom integer|null
----@field public cardsResponded Card[]|null
----@field public disresponsive bool
----@field public unoffsetable bool
----@field public isCancellOut bool
----@field public fixedResponseTimes table<string, integer>|integer|null
----@field public fixedAddTimesResponsors integer[]
----@field public prohibitedCardNames string[]|null
+---@field public toCard? Card
+---@field public responseToEvent? CardEffectEvent
+---@field public nullifiedTargets? integer[]
+---@field public extraUse? boolean
+---@field public disresponsiveList? integer[]
+---@field public unoffsetableList? integer[]
+---@field public additionalDamage? integer
+---@field public additionalRecover? integer
+---@field public customFrom? integer
+---@field public cardsResponded? Card[]
+---@field public disresponsive? boolean
+---@field public unoffsetable? boolean
+---@field public isCancellOut? boolean
+---@field public fixedResponseTimes? table<string, integer>|integer
+---@field public fixedAddTimesResponsors? integer[]
+---@field public prohibitedCardNames? string[]
 
 ---@class SkillEffectEvent
 ---@field public from integer
@@ -158,14 +158,14 @@ fk.IceDamage = 4
 ---@field public card Card
 ---@field public reason string
 ---@field public pattern string
----@field public skipDrop bool
+---@field public skipDrop? boolean
 
 ---@class CardResponseEvent
 ---@field public from integer
 ---@field public card Card
----@field public responseToEvent CardEffectEvent|null
----@field public skipDrop bool
----@field public customFrom integer|null
+---@field public responseToEvent? CardEffectEvent
+---@field public skipDrop? boolean
+---@field public customFrom? integer
 
 ---@class AskForCardUse
 ---@field public user ServerPlayer
@@ -202,12 +202,12 @@ fk.ReasonJudge = 11
 
 ---@class LogMessage
 ---@field public type string
----@field public from integer | nil
----@field public to integer[] | nil
----@field public card integer[] | nil
----@field public arg any
----@field public arg2 any
----@field public arg3 any
+---@field public from? integer
+---@field public to? integer[]
+---@field public card? integer[]
+---@field public arg? any
+---@field public arg2? any
+---@field public arg3? any
 
 ---@class SkillUseStruct
 ---@field public skill Skill
diff --git a/packages/standard/ai/aux_skills.lua b/packages/standard/ai/aux_skills.lua
index bbcabfee..df608b0e 100644
--- a/packages/standard/ai/aux_skills.lua
+++ b/packages/standard/ai/aux_skills.lua
@@ -5,7 +5,7 @@
 -----------------------------
 
 --- 弃牌相关判定函数的表。键为技能名，值为原型如下的函数。
----@type table<string, fun(self: SmartAI, min_num: number, num: number, include_equip: bool, cancelable: bool, pattern: string, prompt: string): integer[]|nil>
+---@type table<string, fun(self: SmartAI, min_num: number, num: number, include_equip?: boolean, cancelable?: boolean, pattern: string, prompt: string): integer[]?>
 fk.ai_discard = {}
 
 local default_discard = function(self, min_num, num, include_equip, cancelable, pattern, prompt)
@@ -38,11 +38,11 @@ end
 -------------------------------------
 
 ---@class ChoosePlayersReply
----@field cardId integer|nil
+---@field cardId? integer
 ---@field targets integer[]
 
 --- 选人相关判定函数的表。键为技能名，值为原型如下的函数。
----@type table<string, fun(self: SmartAI, targets: integer[], min_num: number, num: number, cancelable: bool): ChoosePlayersReply|nil>
+---@type table<string, fun(self: SmartAI, targets: integer[], min_num: number, num: number, cancelable?: boolean): ChoosePlayersReply?>
 fk.ai_choose_players = {}
 
 fk.ai_active_skill["choose_players_skill"] = function(self, prompt, cancelable, data)