EgoFramework-Cfg

<!doctype html>

配置表系统

配置表介绍
每个游戏中都或多或少都有一些游戏配置，而团队又是由各个不同职位的成员组合，有程序、策划、美术等等，不同的职位需要同时对游戏逻辑进行干涉，这就造成了耦合关系，如果没处理好耦合关系的话，就会使效率变慢，配置表的意义就是程序实现好了逻辑之后，策划可以根据策划的需求去调整配置表。
该配置表系统采用csv的格式配置文件。csv，又称为逗号分隔值文件格式，是按照固定分隔字符（一般是逗号）分隔的纯文本文件，因为是纯文本文件，所以在不同平台不会有兼容性问题，支持Excel编辑并输出csv格式，比xml或json少了很多重复键值的定义，文件占用小，编辑和查看更加方便，是一种广泛商业使用的格式。
csv的文件格式如下：item.csv（注意：id不能重复）
id itemName price effect
#自增id 物品名称价格使用效果(hug：饥饿值#加多少;gold:金币#加多少)
1001 鱼蛋 10 hug#10;gold#-10;
1002 麻球 20 hug#20;gold#-20;

id	itemName	price	effect
#自增id	物品名称	价格	使用效果(hug：饥饿值#加多少;gold:金币#加多少)
1001	鱼蛋	10	hug#10;gold#-10;
1002	麻球	20	hug#20;gold#-20;

快速开始

使用方法1（该方法只是初级用法，正式开发请使用方法2）


xxxxxxxxxx
TextAsset csvText = Resources.Load ("item", typeof(TextAsset)) as TextAsset;
//使用TextAsset初始化
CSV csv = new CSV(csvText);
//获取1001那行的itemName
csv.GetValueByLineAndRow("1001", "itemName");

或


xxxxxxxxxx
//读取外部txt配置
LoadTextAction textAction=new LoadTextAction(Application.streamingAssetsPath+"/"+"item.csv");
textAction.Start(delegate
{
    string text = textAction.TextValue;
    //使用TextAsset初始化
    CSV csv = new CSV("item", text);
    //获取1001那行的itemName
    csv.GetValueByLineAndRow("1001", "itemName");
});

使用方法2（正式开发请使用该方式）

将配置表与类关联（对于上面csv，转成的类如下，下面会详细介绍如何快速将配置表转换类）


xxxxxxxxxx
using System.Collections.Generic;
public class ItemCfg:CSVConfig<ItemVO,ItemCfg>,IConfigView
{
    public ItemCfg():base("Config/item"){}
    protected override ItemVO OnDecodeCSVHandle(CSVLine data, out string key)
    {
        ItemVO vo = new ItemVO();
        vo.id = data.GetString("id");
        vo.itemName = data.GetString("itemName");
        vo.price = data.GetInt("price");
        vo.effect = ConfigUtil.ParserToKeyDatas<ItemEffectData>(data.GetString("effect"));
        
        key = vo.id;
        return vo;
    }
    
    protected override void OnProviderEditorItemHandle(ConfigEditorItem editorItem, ItemVO vo)
    {
        editorItem.displayName = string.Format("{0}({1})", vo.id, vo.itemName);
    }
}
public class ItemVO
{
    public string id;//自增id
    public string itemName;//物品名称
    public int price;//价格
    public List<ItemEffectData> effect;//使用效果
}
public class ItemEffectData : BaseKeyData
{
    public string effectType;
    public int effectValue;
    
    protected override void OnRead()
    {
        effectType = GetString(0);
        effectValue = GetInt(1);
    }
    protected override void OnWrite()
    {
        WriteData(effectType);
        WriteData(effectValue);
    }
}

直接通过代码即可快速获取数据（该类的基类已经处理了加载流程）


xxxxxxxxxx
ItemVO itemVo = ItemCfg.Instance.GetData("1001");
Debug.Log(itemVo.id+"=="+itemVo.itemName+"=="+itemVo.price);

