Manual:Zone Manual/The Objects Section/Object macros

From DikuMUD Wiki
< Manual:Zone Manual‎ | The Objects Section
Revision as of 06:18, 15 November 2026 by Agent-mud (talk | contribs) (checked against the current code (wiki review 2026-11-15))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Object macros

Weapons, armour, drinks, lights and most other kinds of objects need a type and a few values that must fit together. The macros in vme/include/wmacros.h and liquid.h set them for you. Both are included by #include <macros.h>.

A macro sets fields such as type, value[] and weight, and those keep the last value given. Write the macro first and change things after it, or the macro overwrites what you wrote before it. manipulate and flags add up, so you can add to the flags a macro sets.

The definitions below are copied from the headers. If you want to check one, the files are on GitHub: wmacros.h, liquid.h.

The bonus scale

Weapons, armour and shields have two bonuses, craftsmanship and magic, and the transfer macros further down take an amount. All of them use the same scale from -7 to +7, with names in values.h:

Value Name Combat bonus Hit points of the item
7 BONUS_ARTIFACT
20
2400
6 BONUS_SUPERIOR
17
2200
5 BONUS_EXCELLENT_PLUS
14
2000
4 BONUS_EXCELLENT
11
1800
3 BONUS_GOOD_PLUS
8
1600
2 BONUS_GOOD
5
1400
1 BONUS_AVERAGE_PLUS
2
1200
0 BONUS_AVERAGE 0 1000
-1 BONUS_AVERAGE_MINUS -2 965
-2 BONUS_BAD -5 930
-3 BONUS_BAD_MINUS -8 895
-4 BONUS_TERRIBLE -11 860
-5 BONUS_TERRIBLE_MINUS -14 825
-6 BONUS_JUNK_ALMOST -17 790
-7 BONUS_JUNK -20 755

vmc refuses anything outside -7..+7 (the old manuals used ±25 and ±10; those numbers are wrong now). The comments in wmacros.h still mention the old ranges; ignore them.

Craftsmanship
How well the item is made: the material and the smith. It decides the item's hit points (last column). Every hit with a weapon, and every hit taken on armour or a shield, wears the item down; at zero hit points it breaks, its title gets "(broken)" and it becomes worthless junk. A hit field on a weapon, armour or shield is ignored.
Magic bonus
How much the item is enchanted. A higher magic bonus also makes the item wear down a little slower.
Combat bonus
When the game loads the item, both bonuses are turned into the combat bonus in the third column (a positive bonus sometimes comes out a little higher). A weapon's craftsmanship and magic bonus are added to its wielder's attack; armour's are added to the defence when that body part is hit, and a shield's to its chance to block. In a melee hit, +2 of combat bonus is worth as much as 1 more point of weapon skill.

Make better items cost more, and give a magic item flags {UNIT_FL_MAGIC} so that detect magic shows it.

Weapons

/* weapon_category: One of the WPN_XXX macros.       */
/* craftsmanship:   [-25..25] Material used & Smity  */
/* magic_bonus:     [-25..25] Magic modification     */
#define WEAPON_DEF(weapon_category, craftsmanship, magic_bonus)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_WIELD} \
   type ITEM_WEAPON            \
   value[0] weapon_category    \
   value[1] craftsmanship      \
   value[2] magic_bonus        \
   value[3] RACE_DO_NOT_USE

#define WEAPONSZ_DEF(weapon_category, craftsmanship, magic_bonus, hgt)  \
   WEAPON_DEF(weapon_category, craftsmanship, magic_bonus)\
   height hgt

The weapon category is a weapon such as WPN_DAGGER or WPN_BATTLE_AXE, from values.h (see weapon definitions in values.h). The groups WPN_SWORD, WPN_AXE_HAM and so on are for skills, not weapons: vmc refuses them here. How hard each weapon hits each kind of armour, whether it needs two hands, and the strength and level needed to wield it are in vme/etc/weapons.def.

