ValheimServerGuide

Turn your Valheim server into a guided experience. Write a YAML file on your server and players receive quest objectives, NPC dialogues, lore popups, and rewards — triggered automatically as they play, using only Valheim's own UI.

No custom assets. No custom UI skins. Just your words, delivered through Hugin, the chat, and dramatic cinematic screens.

What it does

Guides players through your content. When a player crafts their first weapon, enters a dangerous biome, discovers the trader, or kills a boss — show them a message. Give them a quest. Give them a reward.

Runs entirely from the server. You write one YAML file. Every player connected to your server receives it automatically. Update it and save — all players get the new version instantly without restarting.

Uses vanilla Valheim UI. Messages appear as Hugin (the raven) popups, system toasts, chat lines, rune-tablet screens, or the dramatic intro cinematic style. Nothing looks out of place.

Quick setup

1. Install this mod on your server (and on every player's game via r2modman).
2. Start the server. It creates BepInEx/config/ValheimServerGuide/guidance.yaml automatically.
3. Edit that file to add your guidance entries.
4. Save. All players receive the update without a restart.

The mod works in single-player and host & play as well — the host acts as the server.

What you can create

Triggered messages — Show a Hugin raven popup, a toast, or a dramatic full-screen text when a player does something specific:

• Crafts an item for the first time
• Enters a biome
• Kills a creature
• Reaches a skill milestone
• Discovers the trader
• Opens a chest
• And many more...

Multi-step quests — Chain triggers into a quest with steps. "Gather 10 wood → craft a workbench → build a wall." Each step has its own trigger. Progress shows in the on-screen tracker.

NPC conversations — Hold E near Haldor, Hildir, or BogWitch to open a dialogue panel. Give them choices. Fire quests. Grant rewards.

Item turn-ins — Have players bring a specific item to a trader NPC to complete a quest step.

Rewards — Grant items, skill experience, or status-effect buffs when an entry or quest completes.

World events — Mark an entry as scope: global and the first player to trigger it fires the display for every connected player simultaneously. Perfect for boss kills and world milestones.

Discord announcements — Post to a Discord channel when something happens (server-side only; your webhook URL is never exposed to players).

Example

A raven popup when a player crafts their first bronze sword:

- id: first_bronze_sword
  trigger:
    type: craft
    item: SwordBronze
  display:
    mode: raven
    topic: "Bronze Edge"
    text: "Forged in fire, this blade cleaves the Black Forest's beasts."
  once: true

A world event when the first boss falls:

- id: world_eikthyr_fell
  scope: global
  trigger:
    type: kill
    creature: Eikthyr
  display:
    mode: intro
    topic: "The Stag-King Falls"
    text: "Eikthyr is slain. The realm trembles. Your trial begins, traveler."
  once: true
  announce:
    discord: "⚔️ **{playerName}** has slain **Eikthyr** — the first boss has fallen!"

Documentation

Full configuration guides, all trigger types, display mode options, quest chains, NPC conversation setup, reward configuration, and admin commands are covered in the Wiki.

Try it out

This mod was built for the TaegukGaming community server running the Hearthbound modpack. If you want to see it in action:

Hearthbound Valheim Modpack

Disclaimer

This mod is created using AI. No other mods were copied during the process. All feature ideas come from the uploader and are mainly to cater to the needs of the TaegukGaming community server. If any features or ideas look similar to other mods, these are not intentional.

This mod is free to use as is. Voluntary support is appreciated.

Version: 0.5.0 Source / issues / wiki: https://github.com/yesu0725/Valheim-ServerGuide

Changelog

0.5.2

New Features

• vsg_list_player <playerName> — Show the full VSG guidance state of any currently-online player directly from the admin console. Lists fired IDs, max_fires counters, chain progress (step / complete), item-submit progress, and goal-started flags. Works from both listen-server hosts and remote admin clients; results appear asynchronously after the RPC round-trip.
• vsg_reset_player <playerName> [all | <id>] — Reset a specific online player's guidance state. Mirrors vsg_reset exactly (clears fired IDs, fire counters, chain state, submit progress, goal state, raven flags) but targets another player's character instead of your own. The admin console receives a confirmation message once the target client executes the reset. Both commands are admin-only (onlyAdmin: true) and re-verified server-side.

0.5.1

Bug Fixes

• Raven re-show after vsg_reset fixed. After vsg_reset (all or single-id), raven entries now correctly re-show when re-triggered. The root cause was that Vanilla's Raven.AddTempText silently no-ops when a RavenText with the same key already exists in its static list, and vsg_reset clearing the seen-flag disabled vanilla's own cleanup for that entry. The fix evicts stale RavenText entries from Raven.m_tempTexts on every reset path and defensively before every re-show.
• max_fires entries re-fire after vsg_reset. Entries using trigger.max_fires: N (such as player_death tips) were permanently blocked after hitting their cap, even after vsg_reset all. Fire counts are stored in separate VSG.fc.* keys that the old reset code never cleared. vsg_reset all and vsg_reset <id> now also clear these counters.
• vsg_list surfaces max_fires progress. Entries using max_fires never appeared as "fired" in vsg_list (they don't write VSG.fired). They are now tagged [fired N/max] in the configured-entries list so you can see their counter and confirm it cleared after a reset.
• skill_level trigger fires on login for skills already above threshold. Previously the skill_level trigger only fired when a skill level actively increased during the session. If a player logged in with a skill already above one or more thresholds, those entries were silently skipped. On login the mod now scans every configured skill_level threshold; any threshold the player already meets that has not yet fired is raised in ascending level order. For chains, this means all qualifying steps cascade automatically — step 1 fires first (advancing the chain), then step 2 fires, and so on.
• location_entered trigger now detects mod-added locations reliably. The previous implementation read ZoneSystem.m_locationInstances and required m_placed = true, which is only set after the server re-syncs location data to the client. Locations generated after login never received that re-sync, so the trigger was permanently skipped for any zone entered for the first time. Detection now uses Location.s_allLocations (the scene's live spawned Location components) as the primary source, with the ZoneSystem as a fallback for locations lacking a Location component. The fallback also now tries m_name when m_prefabName is empty. Both paths emit LogDebug lines (enable LogLevel = Debug in BepInEx.cfg) so you can confirm the exact prefab names being detected and verify your wildcard patterns.

0.5.0

New Features

• Multi-goal item_acquired triggers. An item_acquired entry can now require several different items at once via a goals: list (each with its own item and count). The entry fires only when every goal is met simultaneously. Items may be collected in any order, and crafted items count toward their goals. Replaces the need to chain several single-item collection steps.
• Per-item goal progress. Multi-goal entries show a per-item breakdown (FineWood: 18/30, Coal: 12/25, …) — in the HUD Tracker row tooltip and in the Guide Codex body — so the player always knows exactly what is still needed. The Codex badge shows N / M goals completed.
• Persistent "started" state. Once the player has collected toward any goal, the entry stays visible in both the HUD Tracker and the Codex even if those items are later removed from the inventory (crafted away, dropped, or lost on death). Visibility is no longer tied to the current inventory once collection has begun.

Improvements

• Plain numeric progress. The HUD progress bar has been removed in favour of a simple current/goal count across all collection displays (chain counter steps, npc_item_submit, and item_acquired goals) for a cleaner, consistent look.
• Chain counter steps show their count. A chain step with a progress_goal now displays its current/goal count in the HUD Tracker row.
• Codex completion is goal-accurate. A multi-goal item_acquired entry is only marked complete in the Codex when every goal is currently satisfied, re-checked live against the inventory.
• vsg_reset clears goal state. vsg_reset all and vsg_reset <id> now also clear the latched goal-started flag.

0.4.0

Improvements

• Raven display queue. Multiple raven entries that fire in quick succession are now shown one at a time instead of all at once. Each raven persists until the player interacts with it (or the raven auto-dismisses). The next queued raven appears only after the current one is acknowledged, so no message is skipped or overwritten.
• Dungeon deferral for raven. Raven entries that fire while the player is inside a dungeon or interior location are held in a deferred queue. The moment the player exits, the deferred ravens drain into the normal queue and show in order.
• vsg_reset clears the raven queue. vsg_reset all wipes the entire raven display queue and deferred list. vsg_reset <id> removes any pending instance of that specific entry from both queues and cancels it immediately if it is the currently-active raven.

0.3.2

Improvements

• item_acquired inventory seeding. When an item_acquired count > 1 entry becomes eligible (on player login or config reload), the mod now immediately reads the player's current inventory and seeds the progress counter from it. Items already carried before the guide entry existed count toward the goal — the player is never penalised for having collected materials early. If the inventory total already meets the goal at that moment, the entry fires right away without requiring another pickup.
• Chain step inventory seeding. When a chain counter step uses progress_trigger: { type: item_acquired }, activating the step now seeds the counter from the player's existing inventory instead of starting at zero. If the seeded count already meets progress_goal, the step advances immediately.
• Wiki updated. Trigger-Types, Guide-Chains, and YAML-Configuration pages document the new inventory-seeding behaviour and the count field for standalone item_acquired entries.

0.3.0

New Features

• item_acquired count goal. Add trigger.count: N to any item_acquired entry to require the player to accumulate N of that item in their inventory before the entry fires. Progress is tracked as the current inventory total (all matching stacks summed), so two stacks of 10 count as 20. Both picking up items and crafting them count toward the goal. A current/goal progress bar appears in the HUD Tracker while collecting and disappears once the goal is reached.

0.2.0

New Features

• Multi-file YAML loading. The loader now scans the entire BepInEx/config/ValheimServerGuide/ folder for *.yaml and *.yml files and merges them into one config. Split your guidance across as many files as you like. Duplicate ids across files: first file (alphabetically) wins. A malformed file is skipped with a log error; other files still load.
• Biome trigger. New trigger.type: biome fires when the local player enters a named biome (e.g. biome: BlackForest). Fires once per session entry; resets on spawn so it also fires on first login.
• Distance trigger. New trigger.type: distance fires when the local player comes within trigger.radius metres (default 50) of a world location whose prefab name matches trigger.location (trailing * wildcard supported). Fires at most once per location per character.
• Codex entry summary:. Add a top-level summary: field to any entry; the Codex shows a "Quest Complete" header + recap once the chain finishes. Falls back to the last step's message if not set.
• Codex step description:. In-progress chain steps now display description: in the Codex body (what the player needs to do), not the completion message: text. Entries without description fall back to message as before.
• General category. Added General to the list of valid Codex categories.
• Display mode rules doc. wiki/Display-Modes.md now includes a full recommended-mode table per trigger type (rune for action events, raven for environmental events, message for NPC/minor tips).
• Guide Authoring Reference. New wiki/Guide-Authoring-Reference.md — comprehensive reference for guide authors covering display mode assignments, chain patterns, and Codex field semantics.

Bug Fixes

• Raven re-fire fix. Raven entries now correctly re-fire when once is not set or after vsg_reset. Previously the vanilla Player.m_shownTutorials gate caused the raven to show only once per character save, ignoring VSG's own repeat controls.
• Raven message: and template support. Raven mode now reads the top-level message: field (same as all other modes). Template tokens ({player_name}, {biome}, etc.) are expanded each time the entry fires.
• Timed trigger player-scope fix. Player-scope timed entries now run on each client individually. Previously dedicated servers skipped player-scope timers entirely, preventing per-player timed tips from ever firing on dedicated servers.
• vsg_reset raven fix. vsg_reset (both all and single-entry) now clears the vanilla raven seen-flag so raven entries can re-show after a reset.

0.1.0

Initial release.

Features

• YAML-driven guidance system. Server admins write a guidance.yaml that is automatically pushed to all connected clients. No client-side file editing required.
• 18 trigger types. React to crafting, item pickups, kills, builds, biome entries, location discovery, skill milestones, NPC interactions, boss defeats, player deaths, timed intervals, and more.
• 6 display modes. Raven (Hugin popup), Message toast, Chat line, Rune viewer, Intro cinematic, and NPC conversation panel — all using vanilla Valheim UI.
• Guide chains. Multi-step quests with per-step triggers, progress counters, and HUD tracking.
• HUD Tracker. On-screen objective tracker widget shows active guide chains with live progress bars. Toggle with F10 (configurable).
• Codex panel. In-game guide browser (F3) organised by category with full entry descriptions.
• NPC Conversation system. Hold E near a trader to open a dialogue panel with choice buttons. Choices can fire entries or grant rewards.
• Reward system. Grant items, skill experience, skill levels, and status-effect buffs on entry completion or conversation choices.
• Discord integration. Server-side webhook POSTs when entries fire or chains complete. Webhook URL stays on the server only.
• Player vs Global scope. Player-scoped entries track per-character; global entries fire for all connected players simultaneously and persist with the world save.
• Firing controls. once, cooldown, requires, and stop_when give full control over when entries fire.
• Admin commands. vsg_reset and vsg_list for testing and moderation from the F5 console.
• Hot-reload. Edit and save guidance.yaml — all connected clients receive the update instantly, no server restart needed.