Confirm with your password

ValheimServerGuide

Server-authoritative YAML-driven guidance mod for Valheim. Author custom quests, NPC conversations, and triggered popups using only vanilla UI. No custom assets required.

Install with Gale
Changelog & versions
Stats Source Decompile

· 💗 Donate

Stars
0
Downloads
39
Version
0.16.1
Updated
Author
TaegukGaming
Virus scan
✓ Scan successful
Runs on
Client & Server
Required by
1 mods

Compatibility

Required 2

Install these too — Gale pulls them in for you.

Description

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. You can split guidance across as many *.yaml / *.yml files as you like — including in nested subfolders — and they are all merged.
  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.

Your server also keeps each character's quest progress in BepInEx/config/ValheimServerGuide/PlayerProgress/, one file per character. Include that folder in your backups — it is your players' quest progress, not config you can regenerate.

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. Players pin the quests they care about from the in-game Codex (the Quests button on the inventory screen, or F3 → Pin to Tracker) and follow their progress on a draggable on-screen panel (F10). The Codex list scrolls, and finished guides can be hidden to keep it short.

NPC conversations — Shift + E on 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!"

Text tokens such as {playerName} (or {player_name} — the two are aliases), {creatureName}, {itemName}, and {biome} are substituted when the entry fires.

New in 0.16.1: guidance now reaches your players no matter how big your config gets. The server used to send the whole config as one network message, and Steam refuses any message over 512 KiB — so once a config crossed that line (197 entries was enough) it was rejected and retried every frame, forever. Players got no guidance at all, the server console filled with send errors, and because everything else to that player queued behind the stuck message, the game appeared to pause whenever anyone opened a chest or a crafting station. The config is now compressed and sent in chunks. Update your server and your players together for this one — older clients cannot read the new format. Also: entries are indexed by trigger type, so an interaction only checks the quests that could actually match it instead of all of them.

New in 0.16.0: Valheim 1.0 (Unity 6) support. This release and everything after it require Valheim 1.0 and cannot run against an older game — update your dedicated server before your players. Reward granting was corrected for a changed game function that would otherwise have flagged earned rewards as cheated, and the BepInEx/Jötunn dependency pins were moved to their Unity 6 builds.

New in 0.15.0: rewards on a dialogue choice now actually happen. If you put a rewards: block on a choice inside a node-based conversation it was thrown away while the file was being read — no error, no log line, no reward, in every version up to 0.14.0. Flat conversation.choices: were always fine, so quest chains built the newer way quietly never paid out. Your YAML needs no changes; a node choice now rewards the moment it is picked, whether it ends the conversation or carries on to another node, and pays at most once per conversation so a looping tree cannot be farmed. Also new: a Quests button on the inventory screen opens the Guide Codex, which until now was reachable only by a hotkey nobody had been told about. F3 still works.

New in 0.14.0: NPC dialogue options with no text are fixed, and the choice buttons now match Valheim's own dialog buttons. A node choice written text: used to render a blank button (only label: was accepted there); both spellings work now, in every conversation shape. Choices also get one full-width row each instead of being packed three across, which is what used to wrap an ordinary reply onto three lines and inflate the button to match. Bounty triggers gained an optional tier: filter (1–5) plus the {tier}, {tierName}, {method} and {bountyBiome} tokens.

Fixed in 0.13.1: type: distance entries now fire on dedicated servers. Valheim only builds its list of world locations on the machine that generated the world, so a player connected to a dedicated server never received it and the trigger sat silent no matter how close they walked. It now also spots locations standing in the world around the player, and map-icon locations (boss altars, vendors) at any range. On a dedicated server, a very large radius: on a location with no map icon is still bounded by how much world the player has loaded.

New in 0.13.0: the rune reading card and the NPC dialogue panel now match the Guide Codex — all three are drawn in Valheim's player-inventory window, using its font, its orange-on-parchment colours, its carved wood frame and its real buttons (hover, pressed and disabled states included). Nothing is added to the download; it is read off the running game and falls back to a plain dark panel if it cannot be. Text is a step larger to suit that font, and buttons now grow to fit a label that wraps onto a second line instead of the text running out past the button's edge. Any rune: size or colour you set yourself still wins — only the defaults moved.