WEAPONSZ_DEF also sets the height. Without a height the weapon is made for a 180 cm character; when a reset equips an NPC with it, it is resized to fit that NPC anyway.

A two-handed iron flail, well made, not magic:

WEAPON_DEF(WPN_FLAIL, BONUS_GOOD, BONUS_AVERAGE)

A rusty sacrificial dagger with an enchantment:

WEAPON_DEF(WPN_DAGGER, BONUS_BAD, BONUS_GOOD)
flags {UNIT_FL_MAGIC}

A huge wooden club made for a 400 cm giant:

WEAPONSZ_DEF(WPN_CLUB, BONUS_BAD, BONUS_AVERAGE, 400)

Slaying weapons

/* race : Match one of the RACE_XXX values. */
#define WEAPON_SLAYER(race) \
  flags {UNIT_FL_MAGIC} \
  value[3] race

/* Will slay dragons */
#define WEAPON_SLAYER_DRAGONS \
  flags {UNIT_FL_MAGIC} \
  value[3] RACE_DRAGON_MIN \
  extra {"$slayer"} {RACE_DRAGON_MIN, RACE_DRAGON_MAX} "dragon slayer"

A slaying weapon gets +50 on its attacks against that race, and more against opponents above level 50. WEAPON_SLAYER_DRAGONS slays every dragon race. Put the slayer macro after WEAPON_DEF, which sets value[3] to RACE_DO_NOT_USE (no slaying):

WEAPON_DEF(WPN_LONG_SWORD, BONUS_GOOD, BONUS_GOOD)
WEAPON_SLAYER(RACE_ORC)

Armour

#define ARMOUR_DEF(atype,craftsmanship, magic_bonus) \
manipulate {MANIPULATE_TAKE} \
type ITEM_ARMOR              \
value[0] atype         \
value[1] craftsmanship       \
value[2] magic_bonus

#define ARMOURSZ_DEF(atype, craftsmanship, magic_bonus, hgt)\
ARMOUR_DEF(atype,craftsmanship, magic_bonus) \
height hgt

The armour type is one of five, from vme.h. Each has a shorter macro of its own, and a SZ version that also takes the height:

Armour type Macro With height
ARM_CLOTHES ARMOUR_CLOTHES(craftsmanship, magic_bonus) ARMOURSZ_CLOTHES(craftsmanship, magic_bonus, hgt)
ARM_LEATHER ARMOUR_LEATHER(...) ARMOURSZ_LEATHER(...)
ARM_HLEATHER (hard leather) ARMOUR_HRD_LEATHER(...) ARMOURSZ_HRD_LEATHER(...)
ARM_CHAIN ARMOUR_CHAIN(...) ARMOURSZ_CHAIN(...)
ARM_PLATE ARMOUR_PLATE(...) ARMOURSZ_PLATE(...)

The type says how the armour is built, not what it is made of; a wooden breastplate built like plate is ARM_PLATE. Each weapon in weapons.def has its own damage against each armour type.

The armour macros only set MANIPULATE_TAKE. Add the body part, or the armour can't be worn:

ARMOUR_PLATE(BONUS_GOOD, BONUS_AVERAGE)
manipulate {MANIPULATE_WEAR_BODY}
ARMOUR_DEF(ARM_CHAIN, BONUS_AVERAGE, BONUS_AVERAGE)
manipulate {MANIPULATE_WEAR_HEAD}

Armour protects the body part it is worn on. More about armour in More complex objects.

Shields

#define SHIELD_DEF(shield_type, craftsmanship, magic_bonus)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_WEAR_SHIELD} \
   type ITEM_SHIELD            \
   value[0] shield_type        \
   value[1] craftsmanship      \
   value[2] magic_bonus

#define SHIELDSZ_DEF(shield_type, craftsmanship, magic_bonus, hgt)  \
   SHIELD_DEF(shield_type, craftsmanship, magic_bonus)\
   height hgt

