HearthstoneMod (Valheim 1.0)

A craftable "Hearthstone" item. Activate it (right-click in inventory, or hotbar

• use key) to teleport instantly to your bed spawn point with your full inventory intact. Reusable, never consumed, 10-minute cooldown by default. It never goes through Valheim's portal system, so it isn't affected by the usual portal restrictions (metal/ore blocking, linked-portal pairing, etc.) - it just moves you.

What's in this project

• Plugin.cs - BepInEx entrypoint. Registers the item (cloned from the vanilla "AmberPearl" prefab), its Workbench recipe, its icon, and its localized name/description. Also owns the BepInEx config entries.
• TeleportPatch.cs - a Harmony patch on Humanoid.UseItem that intercepts only the Hearthstone, enforces the per-item cooldown, checks you have a bed spawn point, and calls Player.TeleportTo directly.
• Assets/hearthstone_icon.png - a small original icon generated for this mod (a dark stone with a glowing rune).
• HearthstoneMod.csproj - project file. References BepInEx, Jotunn, and your own copy of Valheim's game assemblies via the VALHEIM_INSTALL environment variable (see below).
• manifest.json - Thunderstore-style metadata, only needed if you want to package this for r2modman/Thunderstore later.

Prerequisites (already true on this PC as of the last check)

1. Valheim 1.0 - installed at H:\SteamLibrary\steamapps\common\Valheim.
2. .NET SDK - a .dotnet folder already exists in your Windows user profile, which usually means it's installed; confirm with dotnet --version in PowerShell (see Build below). If that prints "not recognized," install it from https://dotnet.microsoft.com/download first.
3. BepInEx + Jotunn - already installed and active, managed through Thunderstore Mod Manager under the profile named "Valheim". That matters for this project specifically: TMM/r2modman don't put mods straight into <Valheim>\BepInEx\plugins - the real, active plugins folder is nested at:

   H:\SteamLibrary\steamapps\common\Valheim\BepInEx\plugins\Valheim\profiles\Valheim\BepInEx\plugins
   

   HearthstoneMod.csproj is already pre-configured with this exact path (via the BEPINEX_ROOT property), so you don't need to set anything - it'll build and deploy to the right place automatically.
4. Jotunn is already installed there as ValheimModding-Jotunn (v2.30.0), which is what manifest.json's dependency is pinned to, matching denikson-BepInExPack_Valheim-5.4.2333 also already installed.

Heads up: your modpack already includes a mod called IceHearthPatriots-Awakened_Hearthstone, which sounds like it might do something similar. Worth a quick look at what that one does before you go to the trouble of running your own alongside it - no conflict is likely since this project uses its own unique internal item/prefab name (Hearthstone), but you may not need both.

You need your own legitimate copy of the game - this project only ever references your assembly_valheim.dll etc. to compile against; it never copies or redistributes them, and you shouldn't either.

Build

No environment variables to set on this machine - the defaults in HearthstoneMod.csproj already point at your real install and profile paths. Just, from this project folder in PowerShell:

dotnet --version        # sanity check - should print a version number
dotnet build -c Release

That's it. The build automatically copies HearthstoneMod.dll and the Assets folder into the profile's BepInEx\plugins\HearthstoneMod\ (see the DeployToGame target in the .csproj), so you can just launch Valheim through Thunderstore Mod Manager afterwards and craft one.

If you ever move Valheim, switch Steam libraries, or rename/recreate the "Valheim" profile in the mod manager, update the VALHEIM_INSTALL and/or BEPINEX_ROOT values at the top of HearthstoneMod.csproj (or set them as environment variables, which override the defaults) to match.

Playing

• Craft a Hearthstone at a Workbench (default cost: 5 Fine Wood, 2 Silver, 5 Greydwarf Eye - all tunable, see Configuration below).
• Set a bed spawn point as normal (sleep in / interact with a claimed bed).
• Right-click the Hearthstone in your inventory (or bind it to a hotbar slot and press the use key) to teleport home instantly.
• It's a single reusable item - keep it in your inventory. After each use it goes on a 10-minute cooldown (shown in its tooltip, enforced per-item and saved with your character so relogging doesn't reset it).

Configuration

