data dirs renamed
[k8-i-v-a-n.git] / Doc / Obsolete / char.txt
blob62ec2e6f0f2d14a7ad1ef3ba212ae395dbd723d6
1 ----------------------------------------------------------------------------
3             How to make a new character type, step-by-step tutorial
5 ----------------------------------------------------------------------------
7 1. Choose whether you want to make an abstract character type, i.e. one that
8    is a base class for other character types but itself can't be
9    instantiated, like a "humanoid", or a concrete character like a "flat
10    mommo slime".
11 2. Choose whether you want to place the code of the character's constructor
12    in a header file or a source file. You generally choose the latter only
13    when you want to add items into the creatures backpack during it's
14    creation process, like a six pack of pepsi for Oree the Pepsi Daemon King.
15 3. If you chose concrete character with header constructor, goto 4.
16    If you chose abstract character with header constructor, goto 5.
17    If you chose concrete character with source constructor, goto 6.
18    If you chose abstract character with source constructor, goto 7.
20 ----------------------------------------------------------------------------
22 4. Use a syntax like the following:
24         HEADER_CONSTRUCTED_CHARACTER(
25                 name,
26                 base,
27                 cparameters,
28                 bparameters,
29                 dparameters,
30                 constructor,
31                 load,
32                 type,
33                 possibility,
34                 data
35         );
37    4.01. Add this at the end of char.h.
38    4.02. Replace "name" with the code name of the new character. This is
39          the character's true name written in lowercase without any spaces
40          or special letters. You may also shorten it somewhat as long as
41          it's clear whom you mean. I.e. "pure mass of Bill's will" could be
42          in this syntax just "billswill".
43    4.03. Replace "base" with the code name of the base class, like
44          "character", "humanoid" or "frog". The new class inherits all
45          specialities of the base class.
46    4.04. Replace "cparameters" with "NORMAL_CHILD_PARAMETERS" if your
47          class is not derived from "humanoid", "HUMANOID_CHILD_PARAMETERS"
48          otherwise.
49    4.05. Replace "bparameters" with "NORMAL_BASE_PARAMETERS" or
50         "HUMANOID_BASE_PARAMETERS" as above.
51    4.06. Replace "dparameters" with the following:
53          (
54           NewMaterial(1, material),
55           size,
56           agility,
57           strength,
58           endurance,
59           perception,
60           relation
61          )
63         4.6.1. Replace "material" with the correct material, like
64                "new ennerbeastflesh(60000)".
65         4.6.2. Specify size, agility, strength, endurance and perception.
66         4.6.3. Specify the initial relation (0==hostile, 1==neutral,
67                2==friend) to the player character. (usually this is 0)
68         4.6.4. If your character is derived from "humanoid", add the
69                following parameters between perception and relation:
70                index-of-arm-picture, index-of-head-picture,
71                index-of-legs-picture, index-of-torso-picture.
72                All indices refer to the order of pictures in human.pcx,
73                of course.
75    4.07. Replace "constructor" with empty brackets, or optionally write
76          some brief constructor code between them.
77    4.08. Replace "load" with empty brackets, or optionally write some brief
78          loading code between them.
79    4.09. Look above your class. Pick the last concrete class declared there,
80          and take its "type". Add one to this, and place the result to
81          "type".
82    4.10. Replace "possibility" with 0 if you don't want these monster
83          to appear randomly in the dungeon. Otherwise use any other
84          number.
85    4.11. Place all the functions you want to overwrite to the "data"
86          field. The essential functions are:
88          NAME_SINGULAR RET(<name here>)
89          NAME_PLURAL RET(<plural name here>)
90          DANGER RET(<danger number here>)
92          Which specify the name of the character and its danger level,
93          which affects how strong the player must be for this character
94          to start appearing in the dungeon.
96          If your character is not a humanoid, you must also specify this
97          function:
99          C_BITMAP_POS RETV(x, y)
101          Replace x and y with the coordinates of the character's
102          picture in char.pcx.
104          Add any other functions here you want, like CHARMABLE RET(false)
105          or CAN_WIELD RET(true). If the function code is long, place
106          semicolon (;) in the place of "RET(<something>)" and write
107          your code to char.cpp instead.
109    4.12. Your character is ready!
111 ----------------------------------------------------------------------------
113 5. Use a syntax like the following:
115         HEADER_CONSTRUCTED_BASE(
116                 name,
117                 base,
118                 cparameters,
119                 bparameters,
120                 constructor,
121                 load,
122                 data
123         );
125    5.01. Add this at the end of char.h.
126    5.02. Replace "name" with the code name of this new base class.
127    5.03. Replace "base" with the code name of the base class of this base
128          class, like "character" or "humanoid". The new base class and all
129          its derived classes will inherit all specialities of the base.
130    5.04. Replace "cparameters" with "NORMAL_CHILD_PARAMETERS" if your class
131          is not derived from "humanoid", "HUMANOID_CHILD_PARAMETERS" otherwise.
132    5.05. Replace "bparameters" with "NORMAL_BASE_PARAMETERS" or
133         "HUMANOID_BASE_PARAMETERS" as above.
134    5.06. Replace "constructor" with empty brackets, or optionally write
135          some brief constructor code between them.
136    5.07. Replace "load" with empty brackets, or optionally write some brief
137          loading code between them.
138    5.08. Place all the functions you want to overwrite to the "data"
139          field. Add any functions here you want, like CHARMABLE RET(false)
140          or CAN_WIELD RET(true). If the function code is long, place
141          semicolon (;) in the place of "RET(<something>)" and write
142          your code to char.cpp instead. All character classes derived
143          from your base will inherit these functions.
145    5.09. Your new base class is ready!
147 ----------------------------------------------------------------------------
149 6. Use a syntax like the following:
151         SOURCE_CONSTRUCTED_CHARACTER(
152                 name,
153                 base,
154                 cparameters,
155                 type,
156                 possibility,
157                 data
158         );
160    6.01. Add this at the end of char.h.
161    6.02. Replace "name" with the code name of the new character. This is
162          the character's true name written in lowercase without any spaces
163          or special letters. You may also shorten it somewhat as long as
164          it's clear whom you mean. I.e. "pure mass of Bill's will" could be
165          in this syntax just "billswill".
166    6.03. Replace "base" with the code name of the base class, like
167          "character", "humanoid" or "frog". The new class inherits all
168          specialities of the base class.
169    6.04. Replace "cparameters" with "NORMAL_CHILD_PARAMETERS" if your
170          class is not derived from "humanoid", "HUMANOID_CHILD_PARAMETERS"
171          otherwise.
172    6.05. Make your new non-default constructor to char.cpp. Use the
173          following syntax if your character is not a humanoid:
175          name::name(material** Material, vector BitmapPos, ushort Size,
176          ushort Agility, ushort Strength, ushort Endurance,
177          ushort Perception, uchar Relations) : base(Material, BitmapPos,
178          Size, Agility, Strength, Endurance, Perception, Relations) {}
180          If it is, use this:
182          name::name(material** Material, vector BitmapPos, ushort Size,
183          ushort Agility, ushort Strength, ushort Endurance,
184          ushort Perception, uchar PArmType, uchar PHeadType, uchar PLegType,
185          uchar PTorsoType, uchar Relations) : base(Material, BitmapPos, Size,
186          Agility, Strength, Endurance, Perception, PArmType, PHeadType,
187          PLegType, PTorsoType, Relations) {}
189          Write your construction code between the empty brackets. Then make
190          the new default constructor as follows:
192          name::name(void) : base(dparameters) {}
194          Refer to 4.06. for information about dparameters. Then copy your
195          non-default constructor's code inside the brackets.
197    6.06. Look above your class. Pick the last concrete class declared there,
198          and take its "type". Add one to this, and place the result to
199          "type".
200    6.07. Replace "possibility" with 0 if you don't want these monster
201          to appear randomly in the dungeon. Otherwise use any other
202          number.
203    6.08. Place all the functions you want to overwrite to the "data"
204          field. The essential functions are:
206          NAME_SINGULAR RET(<name here>)
207          NAME_PLURAL RET(<plural name here>)
208          DANGER RET(<danger number here>)
210          Which specify the name of the character, and its danger level,
211          which affects how strong the player must be for this character
212          to start appearing in the dungeon.
214          If your character is not a humanoid, you must also specify this
215          function:
217          C_BITMAP_POS RETV(x, y)
219          Replace x and y with the coordinates of the character's
220          picture in char.pcx.
222          Add any other functions here you want, like CHARMABLE RET(false)
223          or CAN_WIELD RET(true). If the function code is long, place
224          semicolon (;) in the place of "RET(<something>)" and write
225          your code to char.cpp instead.
227    6.09. Your character is ready!
229 ----------------------------------------------------------------------------
231 7. Use a syntax like the following:
233         SOURCE_CONSTRUCTED_BASE(
234                 name,
235                 base,
236                 cparameters,
237                 data
238         );
240    7.01. Add this at the end of char.h.
241    7.02. Replace "name" with the code name of this new base class.
242    7.03. Replace "base" with the code name of the base class of this base
243          class, like "character" or "humanoid". The new base class and all
244          its derived classes will inherit all specialities of the base.
245    7.04. Replace "cparameters" with "NORMAL_CHILD_PARAMETERS" if your
246          class is not derived from "humanoid", "HUMANOID_CHILD_PARAMETERS"
247          otherwise.
248    7.05. Make your new non-default constructor to char.cpp. Use the
249          following syntax if your character is not a humanoid:
251          name::name(material** Material, vector BitmapPos, ushort Size,
252          ushort Agility, ushort Strength, ushort Endurance,
253          ushort Perception, uchar Relations) : base(Material, BitmapPos,
254          Size, Agility, Strength, Endurance, Perception, Relations) {}
256          If it is, use this:
258          name::name(material** Material, vector BitmapPos, ushort Size,
259          ushort Agility, ushort Strength, ushort Endurance,
260          ushort Perception, uchar PArmType, uchar PHeadType, uchar PLegType,
261          uchar PTorsoType, uchar Relations) : base(Material, BitmapPos, Size,
262          Agility, Strength, Endurance, Perception, PArmType, PHeadType,
263          PLegType, PTorsoType, Relations) {}
265          Write your construction code between the empty brackets.
267    7.06. Place all the functions you want to overwrite to the "data"
268          field. Add any functions here you want, like CHARMABLE RET(false)
269          or CAN_WIELD RET(true). If the function code is long, place
270          semicolon (;) in the place of "RET(<something>)" and write
271          your code to char.cpp instead. All character classes derived
272          from your base will inherit these functions.
274    7.07. Your new base class is ready!
276 ----------------------------------------------------------------------------
278 End of document.