Lpc Manpages

FUNKTION:
    varargs object AddItem(mixed filename,int refresh,mixed props);

DEFINIERT IN:
    /std/room/items.c
    /std/npc/items.c

ARGUMENTE:
    filename
      String mit dem Namen des zu erzeugenden Objektes oder Array von Strings
      mit den Namen der zu erzeugenden Objekte. Bei einem Array wird ein Name
      zufaellig ausgewaehlt.

    refresh
      Wann und wie soll das Objekt erneuert werden:
       - REFRESH_NONE      - Kein Refresh bis zum Neuladen des Raums oder NPCs.
       - REFRESH_DESTRUCT  - Refresh bei Reset, wenn Item zerstoert wurde.
       - REFRESH_REMOVE    - Refresh bei Reset, wenn Item entfernt wurde.
       - REFRESH_ALWAYS    - Neuer Clone bei jedem Reset.
       - REFRESH_MOVE_HOME - Objekt wird bei Reset automatisch zurueckgeholt,
                             wenn es wegbewegt wurde. Nur in Raeumen!

     Bei NPCs gilt zusaetzlich:
       - CLONE_WEAR       - Item Anziehen, wenn es eine Ruestung ist.
       - CLONE_WIELD      - Item zuecken, wenn es eine Waffe ist.
       - CLONE_NO_CHECK   - Zuecken oder Anziehen ohne Ueberpruefungen.

     props (optional):
       Mapping mit denen in einem geclonten Objekt zu setzenden Properties
       oder 1 fuer die Erzeugung einer Blueprint.

RUECKGABEWERT:
     Innerhalb von Raeumen wird das erzeugte Objekt zurueckgeliefert. Bei NPCs
     klappt das leider nicht, da dort die Objekte nicht sofort erzeugt werden,
     sondern erst, nachdem der NPC an seinen Bestimmungsort transferiert wurde.
     Daher wird bei NPC immer 0 zurueckgegeben.

BESCHREIBUNG:
     Abhaengig von <filename> und <props> wird ein Objekt erzeugt und in den
     Raum bzw. NPC bewegt. Dabei gibt es folgende Moeglichkeiten:

     - <filename> ist ein Dateiname.
       Es wird ein Clone dieser Datei erstellt oder, wenn <props>=1 ist, deren
       Blueprint verwendet.

     - <filename> ist ein Array von Dateinamen.
       Es wird eine Datei zufaellig aus dem Array ausgewaehlt und von dieser
       Datei ein Clone erstellt oder, wenn <props>=1 ist, deren Blueprint
       verwendet.

     Uebergibt man fuer <props> ein Mapping mit dem Aufbau
              ([prop_name:prop_wert,...]),
     so werden diese Properties im erzeugten Objekt gesetzt. Der Parameter
     <refresh> gibt an, was waehrend eines Resets im Raum bzw. in NPCs oder
     was beim Erzeugen von NPCs geschehen soll:

     In <rooms.h> sind dazu folgende Moeglichkeiten definiert:

     - REFRESH_NONE
       Das Objekt wird niemals erneuert; falls es zerstoert wurde, wird es
       erst dann wieder erzeugt, wenn der Raum erneut geladen bzw. der NPC
       neu erzeugt wird. Man beachte, dass nicht jeder NPC wirklich
       refreshende Objekte benoetigt, REFRESH_NONE spart hierbei sowohl
       Rechenzeit als auch Speicher!

     - REFRESH_DESTRUCT
       Das Objekt wird nur dann erneuert, wenn es in der Zwischenzeit
       zerstoert wurde. Bei NPCs ist das zum Beispiel der Fall, wenn sie
       getoetet wurden.
       REFRESH_NONE & REFRESH_DESTRUCT + Blueprint-Objekt bedeutet bei
       NPCs ein Unique-Objekt, es wird also nicht beim Neuerzeugen des
       NPCs zurueckgesetzt.

     - REFRESH_REMOVE
       Das Objekt wird erneuert, wenn es sich nicht mehr im Raum bzw. im NPC
       befindet. Das kein sein, weil es zerstoert wurde, aber auch zum
       Beispiel in folgenden Faellen:

       * weil es jemand mitgenommen hat
         (in Raeumen bei Gegenstaenden)

       * weil es fortgegangen ist
         (in Raeumen bei NPCs, die herumlaufen)

       * weil es weggeworfen wurde
         (in NPCs bei Gegenstaenden)

     - REFRESH_ALWAYS
       Das Objekt wird immer erneuert. Diese Refreshmethode sollte man nur
       verwenden, wenn sichergestellt ist, dass die erzeugten Objekte auf
       anderem Wege nach und nach vernichtet werden, sich selbst aufloesen
       etc., da sich sonst mit der Zeit gewaltige Mengen von Objekten
       ansammeln koennen!

    - REFRESH_MOVE_HOME
      Das Objekt wird in einen Raum zurueckbewegt, sofern es noch existiert,
      jedoch nicht mehr in dem Raum ist. Sinnvoll ist dies eigentlich nur
      fuer Lebewesen, funktioniert aber auch bei beliebigen Objekten.
      Hauptsaechlich geht es hierbei darum, herumlaufende NPCs oder bei
      erzwungenen Bewegungen nicht von P_GUARD zurueckgehaltene NPCs wieder
      an einen definierten Ausgangsort zurueckzubringen.

    Hat man in Raeumen als <filename> ein Array von Dateinamen uebergeben,
    so wird beim Reset jedesmal aufs Neue ein zufaelliges Objekt aus der
    Liste ausgewaehlt (nicht in NPCs). In NPCs gilt der Grundsatz der
    Vermeidung von ueberfluessigen Objekten im MUD. Neu erzeugt werden
    Objekte beim Erzeugen eines NPCs oder bei einem Reset im selbigen.
    Anstatt die Objekte gleich neu zu erschaffen, wird geschaut, ob sich
    identische Objekte schon im Raum befinden. Ist dies der Fall, so nimmt
    der NPC sie auf, ruft jedoch vorher nochmals create() in ihnen auf!
    Dies noetig wegen moeglicher Veraenderungen an den Objekten.

    Was dann passiert, haengt von weiteren Angaben in <refresh> ab.
    Folgende weitere Moeglichkeiten sind in <npc.h> definiert:

    - CLONE_WEAR
      Ist das hinzugefuegte Item eine Ruestung, so wird sie nach
      Aufnahme oder Neuerzeugung angezogen.

    - CLONE_WIELD
      Ist das hinzugefuegte Item eine Waffe, so wird sie nach Aufnahme
      oder Neuerzeugung gezueckt.

    Hierbei ist zu beachten, dass die Waffe und Ruestung *in jedem Fall*
    gezueckt bzw. angezogen werden, da eine rollenspieltechinsche
    Ueberpruefung bei NPCs auf diesem Wege NICHT stattfindet.
    Das hat den Vorteil, dass der NPC in jedem Fall diese Ruestung
    anziehen kann, Tragebeschraenkungen also wegfallen, sofern dies
    technisch auch moeglich ist (er also nicht Gefahr laeuft, zB zwei
    Ruestungen gleichen Typs anzuziehen).

    Benutzt man Blueprints (<props>=1) mit REFRESH_REMOVE oder
    REFRESH_ALWAYS, so kann es zu ungewollten Ueberraschungen kommen, da die
    Blueprint dann unabhaengig von ihrem momentanen Aufenthaltsort wieder in
    den Raum bzw. NPC bewegt wird, von dem sie erzeugt wurde!
    Das KANN natuerlich Absicht sein. 😉