After the first run, BepInEx writes BepInEx\config\com.ricky.hearthstonemod.cfg. Edit it while the game is closed (or with a config-manager mod while it's running):

[General]
CooldownSeconds = 600
RequireBedSpawnPoint = true

[Recipe]
FineWood = 5
Silver = 2
GreydwarfEye = 5

Troubleshooting / adapting to a newer game patch

This was written against the publicly documented Jotunn API and the commonly-referenced Valheim internals (Player.TeleportTo, Player.m_teleportEffects, PlayerProfile.GetCustomSpawnPoint, Humanoid.UseItem, ItemDrop.ItemData.m_customData). Valheim occasionally renames or reshuffles internal fields between patches. If dotnet build reports a missing member:

1. Open your own valheim_Data\Managed\assembly_valheim.dll in a decompiler (dnSpy or ILSpy, both free) - this is your own legally-owned copy, so decompiling it locally to check a method signature is fine.
2. Search for the type mentioned in the error (e.g. Player, Humanoid, PlayerProfile) and find the closest-named current member.
3. Update the corresponding line in Plugin.cs / TeleportPatch.cs to match.

The two most likely drift points are Player.TeleportTo's exact parameter list and the name of the teleport VFX field - both are small, isolated one-line fixes if they've changed.

Publishing to Thunderstore

Yes, this can be posted for other players. A Thunderstore package is just a zip with icon.png, README.md and manifest.json at the root (not inside a subfolder), plus your mod's own files. This repo already has everything Thunderstore requires:

• manifest.json - name, version, description (204/250 chars), and pinned dependencies on denikson-BepInExPack_Valheim-5.4.2333 and ValheimModding-Jotunn-2.30.0 - pinned to match what's actually installed and tested on your machine, not necessarily the newest versions on Thunderstore. That's the safer choice for something you've verified works; bump them later if you want to track newer releases.
• icon.png - a 256x256 package icon (required exact size).
• README.md - this file; Thunderstore renders it as your mod's page.
• CHANGELOG.md - optional but expected by most users.

To assemble the actual upload zip after building, run scripts\package_for_thunderstore.ps1 (or the .sh version on Linux/macOS). It copies the built DLL, Assets\, and the four files above into a flat thunderstore_package\ folder and zips it as HearthstoneMod-thunderstore.zip - that's the file you upload, not the source zip.

To actually publish:

1. Create a Thunderstore account and log in at thunderstore.io (OAuth via Discord/GitHub).
2. Create a team for yourself (or use an existing one) - packages are owned by teams, not individual accounts, from your account settings.
3. Go to the Valheim community's upload page (thunderstore.io/c/valheim/create/) and submit HearthstoneMod-thunderstore.zip. Thunderstore validates the zip structure and manifest for you and will point out anything wrong.
4. For future updates, bump version_number in manifest.json (and add a CHANGELOG.md entry) before re-packaging and re-uploading.

There's also a tcli CLI and a GitHub Action (thunderstore-upload-package) if you'd rather automate publishing from CI instead of using the web form - worth it once you're iterating on updates.

One thing to flag: the mod is licensed implicitly as "all rights reserved" by default since there's no LICENSE file. Thunderstore doesn't require one, but if you want other modpack makers to be able to bundle your mod freely, consider adding one (MIT is the common choice in the Valheim modding scene) before you publish.

Notes on "bypasses all portal restrictions" and "no gear loss"

Both fall out naturally from the approach rather than needing special-casing:

• We never call into Portal/TeleportWorld at all, so none of the checks that system applies (linked portal required, certain ores/metals blocked, etc.) ever run for this item.
• Valheim doesn't drop your gear on a direct position teleport - that's only a death mechanic. Player.TeleportTo just moves you, inventory intact.

Changelog

1.0.5

• Found and fixed the REAL bug behind the teleport never firing - it's been here since 1.0.0. Your BepInEx log had it in plain text the whole time: [Error:HarmonyX] Failed to patch void Humanoid::UseItem(...): System.Exception: Cannot get result from void method. Our prefix declared a ref bool __result parameter, which tells Harmony "the original method returns bool, hook its return value" - but on this game version, Humanoid.UseItem actually compiles to a void method, not bool. That mismatch made Harmony refuse to weave the patch in AT ALL, silently, on every single load since the mod's first release - not because of ItemType (1.0.3) and not because of Player's override (1.0.4's theory - a real and still-worthwhile defensive fix, kept in this version, but not what was actually broken). Removed __result entirely; the prefix now just returns bool to tell Harmony whether to run vanilla's code afterward, which was always the only thing that return value needed to do. This is the fix that should finally make the Hearthstone actually teleport you.

1.0.4

• Fixed the Hearthstone playing the food/consumable sound and vanishing instead of teleporting (the 1.0.3 fix made it activate instantly on right-click, but our Harmony patch still never actually ran). Cause: Player overrides Humanoid.UseItem with its own compiled method, so patching typeof(Humanoid), nameof(Humanoid.UseItem) only patched the base class's copy - the game was really calling Player's own override, which our patch never touched, so vanilla's normal "consumable" handling ran instead (eat sound, then destroy the item). Now explicitly locates and patches whichever method actually runs on both Humanoid and Player, so this can't silently miss again. Also added a temporary diagnostic log line so future issues like this show up immediately in the console instead of just failing silently.
• Swapped Silver out of the recipe for Leather Scraps (5, configurable). Silver needs a Mountain-biome pickaxe and smelting - way too late-game for an item meant to be craftable early. Recipe is now FineWood x5, LeatherScraps x5, GreydwarfEye x5 (all editable in the BepInEx config file).

1.0.3

• Fixed the Hearthstone doing nothing when used (showed vanilla's "Use Hearthstone on what?" prompt instead of teleporting). The item was cloned from AmberPearl, which is an ItemType.Material - right-clicking a Material item never calls Humanoid.UseItem, so our activation patch never ran. Now explicitly set to ItemType.Consumable (same category as potions/food), which activates instantly on right-click like intended.

1.0.2

• Rewrote README.md - it had personal/machine-specific build notes in it that don't belong on a public listing page. No functional changes.

1.0.1

• Added a guaranteed-to-render warm light burst effect at both ends of the teleport (departure and arrival), built from plain UnityEngine primitives so it doesn't depend on any specific Valheim asset name.

1.0.0

• Initial release: craftable Hearthstone item, Workbench recipe, teleport-to-bed on use via Harmony patch, 10-minute per-item cooldown, configurable recipe cost and cooldown.