HCMCS: Hardcore Minecraft Discord Bridge
Minecraft server manager that spawns real-time world maps and status displays in Discord voice channels, complete with adaptive rate-limiting orchestration.
A full-featured Discord bot that runs alongside a Fabric Minecraft server, generating minimap PNGs from Minecraft region files, posting rich event notifications (player deaths with emoji-coded causes, advancements, joins), and maintaining live Discord voice channels that display player count, world name, and server status with sophisticated backoff handling for Discord's aggressive rate limits.
- Node.js
- JavaScript (ES6)
- Discord.js 14
- Docker
- Docker Compose
- SQLite3
- Fabric MC 1.21.8
- Zlib/Gzip compression
- PNG.js
- Regex pattern matching
HCMCS is a Minecraft server orchestrator designed for hardcore multiplayer worlds. It ingests the server's console output in real time, parses 60+ death message patterns to categorize player deaths by cause (combat, fall, lava, wither, void, dragon, etc.), and pushes beautiful rich embeds to a Discord feed with contextual color coding and player head/body renders via Crafatar. The system also manages SQLite tables tracking player stats (survival time, advancements, deaths, session history), world metadata, and per-session survival records.
The bot's standout feature is its minimap generator (spawn_map.js), which reads Minecraft's region (.mca) files directly, decompresses them with zlib/gzip, decodes chunk NBT structure, ray-casts from top to bottom to find the first solid block, and renders the result as a PNG with optional topographic shading (controllable light azimuth, altitude, height exaggeration). This runs as a separate script and outputs a world_minimap.png artifact. Deployment is Docker-driven via docker-compose, hosting a Fabric 1.21.8 server with 30+ performance and structure mods (C2ME, Lithium, Ferrite Core, biome/structure generators) on hardcore difficulty.
The Discord integration handles three dedicated status channels (player count, world name, server status) via voice channel name updates—a clever trick to display live data without requiring text permissions. To solve Discord's 2-changes-per-10-minutes rate limit per channel, I built an adaptive backoff system: starts at 5s update intervals, escalates by 5s on each 429 error (up to 60s max), and de-escalates on success. Each channel has independent backoff state, preventing one from blocking others. The system also maps 15+ server lifecycle states (offline, initializing, loading, joinable) down to 3 Discord statuses (🔴 Offline, 🟡 Preparing, 🟢 Online) to minimize unnecessary updates.
- Minimap PNG generator that decodes Minecraft region files, ray-casts to surface, applies topographic shading with configurable light azimuth and height exaggeration; supports chunk-filling strategies (neighbor-copy, averaging, nearest-search) for incomplete world data
- Graceful Discord rate-limit handling via independent-per-channel adaptive backoff: 5s base interval, +5s on 429 error (max 60s), -5s on success (min 5s), resets to 5s if no change needed
- 60+ death message regex patterns with categorization into 12 distinct causes (combat ⚔️, fall 🪂, lava 🌋, dragon 🐉, wither 💀, void 🕳️, sonic 📢, magic ✨, etc.), each with emoji-coded Discord embeds and player head/body thumbnails
- SQLite schema with 20 tables tracking player UUIDs, per-world and global stats (survival time, advancement/death counts, session history), per-cause death summaries, and persistent Discord channel IDs for status displays
- Robust log parsing with 15+ regex patterns for server lifecycle, player joins/leaves/chat/deaths/advancements, with stateful heartbeat sync (/list) to reconcile active players and suppress historical log lines on reattach