HoR Essentials

• Vintage Story 1.22 Migration
  Full port to VS 1.22 APIs. Retargeted to .NET 10.0. All Harmony patch targets, network messages, and game system calls updated for 1.22 breaking changes.
• Now Universal (Client + Server)
  Previous versions were server-side only. v2.0.0 ships client systems (UI Theme, Block Outline, Handbook rendering) and requires installation on both sides. A separate Watersheds variant is available that omits the two DLLs Watersheds already ships.
• UI Theme System
  Server-synced color themes for game UI elements. Per-player override support, flat UI mode, and corner radius control. Players configure overrides via ModConfig/HoR-Essentials/hor_ui_overrides.json. Server admin sets defaults via HoRUITheme.json.
• Block Outline System
  Fully customizable block selection outline. Configurable color, width, glow intensity, and rainbow/RGB cycling modes. Settings saved per-player to hor_outline_settings.json.
• Custom Handbook System
  Server-defined custom handbook pages and tabs. Admin in-game editor dialog for creating and editing pages without touching files or restarting. Content distributed to clients automatically via a companion content mod folder.
• Notifications System
  Server-to-client toast notifications via HoR-ToastLib. Includes FileSystemWatcher-based signal file support so your external restart daemon can trigger in-game notifications.
• Vanilla Bugfixes
  Harmony patch on SyncedTreeAttribute.FromBytes to suppress NRE crashes from entity listeners firing during deserialization.
• Config Folder Migration
  Config folder renamed from ModConfig/HoRConfig/ to ModConfig/HoR-Essentials/. Automatic migration on first launch.
• Per-Role Teleport Cooldowns & Limits
  Home teleports and teleport requests now support per-role cooldown overrides and per-role home limits with a clean 3-tier fallback system. Server owners can tune teleport convenience by donor tier or staff role without separate code changes.
• Dual Standard + Watersheds Builds
  Release packaging now produces both the standard universal zip and a Watersheds-specific variant from the same codebase. The Watersheds build omits the Microsoft.Extensions DLLs that Watersheds already ships.
• Launcher-Aware Configuration
  Discord, database, and character-selection systems can pull environment-specific settings from the HoR launcher configuration instead of duplicating secrets and IDs across multiple files.
• Spawn Command Removed
  The custom /spawn command is no longer part of HoR-Essentials. Teleport features now focus on homes, player requests, and role-based teleport rules.

• Home System (/home, /sethome, /delhome, /home list, /home limit)
  Save multiple named home locations and teleport back to them. Per-role home limits, cooldowns, teleport delays, and optional item costs. Supports refunding the cost when deleting a home. Creative-mode players bypass costs and cooldowns. Teleports cancel if the player moves during the delay.
• Role-Based Teleport Rules
  Home teleports and player-request teleports can use per-role cooldowns, delays, and home limits. This lets servers give faster travel or larger home limits to specific supporter tiers or staff roles without changing the global defaults.
• Teleport-to-Player (/t2p request, /t2pr, /t2pa, /t2p deny, /t2p cancel)
  Request to teleport to another player. Requests expire after 60 seconds. Target must accept. Supports deny, cancel, item costs, and cooldowns. All teleport types share a unified cooldown. Teleports blocked while mounted.
• Private Messaging (/msg, /reply, /r, /ignore, /unignore, /admins)
  Whisper to other players, quick-reply to your last sender, block unwanted messages. Ignore lists persist across restarts. Rate-limited to 3 messages per 10 seconds. HTML-sanitized to prevent VTML injection. /admins lists all online staff.
• Starter Kit (/starterkit)
  One-time claimable kit for new players. Contents set by admins from their hotbar, preserving item attributes and enchantments. Claim status saves immediately to prevent re-claiming after restarts.
• Account Linking (/link <code>)
  Link your in-game account to the web dashboard using an 8-character code. Communicates with the external Python daemon via IPC files.
• Character Re-Selection
  Request to re-select your character via Discord. If your 7-day cooldown has passed the request is granted instantly. Otherwise a numbered request is created for admin approval. Managed via Discord slash commands.
• Server Info (/serverinfo, /rstatus)
  Real-time performance stats (TPS, memory, entities, chunks, uptime, player count) and restart schedule status.

• Restart Control (/rrestart, /rdelay, /rcancel, /rannounce)
  Schedule a manual restart (1–60 min with reason), delay the next scheduled restart (1–120 min), cancel a pending restart, or broadcast a server-wide announcement that simultaneously posts to Discord.
