本文档基于ai生成
[MD][/CENTER]
# 注意事项：
- 该插件需要BetterSidebar.js插件支持才能在侧边栏显示在线时长数据。
- 该插件支持通过命令查询在线时长，也支持通过侧边栏显示。
- 该插件获取渠道：
渠道：
- Minebbs下载
- 官方QQ群：519653012
- 作者QQ：3529832433
### 版本更新历史
#### 版本 1.0.1
- **新增功能**: 新增`mtime list`命令，可查询所有在线玩家的在线时长
- **优化改进**: 优化查询逻辑，提高查询效率
- **新增功能**: 支持将在线时长数据显示在BetterSidebar侧边栏
- **数据扩展**: 提供更详细的在线时长数据（天、小时、分钟）
- **兼容性**: 与BetterSidebar完美集成，支持自定义显示格式
# 存储文件说明
在线时长系统使用SQLite数据库存储玩家在线时长数据，数据库文件位于：
`./Meowdata/meowtime/playertime.db`
数据库结构：
```sql
CREATE TABLE IF NOT EXISTS player_time (
xuid TEXT PRIMARY KEY,
name TEXT,
first_join_time INTEGER,
total_time INTEGER DEFAULT 0,
last_join_time INTEGER,
last_leave_time INTEGER
);
```
**字段说明：**
- `xuid`: 玩家唯一标识符（主键）
- `name`: 玩家名称
- `first_join_time`: 首次加入时间（毫秒时间戳）
- `total_time`: 总在线时长（毫秒）
- `last_join_time`: 上次加入时间（毫秒时间戳）
- `last_leave_time`: 上次离开时间（毫秒时间戳）
# 命令说明
## 1. 查询自己的在线时长
**命令**: `/mtime`
**权限**: 所有玩家可使用
**功能**: 查询当前玩家的总在线时长
**示例**:
```
/mtime
```
**返回示例**:
```
[在线时长] 伊希娅的在线时长为：1天2小时30分钟
```
## 2. 查询指定玩家的在线时长
**命令**: `/mtime query <玩家名>`
**权限**: 所有玩家可使用
**功能**: 查询指定玩家的总在线时长
**参数说明**:
- `<玩家名>`: 要查询的玩家名称
**示例**:
```
/mtime query Steve
```
**返回示例**:
```
[在线时长] Steve的在线时长为：3天12小时45分钟
```
## 3. 查询在线玩家的在线时长列表
**命令**: `/mtime list`
**权限**: 所有玩家可使用
**功能**: 查询所有在线玩家的在线时长，并按时长从长到短排序
**示例**:
```
/mtime list
```
**返回示例**:
```
[在线时长] 在线玩家列表：
1. 伊希娅: 1天2小时30分钟
2. Steve: 3小时45分钟
3. Alex: 1小时20分钟
```
# BetterSidebar 集成说明
## 1. 变量说明
在线时长系统向BetterSidebar注册了以下变量：
### a. 格式化的在线时长
**变量**: `{E.playtime}`
**功能**: 显示玩家的总在线时长（格式化字符串）
**示例**: `1天2小时30分钟`
### b. 在线时长（天）
**变量**: `{E.playtime.days}`
**功能**: 显示玩家在线时长的天数部分
**示例**: `1`
### c. 在线时长（小时）
**变量**: `{E.playtime.hours}`
**功能**: 显示玩家在线时长的小时部分（不包含天数）
**示例**: `2`
### d. 在线时长（分钟）
**变量**: `{E.playtime.minutes}`
**功能**: 显示玩家在线时长的分钟部分（不包含天和小时）
**示例**: `30`
### e. 首次加入时间
**变量**: `{E.playtime.first_join}`
**功能**: 显示玩家首次加入服务器的时间
**示例**: `2023-05-20 14:30:25`
## 2. 配置示例
在BetterSidebar的配置文件中，可以这样使用在线时长变量：
```json
{
"data": [
"§e#§d#§b#§g#个§e人§d信§b息§e#§d#§b#§g#",
"§e你好,§g{pl.realName}",
"§gY币:§5{pl.getScore(money)}",
"§g在线时长: §5{E.playtime}",
"§g首次加入: §5{E.playtime.first_join}",
"§e#§d#§b#§g#其§e它§d信§b息§e#§d#§b#§g#"
]
}
```
## 3. 高级用法
### a. 条件显示
可以使用JavaScript条件判断来根据在线时长显示不同的文本：
```json
{
"data": [
"§g在线时长: §5{E.playtime}",
"§g经验等级: §5{js:(E.playtime.days >= 30 ? '骨灰玩家' : (E.playtime.days >= 7 ? '老玩家' : '新玩家'))}"
]
}
```
### b. 格式化显示
可以自定义在线时长的显示格式：
```json
{
"data": [
"§g在线时长: §5{js:E.playtime.days+'天'+E.playtime.hours+'小时'}",
"§g游戏时间: §5{js:(E.playtime.days*24 + E.playtime.hours)+'小时'}"
]
}
```
# API接口说明
### a. 获取玩家总在线时长（毫秒）
`getPlayerTotalTime(xuid)`
**参数**：
- `xuid`: 玩家XUID（字符串）
**返回值**：总在线时长（数字，单位：毫秒）
**示例**：
```javascript
const totalTime = $Y.i.meowtime.getPlayerTotalTime("2535492042022010");
console.log(`玩家总在线时长：${totalTime}毫秒`);
```
### b. 获取格式化的在线时长
`getFormattedTime(xuid)`
**参数**：
- `xuid`: 玩家XUID（字符串）
**返回值**：包含天、小时、分钟的时间对象
**示例**：
```javascript
const formattedTime = $Y.i.meowtime.getFormattedTime("2535492042022010");
console.log(`在线时长：${formattedTime.days}天${formattedTime.hours}小时${formattedTime.minutes}分钟`);
```
### c. 获取在线时长字符串
`getTimeString(xuid)`
**参数**：
- `xuid`: 玩家XUID（字符串）
**返回值**：格式化的在线时长字符串（如："1天2小时30分钟"）
**示例**：
```javascript
const timeString = $Y.i.meowtime.getTimeString("2535492042022010");
console.log(`在线时长：${timeString}`);
```
### d. 查询玩家在线时长信息
`queryPlayerTime(playerIdentifier)`
**参数**：
- `playerIdentifier`: 玩家XUID或玩家名（字符串）
**返回值**：包含玩家在线时长详细信息的对象
**示例**：
```javascript
const playerInfo = $Y.i.meowtime.queryPlayerTime("伊希娅");
if (playerInfo) {
console.log(`玩家名称：${playerInfo.name}`);
console.log(`在线时长：${playerInfo.timeString}`);
console.log(`首次加入：${playerInfo.firstJoin.toLocaleString()}`);
}
```
## 3. API返回值结构
### queryPlayerTime 返回值结构
```javascript
{
xuid: "2535492042022010", // 玩家XUID
name: "伊希娅", // 玩家名称
firstJoin: Date(2023-05-20), // 首次加入时间（Date对象）
totalTime: 100000000, // 总在线时长（毫秒）
formatted: { // 格式化的时间对象
days: 1, // 天数
hours: 2, // 小时数
minutes: 30, // 分钟数
total: 100000000 // 总毫秒数
},
timeString: "1天2小时30分钟" // 格式化的时间字符串
}
```
# 插件示例
## 1. 基础用法
```javascript
// 获取玩家对象
const player = ...;
// 查询玩家在线时长
const playerInfo = $Y.i.meowtime.queryPlayerTime(player.xuid);
if (playerInfo) {
// 发送在线时长信息给玩家
player.tell(`§a[在线时长] §e${playerInfo.name}§a的在线时长为：§e${playerInfo.timeString}`);
}
```
## 2. 显示在线时长排行榜
```javascript
// 获取所有在线玩家
const onlinePlayers = mc.getOnlinePlayers();
// 构建在线时长排行榜
const rankList = onlinePlayers.map(player => {
return {
player: player,
timeInfo: $Y.i.meowtime.queryPlayerTime(player.xuid)
};
}).filter(item => item.timeInfo)
.sort((a, b) => b.timeInfo.totalTime - a.timeInfo.totalTime);
// 发送排行榜给玩家
const targetPlayer = ...;
targetPlayer.tell("§a[在线时长] §e在线玩家时长排行榜：");
rankList.forEach((item, index) => {
targetPlayer.tell(`§a${index + 1}. §e${item.player.name}§a: §e${item.timeInfo.timeString}`);
});
```
## 3. 根据在线时长奖励玩家
```javascript
// 玩家加入时检查在线时长
mc.listen("onJoin", (player) => {
const timeInfo = $Y.i.meowtime.queryPlayerTime(player.xuid);
if (timeInfo) {
// 在线时长超过30天的玩家给予特殊奖励
if (timeInfo.formatted.days >= 30) {
player.tell("§a[在线时长奖励] §e恭喜你成为骨灰玩家，获得特殊称号！");
// 给予奖励...
}
// 在线时长超过7天的玩家给予奖励
else if (timeInfo.formatted.days >= 7) {
player.tell("§a[在线时长奖励] §e恭喜你成为老玩家，获得奖励！");
// 给予奖励...
}
}
});
```
# 性能与优化
## 1. 数据存储优化
- 使用SQLite数据库进行数据持久化
- 只在玩家离开时更新总在线时长，减少数据库操作
- 玩家加入时只更新基本信息，避免频繁写入
## 2. 查询优化
- 使用XUID作为主键，提高查询效率
- 对玩家名查询添加索引，优化玩家名查询
- 缓存常用查询结果，减少数据库访问
## 3. 资源占用
- 内存占用：约1-2MB
- CPU占用：低（仅在玩家加入/离开时处理数据）
- 磁盘占用：根据玩家数量而定，约1KB/玩家
# 故障排除
## 1. 常见问题
### a. 侧边栏不显示在线时长
**可能原因**：
- BetterSidebar未正确安装
- 变量名拼写错误
- 玩家数据不存在
**解决方案**：
- 确保BetterSidebar已正确安装并启用
- 检查变量名是否为`{E.playtime}`
- 确认玩家已加入过服务器并生成了数据
### b. 命令查询无结果
**可能原因**：
- 玩家名输入错误
- 玩家数据不存在
- 数据库文件损坏
**解决方案**：
- 检查玩家名拼写是否正确
- 确认玩家已加入过服务器
- 尝试重新启动服务器或修复数据库
### c. 在线时长数据不准确
**可能原因**：
- 服务器异常关闭导致数据未保存
- 插件加载顺序问题
**解决方案**：
- 确保服务器正常关闭
- 检查插件加载顺序，确保meowtime在BetterSidebar之前加载
## 2. 日志与调试
插件会在控制台输出以下日志信息：
- 插件加载完成日志
- BetterSidebar集成状态日志
- 数据库操作异常日志
通过查看日志可以帮助定位问题。
# 更新与维护
## 1. 更新方式
- 下载最新版本的插件文件
- 替换原有插件文件
- 重新启动服务器
## 2. 数据备份
建议定期备份数据库文件：
`./Meowdata/meowtime/playertime.db`
## 3. 联系作者
如果您在使用过程中遇到问题或有功能建议，可以通过以下方式联系作者：
- QQ：3529832433
- 官方QQ群：519653012
# 数据迁移工具
## 工具介绍
数据迁移工具（migrateTimeData.js）是为了帮助服务器管理员将旧版本的在线时长数据（存储在TimeData.json文件中）迁移到新版本的SQLite数据库中而开发的插件。该工具支持数据合并和覆盖两种迁移策略，确保数据迁移的安全性和灵活性。
## 工具功能
- **数据读取**：从旧版TimeData.json文件中读取玩家在线时长数据
- **格式转换**：将旧数据格式转换为新版SQLite数据库支持的格式
- **数据映射**：支持UUID到XUID的自动转换，确保数据的准确性
- **数据合并**：可选择合并新旧数据（累加在线时长，保留最早的首次登录时间）
- **数据覆盖**：可选择用旧数据完全覆盖新数据
- **数据备份**：迁移前自动备份主数据库，确保数据安全
- **日志记录**：详细记录迁移过程和结果
- **状态保存**：保存迁移状态，便于后续查询
## 工具路径
- 迁移工具文件：`./plugins/migrateTimeData.js`
- 旧数据文件：`./plugins/TimeData.json`
- 迁移日志：`./Meowdata/meowtime/olddata/migration_log.txt`
- 迁移状态：`./Meowdata/meowtime/olddata/migration_status.json`
## 使用方法
### 命令格式
```
/migratetime [action] [target] [merge]
```
### 参数说明
- **action**：执行的操作
- `start`：开始数据迁移
- `export`：将迁移后的数据导出为JSON格式
- `test`：测试数据迁移（不实际写入数据库）
- 不指定：显示帮助信息
- **target**：迁移目标（可选，默认为main）
- `main`：迁移到主数据库
- `backup`：迁移到备份数据库
- **merge**：合并策略（可选，默认为true）
- `true`：合并新旧数据
- `false`：用旧数据覆盖新数据
### 命令示例
#### 1. 显示帮助信息
```
/migratetime
```
返回：
```
[时间迁移工具] 使用方法：
/migratetime start [target] [merge] - 开始数据迁移
target: main(默认)或backup - 迁移目标数据库
merge: true(默认)或false - 是否合并数据
/migratetime export - 将迁移后的数据导出为JSON格式
/migratetime test - 测试数据迁移（不实际写入）
```
#### 2. 测试数据迁移
```
/migratetime test
```
该命令将测试数据迁移过程，但不会实际写入数据库，适合在正式迁移前检查数据转换是否正确。
#### 3. 使用合并策略迁移到主数据库
```
/migratetime start main true
```
该命令将：
- 备份主数据库
- 从旧数据文件读取数据
- 转换数据格式
- 将数据合并到主数据库（保留最早的首次登录时间，累加在线时长）
#### 4. 使用覆盖策略迁移到主数据库
```
/migratetime start main false
```
该命令将：
- 备份主数据库
- 从旧数据文件读取数据
- 转换数据格式
- 用旧数据完全覆盖主数据库中的数据
#### 5. 将迁移后的数据导出为JSON格式
```
/migratetime export
```
该命令将迁移后的数据导出为JSON格式，便于数据备份和分析。
## 迁移策略详解
### 合并策略（merge=true）
- **首次登录时间**：保留最早的首次登录时间（旧数据和新数据中的较小值）
- **总在线时长**：累加旧数据和新数据中的在线时长
- **最后登录时间**：保留最新的最后登录时间（旧数据和新数据中的较大值）
- **最后离开时间**：保留最新的最后离开时间（旧数据和新数据中的较大值）
### 覆盖策略（merge=false）
- **首次登录时间**：使用旧数据中的首次登录时间
- **总在线时长**：使用旧数据中的在线时长（覆盖新数据）
- **最后登录时间**：使用旧数据中的最后登录时间
- **最后离开时间**：使用旧数据中的最后登录时间（旧数据中没有最后离开时间字段）
## 数据映射
迁移工具会自动进行以下数据映射：
1. **UUID到XUID的转换**：
- 旧数据中的UUID会自动转换为对应的XUID
- 确保数据在新版本中使用统一的XUID作为标识
2. **玩家名称获取**：
- 优先使用玩家的realName字段作为玩家名称
- 若realName不存在，则使用name字段
- 若都不存在，则显示为"未知玩家"
## 注意事项
1. **数据备份**：
- 迁移前会自动备份主数据库到`./Meowdata/meowtime/olddata/playertime_backup.db`
- 建议手动备份TimeData.json文件，确保数据安全
2. **迁移前准备**：
- 确保服务器处于稳定状态
- 确保TimeData.json文件存在且格式正确
- 确保主数据库文件存在且可写
3. **迁移后检查**：
- 查看迁移日志确认迁移结果
- 检查在线时长数据是否正确显示
- 测试命令查询功能是否正常
4. **多次迁移**：
- 可以多次执行迁移命令
- 每次迁移都会自动备份主数据库
- 使用合并策略可以累加多次迁移的数据
## API接口
迁移工具提供了以下API接口供其他插件调用：
```javascript
// 执行数据迁移
const success = $Y.i.migratetime.executeMigration();
// 导出数据为JSON格式
const jsonPath = $Y.i.migratetime.exportDataToJson();
```
## 版本信息
- 工具名称：migrateTimeData
- 版本：1.0.0
- 作者：伊希娅
- 适用版本：在线时长系统 1.0.2+
---
在线时长系统是一款功能强大、易于使用的插件，支持多种查询方式和显示形式，可以满足服务器对玩家在线时长管理的需求。通过与BetterSidebar的集成，玩家可以方便地查看自己的在线时长数据，增强了玩家的游戏体验。
[/MD]
