mamba.TorchDiscordSync

An advanced Space Engineers Torch server plugin providing deep Discord integration, server automation, and administrative tooling.

Unlike simple chat relays, TorchDiscordSync focuses on deep game integration — tracking accurate kill data, analysing damage sources in real-time, synchronising player factions, and monitoring server health, all driven by a configurable Discord bot.

📋 Table of Contents

1. Feature Overview
2. Smart Chat Relay
3. Secure Faction Chat
4. Faction Synchronisation
5. Advanced Death Analysis
6. Player & Death Location
7. Server Health Monitoring
8. Discord Admin Commands
9. Player Verification System
10. Data Storage (XML / SQLite)
11. Event Logging
12. In-Game Commands /tds
13. Configuration Overview
14. Roadmap & Future Plans
15. Contributing
16. Support

Feature Overview

💬 Smart Chat Relay

Bi-directional chat bridge between the SE server and a configured Discord channel.

• Loop protection — messages injected by the plugin (TDS, Discord, Server author tags) are detected and dropped before they can re-enter Discord.
• Privacy filters — private whispers and internal faction chat are never forwarded to the global channel.
• Bi-directional — Discord users can post messages that are broadcast in-game under the [Discord] prefix.
• Rate limiting — duplicate messages and rapid-fire spam are throttled (configurable delay, default 500 ms).
• Text sanitisation — strips control characters and truncates oversized messages before forwarding.

🔒 Secure Faction Chat

Private, isolated communication channels between SE faction chat and Discord.

• Each faction gets a dedicated Discord text channel inside its own Discord category.
• Messages typed in the SE faction chat are forwarded only to the matching Discord channel — never to the global channel.
• Messages posted in the Discord faction channel are delivered as private in-game messages to all online faction members.
• GameFactionChatId mapping — on first sight the channel ID is persisted for instant lookup on all subsequent messages.

🏴 Faction Synchronisation

Automatically mirrors Space Engineers factions into Discord.

• Creates a Discord role and a set of channels (text + voice + optional forum) per faction.
• Assigns/removes roles from Discord members as players join or leave factions in-game.
• Duplicate prevention — checks for existing roles/channels by name before creating to survive plugin restarts cleanly.
• Undo / rollback — admin:sync:undo <tag> and admin:sync:undo_all remove all Discord artefacts created for a faction and revert the database record.
• Cleanup — admin:sync:cleanup removes orphaned Discord roles/channels that no longer correspond to any known faction.
• Cooldown guard — a 10-second post-undo cooldown prevents a sync from running while Discord's internal cache still shows deleted items.

🎯 Advanced Death Analysis

Sophisticated, multi-layer system to determine the exact cause and context of every player death.

Killer Detection

Damage Tracking

• Hooks directly into SE's IMyDamageSystem.DamageHandler event.
• Maintains a rolling in-memory buffer of recent damage events per player.
• Resolves the real cause of death when the native death event contains ambiguous data.

Death Message Templates

Fully configurable templates in DeathMessages.xml. Four named placeholders are available:

Example templates:

PvP:         "{killer} showed {victim} no mercy with {weapon}"
Turret:      "{victim} walked into {killer}'s {weapon}"
Environment: "{victim} discovered that space has no oxygen"

An example of how the above template would look in the game:

PvP:         "orko showed mamba no mercy with Elite Automatic Rifle on the surface of Mars"
Turret:      "mamba walked into Space Pirates's Interior Turret at the edge of known space"
Environment: "mamba discovered that space has no oxygen in the darkness"

• the location (random location text) is added at the end of the message. The exact coordinate of the event is never shown.

The message on Discord has the same text as the in-game one with the emoticon prefix added:

PvP:         "🔥 orko showed mamba no mercy with Elite Automatic Rifle on the surface of Mars"
Turret:      "⚡ mamba walked into Space Pirates's Interior Turret at the edge of known space"
Environment: "💀 mamba discovered that space has no oxygen in the darkness"

🌍 Player & Death Location

Dynamic, runtime-computed location classification — no hardcoded planet coordinates.

1. All planets in the world are detected at runtime (vanilla and modded).
2. The player's death position is compared against every planet's radius.
3. The nearest planet is selected and its surface/orbit zones are computed dynamically.

