ValheimTwitch

ValheimTwitch

A BepInEx 5 mod for Valheim that lets Twitch events interact with the game

through Streamer.bot.

Plugin GUID: CodeWithTD.ValheimTwitch

Communication flow

Twitch -> Streamer.bot -> WebSocket -> ValheimTwitch mod -> Game actions

Valheim runs as a WebSocket client that connects to Streamer.bot's built-in

WebSocket server, authenticates, and subscribes to events. Streamer.bot actions

broadcast JSON commands to the mod; the mod validates them and executes game

actions on the Unity main thread.

Status

Implemented (Phase 1)

• Compilable BepInEx 5 plugin (net462).
• Streamer.bot WebSocket client using the documented protocol:
• Hello handshake (Streamer.bot v0.2.5+) with legacy fallback.
• OBS-style challenge authentication:

auth = base64(SHA256(base64(SHA256(password + salt)) + challenge)).

• Subscribe request for Twitch events and General.Custom broadcasts.
• Auto-reconnect with configurable delay, graceful shutdown, diagnostics.
• Main-thread dispatch: every WebSocket callback is marshalled to the Unity

main thread; nothing touches Unity/game state off-thread.

• Notifications through Valheim's own MessageHud, so they look exactly

like the game's built-in messages (local player only):

• show_message - the top-left general text (title + message as

consecutive messages, like the game's own top messages).

• show_notification - the large yellow center-screen message the game

uses for prominent announcements.

• Automatic top-left notifications for Follow / Cheer / Sub / ReSub /

GiftSub / GiftBomb / Raid / RewardRedemption (defensive field extraction).

• Structured command results and diagnostic logging; command handling fully

decoupled from the WebSocket transport.

• Spawning, executed only with host/server authority (ZNet.IsServer()),

so spawned entities are networked and replicate to all players:

• mob_spawn - a mob type; e.g. Greydwarf spawns greylings, greydwarfs,

shamans and brutes, spread randomly over the spawned amount with mixed

levels (rolled per creature; optional level caps the roll). Levels are

set via Character.SetLevel and stored on the ZDO so every player sees

the stars.

• enemy_spawn - one specific creature prefab by name, also with optional

level.

• item_spawn - items into the player's inventory or dropped on the

ground (shared world), in stack-sized chunks.

• Curated vanilla prefab catalog (no bosses by default); unknown names are

rejected. Spawn amounts are clamped to configured limits.

Not implemented

• Spawning from a pure client (joined someone else's server) is rejected by

design; that would need a server-side component and an RPC protocol.

• Bosses are not in the catalog at all.

Project structure

ValheimTwitch/

├── ValheimTwitch.csproj

├── Plugin.cs # BepInEx plugin entry point, wiring, main-thread pump

├── Configuration/ModConfig.cs # All Config.Bind() entries

├── Networking/

│ ├── StreamerBotClient.cs # WebSocket client, auth, subscribe, reconnect

│ ├── StreamerBotEventParser.cs # Hello/response/event envelope parsing

│ ├── TwitchEventFormatter.cs # Twitch event -> notification text

│ └── MainThreadDispatcher.cs # Background -> Unity main-thread marshalling

├── Commands/

│ ├── CommandRouter.cs # Central router, handlers transport-independent

│ └── CommandModels.cs # Command payloads + defensive JSON extraction

├── Spawning/

│ ├── PrefabCatalog.cs # Mob categories, enemy names, item names

│ └── Spawner.cs # Server-authoritative spawn logic

├── UI/NotificationManager.cs # MessageHud-backed notifications

├── manifest.json # manifest

├── icon.png # icon (256x256)

├── CHANGELOG.md

├── package.ps1 # Build + zip packaging

└── README.md

Build

Requirements:.NET SDK 6/8/9 and a Valheim installation with BepInEx 5

(denikson's BepInExPack recommended).

dotnet build -c Release

Output goes to bin/Release/ (ValheimTwitch.dll, WebSocketSharp.dll,

Newtonsoft.Json.dll).

Assembly references

The project references, via MSBuild properties:

-