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


Treasure Lists
-----------------

Ok, what ARE treasure lists?

In short terms: when you kill a mob, it will left a corpse on the ground.
Inside the corpse there are items which can be taken - the so called "loot".

The treasure lists are nothing more as a list of items which describes
what a monster can drop - its a list of loot.

Thats *one* use of the treasure lists. In fact its more complex.

The items a monster will drop are in the inventory of the monster when its generated.
Thats different to some other games where the loot is
generated in the second a monster dies. We generate it when a monster
appears.

The reason is that the treasure lists are not only for loot - they are for
define what a monster is carrying in their inventory.

Why is that important?

In daimonin nearly everything is an object. Even daimonin is written in
C we have a heavy object oriented system inside.

A "spell force object" for example is something which gives a monster the
power to cast a spell. When a demilich is casting a icestorm, then it
has a icestorm spell object inside its inventory. That "spell force object"
is the same object as a weapon or a tree. It just has a different type
definition.

Because that, i will now only talk about "objects" when i talk about
items or something else a TL (treasure list) will add to something.

"Add to something" always means "into the inventory of another object".
That don't must be a monster. Remember: Everything in daimonin is
an object - in fact the same "base object". For a TL there is no difference
between a monster or something else - a wall, a weapon or a door...
In fact we insert for example in the exactly same way a trap in a door
or in the chest like we add loot to a mob or skills or spells to something
else.

The TL have a row of tools and commands to create good "drop lists"
(a different name for treasure list - because treasure list can be
confused with treasure list*s* - which means all TLs).

It can create random drop lists (means you define a list of items and
the TL "throw a dice" and get one by random), it will count in the level
of the object which should receive the items or the map "difficulty".
Thats why the difficulty setting of a map is important.

Best example are rods or horns. As all know higher mobs are dropping
higher rods, with a higher spell/rod level. Thats done by the TL, using the
monster level as base level for the rods. Would a chest set on the map
and TL list for a random rod added to the chest, then the TL has the
problem that a chest have no nature level. In that case the TL would
fallback to the difficulty setting of the map.

All the treasure lists are inside the file "treasures" inside the /arch
folder (or the /lib folder of an installed server).

Treasure List Examples
-----------------------

The "treasures" list file is nothing more as a collection of single treasure lists.

All the entries you see are single treasure lists.
There are 2 kinds of treasure lists.

"treasureone" is a list which returns only ONE object out of many. Means the
list will stop when it has a valid return object. It looks like this:

treasureone LISTNAME
..
.
end

The other treasure list can return several objects (or nothing), depending
on the settings inside. It looks like this:

treasure LISTNAME
..
.
end

There is a good graphical tool to browse treasure lists inside the editor
under Resources/View Treasurelists. Open the editor and look at them.
The names you see is the name of the single treasure lists.

Lets examine one of the list: double click on the list named "book_misc"

You will see something like this:

1 book_misc (one)
   tome+0 (41%)
   book+0 (59%)

Inside the treasure list file the TL book_misc is described as this:

treasureone book_misc
arch tome
chance 45
magic 0
more
arch book
chance 65
magic 0
end

As described above this TL will drop one item - a book or a tome.
The format is always

treasure(one) LISTNAME
arch/list NAME1
more
arch/list NAME2
more
arch/list NAME3
..
.
end

I choosed the book_misc because you see there an important feature: In the
TL list itself, "chance" describe the random chance from 0-100%, that this item
will drop. As you can see - 65% and 45% are more as 100%. Thats not a bug, the
drop chance inside the TL is described relativ and then its recalculated to "real"
100% from the server when loaded. As you can see in the editor, the TL chance is
 adjusted to 41% and 59%,  which is the right way for 100%.
That makes TL coding alot more easy.

The command "arch NAME" always means the arch object name. Which is described as
"Object NAME" inside the arch files.

The "magic 0" ensures the server don't tries to produce "magic" books, which is
senseless for normal books. For B3 people perhaps remember torches+1, which was
senseless too and was generated because the TL missed the "magic 0".

Instead of using a single arch, you can use other TL.

Like

treasureone books_2
arch book
difficulty 5
chance 30
more
arch tome
difficulty 30
chance 70
end

treasureone books_misc
arch tome
chance 45
more
arch books_2
chance 65
end

Here you call the books_2 TL trough books_misc. Even when it looks here
a bit senseless because it will drop the same arches, you can see that we
play around here with the drop chance. Which opens many uses by connecting
different TLs by using different drop chances. In fact, thats also one use of TLs.

