[ViewVC] Annotation of: cvs/deliantra/server/doc/historic/Developers/skills

SKILLS/EXPERIENCE DOCUMENTATION for DEVELOPERS
----------------------------------------------

- Summary -

0. Introduction 

1. Sketch of system
   a. Initialization - how skills and experience are linked 

2. How to add new skills
   a. creation of new skill: outline of needed steps

3. Detail of skill archetype values.
   
4. Skill Tools

5. Skill Scrolls

6. Other Objects

7. Workings of the Skill System

8. Changes & Limitations

-------------------------------------------------------------------------
0. Introduction
---------------

Skills were redone to a large extent in April 2003.  This document has been
updated to reflect how the skills work.

The main change is that experience categories were removed from the game.
Instead, experience goes to the skill itself.  Thus. how good a player is at
the skills is directly proportional to how good they are at that skill, and
not the category itself.

1. Sketch of system
-------------------

In the skills/experience code, players gain experience for the activities
which they perform in the game ("You are what you do").  The activities a
player may engage in are controlled by the skills they possess. All players
start with a basic set of skills which they may expand through adventuring.
While monsters do not gain experience from the use of skills, they may use any
skills which exist in their inventory if they have the can_use_skill flag set.

In the code, skills are objects which exist in the player/monster inventory.
Both NPC/monsters and players use the same skill archetypes. Not all skills
are however enabled for monster use. Check the Skills_players.doc for
available NPC skills.

The experience one gets for a skill is greatly simplified.  No longer
is it weighted based on the stats of the player.  Rather, the experience is
based on what the skill was used for - opening a tough trap gets more
exp than opening an easy trap.  The stats the player has will improve
the chances of success in most cases - this is bonus enough without also
gaining additional experience.

The chracters total experience is no longer related to the sum of experience
in the players skills - A player could for example only of 1000 exp, but have
skills with 2500 exp, 300 exp, etc.  Removing the tie between skills and total
experience allows for reasonable skill advancement - you can allow a player
to easily get to level 20 in a skill without them now being level 20 player.

Note also that the only tunables are now in the code or in the archetypes -
if the exp for disarming is out of whack, the code would need to be changed
to give more appropriate amounts.

2. How to add new skills
-------------------------

Adding a new skill to CF is not overly difficult, it is little more difficult
than adding new archetypes and a spell to the game.

a. creation of new skill: outline of needed steps

A number of steps are required to create a new skill. 

1) Edit a new skills archetype. See below for appropriate parameters.  If
   you desire the skill to be a skill tool, edit a "face" for the new skill.
   If you want to have the skill to be learned via a skill scroll, edit a
   skillscroll for the skill.  Place the new archetype(s) in the
   lib/arch/skills directory.  Remember to name your new skill appropriately
   (ie skill_<new skill name>).  Make sure you select a unique subtype
   for your new skill.

2) Edit skill_util.c. Add an entry for the skill in do_skill() (so that it may
   be used as a "long-range attack"). If the new skill is a hth attack take a
   look at the attack_hth_skills[] table in do_skill_attack() -- where does
   the hth attack rank? The most useful attacks should occur earlier in the
   table.

3) Create the skill code. If you created a hth attack, you probably can get
   away with just using attack_hth. For other skills, put the skill code in
   skills.c. If your new skill is to be an "associated" skill, then make sure
   that it returns the value of calc_skill_exp().

4) Edit treasures/artifacts file as needed (esp. if your skill will become one
   of the starting skills, or will show up in shops.)


3. Detail of skill archetype values.
------------------------------------

This section details the various object/archetype values.

First, we detail skill objects:
type: SKILL (43)
subtype: subtype of skill
invisible: 1
no_drop: 1

name: Name of the skill, used by things like 'use_skill', as well as output
    of 'skills' command.

skill: Same as name - this simplifies code, so that we can look at
    op->skill for both skills and skill tools. It also means that if a skill
    named is passed, we can verify we have the matching entry.

stats (Str, Dex, sp, grace, etc): These modify the abilities of the player,
    in a sense giving bonuses.

