Free Raid Alarm & Raid Alerts (Open-Source) 0.0.7

Updates & Changes
- All of my plugins now include localization support which generates a new /lang folder where you can fully customize the language the plugins display in. This feature allows you to build localization files and trade them or sell them with others for my plugins. This is great if you're running, German, French, EU type gaming servers where the language is different then English. I believe we're the first plugins to build true Localization support.
- Localization is very common to see with Rust and Minecraft plugins but not commonly seen with ArkServerAPI plugins so going forward all my plugins will have this unique feature as I believe it's a huge quality of life feature.

• Added "SenderName: XXX" support to all my plugins. You can now customize your plugins configuration files to have better control over how the chat messages are displayed in-game.
• Huge Update: I added official support to use Pelayori's ASA Ulities mod! You now have new configuration options such as:

JSON:Copy to clipboard

  "ApiUtilsMod": {
    "Enabled": true,
    "BackdropColor": [0.0, 0.0, 0.0, 0.55],
    "ScreenPosition": "Center",
    "TextAlign": "Center",
    "TextScale": 1.0,
    "MessageSeconds": 6.0,
    "AlsoShowInChat": true
  }

these new options let you control if you want to use the mod, I've also coded a failsafe so in the event you don't have the mod loaded it'll detect that and fallback to native support instead of causing a server crash. Huge shoutout to Pelayori for making the mod and assisting me in Discord on how to integrate it!

• Unicode support has been added, I've added several Unicode support such as UTF-8 and more to support foreign languages and other special ALT characters. Please be aware some characters like Chinese characters may still break but this is a huge upgrade from before.
• Fixed a bug where reload command was silently failing in some occasions. Thank you to DWS for reporting this bug on our Discord server!
• Updated the comment_config.json file to now use the .jsonc format this prevents issues with users trying to load the wrong config file and is proper syntax.
• Fixed several other various bugs reported

New Features:

• Several users in discord and in forum thread have requested the ability for tribes and players in-game to be able to setup their own discord webhooks, I've added this feature with a ton of customization options.
• Permissions are now added so all commands can be fine tuned and control setup of who and what group in-game can use the commands. This is great for setting up VIP systems.
• Added tier system exclusively for servers who want to monetize the plugin in their own webstores. Alot of customization options for tiers is added to the config.
• I've added server name control in all my plugins now this lets you detect custom parms inside your Server Startup and it tells the plugin what config to use for discord webhooks and such. Great way to use same config on all your server maps without having to edit each config per map basis.

Spoiler: Configuration Example

JSON:Copy to clipboard