Death history is persisted per-player and used to detect kill streaks and retaliation scenarios.

🛡️ Server Health Monitoring

Continuous background monitoring via a configurable timer.

• SimSpeed Watchdog — if simulation speed drops below the configured threshold for longer than the configured window (default 30 s), an immediate alert is posted to the configured Discord admin channel. An alert cooldown prevents spam.
• Player Count — the Discord voice channel name is updated to reflect the current number of online players.
• Startup grace — no SimSpeed alerts are fired during the initial startup phase to avoid false positives.

⚙️ Discord Admin Commands

A dedicated Discord channel acts as a remote admin console. Post !tds <subcommand> in the configured admin bot channel to execute any admin command without logging into the game.

Flow: channel + author validation → ⚙️ Executing… acknowledgement → command execution → result embed (success / error / info).

✅ Player Verification System

Securely links a Space Engineers SteamID to a Discord UserID via a one-time code exchange.

Flow:

1. Player types /tds verify @DiscordUsername (or Discord UserID) in-game.
2. Plugin looks up the Discord user, generates an 8-character random code, stores it with an expiry timestamp, and sends it as a Discord DM.
3. Player opens the Discord DM and replies !verify <CODE> to the bot.
4. Bot validates the code, marks the player as verified, and assigns the configured Discord role.

💾 Data Storage (XML / SQLite)

XML (default)

Zero external dependencies. Separate XML files per data type (factions, players, verifications, events). Automatic serialisation via DatabaseService.

SQLite (opt-in)

Enable with config.DataStorage.UseSQLite = true (automatically enabled when the DLLs are present).

⚠️ Installation note: SQLite.Core.dll is a mixed-mode assembly and must not be placed in the plugin folder. Place the DLLs in the Torch server root:

TorchServer\
  ├── System.Data.SQLite.dll       ← managed wrapper
  └── x64\
      └── SQLite.Interop.dll       ← native SQLite engine

Download from: https://system.data.sqlite.org
Package: sqlite-netFx48-binary-bundle-x64-2013-1.0.118.0.zip

If the DLLs are absent, the plugin falls back to XML automatically without error.

📋 Event Logging

Structured log entries are written to the local database (XML or SQLite) and, optionally, to a Discord staff log channel (config.Discord.StaffLog channel ID).

Logged event types include: VerificationAttempt, VerificationDeleted, UnverifyCommand, AdminCommand, CommandError, and more.

🎮 In-Game Commands /tds

All commands are entered in global game chat. The plugin consumes them before they reach Discord.

Player Commands

Admin Commands

⚙️ Configuration Overview

Configuration files are loaded from the plugin's data directory on startup and can be hot-reloaded with /tds reload.

Key settings:

🗺️ Roadmap & Future Plans

Raid Alerts (Offline Protection)

Dependency: SQLite (already implemented)
Notify faction members via Discord DM/ping when their base takes damage while they are offline. High-frequency damage events require SQLite throughput to avoid impacting SimSpeed.

Leaderboards & Statistics

Weekly and monthly PvP rankings generated from accumulated kill data: K/D ratios, Most Active Faction, Top Ace Pilot, kill streak records.

Bounty / Retaliation System

Building on the existing retaliation-detection logic — players place bounties on others, tracked in the database and announced on Discord.

Discord-Driven Economy Readout

Display live in-game economy data (credits, contracts, market prices) via the Discord admin console.

Scheduled Server Announcements

Configurable recurring Discord embeds (rules, event notices, maintenance windows) posted on a CRON-like schedule.

Faction War & Territory Tracking

Detect sustained PvP between faction grids and post live "War Status" updates to Discord.

Web Dashboard (long-term)

A lightweight read-only web panel fed by SQLite: live stats, faction standings, kill history, verification status — no Discord required.

Multi-Server Support

Route one Discord bot across multiple Torch instances with per-server channel configuration.

🤝 Contributing

Pull requests are welcome.
Please maintain compatibility with C# latest / .NET Framework 4.8.
All code comments must be in English.

☕ Support

If you like this project and want to support development:
Buy Me a Coffee ☕