ConsoleStdinHeeler

ConsoleStdinHeeler

Non-blocking STDIN console input and native server management commands for Valheim dedicated servers.

[!NOTE]

Dedicated Server Focused: This mod is intended specifically for headless Valheim servers (Linux or Windows) running in interactive terminals, multiplexers (screen, tmux), systemd services, or Docker containers. It automatically remains dormant if loaded in a standard game client.

The Problem

In vanilla Valheim, dedicated servers running in headless mode (valheim_server.exe on Windows or valheim_server.x86_64 on Linux) do not read from Standard Input (STDIN). Although logs and status messages print to standard output, server hosts cannot enter commands into the terminal or pipe commands into the server process.

Furthermore:

• No Native Server Console Input: Dedicated servers do not process interactive terminal input or piped streams. Server hosts cannot run commands locally without installing external RCON mods, game client admin connections, or remote management tools.
• Missing Operational Commands: The dedicated server binary lacks standard operational commands such as shutdown, stop, kickall, and countdown timers. Halting the server typically requires sending SIGINT (Ctrl+C) or terminating the process, which risks incomplete saves.
• Main-Thread Blocking & EOF Spin Risks: Synchronous reading on the main thread blocks the Unity game loop. Conversely, naive background readers without stream closure handling can rapidly enter spin loops and spike CPU usage when detached or running under non-interactive environments (e.g. systemd services or detached containers) where STDIN reaches EOF.

The Solution

ConsoleStdinHeeler implements a non-blocking background STDIN listener paired with a main-thread execution queue and dedicated server command suite:

• Non-Blocking Background Reader: Runs a dedicated background thread (ConsoleStdinHeeler_Reader) reading Console.ReadLine() without blocking the Unity main thread.
• EOF Stream Closure Guard: Detects consecutive EOF read attempts and terminates the reader thread when the input stream closes, preventing CPU spin in detached environments.
• Main-Thread Queue Dispatch: Commands from the background reader are enqueued to a thread-safe ConcurrentQueue and executed sequentially during the Unity Update() cycle.
• Dedicated Server Management Suite: Provides essential server administration commands, including clean saves, graceful shutdowns with countdown timers, player roster diagnostics, moderation, teleports, broadcasts, raids, and time controls.
• Mod Command Routing: Routes unrecognized commands to Valheim's central Terminal.commands dictionary with elevated permissions (Terminal.m_cheat), allowing commands from mods like WorldEditCommands, ServerDevcommands, and InfinityHammer to execute directly from the terminal.
• ANSI Terminal Translation: Translates Unity `` rich-text markup into terminal ANSI color codes for readable, formatted console logs.

Features

Non-Blocking STDIN Architecture

• Background Worker Thread: Reads Console.ReadLine() on a separate thread (Thread.IsBackground = true), keeping the main game loop uninterrupted.
• EOF Stream Detection: Monitored read loop tracks consecutive null reads. If STDIN reaches stream closure (e.g. systemd without an interactive TTY, or Docker without -i), the listener logs the condition and halts the reader thread.
• Main-Thread Execution: Commands are pushed to a ConcurrentQueue and dequeued on the Unity main thread during Update(), ensuring thread safety with engine and mod APIs.
• Exception Handling: Individual command execution is encapsulated in exception handlers to prevent malformed or failing commands from interrupting the server tick.

Dedicated Server Administration

• Graceful Shutdown (shutdown / stop / exit / quit): Triggers a world and player profile save (ZNet.instance.Save), followed by clean server termination. Supports optional countdown delays in minutes with broadcast reasons (e.g. stop 5 Main