📅 WipeCal Plugin

Calendar-based wipe and restart scheduler for Rust servers using Google Calendar.

📖 Description

WipeCal is a Carbon plugin that automatically monitors a Google Calendar ICS feed for upcoming "wipe" and "restart" events. Built with SOLID principles and architecture, it provides reliable server automation with dynamic event monitoring, multi-timezone support, and comprehensive player notifications.

DISCLAIMER: In theory, you should be able to point the url to any remote .ics file, but we've only tested with Google Calendar.

✨ Features

Core Functionality

• 📆 Google Calendar Integration - Seamless ICS feed support (public or private URLs)
• 🔄 Advanced Recurring Events - Full support for daily, weekly, monthly, and yearly schedules
• 📅 Week-of-Month Rules - Handles complex patterns like "1st Thursday" or "last Friday" of each month
• 🌍 Multi-Timezone Display - Shows event times across multiple timezones with intelligent date-change detection
• ⚡ Dynamic Monitoring - Smart interval adjustment based on event proximity (5min → 1sec as event approaches)

Automation & Safety

• ⚠️ Progressive Warnings - Alerts at 10min, 5min, 2min, 1min, 30s, 15s, 10s, then countdown 9-1 seconds
• 💾 Auto-Save Protection - Automatically saves server 10 seconds before any event
• 🔄 Auto Calendar Refresh - Periodically re-downloads calendar to detect schedule changes
• 🛡️ Thread-Safe Operations - Async/await patterns with semaphore protection for data integrity
• 📊 Event Change Detection - Notifies players when scheduled events are modified

Player Experience

• 💬 Smart Chat Monitoring - Auto-responds when players ask about wipes (60s cooldown)
• 🎨 Customizable Colors - Full control over message appearance
• 🌐 Localization Ready - Built-in message key system for multi-language support
• 📱 Informative Commands - View next single event or list of upcoming events

🚀 Installation

1. Download WipeCal.cs and place it in your carbon/plugins folder
2. Restart server or run c.reload WipeCal
3. Edit the generated config at carbon/configs/WipeCal.json
4. Configure your Google Calendar URL (see below)
5. Reload the plugin: c.reload WipeCal

⚙️ Configuration

{
  "Calendar URL": "https://calendar.google.com/calendar/ical/YOUR_CALENDAR_ID/basic.ics",
  "Chat ID": 0,
  "Chat Prefix": "",
  "Message Color": "#e1e5c8",
  "Number Color": "#cd5909",
  "Calendar Refresh Interval (seconds)": 30.0,
  "Timezones": [
    { "Id": "America/Los_Angeles", "Abbreviation": "PST" },
    { "Id": "America/New_York", "Abbreviation": "EST" }
  ]
}

Configuration Options

Option	Description	Default
Calendar URL	Your Google Calendar ICS feed URL	""
Chat ID	Steam64 ID for chat messages (0 = server)	0
Chat Prefix	Prefix for all plugin messages	""
Message Color	Hex color for message text	#e1e5c8
Number Color	Hex color for numbers/highlights	#cd5909
Calendar Refresh Interval	Seconds between calendar updates	30
Timezones	Array of timezone objects for display	See below

Timezone Configuration

Each timezone entry has two properties:

• Id: IANA timezone identifier (e.g., America/Los_Angeles)
• Abbreviation: Display name (e.g., PST, EST)

Common Timezone IDs:

• 🇺🇸 US Pacific: America/Los_Angeles
• 🇺🇸 US Mountain: America/Denver
• 🇺🇸 US Central: America/Chicago
• 🇺🇸 US Eastern: America/New_York
• 🇬🇧 UK: Europe/London
• 🇪🇺 Central Europe: Europe/Paris
• 🇦🇺 Australia Eastern: Australia/Sydney
• 🇯🇵 Japan: Asia/Tokyo

Full IANA timezone list

📆 Setting Up Google Calendar

Step 1: Create Calendar Events

1. Open Google Calendar
2. Create a new event or use an existing calendar
3. Set the title to exactly wipe or restart (case-insensitive)
4. Set the date and time for your event

Step 2: Configure Recurrence (Optional)

Google Calendar supports various recurrence patterns that WipeCal fully understands:

• Daily: Every day at the specified time
• Weekly: Every [day of week] (e.g., "Every Thursday")
• Monthly:
  • Same date each month (e.g., "15th of every month")
  • Week-based (e.g., "1st Thursday of every month")
• Yearly: Anniversary-style events

Example: For a wipe every first Thursday at 3:00 PM PST:

1. Create event titled "wipe"
2. Set time to 3:00 PM
3. Set recurrence to "Monthly on the first Thursday"

Step 3: Get Your ICS URL

1. Go to Calendar Settings (⚙️)
2. Select your calendar from the left sidebar
3. Scroll to "Integrate calendar"
4. Copy either:
   • Secret address in iCal format (recommended - private)
   • Public address in iCal format (if calendar is public)
5. Paste the URL into your WipeCal.json config
6. Reload the plugin: c.reload WipeCal

💻 Commands

