Paid - Cousin Tribe Log Relay

# Cousin_TribeLogRelay

An ARK: Survival Ascended server plugin that lets each tribe configure a Discord webhook using an in-game chat command. Every time the game generates a tribe log entry (kills, raids, tames, etc.) it is automatically relayed to the tribe's Discord channel as a rich embed.

---

## Features

Per-tribe Discord webhook — each tribe sets its own webhook independently
Live tribe name — always fetches the current tribe name, so renames are reflected automatically
Log filter — tribes choose how much noise they want:

- all — every tribe log entry (default)
- kills — only kill and destruction events
- raids — only base/structure destruction events

@everyone Discord ping — when filter is kills or raids, the bot sends an @everyone (or @here) ping alongside the embed. Enabled by default per tribe; any authorised player can toggle it with /tribelogs mention <on|off>. The mention text is globally configurable (MentionText in config.json).
Flexible permission model — three modes available (see [Permission Model](#permission-model)):

- Default: tribe admin check (IsTribeAdmin())
- Group-based: Permissions plugin group membership
- Node-based: granular per-command permission nodes (tribelogs.set, tribelogs.remove, etc.)

Message batching — events are buffered per tribe for a configurable window (default 3 s) and sent as one Discord message with counts: - 50x Your Metal Foundation was destroyed by Cousin!
Discord rate-limit handling — detects x-ratelimit-remaining and retry_after headers and backs off automatically per-tribe
Persistent retry queue — failed log entries (e.g. server internet blip) are stored in SQLite/MySQL and re-sent on the next plugin reload
Masked webhook URL — the /tribelogs status command shows only the last 8 characters of the URL so the token is never exposed in chat
Zero-downtime reload — Cousin_TribeLogRelay.Reload console/RCON command hot-reloads config without restarting the server
Wipe-day reset — Cousin_TribeLogRelay.WipeAll clears all tribe webhooks and queued logs instantly via console or RCON

---

## Configuration (config.json)

JSON:

{
  "General": {
    "Debug": false,
    "Command": "/tribelogs",
    "OnlyAdminsCanSet": true,
    "SendTestMessageOnSet": true,
    "BotUsername": "ASA Tribe Logs",
    "BotAvatarURL": "",
    "EmbedColor": 16753920,
    "RetryFailedLogsOnReload": true,
    "BatchWindowSeconds": 3,
    "MaxUniquesPerEmbed": 15,
    "MentionText": "@everyone"
  },
  "Messages": { "..." },
  "Permissions": {
    "EnableGroups": false,
    "EnablePermissionNodes": false,
    "Groups": ["Default"]
  },
  "PluginDBSettings": {
    "UseMySQL": false,
    "TableName": "TribeWebhooks",
    "FailedLogsTable": "TribeLogQueue",
    "SQLiteDatabasePath": ""
  }
}

See config-commented.json for a full description of every setting.

### Embed colour

EmbedColor is a decimal colour value. 16753920 = orange.
Use https://www.spycolor.com/ to find values.

---

### 2. Group-based access (moderate)

Requires the Permissions plugin. Set "EnableGroups": true and list group names:

JSON:

"Permissions": {
  "EnableGroups": true,
  "Groups": ["Bronze", "TribeLog"]
}

A player must be in at least one of the listed groups to run set, remove, or filter.

## Database Setup

### Option A — SQLite (default, recommended)

Nothing to do. The plugin creates both tables automatically on first startup inside the plugin folder.

Set "UseMySQL": false and optionally set "SQLiteDatabasePath" to a custom path.

### Option B — MySQL

1. Create an empty database on your MySQL server:

Code:

sql
   CREATE DATABASE TribeLogRelay;

2. Create a user with permissions:

Code:

sql
   CREATE USER 'arkplugin'@'%' IDENTIFIED BY 'yourpassword';
   GRANT ALL PRIVILEGES ON TribeLogRelay.* TO 'arkplugin'@'%';
   FLUSH PRIVILEGES;

3. Update config.json:

Code:

json
   "PluginDBSettings": {
     "UseMySQL": true,
     "Host": "127.0.0.1",
     "User": "arkplugin",
     "Password": "yourpassword",
     "Database": "TribeLogRelay",
     "Port": 3306
   }

4. The plugin automatically creates both tables (TribeWebhooks, TribeLogQueue) on first startup. No manual CREATE TABLE SQL needed.

---
## Player Commands

All commands are typed in the in-game chat.

| Command | Permission | Description |
|---|---|---|
| /tribelogs set <url> | Admin / group / node | Save a Discord webhook for your tribe |
| /tribelogs remove | Admin / group / node | Remove the configured webhook |
| /tribelogs status | Any member | Show webhook status (URL masked) |
| /tribelogs filter <all\|kills\|raids> | Admin / group / node | Set the log filter mode |
| /tribelogs mention <on\|off> | Admin / group / node | Enable or disable @everyone ping (kills/raids only) |
| /tribelogs help | Any member | Print command help |

### Getting a Discord webhook URL

1. In your Discord server, go to Channel Settings → Integrations → Webhooks.
2. Click New Webhook, configure name/avatar, copy the URL.
3. In-game: /tribelogs set https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN

---

## Message Batching

Events that arrive within the same BatchWindowSeconds window (default: 3 seconds) are combined into a single Discord embed. Identical events are counted and shown once:

Code:

Tribe Log
- 50x Your Metal Foundation was destroyed by Cousin!
- 12x Your Metal Wall was destroyed by Cousin!
- 1x Your Rex - Lvl 145 was killed by Cousin!

This prevents Discord rate-limiting during raids and keeps your tribe channel readable. Adjust in config.json:

| Setting | Default | Description |
|---|---|---|
| BatchWindowSeconds | 3 | Seconds to buffer events before posting. Raise for very active servers. |
| MaxUniquesPerEmbed | 15 | Max unique event types per embed. Overflow shown as ... and X more event type(s). |

---

## Filter Modes

| Mode | What gets forwarded |
|---|---|
| all | Every tribe log entry |
| kills | Player and dino deaths only — messages containing "was killed", "killed by", "killed!", "tribe killed" |
| raids | Structure destruction only — messages containing "destroyed", "demolished", "c4 charge", "rocket", "grenade" |

kills and raids are mutually exclusive. Use all if you want both death and destruction events in your Discord channel.

@everyone ping: when the active filter is kills or raids and the tribe's mention toggle is on (default), every Discord message also contains an @everyone notification above the embed. Toggle per tribe with /tribelogs mention <on|off>. To use @here instead, change "MentionText": "@here" in config.json. To disable server-wide, set "MentionText": "". The webhook channel must have the Mention Everyone permission enabled in Discord.

---

## Server / RCON Commands

| Command | Description |
|---|---|
| Cousin_TribeLogRelay.Reload | Reload config.json, refresh webhook cache, retry failed logs |
| Cousin_TribeLogRelay.WipeAll | Wipe day: delete ALL tribe webhooks and queued logs, clear all caches instantly |

Both commands work identically from the in-game server console and via RCON.

WipeAll is designed for wipe day — after running it, every tribe must re-run /tribelogs set <url> to reconnect. No server restart is needed.

---

## Discord Embed Format

When filter is kills or raids with mention enabled (default), the message looks like:

Code:

@everyone
┌─────────────────────────────┐
│ Tribe Log                   │
│                             │
│ Your Rex - Lvl 145 was      │
│ killed by EnemyPlayer!      │
│                             │
│ Tribe: MyTribe │ Time: ...  │
└─────────────────────────────┘

With filter all or mention disabled, the @everyone line is omitted.

---

## Edge Cases Handled

| Scenario | Behaviour |
|---|---|
| Player not in tribe | Command rejected with message |
| Player lacks permission | Specific message shown (node name, group, or "admins only") |
| Invalid webhook URL | Rejected before saving |
| Tribe has no webhook | Hook exits silently (no overhead) |
| Tribe renamed | Live name fetched on every event |
| Discord returns 429 | Per-tribe backoff via DelayExecute, resumes automatically |
| Discord webhook deleted (10015) | Error logged, no retry |
| Network failure | Log queued in TribeLogQueue, retried on next reload |
| Plugin hot-reload | Config re-read, cache refreshed, queued logs retried |
| Permissions DLL not loaded | Graceful fallback to IsTribeAdmin() |

---

Get your licence on my online store for only 19.99$ per year !