Hello

I start now to write some Tutorials.
I will post them to the forum as sticky thread, but there is no
reason we don't include them elsewhere too.

This Tutorials are written for map makers, collecting the technical
docs and dev notes, but they are interesting for everyone dealing
with daimonin and development.

Note to other devs and map makers: You are free to edit this
thread or to add information or remove them when they changed.

Lets start...

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.

So, what IS an artifact?

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.

Here is the format of an artifact description inside the artifacts file:

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

Real example from the artifacts file:

Allowed all
chance 70
difficulty 1
artifact pearl_poor
def_arch pearl_generic
editor 3:items/jewel/pearls
Object
title of poor quality
material_real 0
type 135
value 15
end

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.

They will simply overwrite the old values of the default arch and store it in a "fake arch".

What is a "fake arch", also called "artifact arch"?

The server will load first all arch files and create a collection from it.
After that, it will load the artifacts file and create the artifacts, using
the loaded arch files as base arches - means he will create a copy of the base
arch, rename it and parse the changed values in the artifacts entry over the
original ones.

Then the server will ADD the created new artifacts to the arch list, in the same
way as when the arches are loaded as normal .arc file (ignore the fact that the
editor will generate a "pre collected arch file" for faster loading).

The trick is this: Every entry in the default arch object list has a field called
"base arch". For a REAL arch, that field is empty. The server knows internal that
this arch is a real one.

A artifact arch points in that base arch field to the arch which is used as copy.

Why is that senseful?

For that you have to understand that an artifacts entry has 2 uses:
as MASK and as OBJECT.

Technically, it can be both - but not both is senseful.

As mask, we use the artifacts entry to create out of a class of objects special and
magic ones.

Lets see an example:

Allowed all
chance 20
difficulty 1
artifact weapon_fools
def_arch sword
editor 2:items/weapon
Object
title of fools
ac -1
dam 3
wc -1
type 15
is_magical 1
cursed_perm 1
cursed 1
value 500
end

This entry will work like this:

Inside the object/end you see the "type 15". Every artifacts is identified by its type, the server
parse the entries when loaded and note, that this entry is ONLY used for type 15 = WEAPONS.
Don't get confused by "Allowed all". It don't means allowed by all type, it means allowed by
all arches from type 15!

This entry will change EVERY type 15 object, when called with that entry to a WEAPON of fools with the
settings you see between Object/end.

So, HOW this mask entry is used? In 2 ways:

1.) Implicit called from the treasure lists. Inside the treasure lists there is chance an object
can become magic or cursed or damned. We have also the command "artifact_chance" to explicit set
the chance for an artifaction. "artifact_chance 100" will always force the RANDOM call of an
artifact mask. Random means that the server throws a dice for "chance xx" for EVERY type 15
artifacts mask. It also checks difficulty against object/map level and Allowed for the arch
name.

2.) Explicit by the object command "amask <artifact name>". When an object is loaded, the
map/object loader will parse the artifact map over the object. chance, difficulty and all
between Allowed and Object is IGNORED. The mask is used even map level is to low or something.

Thats the MASK use - how is an entry used as OBJECT? In 2 ways too, but the artifacts
entry looks a bit different:

Allowed none
chance 1
artifact cloak_rhun
def_arch cloak
editor 1:uniques
Object
title of king Rhun
resist_acid 8
resist_poison 8
str 2
dex 1
ac 3
is_named 1
material_real 0
item_level_art 45
item_quality 85
item_condition 85
face cloak_green.101
is_magical 1
value 221
end

First, you will notice the "Allowed none" and the fact that inside the Object/end code is no "type"
defined. Because only entries with valid Allowed and type setting are used as masks, this entry
will NEVER be called as mask, even its defined by the def arch as "cloak". This entry will never
automatically be used by the TL list. But you *CAN* use it with the amask command - even it makes
in most cases no sense and should be avoided.

So, how its called? Remember that artifacts are added to the arch list by the "artifacts <name>".
In this case the name is "cloak_rhun" and its used like every other arch object!

That means we can put it on the map like a normal object (the editor will list all avaible artifacts
like normal arches) or use then with "arch cloak_rhun" inside a TL like every other normal arch.

So, its that the only use of the def_arch? To mark artifacts entries in the arch list and give
some base values? The answer is no - there are 2 other pretty important uses:

First, we can now define the base object. Which is important. For example lets look to nethack.
There we have alot artifact swords - for example Excalibur and Stormbringer.

These are not only different swords - they are different KIND of swords. Excalibur was always
described as long sword as Stormbringer was described as broadsword.

That pretty important for 2 things: Perhaps our objects behave different, basing on the different
sub types or arches. Like we add later skills which gives extra power when you fight with the
special weapon of your guild. Like the knights gets extra power when using a long sword.
Or that broadswords works better against slimes.

