The newb scripting guide; How to go from Newb to Noob in Ot's. (Work in Progress!))

[Xikini]

This thread in it's entirety is a work in progress.
I have not completed the tutorial, nor have I fully spell-checked it at this point in time.
I will be updating it over the next couple of weeks based on suggestions/criticism.
I will be reserving the first 3 posts for the tutorials, and the 4th post, in case I require the extra space. (which is likely.)

The 4th post will likely be comprised of copy-paste scripts for people to use,
and for the questions/answers section.

I realise that each post can have 25k letters.
I want to try to keep the letter count of each post to 15-20k, in case I need to add additional sections explaining stuff I have missed.

When I feel I have completed this guide to my expectations, I will remove this section.

Cheers to all,

Xikini

--------------------------------------------------------

The newb scripting guide; How to go from Newb to Noob in Ot's.

Hello there, my online name is Xikini. X-uh-keen-EE.

If you can't pronounce my name do not read further! I don't wanna teach you anything! (just kidding.)

Before you start to read this thread you will need to have set-up your server.
Some great tutorials to do this can be found here, here, here and here.

A fully set-up server, in my eyes, requires 4 things.

[1] You and others can create characters.
[2] You and others can log into your server.
[3] You have edited one of your characters into a god character.
[4] You know how to pronounce my name.

If you have completed the above steps, then you are ready to undertake your next challenge, Actually creating your server!

My goal at the end of this thread..

[1] You should know what each of the standard files do. [actions/movements/talkactions/et cetera]
[2] You should know how to create basic scripts.
[3] Teach you things at a very relaxed pace, while explaining everything as if you were explaining to your grandmother how to turn on their pc.
[3] You should feel like you are at least semi-floating on water instead of sinking rapidly into the abyss.
[4] And Finally, you should feel confident that you have gone from newb to noob.


Be warned. I'm notorious for walls of text. Before I even start writing this I'm writing this.
This will likely be a very long wall of text with a few code snippets, and maybe some images/gifs.

I will also like to warn, I am not an educated scripter.
I have never gone to school for any of this knowledge.
I have done everything through trial and error.

My scripting style, comments, any scripts I provide as lessons, are all probably garbage.
However! They are working garbage. Very functional, very working, garbage.

Most of the mods and elite scripters probably shake their head everytime I post help or scripts on this forum.

Basically my knowledge of scripting amounts to knowing how tables/loops/arrays work.
If you went to school for a scripting language, you were probably taught the above three things within your first two weeks of class.

I'm fairly smart. I know how to look around for stuff I don't know, and I'm not afraid to fail.
Nobody should be afraid to fail. Everytime you fail to do something you are gaining valuable knowledge.
However if you fail and give up, the only thing you are learning is how to give up when something proves to be difficult.

If you want to create an OT, I'm telling you right now that you will cry into your pillow three nights from now and wish the headaches would stop coming.
I'm totally kidding. I'm definitely not talking from experience. I definitely wasn't 14 years old.
I was a mature adult with the knowledge of everything. I opened my text document and a server was born within 3 weeks.

Alright, enough kidding around.
Let's start learning the basics.

The difference between your client version and your TFS version.

Your client version is your Tibia Clients Version.
Your client version simply tells you what sprites you will be able to use.
Popular client versions are 7.6, 8.0, 8.6, 9.6, 10.77.. et cetera.

Your TFS version is the version of your server.
Your TFS version will tell other people what kind of scripting style, and what available functions your server is allowed to use.
Popular New TFS versions are 1.1, 1.2.
Popular Old TFS versions are 0.3.6, 0.3.7, 0.4.

Anytime you create a thread on the forum, people will ask what TFS you are using.
If they don't know what TFS you are using, they may post code that is incompatable with your server.

I myself use TFS 0.3.7. All of my examples will be using this TFS, because this is what I am familiar with.
Although Old and New TFS versions are slightly different in coding style, the underlying file structure is fairly the same.

You can tell the difference between Old and New TFS by looking for these :::::.
New TFS will use these things in their code.
From my understanding it will call specific data, then use that data in a function.

Alright, next Topic.

What is the difference between the folders located in data/... , and what do they do?

[insert picture here]