The shield type is SHIELD_SMALL, SHIELD_MEDIUM or SHIELD_LARGE, from vme.h. A larger shield blocks more often: the base chance is 15%, 20% and 25%, plus the shield's bonuses. Whether a shield can block a weapon at all is set per weapon in weapons.def. vme.h also defines SHIELD_TOWER, but vmc refuses it.

A small enchanted wooden shield:

SHIELD_DEF(SHIELD_SMALL, BONUS_AVERAGE, BONUS_GOOD_PLUS)
flags {UNIT_FL_MAGIC}
MATERIAL_WOOD("Oak planks bound with iron")

Materials

#define MATERIAL_WOOD(DESCR)    extra {"$material", MAT_WOOD_STR} DESCR
#define MATERIAL_METAL(DESCR)   extra {"$material", MAT_METAL_STR} DESCR
#define MATERIAL_STONE(DESCR)   extra {"$material", MAT_STONE_STR} DESCR
#define MATERIAL_CLOTH(DESCR)   extra {"$material", MAT_CLOTH_STR} DESCR
#define MATERIAL_LEATHER(DESCR) extra {"$material", MAT_LEATHER_STR} DESCR
#define MATERIAL_SKIN(DESCR)    extra {"$material", "$mat_skin"} DESCR
#define MATERIAL_ORGANIC(DESCR) extra {"$material", MAT_ORGANIC_STR} DESCR
#define MATERIAL_GLASS(DESCR)   extra {"$material", MAT_GLASS_STR} DESCR
#define MATERIAL_FIRE(DESCR)    extra {"$material", MAT_FIRE_STR} DESCR
#define MATERIAL_WATER(DESCR)   extra {"$material", MAT_WATER_STR} DESCR
#define MATERIAL_EARTH(DESCR)   extra {"$material", "$mat_earth"} DESCR
#define MATERIAL_MAGIC(DESCR)   extra {"$material", MAT_MAGIC_STR} DESCR

A material macro adds a hidden extra that says what the object is made of, with a short description. The combat code doesn't use materials. They are there for DIL: a program can test MAT_WOOD_STR in item.extra, and in the public zones the engraver in Midgaard refuses items of cloth and fire. Give an object one macro per material it is made of:

MATERIAL_WOOD("A hard oak shaft")
MATERIAL_METAL("A steel spike")

Drink containers

#define LIQ_DEF(color, wgt, max_cap, inside,thirst,full,drunk,poison) \
   type ITEM_DRINKCON           \
   weight (wgt)+(inside) \
   capacity max_cap \
   value[0] inside        \
   value[3] poison \
extra {"$drink_color"}color \
extra {"$drink_thirst"} #thirst \
extra {"$drink_full"} #full \
extra {"$drink_drunk"} #drunk
color
The colour of the liquid, shown when someone looks into the container.
wgt
The weight of the empty container in pounds.
max_cap
How much liquid it holds, in pounds. -1 means it never runs out (a fountain).
inside
How much liquid is in it when it loads. Each pound of liquid adds a pound to the weight.
thirst, full, drunk
What the liquid does to the drinker per sip. Each drink takes 3 to 10 pounds of liquid, and adds thirst × that / 4 to the drinker's thirst; fullness and drunkenness work the same way. All three stop at 24, and a player whose thirst is 24 can't drink more. Water has thirst 10; vodka has drunk 10. Blood has thirst -1, so it makes you thirstier.
poison
How poisonous the liquid is, 0 for none.

When the container is drunk empty, the game removes the last name in its names, so the last name must be the liquid: names {"blue bottle", "bottle", "oil"}. LIQ_DEF sets neither manipulate nor names; a bottle needs MANIPULATE_TAKE, a fountain doesn't.

A bottle of blue oil:

names {"blue bottle", "bottle", "silicone oil", "oil"}
manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD}
LIQ_DEF("blue", 1, 10, 10, 5, 1, 0, 0)

