ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/deliantra/server/pod/objects.pod
(Generate patch)

Comparing deliantra/server/pod/objects.pod (file contents):
Revision 1.8 by elmex, Tue Dec 19 22:21:15 2006 UTC vs.
Revision 1.15 by elmex, Wed Dec 20 20:25:59 2006 UTC

7 7
8This documentation is in a sketchy state. It's mostly 8This documentation is in a sketchy state. It's mostly
9used to collect notes about the internal behaviour of the 9used to collect notes about the internal behaviour of the
10objects. 10objects.
11 11
12=head2 About the notation and terms
13
14The term 'archetype' stands for a collection of fields.
15The term 'object' stands for an archetype instance.
16The term 'field' is used for an object fields and archetype fields.
17
18Field names will be displayed like I<this>.
19
12=head2 About archetypes and objects 20=head2 About archetypes and objects
13 21
14Field denotes an attribute of an archetype. 22Archetypes are 'templates' of objects. If an object is derived
23from an archetype the object fields will be set to the corresponding
24fields in the archetype.
25
26When a map is instanciated (loaded), the 'object' description on the
27map are considered patches of the archetype.
28
29This document does explain the behaviour of the objects and the meaning of
30their fields in the server engine, which are derived from archetypes.
31
15This is an example of an archetype: 32This is an example of an archetype:
16 33
17 Object button_trigger 34 Object button_trigger
18 name button 35 name button
19 type 30 36 type 30
30 editable 48 47 editable 48
31 visibility 50 48 visibility 50
32 weight 1 49 weight 1
33 end 50 end
34 51
35This archetype has the name 'button_trigger' and the objects that 52The first B<field> is I<name>: 'button_trigger', which basically means that
36inherit from this archetype have the name 'button'. 53instances (objects) that are created/derived from this archetype have the
54name 'button' (which means that the field I<name> of the object will be set
55to the same value as the archetypes field I<name>).
37 56
38The next field 'type' decides the main behaviour of this archetype. 57The next field I<type> decides the behaviour of objects derived from this archetype.
39For a comprehensive list of types see include/define.h. For this case 58For a comprehensive list of types see include/define.h. For this case
40you might find a line like: 59you might find a line like:
41 60
42 #define TRIGGER_BUTTON        30 61 #define TRIGGER_BUTTON        30
43 62
44The server internally works with objects that 'inherit' attributes from 63The behaviour of objects is further determined by B<Flags>, like FLAG_APPLIED.
45an archetype. They have a similar set of attributes. 64For more information on this look in the Flags subsection in the next section
46 65
47The following documentation will also document the meaning of code internal 66The following documentation will also document the meaning of internal used
48attributes of objects. These attributes are marked as '(internal)' and can't 67fields of objects. These fields are marked as (internal) and can't
49or shouldn't be set by an archetype. If the internal names differs the 68or shouldn't be set by an archetype.
50external name (for the archetypes) for the attribute is written behind it.
51 69
52=head2 Description of generic archetype and object attributes 70=head2 Description of (mostly) generic object fields
53 71
54These are the fields that most of the objects have and/or their 72These are the fields that most of the objects have and/or their
55default behaviour. 73default behaviour.
56 74
57=over 4 75=over 4
65The name of a collection of these objects (the plural of the name). 83The name of a collection of these objects (the plural of the name).
66 84
67=item face <facename> 85=item face <facename>
68 86
69The graphical appearance of this object. 87The graphical appearance of this object.
88
89=item x <number>
90
91The x position of the object when it is on a map.
92
93=item y <number>
94
95The y position of the object when it is on a map.
96
97=item map (internal)
98
99The map the object is on.
70 100
71=item invisible <number> 101=item invisible <number>
72 102
73If the <number> is greater than 0 the object is invisible. 103If the <number> is greater than 0 the object is invisible.
74For players this field reflects the duration of the invisibility 104For players this field reflects the duration of the invisibility
98 128
99This means: the lower the speed field is (but still above MIN_ACTIVE_SPEED) 129This means: the lower the speed field is (but still above MIN_ACTIVE_SPEED)
100the more seldom the object is processed. And the higher the speed field is 130the more seldom the object is processed. And the higher the speed field is
101the more often the object is processed. 131the more often the object is processed.
102 132
133=item connected <number>
134
135When this field is set the object will be linked to a connection with the
136id <number>. What happens when the connection is 'activated' depends on the
137type of the object.
138
139When FLAG_ACTIVATE_ON_PUSH and FLAG_ACTIVATE_ON_RELEASE they will control
140when to activate the object, see description of these below for further details.
141
103=item no_drop (0|1) 142=item no_drop (0|1)
104 143
105Sets the flag FLAG_NO_DROP. 144Sets the flag FLAG_NO_DROP.
106See Flags section below. 145See Flags section below.
107 146
113=item is_used_up (0|1) 152=item is_used_up (0|1)
114 153
115Sets the flag FLAG_IS_USED_UP. 154Sets the flag FLAG_IS_USED_UP.
116See Flags section below. 155See Flags section below.
117 156
157=item changing (0|1)
158
159Sets the flag FLAG_CHANGING.
160See Flags section below.
161
118=item auto_apply (0|1) 162=item auto_apply (0|1)
119 163
120Sets the flag FLAG_AUTO_APPLY. 164Sets the flag FLAG_AUTO_APPLY.
121See Flags section below. 165See Flags section below.
122 166
123=item no_steal (0|1) 167=item no_steal (0|1)
124 168
125Sets the flag FLAG_NO_STEAL. 169Sets the flag FLAG_NO_STEAL.
126See Flags section below. 170See Flags section below.
127 171
172=item reflecting (0|1)
173
174Sets the flag FLAG_REFLECTING.
175See Flags section below.
176
177=item reflect_spell (0|1)
178
179Sets the flag FLAG_REFL_SPELL.
180See Flags section below.
181
182=item no_skill_ident (0|1)
183
184Sets the flag FLAG_NO_SKILL_IDENT.
185See Flags section below.
186
128=item activate_on_push (0|1) (default: 1) 187=item activate_on_push (0|1) (default: 1)
129 188
130Sets the flag FLAG_ACTIVATE_ON_PUSH. 189Sets the flag FLAG_ACTIVATE_ON_PUSH.
131See Flags section below. 190See Flags section below.
132 191
136See Flags section below. 195See Flags section below.
137 196
138=item editable (more than deprecated) 197=item editable (more than deprecated)
139 198
140This field had a special meaning for crossedit, which used parts 199This field had a special meaning for crossedit, which used parts
141of the server code for editing. Wherever you see this attribute being 200of the server code for editing. Wherever you see this field being
142set in an archetype ignore it and/or remove it. No code interprets this 201set in an archetype ignore it and/or remove it. No code interprets this
143field anymore. 202field anymore.
144 203
145=back 204=back
146 205
173this object is removed or not, see the Force type below for the meaning 232this object is removed or not, see the Force type below for the meaning
174of the duration field in this context. 233of the duration field in this context.
175 234
176If FLAG_APPLIED is not set the object is destroyed. 235If FLAG_APPLIED is not set the object is destroyed.
177 236
237=item FLAG_CHANGING
238
239If the 'state' field of the object is 0 the object will be processed periodically.
240Otherwise it won't "change";
241
178=item FLAG_IS_A_TEMPLATE (internal use) 242=item FLAG_IS_A_TEMPLATE (internal use)
179 243
180This flag is set on the inventory of generators like CREATORs and CONVERTERs, 244This flag is set on the inventory of generators like CREATORs and CONVERTERs,
181or other objects that have the flags FLAG_GENERATOR and FLAG_CONTENT_ON_GEN set. 245or other objects that have the flags FLAG_GENERATOR and FLAG_CONTENT_ON_GEN set.
182 246
188 252
189This flag has only meaning for objects that can be linked together 253This flag has only meaning for objects that can be linked together
190with the 'connected' field and controls wether the object should 254with the 'connected' field and controls wether the object should
191be activated when the connection is 'pushed' or it is 'released'. 255be activated when the connection is 'pushed' or it is 'released'.
192 256
257What 'pushed' and 'released' means depends on the object that
258activates the connection.
259
193This flag is by default on. 260This flag is by default on.
194 261
195=item FLAG_ACTIVATE_ON_RELEASE 262=item FLAG_ACTIVATE_ON_RELEASE
196 263
197This flag has only meaning for objects that can be linked together 264This flag has only meaning for objects that can be linked together
198with the 'connected' field and controls wether the object should 265with the 'connected' field and controls wether the object should
199be activated when the connection is 'pushed' or it is 'released'. 266be activated when the connection is 'pushed' or it is 'released'.
200 267
268What 'pushed' and 'released' means depends on the object that
269activates the connection.
270
201This flag is by default on. 271This flag is by default on.
202 272
203=item FLAG_NO_STEAL 273=item FLAG_NO_STEAL
204 274
205When this flag is set this object can't be stolen. The flag will be 275When this flag is set this object can't be stolen. The flag will be
206resetted once the object is placed on a map. 276resetted once the object is placed on a map.
207 277
208When this flag is set on a monster it can defent attempts of stealing 278When this flag is set on a monster it can defent attempts of stealing
209(but in this context the flag is only used internally). 279(but in this context the flag is only used internally).
210 280
211=back 281=item FLAG_NO_SKILL_IDENT
212 282
213=head2 Description of type specific attributes 283This flag is mostly used internal and prevents unidentified objects
284(objects which don't have FLAG_IDENTIFIED set) being identified by
285skills.
286
287This flag is used to mark objects to never being identified by a skill
288once a player failed to identify an object. So that multiple tries
289of identifying aren't more effective than one.
290
291=item FLAG_REFLECTING
292
293This flag is used by spell effects (eg. SP_BOLT), THROWN_OBJ and ARROW
294to indicate whether this object reflects off walls.
295
296=item FLAG_REFL_SPELL
297
298This flag indicates whether something reflects spells, like spell reflecting
299amuletts.
300
301=back
302
303=head2 Description of type specific fields and behaviour
214 304
215The beginning of the headers of the following subsection 305The beginning of the headers of the following subsection
216are the server internal names for the objects types, see include/define.h. 306are the server internal names for the objects types, see include/define.h.
217 307
218=head3 TRANSPORT - type 2 - Player transports 308=head3 TRANSPORT - type 2 - Player transports
219 309
220This type is implemented by the transport extension and has currently no special 310This type is implemented by the transport extension and has currently no special
221attributes that affect it. 311fields that affect it.
222 312
223=head3 ROD - type 3 - Rods that fire spells 313=head3 ROD - type 3 - Rods that fire spells
224 314
225Rods contain spells and can be fired by a player. 315Rods contain spells and can be fired by a player.
226 316
227=over 4 317=over 4
228 318
229=item level <number> 319=item level <number>
230 320
231This attribute is used for calculating the spell level that can be fired 321This field is used for calculating the spell level that can be fired
232with this rod, it's also the maximum level of the spell that can be fired. 322with this rod, it's also the maximum level of the spell that can be fired.
233The level of the spell that is being fired depends mostly on 323The level of the spell that is being fired depends mostly on
234the 'use magic item' skill level of the player and 1/10 of the level of the 324the 'use magic item' skill level of the player and 1/10 of the level of the
235rod is added as bonus. 325rod is added as bonus.
236 326
450 540
451When this object is applied an instance of <archetype> will be created. 541When this object is applied an instance of <archetype> will be created.
452 542
453=back 543=back
454 544
545=head3 BOOK - type 8 - Readable books
546
547This type is basically for representing text books in the game.
548
549Reading a book also identifys it (if FLAG_NO_SKILL_IDENT is not set).
550
551=over 4
552
553=item msg <text>
554
555This is the contents of the book. When this field is unset
556at treasure generation a random text will be inserted.
557
558=item skill <skill name>
559
560The skill required to read this book. (The most resonable
561skill would be literacy).
562
563=item exp <number>
564
565The experience points the player get for reading this book.
566
567=item subtype <readable subtype>
568
569This field determines the type of the readable.
570Please see common/readable.C in the readable_message_types table.
571
572=back
573
574=head3 CLOCK - type 9 - Clocks
575
576This type of objects just display the time when being applied.
577
578=head3 LIGHTNING - type 12 - Lightnings (DEPRECATED, see SPELL_EFFECT subtype SP_BOLT)
579
580This is a spell effect of a moving bolt. It moves straigt forward
581through the map until something blocks it.
582If FLAG_REFLECTING is set it even reflects on walls.
583
584FLAG_IS_TURNABLE should be set on these objects.
585
586=over 4
587
588=item move_type <movetype>
589
590This field affects the move type with which the lightning moves through
591the map and which map cells will reflect or block it.
592
593=item attacktype <attacktype>
594
595The attacktype with which it hits the objects on the map.
596
597=item dam <number>
598
599The damage this bolt inflicts when it hits objects on the map.
600
601=item Dex <number>
602
603This is the fork percentage, it is reduced by 10 per fork.
604And the damage is halved on each fork.
605
606=item Con <number>
607
608This value is a percentage of which the forking lightning
609is deflected to the left. This value should be mostly used internally.
610
611=item duration <number>
612
613The duration the bolt stays on a map cell. This field is decreased each time
614the object is processed (see the meaning of speed and speed_left fields in
615the object general description).
616
617=item range <number>
618
619This is the range of the bolt, each space it advances this field is decreased.
620
621=back
622
623=head3 ARROW - type 13 - Arrows
624
625This is the type for objects that represent projectiles like arrows.
626The movement of THROWN_OBJs behave similar to this type.
627
628Flying arrows are stopped either when they hit something blocking
629(move_block) or something which is alive.
630If it hits something that is alive, which doesn't have FLAG_REFL_MISSILE
631set, it will inflict damage. If FLAG_REFL_MISSILE is set it will inflict
632damage with a small chance which is affected by the 'level' field of the arrow.
633
634If FLAG_REFLECTING is set on the arrow it will bounce off everything
635that is not alive and blocks it's movement.
636
637When an arrow is being shot it's dam, wc, attacktype, slaying fields will
638be saved in the sp, hp, grace and spellarg fields of the object, to restore them
639once the arrow has been stopped.
640
641=over 4
642
643=item dam <number>
644
645The amount of damage that is being done to the victim that gets hit.
646This field is recomputed when the arrow is fired and will consist
647of the sum of a damage bonus (see description of the BOW type),
648the arrows 'dam' field, the bows 'dam' field, the bows 'magic' field
649and the arrows magic field.
650
651=item wc <number>
652
653The weaponclass of the arrow, which has effect on the propability of hitting.
654
655It is recomputed when the arrow is being fired by this formula:
656
657 wc = 20 - bow->magic - arrow->magic - (skill->level or shooter->level)
658 - dex_bonus - thaco_bonus - arrow->stats.wc - bow->stats.wc + wc_mod
659
660When the arrow is not being shot by an player dex_bonus and thaco_bonus and the
661level is not added.
662
663The wc_mod is dependend on the fire mode of the bow. For a more detailed
664explanation of dex_bonus, thaco_bonus and wc_mod please consult the code.
665
666=item magic <number>
667
668This field is added to the damage of the arrow when it is shot and
669will also improve it's speed by 1/5 of it's value.
670
671=item attacktype <attacktype>
672
673Bitfield which decides the attacktype of the damage, see include/attackinc.h
674On fireing the attacktype of the bow is added to the arrows attacktype.
675
676=item level <number> (interally used)
677
678The level of the arrow, this affects the propability of piercing FLAG_REFL_MISSILE,
679see above in the ARROW description.
680
681The level is set when the arrow is fired to either the skill level or the
682shooters level.
683
684=item speed <number> (internal)
685
686This field shouldn't be set directly in the archetype, the arrow will get it's
687speed from the bow. This fields value has to be atleast 0.5 or otherwise the
688arrow will be stopped immediatly.
689
690On fireing the speed of the arrow is computed of 1/5 of the
691sum of the damage bonus (see BOW), bow magic and arrow magic. After that 1/7
692of the bows 'dam' field is added to the speed of the arrow.
693
694The minimum speed of an arrow is 1.0.
695
696While flying the arrows speed is decreased by 0.05 each time it's moved.
697
698If the speed is above 10.0 it goes straight through the creature it hits and
699it's speed is reduced by 1. If the speed is lower or equal 10.0 the arrow is
700stopped and either sticked into the victim (see weight field description) or
701put on it's map square (if it didn't break, see description of the food field).
702
703=item weight <number>
704
705This field is the weight of the arrow, if the weight is below or equal 5000 (5 kg)
706the arrow will stick in the victim it hits. Otherwise it will fall to the ground.
707
708=item food <number>
709
710The breaking percentage. 100% means: breaks on usage for sure.
711
712=item inventory (internal)
713
714If the flying/moving object has something in it's inventory and it stops, it
715will be replaced with it's inventory. Otherwise it will be handled as usual,
716which means: it will be calculated whether the arrow breaks and it will be
717reset for reuse.
718
719=item slaying <string>
720
721When the bow that fires this arrow has it's slaying field set it is copied
722to the arrows slaying field. Otherwise the arrows slaying field remains.
723
724=item move_type <movetype> (internally used)
725
726This field is set when the arrow is shot to MOVE_FLY_LOW.
727
728=item move_on <movetype> (internally used)
729
730This field is set when the arrow is shot to MOVE_FLY_LOW and MOVE_WALK.
731
732=item race <string>
733
734The race field is a unique key that assigns arrows, bows and quivers. When
735shooting an arrow the bows race is used to search for arrows (which have the
736same race as the bow) in the players inventory and will recursively search in
737the containers (which are applied and have the same race as the bow and the arrow).
738
739=back
740
741=head3 BOW - type 14 - Bows, those that fire ARROWs
742
743TODO, but take into account ARROW description above
744
455=head3 WEAPON - type 15 - Weapons 745=head3 WEAPON - type 15 - Weapons
456 746
457This type is for general hack and slash weapons like swords, maces 747This type is for general hack and slash weapons like swords, maces
458and daggers and and .... 748and daggers and and ....
459 749
577 - weapon speed (last_sp): weapon_speed is calculated by: (last_sp * 2 - magic) / 2 867 - weapon speed (last_sp): weapon_speed is calculated by: (last_sp * 2 - magic) / 2
578 (minium is 0) 868 (minium is 0)
579 869
580=item ac <number> 870=item ac <number>
581 871
582the amount of ac points the player's ac is decreased 872the amount of ac points the player's ac is decreased when applying this object.
583 873
584=item wc <number> 874=item wc <number>
585 875
586the amount of wc points the player's wc is decreased 876the amount of wc points the player's wc is decreased when applying this object.
587 877
588=back 878=back
589 879
590=head4 Player inherits following flags from weapons: 880=head4 Player inherits following flags from weapons:
591 881
596 FLAG_XRAYS 886 FLAG_XRAYS
597 FLAG_BLIND 887 FLAG_BLIND
598 FLAG_SEE_IN_DARK 888 FLAG_SEE_IN_DARK
599 FLAG_UNDEAD 889 FLAG_UNDEAD
600 890
891=head3 GRIMREAPER - type 28 - Grimreapers
892
893These type are mostly used for monsters, they give the
894monster the ability to dissapear after 10 hits with AT_DRAIN.
895
896=over 4
897
898=item value <number>
899
900This field stores the hits the monster did yet.
901
902=back
903
904=head3 CREATOR - type 42 - Object creators
905
906Once a creator is activated by a connection it creates a number of objects
907(cloned from it's inventory or a new object derived from the archetype
908named in the other_arch slot).
909
910If FLAG_LIVESAFE is set the number of uses is unlimited.
911
912=over 4
913
914=item hp <number>
915
916If FLAG_LIVE_SAVE is not set it is the absolute number of times the creator can
917be used.
918
919=item speed <number>
920
921If speed is set the creator will create an object periodically,
922see speed and speed_left fields in general object field description
923for more details on how this period works.
924
925=item slaying <string>
926
927If set the generated object's name and
928title will be set to this.
929
930=item other_arch <string>
931
932If the inventory of the creator is empty new objects
933will be derived from the archetype named by <string>.
934
935=item connected <number>
936
937See generic object field section.
938
939=back
940
601=head3 DRINK - type 54 - Drinkable stuff 941=head3 DRINK - type 54 - Drinkable stuff
602 942
603See FOOD description. 943See FOOD description.
604 944
605=head3 CHECK_INV - type 64 - Inventory checkers 945=head3 CHECK_INV - type 64 - Inventory checkers
651If this field is set the inventory checker will search for an object which 991If this field is set the inventory checker will search for an object which
652has the archetype name that matches <string>. 992has the archetype name that matches <string>.
653 993
654=item connected <connection id> 994=item connected <connection id>
655 995
656This is the connection that will be activated. 996This is the connection that will be activated. The connection is
997'pushed' when someone enters the space with the inventory checker,
998and it is 'released' when he leaves it.
999
1000See also the description of the connected field in the generic object field
1001section.
657 1002
658=back 1003=back
659 1004
660=head3 FLESH - type 72 - Organs and body parts 1005=head3 FLESH - type 72 - Organs and body parts
661 1006
662See FOOD description. 1007See FOOD description.
1008
1009=head3 MISC_OBJECT - type 79 - Misc. objects
1010
1011A type for any object that has no special behaviour.
1012
1013=head3 LAMP - type 82 - A lamp
1014
1015This object makes light.
1016
1017=head3 DUPLICATOR - type 83 - Duplicators or: Multiplicators
1018
1019This type of objects multiplies objects that are above it when it is activated.
1020You can even multiply by 0, which will destroy the object.
1021
1022=over 4
1023
1024=item level <number>
1025
1026The multiplicator, if set to 0 or lower it will destroy the objects above it.
1027
1028=item other_arch <string>
1029
1030The archetype name of the objects that should be multiplied.
1031
1032=item connected <number>
1033
1034See generic object field section.
1035
1036=back
663 1037
664=head3 HOLE - type 94 - Holes 1038=head3 HOLE - type 94 - Holes
665 1039
666Holes are holes in the ground where objects can fall through. When the hole 1040Holes are holes in the ground where objects can fall through. When the hole
667opens and/or is completly open all objects above it fall through (more 1041opens and/or is completly open all objects above it fall through (more
668precisely: if their head is above the hole). 1042precisely: if their head is above the hole).
1043
1044When the HOLE is activated it's speed is set to 0.5.
669 1045
670Trapdoors can only transfer the one who falls through to other coordinates 1046Trapdoors can only transfer the one who falls through to other coordinates
671on the B<same> map. 1047on the B<same> map.
672 1048
673=over 4 1049=over 4
718=over 4 1094=over 4
719 1095
720=item dam <number> 1096=item dam <number>
721 1097
722Each time the poisoning is processed (which is determined by the speed and speed_left 1098Each time the poisoning is processed (which is determined by the speed and speed_left
723fields, see the general object attributes above) it hits the player with 1099fields, see the general object fields above) it hits the player with
724<number> damage and the AT_INTERNAL attacktype (means: it will simply 1100<number> damage and the AT_INTERNAL attacktype (means: it will simply
725hit the player with no strings attached). 1101hit the player with no strings attached).
726 1102
727=item food <number> 1103=item food <number>
728 1104
740inventory. 1116inventory.
741 1117
742Forces only take effect on the player if they have set FLAG_APPLIED. 1118Forces only take effect on the player if they have set FLAG_APPLIED.
743 1119
744Whether the duration field is processed or not a tick is controlled via the 1120Whether the duration field is processed or not a tick is controlled via the
745speed and speed_left field. Look above at the generic description of these 1121speed and speed_left field. Look above in the generic object field description.
746fields.
747 1122
748NOTE: Setting FLAG_IS_USED_UP on an force will also consider the 'food' field 1123NOTE: Setting FLAG_IS_USED_UP on an force will also consider the 'food' field
749like stated above in the FLAG_IS_USED_UP description. BUT: If the food field reaches 1124like stated above in the FLAG_IS_USED_UP description. BUT: If the food field reaches
7500 before duration and FLAG_APPLIED is set, the force will last for 'duration'. 11250 before duration and FLAG_APPLIED is set, the force will last for 'duration'.
751If the FLAG_APPLIED is not set the force is removed when food reaches 0. 1126If the FLAG_APPLIED is not set the force is removed when food reaches 0.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines