Guides

Guild & Clan Culture with Guild chat channels

MUDs rely on persistent player organizations to drive long-term retention. Unlike graphical MMOs, text-based environments require explicit channel architecture and permission systems to maintain faction boundaries. This guide covers the technical implementation of guild structures using standard MUD codebase patterns (Circle/Diku/Merc derivatives), including database schema design for reputation persistence, automated officer succession triggers, and channel isolation protocols to prevent intel leakage between rival factions.

4-6 weeks8 steps
Guild & Clan Culture with Guild chat channels illustration
Placeholder illustration shown while custom artwork is being produced.
1

Audit Existing Faction Data Structures

Inspect how clan membership is currently persisted. Check player files (pfiles) for clan_id, rank, and reputation fields versus separate clan.dat files. Identify whether ranks use hardcoded integers, bitmasks, or string comparisons. Verify if faction reputation is stored per-character or globally per-account, noting legacy pfiles may lack initialization for these fields.

structs.h
struct player_data {
  int clan_id;           /* 0 = unguilded */
  int clan_rank;         /* 1-10 or bitflags */
  int clan_reputation;   /* faction standing */
  time_t clan_joined;    /* for seniority calc */
};

⚠ Common Pitfalls

  • •Assuming all pfiles contain clan fields (legacy files may segfault on null access)
  • •Hardcoded rank integers that break when inserting new ranks between existing levels
2

Implement Tiered Communication Channels

Text MUDs use channel systems gated by level flags. Implement CLAN_CHANNEL, OFFICER_CHANNEL, and LEADER_CHANNEL constants. Route messages only to online members whose CLAN_FLAGS match the sender's rank tier. Add explicit exclusion rules preventing immortals from hearing CLAN_SECRET channels unless possessing IMMT_ALL. Log all officer channel traffic to a separate audit file for conflict resolution.

clan_comm.c
void clan_channel_talk(CHAR_DATA *ch, char *argument, int channel) {
  if (!IS_SET(ch->clan_flags, channel)) return;
  for (d = descriptor_list; d; d = d->next) {
    if (d->character && IS_SET(d->character->clan_flags, channel)
        && d->character->clan_id == ch->clan_id) {
      /* Block immort snooping unless explicitly permitted */
      if (IS_IMMORTAL(d->character) && !IS_SET(d->character->imm_flags, IMMT_ALL))
        continue;
      send_to_char(d->character, argument);
    }
  }
}

⚠ Common Pitfalls

  • •Channel leakage when immortals retain default snoop privileges creating intel asymmetry
  • •Missing online descriptor checks causing NULL pointer dereferences on link-dead officers
3

Build Reputation Decay and Inheritance Systems

Faction standing requires maintenance. Implement last_activity timestamps in clan_data. Create a pulse-based or cron-triggered decay function reducing reputation points weekly for inactive members. For permadeath MUDs, design inheritance protocols where new characters linked to the same account retain 50% of prior standing to preserve institutional memory without full privilege transfer.

maintenance.py
def decay_reputation():
    for member in ClanMember.query.all():
        days_inactive = (now() - member.last_activity).days
        if days_inactive > 7:
            decay = days_inactive * 2  # 2 pts per day
            member.reputation = max(0, member.reputation - decay)
            if member.reputation == 0:
                member.rank = 'Inactive'
    db.session.commit()

⚠ Common Pitfalls

  • •Integer underflow on unsigned reputation values wrapping to maximum
  • •Decay calculations executing during peak server hours causing lag
  • •Inheritance exploits via account sharing to boost new characters
4

Design Officer Permission Matrices

Replace single boolean leader flags with granular access control. Define bitwise permissions: PERM_INVITE (1), PERM_KICK (2), PERM_VAULT (4), PERM_PROMOTE (8), PERM_CALENDAR (16). Store as integer in clan_member_data. Verify bitwise AND before executing sensitive commands to prevent privilege escalation through client-side command spoofing.

clan_security.c
#define PERM_INVITE   (1 << 0)
#define PERM_KICK     (1 << 1)
#define PERM_VAULT    (1 << 2)
#define PERM_PROMOTE  (1 << 3)

bool has_permission(CHAR_DATA *ch, int perm) {
  if (!ch->clan_member_data) return FALSE;
  return (ch->clan_member_data->permissions & perm) == perm;
}

⚠ Common Pitfalls

  • •Bitwise collision if permissions are not distinct powers of two
  • •Missing bounds checks allowing players to set their own permission bits via buffer overflow
  • •Vault access logs failing to record officer actions preventing theft investigation
5

Automate Trial Period Workflows

