This handbook covers how the archetype and treasure systems work in Crossfire, using the arch repository (crossfire-crossfire-arch) and server source (crossfire-crossfire-server) as reference.

—

All game assets live in the arch git repository. At startup, the server loads them directly from disk, or from packed consolidated files generated by crossfire-server -pack-assets.

The arch directory is organised by category (monster/, weapon/, armour/, door/, floor/, player/, etc.). A single category folder typically contains matching .arc, .face, and .png files for each object it defines.

—

Every image file follows a strict naming pattern:

<objectname>.<faceset>.<frame>.png

Frame codes use three hexadecimal digits:

XYZ
│││
││└─ frame index within the facing (1-based)
│└── facing direction (1=default/south, 3=north, 5=west, 7=east)
└─── always 1 for normal objects; used by multi-tile heads/parts

Examples:

• pixie.base.111.png — pixie, base set, facing south, frame 1
• sphinx.base.x71.png — sphinx, base set, facing east, frame 1 (x prefix means extended tile)
• viking.base.131.png — viking, base set, facing north, frame 1

Currently two shipped facesets, defined in arch/image_info:

When a clsc image is absent the client silently uses the base equivalent. You can create a clsc variant by adding a file with the same name but .clsc. instead of .base..

—

A .face file defines the client-visible face names and any animations that belong to the same object group. The server reads these to know which images to send to clients.

face wooddoor_2.111
magicmap brown
end

Animations are also stored in .face files. An animation names a sequence of face identifiers that cycle at runtime.

animation pixie
pixie.111
pixie.112
pixie.111
pixie.112
pixie.111
blank.111
blank.111
mina
face pixie.111
magicmap orange
end
face pixie.112
magicmap orange
end

Example with directional facings (4 directions × 2 frames = 8 lines):

animation northman_player
facings 4
viking.111
viking.112
viking.131
viking.132
viking.151
viking.152
viking.171
viking.172
mina

The animation name used in an .arc file must exactly match the name declared here.

—

An archetype is the blueprint for an in-game object. Every mob, item, floor tile, door, spell, and skill has an archetype. Archetypes are loaded once at server startup and never changed at runtime (except for temporary archetypes created for customised map objects — see §4.7).

Object <archetype_name>
<field> <value>
...
end

The Object keyword opens the definition; end closes it. The archetype name is the internal identifier referenced everywhere else (treasure lists, map files, randomitems, other_arch, etc.).

Minimal example (a wooden club):

Object club
nrof 1
last_sp 9
type 15
face club.111
material 16
dam 6
weapontype 8
weight 9000
value 10
attacktype 1
name_pl clubs
client_type 121
body_arm -1
skill one handed weapons
end

Body slot fields specify what equipment locations this item occupies (positive = slots used, negative = slots provided for items to use):

msg
@match *
I don't know any riddles right now.... GO AWAY!!!!
endmsg

The msg / endmsg block stores the object's readable text or NPC dialog script. For NPC dialog, lines beginning with @match set triggers; see the dialog system documentation for full syntax.

Objects can contain other objects defined inline. This is used for potions that embed a spell, items that carry event connectors, or containers pre-filled with items.

Object potion_heroism
name potion of heroism
type 5
face potionhero.111
weight 1000
value 500
on_use_yield potion_empty
arch spell_heroism
end
end

The inner arch … end block embeds a copy of the spell_heroism archetype inside the potion. Any fields between arch and end override defaults from the referenced archetype.

Event connectors are a common case — they attach plugin/Python scripts:

Object messageboard
name message board
type 98
arch messageboard_apply_event
end
arch messageboard_say_event
end
end

Object messageboard_apply_event
title Python
slaying /python/IPO/board.py
type 116
subtype 1
invisible 1
end

Objects that span more than one map tile are defined as a chain of parts linked by More. The first Object is the head (origin tile); each subsequent part carries a relative x/y offset.

Object large_vdoor1
name large door
type 23
face large_vdoor.111
no_pick 1
end
More
Object large_vdoor2
name large door
type 23
face large_vdoor.111
no_pick 1
y 1
end
More
Object large_vdoor3
name large door
type 23
face large_vdoor.111
no_pick 1
y 2
end

All parts share the same name and behaviour but each occupies its own tile. The More keyword (capital M) separates parts; no end appears after More.