[actions] This type of script is used when a player is interacting with any object. Ctrl + Click

[creaturescripts] This type of script is used when a creature [player/monster/npc] does something.
(When a player advances in skill, when a player looks at something, when a player logs in or out,
When a player takes damage, when a player targets a monster, when a player dies or kills something.
You can then script something to happen.)

[globalevents] This type of script effects many players or all players.

[items] This is where you edit your items and their values. (attack/defence/armor/names of items)

[lib] This holds useful information for scripting. You will probably use 1 or 2 files in here. The rest are UFO's.

[logs] This holds a lot of bug reports. Only useful file for newbs.. might be talkactions - for each player.
If you think a GM is spawning items for players/himself, you can check what talkactions they have used previously.

[monster] This is where you find all of your monsters. You can edit health/attack/defence/loot/et cetera

[movements] This type of script happens when a player walks or equips armor or moves an item onto a square.

[npc] Non-Player Character. This is where your npc files are located.

[raids] This is where you can set-up raids. Nobody fully understands how these work.

[spells] This is where you find spells. Their mana cost / who can use them / how they work.

[talkactions] God commands or player commands. /online or !online

[weapons] These are weapon scripts. They are kind of like spells, but for specific weapons.

[world] Your map. Your map goes here.

 This contains different stuff. mounts/outfits/quests/stages/vocations are the most useful files in here.

And that's it for that.

Let's also quickly discuss some basic knowledge of how to post in Support/Requests.

Let's say you find an error, and after searching around for other people with the same issue, you can't find a solution. Alright, let's post in Support.
[URL]https://otland.net/forums/support.16/[/URL]

Here's a quick template.

Make a good Title. TFS 0.3.7: Lever to spawn monsters is not working
What TFS are you using? 0.3.7
What is the problem? My lever is not working when I click on it.
Post your script. [.code]script goes here[./code] (without the dots.)
Is there errors in your console? (console is the black window that shows up when you host your server)
Yeah I found this error. [.code]error goes here[./code] (without the dots.)
What have you tried to fix the problem? Post any script changes you tried.
Please help me senpai's.

If nobody helps you after 24 hours, type 'bump', and update with more script changes you have tried.

If you fixed your problem, it is acceptable to post before 24 hours with your solution, and then edit your title with the tag "Solved".
You always want to post your solution, so if someone else has the same problem, they can find your solution!

-- Rant Start
It is absolutely unacceptable to edit your first post to 'Blank' or 'Fixed my problem. Close thread//'.
You are apart of a community. Yes, we all have our own projects and ambitions, but if you don't support the community, the community will die.
Editing your main post to "sorry stupid question, solved." or anything similar is arrogant and greedy.
If you had this problem and found the solution, post your solution!
You will be helping someone who currently has the same problem, and could NOT find the solution!
-- end of rant.

If someone else helped you, or attempted to help you, LIKE their post, and post any errors you found with their solution.
If their reply solved your problem, LIKE their post, tell everyone your problem is solved, and edit your title to solved.

[Insert gif on how to edit title]

For requests is the same thing, except you ask people to make you stuff.
[URL]https://otland.net/forums/requests.132/[/URL]

Give them your TFS version.
Tell them what you want your script to do.
Hope and pray someone will make or help you make the script your wanting.

If nobody helps you after 24 hours, type 'bump'.

Remember, Forums are slow. Just be patient.
These people are taking time our of their lives to help you with your problem or request.
Be courteous, and don't lash out at people if their post does not help you.


Back into the basics.

Useful stuff to install.

Remere's Map Editor -- basically the most used map editor of all time.
[URL]https://remeresmapeditor.com/marklar.php[/URL]

Notepad++ -- This makes your eyes stop burning. Basically it will highlight special keywords.
[URL]https://notepad-plus-plus.org/download/v6.9.2.html[/URL]

Let's learn some basic server-wide stuff now.

First thing you want to do as a newb, Create a back-up file of anything you want to change.
If you screw-up something and your server won't load, just replace your edited file with your back-up file.
Back-up files save lives. I promise.

How to set-up experience, loot and skill rates, and free premium.

Very simple. in your config.lua search for

[premium] Until you find "freePremium" or something to that effect. Set to 'true'.

