Plugall Version 4.0.4 README
----------------------------

Plugall is a palace server plugin that controls certain actions taken
by members and guests. It also provides certain other facilities for
all users, member room owners, and wizards.  The specific actions,
limits, and facilities are controlled by a parameter file which is
loaded at startup and by the wizard command 'plugall reload.

Changes in Version 4.0.4
------------------------

Bug fixes
---------

* A bug which didn't limit changing ones avatar to the same avatar is
fixed.

* Fixed some crashes caused by changing a room's RoomID.  There remains
a lot of strange behavior which is because the server doesn't move the
users to the new RoomID.

* Treat TAB characters as whitespace in the configuration file and in
commands.

* A bug which caused a load error if there wasn't a blank line at the
end of the configuration file has been fixed.

* Apply face change limits to `setcolor and `setface.

* Make chatgoto strings not case sensitive.

* A bug that would cause the Linux plugin to select the wrong dupip
entry has been fixed.

* A bug where if `rpin was used on a user, and then `rkick, the user
would end up pinned in the upper left corner of the gate is fixed.


New Features
------------

* Log `chat, `dress, `gotoroom, `move, `naked, `setcolor, `setface,
`setpos, `signoff, and chatgoto when they are targeted to another user.

* Users who are pinned are not permitted to create member rooms.

* A new configuration parameter, "guestwiz" is added, so on guest =
member servers, guests can be prevented from gaining wizard status.


Installation
------------

The following installation instructions assume that the Palace server
has been installed in /usr/local/palace.

Plugall is a standard Palace server plugin.  It is installed by
placing the plugin file, plugall.so, in the palace binary folder,
/usr/local/palace/bin, and adding the following line to the plugin
configuration file, /usr/local/palace/<palace-name>/psdata/plugin.conf

../bin/plugall.so psdata/plugall.txt

The parameter file is placed in /usr/local/palace/<palace-name>/psdata.
Note that Plugall only reads this file.  Therefore, it can be edited
while the server is running and reloaded with a command to Plugall.


The Parameter File
------------------

Parameter file entries consist of a parameter-name, followed by a
variable number of parameters.  Parameter-names fall into two
categories: those which effect specific locations in the palace, and
those which have global effect.  There may be more than one entry for a
specific parameter-name, which permits different policies for different
rooms.

Sample parameter file:

-------------------------------------------------------------------
# Location limited parameters
# parameter  limit decay    where            warn
#
avatarchange    40     2    public altmember
avatarzone      22          rm86 warn
chat            10     1    public altmember
clearlooseprops  1          public altmember
facechange      10   0.5    public altmember
godonly                     rm101
gpage            1   0.2    all
mimick          10          public altmember warn
move            30   0.2    public altmember
namechange       1   0.1    all warn
newroom          1   0.1    all warn
nodupavatars                rm119 warn
page             1   0.2    all
pinx            256   22    rm94 rm123
propdrop        10     1    public altmember
repchat          0   0.0    public altmember warn
repchat          1   0.2    private member
reppage          0   0.0    all
roommsg          0   0.0    public altmember
roompage         1   0.2    all
rpage            1   0.2    all
slide           30   0.2    public altmember
spoof                       public altmember
spotstatechange 30   0.5    public altmember
take                        rm120
zone            12          public altmember
#
# Global Parameters
autoannounce 03:59:00 The server is going down for maintainence
chatgoto         86          gate
chatgoto         currentroom come here
dupip            5          192.168.0.*
dupip            0
gpagelength      20
gpageresponse If you don't get a response, try using `page instead.
guestwiz         no
memberrwho       yes
mroombg                     picture.gif
mroomdiscipline  25
pagelength       10
pageresponse If you don't get a response, please email owner@here.net
rownerinroom     yes
rtakedelay       120
wizinmemberrooms yes
-------------------------------------------------------------------

Most of the parameter-names entries use the format:

   <name> <limit> <decay> <where> <warn>

<limit> is the maximum number of events that a user can cause before
   limiting takes place.  (Note that each prop of an avatar counts as
   one event.)  The value 0 prevents the activity.

   Each user is initially seeded a pool of <limit> events.  This pool
   is decremented for each event.  When the pool drops below one, this
   activity is no longer permitted until the pool is recharged by the
   <decay> parameter.