BEMERKUNGEN:
    Wenn man Blueprints benutzt, sollte man daran denken, dass sich von
    dieser dann keine Clones mehr erstellen lassen!
    RemoveItem() zum Entfernen von Items ist nur fuer Raeume definiert!

    Anstelle von AddItem kann man auch AddNpc, AddWeapon und AddObj etc
    verwendet werden.

BEISPIELE:

    1. Ein Wuerfel, der sich nach Entfernen erneuert:

       AddItem("/obj/misc/wuerfel",REFRESH_REMOVE);

    2. Ein etwas veraenderter Wuerfel:

       AddItem("/obj/misc/wuerfel",REFRESH_REMOVE,
                    ([P_SHORT  : "Ein schwerer Wuerfel",
                      P_WEIGHT : 100]));

    3. Eine Blueprint, die nur einmal im MUD existiert. Wenn sie zerstoert
       wurde, wird sie bei Reset neu erzeugt:

       AddItem("/mon/angsthase",REFRESH_DESTRUCT,UNIQUE_OBJECT);

    4. Eine Blueprint, die nur einmal im MUD existiert. Wenn sie aus dem
       Raum entfernt wurde, wird sie bei Reset zurueckgeholt:

       AddItem("/mon/angsthase",REFRESH_MOVE_HOME,1);

    5. Ein zufaelliges Objekt:

       AddItem( ({"/obj/misc/lolli",
                  "/obj/misc/bonbon",
                  "/obj/misc/bier"}),REFRESH_REMOVE);

    6. Eine Ruestung, die auch angezogen wird (nur in NPCs):

       AddItem("/ruestung/kettenhemd",REFRESH_REMOVE|CLONE_WEAR);

    7. Eine Unique-Waffe, die auch gezueckt wird (nur in NPCs):

       AddItem("/waffe/axt",REFRESH_DESTRUCT|CLONE_WIELD,UNIQUE_OBJECT);

    8. Eine Waffe aus demselben Teilpfad wie die Gegend, in der der NPC
       geschrieben wurde (z.B. "/p/weapon/gebirge/bergwerg/peitsche"):

       AddWeapon("peitsche",REFRESH_DESTRUCT|CLONE_WIELD);


SIEHE AUCH:
    RemoveItem

----------------------------------------------------------------------------
01.02.18, Torin