From 604e1d00b46f4c607f217e829040387bfea1e3f7 Mon Sep 17 00:00:00 2001
From: deepskybird <32931830+deepskybird@users.noreply.github.com>
Date: Wed, 12 Apr 2023 13:28:01 +0800
Subject: [PATCH] core_doc_20230412_0844 (#113)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

general/gamemode/skill更新

Co-authored-by: YWSC120 <111111@163.com>
---
 lua/core/game_mode.lua | 18 +++++++++++++-----
 lua/core/general.lua   | 34 ++++++++++++++++++++++++----------
 lua/core/skill.lua     | 34 +++++++++++++++++++++++-----------
 3 files changed, 60 insertions(+), 26 deletions(-)

diff --git a/lua/core/game_mode.lua b/lua/core/game_mode.lua
index a924f11a..695848a2 100644
--- a/lua/core/game_mode.lua
+++ b/lua/core/game_mode.lua
@@ -1,13 +1,21 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+--- GameMode用来描述一个游戏模式。
+---
+--- 可以参考欢乐斗地主。
+---
 ---@class GameMode: Object
----@field public name string
----@field public minPlayer integer
----@field public maxPlayer integer
----@field public rule TriggerSkill
----@field public logic fun()
+---@field public name string @ 游戏模式名
+---@field public minPlayer integer @ 最小玩家数
+---@field public maxPlayer integer @ 最大玩家数
+---@field public rule TriggerSkill @ 规则（通过技能完成，通常用来为特定角色及特定时机提供触发事件）
+---@field public logic fun() @ 逻辑（通过function完成，通常用来初始化、分配身份及座次）
 local GameMode = class("GameMode")
 
+--- 构造函数，不可随意调用。
+---@param name string @ 游戏模式名
+---@param min integer @ 最小玩家数
+---@param max integer @ 最大玩家数
 function GameMode:initialize(name, min, max)
   self.name = name
   self.minPlayer = math.max(min, 2)
diff --git a/lua/core/general.lua b/lua/core/general.lua
index 1fc221e3..8a53d449 100644
--- a/lua/core/general.lua
+++ b/lua/core/general.lua
@@ -1,15 +1,21 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+--- General用来描述一个武将。
+---
+--- 所谓武将，就是所属包、武将基础信息的集合。
+---
+--- 也许···类似于身份证？
+---
 ---@class General : Object
----@field public package Package
----@field public name string
----@field public trueName string
----@field public kingdom string
----@field public hp integer
----@field public maxHp integer
----@field public gender Gender
----@field public skills Skill[]
----@field public other_skills string[]
+---@field public package Package @ 武将所属包
+---@field public name string @ 武将名字
+---@field public trueName string @ 武将真名，也许可以分辨标界？
+---@field public kingdom string @ 武将所属势力
+---@field public hp integer @ 武将初始体力
+---@field public maxHp integer @ 武将初始最大体力
+---@field public gender Gender @ 武将性别
+---@field public skills Skill[] @ 武将技能
+---@field public other_skills string[] @ 武将身上属于其他武将的技能，通过字符串调用
 General = class("General")
 
 ---@alias Gender integer
@@ -17,6 +23,13 @@ General = class("General")
 General.Male = 1
 General.Female = 2
 
+--- 构造函数，不可随意调用。
+---@param package Package @ 武将所属包
+---@param name string @ 武将名字
+---@param kingdom string @ 武将所属势力
+---@param hp integer @ 武将初始体力
+---@param maxHp integer @ 武将初始最大体力
+---@param gender Gender @ 武将性别
 function General:initialize(package, name, kingdom, hp, maxHp, gender)
   self.package = package
   self.name = name
@@ -34,7 +47,8 @@ function General:initialize(package, name, kingdom, hp, maxHp, gender)
   package:addGeneral(self)
 end
 
----@param skill Skill
+--- 为武将增加技能，需要注意增加其他武将技能时的处理方式。
+---@param skill Skill @ （单个）武将技能
 function General:addSkill(skill)
   if (type(skill) == "string") then
     table.insert(self.other_skills, skill)
diff --git a/lua/core/skill.lua b/lua/core/skill.lua
index cfe2f2dd..a50de3b5 100644
--- a/lua/core/skill.lua
+++ b/lua/core/skill.lua
@@ -1,15 +1,17 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+--- Skill用来描述一个技能。
+---
 ---@class Skill : Object
----@field public name string
----@field public trueName string
----@field public package Package
----@field public frequency Frequency
----@field public visible boolean
----@field public mute boolean
----@field public anim_type string
----@field public related_skills Skill[]
----@field public attached_equip string
+---@field public name string @ 技能名
+---@field public trueName string @ 技能真名
+---@field public package Package @ 技能所属的包
+---@field public frequency Frequency @ 技能发动的频繁程度，通常compulsory（锁定技）及limited（限定技）用的多。
+---@field public visible boolean @ 技能是否会显示在游戏中
+---@field public mute boolean @ 决定是否关闭技能配音
+---@field public anim_type string @ 技能类型定义
+---@field public related_skills Skill[] @ 和本技能相关的其他技能，有时候一个技能实际上是通过好几个技能拼接而实现的。
+---@field public attached_equip string @ 属于什么装备的技能？
 local Skill = class("Skill")
 
 ---@alias Frequency integer
@@ -20,6 +22,9 @@ Skill.Compulsory = 3
 Skill.Limited = 4
 Skill.Wake = 5
 
+--- 构造函数，不可随意调用。
+---@param name string @ 技能名
+---@param frequency Frequency @ 技能发动的频繁程度，通常compulsory（锁定技）及limited（限定技）用的多。
 function Skill:initialize(name, frequency)
   -- TODO: visible, lord, etc
   self.name = name
@@ -43,17 +48,24 @@ function Skill:initialize(name, frequency)
   self.attached_equip = nil
 end
 
----@param skill Skill
+--- 为一个技能增加相关技能。
+---@param skill Skill @ 技能
 function Skill:addRelatedSkill(skill)
   table.insert(self.related_skills, skill)
 end
 
+--- 确认本技能是否为装备技能。
 ---@return boolean
 function Skill:isEquipmentSkill()
   return self.attached_equip and type(self.attached_equip) == 'string' and self.attached_equip ~= ""
 end
 
----@param player Player
+--- 确认技能是否对特定玩家生效。
+---
+--- 据说你一般用不到这个，只要你把on_cost（代价）和on_use（效果）区分得当，
+---
+--- 涉及技能无效时，不需要这个函数也可以实现效果。
+---@param player Player @ 玩家
 ---@return boolean
 function Skill:isEffectable(player)
   local nullifySkills = Fk:currentRoom().status_skills[InvaliditySkill] or {}