liquid.h has ready-made liquids, all with the arguments (WEIGHT, CAPACITY, INSIDE, POISON). This table is generated from it:

Macro Colour Thirst Full Drunk
LIQ_WATER clear 10 1 0
LIQ_BEER brown 5 2 3
LIQ_WINE clear 5 2 5
LIQ_ALE brown 5 2 2
LIQ_DARK_ALE dark brown 5 2 1
LIQ_WHISKEY golden 4 1 6
LIQ_LEMONADE red 8 1 0
LIQ_FIREBRT green 0 0 10
LIQ_LOCALSPC clear 3 3 3
LIQ_SLIME light green 8 4 0
LIQ_MILK white 6 3 0
LIQ_TEA brown 6 1 0
LIQ_COFFEE black 6 1 0
LIQ_BLOOD red -1 2 0
LIQ_SALTWAT clear 2 1 0
LIQ_COKE black 5 1 0
LIQ_VODKA clear 0 0 10
LIQ_BRANDY golden 4 1 6

A waterskin, and a fountain that never runs dry:

names {"waterskin", "skin", "water"}
manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD}
LIQ_WATER(1, 20, 20, 0)
names {"stone fountain", "fountain", "water"}
LIQ_WATER(100, -1, 50, 0)

If you use a liquid of your own often, define a macro for it like those in liquid.h:

#define LIQ_SILICONE(WEIGHT,CAPACITY,INSIDE,POISON) \
        LIQ_DEF("blue", WEIGHT,CAPACITY,INSIDE,5,1,0,POISON)

Food

#define FOOD_DEF(food_amount, poison_factor)  \
   type ITEM_FOOD         \
   value[0] food_amount   \
   value[3] poison_factor

eat adds the food amount to the eater's fullness and the food is gone. A player is full at 24, so FOOD_DEF(24, 0) fills an empty stomach in one go; most food in the public zones is between 2 and 12. The poison factor is 0 for wholesome food. Add MANIPULATE_TAKE:

manipulate {MANIPULATE_TAKE}
FOOD_DEF(6, 0)

Light sources

/* Hours     : How many hours (mud time) that the item may burn for.        */
/* How_bright: The amount of light sources that the item shines with.       */
/*             small torch = 1, torch = 2, lantern = 3...                   */
#define LIGHT_DEF(hours, how_bright)   \
   type ITEM_LIGHT     \
   value[0] hours      \
   value[1] how_bright

The player lights the object with light and puts it out with extinguish. While lit it gives off how_bright light and burns one hour less each mud hour (5 real minutes); at 0 it goes out and can't be lit again. Add MANIPULATE_HOLD: a light lights up the room only when it is held, or when it lies on the floor.

manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD}
LIGHT_DEF(12, 2)

vme.h defines INFINITE_BURNTIME (-1) for a light that never burns out, but light refuses a light with 0 or fewer hours. For a light that is always on, don't use LIGHT_DEF; give the object bright instead:

manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD}
bright 2

Containers

#define CONTAINER_DEF(max_capacity)  \
   type ITEM_CONTAINER               \
   capacity max_capacity

The capacity is the weight of what fits inside, in pounds: a 230 pound corpse needs a capacity of 230. The macro sets no manipulate flags, and nothing can be put into an object without MANIPULATE_ENTER. A sack:

CONTAINER_DEF(50)
manipulate {MANIPULATE_TAKE, MANIPULATE_ENTER}

A heavy chest that stays where it is, locked, with its key:

CONTAINER_DEF(300)
manipulate {MANIPULATE_ENTER}
open {EX_OPEN_CLOSE, EX_CLOSED, EX_LOCKED} difficulty 40
key chest_key

There is no key macro. A key is any object; type ITEM_KEY and manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} are enough.

Money

/* This is ALL you need to define money, rest is inserted at runtime. */
#define MONEY(coin_type, coins) \
  type ITEM_MONEY               \
  manipulate MANIPULATE_TAKE    \
  title coin_type               \
  value[0] coins