Command	Permission	Cooldown	Description	Output
/wipe	All players	5s	Shows next wipe and restart with countdown
/nextwipes	All players	5s	Lists the next 3 upcoming wipes
/nextrestarts	All players	5s	Lists the next 3 upcoming restarts
/refreshcal	Admin (level 2)	5s	Manually refresh calendar from Google

⚙️ How It Works

Architecture

WipeCal uses a modern service-oriented architecture with three main components:

1. 📥 Calendar Service (IcsCalendarService)

   • Downloads ICS files via HTTP with timeout protection
   • Parses VEVENT entries and RRULE recurrence patterns
   • Handles multiple datetime formats and timezone conversions

2. 📊 Event Scheduler (EventScheduler)

   • Processes calendar events and calculates future occurrences
   • Handles complex recurrence rules (daily/weekly/monthly/yearly)
   • Supports week-of-month patterns (e.g., "1st Thursday", "last Friday")
   • Caches next 3 upcoming events of each type

3. 📢 Notification Service (PlayerNotificationService)

   • Formats messages with customizable colors
   • Handles multi-timezone display
   • Manages player notifications and server-wide announcements

Event Monitoring Lifecycle

Server Startup
    ↓
Download Calendar → Parse Events → Calculate Occurrences
    ↓
Cache Next 3 Wipes/Restarts
    ↓
Start Background Monitoring
    ↓
    ├─→ Event Monitor (dynamic interval)
    │   ├─ >1 hour away: check every 5 minutes
    │   ├─ 30min-1hr: check every minute
    │   ├─ 10-30min: check every 30 seconds
    │   ├─ 1-10min: check every 5 seconds
    │   └─ <1 minute: check every second
    │
    └─→ Calendar Refresh (configurable interval)
        └─ Re-download → Detect changes → Update cache

Warning Timeline

When an event approaches:

• 10 minutes: First warning
• 5 minutes: Second warning
• 2 minutes: Third warning
• 1 minute: Fourth warning
• 30 seconds: Fifth warning
• 15 seconds: Sixth warning
• 10 seconds: Save server + warning
• 9-1 seconds: Final countdown
• 0 seconds: Announce event → Kick all players → Quit server

🔧 Advanced Features

Recurrence Rule Support

WipeCal supports the full iCalendar RRULE specification:

Frequency	Example	Result
FREQ=DAILY	Every day at 3pm	Daily wipes
FREQ=WEEKLY;BYDAY=TH	Every Thursday	Weekly on Thursday
FREQ=MONTHLY	15th of every month	Same date monthly
FREQ=MONTHLY;BYDAY=1TH	1st Thursday	First Thursday monthly
FREQ=MONTHLY;BYDAY=-1FR	Last Friday	Last Friday monthly
FREQ=YEARLY	Nov 15th annually	Yearly anniversary

Timezone Intelligence

When displaying times across multiple timezones, WipeCal:

• Shows the full date only when it changes between timezones
• Compacts same-date times for readability
• Uses ordinal suffixes (1st, 2nd, 3rd, 4th, etc.)

Example with date change:

Dec 31st 11:00pm PST
Jan 1st 2:00am EST  ← Date changed

Example without date change:

Dec 15th 3:00pm PST
          6:00pm EST  ← Same date, compact format

Chat Monitoring

WipeCal monitors global chat for the word "wipe" and automatically responds with the next wipe time. This feature:

• Has a 60-second cooldown to prevent spam
• Only triggers on exact word match (case-insensitive)
• Works in global chat only
• Displays time remaining and date information

Dynamic Event Updates

If calendar events change (time moved, event added/removed):

• Plugin automatically detects the change on next refresh
• Resets all warnings for the new event time
• Announces to all players: "Next wipe time has been changed"
• Restarts the event monitoring coroutine

📋 Requirements

• ✅ Carbon Mod installed and running
• ✅ Google Calendar with ICS feed access

💡 Support & FAQ

Q: Does this plugin wipe my server?

⚠️ No! WipeCal only quits your server at the scheduled time. To handle the actual wipe process and bring your server back up, we recommend using wipe-cli. It can ensure your wipe actually happens, stays up to date with Rust and Carbon, and ties into existing infrastructure with its custom script hook system.

Q: Can I use this for restarts only (no wipe)?

✅ Yes! Just create "restart" events instead of "wipe" events. The plugin treats them separately.

Q: What happens if I change an event after the plugin loads?

✅ Automatic! The calendar refreshes every 30 seconds (configurable). Players will be notified of the change.

Q: Can I have multiple recurring schedules?

✅ Yes! Create as many events as needed. WipeCal will calculate all occurrences and show the next 3 of each type.

Q: Does it work with private calendars?

✅ Yes! Use the "Secret address in iCal format" from your Google Calendar settings.

Q: Can I test without restarting the server?

⚠️ Careful! The plugin will execute quit at event time. Use future test dates or the /refreshcal command to update.

🤝 Contributing

This plugin was designed with extensibility in mind. The service-based architecture makes it easy to:

• Add new notification channels (Discord, webhooks, etc.)
• Implement custom recurrence rules
• Extend timezone formatting
• Add new chat commands

---

Made with ❤️ by mainloot | Join our Discord