• Scheduled Automatic Restarts
  Configurable restart times with cascading warnings at 60, 30, 15, 10, 5, and 1 minute. Restart trigger sent via IPC file to your external daemon, which handles stop, backup, and start.
• Configuration Hot-Reload (/reloadconfig)
  Reload HoRConfig.json without restarting. Instant effect on cooldowns, limits, costs, and feature toggles.
• Home Limit Override (/homelimit)
  Override a specific player's home limit beyond their role default.
• Admin Chat (/ac)
  Private staff-only channel that doesn't appear in public chat or Discord relay.
• Starter Kit Admin (/setstarterkit, /resetstarterkit, /resetstarterkitall confirm)
  Set kit contents from your hotbar (attributes and enchantments preserved). Reset an individual player's claim or bulk-reset all online players.
• Creative Action Tracking
  Harmony patches intercept creative-mode commands (/gamemode, /give, /spawnitem) and creative inventory slot activations. All actions logged with player, item/block code, position, and timestamp.
• Admin Command Interception
  Harmony patch on ChatCommandApi.Execute logs privileged commands (gamemode, tp, give, kick, ban, whitelist, etc.) to the audit log with a configurable monitoring list.
• Handbook Editor
  In-game GUI for creating and editing custom handbook pages without leaving the server or touching config files.

Built-in Discord.Net bot - no separate application needed.

• Bidirectional Chat Relay
  Game chat → Discord channel and Discord messages → in-game with [Discord: username] prefix. Emojis VTML-escaped for safe display.
• Discord Rich Presence
  Client-side presence showing server name, player count, session timer, and game mode on Discord profiles. Updates every 15 seconds. Uses HoRDiscordRPC.dll to avoid conflicts with standalone RPC mods.
• 13+ Slash Commands
  Server monitoring: /stats, /status, /serverhealth, /entitycount, /serverinfo
  Character re-selection: /charselrequest, /charselstatus, /charselreset, /accept, /deny
  Server control: /announce, /restart, /delay, /cancel
• System Notifications
  Server online/offline, player join/leave, restart warnings, admin actions, and shutdown events posted to a configurable channel.
• Audit Log Forwarding
  Real-time forwarding of server-audit.log events to categorized Discord channels: admin commands, inventory, combat, player activity, blocks, and misc. Rate-limited batching respects Discord API limits.

Optional - requires your own PostgreSQL instance

• Server Metrics Collection
  Every 10 seconds, reflection-based collection records TPS, tick time, memory, GC stats, thread pool, network packets, player count, entity count, and chunk stats to server_metrics.
• Player Session Tracking
  Tracks connect/disconnect with IP, duration, and 60-second heartbeat. Orphaned sessions cleaned on startup. Bulk heartbeat UPDATE by server name for efficiency.
• Audit Event Logging
  Creative block place/break (with 10-position variation data), permission changes, admin commands, and item crafts logged to audit_events with coordinates, player UID, and JSON details. Deaths, survival actions, pickups, containers, and chat handled by your external audit log parser for zero TPS impact.
• Player UID Mapping
  On every join, upserts player_uid_mapping with UID, name, role code, and last join date.
• Achievement Checking
  Runs on player disconnect and every 5 minutes to check and award achievements.
• Auto-Schema Migration
  Creates tables and runs ADD COLUMN IF NOT EXISTS migrations on startup. Safe on both fresh and existing databases. Refuses default/empty passwords.
• Per-Event Database Toggles
  Individual enable flags for each event type: sessions, deaths, survival actions, items, containers, chat, world edits, entity events, admin commands, and permission changes.

• Role-Based Chat Tags
  Automatically prefixes messages with colored role badges ([Admin], [Moderator], etc.). Configurable formats and colors per role.
• Rotating Announcements
  Configurable server-wide announcement rotation at a set interval. Random or sequential order.
• Admin Chat
  Staff-only /ac channel, separate from public chat and Discord relay.

• Server-Synced Color Themes
  Server admin defines defaults in HoRUITheme.json. Theme pushed to all connecting clients automatically. Covers dialog backgrounds, borders, button colors, and text accents.
• Per-Player Overrides
  Players customize their own theme via an in-game GUI. Saved locally to ModConfig/HoR-Essentials/hor_ui_overrides.json.