The coin type is IRON_PIECE, COPPER_PIECE, SILVER_PIECE, GOLD_PIECE or PLATINUM_PIECE, and coins is how many (at least 1; 0 is logged as an error and made 1). The game gives the money its names, title, description and weight when it is loaded, so the symbolic name and the macro are all you write:

silver_pile
MONEY(SILVER_PIECE, 20)
end

The macro sets the title to the coin's abbreviation, so don't write a title of your own.

Cursed objects

/* To be used when a object is cursed so that it can't be unequipped */
#define CURSED_OBJECT \
affect         \
   id ID_CURSE \
   duration -1 \
   firstf TIF_NONE \
   tickf  TIF_NONE \
   lastf  TIF_NONE \
   applyf APF_MOD_OBJ_FLAGS \
   data[0] OBJ_NO_UNEQUIP;

Once worn, a cursed object can't be removed until the curse is lifted with the remove curse spell. Characters who detect curses see it. Just put the macro in the object:

CURSED_OBJECT

Potions, scrolls, wands and staffs

#define POTION_DEF(power,spell1,spell2,spell3)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} \
   flags {UNIT_FL_MAGIC} \
   spell power      \
   type ITEM_POTION \
   value[0] power   \
   value[1] spell1  \
   value[2] spell2  \
   value[3] spell3

#define SCROLL_DEF(power,spell1,spell2,spell3)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} \
   flags {UNIT_FL_MAGIC} \
   spell power      \
   type ITEM_SCROLL \
   value[0] power   \
   value[1] spell1  \
   value[2] spell2  \
   value[3] spell3

#define WAND_DEF(power,charge,spell1,spell2)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} \
   flags {UNIT_FL_MAGIC} \
   spell power      \
   type ITEM_WAND \
   value[0] power   \
   value[1] charge  \
   value[2] spell1  \
   value[3] spell2  \
   value[4] charge  /* The max charge */

#define STAFF_DEF(power,charge,spell1,spell2)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} \
   flags {UNIT_FL_MAGIC} \
   spell power      \
   type ITEM_STAFF  \
   value[0] power   \
   value[1] charge  \
   value[2] spell1  \
   value[3] spell2  \
   value[4] charge  /* The max charge */
power
How strongly the spells are cast, like a caster's skill in the spell. The public zones use 20 to 60.
charge
How many times a wand or staff can be used.
spell1, spell2, spell3
Spells from values.h, such as SPL_CURE_WOUNDS_1 (see Spell definitions in values.h). Potions and scrolls hold three spells, wands and staffs two. Fill an unused place with SPL_NONE, not 0: 0 is a spell number too.

How they are used:

  • A potion is drunk with quaff: every spell in it is cast on the drinker, and the potion is gone.
  • A scroll is read with recite, which needs the scroll use skill; the scroll is gone afterwards.
  • A wand is held and pointed with use wand <target>. It needs the wand use skill, measured against the wand's power, and can't be used blind.
  • A staff is held and tapped on the ground with use staff. Its spells hit everyone in the room except the user and the user's group.
  • Each use of a wand or staff costs one charge; with none left it does nothing.
POTION_DEF(30, SPL_CURE_WOUNDS_1, SPL_NONE, SPL_NONE)
WAND_DEF(40, 5, SPL_LIGHTNING_1, SPL_NONE)

Bows, arrows and traps

#define MISSILE_DEF(weapon_category, craftsmanship, magic_bonus, \
                    race_sl, spel_type)  \
   manipulate {MANIPULATE_WIELD, MANIPULATE_TAKE, MANIPULATE_HOLD} \
   type ITEM_WEAPON            \
   value[0] weapon_category    \
   value[1] craftsmanship      \
   value[2] magic_bonus        \
   value[3] race_sl            \
   value[4] spel_type

