@gongxh/bit-core 0.0.3 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bit老宫
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,75 +1,194 @@
 # bit-core
-bit-framework库的核心部分
 
-#### 版本支持
-- creator 3.7之前的版本理论上也支持，未测试
-- creator 3.7+ 支持
-- creator 3.8+ 支持
+Bit Framework 的核心库，为 Cocos Creator 3.x 游戏开发提供基础功能支持。
 
->  此项目是框架源码，不是creator项目
->
-> demo见最下方仓库地址
+## 简介
 
-## 安装bit-core
+`bit-core` 是 Bit Framework 的核心库，包含平台检测、时间工具、定时器系统、数据结构、日志工具等核心功能，是整个框架的基石。所有其他模块都依赖于 `bit-core`。
 
-项目已发布到 `npm`, 安装方法如下：
+**核心特性**：
+- ⏰ 完整的时间处理系统（网络时间同步、格式化、时长计算）
+- ⏲️ 高性能全局定时器（延迟、循环、暂停/恢复）
+- 🖥️ 自动平台检测（Android、iOS、HarmonyOS、小游戏、浏览器）
+- 📐 屏幕适配信息（屏幕尺寸、安全区）
+- 🧩 模块系统基类
+- 🛠️ 实用工具集（版本比较、URL 处理、JSON 校验）
+- 📊 高效数据结构（二叉堆、链表、栈）
+- 📝 统一日志系统
+- 🔧 完整的 TypeScript 类型定义
 
-```bash
-npm install bit-core
-```
+**版本支持**：
+- Cocos Creator 3.7+ ✅
+- Cocos Creator 3.8+ ✅
 
-> 如果连不上npm, 可使用国内镜像 比如: 淘宝、腾讯、华为
+## 安装
 
 ```bash
-# 官方
-npm set registry https://registry.npmjs.org
-# 中国镜像站（用这个就行）
-npm set registry https://registry.npmmirror.com/
-#腾讯
-npm set registry https://mirrors.cloud.tencent.com/npm/
-# 华为
-npm set registry https://repo.huaweicloud.com/repository/npm/
-# 阿里
-npm set registry https://npm.aliyun.com
+npm install @gongxh/bit-core
 ```
 
