Clan

A server-authoritative clan system for Valheim, integrated into the vanilla chat UI.

Showcase

Clan panel and management

Open the Clan panel directly from gameplay, then browse clans and players, search the directory, apply or invite, and manage member roles.

Leaders can update the clan name and description and choose an emblem from the server's media catalog.

Clan chat and notifications

Clan chat is attached to the vanilla chat UI, while the movable HUD keeps the active clan and online members visible during play.

The view filter switches between all, clan, local, and global messages without changing the selected sending channel. Pending invitations and applications are surfaced through the Clan control.

Emoji and animated GIFs

Open the five-column emoji picker from chat to insert server-synchronized PNG or GIF emoji. Animated GIFs play directly in supported chat messages.

Features

• Create, browse, search, and manage clans
• Leader, Officer, Member, and Guest roles
• Clan chat with All, Clan, Local, and Global view filters
• Clan-only map pings and optional position sharing
• Movable clan HUD with online player health
• Server-synchronized PNG/GIF emoji and PNG emblems
• English and Korean localization

Quick start

Action	Default control
Open or close the Clan panel	J
Open chat and the Emoji panel	H
Send a clan-only map ping	Hold Left Shift while using the vanilla map ping

Open the Clan panel to create a clan or apply to an existing one. Open vanilla chat to select a channel, insert emoji, filter visible messages, or open the Clan panel from the attached controls.

The Clan HUD starts expanded on the left side and shows up to 10 online players. Press F7 to cycle expanded, collapsed (header only), and hidden. The shortcut works with the inventory open or closed and ignores text entry and menus/dialogs. Set Clan HUD Toggle Shortcut to None to unset it; Clan HUD State still controls visibility. Both settings are client-only and the state persists across sessions.

Drag the HUD header to save a position, or use its arrow to switch between expanded and collapsed. Clan HUD Position remains visible in the configuration UI and uses normalized upper-left coordinates: X from the left and Y from the top, each from 0 to 1. Its default is (0.015, 0.32); reset this setting to restore the original left-side position. Existing custom positions are preserved. Existing Show Clan Member HUD and Clan HUD Player List Collapsed settings are converted once into Clan HUD State and removed. An already saved new state takes precedence.

Roles and Guest clans

A player may have:

• One primary clan role: Leader, Officer, or Member
• One persistent Guest connection to a different clan

While a Guest connection is active, the Guest clan is used for clan chat, HUD, pings, shared map positions, and friendly-fire checks. The primary membership remains stored and becomes active again after leaving or being removed from the Guest clan.

Accepted applications and invitations always start as Guest. Leaders and officers can manage eligible players from the roster; leadership transfer and clan profile management remain leader-only.

Full and Simple mode

1 - General / Mode defaults to Full. Set it to Simple on the server to use persistent, unnamed groups and a compact members/online-player panel. The server selects the active mode when the world starts. Configuration changes take effect on the next server/world start; clients use the server's active mode regardless of their local setting.

In Simple mode, invite an online, ungrouped player from the Players tab to start a group. Any member can invite, and the recipient must accept. An existing pending invitation is not overwritten. Each character can belong to one group. The group leader can remove other members or transfer leadership; there are no Officers, Guests, applications, profiles, names or emblems to manage. Leave requires a confirmation click.

Groups and invitations survive disconnects and server restarts. Disconnecting does not change the leader. When the leader explicitly leaves, leadership passes to the earliest-joined online member, or the earliest-joined remaining member if everyone is offline. The last member leaving deletes the group and its outstanding invitations. Offline members remain in the roster but receive no shared experience or quest credit.

Group chat, item links, HUD, map positions/pings, friendly-fire configuration and optional Epic MMO/QuestForge sharing use the current group. Distance, identity and duplicate-report checks remain in place. The existing J/H/F7 controls and client HUD settings also work in Simple mode. Group membership does not grant Clan-based ward or portal permissions.

Full clan data and Simple group data are stored separately. Switching modes does not convert or delete either store. Simple groups are identified by server-generated IDs; the internal storage name is that ID, not a user-editable clan name. All participants must use this same Clan build (RPC v15).

