Big Brother Bot (B3)

Big Brother is the nominal leader of Oceania in Nineteen Eighty-Four, George Orwell's chilling dystopic novel. The name is now used to mean surveillance in general, usually by a government.

Quoted from Wikipedia

B3's primary purpose is to facilitate surveillance of games servers so Big Brother seemed like an obvious choice. Thanks to kNox.

Big Brother Bot is watching you!

This document is far from complete. It is a first stab at documenting the massive B3 project for system administrators, moderators, and users.

Changelog

B3 IP Key License - You only need one per IP, not IP/port combination.
Python 2.3
MySQL-python Tested with 0.9.2 and 1.0
MySQL Tested with 3.23

I assume you know how to use/install python, MySQL, and your operating system. If not you should consult the documentation for these if you have problems or questions on how to administer each.

Download the package
Extract the package to a suitable location, example: /usr/local/games/b3

DO NOT extract b3lib.zip unless you want to break everything.

To setup MySQL you can use the default b3 SQL scripts.

Create a user that has full permissions on this database for B3:

Download B3 database/user SQL and save to a file. Open the file in a text editor and change <password> to the password you want to use with B3. Execute the command below. Make sure you are in the directory that you saved the .sql script to. You may need to enter your MySQL password. If you do not have a password, remove "-p <mysql password>" from the command below.

Execute:

mysql -u root -p <mysql password> < b3-db.sql

Create the B3 tables:

Download B3 table SQL and save to a file. Execute the command below. Make sure you are in the directory that you saved the .sql script to. You may need to enter your MySQL password. If you do not have a password, remove "-p <mysql password>" from the command below.

Execute:

mysql -u root -p <mysql password> < b3.sql

Your B3 database should be configured and ready to go.

Linux

cd /usr/local/games/b3 
chmod 755 *.sh

PYTHON="/usr/local/bin/python2.3"

cd /usr/local/games/b3 
./b3.sh > /dev/null &

Windows

C:\Python23\python.exe "b3_run.py"

./b3.lnk you can just double click the b3 shortcut

All Systems

tail -n100 -f b3.log

b3.cfg

1 = welcome_newb
2 = welcome_announce_user
4 = welcome_first
8 = welcome_announce_first
16 = welcome_user
add numbers, example 31 = all

[plugins]
; Default plugins
1.censor = conf/plugin_censor.cfg
2.spamcontrol = conf/plugin_spamcontrol.cfg
3.admin = conf/plugin_admin.cfg
4.tk = conf/plugin_tk.cfg
5.stats = conf/plugin_stats.cfg
6.pingwatch = conf/plugin_pingwatch.cfg
7.adv = conf/plugin_adv.cfg
8.status = conf/plugin_status.cfg

%(name)s = player name
%(id)s = player id
%(lastVisit)s = last visit time (only on welcome_user and welcome_newb)
%(group)s = players group (only on welcome_user)
%(connections)s = number of times a user has connected (only on welcome_user and welcome_announce_user)

Admin Plugin Configuration

[commands]
iamgod = none

enable = 100
disable = 100
die = 100
reconfig = 100
restart = 100
mask = 100
unmask = 100

cmdlevel = 90
pause = 90
rebuild = 90
ungroup = 90
delgroup = 90
putgroup = 90
clientinfo = 90
editgroup = 90
groups = 90
newgroup = 90

permban-pb = 80
map = 80
maprotate = 80
warnclear-wc = 80
clear-kiss = 80
lookup-l = 80
makereg-mr = 80
spankall-sall = 80
banall-ball = 80
kickall-kall = 80

ban-b = 60
unban = 60
spank-sp = 60

tempban-tb = 40
aliases-alias = 40
baninfo-bi = 40
find = 40
kick-k = 40
admintest = 40
scream = 40

warns = 20
warninfo-wi = 20
warnremove-wr = 20
warn-w = 20
warntest-wt = 20
spams = 20
spam-s = 20
list = 20
admins = 20
say = 20
status = 20
leveltest-lt = 20

b3 = 9
greeting = 9

seen = 2
maps = 2
nextmap = 2

regtest = 1
time = 1

help-h = 0
register = 0-0
rules-r = 0

