A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/build/weapon

There is a generic weapon object available in obj/weapon. All weapons should
be clones or subclasses (other objects that inherit it) of this object.

The easiest way is to clone obj/weapon directly and set its details by calling
its member functions:

	object club = clone_object("obj/weapon");
	club->set_name("big club");
	club->set_class(10);
	club->set_weight(3);

You should at least call these functions:

set_name(n) 
    string n. Sets the name and short description to n.
    Sets long description to "You see nothing special.\n"

set_class(c) 
    int c. Sets how much damage it will do. 1 to 8 is appropriate for
    beginner weapons, intermediate players typically have weapons of class
    9 to 15.

set_weight(w) 
    int w. Each weapon should have a weight of at least 1, big human sized
    weapons have 3 or 4.


To get a nicer weapon, use a few of those optional functions:

set_alt_name(n) 
    string n. Adds an alternate name to weapon.

set_alias(n) 
    string n. Adds another alternate name to weapon.

set_short(sh) 
    string sh. sh must be lower case. Short description is set to sh
    and long to capitalized sh + "\n".

set_long(long) 
    string long. Long description is set to long.

set_read(str) 
    string str. str will be returned if it's read.

set_type(int)
    At the moment this function only makes the weapon able to display different
    combat messages. Valid types are:
     0 - Normal (= default, if nothing else set)
     1 - Slashing (swords) (standard for most weapons, NOT default)
     2 - Piercing (daggers, spears)
     3 - Bludgeoning (warhammers, morning stars)
     4 - Hands
    If the type is -1, the combat message can be displayed by the weapon
    itself (an example is /lib/weapon/sword.c). Other types will display no
    combat messages at all. Monsters will get extra combat messages, defined
    by the race.

set_value(v) 
    int v. Sets the value.

set_hit_func(ob) 
    object|string ob. Sets up a call to function 'weapon_hit' in object 'ob'.
    It will be called like the hit() function in the weapon itself (see
    below).

    USE ONLY LOADED OBJECTS, OTHERWISE IT WILL CAUSE TROUBLES WITH
    PERSISTENT OBJECTS!

    You can also create a file for your weapon, inherit obj/weapon
    and define your own hit() function, especially if you need to store
    data for it (eg. extra hit every 15 strikes -> need counter).
    The argument passed
    
set_wield_func(ob)
    object|string ob. Sets up a call to function 'wield' in object 'ob'.
    'wield' is called every time the weapon is wielded.
    A return value of 0 form 'wield' means that the weapon will not 
    be wielded. 1 that it's okay to wield it.
    
    DO NOT USE CLONED OBJECTS, THAT WILL CAUSE TROUBLES WITH PERSISTENCE!

    If you want to define it in the weapon itself, put a small function like
    this in another object (eg. the (loaded!) room/monster that clones it).

        wield() { return previous_object()->test_wield(); }

    Then you have to call set_wield_func() with that object and define a
    test_wield() function in your weapon. Use it as described above.
    
    BEWARE: Do not redefine a weapon's 'wield' member function unless you
    really know what you are doing!

MEMBER FUNCTIONS

There are several functions which are intended to be redefined in objects that
inherit obj/weapon:

hit(attacker)
    'hit' is called every time the weapon strikes someone.
    The argument given to 'hit' is the target of the attack. The return value
    of 'hit' adds to the weapons wc for this hit.
    Returning the string "miss" will cause the weapon to miss.

    Redefine this function to replace a call to set_hit_func().


EXAMPLE 1: Creating a simple weapon in a monster's reset function

   .
   .
   .
   my_weapon = clone_object("obj/weapon");
   my_weapon->set_name("big club");
   my_weapon->set_alias("club");
   my_weapon->set_type(3); /* Bludgeoning */
   my_weapon->set_long("This is a big club, suitable for an Ogre or a Giant.\n");
   my_weapon->set_class(8); /* Not a real good weapon... */
   my_weapon->set_weight(5); /* ... but it is heavy! */
   move_object(my_weapon,this_object()); 
   command("wield "+weapon->query_name(),this_object()); /* The monster uses the weapon! */
   .
   .
   .
   
EXAMPLE 2: Create an elaborate weapon in its own file

/*
 * This is a magic sword is has a wc of 9 as base
 * and a wc of 19 if it's attacking an orc.
 */
inherit "obj/weapon";
reset(arg) {
  ::reset(arg);
  if (arg) return;
  
  set_name("short sword");
  set_alias("sword");
  set_short("short sword");
  set_alt_name("orc slayer");
  set_long("This is a very fine blade.\n"+
	"It's covered with ancient runes.\n" + 
	"Engraved on it is a picture of the sword slicing an orc.\n");
  set_read("The only thing you can read is the word 'orc'.\n");
  set_class(9);
  set_weight(2);
  set_value(200);
}

hit(attacker)
{
  if(attacker && attacker->id("orc")){
    write("Ziiing\n");
    return 10;
  }
  return 0;
}

See also:
build/weapon.text
build/weapon.list