AntiAFKPlus v2.5 — Release Notes

AFK Credit System - Earn Time to Be Away

New Feature Overview

Revolutionary AFK Credit System: Players can now earn AFK time by being active! For every X minutes of active gameplay, players earn Y minutes of AFK allowance before being teleported to a designated AFK zone.

What’s New
1. AFK Credit Earning System

• Players earn AFK credits by being actively engaged in gameplay
• Configurable credit ratios based on permissions (default: 5 minutes active = 1 minute AFK credit)
• Real-time credit accumulation tracking with activity validation
• Maximum credit limits to prevent indefinite accumulation

2. Credit-Based AFK Protection

• When a player goes AFK, the system first consumes available credits
• Credits provide immunity from immediate kick/teleportation
• Once credits are exhausted, player is teleported to designated AFK zone
• Smooth transition from credit consumption to zone teleportation

AFK Credit System

• Earn credits while active; consume credits to delay AFK action.
• Teleport to AFK zone when credits are exhausted; /afkback returns you.

WorldGuard Integration

• Zones resolved from regions (reflection, no hard dependency).
• Teleport priority: zones.afk → zones.spawn → credit-system.afk-zone.

AFK Zone Protection

• Optional damage/PVP/mob-spawn protections near the AFK zone.

SQL History (Optional)

• Track earn/consume/admin/decay transactions when SQL is enabled.

New Placeholder

• %antiafkplus_credits_expire_days% — days until credits expire.

How It Works

1. Active players earn credits (ratio-based) up to a configurable cap.
2. When AFK is detected, 1 credit/minute is consumed to delay the action.
3. At 0 credits, the player is teleported to the AFK zone; /afkback returns them.

Configuration (added)

Code (YAML):

modules:
  credit-system:
    enabled : false
credit-system:
  enabled : false
  credit-ratios:
    default : "5:1"
    vip : "4:1"
    premium : "3:1"
    admin : "2:1"
  max-credits:
    default : 120
    vip : 180
    premium : 240
    admin : 480
  earning-requirements:
    minimum-session-minutes : 5
    activity-threshold : 0.3
  afk-zone:
    enabled : true
    world : "world"
    location : "0,100,0"
  notifications:
    credit-earned : true
    credit-consumed : true
    credit-exhausted : true
  return-command:
    enabled : true
    cooldown-seconds : 10

Messages (added)

Permissions (declared)

• antiafkplus.credit.earn — earn credits (default true)
• antiafkplus.credit.use — use credits to delay AFK action (default true)
• antiafkplus.credit.ratio.vip|premium|admin — improved ratios (default false/op)
• antiafkplus.credit.admin — full credit administration

Execution Flow

1. Active player earns credits according to ratio and limits.
2. On AFK, if credits available → cancel action and consume 1/min.
3. On activity → stop consumption (no teleport).
4. On exhaustion → teleport to AFK zone (zone‑management if present; fallback to credit-system.afk-zone).

Compatibility & Performance

• Folia‑safe (no BukkitScheduler in Folia context).
• No changes to AFKManager loop (event‑driven).
• Earning: one global job/min; consumption: per‑player task while AFK with balance.
• Respects antiafkplus.bypass.

Credit System Logic Flow

1. Credit Earning Process:

Player Active (5 minutes) → Activity Validation → Credit Calculation → Credit Award
↓
Activity Score Check → Pattern Detection → Anti-Abuse Validation → Credit Storage

2. AFK Detection with Credits:

Player Goes AFK → Check Credit Balance → Has Credits?
↓
Yes: Consume Credits → Continue Monitoring
↓
No: Save Location → Teleport to AFK Zone → Enable Return Command

3. Return Process:

Player Uses /afkback → Validate in AFK Zone → Check Original Location Safety
↓
Safe: Teleport Back → Clear AFK Status → Success Message
↓
Unsafe: Teleport to Spawn → Warning Message

✅ Benefits and Features

Player Benefits:

• Earn AFK Time: Active gameplay is rewarded with AFK allowance
• Flexible AFK: No immediate kicks, gradual credit consumption
• Safe Return: Always able to return to original location
• Transparent System: Clear feedback on credit earning and consumption

Server Owner Benefits:

• Configurable Ratios: Adjust credit earning rates by permission groups
• Abuse Prevention: Anti-pattern detection during credit earning
• Zone Management: Designated safe AFK areas
• Database Support: Optional persistent credit storage

Technical Benefits:

• Modular Design: Integrates seamlessly with existing module system
• Performance Optimized: Minimal impact on server performance
• API Complete: Full programmatic access for other plugins
• Event System: Comprehensive events for custom integrations

Integration Points

Existing System Integration:

• AFKManager: Credit verification before actions
• PatternDetector: Anti-abuse during credit earning
• ModuleManager: Full module lifecycle support
• PlaceholderAPI: Credit balance and status placeholders
• Reward System: Bonus credits through reward intervals
• Zone Management: AFK zone configuration and management

Testing Scenarios

Core Functionality Tests:

1. Credit Earning: Verify active play generates credits at correct ratios
2. Credit Consumption: Confirm AFK periods consume credits properly
3. Zone Teleportation: Test teleport when credits exhausted
4. Return Command: Validate return to original location
5. Permission Integration: Test different ratios by permission groups

Edge Case Testing:

1. Location Safety: Handle unsafe original locations
2. World Changes: Manage cross-world teleportation
3. Server Restart: Verify credit persistence (if database enabled)
4. Concurrent Usage: Test multiple players earning/using credits
5. Configuration Reload: Ensure system adapts to config changes

Compatibility

• Minecraft: 1.16 - 1.21.8+ (unchanged)
• Java: 17+ (unchanged)
• Platforms: Paper, Spigot, Bukkit, Purpur, Folia (full compatibility)
• Dependencies: None required, Vault optional for database features

Migration and Upgrade
Automatic Migration:

• Existing configurations remain unchanged
• Credit system starts disabled by default
• No breaking changes to existing functionality
• Seamless integration with current AFK detection

Manual Configuration:

• Server owners must enable credit-system.enabled: true
• Configure AFK zone location
• Adjust credit ratios for permission groups
• Customize messages and notifications

Version: 2.5
Release Date: 11/09/2025
Compatibility: Minecraft 1.16 - 1.21.8+
Java: 17+