🚨 MCAlerts — Real-Time Israeli Red Alert Notifications for Minecraft

Never miss a siren again. MCAlerts brings live Home Front Command (pikud ha'oref) rocket and missile alerts directly into your Minecraft server — color-coded, city-targeted, and persistent across restarts.

Built for Israeli players and server owners who don't want to alt-tab during an alert. Fully Hebrew & English bilingual. Zero gameplay interference.

🌟 Features at a Glance

🔴 Alert System — How It Works

MCAlerts polls the official pikud ha'oref API every second and classifies every alert into one of three categories:

🚀 SIREN Alerts — Red

Rocket fire, hostile aircraft, terrorist infiltration, earthquake, Red Alert

• 📺 Full-screen title blasted in the middle of the screen with ⚠ RUN TO SHELTER
• 💬 Red chat message [MCAlerts] Rocket Fire: Tel Aviv
• 🔊 Urgent sound plays
• 🎯 City-targeted only — players who haven't set their city to an affected area won't be disturbed
• ❤️ Safety check-in appears 10 minutes later (Social System, optional)

⚡ PREWARN Alerts — Yellow

Early warning – launch detected, life-saving instructions, minutes to shelter

• 💬 Yellow chat → sent to ALL players on the server (everyone should know)
• 🟡 ActionBar notification → only if your city is in the affected zone
• 🔔 Softer chime sound for city-matched players

✅ ENDED Alerts — Green

Incident ended (סיום האירוע)

• 💬 Green chat → sent to ALL players, no city targeting needed
• No sound, no title — just a calm confirmation

🏙️ City Selection GUI

Run /mcalerts to open the city picker.

• Browse all ~1,200+ Israeli cities loaded live from the government's official city registry
• Search by typing a city name in Hebrew or English
• Global mode — receive alerts for every city in the country (BEACON icon)
• Clear your selection at any time (BARRIER icon)
• Settings and city are saved per-player across sessions

🌐 Bilingual Support

Each player can independently toggle between Hebrew and English via the Language button (BOOK icon) in the city GUI.

❤️ Social Safety System

When a siren alert fires for a player's city, a clickable safety check-in appears in chat 10 minutes later:

[MCAlerts] Are you safe?  [YES, I'M SAFE]

Clicking it broadcasts a server-wide message so everyone knows you're okay. Players can disable this feature per-account via the Sunflower icon in the GUI.

📺 In-World Holograms

Place a live alert board anywhere in your world using TextDisplay entities. Boards auto-update whenever a new alert arrives and color-code each entry by type.

/mcalerts hologram create <id>    — place at your location
/mcalerts hologram delete <id>    — remove it
/mcalerts hologram list            — list all boards

Holograms display the last 10 alerts with timestamps, color-coded 🔴🟡🟢 and formatted for readability. They persist across server restarts.

💾 Persistent Alert History

Every alert is saved to plugins/MCAlerts/alerts-history.json immediately when received. On server restart, the full history is restored — so /mcalerts testapi will correctly show last-hour alert counts even after a reboot.

Up to 200 alerts are retained on disk.

View recent history in chat:

/mcalerts history

🔌 PlaceholderAPI Support

MCAlerts registers a PAPI expansion with the identifier %mcalerts_*%.

Use these in scoreboards, tab lists, action bar plugins, or any PAPI-compatible plugin.

⚙️ Commands

🧪 Test Alert Types

/mcalerts test rocket    — Rocket fire (SIREN, red)
/mcalerts test aircraft  — Hostile aircraft (SIREN, red)
/mcalerts test prewarn   — Early warning (PREWARN, yellow)
/mcalerts test warning   — Life-saving instructions (PREWARN, yellow)
/mcalerts test end       — Incident ended (ENDED, green)

All test alerts require /mcalerts confirm within 30 seconds as a safety gate.

🛠️ Configuration

# config.yml

# Override the alert endpoint — useful if your server IP is outside Israel
# and gets geo-blocked by oref.org.il (HTTP 403)
alert-url: "https://www.oref.org.il/WarningMessages/alert/alerts.json"

# Player data (auto-managed, do not edit manually)
players:
  <uuid>:
    city: "תל אביב - יפו"
    english: false
    social: true

# Hologram locations (auto-managed)
holograms:
  main:
    world: world
    x: 0.0
    y: 64.0
    z: 0.0

🌍 Geo-Block Fix

oref.org.il blocks non-Israeli IP addresses. If your server is hosted outside Israel, you'll see HTTP 403 errors. Set alert-url to a reverse proxy or a self-hosted relay that forwards requests from an Israeli IP.

/mcalerts testapi

Use this command to diagnose connectivity. It will tell you exactly whether your server is blocked, reachable, or if there's an active alert right now.

📋 Requirements

• Paper / Purpur (1.21.X+ recommended, requires TextDisplay API)
• Java 21+
• PlaceholderAPI (optional — enables %mcalerts_*% placeholders)
• Network access to oref.org.il or a proxy relay

⚠️ Spigot works but hologram features require Paper's Display Entity API. Core alert functionality is fully compatible.

🧑‍💻 Credits

frqme — Lead developer, everything you see here

pikud ha'oref (Home Front Command) — The public API this plugin queries. Stay safe 🇮🇱

📜 License

Released under the MIT License. Use it, fork it, self-host it, do whatever you want — just don't sell it as your own.

🚨 MCAlerts is a community safety tool. It relies on the official Israeli Home Front Command API and is not affiliated with or endorsed by the Israeli government.