Optional combat and quest compatibility

Install the same Clan build and the relevant optional mod on the server and participating clients, including clients that own nearby creatures. Adapters are enabled by checking the required APIs and patch structure, without restricting either mod to a specific version number. Epic MMO must retain the combat XP methods, group multiplier and a uniquely matching injection point; QuestForge must expose the Manager and RegisterKill method. If these checks fail, only the affected adapter is disabled with a startup warning. This does not guarantee compatibility with every future change in either mod's behavior. Clan does not bundle either mod or require Jotunn; QuestForge retains its own dependencies.

Server-synchronized settings in 3 - Compatibility:

Setting	Default	Behavior
Share Epic MMO Experience	On	Shares combat XP with other online members of the effective clan, retaining Epic's group multiplier, recipient range, level curves and XP modifiers.
Share QuestForge Kills	On	Adds kill objective credit to nearby living clan members. Each player must accept their own quests; gathering, rewards and progress saves remain personal.
QuestForge Share Range	70	Maximum distance in metres from the killed creature for additional quest credit.

Guest membership takes precedence over primary membership for both features. No credit is sent to both clans, and the original killer is excluded from additional credit. These features do not add a separate temporary-party system or change Clan's existing incompatibility with Groups.

Epic combat sharing uses the base XP before the killer's personal level curve and the final effective monster level, including monster-specific XP/level overrides when provided. Each recipient still uses Epic's own group XP receiver for range, level curves and XP modifiers.

The relay checks connected identities and server-side clan membership. Quest reports also check the creature owner, prefab and death ID; very late reports or unrecognized ownership are rejected. Epic's native combat report has no unique death ID, so the relay rejects duplicate transport sequences but cannot identify independently repeated native kill reports. These checks do not make third-party combat or reward systems fully server-authoritative.

Custom emoji and emblems

The authoritative server loads media from:

BepInEx/config/Clan/emoji
BepInEx/config/Clan/emblems

For single-player and local hosting, place media in the local profile's folders. For a dedicated server, place media in that server installation's folders.

Clan does not embed a default media collection. Install an optional Clan media pack or copy your own files into these folders. This keeps the core mod small and lets server owners and modpack authors select their own catalog without replacing the Clan DLL.

Only the server or host's media catalog is published to connected clients. Remote clients first reuse valid files from the shared cache. When a cache entry is missing, Clan checks the same media-pack path and directly uses a byte-identical local file after verifying its length and SHA-256, without creating a cache copy. Any remaining files are downloaded automatically and added to the shared cache. Changes on the server or host are validated and reloaded automatically.

The legacy spritesheet.png format is not supported; use one image file per emoji.

Content	Limit
Emoji catalog	100 PNG/GIF files total, including up to 50 GIFs
Emblem catalog	50 PNG files
PNG	512 KiB, up to 512 × 512, 8-bit and non-interlaced
GIF	2 MiB, up to 512 × 512; animated GIFs: up to 180 frames and 10 seconds, infinite loop

Basenames must be unique within each folder, contain 1–32 characters, use lowercase a-z, digits, _, or -, and start and end with a letter or digit. Windows reserved names are not allowed, and extensions must be lowercase .png or .gif. The basename becomes the chat token:

wave.png      -> :clan_wave:
pink_math.gif -> :clan_pink_math:

GIFs are also limited to 8,388,608 decoded pixels per file and 3,000 frames across the full catalog. Invalid files are skipped and reported in the server log. Large GIF catalogs can use substantial system and graphics memory.

Each message may contain up to five recognized emoji tokens. Only the newest 15 GIF occurrences in the visible vanilla chat buffer animate; older GIFs remain visible on their first frame.

Clients download only missing media and keep a shared content cache under <Valheim save data>/Clan/cache. Downloads run in the background and do not block world entry.

Configuration and save data

Client and synchronized settings are stored in:

BepInEx/config/sighsorry.Clan.cfg

Main defaults are:

Setting	Default	Scope
Lock Configuration	On	Server-synchronized
Mode	Full (Full / Simple)	Server-selected at world start
Clan Friendly Fire	On	Server-synchronized
Share Clan Positions	On	Server-synchronized
Clan Ping Modifier Key	Left Shift	Client
Clan Chat Window Scale	1 (1–2)	Client
Clan Panel Shortcut	J	Client
Emoji Panel Shortcut	H	Client
Chat After Send	KeepOpen	Client
Clan HUD State	Expanded (Expanded / Collapsed / Hidden)	Client
Clan HUD Toggle Shortcut	F7 (None to unset)	Client
Clan HUD Position	(0.015, 0.32) (left side)	Client

Clan Friendly Fire = On allows clan-connected players to damage one another.

Clan data is stored under:

<Valheim save data>/Clan/

On Windows without -savedir, the default location is:

%USERPROFILE%\AppData\LocalLow\IronGate\Valheim\Clan

Path	Purpose
clans.yml	Clan registry
simple-groups.yml	Persistent Simple groups, invitations and join order (separate format 1)
recent-players.yml	Recent-player directory
cache/	Shared downloaded-media cache

Worlds and mod-manager profiles using the same Valheim save-data root share this persistent Clan data and downloaded-media cache. Their server media sources remain profile-specific under BepInEx/config/Clan. Use separate -savedir values for independent dedicated-server registries. Do not delete the save-data Clan folder unless you also intend to delete saved clan data.

Mod API

ClanApi.ApiVersion is 6. Server-side integrations can query authoritative primary and Guest memberships with ResolveMemberships, query ward access with ResolveWardAuthorization, and invalidate cached results through RegistryRevision and RegistryChanged.

In Simple mode, these Clan membership/ward lookups resolve to no membership/authorization, and Current/KnownClans expose no clans. Mode transitions invalidate registry authorization caches. ServerChatAccepted remains a Full clan event and is not raised for Simple group messages.

Fail closed when either lookup returns Unavailable.

API v5 adds the optional ClanApi.ServerChatAccepted event:

Action<string, long, string, string, string, string>
// platformId, characterPlayerId, playerName, clanId, clanName, message

It fires once on the authoritative dedicated server or local host after identity, membership, text, and rate-limit checks accept a clan message, before delivery to clan members. It does not fire on receiving clients or for rejected/rate-limited messages. Subscribe once, unsubscribe when your integration stops, and keep handlers quick. Nonfatal subscriber failures are isolated from other handlers and chat delivery; diagnostics never include message content.

This additive event enables optional server-side logging integrations such as ServerManager. Clan remains standalone and does not require ServerManager. Clan chat remains private to its clan recipients, but an installed server-side integration can record accepted messages in the server's local logs. The event itself does not log content or create a public chat relay.

API v6 adds optional receiving-client formatting through ClientChatFormatting:

Action<string, long, string, Action<string>>
// chatScopeId, senderRoutedPeerId, sanitizedBody, replaceBody

The server supplies the authenticated routed peer ID; it is not the persistent character player ID used by ServerChatAccepted. Formatting runs once before a received line enters the dock history. Each subscriber receives the original sanitized body. Call replaceBody synchronously with bounded rich text owned by your integration; invalid/late replacements and nonfatal subscriber failures retain the readable line. With multiple valid replacements, the last subscriber wins. Subscribe once and unsubscribe when the integration stops. Existing server events and delivery policy are unchanged.

ChatClanId is the legacy name for the synchronized chat scope: the effective clan in Full mode (Guest first), or the group in Simple mode. It is not a Clan permission. CanShareChatWithPeer(chatScopeId, routedPeerId) checks that client's current online roster using platform/character identity. It is a replicated client check and can lag a server-side membership change; it is not an authoritative server query or a recall mechanism for already delivered data.

InventorySlots uses this optional API for hover item tooltips and middle-click pinning in clan/group chat. Neither mod requires the other. Clan without the integration displays the readable item label. Server and clients must update Clan together: active-mode snapshots and group invitations use RPC protocol v15, which is not wire-compatible with v14. Full clan save format 6 is unchanged.