<decay> is the number of events a user is credited for each
   second that passes without performing the activity.  It is a
   floating point value.  The smaller the value, the slower users
   recover from a burst of activity.

<where> is used on every location limited entry to specify where the
   parameter-name takes effect.  It is described in more detail below.

<warn> specifies that a user whose behavior is limited is to receive a
   warning message about the limit exceeded.  Each parameter-name has
   its own unique message, for example: "Repeated chat messages are
   limited here".  If warn is not specified, the user receives no
   message, but the action is still limited.

Other parameters are described with the detailed parameter-name descriptions.

The <where> parameter can be repeated multiple times in a single
parameter-name entry.  It specifies in which room(s) or types of rooms
the activity will be checked, and whether the user who is limited is
notified that the limit has been applied.  It may be any one or more of:

   all public private member altmember limbo off nowhere
   rmnn rmnn-mm warn

"all" specifies that the parameter effects every room in the palace.

"public" specifies that the parameter effects public rooms in the
palace.

"private" specifies that the parameter effects private rooms in the
palace.

"member" specifies that the parameter effects member created rooms in
the palace.

"altmember" specifies that the parameter effects member created rooms
where the owner has turned `rlimit on.

"limbo" specifies that the parameter effects users who are not in any
room in the palace.  (This state can occur during the logon process.)
"all" includes users who are in limbo.

"off" and "nowhere" specify that the parameter is not in effect
anywhere.

"rmnn" specifies that the parameter effects the specific room number nn.
For example, rm86 effects room 86.

"rmnn-mm" specifies that the parameter effects the specific room numbers
nn-mm inclusive.  For example, rm101-105 effects rooms 101, 102, 103,
104, and 105.

When a user message is received by the server, Plugall determines which
parameter-name(s) apply.  For each parameter-name which applies, Plugall
searches the parameter file for any entries associated with the current
room.  Parameter entries specifying a specific room, using the rmnn or
rmnn-mm forms, take precedence over the more general room-type form.  If
more than one entry applies, Plugall uses the first one.

The parameters and their function:

autoannounce hh:mm:ss <message>

"autoannounce" schedules <message> to be sent to all users on the server
at the local time specified.  When the message is sent, it will be
rescheduled to be sent again 24 hours later.  This logic does not
correct for changes in daylight savings time.  To correct for changes in
daylight savings time, the parameter file will need to be reloaded after
the server's local time has changed.

Note: To remove an autoannounce from the system, reload a parameter file
which does not include it (or has it commented out).

avatarchange <limit> <decay> <where> <warn>

"avatarchange" controls the maximum rate at which a user may change the
props worn as a avatar.  Note that each prop of an avatar counts as
one event.

avatarzone <size> <where> <warn>

"avatarzone" prevents users from moving within <size> pixels of each
other in the room.  Note that the server's choice of initial location
for a user entering the room is not constrained by this parameter.

chat <limit> <decay> <where> <warn>

"chat" controls the maximum rate at which chat messages will be
accepted by the server.  Chat is controlled regardless of whether it
is in the form of open chat, whispers, or room messages.  See also
repchat and roommsg.  Note that Plugall decides whether a chat message
is repeated before it applies a limit.  This means that repeated chat
may be permitted when non-repeated chat is limited.

chatgoto <roomNumber>|currentroom <string>

"chatgoto" specifies that any chat that exactly matches <string>
automatically sends the user to <roomNumber>.  If the user is a wizard
or god, and whispers the string to another user, that other user will be
sent to <roomNumber>.  If the string currentroom is used, the room
number is the location of the user.  (This last feature is most useful
when the <string> is whispered.)

clearlooseprops <people> <where> <warn>

"clearlooseprops" limits the use of the CLEARLOOSEPROPS function.  A
user may only clear loose props when fewer that <people> people are in
the room.  If there are scripts which clear the loose props when the
last person leaves the rooms, setting <people> to 1 will allow them to
run.  A member-room owner may clearlooseprops in their own room
regardless of the settings in this parameter.

dupip <count> [<ipAddress>]

"dupip" controls the number of users sharing an IP number who may be on
the server at one time.  If <count> is zero, then only one user per IP
address is permitted at a time.  <ipAddress> is specified as
nnn.nnn.nnn.nnn, where one or more of the nnn entries may be replaced
with an asterisk as a wildcard meaning all values match.  If more than
one dupip parameter matches a user's IP address, then the one with the
fewest wildcards is used.

facechange <limit> <decay> <where> <warn>

"facechange" controls the maximum rate at which a user may change the
face or color of a round-head.

guestwiz [yes|no]

"guestwiz" controls whether guests may become wizards on the server.
"yes" allows them to become wizards, and no prevents them from becoming
wizards.

godonly <where>

"godonly" limits access to rooms matching <where> to users with god
status.

gpage <limit> <decay> <where> <warn>

"gpage" limits the amount of god paging a user can do.  See also
page, and reppage.

gpagelength <length>

"gpagelength" forces all pages to gods to be at least <length> characters
long.

gpageresponse <message>

"gpageresponse" causes <message> to be sent to a user who sends a page
after the message, "The owners have been paged" is sent.

memberrwho [yes|no]

"memberwho" allows members and guests to get the name of the owner of a
room with the `rwho command.  Otherwise they are advised to send a message
using the `rpage command.

mimick <length> <where> <warn>

"mimick" controls the length of speech which may be immediately repeated
by other users in the room.  If chat is less than <length>, it may be
repeated.  If it is longer, then it will be suppressed.

move <limit> <decay> <where> <warn>

"move" controls the maximum rate at which a user can move around a room.
It acts as a control on "bouncing around the room".  See also slide.

mroombg [off|<pictureName>]

"mroombg" sets <pictureName> as the default background picture for
member created rooms.  "off" disables this feature.  Note that is
feature is implemented by generating a `rpicture command for the user,
so the fixed default picture clouds.gif will display briefly first.  It
is recommended that the server use a clouds.gif which is a neutral grey
or black picture to minimize the flashing effect this implementation
causes.  Note that the message. 'Room picture is "<pictureName>"' will
display for the owner.

