Cross Server Portals Continued

Connect Valheim servers and local worlds through ordinary portals.

Community-maintained fork: This project is a Valheim 1.0-compatible continuation of lunar91/lunarbin's Cross Server Portals. The original design and implementation belong to lunar91 and contributors. This fork is distributed under the same GPL-3.0 license and is not an official lunar91 release.

Recommended companion: PortalPass

For seamless travel between password-protected servers, pair this mod with PortalPass on Thunderstore (source on GitHub). PortalPass is an optional client-only companion that supplies passwords from a private file the player controls, so cross-server portal trips do not stop at a password prompt. It never records or learns passwords automatically.

Compatibility

• Valheim 1.0 / dedicated server network version 39
• BepInExPack Valheim 5.4.2350 or newer compatible release
• Install on every client and server participating in cross-server travel

The plugin GUID and DLL name remain unchanged so existing configuration is retained when upgrading from the original mod. Remove the original DLL before installing this package; do not run both versions together.

Installation

Copy ValheimCrossServerPortals.dll into BepInEx/plugins/CrossServerPortals/ on each client and server.

Portal tags

Use one of these formats:

SourceTag|server.example.com:2456|TargetTag
SourceTag|192.0.2.10:2456
SourceTag|[2001:db8::10]:2456|TargetTag
SourceTag|world:My Local World|TargetTag

• SourceTag identifies the departure portal.
• TargetTag is optional. On arrival, the mod looks for either that ordinary tag or a cross-server portal whose source tag matches it.
• A server address without a port uses Valheim's default port, 2456.
• IPv6 addresses with a port must use brackets.
• world: destinations switch to a local world by name.

Cross-server portals ignore Valheim's ordinary item teleport restrictions, matching the behavior of the original mod.

Configuration

• PreserveStatusEffects — preserve effects such as rested and wet across a mod-driven transfer.
• RecolorPortalGlyphs / CustomPortalGlyphColor — identify cross-server portals visually.
• RecolorPortalEffects / CustomPortalEffectColor — customize their particle effects.
• PromptBeforeTeleport — request confirmation before leaving the current server.
• RequireAdminToRename — server-synchronized restriction for cross-server portal tags.
• LockAdminConfig — lock synchronized administrator configuration.

What changed in this continuation

• Restored Valheim 1.0 compatibility using the new flattened portal-list API.
• Replaced asynchronous thread-pool delays with Unity coroutines.
• Preserved the calculated safe exit position after the destination finishes loading.
• Limited periodic portal enumeration to servers and compare portals by stable ZDO ID.
• Reworked portal-tag validation for safer DNS, port, world-name, and IPv6 handling.
• Updated deprecated particle-system calls and improved null safety.
• Added repeatable Linux builds, parser tests, CI, and Thunderstore-ready packaging.

See CHANGELOG.md for release history and docs/PUBLISHING.md for maintainer release instructions.

Building

Set VALHEIM_GAME_PATH to a Valheim installation containing BepInEx, then:

dotnet test tests/CrossServerPortals.Tests.csproj
dotnet build CrossServerPortals.csproj -c Release
dotnet msbuild CrossServerPortals.csproj -t:Package -p:Configuration=Release

The Thunderstore-ready archive is written to artifacts/.

Credits and license

• lunar91 — original author and architecture
• Wacky-Mole — original admin permission work
• ServerSync — server-authoritative configuration

Licensed under GPL-3.0. Git history from the upstream repository is preserved.

Changelog

1.3.2 - 2026-09-10

• Recommend and link the optional PortalPass companion for seamless travel between password-protected servers.
• Documentation-only package update. The included plugin DLL is unchanged from the tested 1.3.1 release; there are no gameplay or configuration changes.

1.3.1 - 2026-09-09

• Replace the inherited package icon with an original two-world portal emblem.
• No gameplay or configuration changes.

1.3.0 - 2026-09-09

• Add Valheim 1.0 compatibility.
• Replace background-thread delays with Unity coroutines.
• Keep players at the calculated safe portal exit after loading.
• Restrict portal tracking to the server and compare stable ZDO identifiers.
• Improve portal-tag validation, including world names with spaces and bracketed IPv6.
• Default omitted server ports to 2456.
• Update particle APIs and improve visual-effect null safety.
• Add automated parser tests and reproducible release packaging.

Earlier releases

Versions 0.1.0 through 1.2.0 were released by lunar91. See the preserved Git history and upstream repository for their full notes.