PortalRules

PortalRules adds map-based portal travel, access modes, portal limits, Admin portals, and optional Coins fares to Valheim.

The server filters the portal catalog for each player and authorizes every handled trip. Clients receive catalog entries only for portals they are allowed to use.

This source targets Valheim 1.0.7 and BepInExPack Valheim 5.4.2350. Jotunn is no longer required by PortalRules. Other installed mods may still require it. Install PortalRules on the server and clients; its existing ServerSync configuration/version checks remain in place.

All-items portals bypass ordinary material restrictions, while respecting Valheim's absolute item restrictions. Blocked travel is rejected before opening the destination map. Implementation details and the remaining in-game validation checklist are in the 1.0.7 compatibility notes.

Showcase

Portal map and favorites

Browse every portal available to your character from the destination map. Pin overlays show travel restrictions, Coins fares, ownership limits, access modes, and portal tags.

Favorites provide quick travel rows and focus the map on a destination when hovered.

Access modes

Cycle access modes at the portal, then identify Public and reciprocal Tagged connections at a glance.

Clan portals expose their bound access and quota state both on the map and in hover details.

Invite portals use dedicated map and hover indicators, with cooldown feedback when travel is temporarily unavailable.

Admin and location portals

Admin portal pieces appear to server administrators in debug mode. Their controls are protected, and Required GlobalKeys can gate progression.

Admin portals can also be embedded into generated world locations.

Expand World Data can place Admin portals inside generated locations. Add an Admin portal object under each target prefab in expand_locations.yml, then reset the affected location instances to generate the new portals.

- prefab: BogWitch_Camp
  objects:
  - admin_portal_stone, 0,15,0.5, 180,0,0

- prefab: Hildir_camp
  objects:
  - admin_portal_stone, -0.5,14,-0.5, 180,0,0

- prefab: Vendor_BlackForest
  objects:
  - admin_portal_stone, -7,7,-0.5, 135,0,0

Adjust the position and rotation for each location. Editing the YAML does not modify instances that already exist until those locations are reset.

Quick start

When Enable Portal Map is On, enter a handled non-Tagged portal to open the destination map. Select an accessible portal pin to travel.

If the source portal does not allow all items, carrying a non-teleportable item shows Valheim's item restriction message without opening the map. Portals that allow every item show All Items Teleportable above their hover details.

The arrow beside Favorite Portals collapses the list. Its state is saved locally.

Access modes

Normal portals cycle:

Personal → Admin → Public → Invite → Clan → Tagged

Unavailable modes are skipped. Admin portal prefabs default to Public and cycle only:

Admin → Public → Tagged

An ordinary portal's modes may be cycled by its immutable Builder, Primary or Guest members of the Builder's current primary Clan, or a server administrator in debug mode. Invite entry and exit remain Builder-only. Personal, Clan, and Tagged attribution always comes from that Builder, not the player interacting with it. If the Builder has no resolvable primary Clan, only the Builder or an administrator in debug mode may change it.

A Required GlobalKey, when present, is checked in addition to the access mode.

Key defaults

All settings are documented in sighsorry.PortalRules.cfg. Map keys, auto-close grace, map zoom, and the access modifier are client-local; the remaining gameplay rules are server-synchronized and can be locked by the server.

Setting an effective Invite limit to 0 returns eligible Invite portals to their Builder's Personal mode. Raising the limit later does not restore Invite automatically.

Public expiry uses an absolute UTC deadline, so server downtime and unloaded regions still count. Admin portal prefabs and Builderless portals are excluded from that timer.

Disabling Enable Account Portal Limit bypasses only the overall account limit and portal_limit overrides. Invite and Clan limits remain active.

Overall and Invite limits are shared by every character on the authenticated Steam account. The configurable default counted prefabs are portal_wood, portal, and portal_stone; Admin portals and normal portals with neither a valid Builder nor a creator ID are excluded. Lowering the overall limit never destroys existing portals.

Portal map and favorites

• Favorites survive world reloads, but dismantling and rebuilding creates a new portal identity.
• Rows stay in add order from oldest to newest; re-adding one moves it to the bottom.
• At the 10-favorite limit, a new favorite may replace the oldest saved portal that is no longer available.
• Invite cooldowns and fares appear on pins or favorite rows.
• My portal n/limit, Invite n/limit, and Clan n/limit show quota positions.
• Tagged Admin portal prefabs remain usable as connected portals by every eligible player, but their map pins are visible only to server administrators in debug mode.

If Enable Portal Map is Off, PortalRules uses connected destinations for all modes while still applying server authorization.

The CONNECTED hover label is shown only for Tagged portals with a reciprocal connection. Other access modes omit the connection status label.

Admin portals and GlobalKeys

Admin Wood and Admin Stone appear under Hammer → Misc only for server administrators in debug mode. They are creatorless, Builderless, quota-exempt, and restricted to Admin, Public, and Tagged access. Their Tagged mode is a separate public connection pool; Required GlobalKeys still apply.

Placed frames are invisible and non-solid, with a whirling marker while a player is nearby. Placement, editing, and dismantling require administrator debug access; dismantling returns no resources.