mroomdiscipline [<number>|off]

"mroomdiscipline" control how many disciplined users the `rkick `rpin,
`rgag, and `rpropgag commands remember.  If it is set to off, the `rpin,
`runpin, `rgag, `rungag, `rpropgag, and `runpropgag commands are not
available, and 20 users who have been the subject of `rkick are
remembered.

namechange <limit> <decay> <where> <warn>

"namechange" limits the rate at which a user's screen name can change.
It is probably most useful to specify <where> as all.

newroom <limit> <decay> <where> <warn>

"newroom" controls the maximum rate at which a user can create new
rooms.

nodupavatars <where> <warn>

"nodupavatars" prevents two people in the same room from wearing exactly
the same props.

page <limit> <decay> <where> <warn>

"page" limits the amount of wizard paging a user can do.  See also gpage,
and reppage.

pagelength <length>

"pagelength" forces all pages to be at least <length> characters long.

pageresponse <message>

"pageresponse" causes <message> to be sent to a user who sends a page
after the standard server message, "The operators have been paged" is
sent.

pinx <x> <y> <where>

"pinx" sets up an alternative pin location for the room.  See the
`pinx command wizard command.

propdrop <limit> <decay> <where> <warn>

"propdrop" controls the maximum rate at which props can be dropped in
a room.  Note that dropping an avatar may involve dropping up to
nine props.  Also note that "zone" also controls prop dropping.

repchat <limit> <decay> <where> <warn>

"repchat" controls the maximum rate at which chat messages which
repeat the last chat from that user will be accepted by the server.
Repeated chat is controlled regardless of whether it is in the form
of open chat, whispers, or room messages.  See also chat and roommsg

reppage <limit> <decay> <where> <warn>

"reppage" controls the maximum rate at which the server will accept a
single repeated page to the wizards from a user.  See also gpage and reppage.

roommsg <limit> <decay> <where> <warn>

"roommsg" controls the maximum rate at which room messages may be issued
in a room.  A <limit> of 0 forbids ROOMMSG.

rownerinroom [yes|no]

"rownerinroom" set to yes forces the new owner of a member room to be in
the room when the `rowner command is issued.  If the new owner is not in
the room, the current owner will get the message, "The new owner must be
in the member room", when the command is issued.

rpage <limit> <decay> <where> <warn>

"rpage" controls the maximum rate at which pages may be issued to owners
of a user created room.  A <limit> of 0 forbids RPAGE.

rtakedelay <seconds>

"rtakedelay" sets the number of seconds before the `rtake command will
allow any user to take ownership of a member room whose owner has been
disconnected.