Then search for

[rates] Here you will find your rates.
Rates set as 1.0 = regular tibia rates. (or very close to.)
Anything above 1.0 is a multiplier. so 2.0 = 2x experience. (you can also do 0.5 to make half experience)
Skills/Magic/Loot/Experience is easily adjustable.

For experience you have the option of using "experienceStages".
If you change this to "true" you can further adjust how players gain experience.

Go to data/XML/stages.xml
I'm not sure what you'll see there, but here is a quick example of what you could do.
You get higher multipliers from starting levels, which eventually slow down and completely stop at level 500, as max level.
[code]<?xml version="1.0" encoding="UTF-8"?>
<stages>
   <world id="0" multiplier="1">
     <stage minlevel="1" maxlevel="99" multiplier="10"/>
     <stage minlevel="100" maxlevel="199" multiplier="8"/>
     <stage minlevel="200" maxlevel="299" multiplier="6"/>
     <stage minlevel="300" maxlevel="399" multiplier="3"/>
     <stage minlevel="400" maxlevel="499" multiplier="1"/>
     <stage minlevel="500" multiplier="0"/>
   </world>
</stages>

You can change these values at anytime. Just restart your server to test the new rates.

There is a ton of more stuff in config.lua you can change.
I'd suggest going through the entire document and fiddling around with stuff.
If you can't easily guess what something does.. I'd suggest not touching it.

Next basic thing would be editing items. data/items/items.xml

For many people this is their first large task.
You open up this document using notepad++ and the first thing you ask is; why is this file so long?!

Good question! It's long, because it holds the data of every single item in the game!
So if you mess something up in here, your server will definitely not load!
Make a back-up! Now!

Over exagerrating. It's not that complicated.

Here is some leather boots.

<item id="2643" name="leather boots">
   <attribute key="weight" value="900" />
   <attribute key="armor" value="1" />
   <attribute key="slotType" value="feet" />
</item>

All these different things to look at, where do you start?
Well most of this is called "XML formatting".
You've seen this before in stages.xml
Well, now let's explain is a bit.
Forget the numbers, words, and other stuff. Let's focus on the basic stuff behind it.

<item>
</item>

There we go. Less intimidating now.
Same as before when we used [.code][./code] "code tags" to submit our support ticket.
XML just does it a bit different.

When you open a tag you use <>
When you close a tag you use /
If you open a tag on one line, <> but never close it / you can add additional parameters to it.

You can make very simple items such as a dirt floor into one whole line.
Notice that we open and close this item on the same line.

<item id="103" name="dirt" />

Equipable items usually turn into multiple lines.
Let's start adding information for the leather boots.

<item id="2643" name="leather boots">
</item>

So now we have made the sprite id 2643 named to leather boots.
You'll notice we placed all the information regarding the item into the first part of the tag.
This is common for items.. since we will be adding more information to the item, such as weight and armor.
Notice again that the attribute keys open and close on the same line.

<item id="2643" name="leather boots">
   <attribute key="weight" value="900" />
   <attribute key="armor" value="1" />
   <attribute key="slotType" value="feet" />
</item>

Because the item opens on the first line, and closes on the fifth line, all the lines inbetween become this items attributes.

Somewhere in the source code, someone has done all the hard work for us programming what each attribute key does.
All we have to do it edit the attribute keys. If we wanted to we could add more attribute keys to leather boots.
If we find a "life ring", which already has life and mana regeneration, we can simply copy those lines, and put them into our leather boots!

<item id="2643" name="leather boots">
   <attribute key="weight" value="900" />
   <attribute key="armor" value="1" />
   <attribute key="healthGain" value="2" />
   <attribute key="healthTicks" value="6000" />
   <attribute key="manaGain" value="8" />
   <attribute key="manaTicks" value="6000" />
   <attribute key="slotType" value="feet" />
</item>

Of course there is many attribute keys you can add to items, and most of them explain themselves by their name itself.
Some attributes will have a simple value of "1".
If it's something like "showcharges" the value of "1" will mean true, and "0" will mean false.
Of course there's no point in having the line if it's false, so you should just remove that attribute.

But Xikini, when I looked for "life ring" I noticed there are two life rings! What gives?

