RoM Functions

From SolarStrike wiki
Jump to: navigation, search

General Functions

     loadPaths( [path] [,returnpath] );

Load a new waypoint file and if available the default return path to that file. e.g. 'loadPaths("l7-9");' will load the waypoint path 'l7-9.xml' and if available the return path 'l7-9_return.xml'.


changeProfileOption(_option, _value);

change profile options and print values in MM protocol

changeProfileSkill(_skill, _option, _value)

Change a profile skill option and print a message in the micromacro window. Especially useful for skill options that don't normally change and can't be changed in the skills section of the profile eg. CastTime or Cooldown.

levelupSkill(_skillname [, _times] )

Levelup a Single Skill by Name. For the skillname look into the file /database/skills.xml. You can use that function only for skill, which have maintent the skilltab and skillnum values within the skills.xml entry. If the don't have that values, please look yourself for them and use the manual way.

levelupSkills1To10( ["loadonly"] );

That function will levelup a internal given selection of useful skills on your way from 1-10. The selection of the skills is hard coded within functions.lua. That function will also load the skill into your profile skill list and use that skill via the MACRO function. If you restart the bot and want also want to use that skills and don't want to enter them manual into the profile skill list, then just use that function with the parameter 'loadonly' within the onLoad event:

openGiftbags1To10( [[_player_level] , _maxslot] );

open the level 1-10 giftbags and equipt the items.


addMessage( message );

Send a message to the ingame system chat channel.


RoMScript( _script );

 example:
 local ret1, ret2 = RoMScript( "GetPlayerWorldMapPos();" );

Send a macro to the client and execute it ingame by pressing the MACRO hotkey. There are up to 10 return values possible.


sendMacro( _script );

Same as "RoMScript. Additionally you will see a message in the MM window.

getQuestStatus( _questname )

This will return the status of the quest. It will return 'complete' if the quest is completed and ready to be turned in, 'incomplete' if you have accepted the quest but haven't completed it yet and 'not accepted' if you have not accepted the quest. The use of this function requires that the ingamefunctions folder be installed in the games addon folder.

waitForLoadingScreen( [_maxWaitTime] )

Waits for the loading screen to appear then disappear. Used after starting a teleport, entering your house, loading a new character, etc. Basically after any action that would cause the loading screen to appear. Replaces the need to add an overly large yrest(nnnnn). If the optional argument _maxWaitTime is specified and that many seconds has passed without the loading screen appearing, then it will stop waiting and return 'false', else it will return 'true'.

distance(x1, z1, y1, x2, z2, y2)
distance(x1, z1, x2, z2)

Returns the distance between 2 points. Both forms of the command will work. If all 6 arguments are used then it will do a 3 dimensional calculation ie. will take into account the height of the points otherwise it will do a 2 dimensional calculation.

Event Monitor Functions

     EventMonitorStart(monitorName, event [,filter])

Tells the in-game-function's addon to start monitoring event "event" and saving them to a log under the name of "monitorName". "monitorName" is just a name to identify the event monitor. If a filter is included then only events that pass the filter will be saved.

eg.

     EventMonitorStart("LeaderChat", "CHAT_MSG_PARTY",",,,MyLeaderName")

This will monitor party chat and save any events that have the word "MyLeaderName" in the 4th argument which happens to be the chat senders name.

     EventMonitorStop(monitorName)

This will stop monitoring events for "monitorName" and remove any log entries under that name.

     EventMonitorPause(monitorName)

This will pause the event monitor. It will not save any events under that name while paused. You can still retrieve the log entries saved under that name while it is paused.

     EventMonitorResume(monitorName)

This will resume a paused monitor and start saving events again under that name.

     local time, moreToCome, arg1, arg2, arg3, arg4, arg5, arg6 = EventMonitorCheck(monitorName[, returnFilter][, lastEntryOnly])

Use this to return data of an event saved under the name of "monitorName". This function only returns data of 1 event at a time. By default it returns the first log entry under this name and then deletes it from the log. You can use the returnFilter to only return the event arguments you are interested in. If you only want the latest event and are not interested in older events then you can set lastEntryOnly = true. Then only the last entry in the log under that name will be returned and all other entries will be erased.

