📘 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
```yaml
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:**
```java
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
```
---
4️⃣ Interactive GUI System
Dashboard GUI (`/stafftime`)
**Layout Design:**
```
┌─────────────────────────────────────┐
│ [Filler] [Clock] [Filler] │
│ [Filler] [Book] [Filler] │
│ [Filler] [Paper] [Filler] │
└─────────────────────────────────────┘
```
**Slot 2: Current Session Stats (Clock Item)**
```yaml
Display Information:
- Status Indicator: ✓ Active / ⏸ Idle
- Session Duration: "2h 34m 12s"
- Active Time: "2h 15m 30s" (Green)
- Idle Time: "18m 42s" (Yellow)
- Activity Rate: "87.5%" (Color-coded)
- Real-time Updates: Every 2 seconds
Color Coding:
├── Green (80-100%): Excellent activity
├── Yellow (50-79%): Moderate activity
└── Red (0-49%): Low activity
Click Action: Refresh data
```
**Slot 4: Session History (Book Item)**
```yaml
Features:
- Shows last 5 completed sessions
- Date format: "Jan 15, 2026 14:30"
- Duration breakdown per session
- Activity percentage trends
- Total time statistics
Click Action: Opens History GUI
Lore Preview:
"Recent Sessions:"
"━━━━━━━━━━━━━━"
"Jan 15 - 3h 45m (92% active)"
"Jan 14 - 5h 12m (78% active)"
"Jan 13 - 2h 30m (95% active)"
```
**Slot 6: Session Notes (Paper Item)**
```yaml
Note Display:
- Last 5 notes shown
- Timestamped entries: "[14:35:22] Handled player reports"
- Total note count indicator
- Add instructions in lore
Click Action: View-only (add via command)
Example Lore:
"📝 Session Notes (3)"
"━━━━━━━━━━━━━━"
"[14:35:22] Handled 5 player reports"
"[15:10:45] Reviewed ban appeals"
"[16:22:11] Assisted with server event"
""
"Add notes: /stafftime addnote <message>"
```
---
History GUI (`Click book in dashboard`)
**Layout:**
```
┌─────────────────────────────────────────────────┐
│ [Glass] [Glass] [Glass] [Glass] [Glass] │
│ [Session1] [Session2] [Session3] [Session4] │
│ [Session5] [Glass] [Glass] [Glass] │
│ [Glass] [Glass] [Glass] [Back Button] │
└─────────────────────────────────────────────────┘
```
**Session Item Details:**
```yaml
Item Type: Writable Book
Display Name: "Session 1" (Gold, Bold)
Lore Information:
├── 📅 Date: "Jan 15, 2026 09:30"
├── ⏰ Duration: "3h 45m 30s"
├── ⚡ Active Time: "3h 28m 15s"
├── ⏸ Idle Time: "17m 15s"
├── 📊 Activity: "92.3%"
└── 📝 Notes: "(3)" - Shows first 3 notes
Click: View full session details (future feature)
```
**Navigation:**
- Slot 26: Back arrow (returns to dashboard)
- Pagination (future): Next/Previous page buttons
---
Staff List GUI (`/stafftime list` - Admin)
**Layout:**
```
┌──────────────────────────────────────────────────┐
│ [Glass] [Glass] [Glass] [Glass] [Glass] [Glass]│
│ [Staff1] [Staff2] [Staff3] [Staff4] [Staff5] │
│ [Staff6] [Staff7] [Staff8] [Glass] [Glass] │
│ [Glass] [Glass] [Glass] [Refresh] [Glass] │
└──────────────────────────────────────────────────┘
```
**Staff Member Item:**
```yaml
Item Type: Player Head (shows player skin)
Display Name: "PlayerName ✔" (Active) / "PlayerName ⏸" (Idle)
Status Colors:
├── White & Bold: Player name
├── Green ✔: Currently active
└── Yellow ⏸: Currently idle
Lore Display:
├── Status: "Active" (colored)
├── ⏱ Session: "1h 23m 45s"
├── ⚡ Active: "1h 15m 30s"
├── ⏸ Idle: "8m 15s"
├── 📊 Activity: "90.1%" (color-coded)
└── 📝 Notes: "(2)" if notes exist
Real-Time Updates: Auto-refreshes every 2 seconds
```
**Slot 49: Info/Refresh Button**
```yaml
Item: Knowledge Book
Display: "ℹ Information"
Lore:
"Total Active Staff: 7"
"Right-click to refresh"
Click: Manual refresh (instant update)
```
---
5️⃣ Comprehensive Command System
Player Commands (Detailed)
`/stafftime` (Main Dashboard)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)
```yaml
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)**
```yaml
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)**
```yaml
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
```
---
7️⃣ Configuration Deep Dive
Critical Settings Explained
**afk-timeout-seconds** (Default: 600)
```yaml
Description:
Time in seconds before a player is marked as IDLE.
Values:
Minimum: 30 (30 seconds)
Recommended: 300-900 (5-15 minutes)
Maximum: 3600 (1 hour)
Default: 600 (10 minutes)
Impact:
├── Lower values (30-120): Strict monitoring, more idle time recorded
├── Medium values (300-600): Balanced, recommended for most servers
└── Higher values (900+): Lenient, allows breaks without idle marking
Example Scenarios:
afk-timeout-seconds: 120
→ Staff marked idle after 2 minutes of no movement
→ Good for: High-activity servers, customer service roles
afk-timeout-seconds: 600
→ Staff marked idle after 10 minutes
→ Good for: General servers, balanced tracking
afk-timeout-seconds: 1800
→ Staff marked idle after 30 minutes
→ Good for: Build servers, relaxed environments
```
**movement-threshold** (Default: 0.1)
```yaml
Description:
Minimum block movement required to register as activity.
Values:
0.05: Very sensitive (counts tiny movements)
0.1: Recommended (balanced sensitivity)
0.5: Less sensitive (requires larger movements)
1.0: Minimal sensitivity (only counts significant movement)
Impact on Detection:
├── Lower = More sensitive = More active time
└── Higher = Less sensitive = More idle time
Example:
movement-threshold: 0.05
→ Even small adjustments count as active
→ May register unintentional movements
movement-threshold: 1.0
→ Only walking/running counts as active
→ AFK mining/fishing marked as idle
```
**rotation-threshold** (Default: 1.0)
```yaml
Description:
Minimum degrees of head rotation to register as activity.
Values:
0.5: Very sensitive (slight head turns count)
1.0: Recommended (normal head movements)
5.0: Less sensitive (requires deliberate looking)
10.0: Minimal (only counts large view changes)
Use Cases:
1.0 degrees:
→ Looking around while standing counts as active
→ Good for: Monitoring roles, ticket handling
5.0 degrees:
→ Only significant head turns count
→ Good for: Strict movement-only tracking
```
**auto-save-interval** (Default: 5)
```yaml
Description:
How often (in minutes) to save active sessions to database.
Values:
0: Disabled (only save on logout)
1-5: Frequent saves (recommended)
10-30: Infrequent saves (performance mode)
60+: Minimal saves (not recommended)
Safety vs Performance:
├── Lower interval = Safer (less data loss) but more DB writes
└── Higher interval = Faster but risk losing recent data
Recommendations:
Small server (< 20 staff): 5 minutes
Medium server (20-100 staff): 3 minutes
Large server (100+ staff): 10 minutes + MySQL
```
**max-session-duration** (Default: 24)
```yaml
Description:
Maximum hours before auto-ending a session.
Prevents infinitely running sessions from AFK players.
Values:
0: Unlimited (not recommended)
8: 8-hour work shift
12: Half-day maximum
24: Full day (recommended default)
Example:
max-session-duration: 8
→ After 8 hours, session auto-ends
→ Player must manually clock back in
→ Good for: Enforcing shift limits
```
---
Message Customization (MiniMessage)
**Supported Formats:**
**Colors:**
```yaml
<red>Error message</red>
<green>Success message</green>
<yellow>Warning message</yellow>
<blue>Info message</blue>
<gold>Special message</gold>
<aqua>Highlight</aqua>
<gray>Subtle text</gray>
<dark_gray>Very subtle</dark_gray>
<white>Default text</white>
```
**Formatting:**
```yaml
<bold>Bold text</bold>
<italic>Italic text</italic>
<underlined>Underlined</underlined>
<strikethrough>Strikethrough</strikethrough>
<obfuscated>Obfuscated</obfuscated>
```
**Gradients:**
```yaml
<gradient:red:blue>Gradient text</gradient>
<gradient:gold:yellow:green>Multi-color gradient</gradient>
<gradient:FF0000:00FF00>Hex gradients</gradient>
```
**Hover Text:**
```yaml
<hover:show_text:'Hover to see this!'>Main text</hover>
<hover:show_text:'<green>Colored hover text'>Hover me</hover>
```
**Click Actions:**
```yaml
<click:run_command:'/stafftime'>Click to run</click>
<click:suggest_command:'/stafftime '>Click to suggest</click>
<click:open_url:'https://example.com'>Click to open</click>
```
**Combined Example:**
```yaml
messages:
session-started: >
<gradient:green:aqua><bold>✓ SESSION STARTED</bold></gradient>
<newline>
<gray>Your time is being tracked.</gray>
<newline>
<hover:show_text:'<green>Click to view dashboard'>
<click:run_command:'/stafftime'>
<aqua>→ View Stats</aqua>
</click>
</hover>
```
---
8️⃣ Use Cases & Scenarios
Scenario 1: Professional Roleplay Server
**Server Type:** Roleplay/Economy
**Staff Size:** 15 moderators, 5 admins
**Requirement:** Track moderation hours for monthly payments
**Configuration:**
```yaml
afk-timeout-seconds: 300 5 minutes (strict)
max-session-duration: 8 8-hour shifts
auto-save-interval: 3 Frequent saves
notifications:
hourly-updates: true Remind staff of hours worked
admin-notifications: true Notify admins of clock-ins
```
**Permissions:**
```bash
Moderators get auto-tracking
/lp group moderator permission set usm.track true
Admins can view leaderboards
/lp group admin permission set usm.admin true
```
**Usage Workflow:**
1. Moderator joins server → Auto clock-in
2. Works for 4 hours → Session tracked
3. Moderator leaves → Auto clock-out
4. Admin runs `/stafftime top 30` → View monthly hours
5. Admin exports data → Calculate payments
---
Scenario 2: Large Network Staff Management
**Server Type:** Multi-server network (Hub + 5 game servers)
**Staff Size:** 50+ staff across all servers
**Requirement:** Centralized time tracking
**Configuration:**
```yaml
storage-type: mysql Centralized database
mysql:
host: db.network.com
database: staff_global
performance:
thread-pool-size: 8 Higher for many concurrent users
cache-enabled: true
cache-size: 200 Cache more sessions
```
**Database Setup:**
```sql
-- Shared MySQL database accessible by all servers
-- Each server writes to same tables
-- Real-time synchronization
```
**Benefits:**
- Staff can work on any server, time is tracked globally
- Admins see combined hours across all servers
- Single leaderboard for entire network
---
Scenario 3: Community Event Tracking
**Server Type:** Community server
**Staff Size:** 10 event coordinators
**Requirement:** Track event preparation time
**Configuration:**
```yaml
afk-timeout-seconds: 900 15 minutes (lenient for building)
max-note-length: 500 Detailed event notes
notifications:
session-start: false Don't spam during events
session-end: true Summary at end
```
**Usage:**
```bash
Event coordinator starts
/stafftime clockin
Add notes throughout
/stafftime addnote Started building event arena
/stafftime addnote Configured game mechanics
/stafftime addnote Tested event with team
View hours spent on event
/stafftime clockout
```
**Exported Data:**
```json
{
"session_id": 12345,
"coordinator": "EventStaff",
"duration": "5h 30m",
"notes": [
"[10:00:00] Started building event arena",
"[11:30:00] Configured game mechanics",
"[14:15:00] Tested event with team"
]
}
```
---
Scenario 4: Performance Monitoring
**Server Type:** Competitive server
**Staff Size:** 20 helpers
**Requirement:** Identify most active staff for promotions
**Commands Used:**
```bash
Weekly leaderboard
/stafftime top 7
Monthly review
/stafftime top 30
Check current availability
/stafftime list
View individual performance
/stafftime (player opens own dashboard)
```
**Metrics Tracked:**
```yaml
Promotion Criteria:
├── Total active hours > 40h per month
├── Activity percentage > 85%
├── Consistent daily presence
└── Low idle time ratio
Evaluation Process:
1. Run /stafftime top 30
2. Export top performers
3. Review session notes for quality
4. Check activity percentage
5. Make promotion decisions
```
---
9️⃣ Performance Optimization
Server Performance Impact
**CPU Usage:**
```yaml
AFK Detection Task (per 20 ticks):
├── Players Tracked: 50 staff
├── Checks per Second: 50 location comparisons
├── CPU Impact: < 0.1% on modern servers
└── Optimization: Uses efficient location caching
Database Operations:
├── All writes: Asynchronous (no TPS impact)
├── Reads: Cached (minimal DB hits)
└── Connection Pooling: HikariCP (sub-ms acquisition)
Total Impact:
├── TPS Impact: None (< 0.01ms per tick)
├── Memory: ~50MB for 100 active sessions
└── Recommended: 512MB RAM allocation minimum
```
**Optimization Settings:**
For **Small Servers** (< 50 players):
```yaml
performance:
async-database: true
cache-enabled: true
cache-size: 50
thread-pool-size: 2
afk:
check-interval-ticks: 20 Standard 1-second checks
```
For **Large Servers** (100+ players):
```yaml
performance:
async-database: true
cache-enabled: true
cache-size: 200 Cache more sessions
thread-pool-size: 8 More async threads
batch-size: 100 Larger batch inserts
afk:
check-interval-ticks: 20 Keep responsive
mysql:
pool:
maximum-pool-size: 20 More DB connections
minimum-idle: 5
```
For **Networks** (Multi-server):
```yaml
storage-type: mysql Required for multi-server
mysql:
host: dedicated-db-server.com
pool:
maximum-pool-size: 30
minimum-idle: 10
performance:
cache-duration-minutes: 60 Longer caching
thread-pool-size: 16 Network-grade threading
```
---
🔟 Integration & API
PlaceholderAPI Support (Planned v1.1)
**Planned Placeholders:**
```yaml
%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️⃣1️⃣ Troubleshooting Guide
Common Issues & Solutions
**Issue 1: "Sessions not being tracked"**
**Symptoms:**
- Player joins but no session starts
- `/stafftime` shows "No active session"
**Diagnosis:**
```bash
Check permission
/lp user <player> permission check usm.track
Should show: true
Check console logs
Look for: "[ADJUST] Auto-started session for <player>"
```
**Solutions:**
```yaml
1. Verify Permission:
/lp user <player> permission set usm.track true
2. Check Auto-Tracking Config:
In config.yml
notifications:
session-start: true Must be true
3. Check Plugin Loaded:
/plugins
UltimateStaffManagement should be GREEN
4. Test Manual Clock-In:
/stafftime clockin
If this works, permission issue confirmed
```
---
**Issue 2: "Database connection failed"**
**Error Message:**
```
[ERROR] [DB] Failed to create tables: Communications link failure
```
**For SQLite:**
```bash
Check file permissions
ls -la plugins/UltimateStaffManagement/
Should show: -rw-r--r-- staffdata.db
Fix permissions
chmod 644 plugins/UltimateStaffManagement/staffdata.db
Delete and regenerate
rm plugins/UltimateStaffManagement/staffdata.db
/reload confirm
```
**For MySQL:**
```yaml
Test connection manually
mysql -h localhost -u username -p database_name
Common fixes:
mysql:
host: 127.0.0.1 Try IP instead of localhost
use-ssl: false Disable SSL if having issues
Grant proper permissions
GRANT ALL PRIVILEGES ON ultimatestaff.* TO 'minecraft'@'%';
FLUSH PRIVILEGES;
```
---
**Issue 3: "AFK detection not working"**
**Symptoms:**
- Player moving but still marked as idle
- Player AFK but marked as active
**Debug Steps:**
```yaml
1. Enable Debug Mode:
config.yml:
debug-mode: true
2. Check Console:
Should see every second:
"[AFK] Checking 5 players..."
"[AFK] PlayerName is now ACTIVE"
3. Verify Settings:
afk-timeout-seconds: 600
movement-threshold: 0.1
rotation-threshold: 1.0
check-interval-ticks: 20
4. Test Sensitivity:
Lower for more sensitive
movement-threshold: 0.05
rotation-threshold: 0.5
```
---
**Issue 4: "Server lag when using plugin"**
**Symptoms:**
- TPS drops when staff join
- Lag spikes every few seconds
**Diagnosis:**
```bash
Check TPS
/tps Should be 20.0
Check timings
/timings on
Wait 5 minutes
/timings paste
```
**Solutions:**
```yaml
1. Verify Async Enabled:
performance:
async-database: true
2. Reduce Check Frequency:
check-interval-ticks: 40 Check every 2 seconds instead
3. Increase Thread Pool:
performance:
thread-pool-size: 8
4. Enable Caching:
performance:
cache-enabled: true
cache-size: 200
5. Use MySQL for Large Servers:
storage-type: mysql
```
---
**Issue 5: "Data not saving on server crash"**
**Symptoms:**
- Session lost after server crash
- Hours not recorded
**Prevention:**
```yaml
1. Enable Auto-Save:
auto-save-interval: 3 Save every 3 minutes
2. Enable Backups:
advanced:
auto-backup: true
backup-interval-hours: 6
3. Use WAL Mode (SQLite):
sqlite:
wal-mode: true
4. Test Manual Save:
/stafftime clockout
Then check database
```
---
1️⃣2️⃣ Support & Resources
Official Resources
**🐛 Bug Reporting:**
- [Discord](geturplugins)
---
1️⃣3️⃣ Technical Specifications
**Plugin Information:**
```yaml
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
