What Can You Develop?

At the moment, you are limited to developing quests, NPCs, and monsters for The Clans. In the future, items, mine events, classes, races, and possibly game strings may be available — but a system must first exist to prevent cheat packs. It would be far too easy to hand out the item creator and have BBSes build up super items.

Quests are what players go on via the G option in the mines. They're event files (scripts) plus optional NPCs and monster files. Modify your QUESTS.INI and sometimes CLANS.INI and you're set.

NPCs are characters encountered on the street or in other locales. They're made up of stats (for joining clans) and quotes (for conversation).

How Does The System Work?

The Clans uses two INI files for add-on modules:

CLANS.INI — the general INI. Lets the sysop add NPCs, races, classes, items, and spells (only NPCs can be developed by 3rd parties). Also allows changing the language file.

QUESTS.INI — tells the game which quests are available and where to find them.

When distributing an add-on, you must provide installation instructions. Currently, lines must be added to the INI files manually. (An add-on installer may be created in a future version.)

What Are Event Files?

Event files are simple scripts used to construct "events" encountered through quests and mine events (e.g. meeting the spirit knights). They are small programs run by the game using its own compiled language.

Workflow: write a text script → compile it with ECOMP.EXE → test it in The Clans.

Making Event Files

Example 1 — Getting Started

The simplest event file you'll ever see. Lines beginning with # are comments. Event starts a named block; End stops execution. Text outputs a string to the player's screen.

EVENT1.EVT# Example Event File No.1

Event SimpleEvent
  Text "Hello World!
End

Compile it:

ECOMP EVENT1.EVT EVENT1.E

Register it as a quest in QUESTS.INI:

Name            Event1 Test
File            EVENT1.E
Index           SimpleEvent
Known

Go into the game and run the quest. After running it, you won't be able to run it again until you force maintenance with CLANS /M.

Example 2 — Blocks & Jumps

A file can contain multiple blocks. Event blocks can be started directly as quests. Result blocks are jump targets — they're not started on their own. Use Jump to move between blocks. Multiple quests can share one file — just use different Index values.

EVENT2.EVTEvent FirstEvent
  Text "This is the 1st event
  Jump FirstEvent.Result
End

Result FirstEvent.Result
  Text "This is a result of the first event!
End

Event SecondEvent
  Text "This is the 2nd event!
End

The Known keyword in QUESTS.INI makes a quest available without the player needing to be "told" about it by an NPC first.

Example 3 — Getting Options

Prompt is like Text but without a newline at the end. Option captures a single keypress and jumps to a named block. Input captures a full-line response.

EVENT3.EVTEvent Block1
  Text "This is example #3!
  Text
  Prompt "Press A,B,C, or D >
  Option A PressA
  Option B ILikeB
  Option C C
  Option D NextLine

  Text "You pressed D!
  Jump Block2
End

Result PressA
  Text "You pressed A!
  Jump Block2
End

Result Block2
  Text "Now let's chat:
  Input TFC1  1. This is Option 1
  Input TFC2  2. This is Option 2
  Input TFC3  3. This is Option 3
End

Option D NextLine — using NextLine as the target causes execution to continue at the line immediately after all the Option keywords.

Example 4 — Fighting

Use AddEnemy to load monsters into the fight buffer, then Fight to trigger combat. DoneQuest marks the quest permanently completed for that player.

EVENT4.EVTEvent FightExample
  Text "You will now experience a battle!
  Pause

  AddEnemy /m/Output 1
  AddEnemy /m/Output 1
  AddEnemy /m/Output 1
  AddEnemy /m/Output 1
  Fight YouWin YouLose NextLine

  Text "aw, you ran away!
End

Result YouWin
  Text "Good job, you won!
  DoneQuest
End

Result YouLose
  Text "You suck!  How could you lose!?
End

Special Fight labels: NextLine continues after the Fight line, STOP halts execution, NoRun prevents the player from fleeing.

# Most common usage pattern:
Fight NextLine STOP NoRun

Example 5 — Flags & ACS

Flags are boolean variables (TRUE/FALSE) used to track state across an event. They are tested using {} syntax before any command.

EVENT5.EVTEvent FlagExample
  SetFlag T1

  # executed only if T1 is set
  {T1}Text "T1 was set!

  # this line will NEVER execute
  {!T1}Text "T1 was NOT set!

  SetFlag T3
  Jump NextPart