Objects can define an anim_suffix that the engine appends to their animation name during specific actions (attacking, spellcasting, skill use, item application). If an animation called <base>_<suffix> exists in the .face files, it plays for one cycle.

Object my_sword
...
anim_suffix sword
end

When a player wields my_sword and attacks, the engine looks for an animation named <player_anim>_sword and plays it if found.

The type field is a numeric constant defined in the server header include/object.h. Frequently used values:

The material field is a bitmask — add values together for composite materials.

Example: material 16 = wood. material 18 = iron + wood (2 + 16).

The attacktype field is a bitmask of AT_xxx constants. resist_xxx fields name the same attack types in lowercase:

When the map loader encounters a monster whose properties differ from the base archetype (i.e. it has custom attributes added in the map file), the server automatically creates a temporary archetype to record those initial values. This ensures that fix_object() calls (triggered by equipping/unequipping items, being cursed, etc.) can restore the correct baseline rather than the generic defaults.

Temporary archetypes are reference-counted and freed automatically when no living object refers to them. Map developers do not create these directly.

—

Treasure lists define what items are generated inside an object when the server initialises it. They are separate from .arc files so that the same list can be reused across many archetypes.

In the .arc file, the randomitems field names the treasure list to use:

Object door_0
name door
randomitems door
type 23
...
end

When the server spawns this door, it runs the door treasure list and inserts the generated items into the door's inventory.

1. The server tracks a magic (difficulty) level when instantiating a list. An arch entry is only eligible if its magic value is less than or equal to the current difficulty.
2. A maximum of 100 attempts are made to generate an eligible item before the generation is considered failed.
3. The flag GT_ONLY_GOOD (used internally) suppresses cursed and damned items.
4. Comments start with # and are ignored.
5. Lines may be indented freely; leading whitespace is ignored.

—

The file arch/treasures.trs (2 252 lines) is the master treasure definition file. All other .trs files in category subdirectories define lists for specific objects; treasures.trs holds the shared, reusable building-block lists that most content references.

Below is a structured summary of the major lists in the file.

treasure skill_use_magic_item
    arch skill_use_magic_item
end

treasure all_spell_skills
    arch skill_use_magic_item
more
    arch skill_evocation
more
    arch skill_praying
... (etc.)
end

These treasure lists (not treasureone) guarantee that every item in the list is generated, giving a monster or player character a guaranteed set of skill objects. skill_use_magic_item and all_spell_skills are referenced by monster treasure lists so pet monsters award XP to the right skill.

treasureone random_knowledge
    arch scroll_alchemy
        chance 10
more
    arch scroll_bargaining
        chance 5
...
end

A treasureone list. Exactly one skill scroll is chosen, with rarer skills (e.g. scroll_evocation at chance 5) less likely than common ones (scroll_missile_weap at chance 15).

treasureone random_weapon
    list missile_weapons
        chance 5
more
    list melee_weapons
        chance 10
end

treasureone random_armour
    list random_gauntlet
        chance 10
more
    list random_helmet
        chance 40
...
end

These lists compose smaller sub-lists. random_weapon delegates to either missile_weapons or melee_weapons; random_armour delegates to specific slot sub-lists such as random_helmet and random_mail.

treasure random_mushroom
    arch mushroom_1
        chance 50
    no
        arch mushroom_2
            chance 50
        no
            arch mushroom_3
                chance 50
            no
                arch mandrake_root
                    chance 10
            end
        end
    end
end

This illustrates the no branching chain. The generator tries mushroom_1 (50%); if that fails it tries mushroom_2 (50%); if that fails it tries mushroom_3 (50%); if all fail it tries mandrake_root (10%). The deepest nesting acts as a rare fallback.

treasureone random_coin
    arch goldcoin
        chance 5
        nrof 5
more
    arch goldcoin
        chance 5
        nrof 10
...
    arch platinacoin
        chance 5
        nrof 6
end

The same archetype (goldcoin, silvercoin, platinacoin) appears multiple times with different nrof values. In a treasureone list this is how you produce a distribution of stack sizes — each entry is a separate weighted option.

random_wealth is structurally identical but adds gems to the coin mix. starting_wealth is a simpler three-entry list used for new characters.

treasureone special_uncommon
    list NONE
        chance 5
more
    arch bracers_ac
        magic 4
        chance 10
