Valheim Donations

Lets Valheim players donate via Ko-fi, PayPal, Patreon, or PayMongo and get Valcoins credited in-game automatically, redeemable in a configurable in-game shop for perks and weekly-limited consumables. Requires the plugin installed on both server and client — donations happen entirely through an in-game panel, not chat commands.

What it does

• One in-game panel, opened with F4 — a browsable, offline-resilient home for donating, the shop, gifting, and the patron leaderboard, that lights up automatically once the server's donation backend comes online. All actions (donate, buy, gift, admin give/remove) happen here, over a silent RPC — nothing is typed into public chat.
• Simple donate flow — click one button to get your code, copy it, and open the donation portal in your browser; your Valcoins credit automatically. The tab leads with a clear $1 USD = N Valcoins rate (served by your backend, so it always matches what donations actually credit).
• Any of four providers (Ko-fi, PayPal, Patreon, PayMongo) can be wired up independently; each webhook verifies its own signature and credits Valcoins automatically within seconds.
• A configurable shop (valcoin_shop.yaml) sells:
  • Soulkeeper Charm (add_charges) — death insurance: on death you keep your skills (no drain) and a Valkyrie carries you back to your tombstone, scattering nearby creatures on arrival. Capped at 10 charges per player per week.
  • Familiars (armor_vfx) — a miniature flying creature (Bat, Ghost, Deathsquito, Drake, Wraith, Volture, Gjall, Fallen Valkyrie) hovers at your shoulder, bound to your equipped helmet. Grants feather fall and a small flat attack bonus. Other players see it too.
  • Weekly-capped, boss-gated consumables (grant_item) — feasts, meads, and bulk materials spawned directly into the buyer's inventory server-side.
• Preview images — give any shop item a picture via preview_image (an https URL or a file in BepInEx/config). It shows as a thumbnail in the shop row, larger in the purchase-confirm dialog, and clicking either opens a full-size view.
• Gift Valcoins to other players from the panel; a built-in Top Patrons leaderboard shows lifetime donors.
• Admin tab (admin-only) to manually give/remove a player's balance.

Quick setup

1. Install this mod on your dedicated server AND every player's client — the client copy is required, not optional; there's no chat-command fallback for un-modded players.
2. Deploy the companion FastAPI backend (see the GitHub repo — deploys to Fly.io in a few commands).
3. Launch the server once. It writes a template BepInEx/config/valcoin_config.json — fill in backend_url and plugin_token from your backend deploy, then restart.
4. Edit BepInEx/config/valcoin_shop.yaml to set your shop catalog (also auto-templated on first run).
5. List admin Steam64 IDs in BepInEx/config/valcoin_admins.yaml to unlock the panel's Admin tab for them.

That's the minimum. Everything else — provider webhooks, weekly-capped consumables — is documented in the repo.

Documentation

Full setup, provider configuration, and shop schema are in the GitHub repo docs.

Try it out

This mod was built for the TaegukGaming community server running the Hearthbound modpack.

🏰 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 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: 5.16.0 Source / issues: https://github.com/yesu0725/valheim-donations-plugin Backend (required, self-hosted): https://github.com/yesu0725/valheim-donations-backend

Changelog

5.16.0

• Shop preview images. Shop items can now show a picture. A new optional preview_image field on each SKU in valcoin_shop.yaml takes either an https URL or a path relative to BepInEx/config (e.g. shop_images/Bat.png). The shipped Familiars catalog uses it, so you can finally see what you're buying.
• Click to enlarge. Preview images appear as a thumbnail in the Shop row and larger in the purchase-confirm dialog — clicking either opens a full-size view, fitted to your window and never blown up past the image's real size. Close it with the Close button, a click outside, or Escape.
• Exchange rate on the Donate tab. The Donate tab now leads with a large $1 USD = 50 Valcoins callout plus a worked example, so you know what a donation is worth before you open your wallet. The Shop tab carries the same rate as a one-line note. The rate comes from the server, so it can never drift from what donations actually credit.

Server operators: the exchange-rate callout needs a backend running 5.16.0 or later (it serves the new coins_per_usd field). Older backends make the callout read "Exchange rate unavailable". Preview images set as config-relative paths only resolve on machines that hold the image files — use https URLs so every connecting client can load them.

5.15.0