End

Result NextPart
  {T3}Text "T3 is set!
  ClearFlag T1
  {!T1}Text "T1 has been cleared.
  {!T1 & T3}Text "T3 was set but T1 was not.

  # these three sometimes appear and sometimes don't
  {R50}Text "Random display 1

  # ^ = always TRUE, % = always FALSE
  {^}Text "This should ALWAYS be seen
  {%}Text "This should NEVER be seen
End

ACS expressions support & (AND), | (OR), ! (NOT), and grouping with ( ):

# true if G12 AND T2 are set, OR if H9 is set AND D1 is NOT set:
{ (G12 & T2) | (H9 & !D1) }

Additional ACS conditions:

Event File Command Reference

Multi-line Comments

Use >> delimiters for block comments spanning multiple lines:

>>
 Everything in here is a comment.
 Can span many lines.
>>

Monsters

Monsters are the creatures players fight in combat. They're created from a text file and compiled using MCOMP.EXE.

Making Monsters

Create a text file (e.g. MONSTERS.TXT or MYMON.TXT) and compile it:

MCOMP MONSTERS.TXT OUTPUT.MON
MCOMP MYMON.TXT MYMON.MON

See the included MONSTERS.TXT for a full example. The output file extension is just a convention — it can be any valid filename.

Monster Field Reference

NPCs

NPCs are characters encountered by pressing / in game menus, in random mine encounters, and in quests. Players can chat with them and sometimes recruit them to join their clan.

Making NPCs

Create a text file similar to NPCS.TXT and compile it using MakeNPC:

MakeNPC infile.txt outfile.npc

Add the NPC file to the game in CLANS.INI:

NpcFile MYNPCS.NPC

If using a PAKfile:

NpcFile @MYPAK.PAK/npc/Mine

Example NPC — The Knight

Every NPC block starts with the Index line — a unique tagword used to reference the NPC in event files (via Chat <index>). It MUST come first and MUST be globally unique.

After Index, the order of remaining fields doesn't matter. Key fields:

• — QuoteFile: the compiled quote file for this NPC's dialogue
• — NPCDAT: which monster index in the MonFile holds the NPC's stats (0 = first)
• — MonFile: the .MON file containing the NPC's stats
• — Loyalty: 0–10. Higher = less likely to reveal clan info. 10 = never, 0 = always
• — Topic: an unknown topic revealed via TellTopic in a quote file
• — KnownTopic: a topic the player can chat about from the start
• — IntroTopic: the first topic shown when the player starts chatting

Quote Files

Quote files (QFs) are compiled exactly like event files using ECOMP.EXE, but use the keyword Topic instead of Event or Result. Each topic corresponds to a topic listed in the NPC's data file.

Three extra commands are available in QFs:

Using Monster Files for NPC Stats

Create a file similar to NPC-MON.TXT and compile it with MCOMP.EXE as you would a normal monster file. Reference it using the MonFile keyword and the specific monster within it using NPCDAT.

MCOMP NPC-MON.TXT NPC.MON

NPC Field Reference

Installing Add-On NPCs

Tell the sysop to add one line to CLANS.INI:

NpcFile MYNPCS.NPC

# Or if using a PAKfile:
NpcFile @MYPAK.PAK/npc/Mine

Installing Add-On Quests

Ask the sysop to add entries like these to QUESTS.INI:

Name            Bathtub o' Blood
File            BLOOD.E
Index           Blood
Known

# Or with a PAKfile:
Name            Bathtub o' Blood
File            @BOB.PAK/e/Bob
Index           Blood
Known

To avoid the "Help not found!" message, also provide a quest description block for the sysop to append to QUESTS.HLP. Format:

^Bathtub o' Blood
|12Bathtub o' Blood
|06----------------
|04Go on a rampage killing everything in sight.

|12Difficulty: Hard and BLOODY!
^END

The first line (with ^) must exactly match the Name in QUESTS.INI. All text between that line and ^END is displayed to the player.

Tool Overview

The devkit includes several command-line tools for compiling data files. Here's a quick reference — see the section on genall.bat below for how they all fit together.

genall.bat — Building Everything

The included genall.bat shows how all tools are used together to regenerate all the game's data files from source. Useful as a starting template for your own build script.