There are special items in the game that "transform" and "decay" over time.
Rings are an easy example.

<item id="2168" article="a" name="life ring">
   <attribute key="weight" value="80" />
   <attribute key="slotType" value="ring" />
   <attribute key="transformEquipTo" value="2205" />
   <attribute key="stopduration" value="1" />
   <attribute key="showduration" value="1" />
</item>
<item id="2205" article="a" name="life ring (faster regeneration)">
   <attribute key="weight" value="80" />
   <attribute key="slotType" value="ring" />
   <attribute key="decayTo" value="0" />
   <attribute key="transformDeEquipTo" value="2168" />
   <attribute key="duration" value="1200" />
   <attribute key="healthGain" value="2" />
   <attribute key="healthTicks" value="6000" />
   <attribute key="manaGain" value="8" />
   <attribute key="manaTicks" value="6000" />
   <attribute key="showduration" value="1" />
   <attribute key="showattributes" value="1" />
</item>

These are two different items.

2168 is a plain green ring.
2205 is a sparkly green ring.

When you equip a ring in Tibia it turns from a plain ring to a sparkly ring while equipped.

When it's "duration" runs down to "0" it will "decayTo" the item "0".
Because item "0" does not exist (and is probably programmed to delete the item entirely) the ring simply disappears, never to be seen again.

This is probably jumping forward a bit too much, but go to data/movements/movements.xml
Search for 2168 and 2205.
Normally the life ring is all put together in one area, but they might be moved around a little.

<movevent type="Equip" itemid="2168" slot="ring" event="function" value="onEquipItem"/>
<movevent type="Equip" itemid="2205" slot="ring" event="function" value="onEquipItem"/>
<movevent type="DeEquip" itemid="2205" slot="ring" event="function" value="onDeEquipItem"/>

For every item in the game that can be equipped to a player, it will need to be "registered" into movements.xml
If the item is not registered to be equipped or deEquipped, then you cannot equip or deEquip that item.

The reason I brought this up, is because plain life rings have the special attribute

<attribute key="transformEquipTo" value="2205" />

and sparkly life rings have this special attribute

<attribute key="transformDeEquipTo" value="2168" />

When you equip a plain life ring, it will transform into a sparkly life ring.
Because that sparkly life ring transformed in your equipped slot, it is then equipped a second time, but this time registering as the sparkly ring.
When you deEquip the sparkly ring it transforms into the plain life ring again.
Because you are never actually deEquipping a plain life ring, you never need to register it into movements.xml

In either case, jumping back to items.xml, you can simply change some items, then close and restart your server to see the new stuff you added.

Since items.xml is such a large document, I would suggest changing 1-2 items at a time, then testing to make sure you didn't screw anything up.

Once you are done changing your item values and such, come back and we will continue with some basic LUA scripting.

 

[Xikini]

Alright, let's start looking at scripting some stuff.

We will look at actions.xml first, explaining everything in detail, then quickly work our way through the rest of the categories.

Please note, since I'm a noob, I don't understand how spells/raids/weapons scripts work very well.
I'm not sure why, but I can't grasp how they are scripted.
I'm probably just stupid, but I can explain the rest pretty well.

Alright then! let's open data/actions/actions.xml

Pretty much every category has an XML document where all of the scripts are registered.

Let's look at some lines in here.

<action uniqueid="45020" event="script" value="bottle.lua"/>
<action actionid="45804" event="script" value="easy_chests_test.lua"/>
<action itemid="2401" event="script" value="Xikini_Example_Scripts/staff.lua"/>
<action itemid="10511;10513;10515" event="script" value="tools/squeeze.lua"/>
<action itemid="2086-2092;10032;10091" event="script" value="other/keys.lua"/>

Alright so basically these are all going to have the same layout.

<action itemid="1111" event="script" value="script_name.lua"/>
<action actionid="1111" event="script" value="script_name.lua"/>
<action uniqueid="1111" event="script" value="script_name.lua"/>

You'll notice the only thing changing is actionid, uniqueid and itemid.

UniqueID = a unique number, only allowed to be used once in the map.
ActionID = a number which can be used multiple times in a map.
itemID = an item which when used, will activate the script attached to it.