配置表工具
- Config Setting-工具设置（打开方式：Egogame-Config/Config Setting Window）
  
  说明
  该工具是配置配置表的路径，列出当前自动识别到的文件，以及提供一些同步按钮，支持快速更新/同步配置表文件
  工具介绍
  - 原始配置表路径(xlsx)：配置原始配置表(xlsx格式)的路径，一般是在art目录下
    如：D:\felix\cottongame\art\BoyVolunteers\doc\配置表
  - 美术svn的CSV路径：配置导出的csv配置表的路径，原始配置表会导出csv放到该路径，然后同步到Unity
    如：D:\felix\cottongame\art\BoyVolunteers\export\Resources\Config
  - Unity项目的csv路径：csv在Unity的存放路径，默认是在Assets/Game/Resources/Config，配置为该路径即可
  - csv导出软件路径：配置xlsx导出csv格式文件的软件安装路径(.exe路径下)，推荐使用LibreOffice，Excel也可以但是Excel是使用VB导出的，有点慢
    LibreOffice默认安装路径：C:\Program Files\LibreOffice\program
    Excel默认安装路径：C:\Program Files\Microsoft Office\root\Office16
  - CSV配置表：自动找到“Unity项目的csv路径“下的csv文件，列出来，可以点击编辑/生成类/外部打开。一般主要用到生成类，该操作是自动生成对应的继承CSVConfig的类，如ItemCfg，生成的路径在Assets/Game/Scripts/Config
    生成类也可以使用另外一种方式：在Unity编辑器选择csv，右键Config/Create也可创建类
  - 配置表类：列出当前已经生成了类的项，可以点击编辑进行数据编辑，通过该工具可以将数据修改并写入Excel原始表中。
  - 同步Art配置表到Unity：更新美术svn的CSV路径，并自动拷贝到Unity项目
  - 提交Unity的配置表：提交Unity的csv配置表到svn。
  - 提交Art的配置表：弹出svn窗口，将美术资源svn的csv文件提交到svn
  - 打开配置工具：打开配置工具，进行原始数据的修改。
  使用方法
  以上述Item表为例：
  1. 准备一个Item表源文件，item.xlsx，并配置好header头和数据，如上面的配置表
  2. 在ConfigSettingWindow配置对应路径
  3. 配置了“原始配置表路径”后，会多出一个Tab标签，列出当前路径下的所有xlsx源文件
  4. 在原始配置表中找到对应xlsx源文件项，点击“导出csv”按钮，自动将配置表导出csv格式到“美术svn的CSV路径”下。
  5. 点击“同步Art配置表到Unity”按钮，将导出的csv同步到unity
  6. 在“CSV配置表”标签下找到对应的csv文件项，点击生成类，会自动生成对应的类。如：ItemCfg
    生成的路径在：Assets/Game/Scripts/Config
  7. 修改该类的解析方式和变量类型
- Config Editor Window-原始Excel数据修改（打开方式：Egogame/Config/Config Editor Window）
  
  描述
  使用Excel编辑数据的缺点是，对于一些数据不能可视化显示，如道具id为1001，没法编辑时显示为“鱼蛋”，但是保存时保存为1001，还有一些下拉列表等特殊需求，没法可视化显示出来。该工具就是重绘制这些属性，并且支持直接在这个工具修改并保存Excel。上面图片的下拉菜单就是个例子。
  使用方法
  以上述Item表为例：
  1. 找到上面创建出来的ItemCfg类
  2. 自动生成的类应该已经重写displayName，该displayName就是窗口左边"3001(原木)"那个区域显示数据，按照需求修改displayName赋值
```
xxxxxxxxxx
public class ItemCfg:CSVConfig<ItemVO,ItemCfg>,IConfigView
{
    protected override void OnProviderEditorItemHandle(ConfigEditorItem editorItem, ItemVO vo)
    {
        editorItem.displayName = string.Format("{0}({1})", vo.id, vo.itemName);
    }
}
```
  3. 给VO类添加标签
    LabelText：将变量名重新绘制
    Range：Unity自带标签，使数据在区间调节
```
xxxxxxxxxx
public class ItemVO
{
    public string id;//自增id
    [LabelText("物品名称：")]
    public string itemName;//物品名称
    [Range(1,1000)]
    public int price;//价格
    public List<ItemEffectData> effect;//使用效果
}
```
  4. 对特殊变量，如变量名和csv的头名称不一致时，需要指定解析规则
```
xxxxxxxxxx
protected override void OnProviderTableDataHandle(Dictionary<string, string> tableData, AttributeVO vo)
{
    base.OnProviderTableDataHandle(tableData, vo);
    //强制覆盖数据
    tableData.SetValue("FixBelowZero", vo.FixBelowZero ? "2" : "1");
}
```
  5. 如果成员变量是BaseKeyData或者BaseKeyData数组，需要实现BaseKeyData的OnWrite方法。

相关类介绍

CSV类

描述

