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<string> 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 <color=...> 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<string> 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 Maintenance) and cancellation (stop cancel).
• Immediate World Save (save): Triggers an immediate synchronous save of world data and connected player profiles (ZNet.instance.Save(saveOtherPlayerProfiles: true)).
• Player Roster (players / list): Displays connected players, character names, IP endpoints, round-trip latency (ping), and internal player IDs.
• Player Moderation (kick, ban, unban, banned): Moderates players by character name, IP, Steam ID, or PlayFab ID.
• Mass Disconnect (kickall): Saves world and player data, displays an announcement banner, and disconnects all connected players after a configurable delay (default: 3 seconds) with custom kick reasons.

Remote In-Game Notifications & Controls

• Banner Notifications (say): Sends top-left notification banners to all players (@all or *) or a targeted player via ZRoutedRpc.
• Center Announcements (announce / broadcast / alert): Displays center-screen announcement banners to all players or a targeted player.
• Teleportation (tp / teleport): Teleports a player to another player's position or to coordinates (x,y,z). Supports quoted names for player names containing spaces.
• Player Targeting & @random: Supports @random as a player parameter (tp, say, announce, spawn, event) to select a connected player at random.
• Prefab Spawning (spawn): Spawns prefabs near a player or coordinates with optional quantity and star level parameters, placing entities safely on the surface.
• Raid & Event Controls (event, stopevent, randomevent): Starts specific or random raids near players or coordinates, or halts active events.
• World Time Controls (tod, skiptime, sleep): Adjusts time of day (0.0 to 1.0), skips forward in seconds, or advances time to morning with client synchronization.

Terminal & Mod Compatibility

• Mod Command Passthrough: Unrecognized commands are passed to Terminal.commands, allowing console execution for installed developer and administration mods.
• Cheat Permission Elevation: Sets Terminal.m_cheat = true during command dispatch so cheat-flagged and administrative commands execute on dedicated servers.
• Client Command Filter: Intercepts commands that require a local player character or rendering camera (e.g. god, fly, ghost, pos, beard, hair, fov) with clear warnings instead of throwing NullReferenceException errors.
• ANSI Color Formatting: Translates Unity <color=...> tags into terminal ANSI colors with configurable display modes (Ansi, Strip, Raw).
• Command Reference (help): Displays dedicated server commands and auto-discovered mod commands, with help all exposing the full native command catalog.

Available Commands

[!TIP] Player Targeting & @random: Any command accepting a player target (tp, say, announce, spawn, event) supports @random to select a connected player at random.

Client-Only Command Safeguard: Commands that require an active local player character (e.g. god, fly, goto, pos, beard) are intercepted with a warning rather than throwing NullReferenceException errors in the server log.

Configuration

Settings can be customized in BepInEx/config/dreamwraith.ConsoleStdinHeeler.cfg:

Server Deployment Notes

Linux screen or tmux

Launch the Valheim server inside a screen or tmux session to enter commands interactively:

screen -S valheim ./start_server_bepinex.sh
# Type 'save', 'players', or 'shutdown' directly into the console

systemd Services

When running under systemd without an interactive terminal (StandardInput=null), ConsoleStdinHeeler detects stream closure (EOF) and cleanly halts the reader thread without spinning CPU. To pass commands into a systemd service, configure a FIFO pipe or interactive TTY.

Docker

When running inside Docker, allocate standard input:

docker run -i -t ...
# Or attach to an existing container:
docker attach <container_id>

If run detached without -i, the reader detects EOF and terminates the thread.

Compatibility

• Dedicated Servers: Built specifically for headless dedicated servers (valheim_server.exe on Windows or valheim_server.x86_64 on Linux). Safely disables itself if launched within a standard game client.
• Server Administration & Dev Mods: Compatible with server management and developer mods, including WorldEditCommands, ServerDevcommands, and InfinityHammer.
• Vanilla Game Terminal: Passes through native Valheim terminal and server utilities (save, ping, info, genloc, optterrain, listkeys, etc.).
• Interactive Multiplexers & Containers: Compatible with screen, tmux, systemd service units, Windows Command Prompt/PowerShell, and interactive Docker containers.
• Mod Managers: Fully compatible with Gale, Thunderstore Mod Manager, and r2modman.

Installation

Manual Installation

1. Ensure BepInExPack Valheim is installed on your dedicated server.
2. Download and extract the latest release archive.
3. Place ConsoleStdinHeeler.dll into the BepInEx/plugins/ directory on your server.
4. Launch the dedicated server.

