# CSOL缔造者lua开发框架 Sugar

**Repository Path**: csolcreator/sugar

## Basic Information

- **Project Name**: CSOL缔造者lua开发框架 Sugar
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-02-12
- **Last Updated**: 2025-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSOL缔造者lua开发框架 Sugar(1.0.2)

## 特性
* 单事件多绑定
Game.Rule对象和UI.Event对象支持单事件多绑定，同一个事件可绑定多个函数
* 事件函数列表处理器
系统默认处理器的处理机制是单个事件绑定多个函数，所有函数按顺序依次执行，并向CSOL返回第一个 **有返回值的函数** 的返回值，如果系统默认处理器无法满足用户需求，用户可以自定义处理器
* 更加方便CSOL缔造者Lua开发的工具类

## SugarGame模块
用于Game端(即服务器端)的模块
##### SugarGame.Events (服务端事件列表)
**SugarGame.Events** 中的事件为 **Game.Rule** 对象的常用事件（回调函数/呼叫式函数），现支持的事件有
* OnPlayerConnect
* OnPlayerDisconnect
* OnRoundStart
* OnRoundStartFinished
* OnPlayerSpawn
* OnPlayerAttack
* OnPlayerKilled
* OnUpdate
* OnPlayerSignal
* OnGetWeapon

**SugarGame.Events** 中的每个对象都包含以下3个属性
* name 事件名称
* handler 函数列表处理器（如果为nil则使用默认的函数列表处理规则）
* functions 事件绑定的多个函数，事件被触发后会按照**handler(函数列表处理器)**的规则进行处理

## SugarUi 模块
用于Ui端（即客户端）的模块
##### SugarUi.Events (客户端事件列表)
**SugarUi.Events** 中的事件为 **UI.Event** 对象的常用事件（回调函数/呼叫式函数），现支持的事件有
* OnSpawn
* OnKilled
* OnChat
* OnSignal
* OnKeyDown
* OnKeyUp
* OnInput
* OnUpdate
  
**SugarUi.Events** 中的每个事件都包含以下3个属性
* name 事件名称
* handler 函数列表处理器（如果为nil则使用默认的函数列表处理规则）
* functions 事件绑定的多个函数，事件被触发后会按照**handler(函数列表处理器)**的规则进行处理

## SugerUtil模块
实现在CSOL缔造者Lua开发中的常用工具类
##### SugerUtil.Position
坐标工具类，所有包含x、y和z这3个数属性的table类型变量都可以被坐标工具类处理
* SugarUtil.Position:isIn
判断空间中某点是否在两个顶点形成的长方体空间中
* SugarUtil.Position:toString
将position变量转换为{x=,y=,z=}这种格式的字符串
可用于**print**函数或**log**函数输出position对象
* SugarUtil.Position:toPosition
为 **SugarUtil.Position:toString** 函数的逆操作
此外，只要字符串是由6个互相分隔的数值(即数字之间被其他字符分割)组成，就可以被此函数转换为坐标类型的变量，如
3 3 4
4,8,-1
X4Y0Z-1
4 A-3 |3
等字符串都可以被转换为position格式的变量
* SugarUtil.Position:toPositions
与 **SugarUtil.Position:toPosition** 类似，只要字符串是由3的倍数个互相分隔的数值组成，就可以被转换为position类型的列表，如
1 2 4 4 5 9
1,4,8, 11,10,-1, 2,9,3
P(9,14,5) A(100,-24, 5) B(78, 3, 5)
等字符串都可以被转换为多个position形成的列表
如果字符串中的数值不是 **3** 的倍数则返回 **nil**
##### SugarUtil.Time
日期时间工具类
* SugarUtil.Time:ofSeconds
将秒数转换为包含 **小时** 、**分钟** 和**秒**，和 **小数点后两位**共4个字段的时间变量
* SugarUtil.Time:toString
将ofSeconds运算得到的时间变量格式化为字符串
信号量
##### SugarUtil.ValueSignal
可携带其他值的信号量
* SugarUtil.ValueSignal:toValueSignal
创建一个可携带值的信号量
* SugarUtil.ValueSignal:getValue
从ValueSignal中获取携带的值
* SugarUtil.ValueSignal:getSignal
从ValueSignal中获取实际的信号量
* SugarUtil.ValueSignal:recoveryFromValueSignal
为 **SugarUtil.ValueSignal:toValueSignal** 的逆操作

## 使用
##### 引入
在 **project.json** 中引入即可
```json
{
    "game": ["sugar/SugarGame.lua", "game.lua"], 
    "ui": ["sugar/SugarUi.lua", "ui.lua"]
}
```
##### 绑定事件
可在任意Game端包含的lua文件中注册**Game.Rule**对象的事件，如下
```lua
-- 玩家复活事件绑定了两个函数，当这个事件被触发时，默认情况下这两个函数会被依次调用
table.insert( SugarGame.Events.OnPlayerSpawn, function (player)
    print("hh玩家复活被调用的第一个函数")
end)

table.insert( SugarGame.Events.OnPlayerSpawn, function (player)
    print("hh玩家复活被调用的第二个函数")
end)

-- 玩家被击杀绑定了一个函数
table.insert( SugarGame.Events.:OnPlayerKilled, function (victim, killer)
    print("玩家被["..killer.name.."]击杀了")
end)
```
可在任意UI端包含的lua文件中注册**UI.Event**对象的事件，如下
```lua
-- 玩家输入文字绑定了一个函数
table.insert( SugarGame.Events.OnChat, function (text)
    print("玩家输入了一段文字:")
    print(text)
end)

-- 玩家按下按键绑定了两个函数，当这个事件被触发时，默认情况下这两个函数会被依次调用
table.insert( SugarGame.Events.OnKeyDown, function (inputs)
    if inputs[UI.KEY.W] == true
        print("玩家按下了W键!")
    end
end)
table.insert( SugarGame.Events.OnKeyDown, function (inputs)
    if inputs[UI.KEY.W] == true
        print("玩家向前移动了!")
    end
    if inputs[UI.KEY.SPACE] == true
        print("玩家高兴地跳了起来!")
    end
end)
```

##### 使用自定义处理器
```lua
-- 重写回合开始调用的方法
SugarGame.Events.OnRoundStart.hander = funcation(){
    -- 这里的self就是SugarGame.Events.OnRoundStart对象
    for key, func in pairs(self.functions) do
        -- ...
    end
}

-- 重写玩家受到伤害后的事件处理
SugarGame.Events.OnPlayerAttack.hander = funcation(victim, attacker, damage, weapontype, hitbox){
    local results = {}
    for key, func in pairs(self.functions) do
        local result = func(victim, attacker, damage, weapontype, hitbox)
        if result ~= nil then
            table.insert( results, result)
        end
    end
    local sum = 0
    for key, value in pairs(results) do
        sum = sum + value        
    end
    return sum
}
```
或完全重写事件绑定函数，以实现自己所想要的功能,例
```lua
function Game.Rule:OnPlayerSpawn (player)
    print("玩家已复活")
end
```