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.

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.

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, fares, and blocked-item marks 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.

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 = Base Coin Cost
     + ceil(Coins Per Kilometer × max(0, XZ distance − included distance) / 1000)

The server calculates the route and final fare. Denied trips and teleports that fail to start do not consume Coins. Carried-item restrictions always follow the source portal's own item rule.

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.0

• Initial release.