Mod Manager

1. Install via Gale, Thunderstore Mod Manager, or r2modman.
2. Launch the dedicated server.

Building from Source

The project source code is available on GitHub and uses a portable MSBuild configuration that auto-detects standard Steam paths.

dotnet build -c Release

The compiled assembly will be placed in bin/Release/net48/ConsoleStdinHeeler.dll.

Custom & CI Paths

For non-standard Steam library locations or mod manager profiles, copy ConsoleStdinHeeler.csproj.user.example to ConsoleStdinHeeler.csproj.user in the project root (this file is git-ignored and automatically loaded by MSBuild):

<?xml version="1.0" encoding="utf-8"?>
<Project>
  <PropertyGroup>
    <GamePath>D:\SteamLibrary\steamapps\common\Valheim</GamePath>
    <BepInExCorePath>$(UserProfile)\AppData\Roaming\com.kesomannen.gale\valheim\profiles\<ProfileName>\BepInEx\core</BepInExCorePath>
  </PropertyGroup>
</Project>

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details. Source code and issue tracking are available at https://github.com/dreamwraith/Valheim-ConsoleStdinHeeler.

Changelog

All notable changes to ConsoleStdinHeeler will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.1] - 2026-09-26

Fixed

• Corrected project repository and website URLs across package metadata, manifest, and assembly info.
• Revised documentation and changelog formatting.

[1.0.0] - 2026-09-25

Added

• Initial Release of ConsoleStdinHeeler.
• Non-Blocking STDIN Console Architecture:
  • Background reader thread (ConsoleStdinHeeler_Reader) reading Console.ReadLine() without blocking the Unity main thread.
  • Three-strike consecutive EOF detection automatically terminating the reader thread when the input stream closes (e.g. systemd without interactive TTY or detached Docker containers), preventing CPU spin loops.
  • Thread-safe command queue (ConcurrentQueue<string>) drained sequentially on the Unity main thread during Update().
  • Defensive execution wrapping command dispatches in exception handlers to prevent unhandled errors from interrupting the server loop.
• Dedicated Server Management Commands:
  • save: Triggers an immediate synchronous save of world data and player profiles.
  • shutdown / stop / exit / quit: Saves world state and initiates graceful server termination, supporting optional countdown delays in minutes with custom broadcast reasons and cancellation (stop cancel).
  • players / list: Displays connected players, character names, IP endpoints, round-trip ping latency, and peer IDs.
  • kick / ban / unban / banned: Dedicated player moderation commands supporting player name, IP, Steam ID, and PlayFab ID matching.
  • kickall: Saves world data, displays an announcement banner, and disconnects all connected players after a configurable delay (default: 3 seconds) with custom kick messages.
• In-Game Broadcasts & Remote Administration:
  • say: Sends top-left notification banners to all players (@all or *) or a targeted individual via ZRoutedRpc.
  • announce / broadcast / alert: Displays center-screen announcement banners to all players or a targeted player via ZRoutedRpc.
  • tp / teleport: Teleports a connected player to another player's position or to world coordinates (x,y,z), with target position validation and client UI feedback.
  • spawn: Server-side prefab and creature spawning near players or coordinates with optional quantity and star level parameters.
  • event / stopevent / randomevent: Server-side raid event triggering, termination, and random triggering.
  • tod / skiptime / sleep: World time of day adjustment, skipping forward in seconds, and sleeping to morning with network synchronization across all clients.
  • Dynamic @random player targeting for commands accepting player targets (tp, say, announce, spawn, event).
• Command Routing & Mod Compatibility:
  • Automatic passthrough of unrecognized commands to Valheim's central Terminal.commands registry, enabling terminal execution for mods like WorldEditCommands, ServerDevcommands, and InfinityHammer.
  • Automatic Terminal.m_cheat elevation during command dispatch, allowing administrative and developer commands to execute on dedicated servers.
  • Server command filter intercepting client-only commands (emotes, rendering settings, local player cheats) with clear warnings instead of throwing exceptions.
  • Curated help command listing dedicated server commands, installed mod commands, and native utilities, with help all providing an unfiltered catalog.
• Rich-Text ANSI Terminal Translation:
  • Conversion of Unity <color=...> tags into terminal ANSI color escape sequences with configurable display modes (Ansi, Strip, Raw).
  • Configurable console prompt prefix (default: > ) displayed in server logs when commands are received.