GENALL.BATlangcomp strings.txt > TMP.FIL
mcomp eventmon.txt event.mon >> TMP.FIL
mcomp monsters.txt output.mon >> TMP.FIL
mspells spells.txt spells.dat >> TMP.FIL
mitems items.txt items.dat >> TMP.FIL
mclass classes.txt classes.cls >> TMP.FIL
mclass races.txt races.cls >> TMP.FIL
makenpc npcs.txt clans.npc >> TMP.FIL
ecomp pray.evt pray.e >> TMP.FIL
ecomp eva.txt eva.e >> TMP.FIL
ecomp quests.evt quests.e >> TMP.FIL
ecomp church.evt church.e >> TMP.FIL
ecomp secret.evt secret.e >> TMP.FIL
makepak clans.pak pak.lst >> TMP.FIL

MAKEPAK.EXE and PAKfiles

PAKfiles bundle multiple files into one archive to reduce clutter when distributing an add-on. The game reads from PAK archives transparently.

Creating a PAK File

1. Step 1. Create a file listing (e.g. PAK.LST) with two columns: the real filename on the left, the PAKfile internal name on the right. PAKfile names MUST begin with / and cannot exceed 29 characters.

   PAK.LSTmenus.hlp       /hlp/menus
   combat.hlp      /hlp/combat
   items.dat       /dat/items
   spells.dat      /dat/spells
   strings.xl      /dat/Language
   dumbfile.txt    /dumbstuff/dumbfile.text
   important.doc   /This.Is.Important

2. Step 2. Run MAKEPAK:

   MAKEPAK AI.PAK PAK.LST

Accessing PAK Files

Files inside PAKs are accessed using the @ prefix and PAK filename:

# Access /Event.E in ADDON.PAK:
@ADDON.PAK/Event.E

# Access /Event.E in CLANS.PAK (explicit):
@CLANS.PAK/Event.E

# Access /Event.E in CLANS.PAK (shorthand -- omitting @ uses CLANS.PAK by default):
/Event.E

Example — if you PAK an ANSI into DRAGON.PAK as /ans/Welcome:

# CORRECT:
Display "@DRAGON.PAK/ans/Welcome

# WRONG -- searches CLANS.PAK, not DRAGON.PAK:
Display "/ans/Welcome

CHEW.EXE and INSTALL.EXE

For distributing add-ons, you can use the included installation system. Since every Clans installation already has INSTALL.EXE, you don't need to include it in your archive.

Creating a .GUM Archive with CHEW

A .GUM file is a compressed archive (similar to ZIP or ARJ). Create a file list called FILES.LST (one filename per line), then run CHEW:

FILES.LSTMYQUEST.TXT
MYQUEST.PAK
SYSOP.DOC

CHEW MYQUEST.GUM

If no GUM filename is given, ARCHIVE.GUM is created by default. Compression uses the sixpack algorithm by Philip G. Gage.

The INI File

INSTALL.EXE is driven by an INI file. See EXAMPLE.INI for a full template. Key sections:

EXAMPLE.INI (STRUCTURE)# First line beginning with ! specifies the GUM file to use:
!MYQUEST.GUM

# Sections begin with : and end when the next : section starts.
# :title is shown as a header, :goodbye on exit.
:title
  |17 My Quest Installer |16

:welcome
  |15Welcome to My Quest!

:install
  |07This will install My Quest files.

:install.files
# o = overwrite, s = skip if exists, q = query user
o MYQUEST.PAK
o MYQUEST.DOC
s readme.txt

:installdone
Done!  Please read MYQUEST.DOC.

:upgrade
  Upgrade message here.

:upgrade.files
o MYQUEST.PAK
s readme.txt

Run the installer using the INI filename (without extension):

INSTALL MYQUEST

Frequently Asked Questions

Distributing Add-Ons

Once you've created an add-on, open a ticket on SourceForge first so it can be tested (though that's not strictly required any more). If you have a webpage with your add-ons, mention it and we'll link it from the project page.

Web: http://theclans.sourceforge.net

Spell Index

Use these numeric values with the Spell field in monster files.

Item Index

Use these exact names with the GiveItem command in event files.

Monster Index

Event Monsters — @CLANS.PAK/m/Eva

Use these with AddEnemy /m/Eva <index> for quest encounters.

Mine Monsters — @CLANS.PAK/m/Output

Use these with AddEnemy /m/Output <index> for standard mine fights (0–183).

This document and its accompanying files are by no means complete. More work is required — feedback and emails are welcome.