解析csv文本文件的工具类，封装了一些常用的API如获取某个格子的数据等等。该工具类只需要了解解析原理即可，一般不需要用到。他的作用是按照csv格式解析数据并缓存。

方法

方法名	返回类型	说明
ParseCSV	List<string[]>	解析文本文件，返回解析后的数据
ToCSVString	string	将数据转为csv数据（如果有双引号，则自动增加""）
GetValueByLineAndRow	string	通过行和列获取数据
GetLineText	Dictionary<string,string>	获取行数据
GetDataByLine	Dictionary<string,string>	获取某行的数据项字典
GetDataByNameAndValue	Dictionary<string,string>	获取匹配key和value的格子数据
LineDatas	List<Dictionary<string,string>>	行数据
HeaderTypeData	Dictionary<string, string>	获取头类型
Datas	Dictionary<string, Dictionary<string, string>>	总数据
Count	int	总行
Headers	string[]	文件头
Comments	string[]	备注
HeaderTypes	string[]	头类型
Content	string	源文本数据
AssetName	string	文件名

BaseConfig类

描述

配置文件基类，主要功能是根据文件路径，自动加载文件并提供重写方法，供子类进行重写解析为对应格式的数据。文本文件修改时，自动更新类缓存的数据。

方法

方法名	说明
LoadFile	加载文件（一般情况下不需要调用，实例化构造体时会自行调用）
LoadCSV	改变CSV（直接设置CSV数据）
IsSameFile	判断是否是同名文件
Reload	重新读取该文件并通知数据变更
FileName	当前文件名

可重写

方法名	说明
OnParserBeginHandle	解析开始
OnParserHandle	正式解析
OnParserResetHandle	数据重置，一般用来清空自定义的缓存数据变量
OnParserEndHandle	解析结束

CSVConfig<T,T2>类

描述

该类是针对csv的解析类，自动将文本文件解析为特定类格式的数据，提供给其他类继承。T一般是VO类，而T2就是继承的类的本身。

继承关系

继承：BaseConfig

实现接口：IConfig

属性

属性名	返回类型	说明
ConfigList	List	所有配置项列表（如上面的示例，一行数据就会解析为一个T类）
Instance	T2	获取单例
ConfigItems	IList	同ConfigList，只是这个是返回IList
IdName	string	该表以哪个字段作为Key，一般是第一列的头名称
EditorItems	List	为了支持编辑器工具的数据（大概了解即可）

方法

方法名	返回类型	说明
GetData	T	通过键值获取T类，如上面示例，通过1001可以获取包装后的T类
HasData	bool	通过键值判断是否有该数据项
GetConfigList	List	获取配置列表。同属性ConfigList
GetTableData	Dictionary<string, string>	将一个vo转换为字典形式，可以转换填在配置表中。默认支持List、string、int、float。（编辑器使用，了解即可）
Clone	ConfigEditorItem	克隆EditorItem（编辑器使用，了解即可）

可重写

方法名	返回类型	说明
OnDecodeCSVHandle	T	提供将文本数据解析为类的实现接口
OnProviderEditorItemHandle	void	（编辑器工具使用）提供重写EditorItem数据（需实现，主要重写displayName）
OnProviderTableDataHandle	void	（编辑器工具使用）提供将数据反写入原始Excel表格的重定向，主要解决如果数据没有自动映射时，需要提供重定向。

BaseKeyData类

描述

该类的作用是作为VO类的成员，CSVConfig将类解析为VO类，但是如果某个单元格的数据是列表或者更复杂的数据呢？该类就是用来解析单元格复杂数据的，按照一定的格式。目前支持的格式为：#号分隔，$号分隔，;号分隔。请配合ConfigUtil类使用，后续会介绍到。

如上面的示例表，数据项hug#10;gold#-10;将解析为List，分号代表数组分隔，#号代表数据分隔，$代表数据项的子数据分隔。

使用方法

继承BaseKeyData
实现OnRead，获取数据，并将数据赋值到变量

实现OnWrite，按照数据顺序，将数据写入Excel（主要是编辑器工具使用）


xxxxxxxxxx
/// <summary>
/// Key value数据类
/// </summary>
public class KeyValueData:BaseKeyData
{
    public string key;
    public string value;
    protected override void OnRead()
    {
        key = GetString(0);
        value = GetString(1);
    }
    protected override void OnWrite()
    {
        WriteData(key);
        WriteData(value);
    }
}

方法

