TFS 1.x Series Interface Explanations

Discussion in 'Programming & Scripting' started by Codex NG, May 9, 2016.

  1. Codex NG

    Codex NG Recurrent Flamer

    Joined:
    Jul 24, 2015
    Messages:
    3,000
    Likes Received:
    1,607
    Best Answers:
    12
    I will be using 1.0, 1.1 & 1.2 for this tutorial/explanation.

    Since there is no proper documentation for this anywhere, this will be it.

    First let me say this so its out of the way, an interface is not a function in the sense that
    we know of like add(2, 2) = 4, no it is a mechanism which allows us to interact with the server.

    The parameters of the interface are actually arguments which are sent from the server based on our
    actions in the game, whether it is logging in, stepping on a tile, equipping or using an item etc..
    this information is sent to the interface's parameters, which we then use in our scripts.

    List of interfaces

    Actions
    Code (Text):
    1.  
    2. onUse
    3.  
    Chat Channel Events
    Code (Text):
    1.  
    2. canJoin
    3. onJoin
    4. onLeave
    5. onSpeak
    6.  
    Creature Events
    Code (Text):
    1.  
    2. onAdvance
    3. onDeath
    4. onExtendedOpcode
    5. onHealthChange
    6. onKill
    7. onLogin
    8. onLogout
    9. onManaChange
    10. onModalWindow
    11. onPrepareDeath
    12. onTextEdit
    13. onThink
    14.  
    Global Events
    Code (Text):
    1.  
    2. onRecord
    3. onShutdown
    4. onStartup
    5. onTime
    6.  
    Monster Events
    Code (Text):
    1.  
    2. onCreatureAppear
    3. onCreatureDisappear
    4. onCreatureMove
    5. onCreatureSay
    6. onThink
    7.  
    Movements
    Code (Text):
    1.  
    2. onAddItem
    3. onDeEquip
    4. onEquip
    5. onRemoveItem
    6. onStepIn
    7. onStepOut
    8.  
    NPCs
    Code (Text):
    1.  
    2. onCreatureAppear
    3. onCreatureDisappear
    4. onCreatureMove
    5. onCreatureSay
    6. onPlayerCloseChannel
    7. onPlayerEndTrade
    8. onThink
    9.  
    Raids
    Code (Text):
    1.  
    2. onRaid
    3.  
    Talkactions
    Code (Text):
    1.  
    2. onSay
    3.  
    Spells
    Code (Text):
    1.  
    2. onCastSpell
    3.  
    Weapons
    Code (Text):
    1.  
    2. onUseWeapon
    3.  
    --------------------------------------------
    cid, player, creature, npc, monster

    1.0
    The parameter cid is the id of the player, creature, npc or monster
    1.1 - 1.2
    The parameter player, creature, npc, monster is userdata, it is a pointer to a metatable of the
    respected argument, however the argument can be creature and be refering to a player or monster etc..
    this is why we use
    Code (Text):
    1.  
    2. if isPlayer(cid) then
    3.     -- do something
    4. end
    5.  
    6. or
    7.  
    8. if creature:isPlayer() then
    9.     -- do something
    10. end
    11.  
    To determine if the value passed is the intended target.

    Please note, this information might not be 100% correct, but it is better than nothing.

    This code is lifted from the sources.

    --------------------------------------------
    Actions
    onUse
    1.0
    Code (Text):
    1.  
    2. onUse(cid, item, fromPosition, itemEx, toPosition, isHotkey)
    3.  
    1.1 / 1.2
    Code (Text):
    1.  
    2. onUse(player, item, fromPosition, target, toPosition, isHotkey)
    3.  
    item is userdata it contains the itemid and unique id of the item, however it also
    contains other things like the name, description etc and is accessable via its metamethods.

    fromPosition is a metatable which contains x, y, z & stackpos of the item, fromPosition
    returns the position of where the item you are using came from.. e.g. your backpack, the ground etc..

    itemEx or target is userdata it contains the itemid and unique id of the item you use the item on,
    however it also contains other things like the name, description etc and is accessable via its metamethods.

    toPosition is a metatable which contains x, y, z & stackpos of the itemEx or target, toPosition returns
    the position of itemEx or target.. e.g. your backpack, the ground etc..

    isHotkey is a boolean value, the return value of this is true if a hotkey was pressed and false if it wasn't.

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

    Movements
    onStepIn & onStepOut
    1.0
    Code (Text):
    1.  
    2. onStepIn(cid, item, pos, fromPosition)
    3. onStepOut(cid, item, pos, fromPosition)
    4.  
    1.1 / 1.2
    Code (Text):
    1.  
    2. onStepIn(creature, item, pos, fromPosition)
    3. onStepOut(creature, item, pos, fromPosition)
    4.  
    We've already discussed cid and creature,

    item see actions for indepth explanation, however it is not an item you use, it is an item you walk on or off, this doesn't
    have to be a stationary item such a ground tile this can be a moveable item aswell.

    pos is the position of the item you are walking on or off.

    fromPosition is the position of where you came from.

    onEquip & onDeEquip

    1.0
    Code (Text):
    1.  
    2. onEquip(cid, item, slot)
    3. onDeEquip(cid, item, slot)
    4.  
    1.1 / 1.2
    Code (Text):
    1.  
    2. onEquip(player, item, slot)
    3. onDeEquip(player, item, slot)
    4.  

    Both onEquip and onDeEquip are only used by the player, see the cid and player
    explanation above, item see the indepth explanation above, however it is not an
    item you step on or off, or even an item you use, it is as the name of the interfaces imply it is
    an item in which you equip to or remove from the player.

    slot is a number, the slot id of where item is equipped to or de-equipped from.

    onAddItem & onRemoveItem

    1.0 - 1.2
    Code (Text):
    1.  
    2. onAddItem(moveitem, tileitem, pos)
    3. onRemoveItem(moveitem, tileitem, pos)
    4.  
    Both moveitem & tileitem are userdata, moveitem is the item you move on to tileitem, pos is a table with the position of tileitem.

    For instance if tileitem is a dustbin (itemid 1777), and you took your backpack off and tossed it in the dustbin, moveitem would be your backpack.

    This rule applies to both onAddItem & onRemoveItem and can be used in conjunction with onStepIn or onStepOut or both.

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

    Talkactions

    onSay

    1.0
    Code (Text):
    1.  
    2. onSay(cid, words, param, type)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onSay(player, words, param, type)
    3.  
    See cid and player above for an in-depth explanation.

    words is a string, it contains the command used when executing the talkaction.

    param is also a string it contains the argument you pass to the command.

    type is a number it is the speak class used when executing the talkaction.

    If you run a print(type(type)) over it will return 1, which is TALKTYPE_SAY

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

    Raids

    onRaid

    1.0 - 1.2
    Code (Text):
    1.  
    2. onRaid()
    3.  
    onRaid has no parameters, its parameters are read from the xml which is beyond the scope of this tutorial.
    --------------------------------------------
     
    Last edited: May 10, 2016
    2Rec, Sajgon, Banned_User and 3 others like this.
  2. Codex NG

    Codex NG Recurrent Flamer

    Joined:
    Jul 24, 2015
    Messages:
    3,000
    Likes Received:
    1,607
    Best Answers:
    12
    Creature Events

    onKill

    1.0
    Code (Text):
    1.  
    2. onKill(cid, target)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onKill(creature, target)
    3.  
    cid, creature and target are userdata, both cid and creature are the monster, npc or player which did the killing, target is the npc, player or monster which got killed.

    onLogin & onLogout

    1.0
    Code (Text):
    1.  
    2. onLogin(cid)
    3. onLogout(cid)
    4.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onLogin(player)
    3. onLogout(player)
    4.  
    See both player and cid above for an in-depth explanation.

    onAdvance

    1.0
    Code (Text):
    1.  
    2. onAdvance(cid, skill, oldLevel, newLevel)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onAdvance(player, skill, oldLevel, newLevel)
    3.  
    See both player and cid above for an in-depth explanation.

    skill is a number and is referring to the 9 different skills associated with the player and can be referenced either by name or number this includes all the melee skills, magic level, experience level and fishing.

    List of skills for this parameter
    Code (Text):
    1.  
    2.     SKILL_FIST = 0
    3.     SKILL_CLUB = 1
    4.     SKILL_SWORD = 2
    5.     SKILL_AXE = 3
    6.     SKILL_DISTANCE = 4
    7.     SKILL_SHIELD = 5
    8.     SKILL_FISHING = 6
    9.     SKILL_MAGLEVEL = 7
    10.     SKILL_LEVEL = 8
    11.  
    oldLevel is a number and is referring to the previous level they had before they leveled up.

    newLevel is a number and is referring to the current level they have now as a result of leveling up.

    onDeath

    1.0
    Code (Text):
    1.  
    2. onDeath(cid, corpse, lasthitkiller, mostdamagekiller, lasthitunjustified, mostdamageunjustified)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onDeath(creature, corpse, lasthitkiller, mostdamagekiller, lasthitunjustified, mostdamageunjustified)
    3.  
    Both cid, and creature are userdata and can be either a monster, npc or player which has died.

    corpse is the body or container of the thing that died.

    lasthitkiller is userdata, this is an npc, monster, player or field which hit the npc, monster or player last before it died

    mostdamagekiller is userdata, this is an npc, monster, player or field which did the most damage to the npc, monster or player before it died.

    lasthitunjustified is a boolean value, this is open for debate might just be player related I honestly don't know, when i think unjustified i think pker, however this could also possibly be a player experience stealer.

    mostdamageunjustified is a boolean value, this is open for debate might just be player related I honestly don't know, when i think unjustified i think pker, however this could also possibly be a player experience stealer.

    onPrepareDeath

    1.0
    Code (Text):
    1.  
    2. onPrepareDeath(cid, killer)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onPrepareDeath(creature, killer)
    3.  
    Both cid, and creature are userdata and can be either a monster, npc or player which is about to die.

    killer is also userdata this is can be an npc, monster, player or field which is about to kill the player, monster or npc.

    onThink

    1.0
    Code (Text):
    1.  
    2. onThink(cid, interval)
    3.  
    1.1 - 1.2
    Code (Text):
    1.  
    2. onThink(creature, interval)
    3.  
    Both cid and creature are userdata and can refer to being a monster, npc or player.

    interval is a number which is based in miliseconds

    onTextEdit

    1.0 - 1.2
    Code (Text):
    1.  
    2. onTextEdit(player, item, text)
    3.  
    See above for the in-depth explanation of player.

    item is userdata and can be any item you can write text to.

    text is a string the text to write

    I'll use an example found in this thread but convert it to 1.2
    CreatureEvent - Deathnote! (onTextEdit example)

    Code (Text):
    1.  
    2. function onTextEdit(player, item, text)
    3.     if item.actionid == 9202 then
    4.         local name = Player(text)
    5.         if name then
    6.             name:addHealth(-name:getMaxHealth())
    7.         end
    8.     end
    9.     return true
    10. end
    11.  
    onHealthChange

    1.0 - 1.2
    Code (Text):
    1.  
    2. onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    3.  
    creature and attacker are userdata and can be a monster, npc or player.

    primaryType and secondaryType are a combat type, please see below.
    Code (Text):
    1.  
    2.     COMBAT_NONE
    3.     COMBAT_PHYSICALDAMAGE
    4.     COMBAT_ENERGYDAMAGE
    5.     COMBAT_EARTHDAMAGE
    6.     COMBAT_FIREDAMAGE
    7.     COMBAT_UNDEFINEDDAMAGE
    8.     COMBAT_LIFEDRAIN
    9.     COMBAT_MANADRAIN
    10.     COMBAT_HEALING
    11.     COMBAT_DROWNDAMAGE
    12.     COMBAT_ICEDAMAGE
    13.     COMBAT_HOLYDAMAGE
    14.     COMBAT_DEATHDAMAGE
    15.  
    primaryDamage and secondaryDamage are a number which corresponds to the damage type the creature, npc or player receives.

    origin - please refer to the origin list below

    Origin list
    Code (Text):
    1.  
    2.     ORIGIN_NONE,
    3.     ORIGIN_CONDITION,
    4.     ORIGIN_SPELL,
    5.     ORIGIN_MELEE,
    6.     ORIGIN_RANGED,
    7.  
    onManaChange

    1.0 - 1.2
    Code (Text):
    1.  
    2. onManaChange(creature, attacker, manaChange, origin)
    3.  
    creature and attacker are userdata and can be a monster, npc or player.

    manaChange is a number and corresponds to how much mana which was lost or gained.

    origin - please refer to the origin list above

    onExtendedOpcode

    1.0 - 1.2
    Code (Text):
    1.  
    2. onExtendedOpcode(player, opcode, buffer)
    3.  
    opcode is a number (only information i could find on this was CREATURE_EVENT_EXTENDED_OPCODE)

    buffer is a string, will have to skip this til i know more

    onModalWindow

    1.0 - 1.2
    Code (Text):
    1.  
    2. onModalWindow(player, modalWindowId, buttonId, choiceId)
    3.  
    player is userdata and only refers to a player.

    modalWindowId is the id number of the window.

    buttonId this is a number of the button to press which either exits the window or executes the selection.

    choiceId this is a number which corresponds to the id of the selection

    We will use a shorter version of this example to save space
    Lua - Problems with a TP script.

    Code (Text):
    1.  
    2. local towns = {
    3.     "Thais",
    4.     "Carlin",
    5.     "Venore"
    6. }
    7.  
    8. function onUse(player, item, fromPosition, target, toPosition, isHotkey)
    9.     if player:getCondition(CONDITION_INFIGHT, CONDITIONID_DEFAULT) then
    10.         player:sendCancelMessage("PZ locked!")
    11.         player:getPosition():sendMagicEffect(CONST_ME_POFF)
    12.         return true
    13.     end
    14.  
    15.     local modalWindow = ModalWindow(2, "Destination", "Make your choice:")
    16.     for i = 1, #towns do
    17.         modalWindow:addChoice(i, i .. ". " .. towns[i])
    18.     end
    19.  
    20.     modalWindow:addButton(1, 'Go')
    21.     modalWindow:setDefaultEnterButton(1)
    22.     modalWindow:addButton(2, 'Exit')
    23.     modalWindow:setDefaultEscapeButton(2)
    24.  
    25.     modalWindow:sendToPlayer(player)
    26.     player:registerEvent("eventName")
    27.     return true
    28. end
    29.  
    30. local destinations = {
    31.     Position(32369, 32241, 7),
    32.     Position(32360, 31782, 7),
    33.     Position(32957, 32076, 7)
    34. }
    35.  
    36. function onModalWindow(player, modalWindowId, buttonId, choiceId)
    37.     player:unregisterEvent("eventName")
    38.     if modalWindowId ~= 2 or buttonId ~= 1 then
    39.         return false
    40.     end
    41.  
    42.     local destination = destinations[choiceId]
    43.     if not destination then
    44.         return true
    45.     end
    46.  
    47.     player:teleportTo(destination)
    48.     destination:sendMagicEffect(CONST_ME_TELEPORT)
    49.     return true
    50. end
    51.  
    reserved

    reserved
     
    Last edited by a moderator: Jun 15, 2018
  3. Mkalo

    Mkalo ボーカロイド Support Team

    Joined:
    Jun 1, 2011
    Messages:
    1,120
    Likes Received:
    902
    Best Answers:
    55
    Good job.
    Little correction: Item is an userdata not a metatable.

    Only positions are metatables. The other stuff is all userdata. In fact it's a table with Position metatable but that's not that relevant.
     
    StreamSide and Codex NG like this.
  4. Codex NG

    Codex NG Recurrent Flamer

    Joined:
    Jul 24, 2015
    Messages:
    3,000
    Likes Received:
    1,607
    Best Answers:
    12
    thank you sir :)
     
    Banned_User likes this.
  5. Evil Hero

    Evil Hero Legacy Member

    Joined:
    Dec 12, 2007
    Messages:
    1,095
    Likes Received:
    464
    Best Answers:
    2
    Well done so far.
    I just have a little suggestions, you could list all the available events first and then go into detail.
    I know first hand that a lot of people look into this threads and search for an overview, so instead of going through everything and searching it, they can find it easily in a list.

    Probably even add the parameters already to it, easy to copy paste for people who aren't familiar with them then.
     
    Last edited by a moderator: Jun 15, 2018
    Codex NG likes this.
  6. Codex NG

    Codex NG Recurrent Flamer

    Joined:
    Jul 24, 2015
    Messages:
    3,000
    Likes Received:
    1,607
    Best Answers:
    12
    Text is limited per post :(

    I am going to re-arrange the explanation so its in the listing order, I have to get ready for work soon, should of thought about this over the weekend.
     
    Last edited: May 9, 2016
    Banned_User likes this.
  7. Evil Hero

    Evil Hero Legacy Member

    Joined:
    Dec 12, 2007
    Messages:
    1,095
    Likes Received:
    464
    Best Answers:
    2
    reminds me why I didn't update my old tutorial, I cannot even edit the posts cause they're to long, even reporting them didn't really cause any attention to get them changed by a mod
     
  8. Frillinde

    Frillinde Founder: Another Realm

    Joined:
    Jan 16, 2012
    Messages:
    148
    Likes Received:
    3
    Best Answers:
    0
    This is very helpful for me.
    Thank you
     
    Codex NG likes this.
  9. Codex NG

    Codex NG Recurrent Flamer

    Joined:
    Jul 24, 2015
    Messages:
    3,000
    Likes Received:
    1,607
    Best Answers:
    12
    I have the day off tomorrow so I will continue to up this tutorial.
     
    Saints Anathema and Banned_User like this.
  10. Saints Anathema

    Saints Anathema Old School Doleran

    Joined:
    Feb 24, 2009
    Messages:
    654
    Likes Received:
    8
    Best Answers:
    0
    appreciate the work,
    im trying to do more, to learn more

    easily understood!
     
  11. GOD Half

    GOD Half Member

    Joined:
    May 9, 2010
    Messages:
    177
    Likes Received:
    12
    Best Answers:
    0
    Hi, how I get Experience (like monsterType:getExperience()) inside of onHealthChange ?
     
  12. bayview

    bayview Banned User

    Joined:
    Jan 25, 2018
    Messages:
    612
    Likes Received:
    304
    Best Answers:
    24
    creature or attacker could possibly be a monster but you'll need to check for it being a monster because both Player & MonsterType have the method getExperience.

    Code (Text):
    1. https://github.com/otland/forgottenserver/search?l=C%2B%2B&q=getexperience&type=
     
    GOD Half likes this.
  13. GOD Half

    GOD Half Member

    Joined:
    May 9, 2010
    Messages:
    177
    Likes Received:
    12
    Best Answers:
    0
    Can you help me formulate within the onHealthChange the ability to print the monster experience? I need to make a critical calculation based on the monster's experience
     
  14. bayview

    bayview Banned User

    Joined:
    Jan 25, 2018
    Messages:
    612
    Likes Received:
    304
    Best Answers:
    24
    Always check the sources, particularly luascript.cpp this source file will let you know if a specific method exists.
    Here is your example.
    Code (Lua):
    1. function onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    2.     if creature:isMonster() then
    3.         -- do something
    4.     elseif attacker:isMonster() then
    5.         -- or do something else
    6.     end
    7.     return primaryDamage, primaryType, secondaryDamage, secondaryType
    8. end
    Code (Text):
    1. https://github.com/otland/forgottenserver/search?q=isMonster&unscoped_q=isMonster
    Remember both Player & MonsterType have the same method getExperience. Unfortunately I will not complete the script for you.. don't be afraid to code even if it crashes the server.. its not made out of glass.
     
    GOD Half and Sarah Wesker like this.
  15. samco

    samco 4x4 Developer.

    Joined:
    Jul 3, 2007
    Messages:
    879
    Likes Received:
    180
    Best Answers:
    5
    Ar those interfaces or callbacks?
     
  16. bayview

    bayview Banned User

    Joined:
    Jan 25, 2018
    Messages:
    612
    Likes Received:
    304
    Best Answers:
    24
    They are arguments, All of these parameters (creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin) are really arguments, they are sent from the server but only primaryDamage, primaryType, secondaryDamage, secondaryType are returned. However you can manipulate these values prior to returning them. As an example by setting the values primaryDamage & secondaryDamage to 0 you can emulate invincibility from an attack that affects the player's health, hence the name onHealthChange.

    onHealthChange is the interface.
     
  17. samco

    samco 4x4 Developer.

    Joined:
    Jul 3, 2007
    Messages:
    879
    Likes Received:
    180
    Best Answers:
    5
    Sorry for the missunderstanding, i meant all the time "onHealthChange". As your first post you say those are interfaces. I would not call them interfaces.

    Good post anyway.
     
  18. bayview

    bayview Banned User

    Joined:
    Jan 25, 2018
    Messages:
    612
    Likes Received:
    304
    Best Answers:
    24
    But they are interface's otland/forgottenserver
    Google definition of an interface in regards to programming
    Code (Text):
    1. Interfaces in Object Oriented Programming Languages. An interface is a programming structure/syntax that allows the computer to enforce certain properties on an object (class). For example, say we have a car class and a scooter class and a truck class. Each of these three classes should have a start_engine() action.
     
  19. StreamSide

    StreamSide Joseluis Gonzalez

    Joined:
    Aug 31, 2007
    Messages:
    2,976
    Likes Received:
    672
    Best Answers:
    17
    this is very good :)
     
  20. Jo3Bingham

    Jo3Bingham Well-Known Member

    Joined:
    Mar 3, 2008
    Messages:
    974
    Likes Received:
    409
    Best Answers:
    4
    This is correct. The Creature Event class is the interface, and things like onHealthChange are events (methods) of that class. Technically, C++ doesn’t have interfaces, just abstract classes, but that’s beside the point.
     
    Last edited: Jun 15, 2018
    J.Dre and samco like this.

Share This Page

Loading...