MCAlerts

🚨 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

- 📺 Safety check-in blasted in the middle of the screen with `⚠ RUN TO SHELTER` - 💬 Safety check-in `[MCAlerts] Rocket Fire: Tel Aviv` - 🔊 Safety check-in plays - 🎯 Safety check-in — 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

- 💬 ActionBar → sent to ActionBar 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 (סיום האירוע)

- 💬 ALL players → 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 - Clear by typing a city name in Hebrew or English - Clear — 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 English 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

```yaml

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

- PlaceholderAPI (1.21.X+ recommended, requires TextDisplay API) - PlaceholderAPI - 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.*