方法名	返回类型	说明
GetString(int index)	string	获取string
GetInt(int index)	int	获取Int
GetFloat(int index)	float	获取float
GetBool(int index)	bool	获取bool
GetIntEnum(int index)	T	获取枚举（如数据是1，则使用1转为枚举）
GetStringEnum(string value)	T	通过字符串获取枚举（如数据是hug，则使用hug转为枚举）
WriteData(string value)	void	写入String
WriteData(float value)	void	写入float
WriteData(int value)	void	写入int
WriteData(BaseKeyData value)	void	写入BaseKeyData
HasData(int index)	bool	判断索引是否有数据
ToTextValue(List datas)	string	转成Text
ToTextValue(string[] datas)	string	转成Text
GetTableStringData()	string	获取表格数据(编辑器用)

属性

属性名	返回类型	说明
ParserType	ConfigUtil.ParserType	解析类型
Text	string	原始文本
Error	string	错误信息（可以提供显示错误信息）

可重写

方法名	说明
OnRead	获取数据，并将数据赋值到变量
OnWrite	按照数据顺序，将数据写入Excel（主要是编辑器工具使用）
IsError	判断该类是否有解析数据错误信息（方便统一显示）

ConfigUtil类

描述

该类是一个静态工具类，主要作用是提供一些方法，快速将数据转换为对应KeyData类等等。

方法

方法名	返回类型	说明
ToIntEnum(string value)	T	将int数据转换为枚举
T ToStringEnum(string value)	T	将string数据转换为枚举
ToInt(string value)	int	转Int
ToFloat(string value)	float	转Float
ToBool(string value)	bool	转bool
ParserToKeyDatas	List	将string转成数据数组，如1#2#3;1#2#4。
ParserToKeyData	T:BaseKeyData	将string转成数据类
Parser2Array(string text)	string[]	将string转成数组(;号分隔)
Parser2Vector3(string text)	Vector3	将string转成Vector3(#号分隔)
Parser2List(string text)	List	将string转成数组
Parser2IntList(string text)	List	将string转成数组
ParserValueList	string[]	将string转换为数组
ValueListToText	string	数组转String
ParserSubValueList	string[]	将string转数组（数据是$号分隔）
SubValueListToText(string[] valueList)	string	数组转String（数据是$号分隔）
KeyDataToText(BaseKeyData keyData)	string	KeyData转string
KeyDatasToText(IList list)	string	KeyData数组转string
GetConfigDropdownItems	IEnumerable	获取配置表的ValueDropdownList Id，主要是为ValueDropdown标签提供数据

拓展标签

ConfigAttribute

说明

为string类型变量提供选择功能

使用示例

使用ItemCfg类的ItemIdList变量作为选择列表


xxxxxxxxxx
public class ItemUI
{
   [Config(typeof(ItemCfg),"ItemIdList")]
   public string itemId;
}
public class ItemCfg:CSVConfig<ItemVO,ItemCfg>,IConfigView
{
    public ItemCfg():base("Config/item"){}
    
    public List<PopUpDataCollection> ItemIdList
    {
        get
        {
            List<PopUpDataCollection> result=new List<PopUpDataCollection>();
            foreach (var itemVo in GetConfigList())
            {
                result.Add(new PopUpDataCollection(){guiLabel = itemVo.Name,stringValue = itemVo.ItemId});
            }
            return result;
        }
    }
}

ValueDropdown

说明

该标签为Odin标签，更多Odin标签请参照官方教程。

该标签跟上面标签类似，提供源数据作为可选择列表。

使用示例


xxxxxxxxxx
public class AttributeCfgData
{
    [ValueDropdown("AttrIdSelectionList")]
    public string attributeId;
    
    public IEnumerable AttrIdSelectionList
    {
        get
        {
            return ConfigUtil.GetConfigDropdownItems(AttributeCfg.Instance);
        }
    }
}

示例2：


public class AttributeCfgData
{
    [ValueDropdown("IdSelectionList")] 
    public string attributeId;
    public ValueDropdownList<string> IdSelectionList
    {
        get
        {
            ValueDropdownList<string> valueDropdownItems=new ValueDropdownList<string>();
            foreach (var attributeVo in AttributeCfg.Instance.GetConfigList())
            {
                valueDropdownItems.Add(new ValueDropdownItem<string>(attributeVo.Name,attributeVo.AttributeId));
            }
            return valueDropdownItems;
        }
    }
}

更多Odin标签请查看Tools/Odin Inspector/Getting Started或参照官方教程。

WeiBlog