--- deliantra/server/pod/objects.pod 2006/12/19 15:30:01 1.6 +++ deliantra/server/pod/objects.pod 2006/12/20 20:25:59 1.15 @@ -9,9 +9,26 @@ used to collect notes about the internal behaviour of the objects. +=head2 About the notation and terms + +The term 'archetype' stands for a collection of fields. +The term 'object' stands for an archetype instance. +The term 'field' is used for an object fields and archetype fields. + +Field names will be displayed like I. + =head2 About archetypes and objects -Field denotes an attribute of an archetype. +Archetypes are 'templates' of objects. If an object is derived +from an archetype the object fields will be set to the corresponding +fields in the archetype. + +When a map is instanciated (loaded), the 'object' description on the +map are considered patches of the archetype. + +This document does explain the behaviour of the objects and the meaning of +their fields in the server engine, which are derived from archetypes. + This is an example of an archetype: Object button_trigger @@ -32,24 +49,25 @@ weight 1 end -This archetype has the name 'button_trigger' and the objects that -inherit from this archetype have the name 'button'. +The first B is I: 'button_trigger', which basically means that +instances (objects) that are created/derived from this archetype have the +name 'button' (which means that the field I of the object will be set +to the same value as the archetypes field I). -The next field 'type' decides the main behaviour of this archetype. +The next field I decides the behaviour of objects derived from this archetype. For a comprehensive list of types see include/define.h. For this case you might find a line like: #define TRIGGER_BUTTON        30 -The server internally works with objects that 'inherit' attributes from -an archetype. They have a similar set of attributes. +The behaviour of objects is further determined by B, like FLAG_APPLIED. +For more information on this look in the Flags subsection in the next section -The following documentation will also document the meaning of code internal -attributes of objects. These attributes are marked as '(internal)' and can't -or shouldn't be set by an archetype. If the internal names differs the -external name (for the archetypes) for the attribute is written behind it. +The following documentation will also document the meaning of internal used +fields of objects. These fields are marked as (internal) and can't +or shouldn't be set by an archetype. -=head2 Description of generic archetype and object attributes +=head2 Description of (mostly) generic object fields These are the fields that most of the objects have and/or their default behaviour. @@ -68,6 +86,18 @@ The graphical appearance of this object. +=item x + +The x position of the object when it is on a map. + +=item y + +The y position of the object when it is on a map. + +=item map (internal) + +The map the object is on. + =item invisible If the is greater than 0 the object is invisible. @@ -96,6 +126,19 @@ equal to 0 the absolute value of the speed field is added to speed_left on the end of the tick. +This means: the lower the speed field is (but still above MIN_ACTIVE_SPEED) +the more seldom the object is processed. And the higher the speed field is +the more often the object is processed. + +=item connected + +When this field is set the object will be linked to a connection with the +id . What happens when the connection is 'activated' depends on the +type of the object. + +When FLAG_ACTIVATE_ON_PUSH and FLAG_ACTIVATE_ON_RELEASE they will control +when to activate the object, see description of these below for further details. + =item no_drop (0|1) Sets the flag FLAG_NO_DROP. @@ -111,11 +154,36 @@ Sets the flag FLAG_IS_USED_UP. See Flags section below. +=item changing (0|1) + +Sets the flag FLAG_CHANGING. +See Flags section below. + =item auto_apply (0|1) Sets the flag FLAG_AUTO_APPLY. See Flags section below. +=item no_steal (0|1) + +Sets the flag FLAG_NO_STEAL. +See Flags section below. + +=item reflecting (0|1) + +Sets the flag FLAG_REFLECTING. +See Flags section below. + +=item reflect_spell (0|1) + +Sets the flag FLAG_REFL_SPELL. +See Flags section below. + +=item no_skill_ident (0|1) + +Sets the flag FLAG_NO_SKILL_IDENT. +See Flags section below. + =item activate_on_push (0|1) (default: 1) Sets the flag FLAG_ACTIVATE_ON_PUSH. @@ -129,7 +197,7 @@ =item editable (more than deprecated) This field had a special meaning for crossedit, which used parts -of the server code for editing. Wherever you see this attribute being +of the server code for editing. Wherever you see this field being set in an archetype ignore it and/or remove it. No code interprets this field anymore. @@ -166,6 +234,11 @@ If FLAG_APPLIED is not set the object is destroyed. +=item FLAG_CHANGING + +If the 'state' field of the object is 0 the object will be processed periodically. +Otherwise it won't "change"; + =item FLAG_IS_A_TEMPLATE (internal use) This flag is set on the inventory of generators like CREATORs and CONVERTERs, @@ -181,6 +254,9 @@ with the 'connected' field and controls wether the object should be activated when the connection is 'pushed' or it is 'released'. +What 'pushed' and 'released' means depends on the object that +activates the connection. + This flag is by default on. =item FLAG_ACTIVATE_ON_RELEASE @@ -189,11 +265,42 @@ with the 'connected' field and controls wether the object should be activated when the connection is 'pushed' or it is 'released'. +What 'pushed' and 'released' means depends on the object that +activates the connection. + This flag is by default on. +=item FLAG_NO_STEAL + +When this flag is set this object can't be stolen. The flag will be +resetted once the object is placed on a map. + +When this flag is set on a monster it can defent attempts of stealing +(but in this context the flag is only used internally). + +=item FLAG_NO_SKILL_IDENT + +This flag is mostly used internal and prevents unidentified objects +(objects which don't have FLAG_IDENTIFIED set) being identified by +skills. + +This flag is used to mark objects to never being identified by a skill +once a player failed to identify an object. So that multiple tries +of identifying aren't more effective than one. + +=item FLAG_REFLECTING + +This flag is used by spell effects (eg. SP_BOLT), THROWN_OBJ and ARROW +to indicate whether this object reflects off walls. + +=item FLAG_REFL_SPELL + +This flag indicates whether something reflects spells, like spell reflecting +amuletts. + =back -=head2 Description of type specific attributes +=head2 Description of type specific fields and behaviour The beginning of the headers of the following subsection are the server internal names for the objects types, see include/define.h. @@ -201,7 +308,7 @@ =head3 TRANSPORT - type 2 - Player transports This type is implemented by the transport extension and has currently no special -attributes that affect it. +fields that affect it. =head3 ROD - type 3 - Rods that fire spells @@ -211,7 +318,7 @@ =item level -This attribute is used for calculating the spell level that can be fired +This field is used for calculating the spell level that can be fired with this rod, it's also the maximum level of the spell that can be fired. The level of the spell that is being fired depends mostly on the 'use magic item' skill level of the player and 1/10 of the level of the @@ -329,8 +436,7 @@ =item on_use_yield -When this object is applied this object will be created. -This field is also used by FOOD and POISON. +When this object is applied an instance of will be created. =item subtypes @@ -360,6 +466,282 @@ =back +=head3 FOOD - type 6 - Eatable stuff + +This is for objects that are representing general eatables like +beef or bread. + +The main difference between FOOD, FLESH and DRINK is that they +give different messages. + +The specialty of FLESH is that it inherits the resistancies of the +monsters it was generated in and will let dragons raise their resistancies +with that. If the monster has the POISON attacktype the FLESH +will change into POISON. + +If a player runs low on food he will grab for FOOD, DRINK and POISON +and if he doesn't find any of that he will start eating FLESH. + +=over 4 + +=item title + +If the food has a title or is cursed it is considered 'special', which means that the +fields Str, Dex, Con, Int, Wis, Pow, resist_, hp and sp +are interpreted and have further effects on the player. + +The higher the food field is the longer the improvement of the player lasts +(except for hp and sp). + +=item food + +This is the amount of food points the player gets when he eats this. + +=item on_use_yield + +When this object is applied an instance of will be created. + +=back + +=head3 POISON - type 7 - Poisonous stuff + +This type is for objects that can poison the player when drinking. +When applied it will hit the attacked with AT_POISON and will create +a POISONING object in the one who was hit. + +=over 4 + +=item level + +This field affects the propability of poisoning. The higher the level difference +between the one who is hit and the poision the mose propable it is the attacked +one will be poisoned. + +=item slaying + +On poison this field has the usual meaning of 'slaying', when the +ones race matches the slaying field the damage done by the poison +is multiplied by 3. + +=item hp + +This is the amount of damage the player will receive from applying this. The +attacktype AT_POISON will be used to hit the player and the damage will +determine the strenght, duration and depletion of stats of the poisoning. The +created POISONING object which is being placed in the one who was attacked will +get the damage from this field (which is maybe adjusted by slaying or the +resistancies). + +=item food + +1/4 of will be drained from the players food. + +=item on_use_yield + +When this object is applied an instance of will be created. + +=back + +=head3 BOOK - type 8 - Readable books + +This type is basically for representing text books in the game. + +Reading a book also identifys it (if FLAG_NO_SKILL_IDENT is not set). + +=over 4 + +=item msg + +This is the contents of the book. When this field is unset +at treasure generation a random text will be inserted. + +=item skill + +The skill required to read this book. (The most resonable +skill would be literacy). + +=item exp + +The experience points the player get for reading this book. + +=item subtype + +This field determines the type of the readable. +Please see common/readable.C in the readable_message_types table. + +=back + +=head3 CLOCK - type 9 - Clocks + +This type of objects just display the time when being applied. + +=head3 LIGHTNING - type 12 - Lightnings (DEPRECATED, see SPELL_EFFECT subtype SP_BOLT) + +This is a spell effect of a moving bolt. It moves straigt forward +through the map until something blocks it. +If FLAG_REFLECTING is set it even reflects on walls. + +FLAG_IS_TURNABLE should be set on these objects. + +=over 4 + +=item move_type + +This field affects the move type with which the lightning moves through +the map and which map cells will reflect or block it. + +=item attacktype + +The attacktype with which it hits the objects on the map. + +=item dam + +The damage this bolt inflicts when it hits objects on the map. + +=item Dex + +This is the fork percentage, it is reduced by 10 per fork. +And the damage is halved on each fork. + +=item Con + +This value is a percentage of which the forking lightning +is deflected to the left. This value should be mostly used internally. + +=item duration + +The duration the bolt stays on a map cell. This field is decreased each time +the object is processed (see the meaning of speed and speed_left fields in +the object general description). + +=item range + +This is the range of the bolt, each space it advances this field is decreased. + +=back + +=head3 ARROW - type 13 - Arrows + +This is the type for objects that represent projectiles like arrows. +The movement of THROWN_OBJs behave similar to this type. + +Flying arrows are stopped either when they hit something blocking +(move_block) or something which is alive. +If it hits something that is alive, which doesn't have FLAG_REFL_MISSILE +set, it will inflict damage. If FLAG_REFL_MISSILE is set it will inflict +damage with a small chance which is affected by the 'level' field of the arrow. + +If FLAG_REFLECTING is set on the arrow it will bounce off everything +that is not alive and blocks it's movement. + +When an arrow is being shot it's dam, wc, attacktype, slaying fields will +be saved in the sp, hp, grace and spellarg fields of the object, to restore them +once the arrow has been stopped. + +=over 4 + +=item dam + +The amount of damage that is being done to the victim that gets hit. +This field is recomputed when the arrow is fired and will consist +of the sum of a damage bonus (see description of the BOW type), +the arrows 'dam' field, the bows 'dam' field, the bows 'magic' field +and the arrows magic field. + +=item wc + +The weaponclass of the arrow, which has effect on the propability of hitting. + +It is recomputed when the arrow is being fired by this formula: + + wc = 20 - bow->magic - arrow->magic - (skill->level or shooter->level) + - dex_bonus - thaco_bonus - arrow->stats.wc - bow->stats.wc + wc_mod + +When the arrow is not being shot by an player dex_bonus and thaco_bonus and the +level is not added. + +The wc_mod is dependend on the fire mode of the bow. For a more detailed +explanation of dex_bonus, thaco_bonus and wc_mod please consult the code. + +=item magic + +This field is added to the damage of the arrow when it is shot and +will also improve it's speed by 1/5 of it's value. + +=item attacktype + +Bitfield which decides the attacktype of the damage, see include/attackinc.h +On fireing the attacktype of the bow is added to the arrows attacktype. + +=item level (interally used) + +The level of the arrow, this affects the propability of piercing FLAG_REFL_MISSILE, +see above in the ARROW description. + +The level is set when the arrow is fired to either the skill level or the +shooters level. + +=item speed (internal) + +This field shouldn't be set directly in the archetype, the arrow will get it's +speed from the bow. This fields value has to be atleast 0.5 or otherwise the +arrow will be stopped immediatly. + +On fireing the speed of the arrow is computed of 1/5 of the +sum of the damage bonus (see BOW), bow magic and arrow magic. After that 1/7 +of the bows 'dam' field is added to the speed of the arrow. + +The minimum speed of an arrow is 1.0. + +While flying the arrows speed is decreased by 0.05 each time it's moved. + +If the speed is above 10.0 it goes straight through the creature it hits and +it's speed is reduced by 1. If the speed is lower or equal 10.0 the arrow is +stopped and either sticked into the victim (see weight field description) or +put on it's map square (if it didn't break, see description of the food field). + +=item weight + +This field is the weight of the arrow, if the weight is below or equal 5000 (5 kg) +the arrow will stick in the victim it hits. Otherwise it will fall to the ground. + +=item food + +The breaking percentage. 100% means: breaks on usage for sure. + +=item inventory (internal) + +If the flying/moving object has something in it's inventory and it stops, it +will be replaced with it's inventory. Otherwise it will be handled as usual, +which means: it will be calculated whether the arrow breaks and it will be +reset for reuse. + +=item slaying + +When the bow that fires this arrow has it's slaying field set it is copied +to the arrows slaying field. Otherwise the arrows slaying field remains. + +=item move_type (internally used) + +This field is set when the arrow is shot to MOVE_FLY_LOW. + +=item move_on (internally used) + +This field is set when the arrow is shot to MOVE_FLY_LOW and MOVE_WALK. + +=item race + +The race field is a unique key that assigns arrows, bows and quivers. When +shooting an arrow the bows race is used to search for arrows (which have the +same race as the bow) in the players inventory and will recursively search in +the containers (which are applied and have the same race as the bow and the arrow). + +=back + +=head3 BOW - type 14 - Bows, those that fire ARROWs + +TODO, but take into account ARROW description above + =head3 WEAPON - type 15 - Weapons This type is for general hack and slash weapons like swords, maces @@ -487,11 +869,11 @@ =item ac -the amount of ac points the player's ac is decreased +the amount of ac points the player's ac is decreased when applying this object. =item wc -the amount of wc points the player's wc is decreased +the amount of wc points the player's wc is decreased when applying this object. =back @@ -506,6 +888,60 @@ FLAG_SEE_IN_DARK FLAG_UNDEAD +=head3 GRIMREAPER - type 28 - Grimreapers + +These type are mostly used for monsters, they give the +monster the ability to dissapear after 10 hits with AT_DRAIN. + +=over 4 + +=item value + +This field stores the hits the monster did yet. + +=back + +=head3 CREATOR - type 42 - Object creators + +Once a creator is activated by a connection it creates a number of objects +(cloned from it's inventory or a new object derived from the archetype +named in the other_arch slot). + +If FLAG_LIVESAFE is set the number of uses is unlimited. + +=over 4 + +=item hp + +If FLAG_LIVE_SAVE is not set it is the absolute number of times the creator can +be used. + +=item speed + +If speed is set the creator will create an object periodically, +see speed and speed_left fields in general object field description +for more details on how this period works. + +=item slaying + +If set the generated object's name and +title will be set to this. + +=item other_arch + +If the inventory of the creator is empty new objects +will be derived from the archetype named by . + +=item connected + +See generic object field section. + +=back + +=head3 DRINK - type 54 - Drinkable stuff + +See FOOD description. + =head3 CHECK_INV - type 64 - Inventory checkers This object checks whether the player has a specific item in his @@ -557,7 +993,45 @@ =item connected -This is the connection that will be activated. +This is the connection that will be activated. The connection is +'pushed' when someone enters the space with the inventory checker, +and it is 'released' when he leaves it. + +See also the description of the connected field in the generic object field +section. + +=back + +=head3 FLESH - type 72 - Organs and body parts + +See FOOD description. + +=head3 MISC_OBJECT - type 79 - Misc. objects + +A type for any object that has no special behaviour. + +=head3 LAMP - type 82 - A lamp + +This object makes light. + +=head3 DUPLICATOR - type 83 - Duplicators or: Multiplicators + +This type of objects multiplies objects that are above it when it is activated. +You can even multiply by 0, which will destroy the object. + +=over 4 + +=item level + +The multiplicator, if set to 0 or lower it will destroy the objects above it. + +=item other_arch + +The archetype name of the objects that should be multiplied. + +=item connected + +See generic object field section. =back @@ -567,6 +1041,8 @@ opens and/or is completly open all objects above it fall through (more precisely: if their head is above the hole). +When the HOLE is activated it's speed is set to 0.5. + Trapdoors can only transfer the one who falls through to other coordinates on the B map. @@ -607,6 +1083,32 @@ =back +=head3 POISONING - type 105 - The poisoning of players and monsters + +This type is doing the actual damage to the ones who were attacked +via AT_POISON (or drank POISON). + +The duration is handled via the FLAG_IS_USED_UP mechanism (please look +there for details). + +=over 4 + +=item dam + +Each time the poisoning is processed (which is determined by the speed and speed_left +fields, see the general object fields above) it hits the player with + damage and the AT_INTERNAL attacktype (means: it will simply +hit the player with no strings attached). + +=item food + +Just a note: The posion is removed when food == 1 and not when +the whole duration is up, because the POISONING code has to remove +the poison-effects from the player before the FLAG_IS_USED_UP mechanism +deletes the POISONING object. + +=back + =head3 FORCE - type 114 - Forces Forces are a very 'thin' type. They don't have much behaviour other than @@ -616,8 +1118,13 @@ Forces only take effect on the player if they have set FLAG_APPLIED. Whether the duration field is processed or not a tick is controlled via the -speed and speed_left field. Look above at the generic description of these -fields. +speed and speed_left field. Look above in the generic object field description. + +NOTE: Setting FLAG_IS_USED_UP on an force will also consider the 'food' field +like stated above in the FLAG_IS_USED_UP description. BUT: If the food field reaches +0 before duration and FLAG_APPLIED is set, the force will last for 'duration'. +If the FLAG_APPLIED is not set the force is removed when food reaches 0. +Generally this means: FLAG_IS_USED_UP doesn't have good semantics on forces. =over 4