Use physical Alt + Interact to set or clear a Required GlobalKey. Without YouAreNotWorthy, PortalRules checks shared world GlobalKeys. With a compatible YNW API, ordinary progression keys can be evaluated per character.

Coins fares

fare = ceil(non-teleportable cargo weight
          × XZ distance in kilometers
          × Coins Per Weight Kilometer)

In Pay mode, a restricted source portal keeps its whirling effect active for payable cargo and opens the destination map. Map pins and favorite rows show the calculated fare. Tagged portals keep direct connected travel and show the same fare in the connected hover badge. All-items portals and the TeleportAll world modifier remain free because they already allow the cargo.

The server calculates the route and final fare from the client cargo-weight snapshot, and the client verifies that exact weight again before taking Coins and starting the teleport. Denied trips and teleports that fail to start do not consume Coins. Valheim 1.0's absolute item restrictions remain blocked in both modes.

Server files

PortalRules stores server-only data under BepInEx/config/PortalRules/.

Account overrides

format_version: 2
overrides:
  "76561198000000000": 10
  "76561198000000001": 10, 1

The first value is portal_limit. The optional second value is invite_limit; when omitted, it follows the global Invite setting.

Values are -1 for unlimited, 0 to block or disable, or 1..10000 for a custom limit.

Use overrides: {} to clear the table. Invalid reloads keep the last valid data. Because Invite-to-Personal conversion is one-way, load positive or unlimited exceptions and wait for the successful Loaded ... account limit override(s) server log before changing the global Invite limit to 0.

Admin portal biome keys

format_version: 1
biomes:
  Meadows:
  BlackForest: defeated_eikthyr
  Swamp: defeated_gdking
  MyCustomBiome:

An empty value means no requirement. The file is generated once with vanilla biomes and registered Expand World Data biome identifiers. For custom biomes, use the stable biome: identifier rather than a translated name or runtime number.

Biome defaults apply only when a new Admin portal first receives authority. They do not rewrite existing portals. An explicitly stored value, including an explicit empty value, overrides the biome default.

World-editing mods

• InfinityHammer blueprints must use data=true; creatorless normal-portal materialization restores only a complete current PortalRules authority stamp in Public mode. Use an Admin portal prefab for creatorless Tagged connections.
• After zones_reset, run a non-empty zones_generate or visit the zone to recreate the portal.
• In Expand World Data locations, put PortalRules RequiredGlobalKey in child objectData or locationObjectData. Explicit child or blueprint data overrides the biome default.

Misc

Optional integrations:

• Clan API v4 on the server for Clan access; without it, Clan selection and non-Builder access fail closed
• A compatible YouAreNotWorthy installation for character GlobalKeys and its localized missing-key message when available

If YouAreNotWorthy is installed but its compatible API is unavailable, key-gated portals fail closed.

Changelog

1.0.5

• Simplified fare options to (distance)*(weight of non teleportable items)*k

1.0.4

• Updated PortalRules for Valheim 1.0.7, including portal registration, portal-list access, map pointer/right-click handling, hover status formatting, and changed game method signatures.
• Removed the hard Jotunn dependency. Admin portal cloning, network-scene and Hammer registration, cleanup, and UI font selection are now owned by PortalRules while preserving the existing admin portal prefab names and hashes.
• Preserved portal authority changes in Valheim's separate portal save chunk, including admin creator metadata, and made server-world readiness idempotent across the new load path.
• Applied Valheim's absolute item restrictions to all-items portals and prevented refund overflow from creating world drops before CurrencyPocket fallback, reducing item loss or duplication risk.
• Updated the bundled ServerSync to the reviewed valheim-1.0.7-r1 build, preserving configuration/version contracts while fixing 1.0.7 API access and connection-initialization message ordering.
• Updated the required BepInExPack Valheim dependency to 5.4.2350 and added client/dedicated static compatibility and focused behavior checks.

1.0.3

• Show CONNECTED only for Tagged portals with a reciprocal connection; hide connection status in other access modes.
• Check restricted items before opening the portal map and again after server approval, showing Valheim's item restriction message when travel is blocked.
• Add an All Items Teleportable header above portal hover details, with English and Korean translations.
• Remove restricted-item icons from map pins and favorites, and reduce the favorites panel width from 320 to 292. Travel validation, fares, and Invite cooldown indicators remain in place.
• Reduce redundant portal checks, repeated UI lookups, and allocations in idle travel-ticket and reservation cleanup paths.
• Support automatic local Debug DLL deployment through DeployToGame=true after assembly merging.

1.0.2

• Fixed dedicated-server character verification blocking portal use and access-mode changes.
• Fixed authenticated server admins being unable to place Admin portals on dedicated servers.
• Added safe Public handling for creatorless server and location portals.

1.0.1

• Fixed portal catalog updates occasionally being missed after portal changes.
• Enforced Tagged portal connection scopes even when Portal Map is disabled.
• Improved compatibility and payment handling for CurrencyPocket.
• Reduced unnecessary server synchronization traffic and improved state-file write safety.
• Improved resilience to Valheim UI and portal connection API changes.

1.0.0

• Initial release.