expmul: this is the ratio of experience the players total should increase by
    when this skill is use.  If this is zero, then experience only goes to
    to the skill.  Values higher than 1 are allowed.  Note that experience
    rewarded to the players total is in addition to that given to the
    skill.  Eg, if player should get 500 exp for using a skill, and
    expmul is 1, the player will get 500 added to that skill as well as
    500 to their total.

exp: The exp the player has in the skill (object).  If this is an archetype,
   this contains the base amount the player gets for using the skill.
   exp will be set to 0 when the skill is given to the player.

level: Object: The level of this skill - this is just determined from the exp
   above based on the experience table.  Archetype: This is a percentage value
   that determines how the level difference effects experience rewards (like
   the old lexp value).  Basically, if it is set to 100, the ratio is normal
   (eg, if opponent is twice level of player, player would get twice as much
   normal exp).  If level is 200, player would get 4 times.  If level if 50,
   player would half normal.  If level is 0, then we don't adjust exp reward
   based on level.

can_use_skill (flag): If this is set, the player knows the skill natively
   (eg, does not need a skill tool, see below).  If this is not set,
   then this skill object is acting as a container for experience.
   For example, if a player is using a holy symbol in order to get his
   praying skill, we still need to have skill_praying in the players
   inventory to store the experience in.  However, the player can't
   use that praying skill without a holy symbole until they learn it from a
   skill scroll.


4. Skill Tools
-----------------

Skill tools are items that let a player use a skill they do not otherwise
know.  Skill tools may also have advantages, eg, spellpaths they grant to the
caster, stat bonuses, etc.

Most of the values for the skill tools are just like normal equipment
(value, weight, face, body_..., ) fields.

type: skill_tool (74)
skill: Name of the skill this object allows the user of.

Note - the old skill code used 'sp' to denote the skill to use.

5. Skill Scrolls
----------------
type: SKILLSCROLL
skill: Name of the skill to be learned
Rest of the values are per normal equipment (weight, value, identified,
 etc).


6. Other Objects
----------------

Many other objects will use the 'skill' field in their object to denote
what skill is needed to use this object.  Thus, for examples, readable
objects have 'skill literacy' to denote that the literacy skill is
needed to read them.  Weapons have 'skill' values to denote what
skill is needed to use the weapon.  Same for spells.
 

-------------------------------
7. Workings of the Skill System
-------------------------------

This section attempts to briefly explain how this all works.

Due to the addition of the skill pointer, it is no longer required
that a skill be in the ready_skill position to gain experience.

Whenever a player tries to use skill either directly (ready_skill ..)
or indirectly (cast a spell which requires knowledge of the skill), the
code will examine the players inventory to see if they an in fact
use the skill.  This first checks to see if the player has the appropriate
skill archetype in their object.  If they do, and can_use_skill is set
to 1, nothing more is done.  If that is not the case, we then look for
a skill tool.  If none is found, we tell the player the can't use the
skill.  If one is found, we try to apply the skill tool - if this can not
be done, we also error out.

Only if the player explicitly activates a skill with ready_skill do
we change the players range pointer.  Otherwise, it will remain as is
(but not that casting a spell might also change the range pointer).

add_exp has been modified to take two additional parameters -
skill_name and flag.

skill_name is the skill to add the experience to.  By passing this
to add exp, a lot of the code no longer needs to change chosen_skill,
then reset it back again.


flag determines what to do if the player does not currently have the
skill pointer in their inventory.  This can arise if the player
is using a skill tool, or part of a party.

In the default case of flag being 0, if the player does not currently
have the skill in their inventory, this is added (with can_use_skill 0).
If flag is 1, we add the exp to the players total exp, but don't
give them any in the skill.  If it is 2, the player gets nothing.

This fixes many of the abuses of party combat - if a member of your
party is killing things with wizardry, you'll get wizardry exp.  If
you don't have wizardry, you'll get some general exp, but you can't
funnel it into things like alchemy anymore.

The effect of flag 1 to add exp is so that that a player can't have
thousands of exp in a skill and never have used in themselves - for a player
to have any exp in a skill, he will have had to use it at least once.  Note
however that a player could have used the skill just once (to say kill a
kobold) and yet get a bunch more exp from party members that are actually good
wizards.

