Humanitzbot
Fully featured server admin + community tooling for HumanitZ private servers, including Discord integration, server management tooling, queriable SQL database, native grief prevention metrics.
Install / Use
/learn @QS-Zuq/HumanitzbotREADME
Features
🎮 Discord Integration
| Feature | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | Server Status | Live embed with player count, game day, season, server health, and system resources | | Player Stats | Per-player kill stats, playtime, profession, lifetime records, and progression tracking | | Chat Relay | Bidirectional chat bridge between Discord and in-game with rich formatting | | Activity Log | Real-time feeds for connects, deaths, builds, looting, raids, and PvP kills | | Kill Feed | PvP kill attribution with damage tracking, death cause classification, and death loop detection | | Auto Messages | Welcome messages, Discord link broadcasts, and SFTP-hosted welcome files with leaderboard templates | | Milestones | Automatic announcements when players hit kill milestones | | Recaps | Periodic server summary recaps with trending stats | | Daily Threads | Auto-created daily threads for activity and chat — keeps channels clean | | Status Channels | Voice channel names that display live player count, game day, and season |
🗺️ Web Dashboard
| Feature | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Interactive Map | Leaflet-based world map with live player positions, structures, vehicles, containers, horses, dead bodies, and AI entities | | Timeline Playback | Scrub through historical world snapshots — watch your server evolve over time | | Admin Panel | Server power controls, RCON console, player kick/ban, and game settings editor | | Item Tracking | Fingerprint-based item movement tracking with full custody chains and ownership history | | Activity Feed | Searchable, filterable event history with player attribution | | Chat History | Full searchable chat log with Discord ↔ in-game indicators | | Database Browser | Direct SQL queries against 60+ game data tables | | Clan Viewer | Clan membership, territories, and member details | | Bot Config Editor | Edit bot settings from the browser with live-apply and restart detection | | Module Status | Real-time module health dashboard showing status of all bot subsystems | | Per-Server Config | Per-server game settings, welcome messages, and auto-message configuration from the Servers tab | | Server Scheduler | Visual restart schedule with profile rotation | | Discord OAuth2 | Role-based access tiers: public landing, survivor, mod, admin | | Multi-Language | Full i18n support — English, 繁體中文, 简体中文 with browser language detection and instant switching |
⚙️ Server Management
| Feature | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| Multi-Server | Manage multiple game servers from one bot — each gets its own DB, RCON, stats, and modules |
| PvP Scheduler | Automatic PvP on/off at scheduled hours via settings file edit + server restart with countdown warnings |
| Server Scheduler | Timed restarts with profile rotation, per-profile setting overrides, and daily/weekly schedules |
| SFTP Auto-Discovery | Automatically finds game files on your server — no manual path config needed |
| Panel API | Pterodactyl panel integration for hosted servers (Bisect, etc.) — power controls, file API, WebSocket RCON |
| Env Sync | Automatic config migration — .env values auto-migrate to SQLite DB on first boot, with backup |
| CLI Setup | First-run setup via npm run setup — SFTP auto-discovery, data import, and validation |
| Save Parser | Full binary .sav file parser — extracts players, structures, vehicles, containers, companions, world state |
| Snapshot Service | Periodic world state snapshots for timeline playback and historical analysis |
| Diff Engine | Tracks changes between save file parses for activity detection and item movement |
Quick Start
Prerequisites
- Node.js 18+ (22+ recommended)
- A HumanitZ dedicated server with RCON enabled
- SFTP access to the server (password or SSH key)
- A Discord bot application
Installation
git clone https://github.com/QS-Zuq/humanitzbot.git
cd humanitzbot
npm install
Configuration
cp .env.example .env
Fill in the required values:
| Key | Description |
| ------------------- | ---------------------- |
| DISCORD_TOKEN | Your bot token |
| DISCORD_CLIENT_ID | Discord application ID |
| DISCORD_GUILD_ID | Your Discord server ID |
All other settings (RCON, SFTP, channels, toggles, etc.) can be configured in .env or via the Web Dashboard. Settings are stored in the SQLite database.
Language / Locale
The bot language is configured via the Web Dashboard. The web dashboard detects your browser language automatically and can also be switched manually via the language selector in the bottom-left corner.
First Run
npm run setup
This will:
- Connect to your game server via SFTP
- Auto-discover file paths (saves, logs, settings)
- Download initial data and seed the SQLite database
- Deploy Discord slash commands
Start
npm start
Development mode with auto-restart:
npm run dev
Web Dashboard
The dashboard runs on port 3000 by default (WEB_MAP_PORT in .env).
Public Landing Page
The landing page is accessible without authentication and shows:
- Server status (online/offline, player count, game day)
- Connect info and Discord invite
- Multi-server overview
Discord OAuth2 Authentication
For the full dashboard with role-based access:
DISCORD_OAUTH_SECRET=your_oauth_secret
WEB_MAP_CALLBACK_URL=https://your-domain.com/auth/callback
WEB_MAP_SESSION_SECRET=a_random_secret_string
Access Tiers: | Tier | Access | |------|--------| | Public | Landing page, server status | | Survivor | Map, player list, activity feed, chat history | | Mod | Kick players, send RCON
Related Skills
feishu-drive
349.9k|
things-mac
349.9kManage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database)
clawhub
349.9kUse the ClawHub CLI to search, install, update, and publish agent skills from clawhub.com
postkit
PostgreSQL-native identity, configuration, metering, and job queues. SQL functions that work with any language or driver