The second use is that we can "disenchant" now artifacts back to their base object. Like the cloak
of Rhun gets disenchant to a normal cloak when you join the giant god as follower. We have
a fallback then.

Well, thats the base use of artifacts. Lets go the details:

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.

Allowed All will skip any check because we use simply all.

'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.

as described the "artifact" entry is the artifacts name - as mask, fake object or both.
Remember - its added to the arches. So, it must be unique as every other arch name.
If the name is used somewhere in the arches for a normal arch, the server will stop
loading with an error message.

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.

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.

There are some other commands used by the artifacts entry.
This is from the head of the artifacts file:

# The t_style setting
# --------------------
#
# A t_style is a kind of sub class identifier for the artifacts.
# It is used to part the single artifact masks (is has no real use for
# unique artifacts) of a Allowed xxx group in sub groups.
#
# There is a t_style variable also in the treasure file for each treasure or
# treasure list which calls this artifacts file after generation a base item.
# Both t_style are compared:
#
# t_style is "unset" = don't compare
# t_style == 0  : generate only artifacts with t_style unset or 0
# t_style <= -1 : Only style ABS(t_style) or unset or 0
# t_style >= 1  : Only items matching that style
#
# Use:
# A fire giant should be drop fire releated items and artifacts. For example
# only red gems, fire releated potions and magic items or fire based weapons
# or armour. So, all fire releated artifacts are signed as t_style = 1
# (thats the artifacts file default setting for fire releated items).
# Now the treasures of the fire giant are signed to "t_style 1" too.
# If he drops a artifact then it will be a fire releated.
#
# t_style defaults (use this default settings for your treasures and artifacts)
#
# t_style = 1   -> fire
# t_style = 2   -> cold
# t_style = 3   -> electricity
# t_style = 4   -> poison
# t_style = 5   -> acid
#
# end t_style
#
# The 'editor <num>: <path>' entry defines the use of the artifact entry
#
# editor 0: = this item is internal - ignore complete in the editor
# editor 1: = this item is a "fake arch" - don't use it for artifact masking
# editor 2: = this is a mask entry
# editor 3: = this is used as fake arch and also as mask entry
# fake arch = the server will add the entry to the arch list as it would be a file in /arch
# the path behind the ':' is used as a directory inside /arch - the editor will use it to sort them
#
#

Note for the artifacts file:

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.

The .art Files
---------------

As for the TLs, the server will load when startup the artifacts file and then
browse the /maps folder for *.art files. Every .art file found will be loaded
and attached to the original artifacts file.

Like the .tl file is the format of the .art file exactly the same as for the
original artifacts file. The .art files are used to allow "local" artifacts
depending on the map sets without that everyone has patch the artifacts file
which will lead in conflicts, following Murphy's law.

I was unaware of this (I have just seen it in trunk r4190). Can we please come up with something better than hardwiring an arch path into every .art definition? This means that whenever we change the dir structure of arch (be it to simplify the number of subsubdirs or to correct typos or whatever), we also need to hunt through every existing .art file and make the change there too.

This is a particular problem for devs who do not have access to the closed source content (which is where many .art files do/will hide) as it means they cannot make the full necessary change.

as of B5, editor 1:path and editor 3:path are removable for us, editor 2 does not require a path.  ALL artifacts B5 and beyond are editor 2  so they won't be shown in the editor, to "special drop" them from a mob, use amask <artifact object>, though "special drops" should be removed (ie only quest items dropped by script should be similar).  Special drops should be handled by treasurelist and where possible the tl placed in several mobs....(rhun's room all 3 specials could then be possible from any of the giants instead of specific ones).

Well that sounds to address my concern somewhat, but I don't understand what 'removable for us' means.

And also if this is so ('editor 2 does not require a path') then what does this mean:
Ie, editor2 still has a path.

Shouldn't they be shown in the Artifacts tab? Otherwise how do we know what artifacts are avialable?
 Why not have:
Where <string> is used by the editor as a drop down menu entry. So all artifacts appear in the Artifacts tab, categorised according to their <string>? IOW Artifacts is a fake subdir of arch and <string> are fake subsubdirs of Artifacts. In this way we get an informative and useable listing in the editor but arch/ and .art maintenance are separate, as they need to be.

Removable for us means that others that use our code/publicly available artifacts might want them available as fake arches to put in their maps.

It still has a path, but doesn't require it.

As for editor <string> I don't have a problem with that, get with Ragnor on that.  The editor line only affects the editor anyhow.

We also need to make sure /create and /generate only look at archetypes and not artifacts (as archetypes).  I fear that is in loader.l when it loads artifacts and adds them to archtable.