setrank <commandName> <userLevel> [<targetLevel>]

"setrank" lets you change the privilege level required to issue plugall
commands.  The command to be changed is <commandName>.  The levels are
either names (guest, member, wizard, operator, god, owner) or numbers
from 0 to 3 (0=guest, 1=member, 2=wizard, and 3=god).  In addition, a
value of disable will disable use of the command.  Every command has a
<userLevel> which is the level required to issue the command.  In
ddition, the commands that can be targeted so they effect other users
have a <targetLevel>.  The <targetLevel> is normally greater than or
equal to the <userLevel>.

slide <limit> <decay> <where> <warn>

"slide" controls the maximum rate at which a user can slide around a
room.  It acts as a control on "gliding".  A slide is any single
motion of 4 pixels or less.  More than 4 pixels is a move.

spoof <where> <warn>

"spoof" controls where users can use the @x,y form of chat.

spotstatechange <limit> <decay> <where> <warn>

"spotstatechange" controls the maximum rate at which a user can change
the state of a spot or door in a room.  Note that this limit does not
affect the SETSPOTSTATELOCAL Iptscrae command.

take <where>

"take" controls which rooms are "take avatar" rooms.  In those rooms,
the `take command allows one user to take and wear another's avatar.  If
a room is a take avatar room, all users will be warned when entering it.

wizinmemberrooms [yes|no]

"wizinmemberrooms" controls whether wizards may enter closed member
rooms and member rooms with a password. (In the default server, only
gods may enter such rooms.)  Note that a server "feature" may cause the
message, "Sorry, the room is closed." to display for the wizard even
though entry has been permitted.  If wizinmemberrooms is enabled, all
users will receive the message, "NOTE: Wizards may enter closed and
passworded member rooms on this server."

zone <area> <where> <warn>

"zone" specifies that duplicate props are forbidden within <area> pixels
of each other.  It controls users who drop the same prop many times
in one place in a room.  (It also controls moving of props.)


Commands
--------

In addition to the controls provided by use of the parameter file,
Plugall adds the following user commands to the palace server.

`chat <message>
default rank: wizard

`chat allows one user to generate chat for another user.  Note that chat
can include server commands.  It must be whispered to the other user.

`clean
default rank: wizard

`clean clears all loose props and painting in the room.

`dress
default rank: wizard

`dress allows one user to dress another user in the first user's current
avatar.

`find [<target>]
default rank: guest

`find displays in which room the target user is located.

`gmsg <message>
default rank: wizard

`gmsg sends <message> to everyone on the server.

`goto [<target>]
default rank: guest

`goto allows the user to go to the target user's room.

'gotoroom <roomID>
default rank: guest, wizard if targeted

`gotoroom allows the user to go to a room by room number.  The standard
room entry permission checks are performed before allowing the room change.

`gpage <message>
default rank: guest

`gpage sends a messages to all the gods who are on the server.

`killx [<comment>]
default rank: wizard

`killx acts as a macro combining `kill, `banip, and `comment into one
command.  It must be whispered.  If <comment> is omitted, the `comment
command will not be issued.

`listgag [<target>]
default rank: wizard

`listgag prevents the target user from requesting a list of either rooms
or users.  This command does not effect any lists the target user
currently has.

`move <h> <v>
default rank: wizard, wizard if targeted

`move moves the target user a signed number of pixels in the horizontal
(<h>) and vertical (<v>) directions.

`myroom
default rank: member

`myroom allows a room owner to go to that owned room.

`naked [<target>]
default rank: guest, wizard if targeted

`naked removes all props the targeted user is wearing.  If no target
is specified, it removes all the user's props.

`namegag [<newname>]
default rank: wizard

`namegag prevents the user from changing screen names.  It must be
whispered.  If <newname> is specified, the user will be forced to wear
<newname> as a screen name.

`nolooseprops [on|off]
default rank: wizard

`nolooseprops controls whether loose props may be dropped in the room.
It does not effect any loose props already in the room.  Note that the
nolooseprops setting also effects wizards and gods.

`pagegag [<screename>]
default rank: wizard

`pagegag prevents the user from paging wizards.  It may be whispered or
the target user may be named.

