Unstable Portals: Metal Transport

A client-side Valheim mod for BepInEx that lets players transport metal and other normally restricted items through portals by paying a configurable toll. The default is 1 Surtling Core and 5 Greydwarf Eyes per successful trip, with portal damage and audiovisual instability warning of the risk.

Behavior

• Ordinary portal travel remains free.
• If the inventory contains one or more portal-restricted items, the player must also carry the configured toll. The default is 1 Surtling Core and 5 Greydwarf Eyes.
• The toll is consumed only after Valheim accepts the teleport.
• The price is per trip, not per stack, item, or unit of metal.
• By default, the source and destination portals each take damage equal to 10% of their maximum health. They can be repaired normally.
• When the toll is available, the portal's existing particle animation and light slowly pulse from dark orange to purple and back. By default, the glowing frame runes pulse in the opposite phase, suggesting unstable energy moving between the portal and its frame. No custom model or animation is added.
• The portal's existing sound also wobbles at a slightly deeper pitch while that instability effect is active. This uses the built-in audio source; no sound file is added.
• Ordinary items flagged by Valheim as non-teleportable count. This includes metals and ores. Items marked by Valheim as absolutely blocked remain blocked.
• Toll items inside a cart or container do not count; they must be in the player's inventory.

Installation

1. Install the current BepInExPack for Valheim.
2. If upgrading from version 1.2.0 or earlier, delete the pre-rename DLL first. Do not leave both DLLs installed.
3. Create BepInEx\plugins\UnstablePortalsMetalTransport in the Valheim game folder.
4. Copy UnstablePortalsMetalTransport.dll into that folder.
5. Start Valheim through the mod manager or BepInEx-enabled launcher.

For multiplayer, install the mod on every player's client. A dedicated-server-only installation is not sufficient because the player's client owns this portal interaction.

Configuration

After the game starts once with the mod installed, edit:

BepInEx/config/com.kernelpanik.unstableportalsmetaltransport.cfg

Version 1.2.2 completes the mod rename by changing its internal plugin identity. BepInEx therefore creates a new configuration file. After launching once, copy any customized values from your previous configuration into the new file.

The available settings are:

Set either item cost or the damage percentage to 0 to disable that part. Set either portal-damage toggle to false to protect that side. In multiplayer, use the same configuration on every player's client for consistent tolls.

For a higher, more strained sound, try MinimumPitchMultiplier = 1.04 and MaximumPitchMultiplier = 1.18. Set both pitch values to the same number for a steady pitch shift instead of a wobble.

Build from source

Requirements:

• The current PC version of Valheim
• BepInExPack for Valheim installed in the game directory
• .NET SDK capable of targeting .NET Framework 4.6.2

From PowerShell:

.\build.ps1

If Valheim is not in the default Steam location:

.\build.ps1 -ValheimPath "D:\SteamLibrary\steamapps\common\Valheim"

The output DLL is written to bin\Release\net462\UnstablePortalsMetalTransport.dll.

Compatibility notes

The mod uses BepInEx and Harmony but does not require Jötunn. It resolves Valheim gameplay types at runtime so moving those types between game assemblies does not by itself break the mod. Other mods that completely replace portal logic may conflict.

Version 1.2.2 targets Valheim 1.0.14's current portal flow. Keep a normal world/character backup before testing any new mod.

Uninstall

Delete UnstablePortalsMetalTransport.dll from BepInEx\plugins. The mod does not add items or save custom world data.

Changelog

1.2.2

• Completes the rename by changing the plugin GUID to com.kernelpanik.unstableportalsmetaltransport.
• Changes the generated config filename to com.kernelpanik.unstableportalsmetaltransport.cfg.
• Removes the remaining legacy project-name references from current source, documentation, and package metadata.
• Existing customized settings must be copied once from the previous config file.

1.2.1

• Renames the mod to Unstable Portals: Metal Transport.
• Renames the assembly, DLL, project, installation folder, and release packages to UnstablePortalsMetalTransport.
• Temporarily retains the preceding plugin GUID and config filename so existing 1.2.0 settings continue to work.
• Requires the pre-rename DLL to be removed during upgrade so BepInEx does not find duplicate copies of the same plugin.
• Adds Hexium/Thunderstore package metadata and a 256-by-256 package icon.

1.2.0

• Adds a configurable pitch wobble to the portal's existing sound while the restricted-item instability effect is active.
• Defaults to a deeper 0.82-to-0.96 pitch range; both endpoints can be configured or the audio effect can be disabled.
• Restores the portal's original pitch as soon as the toll effect ends.
• Changes the plugin identity and project author metadata to KernelPanik.
• Moves the generated config filename into the KernelPanik plugin namespace.

1.1.4

• Raises the frame-rune colors into HDR emission range so the inverse pulse remains visible instead of appearing black.
• Adds Visuals.RuneBrightnessMultiplier, default 3, for adjusting rune brightness and bloom.

1.1.3

• Moves the instability animation from a Harmony patch on TeleportWorld.Update() to the mod's own reliable per-frame update loop.
• Keeps Valheim's normal half-second portal eligibility check while animating all active toll portals every frame.

1.1.2

• Pulses the portal frame emission/runes in the opposite color phase from the particles and light by default.
• Adds Visuals.InverseRunePulse; set it to false to make the frame, particles, and light pulse together.

1.1.1

• Replaces the static purple toll color with a smooth 2.6-second dark-orange-to-purple instability pulse.
• Applies the pulse to the existing portal emission, particles, and light without adding assets.
• Runs the visual pulse at frame rate while retaining the normal half-second eligibility check.

1.1.0

• Changes the default restricted-item toll to 1 Surtling Core and 5 Greydwarf Eyes.
• Damages both the source and destination portals by 10% of maximum health after a successful paid trip.
• Adds BepInEx configuration for both item costs, the damage percentage, and independent source/destination damage toggles.
• Queues destination damage until the linked portal loads, then applies it through Valheim's networked WearNTear damage path.

1.0.3

• Tints the existing portal model glow, particle animation, and light purple while nearby restricted cargo can pass by paying a Surtling Core.
• Restores the portal's original colors as soon as the toll condition no longer applies.
• Adds no custom models, textures, or animations.

1.0.2

• Correctly patches Valheim 1.0.14's Humanoid.IsTeleportable(bool) method, allowing the portal's normal active effect when the toll can be paid.
• Correctly patches the Player.TeleportTo(...) override so one Surtling Core is removed after a successful portal teleport.
• Does not charge when a teleport fails to start or when the portal/world already allows the cargo for free.

1.0.1

• Updated the patch points for Valheim 1.0, which removed Humanoid.IsTeleportable().
• Hooks TeleportWorldTrigger.OnTriggerEnter and Character.TeleportTo so the Core is charged only when portal travel starts successfully.
• Temporarily relaxes eligible item restrictions only during the portal trigger, then restores them immediately.
• Keeps Valheim's absolute item restrictions blocked and keeps allow-all-items portals free.

1.0.0

• Initial release.
• Allows portal travel with Valheim-restricted inventory items when carrying a Surtling Core.
• Consumes one Surtling Core only after a portal teleport succeeds.
• Adds center-screen feedback for the requirement and successful payment.