Implement CLAN_TRIAL status with automated evaluation. On recruitment, set trial_end timestamp (current_time + 1209600 seconds for two weeks). Daily maintenance checks expired trials against activity metrics: minimum hours online, messages sent to clan channel, and participation in clan events. Auto-promote to full member status meeting thresholds or auto-remove failing recruits to prevent roster bloat.

clan_automation.c
void check_trials() {
  for (clan = clan_list; clan; clan = clan->next) {
    for (member = clan->members; member; member = member->next) {
      if (!IS_SET(member->flags, CLAN_TRIAL)) continue;
      if (current_time > member->trial_end) {
        if (member->hours_online > 10 && member->clan_messages > 5)
          REMOVE_BIT(member->flags, CLAN_TRIAL);
        else
          clan_remove_member(member);
      }
    }
  }
}

⚠ Common Pitfalls

  • •Timezone mismatches between game server clock and trial period calculations
  • •Trial members accessing restricted guild vaults via group-follow exploits before promotion
  • •Auto-removal triggering during server outages causing data inconsistency
6

Integrate External Event Calendars

Bridge in-game scheduling to external coordination tools. When leaders use 'clan war schedule' commands, POST JSON payloads to Discord webhooks or Google Calendar APIs. Implement asynchronous HTTP requests using libcurl with timeout thresholds to prevent blocking the game loop. Store external event IDs in the MUD database to allow cancellation or editing from within the game.

webhook_bridge.py
import requests
import json

def post_clan_event(clan, event_time, description):
    payload = {
        "content": f"**{clan.name} Event Scheduled**",
        "embeds": [{"description": description, "timestamp": event_time.isoformat()}]
    }
    try:
        requests.post(clan.webhook_url, json=payload, timeout=5)
    except requests.exceptions.RequestException:
        log_error(f"Webhook failed for clan {clan.id}")

⚠ Common Pitfalls

  • •Synchronous HTTP calls freezing the MUD during DNS resolution or SSL handshake
  • •Discord rate limiting (10 requests per second) causing missed raid announcements
  • •SSL certificate validation failures on older MUD servers using outdated CA bundles
7

Establish Officer Succession Protocols

Prevent guild collapse due to absentee leadership. Track last_login timestamps for clan leaders. After 30 days absence, trigger election state: notify all officers, open 7-day voting window. If no votes cast, automatically promote the officer with longest service record. If no eligible officers exist, archive the clan to inactive_clans table rather than deleting data, preserving history for potential future revival.

succession.sql
-- Succession trigger procedure
CREATE OR REPLACE FUNCTION check_leader_absence() RETURNS void AS $$
DECLARE
  leader_rec RECORD;
BEGIN
  FOR leader_rec IN 
    SELECT clan_id, leader_id FROM clans 
    WHERE last_login < NOW() - INTERVAL '30 days'
  LOOP
    INSERT INTO clan_elections (clan_id, start_time) 
    VALUES (leader_rec.clan_id, NOW());
    NOTIFY officers, leader_rec.clan_id;
  END LOOP;
END;
$$ LANGUAGE plpgsql;

⚠ Common Pitfalls

  • •Race conditions during simultaneous leadership claims requiring database row locking
  • •Atomic transaction failures leaving clan with two leaders if promotion commit fails
  • •Inactive officer lists containing deleted characters preventing any eligible successors
8

Debug Cross-Faction Channel Isolation

Conduct security audits to ensure guild communications remain confidential. Review all do_clan_chat implementations for buffer overflows that might leak memory contents to rival clients. Test with two separate client connections: one in Clan A, one in Clan B. Verify no packet leakage occurs in network buffers during high-load scenarios. Check that CLAN_SECRET flags properly override immortal snooping privileges unless explicitly granted IMMT_ALL.

clan_debug.c
/* Debug command for immortals to verify isolation */
void do_clan_audit(CHAR_DATA *ch, char *argument) {
  int target_clan = atoi(argument);
  int count = 0;
  
  for (d = descriptor_list; d; d = d->next) {
    if (d->character && d->character->clan_id == target_clan) {
      printf("Found: %s\n", d->character->name);
      count++;
    }
  }
  printf("Total members online: %d\n", count);
}

⚠ Common Pitfalls

  • •Immortal invis level allowing unintended eavesdropping on sensitive strategy discussions
  • •Buffer overflow in clan message formatting exposing adjacent memory containing rival communications
  • •Log files capturing secret clan passwords or strategy inadvertently written to global syslog

What you built

Guild systems in MUDs require rigorous data persistence and clear permission boundaries. Once implemented, schedule monthly audits of clan_data integrity and review officer action logs for privilege abuse. The technical foundation establishes social trust—without secure channels and fair succession code, player-led factions collapse into OOC drama. Maintain backup procedures for clan tables separately from player files to prevent corruption during pfile wipes.