** ? UltimateStaffManagement - 完整文档
? 插件概览
什么是 UltimateStaffManagement?
UltimateStaffManagement 是一款企业级员工工时追踪插件,专为运行在 1.21 至 1.21.11 版本的 Minecraft Paper 服务器设计。它为服务器管理员提供了强大的工具,以精确、轻松地对员工活动进行监控、分析和管控。
与基本的计时解决方案不同,UltimateStaffManagement 智能区分活跃工作时间和闲置/AFK 时间,为您提供关于实际员工生产力的准确见解,而不仅仅是登录时长。
? 主要功能(完整列表)
1️⃣ 智能会话管理
自动会话追踪
- 自动打卡: 拥有
usm.track 权限的玩家加入服务器时,会话自动开始
- 自动签退: 玩家断开连接或服务器关闭时,会话优雅结束
- 手动覆盖: 员工可使用命令手动打卡/签退,以便灵活调度
- 会话持久化: 所有活跃会话在服务器意外崩溃时立即保存
- 多会话支持: 跟踪每个玩家的无限历史会话
捕获的会话数据
对于每次会话:
├── 唯一会话 ID
├── 玩家 UUID 和名称
├── 开始时间戳(毫秒精度)
├── 结束时间戳(毫秒精度)
├── 总活跃时间(毫秒)
├── 总闲置时间(毫秒)
├── 会话备注(带时间戳的条目)
└── 活跃度百分比计算
2️⃣ 高级 AFK/活动检测
基于移动的检测
该插件使用复杂的多因素检测系统:
追踪参数:
- X, Y, Z 坐标 - 检测物理移动(0.1 格精度)
- 偏航角(头部水平旋转) - 追踪左右头部移动(1° 精度)
- 俯仰角(头部垂直旋转) - 追踪上下头部移动(1° 精度)
- 世界变化 - 即时检测传送/维度变化
检测算法:
检测到移动 IF:
├── X/Y/Z 变化 > 0.1 格 OR
├── 偏航角变化 > 1.0 度 OR
├── 俯仰角变化 > 1.0 度 OR
└── 检测到世界变化
状态更新:
├── 活跃 (ACTIVE):超时期内检测到任何移动
└── 闲置 (IDLE):配置时长内无移动(默认:600 秒)
计时机制
- 刻率: 每 20 刻(1 秒)检查一次,以获得最佳性能
- 时间累积: 每秒将 1000 毫秒添加到活跃或闲置计数器
- 实时更新: 状态更改立即反映在 GUI 中
- 可配置阈值: 完全自定义灵敏度设置
3️⃣ 企业级数据库管理
SQLite 支持(默认)
优势:
- ✅ 零配置: 安装后立即生效
- ✅ 便携性: 单个数据库文件,易于备份
- ✅ 无依赖项: 无需外部数据库服务器
- ✅ WAL 模式: 预写式日志以确保数据完整性
- ✅ 自动备份: 每日备份轮换(可配置)
MySQL 支持(可选)
**完美适用于:**
- 多服务器网络(BungeeCord/Velocity)
- 集中式数据管理
- 高级查询和报告
- 大型玩家基数(500+ 并发)
**配置示例:**
```yaml
storage-type: mysql
mysql:
host: db.yournetwork.com
port: 3306
database: staff_tracking
username: minecraft
password: securePassword123
pool:
maximum-pool-size: 10 最大并发连接数
minimum-idle: 2 保持的空闲连接数
connection-timeout: 30000 30 秒
idle-timeout: 600000 10 分钟
max-lifetime: 1800000 30 分钟
use-ssl: true 加密连接
HikariCP 连接池
性能优势:
- ⚡ 亚毫秒级连接获取
- ? 自动连接回收
- ?️ 连接泄漏检测
- ? 实时池统计信息
- ? 可配置的池大小
异步架构:
玩家操作
↓
主线程(无阻塞)
↓
异步任务队列
↓
HikariCP 线程池
↓
数据库操作
↓
回调至主线程
↓
结果显示
5️⃣ 全面的命令系统
玩家命令(详细)
/stafftime(主仪表板)
权限: usm.use
别名: /st, /clock, /staffclock
用法: /stafftime
描述:
打开主交互式仪表板 GUI,显示:
- 当前会话统计信息
- 实时活动状态
- 快速访问历史记录和备注
行为:
├── 如果有活跃会话:显示实时统计数据
├── 如果没有会话:显示“未打卡”及说明
└── 权限检查:需要 usm.use
音效: BLOCK_CHEST_OPEN(音量 0.5)
输出示例: [打开 9 槽位 GUI]
/stafftime clockin(手动开始会话)
权限: usm.use
别名: /st clockin, /clock in
用法: /stafftime clockin
描述:
为玩家手动启动新的时间追踪会话。
适用于未启用自动追踪的员工。
验证检查:
├── 已有会话?→ 错误消息
├── 权限检查: usm.use
└── 仅限玩家命令
成功消息:
"═══════════════════════════════"
" ✓ 打卡成功"
"═══════════════════════════════"
"您的工作会话已开始。"
"会话将持续追踪,直到您签退或断开连接。"
""
"查看您的统计数据: /stafftime"
音效: BLOCK_NOTE_BLOCK_PLING(音量 1.0,音调 2.0)
数据库操作: 创建新会话记录(异步)
/stafftime clockout(手动结束会话)
权限: usm.use
别名: /st clockout, /clock out
用法: /stafftime clockout
描述:
手动结束当前活跃会话并显示
工作期间的详细摘要。
验证检查:
├── 没有活跃会话?→ 错误消息
├── 权限检查: usm.use
└── 仅限玩家命令
成功输出:
"═══════════════════════════════"
" ✓ 打卡成功"
"═══════════════════════════════"
""
"会话摘要:"
""
" ⚡ 活跃时间:2小时15分30秒"
" ⏸ 空闲时间:18分42秒"
" ⏱ 总时长:2小时34分12秒"
" ? 活跃度:87.5%"
""
"您的会话已保存至数据库。"
音效:ENTITY_EXPERIENCE_ORB_PICKUP
数据库操作:
├── 将会话保存至 usm_sessions 表
├── 更新 usm_users 表中的用户总计
└── 从活跃会话缓存中移除
/stafftime addnote <message> (会话备注)
权限:usm.use
别名:/st addnote, /clock note
用法:/stafftime addnote <message>
示例:/stafftime addnote Handled 5 player reports
描述:
为当前活跃的会话添加带时间戳的备注。
备注将随会话一起保存,并可在历史记录中查看。
验证检查:
├── 无活跃会话?→ 错误消息
├── 消息为空?→ 显示用法
├── 消息超过 200 字符?→ 错误消息
├── 单个会话备注超过 50 条?→ 错误消息
└── 权限检查:usm.use
备注格式:
存储格式:"[14:35:22] Handled 5 player reports"
时间戳格式:HH:mm:ss(可配置)
成功消息:
"═══════════════════════════════"
" ? 备注已添加"
"═══════════════════════════════"
""
"备注:Handled 5 player reports"
""
"此备注将随您的会话一起保存。"
音效:ENTITY_ITEM_PICKUP (音量 0.5,音调 1.5)
使用场景:
├── 记录处理过的玩家举报
├── 记录审查的封禁申诉
├── 记录协助的服务端事件
├── 记录做出的重要决定
└── 追踪已解决的工单
管理员命令(详细)
/stafftime top [days] (排行榜)
权限:usm.admin
别名:/st top, /clock leaderboard
用法:
/stafftime top (默认 7 天)
/stafftime top 30 (最近 30 天)
/stafftime top 1 (最近 24 小时)
描述:
按指定时间段内的活跃时间(排除空闲时间)显示工作人员的排名排行榜。
参数:
├── days:整数(1-365)
├── 默认值:7 天
└── 显示前 10 名结果
输出格式:
"═══════════════════════════════════════"
" ? 最佳工作人员 - 过去 7 天"
"═══════════════════════════════════════"
""
"? 1 PlayerOne - 45h 30m 15s"
"? 2 PlayerTwo - 38h 15m 42s"
"? 3 PlayerThree - 32h 45m 10s"
" 4 PlayerFour - 28h 20m 30s"
" 5 PlayerFive - 25h 55m 18s"
" 6 PlayerSix - 22h 10m 45s"
" 7 PlayerSeven - 20h 30m 22s"
" 8 PlayerEight - 18h 45m 50s"
" 9 PlayerNine - 15h 20m 12s"
" 10 PlayerTen - 12h 35m 40s"
""
"═══════════════════════════════════════"
"显示前 10 名工作人员"
奖牌图标:
├── ? 第一名(金牌)
├── ? 第二名(银牌)
└── ? 第三名(铜牌)
数据库查询:
SELECT u.name, SUM(s.active_millis) as total
FROM usm_sessions s
JOIN usm_users u ON s.uuid = u.uuid
WHERE s.start_timestamp >= [cutoff]
GROUP BY s.uuid
ORDER BY total DESC
LIMIT 10
处理:异步(显示加载消息)
/stafftime list (实时工作人员监控)
权限:usm.admin
别名:/st list, /clock active
用法:/stafftime list
描述:
对玩家:打开包含玩家头像的交互式 GUI
对控制台:显示格式化的聊天列表
GUI 功能:
├── 带有皮肤的玩家头像
├── 实时状态指示器
├── 会话时长显示
├── 活动百分比(颜色编码)
├── 备注计数
└── 手动刷新按钮
控制台输出:
"═══════════════════════════════════════"
" ? 当前活跃的工作人员"
"═══════════════════════════════════════"
""
"1. PlayerOne - 2h 34m (活跃度:92.3%)"
" 活跃:2h 15m | 空闲:18m"
""
"2. PlayerTwo - 1h 45m (活跃度:78.5%)"
" 活跃:1h 22m | 空闲:22m"
""
"═══════════════════════════════════════"
"总计:2 名工作人员在线"
使用场景:
├── 监控当前工作人员可用性
├── 检查谁正在积极工作
├── 识别空闲的工作人员
├── 规划班次覆盖
└── 绩效监督
/stafftime adjust <player> <add|remove> <amount> <active|idle> (时间调整)
权限:usm.admin(需要 usm.adjust)
别名:/st adjust, /clock modify
用法:
/stafftime adjust <player> <add|remove> <amount> <active|idle>
示例:
/stafftime adjust Steve add 3600000 active
→ 给 Steve 增加 1 小时的活跃时间
/stafftime adjust Alex remove 1800000 idle
→ 从 Alex 的空闲时间中减去 30 分钟
/stafftime adjust Bob add 7200000 active
→ 给 Bob 增加 2 小时的活跃时间
参数:
├── player:玩家名称(在线或离线)
├── operation:“add” 或 “remove”
├── amount:毫秒数(1 小时 = 3600000)
└── type:“active” 或 “idle”
时间换算:
├── 1 分钟 = 60,000 毫秒
├── 5 分钟 = 300,000 毫秒
├── 10 分钟 = 600,000 毫秒
├── 30 分钟 = 1,800,000 毫秒
├── 1 小时 = 3,600,000 毫秒
├── 2 小时 = 7,200,000 毫秒
└── 24 小时 = 86,400,000 毫秒
验证:
├── 检查玩家是否存在
├── 检查数量 > 0
├── 检查操作是否有效
├── 检查类型是否有效
└── 权限验证
确认显示:
"═══════════════════════════════════"
" 时间调整"
"═══════════════════════════════════"
""
"玩家:Steve"
"操作:ADD"
"数量:1h 0m 0s"
"类型:ACTIVE"
""
"⏳ 正在处理调整..."
"✓ 时间调整应用成功!"
日志记录:
记录到控制台:
"[ADJUST] AdminName added 1h 0m 0s active time for Steve"
使用场景:
├── 纠正跟踪错误
├── 补偿服务器停机时间
├── 奖励额外时间
├── 修复数据库问题
└── 手动修正
6️⃣ 权限系统(完整)
权限层级树
usm.* (OP)
│
├─ usm.use (TRUE) ─────────────────┐
│ ├─ usm.clockin │ PLAYER
│ ├─ usm.clockout │ PERMISSIONS
│ ├─ usm.addnote │
│ └─ usm.history │
│ │
├─ usm.track (FALSE) ──────────────┤ STAFF
│ └─ [启用自动追踪] │ PERMISSION
│ │
└─ usm.admin.* (OP) ───────────────┘
├─ usm.admin
├─ usm.top
├─ usm.list
└─ usm.adjust
权限说明
**usm.***(家长许可)
```yaml
Description: 授予所有插件权限
Default: 仅限 OP
Children:
- usm.use
- usm.track
- usm.admin
- usm.adjust
Grant Command (LuckPerms):
/lp user <name> permission set usm.*
Use Case: 服务器所有者和高级管理员
usm.use(基本访问权限)
Description: 可访问仪表盘和基本命令
Default: True(所有玩家)
Allows:
- /stafftime(仪表盘)
- /stafftime clockin
- /stafftime clockout
- /stafftime addnote
Does NOT Allow:
- Auto-tracking on join
- Admin commands
授予命令:
/lp group default permission set usm.use true
用例:所有玩家(用于个人时间追踪)
usm.track(自动追踪)
Description: 启用自动会话追踪
Default: False (必须授予)
Behavior:
- 加入时自动签到
- 退出时自动签退
- 同时需要 usm.use 权限
Grant Command:
/lp user <name> permission set usm.track true
Use Case: 仅授予真正的员工成员
Example Setup:
1. 创建员工组:/lp creategroup staff
2. 授予追踪权限:/lp group staff permission set usm.track true
3. 添加用户:/lp user PlayerName parent add staff
usm.admin(管理员命令)
Description: 访问管理功能
Default: 仅限 OP
Allows:
- /stafftime top
- /stafftime list
- 查看所有玩家数据
Does NOT Allow:
- 时间调整(需要 usm.adjust 权限)
Grant Command:
/lp user <name> permission set usm.admin true
Use Case: 服务器版主和管理员
usm.adjust(时间修改)
Description: 修改玩家时间记录的权限
Default: 仅限 OP
Allows:
- /stafftime adjust 命令
- 为任何玩家添加/移除时间
Security Warning:
仅授予高度信任的管理员!
Grant Command:
/lp user <name> permission set usm.adjust true
Use Case: 高级管理员仅用于修正
推荐权限配置
Setup 1: 小型服务器(10-50 名玩家)
Default Group (所有玩家):
- usm.use: true
工作人员组(版主):
- 继承:default
- usm.track: true
管理员组(管理员):
- 继承:staff
- usm.admin: true
- usm.adjust: true
命令:
/lp creategroup staff
/lp group staff parent add default
/lp group staff permission set usm.track true
/lp creategroup admin
/lp group admin parent add staff
/lp group admin permission set usm.admin true
/lp group admin permission set usm.adjust true
设置 2:大型网络(100+ 玩家)
Groups:
default:
- No USM permissions (not tracked)
helper:
- usm.use: true
- usm.track: true
moderator:
- Inherits: helper
- usm.admin: true
admin:
- Inherits: moderator
- usm.adjust: true
owner:
- usm.*: true
Commands:
/lp creategroup helper
/lp group helper permission set usm.use true
/lp group helper permission set usm.track true
/lp creategroup moderator
/lp group moderator parent add helper
/lp group moderator permission set usm.admin true
/lp creategroup admin
/lp group admin parent add moderator
/lp group admin permission set usm.adjust true
? 集成与 API
PlaceholderAPI 支持(计划 v1.1)
计划中的占位符:
%usm_session_duration% → "2h 34m 12s"
%usm_session_active% → "2h 15m 30s"
%usm_session_idle% → "18m 42s"
%usm_session_activity% → "87.5%"
%usm_session_status% → "Active" / "Idle"
%usm_total_active% → "145h 30m 15s"
%usm_total_idle% → "12h 45m 20s"
%usm_rank_position% → "3"
%usm_notes_count% → "5"
用法示例(记分板):
- &aSession: &f%usm_session_duration%
- &aStatus: &f%usm_session_status%
- &aActivity: &f%usm_session_activity%
1️⃣2️⃣ 支持与资源
官方资源
? 错误报告:
1️⃣3️⃣ 技术规格
插件信息:
Name: UltimateStaffManagement
Version: 1.0.0
Author: geturplugins
License: AllRightsReserved
Language: Java 21
Dependencies:
├── Paper API: 1.21-1.21.11 (Required)
├── HikariCP: 5.1.0 (Bundled)
├── SQLite JDBC: 3.45.1.0 (Bundled)
├── MySQL Connector: 8.3.0 (Optional)
└── Adventure API: 4.x (Provided by Paper)
File Size:
├── JAR Size: ~1.5 MB
├── With Dependencies: ~3.2 MB
└── Database (SQLite): Grows ~50KB per 1000 sessions
Performance:
├── RAM Usage: 30-50MB (100 active sessions)
├── CPU Impact: < 0.1% per 50 tracked players
├── TPS Impact: None (async operations)
└── Database Speed: < 10ms per query (SSD)
Compatibility:
✅ Paper 1.21 - 1.21.11
✅ Purpur 1.21+
⚠️ Spigot 1.21 (Limited Adventure API)
❌ Bukkit (Not supported)
❌ Folia (Not yet supported)
? 统计数据(示例服务器)
服务器概况:
- Type: Roleplay Server
- Players: 150 concurrent
- Staff: 25 tracked members
- Database: MySQL
- Uptime: 99.8%
结果:
Performance Metrics:
├── Average Session Length: 3h 15m
├── Total Sessions Tracked: 12,450
├── Database Size: 145 MB
├── Query Response Time: < 5ms
└── Zero TPS impact
员工洞察:
├── 最活跃员工:每周 45 小时
├── 平均活跃度:82.3%
├── 总记录时长:15,230 小时
└── 记录备注:3,847 条
资源使用情况:
├── 插件内存占用:42 MB
├── 数据库连接:8 个活跃连接
├── 线程池:4 个线程
└── CPU 使用率:0.08%
? 简介
**UltimateStaffManagement** 是适用于 Minecraft 服务器的最全面的员工追踪解决方案,提供:
✅ **精准追踪** - 毫秒级精度的时间记录,支持活跃/闲置状态区分
✅ **零性能影响** - 完全异步操作,采用 HikariCP 连接池
✅ **精美 GUI** - 实时更新的交互式仪表盘
✅ **企业级数据库** - 支持 SQLite 和 MySQL,并具备自动备份功能
✅ **强大分析** - 排行榜、绩效指标及详细报告
✅ **灵活配置** - 100+ 项配置选项,实现完全自定义
✅ **开发者友好** - 完整的 Java API 与详尽文档
✅ **生产就绪** - 经过实战检验的架构,配备完善的错误处理机制
**适用场景:**
- 需要记录员工工作时长角色扮演服务器
- 需要集中化管理时间的服务器网络
- 管理志愿者员工的社区服务器
- 雇佣付费员工的职业化服务器
- 任何希望获取详细活动分析数据的服务器
---
**? 员工管理的终极解决方案 ?**
** ? UltimateStaffManagement - Complete Documentation
? Plugin Overview
What is UltimateStaffManagement?
UltimateStaffManagement is an enterprise-grade staff time tracking plugin designed specifically for Minecraft Paper servers running versions 1.21 through 1.21.11. It provides server administrators with powerful tools to monitor, analyze, and manage staff member activity with precision and ease.
Unlike basic time-tracking solutions, UltimateStaffManagement intelligently differentiates between active work time and idle/AFK time, giving you accurate insights into actual staff productivity rather than just login duration.
? Key Features (Complete List)
1️⃣ Intelligent Session Management
Automatic Session Tracking
- Auto Clock-In: Sessions start automatically when players with
usm.track permission join the server
- Auto Clock-Out: Sessions end gracefully when players disconnect or when the server shuts down
- Manual Override: Staff can manually clock in/out using commands for flexible scheduling
- Session Persistence: All active sessions are immediately saved during unexpected server crashes
- Multi-Session Support: Tracks unlimited historical sessions per player
Session Data Captured
For Each Session:
├── Unique Session ID
├── Player UUID & Name
├── Start Timestamp (millisecond precision)
├── End Timestamp (millisecond precision)
├── Total Active Time (milliseconds)
├── Total Idle Time (milliseconds)
├── Session Notes (timestamped entries)
└── Activity Percentage Calculation
2️⃣ Advanced AFK/Activity Detection
Movement-Based Detection
The plugin uses a sophisticated multi-factor detection system:
Tracked Parameters:
- X, Y, Z Coordinates - Detects physical movement (0.1 block precision)
- Yaw (Head Rotation Horizontal) - Tracks left/right head movement (1° precision)
- Pitch (Head Rotation Vertical) - Tracks up/down head movement (1° precision)
- World Changes - Instant detection of teleportation/dimension changes
Detection Algorithm:
Movement Detected IF:
├── X/Y/Z change > 0.1 blocks OR
├── Yaw change > 1.0 degrees OR
├── Pitch change > 1.0 degrees OR
└── World change detected
Status Update:
├── ACTIVE: Any movement detected within timeout period
└── IDLE: No movement for configured duration (default: 600 seconds)
Time Tracking Mechanism
- Tick Rate: Checks every 20 ticks (1 second) for optimal performance
- Time Accumulation: Every second adds 1000ms to either active or idle counter
- Real-Time Updates: Status changes are reflected immediately in GUIs
- Configurable Thresholds: Fully customizable sensitivity settings
3️⃣ Enterprise Database Management
SQLite Support (Default)
Advantages:
- ✅ Zero Configuration: Works immediately after installation
- ✅ Portable: Single database file, easy to backup
- ✅ No Dependencies: No external database server required
- ✅ WAL Mode: Write-Ahead Logging for data integrity
- ✅ Automatic Backups: Daily backup rotation (configurable)
MySQL Support (Optional)
**Perfect For:**
- Multi-server networks (BungeeCord/Velocity)
- Centralized data management
- Advanced querying and reporting
- Large player bases (500+ concurrent)
**Configuration Example:**
```yaml
storage-type: mysql
mysql:
host: db.yournetwork.com
port: 3306
database: staff_tracking
username: minecraft
password: securePassword123
pool:
maximum-pool-size: 10 Max concurrent connections
minimum-idle: 2 Idle connections maintained
connection-timeout: 30000 30 seconds
idle-timeout: 600000 10 minutes
max-lifetime: 1800000 30 minutes
use-ssl: true Encrypted connections
HikariCP Connection Pooling
Performance Benefits:
- ⚡ Sub-millisecond connection acquisition
- ? Automatic connection recycling
- ?️ Connection leak detection
- ? Real-time pool statistics
- ? Configurable pool sizing
Async Architecture:
Player Action
↓
Main Thread (No Blocking)
↓
Async Task Queue
↓
HikariCP Thread Pool
↓
Database Operation
↓
Callback to Main Thread
↓
Result Displayed
5️⃣ Comprehensive Command System
Player Commands (Detailed)
/stafftime (Main Dashboard)
Permission: usm.use
Aliases: /st, /clock, /staffclock
Usage: /stafftime
Description:
Opens the main interactive dashboard GUI showing:
- Current session statistics
- Real-time activity status
- Quick access to history and notes
Behavior:
├── If Active Session: Shows live stats
├── If No Session: Displays "Not clocked in" with instructions
└── Permission Check: Requires usm.use
Sound Effect: BLOCK_CHEST_OPEN (0.5 volume)
Example Output: [Opens 9-slot GUI]
/stafftime clockin (Manual Session Start)
Permission: usm.use
Aliases: /st clockin, /clock in
Usage: /stafftime clockin
Description:
Manually starts a new time tracking session for the player.
Useful for staff who don't have auto-tracking enabled.
Validation Checks:
├── Already has session? → Error message
├── Permission check: usm.use
└── Player-only command
Success Message:
"═══════════════════════════════"
" ✓ Clock-In Successful"
"═══════════════════════════════"
"Your work session has started."
"Session will be tracked until you clock out or disconnect."
""
"View your stats: /stafftime"
Sound Effect: BLOCK_NOTE_BLOCK_PLING (1.0 volume, 2.0 pitch)
Database Action: Creates new session record (async)
/stafftime clockout (Manual Session End)
Permission: usm.use
Aliases: /st clockout, /clock out
Usage: /stafftime clockout
Description:
Manually ends the current active session and displays
a detailed summary of the work period.
Validation Checks:
├── No active session? → Error message
├── Permission check: usm.use
└── Player-only command
Success Output:
"═══════════════════════════════"
" ✓ Clock-Out Successful"
"═══════════════════════════════"
""
"Session Summary:"
""
" ⚡ Active Time: 2h 15m 30s"
" ⏸ Idle Time: 18m 42s"
" ⏱ Total Time: 2h 34m 12s"
" ? Activity: 87.5%"
""
"Your session has been saved to the database."
Sound Effect: ENTITY_EXPERIENCE_ORB_PICKUP
Database Actions:
├── Save session to usm_sessions table
├── Update user totals in usm_users table
└── Remove from active sessions cache
/stafftime addnote <message> (Session Annotation)
Permission: usm.use
Aliases: /st addnote, /clock note
Usage: /stafftime addnote <message>
Example: /stafftime addnote Handled 5 player reports
Description:
Adds a timestamped note to the current active session.
Notes are saved with the session and visible in history.
Validation Checks:
├── No active session? → Error message
├── Message empty? → Show usage
├── Message > 200 chars? → Error message
├── Notes > 50 per session? → Error message
└── Permission check: usm.use
Note Format:
Stored: "[14:35:22] Handled 5 player reports"
Timestamp: HH:mm:ss format (configurable)
Success Message:
"═══════════════════════════════"
" ? Note Added"
"═══════════════════════════════"
""
"Note: Handled 5 player reports"
""
"This note will be saved with your session."
Sound Effect: ENTITY_ITEM_PICKUP (0.5 volume, 1.5 pitch)
Use Cases:
├── Document player reports handled
├── Record ban appeals reviewed
├── Note server events assisted
├── Log important decisions made
└── Track tickets resolved
Admin Commands (Detailed)
/stafftime top [days] (Leaderboard)
Permission: usm.admin
Aliases: /st top, /clock leaderboard
Usage:
/stafftime top (defaults to 7 days)
/stafftime top 30 (last 30 days)
/stafftime top 1 (last 24 hours)
Description:
Displays a ranked leaderboard of staff members by
ACTIVE time (idle time excluded) for the specified period.
Parameters:
├── days: Integer (1-365)
├── Default: 7 days
└── Shows top 10 results
Output Format:
"═══════════════════════════════════════"
" ? Top Staff - Last 7 Days"
"═══════════════════════════════════════"
""
"? 1 PlayerOne - 45h 30m 15s"
"? 2 PlayerTwo - 38h 15m 42s"
"? 3 PlayerThree - 32h 45m 10s"
" 4 PlayerFour - 28h 20m 30s"
" 5 PlayerFive - 25h 55m 18s"
" 6 PlayerSix - 22h 10m 45s"
" 7 PlayerSeven - 20h 30m 22s"
" 8 PlayerEight - 18h 45m 50s"
" 9 PlayerNine - 15h 20m 12s"
" 10 PlayerTen - 12h 35m 40s"
""
"═══════════════════════════════════════"
"Showing top 10 staff members"
Medal Icons:
├── ? 1st Place (Gold)
├── ? 2nd Place (Silver)
└── ? 3rd Place (Bronze)
Database Query:
SELECT u.name, SUM(s.active_millis) as total
FROM usm_sessions s
JOIN usm_users u ON s.uuid = u.uuid
WHERE s.start_timestamp >= [cutoff]
GROUP BY s.uuid
ORDER BY total DESC
LIMIT 10
Processing: Async (displays loading message)
/stafftime list (Live Staff Monitor)
Permission: usm.admin
Aliases: /st list, /clock active
Usage: /stafftime list
Description:
For players: Opens an interactive GUI with player heads
For console: Displays formatted chat list
GUI Features:
├── Player heads with skins
├── Real-time status indicators
├── Session duration displays
├── Activity percentages (color-coded)
├── Note counts
└── Manual refresh button
Console Output:
"═══════════════════════════════════════"
" ? Currently Active Staff"
"═══════════════════════════════════════"
""
"1. PlayerOne - 2h 34m (Activity: 92.3%)"
" Active: 2h 15m | Idle: 18m"
""
"2. PlayerTwo - 1h 45m (Activity: 78.5%)"
" Active: 1h 22m | Idle: 22m"
""
"═══════════════════════════════════════"
"Total: 2 staff member(s) active"
Use Cases:
├── Monitor current staff availability
├── Check who's actively working
├── Identify idle staff members
├── Plan shift coverage
└── Performance oversight
/stafftime adjust <player> <add|remove> <amount> <active|idle> (Time Adjustment)
Permission: usm.admin (requires usm.adjust)
Aliases: /st adjust, /clock modify
Usage:
/stafftime adjust <player> <add|remove> <amount> <active|idle>
Examples:
/stafftime adjust Steve add 3600000 active
→ Adds 1 hour to Steve's active time
/stafftime adjust Alex remove 1800000 idle
→ Removes 30 minutes from Alex's idle time
/stafftime adjust Bob add 7200000 active
→ Adds 2 hours to Bob's active time
Parameters:
├── player: Player name (online or offline)
├── operation: "add" or "remove"
├── amount: Milliseconds (1 hour = 3600000)
└── type: "active" or "idle"
Time Conversions:
├── 1 minute = 60,000 ms
├── 5 minutes = 300,000 ms
├── 10 minutes = 600,000 ms
├── 30 minutes = 1,800,000 ms
├── 1 hour = 3,600,000 ms
├── 2 hours = 7,200,000 ms
└── 24 hours = 86,400,000 ms
Validation:
├── Player exists check
├── Amount > 0 check
├── Valid operation check
├── Valid type check
└── Permission verification
Confirmation Display:
"═══════════════════════════════════"
" Time Adjustment"
"═══════════════════════════════════"
""
"Player: Steve"
"Operation: ADD"
"Amount: 1h 0m 0s"
"Type: ACTIVE"
""
"⏳ Processing adjustment..."
"✓ Time adjustment applied successfully!"
Logging:
Logs to console:
"[ADJUST] AdminName added 1h 0m 0s active time for Steve"
Use Cases:
├── Correct tracking errors
├── Compensate for server downtime
├── Reward bonus time
├── Fix database issues
└── Manual corrections
6️⃣ Permission System (Complete)
Permission Hierarchy Tree
usm.* (OP)
│
├─ usm.use (TRUE) ─────────────────┐
│ ├─ usm.clockin │ PLAYER
│ ├─ usm.clockout │ PERMISSIONS
│ ├─ usm.addnote │
│ └─ usm.history │
│ │
├─ usm.track (FALSE) ──────────────┤ STAFF
│ └─ [Enables auto-tracking] │ PERMISSION
│ │
└─ usm.admin.* (OP) ───────────────┘
├─ usm.admin
├─ usm.top
├─ usm.list
└─ usm.adjust
Permission Descriptions
usm.* (Parent Permission)
Description: Grants all plugin permissions
Default: OP only
Children:
- usm.use
- usm.track
- usm.admin
- usm.adjust
Grant Command (LuckPerms):
/lp user <name> permission set usm.*
Use Case: Server owners and senior administrators
usm.use (Basic Access)
Description: Access to dashboard and basic commands
Default: True (all players)
Allows:
- /stafftime (dashboard)
- /stafftime clockin
- /stafftime clockout
- /stafftime addnote
Does NOT Allow:
- Auto-tracking on join
- Admin commands
Grant Command:
/lp group default permission set usm.use true
Use Case: All players (for personal time tracking)
usm.track (Auto-Tracking)
Description: Enables automatic session tracking
Default: False (must be granted)
Behavior:
- Auto clock-in on join
- Auto clock-out on quit
- Requires usm.use permission also
Grant Command:
/lp user <name> permission set usm.track true
Use Case: ONLY grant to actual staff members
Example Setup:
1. Create staff group: /lp creategroup staff
2. Grant tracking: /lp group staff permission set usm.track true
3. Add user: /lp user PlayerName parent add staff
usm.admin (Admin Commands)
Description: Access to administrative features
Default: OP only
Allows:
- /stafftime top
- /stafftime list
- View all player data
Does NOT Allow:
- Time adjustments (requires usm.adjust)
Grant Command:
/lp user <name> permission set usm.admin true
Use Case: Server moderators and administrators
usm.adjust (Time Modification)
Description: Ability to modify player time records
Default: OP only
Allows:
- /stafftime adjust command
- Add/remove time from any player
Security Warning:
Only grant to highly trusted administrators!
Grant Command:
/lp user <name> permission set usm.adjust true
Use Case: Senior admins for corrections only
Recommended Permission Setups
Setup 1: Small Server (10-50 players)
Default Group (All Players):
- usm.use: true
Staff Group (Moderators):
- Inherits: default
- usm.track: true
Admin Group (Administrators):
- Inherits: staff
- usm.admin: true
- usm.adjust: true
Commands:
/lp creategroup staff
/lp group staff parent add default
/lp group staff permission set usm.track true
/lp creategroup admin
/lp group admin parent add staff
/lp group admin permission set usm.admin true
/lp group admin permission set usm.adjust true
Setup 2: Large Network (100+ players)
Groups:
default:
- No USM permissions (not tracked)
helper:
- usm.use: true
- usm.track: true
moderator:
- Inherits: helper
- usm.admin: true
admin:
- Inherits: moderator
- usm.adjust: true
owner:
- usm.*: true
Commands:
/lp creategroup helper
/lp group helper permission set usm.use true
/lp group helper permission set usm.track true
/lp creategroup moderator
/lp group moderator parent add helper
/lp group moderator permission set usm.admin true
/lp creategroup admin
/lp group admin parent add moderator
/lp group admin permission set usm.adjust true
? Integration & API
PlaceholderAPI Support (Planned v1.1)
Planned Placeholders:
%usm_session_duration% → "2h 34m 12s"
%usm_session_active% → "2h 15m 30s"
%usm_session_idle% → "18m 42s"
%usm_session_activity% → "87.5%"
%usm_session_status% → "Active" / "Idle"
%usm_total_active% → "145h 30m 15s"
%usm_total_idle% → "12h 45m 20s"
%usm_rank_position% → "3"
%usm_notes_count% → "5"
Usage Example (Scoreboard):
- &aSession: &f%usm_session_duration%
- &aStatus: &f%usm_session_status%
- &aActivity: &f%usm_session_activity%
1️⃣2️⃣ Support & Resources
Official Resources
? Bug Reporting:
1️⃣3️⃣ Technical Specifications
Plugin Information:
Name: UltimateStaffManagement
Version: 1.0.0
Author: geturplugins
License: AllRightsReserved
Language: Java 21
Dependencies:
├── Paper API: 1.21-1.21.11 (Required)
├── HikariCP: 5.1.0 (Bundled)
├── SQLite JDBC: 3.45.1.0 (Bundled)
├── MySQL Connector: 8.3.0 (Optional)
└── Adventure API: 4.x (Provided by Paper)
File Size:
├── JAR Size: ~1.5 MB
├── With Dependencies: ~3.2 MB
└── Database (SQLite): Grows ~50KB per 1000 sessions
Performance:
├── RAM Usage: 30-50MB (100 active sessions)
├── CPU Impact: < 0.1% per 50 tracked players
├── TPS Impact: None (async operations)
└── Database Speed: < 10ms per query (SSD)
Compatibility:
✅ Paper 1.21 - 1.21.11
✅ Purpur 1.21+
⚠️ Spigot 1.21 (Limited Adventure API)
❌ Bukkit (Not supported)
❌ Folia (Not yet supported)
? Statistics (Example Server)
Server Profile:
- Type: Roleplay Server
- Players: 150 concurrent
- Staff: 25 tracked members
- Database: MySQL
- Uptime: 99.8%
Results:
Performance Metrics:
├── Average Session Length: 3h 15m
├── Total Sessions Tracked: 12,450
├── Database Size: 145 MB
├── Query Response Time: < 5ms
└── Zero TPS impact
Staff Insights:
├── Most Active Staff: 45h/week
├── Average Activity Rate: 82.3%
├── Total Hours Tracked: 15,230h
└── Notes Recorded: 3,847
Resource Usage:
├── Plugin RAM: 42 MB
├── Database Connections: 8 active
├── Thread Pool: 4 threads
└── CPU Usage: 0.08%
? Summary
UltimateStaffManagement is the most comprehensive staff tracking solution for Minecraft servers, offering:
✅ Precision Tracking - Millisecond-accurate time tracking with active/idle differentiation
✅ Zero Performance Impact - Fully asynchronous operations with HikariCP pooling
✅ Beautiful GUIs - Interactive dashboards with real-time updates
✅ Enterprise Database - SQLite and MySQL support with automatic backups
✅ Powerful Analytics - Leaderboards, performance metrics, and detailed reports
✅ Flexible Configuration - 100+ config options for complete customization
✅ Developer Friendly - Full Java API with extensive documentation
✅ Production Ready - Battle-tested architecture with comprehensive error handling
Perfect for:
- Roleplay servers requiring staff hour tracking
- Networks needing centralized time management
- Communities managing volunteer staff
- Professional servers with paid staff positions
- Any server wanting detailed activity analytics
? The Ultimate Solution for Staff Management ?
评论 0
登录后参与评分
还没有评论,来抢沙发吧