• Familiars now grant small perks. While a familiar helmet is equipped you get feather fall (the Feather Cape's own effect — wearing both doesn't stack) and a tiny flat attack bonus matched to the creature: Bat/Ghost/Wraith +2 slash, Deathsquito +2 pierce, Drake Hatchling +2 frost, Volture +3 pierce, Gjall +2 blunt & +1 fire, Fallen Valkyrie +2 spirit. The bonus is a fraction of a percent of endgame weapon damage — flavor, not power — and applies to melee, bows, and magic alike.
• Overwrite warning. If your equipped helmet already carries a familiar, the purchase-confirm modal now warns that buying a new one overwrites it, before you spend.
• Soulkeeper Charm: 10 charges per week. The charge pool is now capped at 10 per player per week, shared across the x1/x5/x10 tiers. Over-cap purchases are rejected with no coins spent and a "resets in …" note.
• Tomb creature repel. When the Valkyrie sets you down at your tombstone, hostile creatures nearby are staggered and shoved away so you aren't instantly mobbed. (Not a lasting safe zone — they can wander back.)
• Gjall familiar no longer drips tar, and its (and the Fallen Valkyrie's) particle effects are scaled down to match the mini-pet size.

5.14.0

• Familiar fixes. The Drake Hatchling now animates instead of freezing; a harmless "Can't remove Humanoid" log spam on some familiars is gone; Volture, Gjall, and Fallen Valkyrie hover a bit higher and read more clearly.
• Spawn/despawn effect. A small puff of effect plays when a familiar appears (helmet equipped) or disappears (unequipped).

5.13.0

• Familiars. The armor-effect category is now eight miniature flying creatures — Bat, Ghost, Deathsquito, Drake Hatchling, Wraith, Volture, Gjall, and Fallen Valkyrie — that hover at your shoulder, bound to your equipped helmet (which gains a matching name suffix). Other players running the mod see them too. Priced by progression tier (400–1300 Valcoins).

5.10.0

• Armor effects. New armor_vfx shop effect attaches a cosmetic aura to a chosen equipped armor piece, broadcast to other players via ZDO. (Reworked into Familiars in 5.13.)

5.9.0

• Native panel skin + purchase confirmation. The donation panel is restyled to match Valheim's own UI, and clicking Buy now opens a Yes / Cancel confirmation before any Valcoins are spent.

5.8.0

• Grouped shop. The Shop tab now groups items into categories (Soulkeeper Charms, Familiars, Feasts, Meads, Supplies) with one description per category, instead of one long flat list.

5.7.0

• Soulkeeper Charm. A new death-insurance consumable: on death you keep your skills (no skill drain) and a Valkyrie carries you from the spawn point back to your tombstone. Bought as stackable charges; backend-tracked.
• Removed cosmetic chat perks. The donor badge and chat title were removed — on a dedicated server their chat rendering was unreliable. Replaced by the Soulkeeper Charm and other consumables.

5.3.0

• One combined panel, one hotkey. The separate F4 "Codex" and F8 "quick panel" are merged into a single donation panel — open it with F4 (the F8 hotkey was removed). Tabs: Donate, Shop, Gift, Patrons, and Admin (admins only).
• Reworked Donate tab. Clicking "Get my donation code" now shows the code inline, right below the button, with a Copy code button and an Open donation portal button that launches your default web browser (no more copy-pasting a raw link). Clear step-by-step instructions live on the same tab.
• Anti-spam cooldown on generating a donation code (30s), with a live countdown.
• Terms of Use link on the Donate tab opens an in-game modal with the donation terms.
• Fixed the "square" icons. Valheim's in-game font can't render emoji, so every emoji in the UI and server messages was replaced with clean text — no more blank squares.
• More readable buttons — the primary donate action uses a high-contrast gold style.

5.2.0

• Removed all chat and console commands (/donate, /coins, /shop, /buy, /gift, /topdonors, /title, /givecoins, /removecoins). The chat-command hook proved unreliable on servers running other chat-patching mods; the F4 Codex and F8 panel already covered every action over a reliable silent RPC.
• ⚠️ Breaking: the plugin is now required client-side to use the donation system at all. Vanilla (un-modded) clients can no longer donate/shop/gift — only players running the plugin can open the F4/F8 panels. A passive donor-badge/chat-title chat prefix still works for everyone.
• New Admin tab (F8 panel): give/remove a player's Valcoin balance from the UI, replacing the removed /givecoins//removecoins commands. Only visible to Steam64 IDs listed in valcoin_admins.yaml.

5.1.0

• F8 panel now tracks live backend reachability, same as the F4 Codex: it polls periodically while open, flips an online/offline state on real fetch success/failure (not just "config has a URL"), and dims the Buy/Donate/Gift buttons while offline.
• Shop catalog now syncs to remote clients over RPC. Previously valcoin_shop.yaml only existed on whichever machine loaded it, so vanilla/remote clients connecting to a dedicated server saw an empty shop. The server now broadcasts its parsed catalog to every connected client every 30 seconds.

5.0.0

Initial public release.

• Valcoin economy: /donate, /coins, /shop, /buy, /gift, /topdonors, /title, plus admin /givecoins and /removecoins.
• Four donation providers: Ko-fi, PayPal, Patreon, PayMongo — each independently optional, verified via its own webhook signature.
• F4 Donation Codex: browsable, offline-resilient home for the economy, shop catalog, and patron leaderboard. Lights up automatically when the backend comes online — no client update needed.
• F8 quick panel: Donate / Shop / Gift / Top tabs for players who also run the plugin.
• Mouse-cursor fix for both panels — click and navigate with the mouse instead of hotkeys only.
• grant_item shop effect: weekly-capped, boss-gated consumable items (hard-to-cook food, meads, rare materials) spawned directly into the buyer's inventory — works for vanilla clients too.
• Vanilla-client compatible: every command works via chat even without the plugin installed client-side.