`pdel
default rank: wizard

`pdel clears the loose props in a room.  It does not affect any painting
that may be present.

`pinx [<screename>]
default rank: wizard

`pinx pins the user in a location specified in the parameter file.  If
no entry in the parameter file matches the current room, it defaults to
a `pin.  It may be whispered or the target user may be named.  `pinx is
undone by a `unpin command.  Note that the `pin command will use the
standard location, allowing two user to be pinned in separate locations.

`plugall reload
default rank: wizard

`plugall reload causes the parameter file to be read updating the
control parameters.

`propfreeze [on|off]
default rank: wizard

`propfreeze on prevents loose props in the current room from being moved
or removed.  `propfreeze off resets this behavior.

`rannounce <message>
default rank: wizard and room owner

`rannounce sends <message> to everyone in the current (member created)
room.

`rbanlist
default rank: wizard and room owner

`rbanlist lists the people currently rkicked, rgagged, rpinned, or
rpropgagged in the room.

`reset
default rank: guest

`reset resets the user's client to match the server's record of the
client state.  The face, color, props, room location, and screen name
are reset.

`rgag [<screename>]
default rank: wizard and room owner

`rgag prevents the user from chatting or whispering in the room.  It may
be whispered or the target user may be named.  When the user leaves the
room, the gag is suspended until the user reenters the room.  Note that
wizards and the room owner not affected by this command.  See the
MROOMDISCIPLINE parameter.

`rkick [<user>]
default rank: wizard and room owner

`rkick kicks the target user out of the current (member created) room.

`rlimit [on|off]
default rank: wizard and room owner

`rlimit on makes a member room subject to the ALTMEMBER parameters from
the parameter file.  If `rlimit is entered without a parameter, the
current setting is displayed.

`rlockdown
default rank: wizard and room owner

`rlockdown on acts as a macro combining `rscripts off, `rpaint off, and
`rlimit on.

`rmsg <message>
default rank: wizard

`rmsg sends <message> to everyone in the current room.

`rnodupavatars [on|off]
default rank: wizard and room owner

`rnodupavatars on prevents two user from wearing the same avatar in the
room.  If `rnodupavatars is entered without a parameter, the current
setting is displayed.  Note that wizards and the room owner are not
affected by this command.

`rnolooseprops [on|off]
default rank: wizard and room owner

`rnolooseprops allows member room owners to prevent loose props from
being dropped in their rooms.  If `rnolooseprops is entered without a
parameter, the current setting is displayed.  Note that wizards and the
room owner are not affected by this command.

`roompage <message>
default rank: guest

`roompage sends a message to all the wizards and gods in the current
room.

`roomprefs
default rank: wizard

`roomprefs shows certain information about the current room.  The
room's name, ID, the last painter's user number, the maximum occupancy
(or zero for not specially limited), the number of painting commands,
the number of users, the number of hot spots or doors, the number of
pictures, and the number of loose props are shown.

`roperatorsonly [on|off]
default rank: wizard and room owner

`roperatorsonly controls whether members and guests are permitted in
the current (member created) room.  Note that setting `roperatorsonly
on will not remove guests or members already in the room.

`rpage <message>
default rank: guest

`rpage allows anyone in a member room to send a message to that room's
owner.  The owner may use the `respond command to send a response.

`rpin [<screename>]
default rank: wizard and room owner

'rpin pins the target user while in the member room.  It may be
whispered or the target user may be named.  When pinned, the user is
kept in the lower right corner of the room and forced to wear the chains
prop (number 1280).  When the user leaves the room, the pin is suspended
until the user reenters the room.  Note that wizards and the room owner
are not affected by this command.  See the MROOMDISCIPLINE parameter.

`rpropfreeze [on|off]
default rank: wizard and room owner

`rpropfreeze on freezes all loose props in the room.  Other users can't
move or delete them.  (Other users may copy them.)  If `rpropfreeze is
entered without a parameter, the current setting is displayed.  Along
with `rnolooseprops, this command gives the room owner control of loose
props in the room.  Note that wizards and the room owner are not
affected by this command.

`rpropgag [<screename>]
default rank: wizard and room owner

`rpropgag prevents a user from wearing props in the room.  It may be
whispered or the target user may be named.  The user may again wear
props after leaving the room, until reentering the room.  Note that
wizards and the room owner not affected by this command.  See the
MROOMDISCIPLINE parameter.