If you look at the "book_2" list, you will see the "difficulty 5" and "difficulty 30"
commands. Thats the same as "level" and the map "difficulty".

How it works? If book_2 is called for a level 10 mob, then book_2 will check the
difficulty against the mob level. Because the mob is to low, book_2 will always
fail to generate a tome - it will always return book. Difficulty will overrule
the chance and every other command.

If you browse the different TLs in the editor TL viewer, you can see how the TLs
are connected and called.

In the head of the "treasures" list you will see an overview about the commands
which are allowed:
http://daimonin.svn.sourceforge.net/viewvc/daimonin/trunk/arch/treasures?view=markup

Also, here is a more detailed description about how to write TLs:
http://daimonin.svn.sourceforge.net/viewvc/daimonin/trunk/doc/treasurelists.txt?view=markup


The .tl files
--------------

The "treasures" files is the static default treasure list collection.
Map makers and designers can use them.

Sometimes, you want a new or special treasure list for your own maps.
For that, we have the .tl files.

When a server starts, it will load the "treasures" file from it /lib folder.
Then the server will browse the whole /maps folder and collect every *.tl file
inside!

The TLs inside the .tl files are attached to the ones from treasures files.
The format of the .tl files is exactly the same as for the treasures files,
there is no difference. Ensure the TLs in your own .tl file have different
names - or the server will drop an error message. If the server don't starts
after you added/changed a .tl file, check the server log, there you will
find the error messages.

Here is an example for an local .tl file - it will define the TLs for the
random drop dev test map. As you can see the .tl file calls a TL from the
original treasures file without a problem:
http://daimonin.svn.sourceforge.net/viewvc/daimonin/trunk/maps/dev/testmaps/dev_maps.tl?view=markup

TLs are attached to object by using the "randomitems" command, which is explained in the next
Tutorial.

EDIT:

Just a warning - the TL list are heavily recursive called. Which makes it
sometimes really hard to follow the drop flow and to define the results.
The server has some code inside to avoid recursive locks and other
bad results. But its hard to see from the naked lists how the results
will be when its called all over recursive.

I suggest you try a new list always out by changing the .tl file in the
/dev maps and watching the results in the random drops test map.

Hm, but there is a difference between spell forces and treasure, in that while a mob's treasure should be random (within the bounds of it's tl) the spell should surely (almost always ) be constant.

IOW your skel mage may sometimes have 1c or a ring or nothing but he will always be able to cast is.

Therefore which is better: add the spell to his tl or add the force obj to his inv in the editor? Same end effect I guess, but the latter seems to me the more sensible approach because of the distinction mentioned. Or?

No, thats not defined by the TLs - its defined how we call them through the "randomitems" command.

the TL list describes the chance of the OBJECTS inside the list to appear.
You can make it random or fixed, thats on you.

Technically, there is no difference. Object is object. Just we don't add
the spell force object to every ant running around. If we would do it
and enable the ants to try spellcasting, they would do it.

We had in early versions an ant which spites poison. It worked in the
same way, just the used object was an ability - which is interesting for
the server because it defines how the server use it - but for the TL its
absolut the same as dealing with rock arches or something else.

In fact when we have more and different ice spells, we can change the drop list
for the ice spells so it generates random sets of spells, which will return different
behaves of the skel mages.

You noticed we are adding AI objects with the TLs too?

Don't get confused by the term "by chance".
It don't means it MUST be random - a chance of 100% and
a not set "chance" command means "always". Which will
return the object in any case.

Using the "randomitems" command  right will allow to define a chance
a TL is called or not. So, you can define a TL which will always return
a object (for example a spell), but you define that the list is only called
every 2 of 5 times by chance. Of course you can define also inside
the TL itself it should only drop by chance like 2/5.

Confused?

Its easy - when we do it in the TL (defining all the random, chances and
stuff) - then the whole thing is STATIC. And we need for different mobs
which should have different drop rates to define always a new TL.

Through the feature to define the drop chance inside the TL AND by
the randomdrops command itself, we can make it dynamic.

Why not make level a default attribute so all objects have a level. Then TL could be determined by the, eg, chests level and map level could be used as suggested here: http://www.daimonin.net/index.php?name=PNphpBB2&file=viewtopic&p=34924

Ie, the map difficulty is used to modify the mob (and other object) levels so instances can be easily tailored for different level players.