The "artifacts" file

NOTE:
Running daimonin with -m3 creates a nice list of this table.
Good for debugging if you seem to have problems with some entry.

A artifacts entry defines new objects, using the arch files as base objects and changing
the default values. This file is historical used for "artifacts" - unique magic items.
But it has some more powers. It is used to generate different objects using the same base
object - for example is there only one potion object in the arches, called "potion_generic".
In the arch file, this base object is changed to the different potions with the different
effects.

A artifacts entry starts with the keyword "Allowed", followed by some more keywords, used
by the artifacts list which is generated from the artifacts file. The body part follows
after the "Object" command. All commands between "Object" and the "end" are the same
as can be in a normal arch file and they are read in from the same parser.

Allowed <name1>,<name2> OR 'none'
chance xx
difficulty yy
name <name_in_arch_list>
def_arch <arch_name>
Object <name>
...
...
end

After the 'Allowed <whatever>' field, a 'chance <value>' field
follows.  This is how likely the item is to be created.  It is relative
to other objects of the same type.  What happens is that all of the
artifacts with the same type are put on 1 list, and their chance
field is summed together.  Then, when an artifact is created,
a roll is made based on that sum, and the appropriate artifact
is chosen.  If the item being transformed can not turn into that
artifact (magic bonus, difficulty (see below), or just not 'Allowed'),
it will be re-rolled, attempting to make an artifact again.  The number
of re-rolls attempted is determined in the treasure.c file.  IT is,
by default, 1. chance is meaningless if there is only 1 artifact of a
certain type.  It will always be generated, no matter what the chance
is set to.  As such, if adding an artifact for a new type,
make sure there are at least two, unless you always want
that specific one to be generated.

A 'Allowed none' is a special case, used by unique artifacts. It is explained
in the 'name & def_arch' area. Artifacts with 'allowed none' are don't be used
by normal artifacts creation.

'difficulty <value>' can also be included before the 'Object <name>'
field.  If set, the difficulty must be greater or equal to that
value in order to the object to be created.  This can make it so that
some items are never created on easy maps.

The 'name' of the artifact entry is used in 2 ways. In the past, the string
after the "Object" command was used to find a artifacts entry - this was buggy,
because there can be multiply entrys for the same item type with the same name
using the "Object <title>" entry (the string after the Object is called "title"
because the artifacts file use it as title, putting a "of" before it).

This has changed and the 'name' entry is now used. This is in the most cases used from
the trasure file, calling in a treasure creation the artifacts routine with a given base
object and sometimes with a fixed layer name too. For example are there many different types
of weapons (sword, axes, spears, etc). The rules to add a new attack type to a weapon are
for all weapons the same. The artifacts entries can be called for different base objects
- patching them all with the same entry.

The 2nd way is the use of the 'name' entry (with the def_arch) IN THE SAME WAY
like a arch name. If a creation function is called (treasure file, map loader,
DM "/create" command, ...) the create_object() search this names in the same way
it search the normal arch list.

The 'def_arch' entry is nothing else as a normal base arch. When the artifacts file is
loaded, this base arch is copied, patched with the values of the artifacts entry and added
to the normal arch list.

This allows the use of the artifacts entries in 2 ways: as patches for normal arches and as
"unique" arches for a fixed base arch. For example is there only one "Stormbringer" sword,
using a broadsword base arch. The name is unique as the object itself. Even when there be
multiply Stormbringer swords in the game used by different players, we don't want "spear Stormbringer" or "dagger Stormbringer" (in fact, a DM can force the creation of a
"spear Stormbringer" by using the /create command with a spear and 'Stormbringer' as
artifacts spear). But the item can't be generated by the treasure file when the
'allowed' command has the parameter 'none'.

More interesting is, that when a 'unique' artifact is created, the def_arch is copied
and patched. In this process, the new arch is added to the arch list, using the new
'name' from the artifacts list as arch name. But the old name of the def_arch is stored
too in this list!

This means, that when we create a object "Stormbringer" - the object_creation() will create
and use it like it is a base arch defined in the arches. But because we stored the def_arch,
it is possible for the server to track down which base arch this "fake arch" use. The normal
server function don't care about it and use it like a normal arch object. But for example
the function for "cancellation" CAN look deeper in the arch - So a real powerful magic
can dispel the items power - and it will be a normal broadsword.

This means, that the server can INSIDE track down the patch history of every item and go
backwards. This will allow powerful game mechanism like cancellation, dispel or even
"block magic". The server can in every case using the right "non magic" base item.

It should be the goal to use for every magic item which magic can be blocked or dispelled
to use a unmagical base item (= normal arch) and using the artifacts file for creating
the item.

Note:
The above mentioned fields (chance, difficulty) must be set before the
Object command - if they are placed between the Object and End commands,
they will have no affect.

Because the arch commands after the Object command are used to "patch" the
used base arch, this commands are used in some cases different as the
normal arch commands:

