SMPGracePeriod

Temporary PvP disable with configurable duration, BossBar countdown, and inter-plugin API.

Features

• Command-based control: /smpg with subcommands (start, stop, pause, resume, status)
• BossBar countdown: Displays remaining time with color and progress bar to all players
• Configurable duration: Supports flexible format (e.g., 5m, 2h, 1d, 300s)
• State management: Active, paused, and stopped states with server restart persistence
• Milestone announcements: Title/subtitle notifications at fixed times (1m, 2m, 5m, 10m, 30m, 60m)
• Countdown display: Title/subtitle countdown for final 10 seconds with sound effects
• Sound effects: Configurable sounds for milestones, countdown, and completion
• Damage blocking: Blocks all player-to-player damage during grace period
• Public API: Other plugins can interact with the grace period system
• Tab completion: Full tab completion for subcommands

Commands

• /smpg start - Begin grace period
• /smpg stop - End grace period immediately
• /smpg pause - Pause countdown (shows frozen time)
• /smpg resume - Resume from paused state
• /smpg status - Display current state and remaining time
• /smpgraceperiod - Alias for /smpg

Permissions

• smpgraceperiod.admin - Access all commands (OP only)
• smpgraceperiod.start - Start grace period (OP only)
• smpgraceperiod.stop - Stop grace period (OP only)
• smpgraceperiod.pause - Pause grace period (OP only)
• smpgraceperiod.resume - Resume grace period (OP only)
• smpgraceperiod.status - Check status (Everyone)

Configuration

config.yml - Customizable settings:

• Duration: Grace period length with flexible format
  • Plain numbers: 300 (seconds)
  • With suffix: 10s, 5m, 2h, 1d
  • Combined: 5m30s (5 minutes 30 seconds)
• Messages: All messages use MiniMessage format
  • Start/Stop/Pause/Resume chat messages
  • Milestone title and subtitle messages (with {time} placeholder)
  • Countdown title and subtitle messages (with {time} placeholder)
• BossBar: Customize color (PURPLE, BLUE, RED, GREEN, YELLOW, WHITE, PINK) and style
• Sounds: Configurable sound effects for milestones, countdown, and completion

status.yml - Auto-saved state (created automatically):

• Current state (active/paused/stopped)
• Start timestamp and pause offset
• Original duration (preserves across config changes)
• Automatically restored when server restarts

Package Structure

• org.m9mx.smpgraceperiod.SMPGracePeriod - Main plugin class
• org.m9mx.smpgraceperiod.api - Public API for other plugins
• org.m9mx.smpgraceperiod.config - Configuration management
• org.m9mx.smpgraceperiod.grace - Grace period logic
• org.m9mx.smpgraceperiod.util - Utility functions (DurationParser)

Public API

Other plugins can interact with the grace period system using the GracePeriodAPI interface.

Getting the API

import org.bukkit.Bukkit;
import org.bukkit.plugin.Plugin;
import org.m9mx.smpgraceperiod.SMPGracePeriod;
import org.m9mx.smpgraceperiod.api.GracePeriodAPI;

Plugin plugin = Bukkit.getPluginManager().getPlugin("SMPGracePeriod");
if (plugin instanceof SMPGracePeriod smpGrace) {
    GracePeriodAPI api = smpGrace.getAPI();
    // Use the API
}

API Methods

void start()

Starts the grace period.

api.start();

void stop()

Stops the grace period immediately.

api.stop();

void pause()

Pauses the grace period countdown.

api.pause();

void resume()

Resumes the grace period from paused state.

api.resume();

String getStatus()

Gets the current status (active, paused, stopped).

String status = api.getStatus();

long getRemainingTime()

Gets remaining time in seconds (0 if not active).

long remaining = api.getRemainingTime();

boolean isActive()

Checks if grace period is currently active.

if (api.isActive()) {
    // PvP is disabled
}

boolean isPaused()

Checks if grace period is currently paused.

if (api.isPaused()) {
    // Grace period is paused
}

long getDuration()

Gets configured grace period duration in seconds.

long duration = api.getDuration();

Full Example

import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.Plugin;
import org.bukkit.plugin.java.JavaPlugin;
import org.m9mx.smpgraceperiod.SMPGracePeriod;
import org.m9mx.smpgraceperiod.api.GracePeriodAPI;

public class MyPlugin extends JavaPlugin implements Listener {
    
    @Override
    public void onEnable() {
        Plugin plugin = Bukkit.getPluginManager().getPlugin("SMPGracePeriod");
        
        if (plugin instanceof SMPGracePeriod smpGrace) {
            GracePeriodAPI api = smpGrace.getAPI();
            getServer().getPluginManager().registerEvents(this, this);
            getLogger().info("SMPGracePeriod API loaded!");
        } else {
            getLogger().warning("SMPGracePeriod plugin not found!");
        }
    }
    
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        Plugin plugin = Bukkit.getPluginManager().getPlugin("SMPGracePeriod");
        if (plugin instanceof SMPGracePeriod smpGrace) {
            GracePeriodAPI api = smpGrace.getAPI();
            
            if (api.isActive()) {
                event.getPlayer().sendMessage("Grace period active! " + 
                    api.getRemainingTime() + "s remaining");
            }
        }
    }
}

Plugin Dependency

To use the API, add SMPGracePeriod as a dependency:

paper-plugin.yml:

dependencies:
  server:
    SMPGracePeriod:
      load: BEFORE
      required: true
      join-classpath: true

plugin.yml (Bukkit/Spigot):

depend: [SMPGracePeriod]

Key Features

• MiniMessage formatting for all messages
• Repeating BukkitScheduler task for countdown
• Event listener for damage blocking
• Proper state validation (can't start if already active, etc.)
• Duration parser supporting flexible time formats
• Thread-safe API for inter-plugin communication