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:
========
23.06.2003 - added:
OnExit() optional function. If defined then it's called on Serving stop
but before
the server socket closes. Useful for storing current variables into
file or whatever.

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 called on Serving Stop but BEFORE the server socket closes.
function OnExit()
-- TODO your final 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 <Banner> 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...