工具模块为 Game Macro 系统提供必要的辅助函数、对象工具和 ID 生成服务。
| English Version | 中文版本 |
工具模块提供：
工具系统组织为专门的工具组件：
用于常见操作的主要工具函数。
对象操作和管理工具。
唯一标识符生成系统。
提供整个系统使用的通用工具函数。
提供对象操作和管理工具。
提供唯一标识符生成服务。
去除字符串两端的空白字符。
参数：
str（字符串）：输入字符串返回： 去除空白后的字符串
使用提供的参数格式化字符串。
参数：
format（字符串）：格式字符串args...（可变参数）：格式参数返回： 格式化后的字符串
按分隔符分割字符串。
参数：
str（字符串）：输入字符串delimiter（字符串）：分隔符字符返回： 分割后的字符串数组
生成 min 和 max 之间的随机数。
参数：
min（数字）：最小值max（数字）：最大值返回： 随机数
将值限制在 min 和 max 之间。
参数：
value（数字）：输入值min（数字）：最小值max（数字）：最大值返回： 限制后的值
将数字四舍五入到指定小数位。
参数：
value（数字）：输入值decimals（整数）：小数位数返回： 四舍五入后的数字
从文件名获取文件扩展名。
参数：
filename（字符串）：文件名返回： 文件扩展名
将路径部分连接成完整路径。
参数：
parts...（可变参数）：路径组件返回： 连接后的路径字符串
检查文件是否存在。
参数：
filepath（字符串）：文件路径返回： 布尔值指示文件存在性
获取当前时间戳（毫秒）。
参数：无
返回： 当前时间戳
休眠指定的毫秒数。
参数：
ms（整数）：休眠毫秒数返回： 无
获取系统信息。
参数：无
返回： 系统信息映射
检查值是否为空。
参数：
value（任意）：要检查的值返回： 布尔值指示是否为空
检查值是否为数字。
参数：
value（任意）：要检查的值返回： 布尔值指示是否为数字
检查值是否为字符串。
参数：
value（任意）：要检查的值返回： 布尔值指示是否为字符串
创建具有指定属性的新对象。
参数：
properties（映射）：对象属性返回： 新对象
创建对象的深拷贝。
参数：
obj（映射）：要克隆的对象返回： 克隆的对象
将源对象合并到目标对象中。
参数：
target（映射）：目标对象source（映射）：源对象返回： 合并后的对象
使用点符号从对象获取属性。
参数：
obj（映射）：源对象propertyPath（字符串）：属性路径返回： 属性值
使用点符号在对象中设置属性。
参数：
obj（映射）：目标对象propertyPath（字符串）：属性路径value（任意）：要设置的值返回： 修改后的对象
从对象中删除属性。
参数：
obj（映射）：目标对象propertyPath（字符串）：属性路径返回： 修改后的对象
检查对象是否具有属性。
参数：
obj（映射）：要检查的对象propertyPath（字符串）：属性路径返回： 布尔值指示属性存在性
根据模式验证对象。
参数：
obj（映射）：要验证的对象schema（映射）：验证模式返回： 布尔值指示验证成功
将对象序列化为字符串。
参数：
obj（映射）：要序列化的对象返回： 序列化后的字符串
将字符串反序列化为对象。
参数：
str（字符串）：序列化后的字符串返回： 反序列化后的对象
生成下一个顺序 ID。
参数：无
返回： 顺序 ID
重置顺序 ID 计数器。
参数：无
返回： 布尔值指示成功
生成 UUID。
参数：无
返回： UUID 字符串
验证 UUID 字符串。
参数：
uuid（字符串）：要验证的 UUID返回： 布尔值指示 UUID 有效性
生成基于时间戳的 ID。
参数：无
返回： 时间戳 ID
解析时间戳 ID 以提取时间戳。
参数：
timestampId（字符串）：时间戳 ID返回： 解析后的时间戳
生成自定义格式 ID。
参数：
prefix（字符串）：ID 前缀suffix（字符串）：ID 后缀返回： 自定义 ID
设置自定义 ID 生成格式。
参数：
format（字符串）：自定义格式字符串返回： 布尔值指示成功
; 字符串操作
trimmed := Utils_Trim(" hello world ") ; "hello world"
formatted := Utils_FormatString("Hello {1}, you have {2} messages", "User", 5)
parts := Utils_SplitString("a,b,c,d", ",") ; ["a", "b", "c", "d"]
; 数学函数
random := Utils_Random(1, 100)
clamped := Utils_Clamp(150, 0, 100) ; 100
rounded := Utils_Round(3.14159, 2) ; 3.14
; 文件操作
extension := Utils_GetFileExtension("document.txt") ; ".txt"
fullPath := Utils_JoinPath("C:", "Users", "Documents", "file.txt")
exists := Utils_FileExists("C:\file.txt")
; 系统工具
timestamp := Utils_GetTimestamp()
Utils_Sleep(1000) ; 休眠 1 秒
systemInfo := Utils_GetSystemInfo()
; 验证函数
isEmpty := Utils_IsEmpty("") ; true
isNumber := Utils_IsNumber("123") ; true
isString := Utils_IsString("hello") ; true
; 对象创建
person := Obj_Create({"name": "John", "age": 30})
clone := Obj_Clone(person)
merged := Obj_Merge({"a": 1}, {"b": 2}) ; {"a": 1, "b": 2}
; 对象操作
name := Obj_GetProperty(person, "name") ; "John"
Obj_SetProperty(person, "address.city", "New York")
Obj_DeleteProperty(person, "age")
; 对象验证
hasName := Obj_HasProperty(person, "name") ; true
isValid := Obj_ValidateStructure(person, {"name": "string", "age": "number"})
; 对象序列化
serialized := Obj_Serialize(person)
deserialized := Obj_Deserialize(serialized)
; 顺序 ID
id1 := IdGen_NextSequential() ; 1
id2 := IdGen_NextSequential() ; 2
IdGen_ResetSequential()
; UUID 生成
uuid := IdGen_GenerateUUID()
isValid := IdGen_ValidateUUID(uuid)
; 时间戳 ID
timestampId := IdGen_GenerateTimestampId()
parsedTime := IdGen_ParseTimestampId(timestampId)
; 自定义 ID
customId := IdGen_GenerateCustomId("USER", "ID")
IdGen_SetCustomFormat("{prefix}-{timestamp}-{sequential}")
; 配置管理中的工具函数
profilePath := Utils_JoinPath(App["ProfilesDir"], Utils_FormatString("{1}.json", profileName))
; 规则引擎中的对象工具
rule := Obj_Create({
"condition": {
"type": "pixel",
"x": 100,
"y": 200,
"color": "0xFF0000"
},
"action": {
"type": "skill",
"skillId": 1
}
})
; 实体的 ID 生成
skillId := IdGen_NextSequential()
buffId := IdGen_GenerateUUID()
工具设置可以在主配置中配置：
App["UtilityConfig"] := {
StringFormat: "{1}",
DefaultRandomSeed: 12345,
IDGeneration: {
SequentialStart: 1,
UUIDFormat: "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
TimestampFormat: "yyyyMMddHHmmss"
}
}
工具模块包含全面的错误处理：
模块提供调试功能：
; 启用工具调试
Utils_EnableDebug()
; 获取调试信息
debugInfo := Utils_GetDebugInfo()
工具操作可以记录用于故障排除：