{
  // A guided tour of RaidAlarm's config.json. The notes below make it fail as JSON, so put your
  // real changes in config.json and keep this one just for reading.
  //
  // What RaidAlarm does now: it still watches your structures and sounds the alarm when somebody
  // starts breaking them. New in this build, a player or a whole tribe can point that alarm at a
  // Discord channel of their own, so they get woken up when their base is hit at 3am. Your own
  // webhook still sees everything.

  // Language: which language file RaidAlarm reads its in game and command text from. It points at a
  // file in the lang folder next to this config, so "en" reads lang/en.json and "de" reads lang/de.json.
  // Ship lang/en.json is always there. To add your own, copy lang/en.json to lang/<code>.json, change
  // only the text on the right of each line, keep every {} in place, then set Language to that code.
  // If you pick a code with no matching file, RaidAlarm just falls back to English, so it never goes blank.
  "Language": "en",

  // LangAutoFill: tops your language file up after an update.
  // A new build usually brings a few new lines. Your file will not have them, so with
  // this on I add just the missing ones and leave everything you wrote exactly as it
  // is. I save a .bak of your old file before I write anything.
  // Your server never breaks without this, since a missing line falls back to my
  // built in English. It only saves you from working out what is new by hand.
  // Turn it off if you would rather I never wrote to your files.
  "LangAutoFill": true,

  // SenderName: the name shown in front of my chat lines.
  // Leave it empty and the game prints its normal (SERVER): line. Put any name in and I use that
  // instead. You can drop {map} or {server} into it, so "Watchman on {map}" reads as "Watchman on
  // The Island". This only touches chat lines, never the on screen box.
  "SenderName": "",

  "General": {
    // Debug: turns on the detailed log.
    // With this on I write to ArkApi.log every time I take or refuse a webhook and why, every
    // permission answer, every rank I work out, every post I send and every failure that comes back.
    // Leave it off day to day so the log stays short. Turn it on for an hour when something is wrong.
    "Debug": false
  },

  "Commands": {
    // AlarmCMD: the chat command players type to set up their own alarm.
    // Change it if it clashes with another plugin. Set it to "" and the whole player side goes away,
    // which leaves RaidAlarm working exactly like the old one webhook version.
    "AlarmCMD": "/raidalarm"
  },

  "RaidAlarm": {
    // BatchSeconds: how long I wait after the very first hit before the first alarm goes out.
    // Smaller means a faster warning and more posts. Bigger means one calmer post that already
    // knows how bad it is. 60 suits most servers. Below 10 and a neighbour swinging a pick at your
    // wall will wake the tribe up. A rank in Tiers below can give some players a shorter wait.
    "BatchSeconds": 60,

    // MinHitsToAlert: how many hits a base takes before I say anything at all.
    // Bigger keeps a single accidental hit quiet. Smaller warns on almost anything.
    // At 5 a stray hit is ignored but a real attack still gets through in seconds.
    "MinHitsToAlert": 5,

    // IgnoreSelfDamage: stay quiet when a tribe is knocking down its own build.
    // Almost everyone wants this true. Set false only if you want to see every hit, including
    // somebody demolishing their own base.
    "IgnoreSelfDamage": true,

    // PlayerAttackersOnly: only a real player attacking counts.
    // True means a wild dino chewing a fence raises nothing. False means wild animals set the
    // alarm off too, which on a busy map is a lot of noise.
    "PlayerAttackersOnly": true,

    // LogCoords: work out the map coordinates of the raid and put them in the alarm.
    // True is what most people want, since it tells a defender where to go. Set false if you would
    // rather not put the position of a fight into a channel.
    "LogCoords": true,

    // WarnOnlineTribe: also shout at any tribe member who is online right now, in game.
    // The Discord alarms go out either way. Turn it off if you only want Discord.
    "WarnOnlineTribe": true,

    // PingEveryRaid: put an @here on the alarm that goes to YOUR webhook.
    // This never applies to a channel a player or a tribe set up. Their own tag setting handles that,
    // and @everyone and @here are never allowed from a player.
    "PingEveryRaid": true,

    // MinTeamId: ignore any structure whose tribe id is this number or lower.
    // 0 is right for almost everyone. Raise it only if odd unowned builds keep setting the alarm off.
    "MinTeamId": 0,

    // BreachHits: how many hits before I stop calling it a raid and call it a breach.
    // A breach is loud. It posts a fresh red message with the tag on it, even if a quiet running
    // update was already going. Bigger means it takes more damage before you get the second buzz.
    "BreachHits": 250,

    // BreachMinutes: or how many minutes of steady damage before I call it a breach.
    // Whichever of these two happens first wins. Set either to 0 to switch that half off.
    "BreachMinutes": 10,

    // RaidOverSeconds: how long with no hits at all before I decide the raid is finished.
    // Bigger means a raider stopping for a drink does not end it early. Smaller wraps up sooner.
    // 300 is five minutes.
    "RaidOverSeconds": 300,

    // UpdateSeconds: while a raid is still running I edit the same Discord message this often with
    // the new count. Smaller is more up to date and uses more calls on that channel.
    // Do not go under 15 or Discord will start slowing you down.
    "UpdateSeconds": 60,

    // LiveMessage: make a raid ONE Discord message that keeps changing, instead of a stream of them.
    // This is the nicest part of the build. An edit is quiet, so your phone only buzzes when the
    // raid actually gets worse. Set false if you would rather have a separate post per update.
    "LiveMessage": true,

    // PostRecap: edit the message one last time when the raid stops, with how long it ran and how
    // many hits it took. Set false to leave the last running update as the final word.
    "PostRecap": true
  },

  // Routes: everything about letting players and tribes point alarms at their own Discord.
  "Routes": {
    // Enabled: the master switch for the whole player side.
    // Set false and RaidAlarm goes back to exactly how it was before: one alarm, to your webhook,
    // no player commands, no database. Nothing else in this block matters when it is false.
    "Enabled": true,

    // AllowedHosts: the only sites I will ever call.
    // I match the site name exactly, so "discord.com.something.else" and "my-discord.com" are both
    // refused on this line. Leave this alone unless you really know what you are doing. Adding a
    // site here means your game server will make a web call to it when somebody's base is hit.
    "AllowedHosts": ["discord.com", "discordapp.com", "canary.discord.com", "ptb.discord.com"],

    // AllowThreads: let a player put ?thread_id=NUMBER on the end of their webhook so their alarms
    // land in one thread. Off by default, because anything tacked on the end of a link is worth
    // being careful with. Nothing else is ever allowed on the end, even with this on.
    "AllowThreads": false,

    // MaxUrlLength: the longest webhook link I will take.
    // A real Discord webhook is well under 200. Raising this does not help anybody.
    "MaxUrlLength": 200,

    // ConfirmMinutes: when somebody sets an alarm I post a short code into their channel and they
    // have to type it back in game. This is how many minutes that code lives.
    // Bigger is friendlier for somebody who has to go and look at their phone. Smaller is tidier.
    // The code is why a typo in a webhook can never quietly send your base coordinates to a stranger.
    "ConfirmMinutes": 10,

    // KeeperStaleDays: the first tribe member to set the tribe alarm looks after it, and only they
    // can change it. If they have not been seen for this many days, anybody in the tribe can take
    // it over. Bigger locks it to one person for longer. Set 0 and it never goes stale, which means
    // a tribe whose keeper quits has to ask staff.
    "KeeperStaleDays": 30,

    // HandoverHours: when a tribe alarm moves to a new channel, the OLD channel keeps getting
    // alarms for this many hours.
    // This is the thing that stops somebody joining a tribe as a spy, quietly moving the alarm to
    // their own channel, and raiding a tribe that has gone deaf. Every change is also announced to
    // the whole tribe in game and posted in both channels. Set 0 to switch the grace off.
    "HandoverHours": 24,

    // HardStrikesToDrop: how many hard failures in a row before I give up on a channel and switch
    // it off. A hard failure is Discord telling me that webhook is gone. A network hiccup or a
    // slow down never counts. Smaller gives up faster, bigger keeps trying a broken channel longer.
    "HardStrikesToDrop": 3,

    // HeartbeatDays: every this many days I post a quiet "still on watch" line into each channel.
    // It is worth more than it looks. Without it, a channel that has been silent for a month could
    // mean a quiet month or a dead alarm, and nobody finds out which until the night it matters.
    // Set 0 to switch it off. A rank in Tiers below can set its own number.
    "HeartbeatDays": 7,

    // MaxMuteMinutes: the longest a player can mute their own alarm in one go.
    // 720 is twelve hours. This stops somebody muting themselves for a year by mistake.
    "MaxMuteMinutes": 720,

    // QuietBlocksAll: during a player's quiet hours I normally still get through for a real breach.
    // Set true and quiet hours block everything, even a breach.
    "QuietBlocksAll": false,

    // FastBatchSeconds: the alarm window for anybody holding the RaidAlarm.Fast permission node.
    // Smaller means a VIP hears about a raid sooner than everybody else. This is an easy thing to
    // sell, and it takes nothing away from a free player.
    "FastBatchSeconds": 10,

    // SetCooldownSeconds: how long a player waits between setting alarms.
    // Bigger is safer, smaller is friendlier to somebody fixing a typo.
    "SetCooldownSeconds": 30,

    // TestCooldownSeconds: how long a player waits between test rings.
    "TestCooldownSeconds": 60,

    // MaxPostsPerTick: how many Discord posts I am allowed to start each second.
    // Every post runs on its own thread, so this is the setting that stops a big raid across many
    // tribes from making a pile of threads at once. Bigger clears a backlog faster and costs more.
    "MaxPostsPerTick": 4,

    // MaxInFlight: how many posts may be waiting for an answer at the same time.
    "MaxInFlight": 8,

    // MaxQueued: the most posts I will hold in the queue.
    // Past this I start dropping the quietest ones and say so once in the log. Losing an alarm line
    // is the right trade. Running the server out of memory is not.
    "MaxQueued": 500,

    // TierCacheSeconds: how long I remember what rank a player is before asking Permissions again.
    // Bigger is lighter on Permissions. Smaller picks up a rank change sooner. 300 is five minutes.
    "TierCacheSeconds": 300,

    // KeepCallsDays: how many days I keep the record of every alarm I sent.
    // This is what lets you answer "my alarm never went off" weeks later. Set 0 to keep no record.
    "KeepCallsDays": 30
  },

  // Show: what goes IN the alarm, for each kind of channel.
  // "Server" is your own webhook. "Tribe" is a channel a tribe set up. "Player" is a channel one
  // player set up for themselves. A player can hide things from their own channel but never add
  // something you have switched off here.
  "Show": {
    "Server": {
      // Your own channel sees everything by default. It is your server.
      "Attacker": true,
      "AttackerTribe": true,
      "Coords": true,
      "Hits": true,
      "Online": true
    },
    "Tribe": {
      // Attacker: read this one before you change it.
      // This decides whether a tribe is told WHO is hitting them while they are asleep. The base
      // game never tells anybody that. Turning it on hands defenders real information they would
      // not otherwise have, and it changes how raiding feels on your whole server.
      // Leave it false on a serious PvP server. Turn it true on PvE, or on a friendly server where
      // everybody knows each other anyway.
      "Attacker": false,

      // AttackerTribe: same idea, but the raider's tribe name instead of their player name.
      "AttackerTribe": false,

      // Coords: where the hits are landing. This is the tribe's own base, so it is on by default.
      "Coords": true,

      // Hits: how many hits have landed so far.
      "Hits": true,

      // Online: how many of their tribe were online when it happened.
      "Online": true
    },
    "Player": {
      // The same list again for one player's own channel. The same warning applies to Attacker.
      "Attacker": false,
      "AttackerTribe": false,
      "Coords": true,
      "Hits": true,
      "Online": true
    }
  },

  // Tiers: ranks. "Default" is everybody. Every other name here is a Permissions GROUP name, so
  // "vip" means anybody in the vip group in Permissions. A player in more than one group gets the
  // best one. If you have no Permissions installed, everybody is on Default.
  "Tiers": {
    "Default": {
      // Lines: how many alarms a player may keep, and the one number that makes this a VIP perk.
      // It ships at 1, so a normal player gets one free alarm and the plugin feels generous out of
      // the box. Set it to 0 and nobody gets an alarm at all unless they are in one of the groups
      // below. That single change is how you turn this whole feature into something you sell.
      "Lines": 1,

      // BatchSeconds: how many seconds after the first hit their alarm goes off.
      // A bigger number here next to a smaller one in vip is what makes the VIP rank worth having.
      "BatchSeconds": 60,

      // Mention: whether they may tag themselves or a role on the post.
      // A tag is what makes a phone actually buzz, so this is the most wanted line on the list and
      // the easiest one to hold back for a paying rank.
      "Mention": false,

      // Quiet: whether they may set quiet hours.
      "Quiet": false,

      // Recap: whether they get the wrap up post when the raid ends.
      "Recap": false,

      // HeartbeatDays: their own "still on watch" post, in days. 0 means they get none.
      "HeartbeatDays": 0
    },
    "vip": {
      "Lines": 2,
      "BatchSeconds": 30,
      "Mention": true,
      "Quiet": true,
      "Recap": true,
      "HeartbeatDays": 7
    },
    "vip2": {
      "Lines": 3,
      "BatchSeconds": 10,
      "Mention": true,
      "Quiet": true,
      "Recap": true,
      "HeartbeatDays": 3
    }
  },

  "Permissions": {
    // Enabled: set false and I never ask Permissions anything. Everybody gets the Default rank.
    "Enabled": true,

    // Strict: read this one too, because it works the opposite way round to what you might guess.
    // Normally, if Permissions is not installed, I let everybody through, so the plugin still works
    // on a plain server with nothing else on it. That is the wrong answer if you wanted alarms to be
    // VIP only, because a missing Permissions.dll would quietly open the feature up to everyone.
    // Set this true and a missing or unreadable Permissions means NOBODY can set up an alarm, and I
    // say so loudly in the log once at boot. Only set it true if Permissions is installed and working.
    "Strict": false,

    // UseNode: may use the chat command at all.
    "UseNode": "RaidAlarm.Use",

    // PersonalNode: may set an alarm for themselves.
    "PersonalNode": "RaidAlarm.Personal",

    // TribeNode: may set the alarm for their whole tribe.
    "TribeNode": "RaidAlarm.Tribe",

    // MentionNode: may tag themselves or a role, so the post buzzes a phone.
    "MentionNode": "RaidAlarm.Mention",

    // QuietNode: may set quiet hours.
    "QuietNode": "RaidAlarm.Quiet",

    // FastNode: gets the short window from Routes.FastBatchSeconds above.
    "FastNode": "RaidAlarm.Fast",

    // AdminNode: staff. This one always fails shut, so nobody ever gets it by accident, not even on
    // a server with no Permissions. It lets somebody change or clear a tribe alarm that is not theirs.
    "AdminNode": "RaidAlarm.Admin"
  },

  // Database: where the alarm routes live so they survive a restart.
  "Database": {
    // UseMySQL: false uses SQLite, which needs no setup at all and writes one file into my data
    // folder. True uses MySQL. On a cluster you want MySQL, because then a tribe sets their alarm
    // once and every map on the cluster uses it.
    "UseMySQL": false,

    "Host": "",
    "Port": 3306,
    "User": "",
    "Password": "",
    "Database": "",

    // TableName: I make two tables out of this name, one for the routes and one for the record of
    // alarms sent. With "raidalarm" you get raidalarm_lines and raidalarm_calls.
    "TableName": "raidalarm",

    // SQLiteDatabasePath: leave it empty and the file goes in my data folder, which is where you
    // want it. Put a full path here to keep it somewhere else.
    "SQLiteDatabasePath": ""
  },

  // Server: which server this is. One config file can go to every map on a cluster and each map
  // will still name itself correctly.
  "Server": {
    // Name: set this and it wins over everything else. Leave it empty on a cluster.
    "Name": "",

    // NameFromParams: if Name is empty I read the launch line and take the first one of these I
    // find. If you already run ArkShop you almost certainly have -serverkey= on there, so this
    // works with no launch line change at all.
    "NameFromParams": ["-ServerName=", "-serverkey=", "-clustermap=", "?SessionName="],

    // UseSessionName: reading the session name out of the running game needs an extra game symbol,
    // and a game patch that renames it would stop the server. The launch line and the map name
    // cover nearly everyone, so leave this off unless you really need it.
    "UseSessionName": false,

    // Id: only needed if two of your maps end up with the same name. Give each one a short id here.
    "Id": ""
  },

  "Discord": {
    // Enabled: set true and fill in WebhookURL to get alarms in your own channel.
    // Player and tribe alarms need this on too, since it is the same sending machinery.
    "Enabled": false,

    // WebhookURL: your channel. Make one in Discord under Channel Settings, then Integrations,
    // then Webhooks. This one is yours and it sees every raid on the server.
    "WebhookURL": "",

    // AlertWebhookURL: where the odd stuff goes, such as a player alarm that stopped answering.
    // Leave it empty and that goes to WebhookURL instead.
    "AlertWebhookURL": "",

    // Username: the name my posts appear under in Discord.
    "Username": "RaidAlarm",

    // ServerName: your server name. It goes in the small print at the bottom of every post.
    "ServerName": "My ARK Server",

    // Speaker: on a cluster, pin which map speaks for the whole cluster. Put the name that map
    // works out for itself. Leave it empty and every map speaks for itself, which is right for a
    // single server.
    "Speaker": "",

    // Posts: which of my posts go out from every map, and which go out once for the whole cluster.
    // "all" means every map posts. "speaker" means one map posts for all of them. "off" means
    // nobody posts that kind.
    // This only ever applies to YOUR webhook. A tribe or player channel is always treated as "all",
    // because a tribe raided on one map has to hear about it from that map.
    "Posts": {
      "Boot": "speaker",
      "Raid": "all",
      "Recap": "all",
      "RouteChanged": "all",
      "RouteDead": "all",
      "Heartbeat": "speaker"
    }
  },

  // ApiUtilsMod: the free ASA API Utils mod draws my in game warnings as a proper box on screen
  // instead of a plain chat line. The mod is a nice extra, never a must have. Without it everything
  // still works, the warnings just look plain.
  "ApiUtilsMod": {
    // Enabled: set false and I always use plain chat lines.
    "Enabled": true,

    // BackdropColor: the box colour behind the words, as red, green, blue, and how solid it is.
    // Each number runs 0.0 to 1.0. The last one is the one worth playing with.
    "BackdropColor": [0.0, 0.0, 0.0, 0.55],

    // ScreenPosition: where the box sits. "Left", "Center" or "Right".
    "ScreenPosition": "Center",

    // TextAlign: how the words sit inside the box. "Left", "Center" or "Right".
    "TextAlign": "Center",

    // TextScale: how big the words are. 1.0 is normal, 1.5 is half again as big.
    "TextScale": 1.0,

    // MessageSeconds: how long the box stays up. Bigger keeps it on screen longer.
    "MessageSeconds": 6.0,

    // AlsoShowInChat: when true I also send a real chat line, so the warning stays in the chat log
    // after the box fades. That does mean two messages per warning.
    "AlsoShowInChat": true
  },

  "MapName": {
    // Pretty: the game calls The Island "TheIsland_WP". With this on I tidy that up before anybody
    // reads it. Set false to show the raw file name.
    "Pretty": true,

    // Overrides: for a mod map whose file name looks nothing like its real name, put it here.
    // Example: { "Svartalfheim_WP": "Svartalfheim" }
    "Overrides": {}
  }
}

To learn more and get real-time updates join our discord: https://discord.gg/QscWXn62dE