more
    list rare_artifacts
        magic 14
        chance 5
...
end

list NONE is a special no-op entry that lets the list intentionally produce nothing for that roll. The magic field on list rare_artifacts means this branch is only considered when the current difficulty is ≥ 14 — so truly rare items cannot appear in low-level areas.

artifact field usage example from later in the file:

    arch potion_generic
        artifact minor healing
        chance 3

This forces the generated potion_generic to become the minor healing artifact rather than a random potion.

treasure poor_old
    arch bow
        chance 5
    yes
        arch arrow
            nrof 6
    end
    ...
end

If the bow is generated (5% chance), the yes block fires and guarantees arrows are also generated (nrof 6 = up to 6 arrows). No chance on the arrows means 100% — the arrows are certain once the bow appears.

The no branch cascades through increasingly-likely weapon fallbacks:

    arch b_ssword_2
        magic 1
        chance 5
    no
        arch b_ssword_1
            chance 10
        no
            arch b_dagger
                chance 15
            no
                arch stoneaxe
                    chance 20
                no
                    arch club
                        chance 25
                end
            end
        end
    end

If b_ssword_2 is not generated (95% of the time), try b_ssword_1; if that fails, try b_dagger; and so on down to club as the final fallback. Note that b_ssword_2 also requires magic 1 — it cannot generate at difficulty 0.

The lists poor, standard, rich (and their _old variants) are the primary lists assigned via randomitems to humanoid monsters:

These are assembled with more and sometimes delegate to humanoidpockets_low/medium:

treasure standard
    arch skill_use_magic_item
more
    list standard_old
more
    arch torch_unlit
        nrof 3
        chance 1
more
    list humanoid_parts
        chance 20
end

Towards the end of treasures.trs are lists for specific NPC/monster types used by the randomitems field on character archetypes:

treasure elf
    list fighter_skills
more
    list mage_skills
more
    arch bow
        magic 2
more
    arch skill_bowyer
more
    arch cloak
more
    arch arrow
        nrof 50
more
    list humanoid_parts
        chance 20
more
    list humanoidpockets_low
end

These composed lists give NPC classes coherent equipment sets without duplication. fighter_skills, mage_skills, and basic_skills are defined in player/player_skills.trs and referenced here by name, showing that treasure lists can cross-reference lists defined in other .trs files — all files are merged into crossfire.trs at build/pack time.

treasureone restoration_potions
    arch minor_potion_restoration
        chance 15
more
    arch medium_potion_restoration
        chance 10
more
    arch major_potion_restoration
        chance 5
more
    arch potion_restoration
        chance 5
end

A simple treasureone weighted by rarity: minor (15) → medium (10) → major (5) → full (5). The total weight is 35; a major_potion_restoration has a 5/35 ≈ 14% chance once this list is chosen.

—

• Naming conventions — The archetype name in Object <name> must be unique across all .arc files. It becomes the identifier everywhere: randomitems, other_arch, map files, treasure lists.
• Face references — The face name in face <name> strips the faceset and extension. face pixie.111 expects pixie.base.111.png (and optionally pixie.clsc.111.png).
• Adding a new object — Create a .arc file (plus matching .face and .png) in the appropriate category folder. No registration step is needed; the server finds all files recursively.
• Treasure list scope — treasures.trs is global. Category-local .trs files (e.g. door/locking_key.trs) are for lists used only by objects in that folder, but any list name is accessible globally once packed.
• NONE list — list NONE is a built-in no-op. Using it in a treasureone list adds a weighted “generate nothing” outcome, useful for controlling drop frequency without changing all the other weights.
• Difficulty gating — Use magic <n> on a list entry to create level-appropriate loot tables. Combine with list_magic_adjustment to scale difficulty up or down relative to the current area.
• Event connectors — Attach Python scripts to objects by embedding type 116 (EVENT_CONNECTOR) sub-objects. The subtype selects the event (1=apply, 6=say, etc.) and slaying is the script path relative to the server's Python directory.

—

This section walks through an entire treasureone chain end-to-end — from the top-level list down through every sub-list — using random_armour as the example. It is intended to make the relationship between chance, treasureone, list, and magic concrete.

treasureone random_armour
    list random_gauntlet
        chance 10
more
    list random_helmet
        chance 40