[spamages]
rule1 = ^3Rule #1: No racism of any kind 
rule2 = ^3Rule #2: No clan stacking, members must split evenly between the teams 
rule3 = ^3Rule #3: No arguing with admins (listen and learn or leave) 
rule4 = ^3Rule #4: No abusive language or behavior towards admins or other players 
rule5 = ^3Rule #5: No offensive or potentially offensive names, annoying names, or in-game (double caret (^)) color in names 
rule6 = ^3Rule #6: No recruiting for your clan, your server, or anything else
rule7 = ^3Rule #7: No advertising or spamming of websites or servers 
rule8 = ^3Rule #8: No profanity or offensive language (in any language) 
rule9 = ^3Rule #9: Do ^1NOT ^3fire at teammates or within 10 seconds of spawning 
rule10 = ^3Rule #10: Offense players must play for the objective and support their team

[messages]
ban_denied = ^7Hey %s^7, you're no Elvis, can't ban %s
help_available = ^7Available commands: %s
greeting_yours = ^7Your greeting is %s
temp_ban_self = ^7%s ^7Can't ban yourself newb
groups_in = ^7%s^7 is in groups %s
greeting_bad = ^7Greeting is not formated properly: %s
say = ^7%s^7: %s
player_id = ^7[^2%s^7] %s^7
seen = ^7%s ^7was last seen on %s
help_no_command = ^7Command not found %s
lookup_found = ^7[^2@%s^7] %s^7 (^3%s^7)
kick_self = ^7%s ^7Can't kick yourself newb!
groups_welcome = ^7You are now a %s
greeting_changed = ^7Greeting changed to: %s
greeting_cleared = ^7Greeting cleared
warn_denied = %s^7, %s^7 owns you, can't warn
groups_already_in = ^7%s^7 is already in group %s
temp_ban_denied = ^7Hey %s^7, you're no ^1Red ^7Elvis, can't temp ban %s
players_matched = ^7Players matching %s %s
ban_self = ^7%s ^7Can't ban yourself newb!
regme_annouce = ^7%s ^7put in group %s
kick_denied = ^7%s^7 gets 1 point, %s^7 gets none, %s^7 wins, can't kick
no_players = ^7No players found matching %s
spanked_reason = %s ^7was ^1SPANKED^7 by %s ^7for %s
groups_added = ^7%s ^7added to group %s
groups_put = ^7%s ^7put in group %s
groups_none = ^7%s^7 is not in any groups
help_command = ^2%s%s ^7%s
greeting_empty = ^7Your have no greeting set
warn_self = ^7%s ^7Can't warn yourself newb!
regme_regged = ^7You are now a %s
help_none = ^7You have no available commands
greeting = ^7%s^7 joined: %s
spanked = %s ^7was ^1SPANKED^7 by %s
admins = ^7Admins online: %s
time = At the sound of the beep it will be ^3%s^7...(beeeep)
unknown_command = ^7Unrecognized command %s
leveltest = ^7%s ^7(^3@%s^7) is a ^3%s ^7[^2%s^7] since %s
leveltest_nogroups = ^7%s ^7(^3@%s^7) is not in any groups
aliases = ^7%s^7 aliases: %s
warn_kick_alert = ^1ALERT^7: %(name)s^7 auto-kick from warnings if not cleared (^3%(warnings)s^7)
warn_ban_alert = ^1ALERT^7: %(name)s^7 auto-ban from warnings if not cleared (^3%(warnings)s^7)

; color = warning keyword
; 1h = 1 hour active duration
; A warning for in-game color
color = 1h, ^7No in-game (double caret (^)) color in names

; language is an exact copy of the rule8 warning
language = /rule8 

; rule1 = warning keyword
; 10d = 10 day active duration
; This warning referres to rule1 from spamages
rule1 = 10d, /spam#rule1

[warn_reasons] 
generic = 1h, ^7 
default = 1h, ^7behave yourself 

rule1 = 10d, /spam#rule1 
rule2 = 1d, /spam#rule2 
rule3 = 1d, /spam#rule3 
rule4 = 1d, /spam#rule4 
rule5 = 1h, /spam#rule5 
rule6 = 1d, /spam#rule6 
rule7 = 1d, /spam#rule7 
rule8 = 3d, /spam#rule8 
rule9 = 3h, /spam#rule9 
rule10 = 3d, /spam#rule10 

stack = 1d, /spam#stack 

lang = /rule8 
language = /rule8 
cuss = /rule8 
profanity = /rule8 

name = /rule5 
color = 1h, ^7No in-game (double caret (^)) color in names
badname = 1h, ^7No offensive, potentially offensive, or annoying names
spec = /spectator 