You'll also notice that they somtimes use ";" or "-" inbetween some numbers.

";" and "-" are used so we don't have to put multiple lines attaching a single script to multiple items, or actionID's.

"-" is used when we have many numbers that are directly beside one another.

So instead of doing this..

<action actionid="1111" event="script" value="script_name.lua"/>
<action actionid="1112" event="script" value="script_name.lua"/>
<action actionid="1113" event="script" value="script_name.lua"/>
<action actionid="1114" event="script" value="script_name.lua"/>
<action actionid="1115" event="script" value="script_name.lua"/>

We do this.

<action actionid="1111-1115" event="script" value="script_name.lua"/>

";" is used when we have many numbers that attach to a script, however are not directly beside one another.

So instead of doing this

<action actionid="1118" event="script" value="script_name.lua"/>
<action actionid="1123" event="script" value="script_name.lua"/>
<action actionid="1125" event="script" value="script_name.lua"/>
<action actionid="1167" event="script" value="script_name.lua"/>
<action actionid="1169" event="script" value="script_name.lua"/>

we do this

<action actionid="1118;1123;1125;1167;1169" event="script" value="script_name.lua"/>

We can also put both of these into practice together.

<action actionid="1111-1115;1118;1123;1125;1167;1169" event="script" value="script_name.lua"/>

And of course just like items.xml we make sure to open <> and close / each line correctly.

If you want to add "green text" to an XML document.. you do it like this

<!-- type stuff here -->

<!-- opens the green text
--> closes the green text

It is usually used for titles to section off area's for easier reading.

Or you can put green-text around a large chunk of text to make it not load.

   <!-- Bread Creating
<action itemid="2692" event="script" value="other/createbread.lua"/>

<action itemid="2694" event="script" value="other/createbread.lua"/>
-->

Basically, anything in green text is ignored by the script.

A bit more information for actions.xml

When you attach an item or actionID or uniqueID to a specific script, the server will now know which script to load for that item/object.

So let's pretend we are making a very simple chest, which will give our character leather boots.

go to data/actions/scripts/

Now open any of the LUA files in here with notepad++

go to file -> save as

At the bottom you will see two things.
The name of the file, and "save as type:"

Whenever you save your file, you need to save it as "Lua source File (*.lua)"
If you save it as a text document "Normal text file (*.txt)"

The server won't know what to look for, or what to do with it.

Alright, so make the file name "give_leather_boots"

click "save".

At this point we will have created a new lua file with some other person's script inside.
Delete everything inside the script and replace it with this standard action script.

Remember this is for TFS 0.3.7.
If you are using the newer TFS your function will look slightly different, but I'm only here to teach you the absolute basics, not the different functions for each TFS version.

function onUse(cid, item, fromPosition, itemEx, toPosition)

   return true
end

Alright. before we look at what this all means, we are going to register our newly created script file in actions.xml

go to data/actions/actions.xml