New in 0.12.0: quest progress is saved on the server, in one readable file per character under BepInEx/config/ValheimServerGuide/PlayerProgress/. Previously it rode along inside each player's own character save, which meant quests finished in single-player showed up as already done when they rejoined your server. Existing progress migrates automatically the first time each character logs in — nothing resets. Back this folder up (or point ProgressPath outside config/): it is your players' quest progress.

New in 0.12.0: the Guide Codex is drawn in the game's own window — the player inventory's carved frame, interior boxes, buttons and font, so it matches your install and adds nothing to the download. Its text is a size or two larger to suit that font, its buttons are sized for their labels, and the window now scales with your resolution and GUI scale instead of coming out oversized. Rune readings also use the width: you set — the first one of each session used to come out as a narrow column.

New in 0.12.0: the Guide Codex list scrolls instead of paging — one continuous list with a scrollbar that appears only when there is more to see. The mouse wheel no longer zooms the camera while the Codex is open, every scrolling area in the mod moves a sensible distance per notch (the detail pane, "Upcoming Steps" and the rune reading could not be wheel-scrolled at all before), and no game HUD element covers a mod panel any more — the stamina bar used to draw over NPC dialogue, and the crosshair sat in the middle of every panel. The crosshair and hover text now hide while a panel is open and return when it closes.

New in 0.11.0: the Guide Codex list no longer collapses its rows into blank gaps once the list outgrows the panel. (This version fixed it by paging the list; the unreleased note above replaces that with scrolling.) Players can hide guides they are done with ([ ] Hide from list) and bring them back with [ ] Show hidden. New public vsg_refresh command rebuilds the Codex and re-pulls the server's config — no admin needed.

New in 0.10.0: panels now size themselves to your text — the NPC conversation panel grows to fit and scrolls instead of cutting long dialogue off, message at position: Center word-wraps, and no display mode truncates any more. Plus a new highlight: block that colours chosen words or phrases inside any text, so the hotkey, the cost or the warning survives a skim.

New in 0.9.1: {playerName} now expands everywhere author-written text is shown — the Guide Codex, the HUD tracker, NPC conversation headers and choice buttons, raven/intro topics, NPC hover text, and every reward message — instead of only in the message shown at the moment an entry fires.

New in 0.9.0: the rune display mode is now a fully customizable, game-themed panel — set your own header/body/list fonts, colors, and alignment per entry, add a bullet list, and enjoy a smooth fade in/out. Plus seven new Lost Scrolls II trigger types for party duels, the party ladder, and bracket tournaments.

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.16.1 Source / issues / wiki: https://github.com/yesu0725/Valheim-ServerGuide

Changelog

0.16.1 Latest

A fix for a bug that could stop guidance reaching your players at all, and a large cut in the work every interaction does. No quest progress is touched and no YAML changes.

Update the server and your players together this time. The config now travels compressed and split into chunks, and a client still on 0.16.0 or earlier cannot read the new format — it will log Failed to apply synced config and show no guidance. This is the one release where the usual "any order" rule does not apply.

Guidance silently stopped arriving once the config grew past a certain size

The server sent your whole config to each joining player as a single network message. Steam refuses any reliable message over 512 KiB, and a config of 197 entries — 351 KB of YAML as you write it — arrives at 539,881 bytes once it is serialised, because the wire form re-emits every field your files leave at its default. That is 3% over the line.

Nothing warned. It simply stopped working when one more quest file tipped it over, and it failed in the worst possible way: Steam rejected the message, Valheim left it at the head of that player's send queue, and retried it every frame for as long as they stayed connected — about 1,500 failed sends a second, each one a line in your server console.

Because that queue is ordered, everything else waiting to reach that player queued up behind a message that could never leave. Chest contents, crafting stations, doors, item ownership — all of it arrives over the same queue, which is why the game appeared to pause whenever anyone opened anything, on a server that was otherwise idle. And the config itself never arrived, so those players had no guidance at all.

The config is now compressed before it is sent — the same config drops from 539,881 to 110,733 bytes — and then split into 128 KiB chunks that the client reassembles. Compression alone would have been enough today, but it only moves the cliff; chunking removes it, so no amount of authored YAML can jam a connection again. Each push logs one line with the sizes, which is also the early warning if it ever creeps back up.

Every interaction checked every quest