#define RANGED_DEF(spel_type, craftsmanship, magic_bonus, \
                   race_sl, weapon_category, s_power)  \
   manipulate {MANIPULATE_TAKE, MANIPULATE_HOLD} \
   type ITEM_FIREWEAPON        \
   value[0] spel_type          \
   value[1] craftsmanship      \
   value[2] magic_bonus        \
   value[3] race_sl            \
   value[4] weapon_category    \
   spell s_power               \
   dilcopy ranged_need@skills();

#define TRAP_DEF(craftsmanship, magic_bonus) \
   manipulate {MANIPULATE_TAKE} \
   type ITEM_TRAP               \
   value[1] craftsmanship       \
   value[2] magic_bonus

RANGED_DEF makes a bow, crossbow or sling (WPN_BOW, WPN_CROSSBOW, WPN_SLING) for the shoot command. With spel_type 0 it shoots missiles; with a spell it shoots that spell instead and needs no missiles. MISSILE_DEF makes the arrows, bolts or stones; their weapon category must be the launcher's (WPN_BOW for arrows). race_sl is a slaying race, or RACE_DO_NOT_USE. TRAP_DEF makes a trap for the trap skill. The ranger items in vme/zone/skills.zon (a bow, an arrow and a man trap) show them in use.

RANGED_DEF(0, BONUS_GOOD, BONUS_AVERAGE, RACE_DO_NOT_USE, WPN_BOW, 0)
MISSILE_DEF(WPN_BOW, BONUS_AVERAGE, BONUS_AVERAGE, RACE_DO_NOT_USE, 0)

Bonuses while the object is used

These macros give the character something for as long as the object is worn, wielded or held, and take it away again when it is removed. Each also sets UNIT_FL_MAGIC.

Macro Gives
STR_TRANSFER(amount), DEX_TRANSFER, CON_TRANSFER, CHA_TRANSFER, BRA_TRANSFER, MAG_TRANSFER, DIV_TRANSFER More (or less) strength, dexterity, constitution, charisma, brain, magic or divine ability.
HIT_TRANSFER(amount) More (or less) of the hit point ability, so more hit points.
SKILL_TRANSFER(skill, amount) A better skill, SKI_*.
WEAPON_TRANSFER(weapon, amount) A better weapon skill, a weapon or a group, WPN_*.
SPELL_TRANSFER(spell, amount) A better spell skill, SPL_*.
CHAR_FLAG_TRANSFER(flags) Character flags, such as CHAR_DETECT_INVISIBLE.
SPEED_TRANSFER(delta_speed) Faster combat: a positive number lowers the combat speed (12 is normal, 4 the fastest).
SLOW_TRANSFER(delta_speed) Slower combat. The number must be negative.
PROTECTION_FROM_EVIL, PROTECTION_FROM_GOOD
20 defence in melee against evil (or good) attackers.
CURSED_OBJECT See above.

The amount is on the bonus scale, -7 to +7. An ability, skill, weapon or spell goes up or down by about 10 points at ±7 (the table in vme/src/common.cpp: 1, 2, 4, 5, 6, 8, 10 for 1 to 7). vmc refuses an amount outside -7..+7. A speed change must be between -8 and 8; vmc doesn't check it, and the game ignores one outside that range.

A belt that makes its wearer stronger but a worse mage:

ARMOUR_LEATHER(BONUS_AVERAGE, BONUS_AVERAGE)
manipulate {MANIPULATE_WEAR_WAIST}
STR_TRANSFER(BONUS_GOOD)
MAG_TRANSFER(BONUS_BAD)

A ring of seeing:

manipulate {MANIPULATE_TAKE, MANIPULATE_WEAR_FINGER}
type ITEM_WORN
CHAR_FLAG_TRANSFER(CHAR_DETECT_INVISIBLE)
SKILL_TRANSFER(SKI_SEARCH, BONUS_GOOD_PLUS)

The full definitions are in wmacros.h and on Complete magical transfers macros listing.

Previous: The Objects Section
Next: Building your first object