-# 集成目录
-1. [使用教程 (新手必看)](./docs/Noviciate.md)
-2. [项目配置](./docs/Basic.md)
-3. [UI模块](./docs/UI.md)
-4. [全局计时器](./docs/Timer.md)
-5. [平台工具](./docs/Platform.md)
-6. [屏幕尺寸](./docs/Screen.md)
-7. [小工具](./docs/Tools.md)
-8. [时间](./docs/Time.md)
-9. [小游戏接口封装](./docs/MiniGame.md)
-10. [热更新](./docs/HotUpdate.md)
-11. [条件显示节点 (一般用于UI上的红点)](./docs/Condition.md)
-12. [数据模块](./docs/Data.md)
-
-# 独立模块目录
-1. [ec模块](https://github.com/Gongxh0901/kunpo-ec)
-2. [ecs模块](https://github.com/Gongxh0901/kunpo-esc)
-3. [网络模块 http和socket](https://github.com/Gongxh0901/bit-core-net)
-4. [四叉树](https://github.com/Gongxh0901/kunpo-quadtree)
-5. [行为树](https://github.com/Gongxh0901/bit-core-behaviortree)
-6. [资源管理](https://github.com/Gongxh0901/bit-core-assets)
-7. [全局事件](https://github.com/Gongxh0901/bit-core-event)
-## 类型支持
-
-该库完全使用 TypeScript 编写，提供完整的类型定义文件。
+## 使用说明
 
-## 许可证
+### 时间工具 (Time)
 
-ISC License
+完整的时间处理工具类，支持网络时间同步。
 
-## 作者
+**基础方法**：
+- `now()` - 获取当前时间戳（毫秒）
+- `setNetTime(netTime)` - 设置网络时间用于同步
+- `msTos(ms)` / `sToMs(s)` - 毫秒秒互转
+
+**时间字段**：
+- `getYear()` / `getMonth()` / `getDay()` - 获取年月日
+- `getHour()` / `getMinute()` / `getSecond()` - 获取时分秒
+- `getWeekDay()` - 获取星期几 (1-7)
+
+**时间范围**：
+- `getDayStartTime()` / `getDayEndTime()` - 当天起止时间
+- `getWeekStartTime()` / `getWeekEndTime()` - 本周起止时间
+- `getMonthStartTime()` / `getMonthEndTime()` - 本月起止时间
+- `getYearStartTime()` / `getYearEndTime()` - 本年起止时间
+- `getMonthDays()` - 获取当月天数
+
+**时间比较**：
+- `isSameDay()` / `isSameWeek()` / `isSameMonth()` / `isSameYear()` - 时间比较
+
+**时间格式化**：
+- `format(timestamp, pattern)` - 通用时间格式化
+  - 支持 YYYY/YY, MM/M, DD/D, hh/h, mm/m, ss/s 等占位符
+- `formatTime(timestamp)` - 格式化为 `YYYY-MM-DD hh:mm:ss`
+- `formatTimeChinese(timestamp)` - 格式化为中文
+- `formatDuration(seconds, pattern, options?)` - 时长格式化
+  - 支持 DD/D, HH/H, hh/h, MM/M, mm/m, ss/s 等占位符
+- `formatSmart(seconds)` - 智能时长格式化（自动隐藏为0的单位）
+- `formatSmartSimple(seconds)` - 简化智能时长格式化（只显示最大两个单位）
+
+### 全局定时器 (GlobalTimer)
+
+全局定时器系统，支持延迟执行和循环执行。
+
+**主要方法**：
+- `startTimer(callback, interval, loop?)` - 启动定时器
+  - `callback` - 回调函数
+  - `interval` - 时间间隔（秒）
+  - `loop` - 循环次数（0:一次, 1~n:n次, -1:无限）
+  - 返回定时器 ID
+- `stopTimer(timerId)` - 停止定时器
+- `pauseTimer(timerId)` - 暂停定时器
+- `resumeTimer(timerId)` - 恢复定时器
+- `clearAllTimer()` - 清除所有定时器
+
+### 平台检测 (Platform)
+
+自动识别运行平台，提供平台信息。
+
+**平台类型枚举 (PlatformType)**：
+- `Android` / `IOS` / `HarmonyOS` - 原生平台
+- `WX` / `Alipay` / `Bytedance` / `HuaweiQuick` - 小游戏平台
+- `Browser` - 浏览器
+
+**平台属性**：
+- `platform` - 当前平台类型
+- `isNative` / `isMobile` / `isNativeMobile` - 平台分类
+- `isAndroid` / `isIOS` / `isHarmonyOS` - 原生平台判断
+- `isWX` / `isAlipay` / `isBytedance` / `isHuaweiQuick` - 小游戏判断
+- `isBrowser` - 浏览器判断
+- `deviceId` - 设备 ID
+
+### 屏幕信息 (Screen)
+
+提供屏幕尺寸和安全区信息。
+
+**属性**：
+- `ScreenWidth` / `ScreenHeight` - 屏幕宽高
+- `DesignWidth` / `DesignHeight` - 设计分辨率宽高
+- `SafeAreaHeight` - 安全区外侧高度/宽度
+- `SafeWidth` / `SafeHeight` - 安全区宽高
+
+### 模块基类 (Module)
+
+组织游戏系统的抽象基类。
+
+**使用方式**：
+- 继承 `Module` 类
+- 实现 `onInit()` 方法
+- `moduleName` - 模块名称属性
 
-gongxh
+### 工具类 (Utils)
 
-## 联系作者
+实用工具函数集。
 
-*  邮箱: gong.xinhai@163.com
+**主要方法**：
+- `compareVersion(v1, v2)` - 版本号比较
+  - 返回值：>0 表示 v1>v2，=0 表示相等，<0 表示 v1<v2
+- `isJsonString(str)` - 判断是否为 JSON 字符串
+- `getUrlParam(url)` - 解析 URL 参数
+  - 返回 `{url: string, params: {...}}`
+- `addUrlParam(url, key, value)` - 给 URL 添加参数
+
+### 日志系统
+
+统一的日志输出接口。
+
+**日志函数**：
+- `enableDebugMode(enabled)` - 启用/禁用调试模式
+- `debug(...args)` - 调试日志
+- `log(...args)` - 普通日志
+- `info(...args)` - 信息日志
+- `warn(...args)` - 警告日志
+- `error(...args)` - 错误日志
+
+### 数据结构
+
+内置高效的数据结构。
+
+**BinaryHeap（二叉堆）**：
+- `new BinaryHeap<T>(compareFn)` - 创建堆
+- `push(value)` / `pop()` / `peek()` - 入堆/出堆/查看堆顶
+- `size()` / `clear()` - 获取大小/清空
+
+**LinkedList（链表）**：
+- `append(value)` / `prepend(value)` - 尾部/头部添加
+- `remove(value)` / `find(value)` - 移除/查找
+- `clear()` - 清空
+
+**DoublyLinkedList（双向链表）**：
+- 支持双向遍历的链表
+
+**Stack（栈）**：
+- `push(value)` / `pop()` / `peek()` - 入栈/出栈/查看栈顶
+- `size()` / `clear()` - 获取大小/清空
+
+详细 API 请查看 `bit-core.d.ts` 类型定义文件。
+
+## 相关模块
+
+`bit-core` 是框架的基础库，其他模块都依赖于它：
+
+- **bit-event** - 事件系统
+- **bit-ec** - Entity-Component 架构
+- **bit-ecs** - Entity-Component-System 架构
+- **bit-ui** - UI 系统
+- **bit-net** - 网络通信
+- **bit-assets** - 资源管理
+- **bit-quadtree** - 四叉树
+- **bit-behaviortree** - 行为树
+- **bit-condition** - 条件显示系统
+- **bit-minigame** - 小游戏适配
+- **bit-hotupdate** - 热更新
+
+更多信息请参考 [根目录 README](../README.md) 和 [架构文档](../ARCHITECTURE.md)。
+
+## 许可证
+
+MIT License
+
+## 作者
+
+**bit老宫** (gongxh)  
+**邮箱**: gong.xinhai@163.com
 
 ## 源码仓库
-[bit-core github地址](https://github.com/Gongxh0901/bit-framework)
+
+- [GitHub](https://github.com/Gongxh0901/bit-framework)
+- [npm](https://www.npmjs.com/package/@gongxh/bit-core)