The handling of add_exp with skill_name is pretty simple.  In most cases, we
know immediately the skill that was used (eg, melee combat, search, disarm,
etc).  In cases of indirect death (spells), we set the skill in the spell
object to the skill that it should get awarded to.

------------------------
8. Changes & Limitations
------------------------

The old skill system had the idea of stats that effect the skill.  There
is no good way to do that within the new system - instead, the code
the executes the skill will do this.  This really isn't much worse
than the old system anyways - the old code still did things like
'stat average * 3' or otherwise determine how important the stats are.

 In addition, this allows for more flexibility for multi faceted
skills.  For example, the identification portion of some skills should
probably use int, but the creation portion should perhaps be dex and strength.

There is no more SK_level function - while this could still be useful
to replace code like 

level= op->chosen_skill?op->chosen_skill->level:op->level;

the use of automatically de-referencing the op->chosen_skill is not
suggested - the new skill system is much more lenient on passing the
appropriate skill object to functions that need it, so calls to
SK_level in most cases may not really be the right approach - in many
cases, the chosen_skill may not be what the code is really expecting.

Revision:	1.1
Committed:	Thu Sep 7 21:42:57 2006 UTC (17 years, 10 months ago) by pippijn
Branch:	MAIN
CVS Tags:	rel-2_82, rel-2_81, rel-2_80, rel-3_1, rel-3_0, rel-2_6, rel-2_7, rel-2_4, rel-2_5, rel-2_2, rel-2_3, rel-2_0, rel-2_1, rel-2_72, rel-2_73, rel-2_71, rel-2_76, rel-2_77, rel-2_74, rel-2_75, rel-2_54, rel-2_55, rel-2_56, rel-2_79, rel-2_52, rel-2_53, rel-2_32, rel-2_90, rel-2_92, rel-2_93, rel-2_78, rel-2_61, rel-2_43, rel-2_42, rel-2_41, HEAD
Log Message:	Moved documents to doc/historic
#	User	Rev	Content
1	pippijn	1.1	SKILLS/EXPERIENCE DOCUMENTATION for DEVELOPERS
2			----------------------------------------------
3
4			- Summary -
5
6			0. Introduction
7
8			1. Sketch of system
9			a. Initialization - how skills and experience are linked
10
11			2. How to add new skills
12			a. creation of new skill: outline of needed steps
13
14			3. Detail of skill archetype values.
15
16			4. Skill Tools
17
18			5. Skill Scrolls
19
20			6. Other Objects
21
22			7. Workings of the Skill System
23
24			8. Changes & Limitations
25
26			-------------------------------------------------------------------------
27			0. Introduction
28			---------------
29
30			Skills were redone to a large extent in April 2003. This document has been
31			updated to reflect how the skills work.
32
33			The main change is that experience categories were removed from the game.
34			Instead, experience goes to the skill itself. Thus. how good a player is at
35			the skills is directly proportional to how good they are at that skill, and
36			not the category itself.
37
38			1. Sketch of system
39			-------------------
40
41			In the skills/experience code, players gain experience for the activities
42			which they perform in the game ("You are what you do"). The activities a
43			player may engage in are controlled by the skills they possess. All players
44			start with a basic set of skills which they may expand through adventuring.
45			While monsters do not gain experience from the use of skills, they may use any
46			skills which exist in their inventory if they have the can_use_skill flag set.
47
48			In the code, skills are objects which exist in the player/monster inventory.
49			Both NPC/monsters and players use the same skill archetypes. Not all skills
50			are however enabled for monster use. Check the Skills_players.doc for
51			available NPC skills.
52
53			The experience one gets for a skill is greatly simplified. No longer
54			is it weighted based on the stats of the player. Rather, the experience is
55			based on what the skill was used for - opening a tough trap gets more
56			exp than opening an easy trap. The stats the player has will improve
57			the chances of success in most cases - this is bonus enough without also
58			gaining additional experience.
59
60			The chracters total experience is no longer related to the sum of experience
61			in the players skills - A player could for example only of 1000 exp, but have
62			skills with 2500 exp, 300 exp, etc. Removing the tie between skills and total
63			experience allows for reasonable skill advancement - you can allow a player
64			to easily get to level 20 in a skill without them now being level 20 player.
65
66			Note also that the only tunables are now in the code or in the archetypes -
67			if the exp for disarming is out of whack, the code would need to be changed
68			to give more appropriate amounts.
69
70			2. How to add new skills
71			-------------------------
72
73			Adding a new skill to CF is not overly difficult, it is little more difficult
74			than adding new archetypes and a spell to the game.
75
76			a. creation of new skill: outline of needed steps
77
78			A number of steps are required to create a new skill.
79
80			1) Edit a new skills archetype. See below for appropriate parameters. If
81			you desire the skill to be a skill tool, edit a "face" for the new skill.
82			If you want to have the skill to be learned via a skill scroll, edit a
83			skillscroll for the skill. Place the new archetype(s) in the
84			lib/arch/skills directory. Remember to name your new skill appropriately
85			(ie skill_<new skill name>). Make sure you select a unique subtype
86			for your new skill.
87
88			2) Edit skill_util.c. Add an entry for the skill in do_skill() (so that it may
89			be used as a "long-range attack"). If the new skill is a hth attack take a
90			look at the attack_hth_skills[] table in do_skill_attack() -- where does
91			the hth attack rank? The most useful attacks should occur earlier in the
92			table.
93
94			3) Create the skill code. If you created a hth attack, you probably can get
95			away with just using attack_hth. For other skills, put the skill code in
96			skills.c. If your new skill is to be an "associated" skill, then make sure
97			that it returns the value of calc_skill_exp().
98
99			4) Edit treasures/artifacts file as needed (esp. if your skill will become one
100			of the starting skills, or will show up in shops.)
101
102
103
104			3. Detail of skill archetype values.
105			------------------------------------
106
107			This section details the various object/archetype values.
108
109			First, we detail skill objects:
110			type: SKILL (43)
111			subtype: subtype of skill
112			invisible: 1
113			no_drop: 1
114
115			name: Name of the skill, used by things like 'use_skill', as well as output
116			of 'skills' command.
117
118			skill: Same as name - this simplifies code, so that we can look at
119			op->skill for both skills and skill tools. It also means that if a skill
120			named is passed, we can verify we have the matching entry.
121
122			stats (Str, Dex, sp, grace, etc): These modify the abilities of the player,
123			in a sense giving bonuses.
124
125			expmul: this is the ratio of experience the players total should increase by
126			when this skill is use. If this is zero, then experience only goes to
127			to the skill. Values higher than 1 are allowed. Note that experience
128			rewarded to the players total is in addition to that given to the
129			skill. Eg, if player should get 500 exp for using a skill, and
130			expmul is 1, the player will get 500 added to that skill as well as
131			500 to their total.
132
133			exp: The exp the player has in the skill (object). If this is an archetype,
134			this contains the base amount the player gets for using the skill.
135			exp will be set to 0 when the skill is given to the player.
136
137			level: Object: The level of this skill - this is just determined from the exp
138			above based on the experience table. Archetype: This is a percentage value
139			that determines how the level difference effects experience rewards (like
140			the old lexp value). Basically, if it is set to 100, the ratio is normal
141			(eg, if opponent is twice level of player, player would get twice as much
142			normal exp). If level is 200, player would get 4 times. If level if 50,
143			player would half normal. If level is 0, then we don't adjust exp reward
144			based on level.
145
146			can_use_skill (flag): If this is set, the player knows the skill natively
147			(eg, does not need a skill tool, see below). If this is not set,
148			then this skill object is acting as a container for experience.
149			For example, if a player is using a holy symbol in order to get his
150			praying skill, we still need to have skill_praying in the players
151			inventory to store the experience in. However, the player can't
152			use that praying skill without a holy symbole until they learn it from a
153			skill scroll.
154
155
156			4. Skill Tools
157			-----------------
158
159			Skill tools are items that let a player use a skill they do not otherwise
160			know. Skill tools may also have advantages, eg, spellpaths they grant to the
161			caster, stat bonuses, etc.
162
163			Most of the values for the skill tools are just like normal equipment
164			(value, weight, face, body_..., ) fields.
165
166			type: skill_tool (74)
167			skill: Name of the skill this object allows the user of.
168
169			Note - the old skill code used 'sp' to denote the skill to use.
170
171			5. Skill Scrolls
172			----------------
173			type: SKILLSCROLL
174			skill: Name of the skill to be learned
175			Rest of the values are per normal equipment (weight, value, identified,
176			etc).
177
178
179			6. Other Objects
180			----------------
181
182			Many other objects will use the 'skill' field in their object to denote
183			what skill is needed to use this object. Thus, for examples, readable
184			objects have 'skill literacy' to denote that the literacy skill is
185			needed to read them. Weapons have 'skill' values to denote what
186			skill is needed to use the weapon. Same for spells.
187
188
189			-------------------------------
190			7. Workings of the Skill System
191			-------------------------------
192
193			This section attempts to briefly explain how this all works.
194
195			Due to the addition of the skill pointer, it is no longer required
196			that a skill be in the ready_skill position to gain experience.
197
198			Whenever a player tries to use skill either directly (ready_skill ..)
199			or indirectly (cast a spell which requires knowledge of the skill), the
200			code will examine the players inventory to see if they an in fact
201			use the skill. This first checks to see if the player has the appropriate
202			skill archetype in their object. If they do, and can_use_skill is set
203			to 1, nothing more is done. If that is not the case, we then look for
204			a skill tool. If none is found, we tell the player the can't use the
205			skill. If one is found, we try to apply the skill tool - if this can not
206			be done, we also error out.
207
208			Only if the player explicitly activates a skill with ready_skill do
209			we change the players range pointer. Otherwise, it will remain as is
210			(but not that casting a spell might also change the range pointer).
211
212			add_exp has been modified to take two additional parameters -
213			skill_name and flag.
214
215			skill_name is the skill to add the experience to. By passing this
216			to add exp, a lot of the code no longer needs to change chosen_skill,
217			then reset it back again.
218
219
220			flag determines what to do if the player does not currently have the
221			skill pointer in their inventory. This can arise if the player
222			is using a skill tool, or part of a party.
223
224			In the default case of flag being 0, if the player does not currently
225			have the skill in their inventory, this is added (with can_use_skill 0).
226			If flag is 1, we add the exp to the players total exp, but don't
227			give them any in the skill. If it is 2, the player gets nothing.
228
229			This fixes many of the abuses of party combat - if a member of your
230			party is killing things with wizardry, you'll get wizardry exp. If
231			you don't have wizardry, you'll get some general exp, but you can't
232			funnel it into things like alchemy anymore.
233
234			The effect of flag 1 to add exp is so that that a player can't have
235			thousands of exp in a skill and never have used in themselves - for a player
236			to have any exp in a skill, he will have had to use it at least once. Note
237			however that a player could have used the skill just once (to say kill a
238			kobold) and yet get a bunch more exp from party members that are actually good
239			wizards.
240
241			The handling of add_exp with skill_name is pretty simple. In most cases, we
242			know immediately the skill that was used (eg, melee combat, search, disarm,
243			etc). In cases of indirect death (spells), we set the skill in the spell
244			object to the skill that it should get awarded to.
245
246			------------------------
247			8. Changes & Limitations
248			------------------------
249
250			The old skill system had the idea of stats that effect the skill. There
251			is no good way to do that within the new system - instead, the code
252			the executes the skill will do this. This really isn't much worse
253			than the old system anyways - the old code still did things like
254			'stat average * 3' or otherwise determine how important the stats are.
255
256			In addition, this allows for more flexibility for multi faceted
257			skills. For example, the identification portion of some skills should
258			probably use int, but the creation portion should perhaps be dex and strength.
259
260			There is no more SK_level function - while this could still be useful
261			to replace code like
262
263			level= op->chosen_skill?op->chosen_skill->level:op->level;
264
265			the use of automatically de-referencing the op->chosen_skill is not
266			suggested - the new skill system is much more lenient on passing the
267			appropriate skill object to functions that need it, so calls to
268			SK_level in most cases may not really be the right approach - in many
269			cases, the chosen_skill may not be what the code is really expecting.
270