• Flat UI Mode
  Removes gradients and shadows from dialogs for a cleaner look.
• Corner Radius Control
  Adjustable border radius for rounded or sharp UI edges.

• Custom Selection Outline
  Replaces the vanilla block selection outline with a fully configurable renderer. Custom color (RGBA), line width, and glow intensity.
• Rainbow/RGB Mode
  Optional cycling color mode that smoothly rotates the outline through hues over time.
• Per-Player Settings
  Saved to ModConfig/HoR-Essentials/hor_outline_settings.json on the client.

• Server-Defined Handbook Pages
  Add custom pages and tabs to the VS handbook visible to all players. Defined in HoRHandbook.json.
• In-Game Editor
  Admin editor dialog - create, edit, and reorder pages without touching config files or restarting. Pages inject via VS's OnInitCustomPages hook naturally.
• Content Distribution
  ContentGenerator writes a companion content mod folder that VS distributes to clients automatically.

• Server-to-Client Toast Notifications
  Sends toast-style in-game notifications to players via HoR-ToastLib integration. Used for restart warnings, announcements, and system messages.
• Signal File Watcher
  Reads signal files written by your external restart daemon. Translates external events into in-game notifications instantly.

• Single Config File
  Everything in ModConfig/HoR-Essentials/HoRConfig.json. No separate environment config files.
• Automatic Migration
  Old ModConfig/HoRConfig/ folder migrated to ModConfig/HoR-Essentials/ automatically on first launch.
• Per-Feature Toggles
  Every major system has its own enabled flag. Disable anything without removing the mod.
• Role-Based Configuration
  Per-role overrides for home limits, cooldowns, teleport delays, and item costs.
• Hot-Reload (/reloadconfig)
  Immediate effect on all toggleable settings without restart.

Player Commands

• /home [name] - Teleport to a saved home
• /sethome [name] - Save current location as home
• /delhome [name] - Delete a home
• /home list - List all saved homes
• /home limit - Show your home limit
• /t2pr [player] - Request teleport to player
• /t2pa - Accept incoming teleport request
• /t2p deny - Decline incoming request
• /t2p cancel - Cancel your outgoing request
• /msg [player] [message] - Send private message
• /r [message] - Reply to last PM sender
• /ignore [player] / /unignore [player] - Block/unblock PMs
• /admins - List online staff
• /starterkit - Claim one-time starter kit
• /link [code] - Link account to web dashboard
• /serverinfo - View server performance stats
• /rstatus - Check restart schedule status

Admin Commands (require controlserver privilege)

• /rrestart [minutes] [reason] - Schedule manual restart
• /rdelay [minutes] - Delay next scheduled restart
• /rcancel - Cancel pending restart
• /rannounce [message] - Server-wide announcement + Discord
• /ac [message] - Admin-only chat
• /reloadconfig - Hot-reload HoRConfig.json
• /homelimit [player] [limit] - Override player home limit
• /setstarterkit - Set starter kit from hotbar
• /resetstarterkit [player] - Reset player's kit claim
• /resetstarterkitall confirm - Bulk reset all online players

• Vintage Story 1.22.0+
  Required. Targets VS 1.22 APIs and .NET 10.0.
• HoR-ToastLib (required for notifications)
  Install alongside Essentials for in-game toast notifications.
• PostgreSQL Database (optional)
  Required only if enabling database features. Must provide your own instance.
• Discord Bot Token (optional)
  Required only for Discord integration. Discord.Net library is bundled.
• External Restart Daemon (optional)
  The mod communicates via IPC text files. You provide the external tool (e.g. PanduhsRestarter.py) that handles actual server stop/backup/start and audit log parsing.

Important: GameMetrics-Launcher and the HoR website platform are separate products and are not included with HoR-Essentials.

• Separate Service Offering
  The launcher + web dashboard stack is provided as a server service package for game servers that want hosted metrics, parser pipelines, automation tools, and management UI.
• What the Service Adds
  Audit parser ingestion, automated restart scheduling, backup orchestration, metrics dashboards, player profiles, and integrated web control workflows.
• How Essentials Fits In
  HoR-Essentials provides the in-game hooks and data/events that feed those systems (IPC messaging, restart signaling, account linking, Discord integration, and server telemetry).
• Interested in a Demo or Setup
  If you want to see how the website works or are interested in using it for your server, contact me privately on Discord at @Panduhs.