more
    list random_mail
        chance 52
more
    list random_shield
        chance 36
more
    list random_boots
        chance 10
more
    arch cloak
        chance 10
end

In a treasure list, chance is a plain percentage (0–100). In a treasureone list the meaning is different: chance is a relative weight, not a percentage.

The engine sums every chance value in the list to get a total, then assigns each entry a share proportional to its weight.

Total weight = 10 + 40 + 52 + 36 + 10 + 10 = **158**

The real probability of any entry = chance ÷ 158.

Concrete example: Imagine 158 numbered tickets in a hat. 52 of them say “random_mail”, 40 say “random_helmet”, and so on. One ticket is drawn. The entry whose ticket is drawn wins, and its items are generated. Everything else produces nothing.

Body armour (random_mail) is the most likely single outcome. Gauntlets, boots, and cloaks share the lowest probability.

treasureone random_armour

Declares the list named random_armour. The treasureone keyword means one and only one outcome is produced per instantiation.

    list random_gauntlet
        chance 10

References the sub-list random_gauntlet (defined in armour/gauntlets/random_gauntlet.trs). 10 tickets out of 158 (~6.3 %). If this entry wins, control is handed to random_gauntlet, which rolls its own internal treasureone to pick a specific pair of gloves or gauntlets.

more

Continues the list. Every entry except the last must be followed by more. Without it, the parser would treat the next line as a new top-level definition.

    list random_helmet
        chance 40

References random_helmet (armour/helmet/random_helmet.trs). 40 tickets (~25.3 %). Helmets are the second-most-likely slot.

    list random_mail
        chance 52

References random_mail (armour/mail/random_mail.trs). 52 tickets (~32.9 %) — the highest weight in the list. Body armour is the most common result from random_armour.

    list random_shield
        chance 36

References random_shield (armour/shield/random_shield.trs). 36 tickets (~22.8 %).

    list random_boots
        chance 10

References random_boots (armour/boots/random_boots.trs). 10 tickets (~6.3 %).

    arch cloak
        chance 10
end

Generates a cloak archetype directly — no sub-list involved. 10 tickets (~6.3 %). end closes the entire random_armour definition.

When one of the list entries wins, that sub-list runs its own treasureone roll. Each sub-list has its own set of weights, and many entries carry a magic requirement that gates them behind a minimum difficulty level. An entry whose magic value exceeds the current difficulty is skipped; the engine retries up to 100 times before giving up.

gloves_cloth is the only entry with no magic requirement, making it the sole result possible at difficulty 0. gauntlets and gloves_b/w are locked behind higher thresholds.

All entries share chance 5, so each has an equal 12.5 % share of this sub-list. Magic difficulty is the only differentiator.

At difficulty 1 only horned_helmet and bighorned_helmet are eligible. At difficulty 4 all eight are in the pool.

ring_mail appears twice at equal weight, effectively doubling its combined share to ~18.8 % at difficulty ≥ 4. lapron, tunic, and random_dress have only 1 ticket each, making them rare. random_dress is itself a further treasureone sub-list choosing between dress styles and a tunic.

spiked_shield is the rarest at 1 ticket (2.8 %). Three shields (small_shield, round_shield, spiked_shield) are available from difficulty ≥ 1; the remainder require ≥ 2 or ≥ 4.

The most compact sub-list. low_boots wins half the time. The coloured variants (black, white) are each 10 % of this already-rare (~6.3 %) outcome.

The final chance of a specific item is the product of each stage:

P(item) = P(sub-list wins in random_armour) × P(item wins in sub-list)

Example — gauntlets (the best gauntlets, magic ≥ 4):

P(random_gauntlet wins) = 10/158 = 6.33 %
P(gauntlets wins in random_gauntlet, at difficulty ≥ 4) = 5/22 = 22.7 %
P(gauntlets) = 6.33 % × 22.7 % ≈ 1.4 %

Example — plate_mail (magic ≥ 4):

P(random_mail wins) = 52/158 = 32.9 %
P(plate_mail wins in random_mail, at difficulty ≥ 4) = 5/53 = 9.4 %
P(plate_mail) = 32.9 % × 9.4 % ≈ 3.1 %

Despite random_mail being by far the most likely slot, the many entries inside it dilute any individual item's final probability considerably.

—