For our script we are going to be using "ActionID".
so somewhere near the top (so it's easier to find) put this line in.

<action actionid="45001" event="script" value="give_leather_boots.lua"/>

The number you use for actionid needs to be a number that has never been used before.
In my experience, numbers ranging from 45001 to 46999 are all not used.
I would suggest creating a text document, separate from your server files, that shows which numbers you have used before.
This way you never run into the problem of re-using numbers, and getting errors in your console.

Alright, back to our script.

So we have a whole bunch of stuff going on.

function onUse(cid, item, fromPosition, itemEx, toPosition)

function = This means that we are creating a function. Functions can be called upon further in the script, or in this case as the main function.
onUse = the name of the function. In this case it is the primary function that actions.xml will be looking for.
Everything inside of () is the parameters we can use with the function onUse.
Our source code is programmed to find and grab this information for us.
cid = creature ID. This is a number assigned to a character, a monster or an npc when they are created into the game. Every creature has a unique ID.
item = the item_id your character is using. In this case it is going to be the "chest" we use to get our leather boots.
fromPosition = This is the location where the script is being triggered from. In our example, it will be our characters position.
itemEx = the item that is being targetted. (If we use a rope on a rope hole, it will be the rope hole's ID)
toPosition this is the location of the item that is being triggered. In our example it will be the position of the chest.

Further down we have
return true = this basically means, end the script here and tell the function onUse that everything worked perfectly.
end = End the function onUse. Pretty much end is like a period ".". It tells the script to close the sentence.

Alright, so now we have our function, but how do we make it do something?
Well some other smart people have created functions for us to use.

If your server came with "a source" or the source code.. you can usually find almost every "lua function" in lua.cpp

Or you can use a list of functions included in our TFS versions, that other forum members have already created into a list for us.
Now these lists may not be up to date, and they not include every function that our TFS can use, but they will include most of the basic useful ones.
I use this list often.
https://otland.net/threads/scripting-guide.74030/#post-758231

I want to give a player an item. SO let's find the function that says it will do that for us.

doPlayerAddItem(uid, itemid[, count/subtype[, canDropOnMap = true]])

And of course it comes with a whole bunch of new stuff for us to look at.

Everything in [] is optional options we can use.
I'm going to use everything this function offers, so let's make our function prettier.

doPlayerAddItem(uid, itemid, count/subtype, canDropOnMap = true)

There, now it's a bit less scary.

So the function name is "doPlayerAddItem". This sounds like what we want to do. Alright, how do we use it?
Let's look at the parameters this function wants to use.
uid = UniqueID of the creature you want to use the function with. Since we already know we want the player to receive the item, we will change this to "cid"
itemid = the items we want to give to the player. We will change this to the item_id of leather boots. 2643 (you can look this number up in items.xml)
count/subtype = how many items we want to give to the player. We will set this to 1. (subtype is sometimes used instead of count.. when you want to put liquid into an item. It's rarely used.)
canDropOnMap = true || = If the player has no cap or space for the item, drop the item onto the ground underneath the player. we will set this as true.

So now our function looks like this, after replacing each part of it.

doPlayerAddItem(cid, 2643, 1, true)

Whenever we add these functions into our script, you want to put them into the "body" of the main function. (basically think of it as a human. Put the function in your stomach so we can digest the information.)
So let's do that.

function onUse(cid, item, fromPosition, itemEx, toPosition)
   doPlayerAddItem(cid, 2643, 1, true)
   return true
end

Alright! we have a complete script.
Now we want to make this script available to use in our world.


go to data/world/
open up your map using remere's map editor.

Travel around until you find a good spot to put your chest.
use "j" search for "chest" and then place your chest on the ground.
Now "right click" your chest and open "properties".
Change ActionID from "0" to "45001" (the same as we put in actions.xml)

Save your map, and restart your server.

Now when you take your character over to the chest, and use the chest, you will receive leather boots.

So altogether this is what's happening when your using the chest..

Character clicks on the chest. Since this is a "Action" actions.xml checks if that action corresponds with anything inside of it.
Since the chest has ActionID 45001, and actions.xml has a script attached to ActionID 45001, it will now load the script attached to that line.
Our script then finds the function onUse, and grabs information from the server related to it's parameters, (cid, item, fromPosition, itemEx, toPosition).
Our function inside of onUse, uses the parameters that the server has grabbed for onUse, and uses those parameters + the parameters we have set inside of the function "doPlayerAddItem" to add an item to the creature (the player) who used the chest.
the script then finds "return true" which basically means, everything went fine! and ends the script.

And that's basically what every script in the game does when it interacts with your files.

 

[Xikini]

Reserving.

 

[Xikini]

Reserving as well.

 

[tetra20]

The Amount of effort exerted in this topic is huge, Well Done Mate! Just few suggestion

1-Make it More Interesting,Bold Characters/Images so the person who is reading wont find it hard to reach or find what he needs
2-Less Characters Maybe? you would usually Get bored after reading that huge wall of text

Only Those,Great job tho xD

 

[Damon]

Good job mate! Just as @tetra20 said: Make it a bit more interesting by e.g. highlighing stuff Too much wall of text xD

 

[Shyzoul]

Good job, imo sublime text > notepad++, it is multi platform also, good to point it out since lately i've noticed a bit more of unix based system users.

 

[tokenzz]

Both are text editors. >= would be more fitting


or you can use my text editor written in python it is very nice

 

[Shyzoul]

or you can use my text editor written in python it is very nice

it would never beat vim