# List of artifact modifiers
#
#	Attributes (str, dex, etc) are modifiers to the previous
#	value - positive will increase it by that much, negative
#	will decrease it.
#
#	cursed and damned flags will make the object cursed/damned.
#	no way to remove cursed/damnedness right now.  If the
#	object is cursed, the present magic value will become
#	negative (ie, a +1 sword will become -1 cursed.)
#
#	path_attuned, path_denied, path_repelled values are OR'd to existing values.
#
#	luck,exp, wc and ac  increase the value by that amount (which means
#	a negative value will decrease the value)
#
#	lifesave, reflect_spell, reflect_missile, stealth, xrays,
#	and see_invisible invisible sets the appropriate value
#	in the new artifact.  No way to remove these abilities.
#
#	if stand_still is set, the object will not be animated
#	(useful if giving an artifact a new image when the object
#	it is being created from is animated.
#
#	nrof is the number of object to be created.  A range
#	of 1-nrof of objects will be created.  If 0, then the
#	default number will be used instead.
#
#	hp, maxhp, sp, maxsp, food, level have this:  If the value is
#	positive, it is increased by that amount.  If negative, the
#	artifact is created with that value absolute (ie, hp -5
#	will create and artifact with hp value of 5)
#
#	dam:  If negative, absolute value is used (as in
#	hp, maxhp, etc above).  If positive, it acts as a percentage
#	in increments of 10 (a value of 10 has the normal value, 5
#	would be half normal, 20 twice, etc.
#
#	weight, last_sp, last_heal is in percent (200% would
#	be twice normal, 50% half of normal).  Negative values
#	work the same as armour and dam.
#
#	'value' is a multiplier to the previous value (value 10
#	means the object is worth 10 times normal)
#    Is 'value' is < 0, the value is multiplied by -1 and used as new value.
#
#	the 'material', 'material_real#, 'slaying', and 'msg' elements will
#	replace exiting values.
#
#	magic is the mininum magic for an item to become that artifact.
#
#	If the value is not described above, changing it probably is
#	not supported.
#

Note:

Try to keep common types of items together.  For example, keep
all helmets types together, all weapon types, etc.  From there,
try to group by subtype (plate mails, leathers, chains, crowns,
etc.)  This just makes it easier to find stuff.  From their, it
might be nice to keep them in chance order, but most aren't in
that right now.


Maps, treasure_list & treasure_def

This paper describes the map file format, the treasure_list and the treasure_def file with
commands.

1. Item generation with treasure_list and treasure_def

The files treasure_list and treasure_def are used to generate or modify item at run time.
The are pre defined and loaded by the server at system start. They are triggered when new
objects (for example items) are generated.

There are 2 ways, a item comes in play: fixed or random.

Fixed items are set "by hand" from a map maker. Every object you put with the map editor
on a map is fixed. This means, that his stats will not be altered when the map is loaded.
The arches in the left arch panel of the editor has only the "base settings".  The map
maker need to set the special values by hand. For example is the default arch setting
for most armors item_race = none (human) and material_real = 0 (iron when the base material
is IRON) and they are not magical or have bonuses. All these must set the map maker by hand.

Random items will be generated with the help of treasure_list and treasure_def.

There are some different ways, random items will be generated but all use the same
mechanism. All these objects has a command, which is called "randomitems <name>".
The special objects "random_items" or "shop floors" has also these "randomitems" command
inside and when a map is loaded, the loader change these "dummy objects" to real objects.

"randomitems" is a arch command. The paramter <name> points to a pre defined list of
objects inside the treasure_list file. When triggered, the treasure_list function will
go through this list and generate these objects when the chance (by random) and/or the
difficulty level is right.

Every time, there is a object picked from this list, this is the "raw" arch which have only
the "base settings" from the arches. Like the map maker, the random object function need now
to setup some values for this arch, to make it fit in the map. This goes in 2 steps.

First, there can be inside the treasure_list lists some commands to set this new object.
These are called the "pre settings". They will be explained in the treasure_list command
list.

After this is done, the treasure_list calls treasure_def.

Treasure_def will get this objects and examine them by TYPE. Based on object type, map,
difficulty and change there will be a chance these object become special or magical.
These are called the "post settings". Treasure_def has complex lists for possible changes
for most types. They get sorted at server start.

These changes are somewhat complex, because depending on the base and pre settings, there
can be some changes possible and senseful, and others not. The treasure_def has to analyze
the object to decide how and what should be changed.

Example:

When a map maker put an orc on the map, this orc is FIXED. His own stats are not altered
except by the mak maker. But the orc has also the command "randomitems orc" inside his
arch. When now loaded, the orc are given the item listed in treasure_list in the list
"orc". There can be defined different actions, like give the orc a sword OR a axe, give
him always a chainmail, etc.

In the "orc" list are also a command, which changes the item_race of the base items for him
to "orcish". The same can (but not must) happens for the material_real.

Then these items goes to treasure_def, where they become perhaps magical - or cursed.

If both list are done, these random generated items are put in the inventory of the orc.
If the orc get slained by a player, they are dropped to the floor and the player can get
them.