This section provides a probability table for every treasureone list defined in arch/treasures.trs. Each table lists entries in file order. The Probability column is chance ÷ total_weight × 100, rounded to one decimal place. magic req is the minimum difficulty level at which an entry is eligible; entries with no magic requirement can appear at any difficulty. nrof is the maximum stack size generated. arch entries generate an object directly; list entries delegate to another named treasure list. list NONE is a built-in no-op that intentionally generates nothing.

random_armour is covered in full in §8.

Used by shops, libraries, and monster drops to give one random skill scroll. Scrolls for harder skills (evocation, oratory, pyromancy, sorcery, summoning) have lower weight; two skills with the broadest use (missile weapons, praying) share the highest weight of 15.

Total weight: 247

Used by needle traps to inject a random disease into a player. Most diseases share equal weight (20). Athletes foot and tooth decay are notably rarer at 5 each.

Total weight: 150

A high-level picker that selects a weapon category. Melee weapons are twice as likely as missile weapons.

Total weight: 15

See §8 for the full line-by-line breakdown and sub-list expansion.

Total weight: 158

Used by special shops and high-value loot containers. Wands are the single most likely result. scroll_new appears three times with different nrof values, creating a distribution of scroll quantities. special_uncommon is gated at three magic thresholds (5, 8, 10) so premium items only appear in higher-level areas.

Total weight: 108

Generates one coin stack. All 14 entries share equal weight (5), making each outcome equally likely. The same archetype is repeated with different nrof values to distribute stack sizes across coin types.

Total weight: 70 (14 entries × 5)

An expanded version of random_coin that also includes gem drops. All 24 entries share equal weight (5). Gold and silver cover larger stacks than in random_coin. Platinacoin starts at nrof 1.

Total weight: 120 (24 entries × 5)

All entries have equal probability of 4.2 % each.

Generates one gem type and quantity. Common gems (gem, pearl, ruby, sapphire, emerald, amethyst) each have two entries at chance 5, spreading their quantity range. Topaz and bloodstone are rarer at chance 3.

Total weight: 72

Used to assign starting money to a new character. All three coin types are equally likely, giving each a one-in-three chance.

Total weight: 15

Generates foliage and botanicals. flowers_permanent is the most likely result. random_mushroom requires difficulty ≥ 15 and is only eligible in very high-level areas.

Total weight: 76

Alchemy supply stock list. A plain cauldron dominates at chance 18. A magic-enhanced cauldron (magic ≥ 5) has only a 3.1 % share. Mineral reagents, base metals, and plants round out the list. fix_mercury (transmuted mercury) is the rarest single item at chance 1.

Total weight: 97

A layered potion list. The seven stat potions each get a modest weight of 3. shop_potions is referenced three times at escalating magic thresholds (2, 6, 8), and random_potion references itself recursively at thresholds 10, 12, and 14 to create tiered escalation. special_uncommon is included five times at decreasing magic thresholds so that truly unusual items only emerge at high difficulty.

Total weight: 91

A gateway list for mid-tier rare items. Referenced heavily by random_potion and random_magical. bracers_ac and lockpicks lead with 10 tickets each. mithril_chainmail and ring_spell are the rarest non-NONE outcomes at 1 ticket each. list NONE (1.0 % base) intentionally produces nothing. uncommon_items is referenced four times at escalating magic thresholds.

Total weight: 97

Used wherever a random bag-type item is needed. Sacks and bags are the most common. Quivers for throwing (quiver_throwing) and scroll cases are the rarest.

Total weight: 110