The returned values are:

time - The time the event occurred. I used os.time() to get this value but rombots version of this command returns a different value so I'm not sure how you can use this but I thought it needed to be included. Maybe it can be changed to a better format in the future.

moreToCome - Is 'true' if there are more log entries under that name and 'false' if not. This would be useful to iterate though all the messages to collect them all.

arg1, arg2, ... argn - These are the arguments returned by the event. If no returnFilter was specified then all arguments will be returned. If the returnFilter was used then only the requested arguments will be returned in the order requested.

eg.

     local time, moreToCome, name, msg = EventMonitorCheck("LeaderChat", "4,1")

This will return the next "LeaderChat" log entry. Note that I only want the 4th and 1st argument. The 4th argument is the sender and will be stored in the 'name' variable and the 1st argument is the message and will be stored in the 'msg' variable.

Player Functions

     player:harvest([id]);

Use 'player:harvest()' to scan that waypoint for a harvest node and harvest that ie. wood, herbs and ore. For backward compatibility you can use 'player:harvest(id-nr)' to scan and use/open a object with that given object-id but you should use player:target_Object() instead as it has more options related to opening objects. Note: 'player:harvest("test")' is no longer supported, use 'rom/getid.lua' instead.


     player:restrnd([probability [, minrest [, maxrest]]]);

e.g. 'player:restrnd(30, 3, 10);' Rest with a probability from 30% at that waypoint for between 3 and 10 seconds. The bot will fight back if attacked while resting and continue after that. Similar functions are 'stopPE()' and 'player:sleep()'.


     player:rest( minrest [, maxrest[, time|full[, restaddrnd]]]);

minrest ( min time to rest in sec) maxrest ( max time to in sec) resttype ( time | full ) time = rest the given time | full = stop resting after being full / default = time restaddrnd ( max random addition after being full in sec)

If using type 'full', the bot will only rest if HP or MP is below a defined level. You define that level in your profile with the options: Code:

     <option name="HP_REST" value="15" />
     <option name="MP_REST" value="15" />

Default value if not defined is 15% each.

     examples:
     player:rest(20) will rest for 20 seconds.
     player:rest(60, 20) will rest between 60 and 80 seconds.
     player:rest(90, 40, "full") will rest up to between 90 and 130 seconds, and stop resting if being full
     player:rest(90, 40, "time") will rest up to between 90 and 130 seconds, and not stop resting if being full
     player:rest(20, 40, "full, 20") will rest up to between 20 and 60 seconds, and stop resting if being full, and wait after that between 1-20 seconds


     player:sleep();

Pause the bot at that waypoint in a sleep mode. The bot will still fight back attackers and sleep again after doing that. Press DEL if you want to continue. Similar functions are 'player.restrnd()' and 'stopPE()'.


     player:logout([true]);

Logout from RoM. With 'player:logout(true)' you will also shutdown your pc after loging out.


     player:mouseclickL(x, y [RoM window wide, RoM window high]);

Left click a screen point and by that, interact with a NPC. x, y is relative to the RoM window. So it is your fiddly task to find the right values to click the right buttons. Remember the RoM windows size for that click positions. By doing that, we can later recalculate the mouse click points if we run the bot in a different RoM windows size.

     player:cast("skill"|skill);

This function accepts either a skill name (ie. "MAGE_FIREBALL") or a skill object (ie. settings.profile.skills["MAGE_FIREBALL"]). If the parameter is a string, it must be listed in the players' profile.

     player:checkSkills(_only_friendly);

This will check all skills that the player has loaded in his profile for those that are appropriate to use. _only_friendly should be either true or false. If true, it will only use helpful skills, such as healing, even while in combat. This is generally not needed by the end-user.

     player:checkPotions();

This is similar to player:checkSkills(). It will check if the player needs to use any potions and use them accordingly. This is generally not needed by the end-user.

     player:hasBuff(_buffname);

