SCRIPTING and PtokaX ======================= ! LUA is not VBScript compatible ! There are some differences from VBScript used in NMDC hub. First, the LUA is not a true object oriented programing language. From script there is NO DIRECT ACCESS to objects or classes of the host application. Everything you can access is defined by the API which is currently under development and can be changed a little bit or extended according to requests from other users/coders. Detailed overview of LUA4 syntax can be found on http://www.lua.org Changes: ======== 09.06.2003 - added: frmHub:EnableSearchData(n) ... enables/disables passing of $Search, $MultiSearch and $SR to current script frmHub:EnableFullData(n) ... enables/disables passing of ALL incomming data to current script 05.06.2003 - added: user:TimeBan(time) ... bans temporarily for specified amount of minutes 04.06.2003 - added: frmHub:GetMinShare() ... returns the minshare in bytes frmHub:SetMinShare(amount, unit) ... set the minshare (unit: 0=byte, 1=KByte,2=MByte, 3=GByte) frmHub:GetCurrentShareAmount() ... returns te total share of all users at the moment frmHub:GetOpChatName() ... returns the name of the OpChat-Bot frmHub:GetHubBotName() ... returns te name of the HubBot user:TempBan() ... bans temporarily without kick-message AddProfile(profile_name, profile_data) ... adds new profile RemoveProfile(profile_name) ... removes profile GetProfileIdx(profile_name) ... gets profile index by profile name GetProfileName(profile_idx) ... gets profile name by profile index GetProfiles() ... returns profile names in a table GetUsersByProfile(profile_name) ... returns table of all users with given profile changed: AddRegUser(nick,pass,profile_index) is now global function. No preceeding frmHub is needed DelRegUser(nick) is now global function. No preceeding frmHub is needed 20.02.2003 - added: user:Kick(reason) - added: return value can be used in DataArrival(user, data) function return 1 to stop processing the data by the hub, return 0 or no return at all to let the hub process the data. Look at TrickerBot2.lua for better understanding 11.02.2003 - added: ClearTempBan() function 28.12.2002 - added: SetTimer, StartTimer, StopTimer 31.12.2002 - added: UnregBot, SendToOps, SendPmToOps - added: event functions UserDisconnected, OpDisconnected 10.01.2003 - fixed: SendToOps(from, data), SendPmToOps(from, data) now works for NMDC - added user class methods: Ban() NickBan() - added: global methods: Unban(what), DisconnectByName(nick), GetItemByName(nick), SendPmToAll(from, data), - changed: global SendToAll is now overloaded can be used in these forms: SendToAll(from, data) SendToAll(data) // for sending raw data to all at once - changed: user class method SendData is now overloaded the same way as global SendToAll user:SendData(from, data) user:SendData(data) The Editor ---------- [Load] loads desired script file into editor In the editor you can write your code and check for syntax errors. This editing doesn't affect the script file. [Save] saves the script code from editor into desired file [Restart scripts] is enabled only when serving. This one reloads all scripts from the script folder and call their Main() functions. [Check syntax] will call the script engine to parse the code and check it for syntax errors. Note that it will NOT check the variable names, number of function arguments etc. What's implemented right now ? ------------------------------ Right now the most usefull functions are implemented. Most of common scripts will use them. Below is a common script skeleton, you can/may use as a good starting point. --// PtokaX script skeleton START ---------------------------------------------------- -- if you need any global variable, define them outside any function -- for example here, onthe top of the script --// below are predefined functions which are called by the hub on a specific action --// This function is fired at the serving start function Main() -- TODO your code here end --// This function is fired when a new data arrives function DataArrival(curUser, sData) -- TODO your code here end --// This function is fired when a new user finishes the login function NewUserConnected(curUser) -- TODO your code here end --// This function is fired when an operator enters the hub function OpConnected(curUser) -- TODO your code here end --// This function is fired when an user disconnects function UserDisconnected(curUser) -- TODO your code here end --// This function is fired when an operator disconnects function OpDisconnected(curUser) -- TODO your code here end --// PtokaX script skeleton END ---------------------------------------------------- Variables --------- Variables in LUA are easy. myvariable1 = "Hallo" botName = "MyKewlBot" minShare = 50 * (1024*1024*1024) pi = 3.14 someArray = { "string1", "string2", 123, 666, "etc"} -- or an associative array aarray = { bot="myBot", op1="John", op2="Ptaczek", ["very long key"]="theLongKey" } -- then you can obtain ptaczek by aarray.op2 -- or the long key by aarray["very long key"] -- arrays can hold also functions references fnarray = { fn1 = function(arg1, arg2) return arg1+arg2 end } -- then you can call it by fnarray.fn1(2,3) Data sending ------------ Inside the script you can send data to another user or to all users. The 'data' means ANY string including control character. data - is a simple string variable. In function DataArrival(user, data) the 'data' variable contains the received data including the ending '|' userObject - is an associative array with these fields: properties: sName bOperator sIP iVersion sMyInfoString iProfile methods: SendData(data) SendPM(from, data) Disconnect() Ban() NickBan() TempBan() ... bans temporary without kick-message TimeBan(time) ... bans temporarily for specified amount of minutes Calling methods, reading properties ----------------------------------- Remeber! - user's property is accessible via dot! Ex.: curUser.sName - user's method is called via double_dot! Ex.: curUser:SendData("Hello user") This is really iportant. If you try access property via ':' or call method via '.' then you get nothing. Also note,that by now all properties are just read-only variables. sName - (string) user's nickname bOperator - (nil or integer) when nil, the user is not operator. sIP - (string) users IP address. iVersion - (string) users client version sMyInfoString - (string) MyINFO string including the $MyINFO and the ending '|' iProfile - (number) users profile index or -1 for normal user. Use GetProfileName(index) to get the profile name string Global Data-Sending Functions and User-manipulating functions ============================================================= Data-Sending ------------ SendToNick(nick, data) - Sends data to specified nick. If the nick is not online then it's ignored nick - a nickname of user you want to send data to data - string to send SendToAll([from,] data) - Sends text to mainchat window of all users from - [optional] nick of sending user or bot or anything data - string to send SendPmToAll(from, data) - Sends private message to all users from - nick of sending user or bot or anything data - message to send SendPmToNick(to, from, data) - Sends a private message to given nick to - nickname you want to send the PM to from - who's sending the message ? data - string to send SendToOps(from, data) - Sends data to main chat of all operators from - nick of sending user or bot or anything data - string to send Ex.: SendToOps("Banner", "User XX has been banned.") Shows in mainchat of every operator User XX has been banned. SendPmToOps(from, data) - Sends private message to all operators from specified nick from - nick of user or bot who's sending the PM data - string to send User-manipulating ----------------- GetItemByName(nick) - Returns user object of the nick nick - the nick of user. DisconnectByName(nick) - disconnects user by given nick nick - nick of user to disconnect AddRegUser(nick, pass, level) - adds new registered user or changes his password and profile if user is already registered nick - nick of user to be added to registered users list pass - password for the user level - a profile index ( obtained by function GetProfileIdx(profile_name) for example.) DelRegUser(nick) - deletes a given user from reg.users list nick - nick of the user function returns -1 if the user is not on the list or 1 on success Access to hub's properties ========================== By now you have access to these hub's settings via frmHub object's methods: frmHub:GetUsersCount() returns number of online users frmHub:GetHubName() returns string frmHub:SetHubName(string) string = hub name frmHub:GetHubDescr() returns string frmHub:SetHubDescr(string) string = hub description frmHub:GetRedirectAddress() returns string frmHub:SetRedirectAddress(string) string = hub address (IP or hostname) frmHub:GetRedirectAll() returns 0 or 1 frmHub:SetRedirectAll(number) number = 0 or 1 frmHub:GetRedirectFull() returns 0 or 1 frmHub:SetRedirectFull(number) number = 0 or 1 frmHub:GetRegServer() returns string frmHub:SetRegServer(string) string = address of the reg.server (currently only one address is allowed) frmHub:SetAutoRegister(number) number = 0 or 1 frmHub:GetMaxUsers() returns number of UserLimit frmHub:SetMaxUsers(number) number = 1 to 2000 frmHub:GetMinShare() returns the minshare in bytes frmHub:SetMinShare(amount, unit) amount = number unit = number (unit: 0=byte, 1=KByte,2=MByte, 3=GByte) sets the minshare frmHub:GetCurrentShareAmount() returns the total share of all users at the moment in bytes frmHub:GetOpChatName() returns the name of the OpChat-Bot frmHub:GetHubBotName() returns the name of the HubBot frmHub:EnableSearchData(n) n = 1 or 0 (1-enable,0-disable) enables/disables passing of $Search, $MultiSearch and $SR to current script frmHub:EnableFullData(n) n = 1 or 0 (1-enable,0-disable) enables/disables passing of ALL incomming data to current script NOTE: may have significant influence on hub's performance. Use it wisely! Bot (un)registering =============== Bot(s) name(s) can be registered via frmHub:RegBot(botname) usualy in the Main() function of the script. Bot(s) name(s) can be unregistered via frmHub:UnregBot(botname) Timers ====== By now every script has it's own timer. There are three global functions for timer control: SetTimer(time) time = time in miliseconds StartTimer() starts the timer StopTimer() stops the timer To respond on timer event write your response code into OnTimer function: function OnTimer() //TODO: your code here end Banlists manipulating ===================== Unban(what) - removes from permBan list given item what - ip or nick from banlist ClearTempBan() - clears all entries in PermBan list Working with profiles ===================== Profiles was first implemented in the 0.325 AshCan. After first start of the hub there are 4 default profiles Master - index 0, highest possible profile Operator - index 1 VIP - index 2 Reg - index 3 !!! IMPORTANT !!! Please note that in older versions of PtokaX index 0 was used for registered users and index 1 for operators. If you switch to version 0.325 or more then you HAVE TO edit your list of registered users and reassign desired profiles for them if you wont have your registered users as Masters ;) Now back to implementation. Every profile is stored in the file named profiles.dat and by default it looks like this: 0|Master|11111111111111111111000000000000 1|Operator|11111100011001111111000000000000 2|VIP|10000000000001111000000000000000 3|Reg|10000000000000000000000000000000 4|TestProfile|10000000011000000000000000000000 The format is simple and understandable on first sight. There are three fields divided by pipes | and means from left to right: - profile index - profile name - profile data pattern (PDP) Index and name are self-explanable. The profile data pattern (PDP) consist of 32 digits (1 or 0). Each digit correspondes to one right or permission from the profile manager. In fact the pattern is a binary representation of 32-bit number. The left-most digit is the Most Significant Bit (MSB), the right-most digit is the Least Significant Bit (LSB). List of permissions: Bit permission 31 - Enter full hub 30 - !drop 29 - kick 28 - !ban, !unban 27 - redirect 26 - !gag, !ungag 25 - !op 24 - !restarthub 23 - !restartscripts 22 - !getbanlist 21 - !getinfo 20 - !cleartempban 19 - no share limit 18 - no slot check 17 - no slot/hub check 16 - no maxhubs check 15 - no chatlimit 14 - !addreguser 13 - !delreguser 12 - reserved 11 - reserved 10 - reserved 09 - reserved 08 - reserved 07 - reserved 06 - reserved 05 - reserved 04 - reserved 03 - reserved 02 - reserved 01 - reserved 00 - reserved There is few functions for working with profiles: AddProfile(name, profile_data) ------------------------------ - this function adds new custom profile. name - string profile_data - number computed as a sum of values of individual bits. Value of a bit is a n-th power of 2. Ex.: to compute a profile that allows user to 'enter full hub' (bit 31), '!getbanlist' (bit 22) and 'no share limit' (bit 19) the formula is as follows profile_data = 2^31 + 2^22 + 2^19 result in decimal form is: 2152202240 result on binary form is: 10000000010010000000000000000000 Returns: -1 if the profile already exists or new profile index on success RemoveProfile(name) ------------------- - this function removes profile name - string Returns: 0 if the profile doesn't exists or it's a default profile idx 0-3 or no parameter given -1 if the profile is in use 1 on success GetProfileIdx(name) --------------------- - this function can be used to retrieve index of a profile. i.e. for the AddRegUser(nick, pass, profile_index) function name - string Returns: -1 if the profile name doesn't exist or profile index on success GetProfileName(idx) ------------------- - this function returns profile name of given index idx - number Returns: profile name as a string or nil if no profile of given index exists GetProfiles() ------------- - this function can be used to retrieve a list of all profile names Returns: numbered zero-based table of strings GetUsersByProfile(name) ----------------------- - this function can be used to retrieve a list of all users with given profile name - string Returns: numbered zero-based table of strings -Ptaczek- ===================================================================================== TODO: Make more hub's properties accessible from the script and more...