`rtake
default rank: member

`rtake allows anyone to take ownership of a member room after the owner
has been disconnected for RTAKEDELAY.  See the RTAKEDELAY parameter.

`rungag [<screename>]
default rank: wizard and room owner

`rungag undoes the effect of a `rgag command.  It may be whispered or
the target user may be named.  See the MROOMDISCIPLINE parameter.

`runkick [<screename>]
default rank: wizard and room owner

`runkick undoes the effect of a `rkick command.  It may be whispered or
the target user name be names.  See the MROOMDISCIPLINE parameter.

`runpin [<screename>]
default rank: wizard and room owner

`runpin undoes the effect of a `rpin command.  It may be whispered or
the target user may be named.  See the MROOMDISCIPLINE parameter.

`runpropgag [<screename>]
default rank: wizard and room owner

`runpropgag undoes the effect of a `rpropgag command.  It may be
whispered or the target user may be named.  See the MROOMDISCIPLINE
parameter.

`rwho
default rank: guest

`rwho enquires about the room's owner.  If the owner is not on the
server, it will note that fact and recommend the`rtake command to gain
ownership.  If the user is a wizard or god, or if MEMBERRWHO is yes,
it will respond with the name of the room's owner.  If the user is a
guest or member, it will say that the room has an owner an recommend
the `rpage command as a way of contacting that owner.

`setcolor <colorNumber>
default rank: guest

`setcolor sets the color of the user's avatar to <colorNumber>.
<colorNumber> may range from 0 to 15

`setface <faceNumber>
default rank: guest

`setface sets the face of the user's avatar to <faceNumber>.
<colorNumber> may range from 0 to 12

`setpos <h> <v>
default rank: wizard, wizard if targeted

`setpos moves the target user to the location specified by the horizontal
(<h>) and vertical (<v>) parameters.

`signoff [<screename>]
default rank: guest, wizard if targeted

`signoff disconnects the target user from the server.

`take [<screename>]
default rank: guest

`take copies the target user's avatar on to the user issuing the `take
command.  See the TAKE parameter.

`unlistgag [<screename>]
default rank: wizard

`unlistgag undoes the effects of a `listgag.  It may be whispered or the
target user may be named.

`unnamegag [<screename>]
default rank: wizard

`unnamegag undoes the effects of a `namegag.  It may be whispered or the
target user may be named.

`unpagegag [<screename>]
default rank: wizard

`unpagegag undoes the effects of a `pagegag.  It may be whispered or the
target user may be named.

`userprefs [<screename>]
default rank: wizard

`userprefs shows certain information about the target user.  The user's
Signon Time, Last Active time, Desired Room at login, Screen Name,
UserID number, Color number, Face number, Number of Authorization
Attempts, Number of Failed Password Attempts, Number of Flood Events,
Number of Props, Position in the Room, and PUID are shown.


Additional Features
-------------------

Plugall also corrects several long-standing problems with the palace
server.

The `respond command has been extended to work when the last private
message came from a user in the same room as the user entering the
command.

People receiving a member room with a `rowner command are checked to
see if they already own another room before allowing the command.
If the receiver already owns a room, the command is suppressed.

Null carriage return, *, leading blank, leading apostrophe, leading
hyphen, trailing blank, and multiple blank characters are not allowed in
member names.  Blocking the null and carriage return prevents wizards
from getting the user not found error when trying to pin, gag, list,
etc.  Blocking the leading apostrophe and hyphen allows PC using wizards
to use the mouse commands without getting, "User not found".

A long standing server bug which prevents member room owners who
disconnect from regaining ownership when they log back on is patched by
the plugin.

Users who have been kicked out of a member room with `rkick remain
kicked even after disconnecting and reconnecting.  The new `rpin, `rgag,
and `rpropgag commands also remember their state over a disconnect and
reconnect.

Note: One of the ways users are identified is by IP address.  This last
feature can produce surprizing results when two or more users share an
IP address, because they will be identified as the same user.


Notes:
------

Gods and Wizards are exempt from all limits except the check for already
owning a room when processing 'rowner.

If you have any questions you can email me at joe@avatarpalace.net

This plugin is free for public use. If you would like to make donations
please go to: http://www.avatarpalace.net/donate/