adv = /rule7 
racism = /rule1 
stack = /rule2 
recruit = /rule6 
argue = /rule3 
sfire = /rule9 
spawnfire = /rule9 
jerk = /rule4 

afk = 5m, ^7you appear to be away from your keyboard 
tk = 1d, ^7stop team killing! 
obj = 1h, ^7go for the objective! 
camp = 1h, ^7stop camping or you will be kicked! 
fakecmd = 1h, ^7do not use fake commands 
nocmd = 1h, ^7do not use commands that you do not have access to, try using !help 
ci = 5m, ^7connection interupted, reconnect 
spectator = 5m, ^7spectator too long on full server 
spam = 1h, ^7do not spam, shut-up!

; The following warnings are used by B3 and must be defined
generic - used as a prefix to custom warnings
default -  used as the default when no reason is given for the warning
spam - displayed when a user spams too much
sfire - spawn fire
badname - user name on bad names list
cuss - user said something on the bad words list
nocmd - using commands with out access
fakecmd - using commands that do not exist

TK Plugin Configuration

[level_0]
kill_multiplier = 2
damage_multiplier = 1
ban_length = 2

[level_1]
kill_multiplier = 2
damage_multiplier = 1
ban_length = 2

[level_2]
kill_multiplier = 1
damage_multiplier = 0.5
ban_length = 1

[level_20]
kill_multiplier = 1
damage_multiplier = 0.5
ban_length = 0

[level_40]
kill_multiplier = 0.75
damage_multiplier = 0.5
ban_length = 0

Status Plugin Configuration

Plugins developed for B3 usually consist of two files, a ".py" python file and a ".cfg" configuration file. The python file belongs in the b3/plugins directory and the config file belongs in the b3/conf directory.

For example, a plugin called "Example Plugin" should have files called "example.py" and "plugin_example.cfg". Place example.py in b3/plugins and plugin_example.cfg in b3/conf.

If the plugins directory does not exist under the b3 directory, you must create it. You also must make an empty file called "__init__.py" and place it in the plugins directory.

A key feature of the B3 Bot is it's ability to monitor a players behaviour and create a patten of development while on a server with B3. Should a player consistantly break rules, however minor, this patten of behaviour can be logged and presented to the player for bahavior modification, or justifcation for not allowing said player to return back to the server. Tracking the type or warn, kick and temp ban can allow the admin a greater understanding of the player and his/her behaviours. For example, a player with a lot of warns for being afk is not a threat to the community, but will inpead the game. The admin now knows to watch for this player while in game for afk status. On the other hand a player with consistant warns for bad language will allow an admin to dish out a more sevear form of discipline, such as a tempban or a kick. should negative behaviour continue.

The tiered system of the B3, allows for a better relationship between admins and players, while still creating a sense of discipline and seniority. The Tiered system also allows the player to choose to become a part of the community/server. by typing !register the player has become a member of the community, the next level can only be given out by senior admins. This automatically creates a relationship between player and admin, and rewards the player with more commands. The player will then wish to stay with the server community longer, to play by the rules and to socialize with the community to gain recognition.

B3's permissions are based on groups and levels. Users are assigned to groups and each group has a level. Commands can be ran by users that have the minimum level needed to use the command. Upper level user roles are assigned by Super Admins with the !putgroup command using the keywords below.

B3 has several default user groups, each serving a different purpose. You can add, edit, or remove user groups but each of the levels below server meaningful purposes in B3. If you change groups, you should at least maintain a level 100, 2, and 1 user.

Super Admin

Senior Admins

Full Admins

Admins

Moderators

Regulars

Users

Command Reference
Plugin Configuration

The command interface is provided by B3's admin plugin. B3 is meant to make administration easy. In fact, most everyday RCON commands are built in including !kick, !ban, !maprotate, player !list, !map, and more.

Commands that take a player as input can use three types of sources: a partial name, game client id, or B3 "@ID", see Player Identification for more details.

Warnings

!warn PlayerName camping

WARNING (1): PlayerName we do not allow camping on this server

!warn PlayerName exploit

WARNING (2): PlayerName using map exploits are not allowed here

# 1 day total warnings
86400 / 30 = 2880 seconds = 48 minute temp-ban
# 1 hour total warnings
3600 / 30 = 120 seconds = 2 minute temp-ban
# 5 minutes total warnings
300 / 30 = 10 second temp-ban

3 - 1d warnigns = 2.4 hour temp-ban
3 - 1h warnings = 6 minute temp-ban
3 - 5m warnings = 30 second temp-ban

