🚨 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
| Feature | Details |
|---|---|
| 🔴 Rocket/Siren Alerts | Full-screen title + red chat — city-targeted only |
| 🟡 Pre-Warnings | Yellow chat (everyone) + actionbar (your city) |
| 🟢 Incident Ended | Green chat broadcast to all players |
| 🏙️ City Selection GUI | Browse & search all Israeli cities |
| 🌐 Bilingual | Hebrew & English per-player toggle |
| 💾 Persistent History | Alerts survive server restarts (up to 200 stored) |
| 📺 Holograms | In-world TextDisplay boards with recent alert history |
| 📣 Social Safety System | Clickable "I'm safe" broadcast after sirens |
| 🔌 PlaceholderAPI | Expose alert data to scoreboards, tab lists, etc. |
🔴 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.
| Hebrew | English Translation |
|---|---|
| ירי רקטות וטילים | Rocket Fire |
| חדירת כלי טיס עוין | Hostile Aircraft Infiltration |
| חדירת מחבלים | Terrorist Infiltration |
| סיום האירוע | Incident Ended |
| התרעה מוקדמת - זיהוי שיגור | Early Warning – Launch Detected |
| הנחיות מצילות חיים | Life-Saving Instructions |
❤️ 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_*%.
| Placeholder | Returns |
|---|---|
%mcalerts_last_title% |
Title of the most recent alert |
%mcalerts_last_areas% |
Affected areas of the most recent alert |
%mcalerts_last_time% |
Timestamp of the most recent alert |
%mcalerts_history_1% |
Full formatted string for alert #1 (newest) |
%mcalerts_history_N% |
Full formatted string for alert #N |
Use these in scoreboards, tab lists, action bar plugins, or any PAPI-compatible plugin.
⚙️ Commands
| Command | Permission | Description |
|---|---|---|
/mcalerts |
— | Open city selection GUI |
/mcalerts history |
— | View last 20 alerts in chat |
/mcalerts testapi |
— | Test endpoint connectivity & last-hour summary |
/mcalerts test <type> |
mcalerts.test |
Stage a test alert (requires confirm) |
/mcalerts confirm |
mcalerts.confirm |
Confirm a pending test broadcast |
/mcalerts clearhistory |
mcalerts.clear |
Wipe all stored alert history |
/mcalerts hologram <create|delete|list> [id] |
mcalerts.test |
Manage in-world alert boards |
/mcalerts safe |
— | Broadcast your safety status (clickable button) |
🧪 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.ilor 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.