Opening a chest evaluated all 197 entries to discover that none of them listen for chests. Entries are now indexed by trigger type, so an event only walks the entries that could possibly match it plus any quest chains in flight — a chest goes from 197 checks to 7, a kill from 197 to 40. Prerequisite lookups got the same treatment: checking whether a quest's requires: is satisfied used to scan the whole config each time, on every event, for every chain a player had open.

This is headroom rather than a fix for the stalls above — those were the network queue — but it is the difference between a config you can keep growing and one that starts costing you frames.

0.16.0

Valheim 1.0 support.

Valheim 1.0 moved to Unity 6 and changed five of the game functions this mod calls. Four of them only gained optional arguments and needed no changes here, but the new shapes are baked into the build, so this release and everything after it require Valheim 1.0 — it cannot run against an older game. Update your dedicated server before your players.

The fifth needed care: the function that puts a reward in a player's inventory gained a cheated flag inserted ahead of an existing one, which means the old call would have started marking every granted reward as cheated. Guidance rewards are earned through play, so they are passed as not cheated and your players' saves stay clean.

Also updated the dependency pins to the Unity 6 builds of BepInEx and Jötunn. If you install through a mod manager, this is the part that matters: the previous pins would have handed you a loader that cannot start under Valheim 1.0.

0.15.0

One quest-breaking fix and one new way into the codex. No quest progress is touched, and every existing YAML keeps working — you can update the server and the players in any order.

Rewards on a dialogue choice were silently ignored

If you wrote a rewards: block on a choice inside a node-based conversation, it never happened. Not "failed with an error" — nothing at all: the dialogue played perfectly, the player picked the option, and the reward quietly went nowhere. No warning in the log, no hint that anything was wrong.

Two things were needed to make it work, and neither was there. Node choices had no rewards: field to parse into, and unknown keys are dropped without comment, so the block was thrown away while the file was still being read. Even a parsed reward would have gone nowhere, because the node path never asked the reward system for anything.

Both are fixed. A node choice now takes rewards: exactly the way the flat conversation.choices: form always has, with the same reward types and the same syntax:

nodes:
  - id: offer
    text: "Take the commission, then."
    choices:
      - text: "Mark it on my map."
        rewards:
          - type: set_player_key
            key: MY_QUEST_STARTED

Two things worth knowing:

  • The reward is granted the moment the choice is picked, whether that choice ends the conversation, jumps to another node, or hands off to another entry. A reward partway through a branching conversation works.
  • A choice pays out at most once per conversation. Node trees can loop — "ask me again" options are a normal shape — and without this a loop back through a rewarding choice would pay every time round. Use the entry's own once:, cooldown: or max_fires: to control how often the conversation itself can be had.

The log now names the entry and the choice whenever rewards are granted, so this failing silently again would be obvious.

If you have a quest that was affected, players who already went through the dialogue have it recorded as done and will not be offered it again. vsg_reset <entry_id> clears it for the character running the command, and vsg_reset_player <playerName> <entry_id> does it for someone else on the server.

A "Quests" button on the inventory screen

The Guide Codex was reachable only by pressing F3. A key nobody mentions is not discoverable — a player who never reads the server's config or wiki had no way to learn the codex was there at all.

There is now a Quests button on the inventory screen that opens it. It is a clone of the inventory's own Take All button, so it looks like part of the game rather than something bolted on, and it is rebuilt on every world load so it survives relogs and respawns. F3 still works.

Running Lost Scrolls II as well? The button parks itself directly under that mod's Tournaments button and follows that row wherever it has been nudged, so the two mods read as one menu instead of two rows fighting over the same corner.

21 older entries, full version history & downloads →

Files

5 files · 261 KB download

Loading files…

Manual download
Just this mod One .zip — ValheimServerGuide 0.16.1
Files you'll get 3

Your browser may ask permission to download several files at once. How to install these manually
Manual installation instructions
1

Install BepInExPack Valheim

BepInExPack Valheim is required to run mods in Valheim.

Download BepInExPack Valheim 5.4.2360 · View mod page

Check out the mod page for detailed installation instructions.

2

Install ValheimServerGuide

This mod must be installed on both the client and the server.

Download ValheimServerGuide 0.16.1

Extract the ZIP and place the file(s) into the BepInEx/plugins/ folder inside your Valheim game folder.