Spammages

!spam website

Visit our website at www.bigbrotherbot.com

Command Reference
Plugin Configuration

Whenever a user kills/bleeds a teammate they will be issued TK points. At a certain number a repramand will automatically be issued. Should the team damage be an accident, the user that was offended can !forgive the offending user, thus clearing him of TK points. Should the team damage be intentional, a simple !grudge command will stop the offending user from being forgiven in future, thus speeding up the repramand process.

For a complete description of commands see the TK Plugin Commands.

The censor plugin will monitor chat messages for banned words. Whenever a player speaks a banned word he will be warned automatically. B3 has been pre-programmed with a list of profanities in many languages. You can modify the badwords.txt to fit your needs.

The spam control plugin automatically dectects a player spaming messages, commands, binds, or voice commands and warns them. It weighs spam considering color messages, repeat messages, and voice commands more spam-like.

The Ping Watch Plugin will monitor player pings and alert players when a players ping is too high or 999 connection interupted

The Adv Plugin will rotate through ads and display them and regular intervals. Great for displaying your server's website or rules.

Plugin Configuration

The Status Plugin will output an XML file with player information and server settings periodically.

Command Reference

The stats plugin currently provides stats for the current map. It awards points based on skill. To view stats a user can use the !mapstats command.

Future versions of B3 will have persistant stats that keep track of player statistics forever.

Even though Big Brother Bot was designed to give complete control of your server, you may have a need unique to your situation, or an idea that may not have been considered. Great news! B3 was also designed with this in mind. Each feature of B3 is actually a plugin module independent of each other. What this means is you can create a plugin for your individual needs, or something that you think the community could use. With a little scripting, the possibilities are almost endless.

www.bigbrotherbot.com will also create custom plugins for you for a fee.

Commands that deal with time duration like !tempban can use time suffixes.

m = minutes
d = days
h = hours
w = weeks

Example:

1d = 1 day
3h = 3 hours

Commands that accept player designations can use several inputs.

Partial Name

!warn playe cuss

Client ID

!kick 3 tk

Database ID

!makereg @1235

Commands can be hidden from other players if you meet the hidecmd_level. To run a command privately you can use the private messaging built into most games.

Call Of Duty Example:
First you must figure out your client ID. You can use !list or !find.

!find MyName

If found it should display your name and client ID, for example 12. Once you have your client ID you can use the "/tell" command built into CoD. You must type the message in console.

/tell 12 !mask reg MyName

If you meet the minimum level for Private commands B3 will execute your command. You may see your /tell message displayed twice, this is normal.

!register

!help

!regtest

!time

!maps

!nextmap

!seen

!admins

!b3

!greeting

!list

!say

!spam

!spams

!warn

!warninfo

!warnremove

!warns

!warntest

!admintest

!aliases

!baninfo

!find

!kick

!leveltest

!scream

!tempban

!ban

!spank

!pbss

!permban

!clear

!lookup

!makereg

!map

!restart

!warnclear

!clientinfo

!cmdlevel

!delgroup

!editgroup

!groups

!newgroup

!pause

!putgroup

!rebuild

!ungroup

!die

!disable

!enable

!reconfig

!mask

!unmask

!runas

!forgive

!forgiveall

!forgiveprev

!forgivelist

!grudge

!forgiveinfo

!forgiveclear

!mapstats

!testscore

For plugin database usage, the best way to connect is to use b3's connection handling. Not only will this ensure you only have one client connected to your database, but b3's connection handler will reconnect in the event the servers connection is interrupted. B3 uses ADODB for Python.

Example:

cursor = self.console.storage.query(sqlQuery)

if cursor:
    # Query successful, cursor is a adodb.ADOCursor

    print '%s Records' % cursor.RecordCount()

    while not cursor.EOF:
        # cursor.GetRowAssoc(0) returns a dictionary with all keys lowercase
        record = cursor.GetRowAssoc(0)

        # do whatever with record here

        cursor.MoveNext()

else:
    # Connection failed, handle gracefuly
    # The database may be temporarily unreachable, 
    # do something intelligent in the mean time.
    # For example, the admins plugin will check
    # a local cache of top admins incase admining
    # is need while the server is down

Here is a rough example of a plugin. It covers some of the basic functions of a plugin with some rather useless commands.

Config file

; b3/conf/plugin_example.cfg
[settings]
min_level = 20