Ammunition (arrows, bolts) dominates at chance 35 each. Bows and crossbows each get 10. Rare bow variants (hunter's, long, composite) have only 1 ticket each. All weapon entries require magic ≥ 3; quivers have no magic requirement.

Total weight: 103

Spears are the most common thrown weapon (31.8 %) followed by daggers (27.3 %). Throwing stars, tridents, and the quiver are the rarest. All thrown weapon stacks require magic ≥ 2 (tridents ≥ 3).

Total weight: 110

A large list covering most one- and two-handed melee weapons. All 39 standard weapons share chance 5 (magic ≥ 4 unless noted). Three weapons requiring only magic ≥ 3 (club, stonehammer, stoneaxe) are available at slightly lower difficulty. The list delegates to uncommon_weapons (10 tickets) and rare_weapons (1 ticket) for exotic choices.

Total weight: 209

Standard entries (chance 5 each, magic ≥ 4 unless marked):

Non-standard entries:

Exotic and high-value weapons rarely found. brdaxe1 (broad axe) has the highest share. dhaxe2 requires magic ≥ 6, making it one of the most difficulty-gated weapons in the game. Sai, kama, and other eastern weapons each have 1 ticket.

Total weight: 18

Cultural and unusual weapons. Katana requires magic ≥ 4; nunchaku, taifu, and trident require ≥ 3; shovel and stake need only ≥ 2. Scythe and sickle have lower weight (2) than the rest.

Total weight: 42

Named artifact weapons, armour, and accessories. Most entries share chance 5. The three dragon mail variants (dragon_mail, green_dragon_mail, blue_dragon_mail) are slightly rarer at chance 3. The amulet entry uses the artifact keyword to force generation of the lifesaving artifact specifically.

Total weight: 99

A broad magic-item loot list. restoration_potions leads at 24.5 % and scroll_new (stack of 9) follows at 21.0 %, making these the two most common outcomes. ring_spell is nearly impossible at 0.7 %.

Total weight: 143

Legendary named items. list NONE occupies 20 % of the weight, meaning one in five rolls produces nothing. Each of the 16 actual artifacts has an equal 5 % weight, giving a 5/100 = 5.0 % chance per item when the list wins. All artifacts in this list have no magic restriction — they are gated purely by whatever magic requirement the calling entry imposed.

Total weight: 100

A scroll-focused list weighted so that single scrolls are far more common than multi-scroll stacks. The five scroll_new entries at increasing nrof with decreasing weight create a graduated rarity curve. The eleven weapon- and armour-improvement scrolls each have only 1 ticket — they are very rare individually, though their combined weight (11) is significant relative to the total.

Total weight: 186

Used by shops and monster drops to pick a magic device. Wands dominate overwhelmingly at 72.0 %. Staves are a distant second. rod_heavy and ring_spell are extremely unlikely at under 1 % each.

Total weight: 132

Used by shops and high-value drops. Cleric spell books are the most common (23.5 %). All arcane school books (evocation, pyromancy, sorcery, summoning) share equal weight at 17.6 % each. random_read (non-spell readable items) is the rarest at 5.9 %.

Total weight: 85

Picks a generic readable item. Clamped books and scrolls share the highest weight (28.3 % each). Quartos are the rarest.

Total weight: 230

Generates stone and raw geological material. Field stone is the most common (31.3 %). Gold nuggets (largenugget) are rare; small nuggets and mountain stone are equal at 18.8 % each.

Total weight: 80

A top-level category picker for raw materials. Stones (38.8 %) and minerals (34.0 %) are the dominant categories. Plain rock (rock2) fills the gap. Ore is very rare at 2.9 %.

Total weight: 103

Selects a mineral reagent for alchemy or crafting. Salt is the most abundant (21.4 %). Gold nuggets (largenugget) are the rarest at 2.9 %.

Total weight: 70

A compact list used to populate spell-carrying containers. A scroll_new (stack of 3) is the most likely result. Wands, staves, and spell books share the remaining weight.

Total weight: 35

Picks a talisman or ring. Plain rings are most likely at 50 %, amulets at 37.5 %. The talisman sub-list and special_uncommon each hold only 6.3 %.

Total weight: 80

A simple two-entry picker that delegates entirely to sub-lists. Uncommon artifacts are twice as likely as rare ones.

Total weight: 15

Mining loot list. Rubble dominates at 24.8 %. Precious metals follow an inverse-rarity gradient from zinc (14.9 %) down to platinum (0.5 %). Stone and mineral sub-lists provide variety at 2.5 % and 2.0 % respectively.

Total weight: 202

Miscellaneous unusual items. list NONE holds the largest single share (37.1 %), meaning over one-third of rolls produce nothing — a deliberate mechanism to keep these items infrequent. Horns and rods are the most likely actual items. ring_spell is the rarest live outcome at 1.6 %.

Total weight: 62

The terminal potion list for restorative effects. Minor potions are most common (42.9 %). Full potion_restoration and major potions share the lowest weight at 14.3 % each.

Total weight: 35

—

Generated from crossfire-crossfire-arch and crossfire-crossfire-server source.