This will return true if your player has the buff, false if not. Run player:updatebuffs() first if you need to be sure your buff list is up-to date. Can also be used to check buffs on target. You may need to create the target object first. For example:

 local target = player:getTarget();
 target:updateBuffs()
 if target:hasBuff("buffname") then
 etc...
     player:hasDebuff(_debuffname);

This will return true if your player has the debuff, false if not. Run player:updatebuffs() first if you need to be sure your debuff list is up-to date. Can also be used to check debuffs on target. You may need to create the target object first. For example:

 local target = player:getTarget();
 target:updateBuffs()
 if target:hasDebuff("debuffname") then
 etc...
     player:fight();

If the player has an enemy target, it will engage that target in combat. This is generally not needed by the end-user.

     player:loot();

If the player has a dead enemy target, it will attempt to loot the corpse. This is generally not needed by the end-user.

     player:lootAll();

Will attempt to loot all nearby lootable bodies. This is generally not needed by the end-user.

     success, reason = player:moveTo(waypoint, ignoreCycleTargets);

This will attempt to move the player to the given waypoint. If ignoreCycleTarget is true, it will not attempt to target and engage nearby enemies while on the move. 'waypoint' may also be a unit (such as player.Target - to move to the player's target). If you have raw coordinates, such as 100,200 that you want to move to, use CWaypoint(100,200) for your 'waypoint'.

This function will return whether or not it was successful and, if unsuccessful, the reason. 'success' will either be true or false, and 'reason' will be WF_TARGET(we abandoned movement because we've got a target), WF_COMBAT(we abandoned movement because we entered combat [typically; pulled an aggressive monster]), WF_DIST(for some reason or other, we actually started moving away from the waypoint [slid down a hill?]), or WF_STUCK(got stuck on something in the terrain).

     player:waitForAggro();

This function causes the player to stop and wait for a maximum of 5 seconds for aggressive enemies to engage in combat with the player. This is typically not needed by the end-user.

     player:faceDirection(angle);

This will rotate the character to face the specified direction in radians(not degrees!). This is typically not needed by the end-user.

     player:turnDirection(angle);

This will rotate the character some amount rather than face a specific direction. If 'angle' is negative, the character will rotate 'left', and if 'angle' is positive, then the character will rotate 'right'. 'angle' should be specified in radians.

     player:unstick();

Attempts to get the player out of being stuck on something. This is generally not needed by the end-user.

     player:haveTarget();

Returns true if the player has a valid, attackable target.

     player:update();

This causes the player to update all information (hp/mp/etc. from the game client). This should be used after causing the player to enter their home, teleport, log out and back in, etc.

     player:clearTarget();

Causes the player to drop their current target.

     player:isFriend(pawn);

Returns true if the given pawn (such as player.Pet or player.Target) are on the player's friend list inside their profile.

     player:isInMobs(pawn);

Exactly like player:isFriend(), only it checks if the pawn is in the 'mobs' section of their profile.

     player:logout(fc_shutdown);

Causes the player to attempt to log out of the game and, optionally, shut down their computer (if available). If fc_shutdown is true, it will attempt to shut down your computer after logging off.

     player:findTarget();

Attempts to locate a nearby target, returning true if it does, otherwise false.

     player:merchant(_npcname, _option);

Attempts to open the store of a nearby NPC with the name given by '_npcname'. It will then buy, sell and repair based on the characters profile settings. If the 'open shop' option is not the first in the npc dialog, eg. house npcs, you can specify which option it is in the second argument '_option'. '_option' is optional and will default to 1 which is correct for most merchants.

     player:openStore(_npcname, _option);

Attempts to open the store of a nearby NPC with the name given by '_npcname'. You can then issue your own buy and/or sell commands. If the 'open shop' option is not the first in the npc dialog, eg. house npcs, you can specify which option it is in the second argument '_option'. '_option' is optional and will default to 1 which is correct for most merchants.

     player:target_NPC(_npcname);

This will attempt to target a nearby NPC with the name given by '_npcname' but not interact with them.

     player:target_Object(_objname, _waittime, _harvestall, _donotignore, _evalFunc);

This will target an object similarly to target_NPC but this function has more options to cater for the different behaviors of different objects.

_objname = name or id of object to target. Accepts partial names or a table of names and ids.(Required)

_waittime = time to wait if the object takes time to action, in ms. By default will wait until casting bar is gone. Only really necessary if you want it to wait longer than it takes to collect.(Optional)

_harvestall = true if you wish to collect all in the immediate area. Only use if the object disappears once collected. (Default is false ie. opens/collects only once)

_donotignore = If false, will target an object once then move onto the next object. If true, will continue to target object until it disappears or moves away. Only set to true if the target disappears or moves away or you might end up in an infinite loop.(if _harvestall = true then the default is false, else it is true).

_evalFunc = A user created custom function that can be used to evaluate whether objects are valid or not. Should except an address as an argument and return true or false. (Optional)


Examples:

player:target_Object ("Mailbox") -- Targets 'Mailbox' with no wait time afterward.

player:target_Object ("Ranch Hen", 8000) -- Encourage hen to lay then wait 8 seconds even though the cast bar only appears for a couple of seconds. Done only once.

player:target_Object ("Ranch Hen", nil, true, true) -- Feed all nearby hens, waiting until the cast bar ends. And do not ignore the current hen when searching for the next closest.

The example below targets all hens in the coop by checking their Z coordinate, with no ignoring.

-- The evaluate function
function henInCoop (address)
  if CObject(address).Z > 3240 then
    return true
  else
    return false
  end
end

-- The target hen command
player:target_Object("Ranch Hen", nil, true, true, henInCoop);


     player:findNearestNameOrId(_objnameorid, _evalFunc)

Finds the nearest object without targeting it. Accepts the items name or id as argument or a table of items and ids to search for. Returns the closest objects table or nil if not found. For a description on how to use _evalFunc, please read the description for player:target_Object() above.

     player:mount();

Finds the first permanent mount in your known inventory (typically slots 1-60; item shop bag not checked) and, if found, mounts it. You may also check if player.Mounted is true or false if you want to know whether the player is mounted or not. Will respond to aggro if mounting is interrupted but will still mount once aggro is dealt with.

Inventory and Item Functions

inventory:itemTotalCount(itemNameOrId, range)

Get the total quantity of an item in your inventory. You can use the item-id or the name of the item. As a second argument you can specify where to look. Accepted values for range are; 'all', 'bags', 'bag1', 'bag2', 'bag3', 'bag4', 'bag5', 'bag6', 'magicbox' and 'itemshop'. By default it searches just the 'bags'.

example:

if( inventory:itemTotalCount(214536) > 25 ) then
   loadPaths("deliver_quest");
end
inventory:getItemCount(itemNameOrId, range)

This function is obsolete. It is kept for backward compatibility. It is functionally the same as using inventory:itemTotalCount(itemNameOrId, range)

inventory:findItem(itemNameOrId, range)

Finds the first item in your inventory by name or id and returns the item object. If it is a stackable item it will return the smallest stack of that item. As a second argument you can specify where to look. Please consult the 'inventory:itemTotalCount' entry for excepted values for 'range'. By default it will search 'all' the inventory.

inventory:useItem(itemNameOrId)

Finds an item in the inventory by name or id then uses it.

inventory:getMainHandDurability()

Returns the durability of the main-hand weapon as a percent value from 1 to 100.

inventory:update()

Update the whole inventory from the games client.

inventory:storeBuyItem(nameIdOrIndex, quantity)

Buys 'quantity' of items from a store by name, id or store index. Assumes store is already open. If 'quantity' is not specified then it will buy 1 by default.

Examples:

inventory:storeBuyItem("Gold-wrapped Belt") -- Buy by item name
inventory:storeBuyItem(221544, 1) -- Buy by item id
inventory:storeBuyItem(3, 1) -- Buy by store index

All of these examples will do the same thing, buy 1 'Gold-wrapped Belt'.

item:moveTo(bag)

Moves the item to the specified bag. Accepted values for bag are; 'bags', 'bag1', 'bag2', 'bag3', 'bag4', 'bag5', 'bag6', 'magicbox' and 'itemshop'. If possible it will try to merge stackable items. This is particularly useful for moving itemshop items to the itemshop bag.

inventory:deleteItemInSlot(slot)

Deletes the item in the numbered slot. Values range from 0-240; Slots 0-22 are equipped items, Slots 23-60 are for the Item Shop Bag, Slots 61-240 are your inventory bag slots.

Waypoint File Functions

__WPL:reverse();

Resort the waypoints. Means after running from 1 to 20 you can now run from 20 - 1. It is strongly recommended to use '__WPL:setDirection(..)' instead of this function.


__WPL:setDirection( [WPT_FORWARD | WPT_BACKWARD] );

Set the direction in which order the waypoints should be proccessed. It is usefull to put that at the first and at the last waypoint if you want to run between two places. Remember to use WPT_FORWARD at the first and WPT_BACKWARD at the last waypoint to run between them. Use this instead of '__WPL:reverse()' to avoid problems in your waypoint file.


__WPL:setWaypointIndex( number);

Set the waypoint # 'number' as next waypoint to reach


__WPL:getNearestWaypoint(player.X, player.Z);

Get back the number of the closest waypoint.


__WPL:setForcedWaypointType( [["NORMAL"] | ["TRAVEL"] | ["RUN"]]);

Set a forced waypoint type. The waypoint type overwrites the type settings within the waypoint file. The forced waypoint type is valid until you load a new waypoint file or you call the function '__WPL:setForcedWaypointType();' without argument.


__WPL:getFileName();
Returns the name of the waypoint file as string (e.g. "l1t_start.xml"). The string will not contain any information about the path of the file.

RoM API Functions

With the function sendMacro() or RoMScript() we can submit macros to the RoM API. For a complete list of RoM API functions, go to http://theromwiki.com/index.php/List_of_Functions

Here are some important API functions you can use:

sendMacro("SetSpellPoint( 4, 2 );");

Levelup a skill. First number is the tab (1=general, 2=general class skills, 4=only primary class skills). Second number is the number of the skill at the tab. You can test the numbers by entering following macro ingame:

/script _SkillName=GetSkillDetail(4,3); SendSystemChat(_SkillName);
That will print you the name of the given skill into the ingame system chat.


/script SendSystemChat(tonumber(string.sub(GetBagItemLink(GetBagItemInfo(1)), 8, 12), 16));

Print the itemid of slot-nr 1 into the system chat. Change the slot number to the item you want to get informations about or move that item to slot #1.


sendMacro("GetBagItemCount("..itemid..")")

Get back the quantity of an givem item ID in your bags.


occupiedSlots, totalSlots = sendMacro("GetBagCount();");

Get back the number of total slots in your bag and the number of the occupied slot in your bag.

User Functions

Since version r413 users are able to use a userfunctions.lua file in the Rombot root directory to hold all of their own custom functions.

If you find that you repeat a particular set of code in your waypoint files, you can create your own function with that code in the userfunctions.lua file and use it anywhere with a simple call to that function.

eg.

------------------------------------------------
-- CancelBuff Script
-- buffname = name of buff as appears in player buffs
-- returns 'true' if buff was removed or 'false' if did not have buff.
------------------------------------------------
function CancelBuff(buffname)
    if buffname == nil then
        cprintf(cli.yellow,"No buff specified. Please use 'CancelBuff(buffname)'.\n")
        return false
    end
    local buffnum=1
    local buff=RoMScript("UnitBuff('player',"..buffnum..")");
    while buff ~= nil do
        if buff == buffname then
            sendMacro("CancelPlayerBuff("..buffnum..");")
            return true
        end
        buffnum=buffnum+1
        buff=RoMScript("UnitBuff('player',"..buffnum..")");
    end
    return false
end

With this function in my userfunctions.lua file I can cancel a buff with a 1 line command. For example, every time I want to dismount my Brown Horse I use

CancelBuff("Brown Horse")

To use, simply create a text file in the rombot root directory named userfunctions.lua and place your functions within it.

Some user created custom functions can be found here: New Feature: Userfunctions.lua