[messages]
hello = ^1Hi %s
count = ^2Count for %s: ^7%s

Plugin:

# b3/plugins/example.py
# all plugins must import b3 and b3.events
import b3
import b3.events

#--------------------------------------------------------------------------------------------------
class ExamplePlugin(b3.Plugin):
	_adminPlugin = None
	_minLevel = None

	def startup(self):
		"""\
		Initialize plugin settings
		"""

		# get the plugin so we can register commands
		self._adminPlugin = self.console.getPlugin('admin')
		if not self._adminPlugin:
			# something is wrong, can't start without admin plugin
			self.error('Could not find admin plugin')
			return False
		
		# get the minium level allowed to use this plugin
		self.verbose('Getting config options')
		self._minLevel = self.config.getint('settings', 'min_level')

		# register our !echo command
		self.verbose('Registering commands')
		self._adminPlugin.registerCommand(self, 'echo', self._minLevel, self.cmd_echo, 'e')
		self._adminPlugin.registerCommand(self, 'shout', self._minLevel, self.cmd_shout)
		self._adminPlugin.registerCommand(self, 'sayto', self._minLevel, self.cmd_sayto)
		self._adminPlugin.registerCommand(self, 'hello', self._minLevel, self.cmd_hello)
		self._adminPlugin.registerCommand(self, 'count', self._minLevel, self.cmd_count)

		# listen for client say events
		self.verbose('Registering events')
		self.registerEvent(b3.events.EVT_CLIENT_SAY)
		self.registerEvent(b3.events.EVT_CLIENT_TEAM_SAY)

		self.debug('Started')

	def handle(self, event):
		"""\
		Handle intercepted events
		"""

		if event.type == b3.events.EVT_CLIENT_SAY:
			self.debug('Client %s said: %s', event.client.name, event.data)
		elif event.type == b3.events.EVT_CLIENT_TEAM_SAY:
			self.debug('Client %s said to team %s: %s', event.client.name, event.client.team, event.data)

	def cmd_echo(self, data, client, cmd=None):
		"""\
		<message> - repeat a message
		"""

		self.verbose('Client %s echos "%s"', client.name, data)

		if not len(data):
			client.message('^7You must supply a message to echo')
			return False

		# if the user used the ! prefix the message will be private
		# if the user used the @ prefix the message will be public
		cmd.sayLoudOrPM(client, data)

	def cmd_shout(self, data, client, cmd=None):
		"""\
		<message> - shout a message to all users
		"""

		self.verbose('Client %s shouts "%s"', client.name, data)

		if not len(data):
			client.message('^7You must supply a message to shout')
			return False

		self.console.say('^7%s' % data.upper())

	def cmd_sayto(self, data, client, cmd=None):
		"""\
		<player> <message> - send a message to a user
		"""

		# this will split the player name and the message
		input = self._adminPlugin.parseUserCmd(data)
		if input:
			# input[0] is the player id
			sclient = self._adminPlugin.findClientPrompt(input[0], client)
			if not sclient:
				# a player matchin the name was not found, a list of closest matches will be displayed
				# we can exit here and the user will retry with a more specific player
				return False
		else:
			event.client('^7Invalid data, try !help sayto')
			return False

		if not len(input[1]):
			client.message('^7You must supply a message to sayto')
			return False

		# private message the player the message
		sclient.message('^7%s ^3says ^7%s' % (client.exactName, input[1]))

	def cmd_hello(self, data, client, cmd=None):
		"""\
		- Have B3 greet you
		"""

		client.message(self.getMessage('hello', client.exactName))

	def cmd_count(self, data, client, cmd=None):
		"""\
		- Count for the player
		"""

		# get the clients "count" variable and increment it
		count = client.var(self, 'count', 0).value += 1
		self.console.say(self.getMessage('count', client.exactName, count))

You can get access to other plugins functionality by getting a reference to that plugin.

Example:

self._adminPlugin = self.console.getPlugin('admin')

To create commands you can hook into the admin plugin by using getPlugin

Example:

self._adminPlugin = self.console.getPlugin('admin')
if self._adminPlugin:
	# registerCommand(<plugin reference>, <command name>, \
	# <minimum user level>, <callback function>, <command shortcut>)
	self._adminPlugin.registerCommand(self, 'forgive', 0, self.cmd_forgive, 'f')

Command Callbacks

def cmd_myCommandName(self, data, client, cmd=None):
	"""\
	Your command [!help] description goes here
	"""
	# your code here