Overview

The Clans is a multi-user fantasy RPG door game for BBS systems. It features clan management, empire warfare, turn-based combat, and a unique Inter-BBS (IBBS) multiplayer system that links multiple BBSes into a shared game world. The game was written in C (originally Turbo C++ for DOS), and has since been modernized to compile with GCC and C17, targeting FreeBSD, Linux, and Windows.

Each BBS running the game acts as a "village" in a shared league. Players build clans, join empires, and fight for control of the village. Through the IBBS system, clans can travel to -- and attack -- other villages over a Fidonet-style packet network.

This document is the developer and contributor reference. For sysop installation and game setup, see release/clans.txt. For quest and NPC development, see devkit/clandev.txt.

License and History

The Clans was written by Allen Ussher from 1997 to 2002. The game originally ran on DOS-based BBS systems, compiled with Turbo C++ and using the OpenDoors door library by Brian Pirie. It was released as open source under the GPL v2 in 2002.

Modernization work includes:

• Compiler: GCC with C17 standard, replacing Turbo C++
• Platforms: FreeBSD, Linux, and Windows (was DOS only)
• Serialization: Explicit pack/unpack macros replacing raw struct I/O
• Platform abstraction: unix_wrappers.c / win_wrappers.c / platform.c
• Build system: GNUmakefile (Unix) and Visual Studio solution (Windows)

The OpenDoors library is still used for BBS door integration and is linked statically as libODoors.a. For the GPL v2 license text, see docs/gpl.txt.

Prerequisites

Unix (FreeBSD, Linux)

• GCC with C17 support
• GNU Make (invoke as gmake on BSD systems)
• libODoors.a -- the OpenDoors library, compiled for your target platform and placed where the linker can find it

On FreeBSD, GCC and GNU Make can be installed via ports or pkg. The OpenDoors library must be compiled from source. Once libODoors.a is available, the build system will link it automatically.

Windows

• Visual Studio 2022 (version 17) or later
• The solution file src/clans.sln contains a project for every binary. Open it in Visual Studio and build the desired projects or the entire solution. libODoors.a must also be compiled and available for the linker. Alternatively, MinGW-w64 with GCC and GNU Make can be used with the GNUmakefile path described below.

Building from Source

All source files are in src/. Data source files are in data/.

Unix / MinGW -- GNUmakefile

Build output goes to bin/<os>.<arch>.<flavour>/ -- for example:

bin/freebsd.amd64.opt/      Release build on FreeBSD/amd64
bin/freebsd.amd64.debug/    Debug build

The game target also copies binaries and clans.pak to the project root directory, which is where the test/ instance expects to find them. The release build uses -Os -flto. The debug build enables -Wall -Wextra -Wconversion -pedantic -g -O0.

Windows -- Visual Studio 2022

Open src/clans.sln. The solution contains one project per binary. Build individual projects or the full solution. Output goes to the standard VS output directories (Debug/ or Release/ under each project). Data files must still be built using the devkit tools.

Running and Testing

There are no automated tests. The test/ directory contains a pre-configured game instance for manual verification:

cd test/
./clans       Run the main game
./reset       Run the maintenance reset
./config      Run the configuration utility
./pcedit      Edit player characters

After gmake game, binaries and clans.pak are copied to the project root alongside test/. The shell scripts in test/ expect the binaries in the parent directory (../clans, etc.).

The devkit tool qtest allows testing a single quest event script outside of the full game -- useful when developing new quests.

Module Summary

All 61 source files live in src/. They are organized as follows:

Compiled Binaries

Core Game Engine

Inter-BBS Networking

Gameplay Systems

Data Serialization

See section 3.2 for serialization rules and the full BUF_SIZE list.

Platform Abstraction

Conditional compilation uses #ifdef UNIXY for Unix-specific code and #ifdef WIN for Windows. Platform detection is handled by mk/Platform.gmake, which sets UNIXY or WIN and selects the appropriate wrapper file.

Content and Strings

See section 3.4 for the full strings workflow.

Utility Modules

Tools and Utilities

Game Utilities

DevKit Tools

Built by gmake devkit:

Each devkit tool is documented in devkit/*.txt. See especially devkit/clandev.txt for a comprehensive content-creation guide.

Data Structures (structs.h)

Almost all game data structures are defined in src/structs.h. The 42 structs are organized by function:

Configuration and Runtime System

Core Game State

Player and Combat

Items, Spells, and Content

Social, NPCs, and Alliances

Trade and Messages

Inter-BBS Packets and Nodes

Other

Serialization System

Game data files are written and read using explicit serialization rather than raw struct dumps. This ensures a stable on-disk format that is independent of compiler layout and padding decisions.

The serialize.c / deserialize.c pair provides pack_* and unpack_* macros for each supported type:

Both serialize and deserialize functions return SIZE_MAX on buffer overflow or underflow.

XOR encryption is applied by myopen.c at the file I/O layer. Each data file type has its own constant (see section 3.3).

Buffer Sizes (BUF_SIZE_* in myopen.h)

Buffer sizes for every serialized struct are declared as BUF_SIZE_* constants in myopen.h. The current values are:

XOR Encryption Constants

Data files are XOR-encrypted byte-by-byte with a fixed per-type key defined in src/defines.h. This prevents casual editing of binary data files but is not a security mechanism. A determined attacker with access to the source code can decode any file trivially.

Language and String System

User-visible strings are not hardcoded in C source. They live in data/strings.txt and are compiled into the binary language file data/strings.xl by the langcomp devkit tool.

Workflow for Adding or Changing a String

1. Add or edit the entry in data/strings.txt.
2. Run: langcomp strings.txt strings.xl
3. Run: makepak pak.lst clans.pak (or copy strings.xl manually to the game directory for quick testing).

In C code, strings are referenced through macros in src/mstrings.h:

od_printf( STR_WELCOME );
od_printf( STR_CLAN_DISBANDED );

Each macro expands to a lookup in the loaded Language struct by index. The macros are the authoritative list of all user-visible strings. Do not add string literals to source code for any text that a player will see.

Packet Types

Inter-BBS packets are identified by the PT_* constants in packet.h.

Packet Filenames

Outgoing packet files follow the naming convention:

clFFFTTTDDI

Example: cl001002AAa is the first outbound packet from BBS 001 to BBS 002 in league "AA".

Packets are written to the outbound/ directory and attached to outgoing Fidonet netmail messages by myibbs.c.

BACKUP.DAT tracks all in-flight packets. During maintenance, stale PT_CLANMOVE entries cause the clan to be re-added locally; stale PT_ATTACK entries return troops to the attacking side.

League Structure and Roles

Each BBS in the league is identified by a numeric BBSID. BBS ID 1 is the League Controller (LC), which is the authoritative node.

New User Registration Flow

1. User registers on BBS X. BBS X sends PT_NEWUSER to the LC.
2. LC checks for duplicate names across all known users.
3. LC broadcasts PT_ADDUSER to every node in the league.
4. All nodes add the user to their local userlist on receipt.

Periodically, the LC sends a full PT_ULIST to all nodes to re-synchronize the user list. PT_ULIST updates only records for users whose home BBS is not the receiving node; local users are never overwritten.

Configuration Files

The full IBBS protocol, including packet flow diagrams and edge case handling, is in docs/ibbs-notes.txt.

Further Reading

docs/ibbs-notes.txt is the authoritative IBBS protocol reference. It documents every packet type in detail, the BACKUP.DAT recovery mechanism, and the full sequence for common operations like clan migration, inter-BBS attacks, and league resets.

Data Files Overview

The game reads all content from clans.pak, a custom archive file similar in concept to a Quake PAK file. The PAK is assembled from compiled binary data by the makepak devkit tool.

Files Inside clans.pak

The source text files for all of the above live in data/ and are compiled by devkit tools into their binary forms. pak.lst in data/ lists exactly which compiled files are included in the PAK and what internal path each one gets.

Building Data Files

All commands below are run from the data/ directory (or provide paths accordingly). The tools must be on your PATH or invoked with their full path from bin/.

After modifying any source data file, you must recompile it and rebuild clans.pak before the changes will appear in the game.

The genall.bat script in data/ was the original batch runner for all of the above steps. Under Unix, run the commands individually or write a shell script to automate them.

Each tool is documented in devkit/*.txt. See devkit/clandev.txt for a comprehensive guide to creating quests, NPCs, and monsters.

Event Scripts

Events are scripts for mine encounters and quests. They are written in a simple compiled scripting language and processed by event.c and quests.c at runtime.

Key Scripting Commands

Scripts are compiled from .evt (source) to .e (binary) using ecomp. The compiled .e files are what the game actually loads.

Registering Quests in QUESTS.INI

Quest Help Entries (QUESTS.HLP)

Quest descriptions shown in the help system live in QUESTS.HLP. Each entry follows this format:

^Quest Name
Description text.
^END

See devkit/ecomp.txt for the full event command reference, and devkit/event1.evt through event5.evt for worked examples. The QUESTS.INI and QUESTS.HLP in the release/ directory are the reference versions for the built-in quest set.

Help Files

The in-game F1/? help system loads plain ASCII .hlp files bundled in clans.pak. Each file covers one topic area. Current files:

To add a new help topic, create a .hlp file, add it to pak.lst, and register it in help.c. Help files are plain text; ANSI colour codes are supported.

Internal %-codes

rputs() in door.c processes %-codes embedded in any displayed text. The general-purpose codes (%P, %C, %L, %R, %D, %B, %V) and the game-state codes (%F, %M, %1, %2, %X, %Q, %N, %T, %Y) are documented in clans.txt section 1.9.

The following codes are used internally by strings.txt and the combat system. They depend on transient state that is only valid during specific game routines and are not useful in quest packs or sysop-editable files:

%SS, %SD, and %SV are populated only during spell resolution in fight.c. Outside that context, they contain stale or empty values.

%Z silently discards the rest of the current rputs() call. It has no practical use in content files.

Current Issues

XOR encryption is trivially weak

The per-file XOR keys in defines.h are visible in the source. Anyone with the source can decode and modify any data file. This has always been the case; the original author acknowledged it explicitly. Do not rely on it for security. See section 6.2 for the recommended approach.

video.c is hardware-specific

The terminal output layer carries assumptions from the original DOS/serial-port environment. It works correctly on current platforms but is fragile. Review the full file before making any changes to the terminal output layer.

ibbs.c and empire.c are large and complex

At ~100KB each, these files pre-date the current serialization and platform abstraction layers and contain legacy patterns. Changes here require extra care and thorough manual testing.

Some user-visible strings are still hardcoded

Despite the language system, a number of string literals remain in the C source that should be in strings.txt. Any such string is a localization gap and a maintenance burden.

No automated tests

All verification is manual via the test/ directory. A bug in the IBBS path, for example, can only be caught by running a two-node local league and exercising the specific code path.

Suggested Improvements

These are the original author's recommendations, still valid:

1. Replace the Fidonet transport with TCP sockets

The current IBBS system requires a configured Fidonet mailer (Binkley or compatible) at every node. This is the biggest practical barrier to setting up an IBBS league. A direct TCP packet exchange between nodes would eliminate this dependency.

2. Replace XOR encryption with real packet authentication

Ideally, sign packets with a per-league private key so that nodes can verify packet origin. This would close the cheating vector in competitive leagues.

3. Harden the IBBS state machine

The BACKUP.DAT recovery logic handles the common cases, but desync between nodes is still possible in some edge cases (e.g., a node missing a PT_ADDUSER and later receiving a PT_ULIST that includes that user's data).

Additional modernization ideas:

4. Add an automated test harness

The quest event interpreter (quests.c / event.c) is the most tractable place to start; individual .evt scripts can be tested in isolation with qtest.

5. Move remaining hardcoded strings to data/strings.txt

A grep for od_printf(" in the source will find them.

6. Add CRC validation to all deserialization paths

Currently, some deserialize functions check CRC and some do not. Consistent validation would catch file corruption much earlier and make debugging easier.

Build Targets

Release Artifacts

Complete Game Installation

DevKit Installation

Copyright Notice

"Originally copyright 1997-2002 Allen Ussher. Open source contributors. GPL v2."