Welcome to BigBrotherBot’s User Documentation!¶

BigBrotherBot (B3 for short) is a complete and total server administration package for online games. It features :

In-game commands without authentication. B3 recognizes who is admin and who can run what rcon command.
Automated administration. B3 enforce your game server rules even when no admin is online.
Over 18 FPS games supported (CoD serie, BF3, CS:GO, ArmaII, BF:BC2, MoH, ...)
Extensible through plugins (11 officials and over 130 community contributed)
Highly customizable

Contents¶

Getting Started¶

Installing B3¶

There are several types of installation available. For Windows users the binary packages are recommended. Developers and Unix users can use the Python standard tools.

Windows binaries¶

This package is a MS windows installer package that has an included python interpreter for windows. You do not need to install Python.

Current packages of the stable version can downloaded in the forum or on SourceForge.

Just run the installer and follow the instructions.

Some developers offer daily builds based on latest development code.

Note

Daily builds are not officially supported. If you have problems, please try to use the stable version of B3.

If you find a bug in such a build, please report the bug with as much details on how to reproduce it in the forum.

Python .egg and source code package¶

If you have distribute installed, the easiest way of getting B3 is to simply use easy_install:

$ easy_install b3

If you have downloaded a source tarball you can install it by doing the following:

$ python setup.py build
# python setup.py install # as root

That’s it.

The development version¶

It is also possible to install the development version of B3 from our Git source code repository. To do this you will need to have Git installed on your system. Then just do:

$ git clone https://github.com/BigBrotherBot/big-brother-bot.git
$ cd big-brother-bot
$ python setup.py install

Game server configuration¶

This document describes the configuration of your game server that might be required in order for B3 to work properly.

If your game is not listed below, then you have nothing specific to do.

Quake III Arena, Call of Duty games, etc¶

Make sure your game server config sets the g_logsync cvar correctly.

set g_logsync 2

Urban Terror 4.1 and 4.2¶

Make sure your game server config sets the g_logsync cvar correctly.

set g_logsync 2

You might want to log every bullet hit to the game log file in order for B3 to work with plugins such as XLRstats. Then set the cvar g_loghits as bellow.

set g_logsync "2"    // 0=no log, 1=buffered, 2=continuous, 3=append
set g_loghits "1"    // log hits which allows b3 to recognize headshots and xlrstats to provide hit location statistics

Note

If you are running a patched UrT server that allows up to 64 players, set sv_minrate to 25000 to have stable pings and have B3 work smoothly

Smokin’ Guns¶

set g_logsync "1"
set g_debugDamage "1" // log hits

Soldier of Fortune 2¶

This game actually switches the settings…

set g_logSync "0"  // 0 = continuous logging, 1 = buffered logging
set g_logHits "1"  // set to 1 to log hits

Counter-Strike: Global Offensive CS:GO¶

In order to have a consistent name for the game log file, you need to start the game server with -condebug as a command line parameter. The game server log file can then be found in the csgo folder under the name console.log.

You must have SourceMod installed on the game server. See http://www.sourcemod.net/

Make sure to avoid conflict with in-game commands between B3 and SourceMod by choosing different command prefixes. See PublicChatTrigger and SilentChatTrigger in addons/sourcemod/configs/core.cfg

SourceMod recommended plugins¶

B3 Say¶

If you have the SourceMod plugin B3 Say installed then the messages sent by B3 will better displayed on screen.

SuperLogs:CS:S¶

If you have the SourceMod plugin SuperLogs:CS:S installed then kill stats will be more accurate.

First run¶

This document describes the preparations and the first start of B3. You’ll need the following:

Database
Access to your game server

Database Setup¶

B3 currently only supports MySQL and SQLite databases. We recommend the use of MySQL. For small installations SQLite may be sufficient. If you want to use SQLite, then once is nothing more to do.

Create a new MySQL database for B3 (see mysql-tools)
Import the table structure
On the database you just created, import the b3.sql file located in b3/docs/ to create the tables and insert the initial values in your database.

Use your favorite database management tool again or the following command.
mysql -u root -p<mysql password> b3 b3.sql

Configuration¶

B3 main config file is called b3.xml by default. If you run the bot straight away, it will detect you did not properly setup the main config file and will walk through a config wizard where each setting is prompted with a short description.

Alternatively, you can use our online configuration generator.

Detailed configuration options can be found in the manual. For game-specific configuration and alternative scenarios visit to our forums.

Running B3¶

You can run B3 from the command line when you’ve installed it as a source install or python egg.

python ./b3_run.py

Windows users who use the binary package, will find a shortcut.

With command line parameters can influence the behavior of B3. An overview of all parameters can be found in the manual.

Become Super Admin¶

After successfully installing and configuring your B3 bot you’ll start B3 for the first time. B3 will check if there are any SuperAdmins in your database. If not, B3 will enable the !iamgod command for the first player typing it in game.

So, it is wise to go in game immediately after starting B3 and typing !iamgod in chat, it will register you as the SuperAdmin and disable the !iamgod command.

User Guide¶

Introduction¶

This user guide describes some of the concepts of B3. Detailed instructions and configuration options can be found in the documentation of the plugins.

Configuration¶

Basics¶

Messages¶

User Roles and Groups¶

Basics¶

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.

Most commands for user and group management provided by the admin plugin.

B3 Groups¶

B3 has several default user groups, each serving a different purpose.

Level	Group	description
100	superadmin	The Super Admin is the highest level of authority. A Super Admin has access to all commands and is generally only assigned to the server owner.
80	senioradmin	Senior Admins are the highest admins. They have access to most commands except for the commands used in server/bot setup.
60	fulladmin	Full admins have less authority than Senior Admins but still have access to harsher punishment commands such as !ban.
40	admin	Admins are the first level of administrators. Their harshest punishment is a !kick, yet they are probably the most numerous of the admins.
20	mod	Moderators are the first step to becoming an admin, an admin training ground if you will. They can only !warn users or remind them of the rules. They can notify higher level admins when harsher punishment is needed.
2	reg	Regulars are not admins or moderators, but your loyal server population. You would only give regular status to members of your community.
1	user	A user is like a self appointed regular. New players can use the !register command to gain user status. User’s have only a few commands but gain extra privelages that would be ignored for the one-time visit players.

Warning

Plugins rely on these default groups. Do not remove these groups.

user Management¶

Users can be moved in groups by privileged users (eg admins) with the !putgroup command. The prerequisite is that the user is registered.

Useful Commands:

!register - register yourself as a basic user
!makereg <player> - Used by admins to add a user to the regular group
!unreg <player> - Used by admins to remove a user from the regular group
!putgroup <player> <group> - Used by admins to add a user to a group
!ungroup <player> <group> - Used by admins to remove a client to a group

The following example would move PlayerA into the moderators group.

!putgroup playerA mod

Users can only be a member of one group.

group Permissions¶

Group permissions regulate which command may be executed. Each plugin (core plugins or 3rd party plugins) comes with a config file where you can set levels belonging to the commands.

The following example would allow users with level 1 to use the !time command.:

<set name="time">1</set>

If you don’t want level 1 users to be able to use the command, but you want regulars (level 2) and up to be able to use it, change it to:

<set name="time">2</set>

You can set a range for the usage of the commands.:

<set name="time">20-40</set>

This will give the right to use the !time command only to moderators up to admins, but no below or above privileges can possibly use this command.

Note

Changes to the configuration file require a restart or reread the configuration files.

Warning System¶

Basics¶

The warning system allows to design an easy to use set of rules. Warnings are issued for breaking of the rules. B3 will automatically enforce harsh penalties if a limit of maximum warnings was exceeded.

Warnings are awarded automatically based on rules and manually by authorized players. The censorship plugin for example cautioned player automatically when they use an inappropriate language in chat. In another case, a moderator can warn a player for unfair play - example camp.

Automatic Warnings¶

Automatic warnings are carried out by the plugins. In general, the message, the warning time and the punishment can be configured.

Note

The configuration may vary and is documented in the manual of the plugin.

Manual Warnings¶

Manual warnings can be given by authorized players like moderators and are handled by the admin plugin.

A player may be warned with the following command:

!warn PlayerName camp

The player would receive the following warning:: WARNING (1): PlayerName stop camping or you will be kicked!

Tip

The warning system can make use of pre-configured rules and their abbreviations.

Useful Commands:

!clear <player> - Clears active warnings and tk points for the player identified by <player>

The admin plugin comes with a variety of configured warnings. The configuration is made in the file admin_plugin.xml.

Plugins¶

B3 in itself does not do much. Features like in-game commands or automated tasks really come from plugins. However there one special plugin, the admin plugin, which is at the heart of B3 and which allows other plugins to add their own commands.

Contents:

Admin¶

The admin plugin is at the heart of BigBrotherBot. It brings to B3 the user groups and in-game commands.

It allows the game server owner to define his staff by assigning trusted players to the different administration groups. Depending on their group membership, players will be given access to administrating commands which allow them to:

display the server rules
warn a user
kick
ban
change map
change the gamemode
etc

General settings¶

All settings below are defined in the settings section of the admin plugin config file.

noreason_level¶

The group/level from which admins are not required to specify a reason when giving penalties to players.

expected values: any group keyword or any group level, see B3 Groups
default value: superadmin

hidecmd_level¶

The group/level required to be able to use hidden commands. On quake3 based games, a hidden command can be issued by telling to command to oneself.

expected values: any group keyword or any group level, see B3 Groups
default value: senioradmin

long_tempban_level¶

Group/level required to be able to issue bans longer than the duration defined for the long_tempban_max_duration setting.

expected values: any group keyword or any group level, see B3 Groups
default value: senioradmin

long_tempban_max_duration¶

Maximum ban duration that can be inflicted by admins of group/level below the one defined at the long_tempban_level setting.

expected values: duration, see duration-syntax
default value: 3h

command_prefix¶

The prefix that should be put before b3 commands.

expected values: a single character
default value: !

command_prefix_loud¶

Some commands can have their result broadcasted to all players instead of only to the player issuing the command. To have such a behavior, use this command prefix instead of command_prefix.

Note

that this behavior only work with commands that consider it.

expected values: a single character
default value: @

command_prefix_big¶

Some commands can have their result broadcasted to all players as a very noticeable way. To have such a behavior, use this command prefix instead of command_prefix.

Note

This behavior only work with commands that consider it. Also depending on the game, abuse of such display can be frustrating for users ; use it wisely.

expected values: a single character
default value: &

admins_level¶

The admin plugin considers as an admin any player who is member of a group of level higher or equal to the group/level defined in the admin plugin config file at admins_level.

expected values: any group keyword or any group level, see B3 Groups
default value: mod

ban_duration¶

Temporary ban duration to apply to bans given by the !ban and !banall commands.

expected values: duration, see duration-syntax
default value: 14d

announce_registration¶

Define if a public message will be displayed to all in-game players when a user registered himself using the !register command. If enable, this can encourage others to register too.

expected values: yes or no
default value: yes

Spamages settings¶

The spamages section of the admin plugin config file defines ids for messages you want to be easily displayed to players with the spam command.

If the message id is of the form ‘rule#’ where # is a number between 1 and 20, it will be used for the rules command.

Related commands:

spam, spams and rules.

Commands¶

admins¶

Tells which admins are currently on the game server.

default required level

mod

usage

The !admins command takes no parameters.

customization

Admins are players who are member of a group of level equal or higher than the group/level set in the admin plugin config file at admins_level.

The !admins command responds with two types of messages depending on if there are any admins online. Those messages can be customized in the admin plugin config file:

messages:admins: When there is one admin online or more, the message template used is messages:admins. This template must contain a %s placeholder which will be replaced with the actual list of online admin names and levels.
messages:no_admins: When there is no admin online, the message used is messages:no_admins. In the special case where message messages:no_admins would be present but empty, then no answer is given back to the player when using the !admins command.

admintest¶

Alias for command regtest

default required level

admin

aliases¶

Show at most 10 aliases of a player.

default required level

mod

usage

!aliases [player]

If player is provided, display at most 10 aliases for that player.

If player is not provided, display at most 10 of your aliases.

alias

!alias

customization

The !aliases command response can be customized in the admin plugin config file:

messages:aliases: When the player has at least an alias, the message template used is messages:aliases. This template must contain 2 %s placeholder which are respectively: - the player’s name - the list of aliases
messages:aliases_more_suffix: When the player has more than 10 aliases, this suffix will be added to the response.
messages:no_aliases: When the player has no aliases, the message template used is messages:no_aliases. This template must contain one %s placeholder which will be replaced with the player’s name.

b3¶

Show the B3 version and uptime.

default required level

mod

usage

The !b3 command takes no parameters.

ban¶

Temporarily ban a player for the duration set by ban_duration.

default required level

fulladmin

usage

!ban <player> <reason>: ban a player specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!ban <player>: ban a player not specifying a reason. This is allowed only for admins of group level higher than noreason_level.

alias

!b

customization

The messages that can be displayed are: invalid_parameters, error_no_reason, ban_self, action_denied_masked and ban_denied.

The ban duration can be changed in the plugin config file at ban_duration.

banall¶

Like the ban command except it will ban multiple players whom name contains a given term.

default required level

senioradmin

usage

!banall <term> [<reason>]

alias

!ball

baninfo¶

Tell if a given player has active bans.

default required level

admin

usage

!baninfo <player>

alias

!bi

customization

The messages that can be displayed are: baninfo, baninfo_no_bans.

clientinfo¶

Show the value of a given property for a player. The purpose of this command is more for debug purpose than anything else but it can be useful to retrieve info such as the player IP address or guid.

default required level

senioradmin

usage

!clientinfo <player> <field>

where field can be one of:

guid

pbid

name

exactName

ip

greeting

autoLogin

groupBits

connected

lastVisit

timeAdd

timeEdit

data

bans

warnings

groups

aliases

ip_addresses

maskLevel

maskGroup

maskedGroup

maskedLevel

maxLevel

maxGroup

numWarnings

lastWarning

firstWarning

numBans

lastBan

Note

Not all those fields will return human readable data.

clear¶

Clear all active warnings and tk points (if the tk plugin is active) for a given player or for all in-game players.

default required level

senioradmin

usage

!clear

Clears active warnings and tk points for all in-game players

!clear <player>

Clears active warnings and tk points for the player identified by <player>

alias

!kiss

customization

The messages that can be displayed are: cleared_warnings and cleared_warnings_for_all.

die¶

Shutdown B3

default required level

superadmin

disable¶

Disable a plugin

default required level

superadmin

usage

!disable <plugin name>

enable¶

Enable a plugin that would have been disabled

default required level

superadmin

usage

!enable <plugin name>

find¶

Return the name and slot id of connected players matching a given pattern

default required level

mod

usage

!find <name>: Find a player by its name or partial name
!find <slot id>: Find a player by its game slot id

help¶

List available commands, or the short description of a given command

default required level

guest

usage

!help

List the commands available to the player issuing the command

!help <command>

Show a short description of the given command

kick¶

Forcibly disconnects a player from the game server

default required level

admin

usage

!kick <player> <reason>: kick a player specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!kick <player>: kick a player without specifying any reason. This is allowed only for admins of group level higher than noreason_level.

alias

!k

customization

The messages that can be displayed are: invalid_parameters, error_no_reason, kick_self, action_denied_masked and kick_denied.

kickall¶

Forcibly disconnects all players matching a pattern from the game server

default required level

senioradmin

usage

!kickall <pattern> <reason>: kick all players whose name matches the given pattern specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!kickall <pattern>: kick all players whose name matches the given pattern without specifying any reason. This is allowed only for admins of group level higher than noreason_level.

alias

!kall

customization

The messages that can be displayed are: invalid_parameters and error_no_reason.

lastbans¶

List the 5 last active bans.

default required level

admin

usage

!lastbans

alias

!lbans

leveltest¶

Tell in which B3 group a player is in.

usage

!leveltest [player]

If player is an on-line player name, display in which B3 group this player is in.

If player is not provided, display in which B3 group you are in.

alias

!lt

customization

The !leveltest command responds with two types of messages depending on if the user has a group or not. Those messages can be customized in the admin plugin config file:

messages:leveltest: When the player is in a B3 group, the message template used is messages:leveltest. This template must contain 5 %s placeholder which are respectively: - the player’s name - the player’s B3 database identifier - the player’s B3 group name - the player’s B3 group level - the date at which the player joined that B3 group
messages:leveltest_nogroups: When the player is in no B3 group, the message template used is messages:leveltest_nogroups. This template must contain 2 %s placeholder which are respectively: - the player’s name - the player’s B3 database identifier

lookup¶

Return the name and database ID of a player matching a given pattern

default required level

senioradmin

usage

!lookup <name>

Find a player in the B3 database by its name or partial name

customization

The messages that can be displayed are: invalid_parameters, no_players and lookup_found.

makereg¶

Put a player in the Regular group.

default required level

senioradmin

usage

!makereg <player>

alias

mr

customization

The messages that can be displayed are: invalid_parameters, groups_already_in and groups_put.

map¶

Change the map on the server

default required level

senioradmin

usage

!map <map name>

maprotate¶

Load the next map on the game server

default required level

senioradmin

usage

!maprotate

maps¶

List the server map rotation list

default required level

regular

usage

!maps

mask¶

Mask yourself as being a member of a group of lower level

default required level

senioradmin

usage

!mask <group>: Mask yourself as being a member of the given group.
!mask <group> <player>: Mask another player as being a member of the given group.

customization

The messages that can be displayed are: invalid_parameters and group_unknown.

nextmap¶

Tell which map will be loaded next on the game server

default required level

reg

usage

!nextmap

notice¶

Save to the B3 database a note about a player

default required level

admin

usage

!notice <player> <note>

pause¶

Make B3 ignore any game event for a given duration

default required level

senioradmin

usage

!pause <duration>

permban¶

Permanently ban a player.

default required level

senioradmin

usage

!permban <player> <reason>: permanently ban a player specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!permban <player>: permanently ban a player not specifying a reason. This is allowed only for admins of group level higher than noreason_level.

alias

!pb

customization

The messages that can be displayed are: invalid_parameters, error_no_reason, ban_self, action_denied_masked and ban_denied.

poke¶

Notify a player that he needs to move.

default required level

mod

usage

!poke <player>

customization

The messages that can be displayed are: invalid_parameters.

putgroup¶

Add a player to a B3 group.

default required level

senioradmin

usage

!putgroup <player> <group>

customization

The messages that can be displayed are: invalid_parameters, group_unknown, group_beyond_reach, groups_already_in and groups_put.

rebuild¶

Sync up connected players. This can be useful for games for which B3 can loose track of connected players.

default required level

senioradmin

usage

!rebuild

reconfig¶

Re-load all config files.

This way you can change some settings and apply them without restarting B3.

Warning

Some plugins may require a full restart of B3 to apply changes

default required level

superadmin

usage

!reconfig

register¶

Register yourself as a basic user.

default required level

guest

usage

!register: Put the player who typed the command into the :ref:`user <groups>` group

customization

The messages that can be displayed are: groups_already_in, regme_confirmation and regme_annouce.

regtest¶

The !regtest command tells in which B3 group you are in.

usage

The !regtest command takes no parameters.

customization

The response message template can be customized in the admin plugin config file at messages:leveltest.

regulars¶

List online players which are in the regular group.

default required level

user

usage

!regulars

alias

!regs

customization

The messages that can be displayed are: regulars and no_regulars.

restart¶

Restart B3.

Warning

For this command to work, B3 must have been started with the –restart command line parameter

default required level

superadmin

usage

!restart

rules¶

Display the server rules.

default required level

guest

usage

!rules

alias

!r

customization

The server rules are defined in the admin plugin config file under the section spamages.

Default rules are:

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

If you want to add another rule, name it rule11 and so on up to number 20.

runas¶

Run a command as a different user

default required level

superadmin

usage

!runas <name> <command>

alias

!su

customization

The messages that can be displayed are: invalid_parameters.

say¶

Broadcast a message to all players.

default required level

mod

usage

!say <text>

alias

!su

customization

The text template can be customized with setting say from the messages section of the config file.

That text template must have two place holders %s. The first one will be replaced by the name of the player issuing the command, while the second will be replaced with the text to broadcast.

scream¶

Broadcast a message 5 times in a row to all players.

If your game support Quake3 color codes, then each message occurrence will be in a different color.

default required level

admin

usage

!scream <text>

seen¶

Report the last time a player was seen on the game server.

default required level

reg

usage

!seen <player>

customization

The messages that can be displayed are: invalid_parameters, no_players and seen.

The seen template must contain two %s placeholders which will be respectively replaced by the name of the player and the date and time he was last seen at.

spam¶

Spam a predefined message.

default required level

mod

usage

!spam <message id>: will spam the message defined in the spamages section of the config file under the given message id to all players.
!spam <player> <message id>: will spam the message defined in the spamages section of the config file under the given message id to the specified player in a private message.

alias

!s

customization

The messages that can be displayed are: invalid_parameters.

Also see the spamages section of the config file.

spams¶

List spam message ids.

default required level

mod

usage

!spams

spank¶

Spank a player (kick).

default required level

fulladmin

usage

!spank <player> <reason>: spank a player specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!spank <player>: spank a player without specifying any reason. This is allowed only for admins of group level higher than noreason_level.

alias

!sp

customization

The messages that can be displayed are: invalid_parameters, error_no_reason, kick_self, action_denied_masked,: kick_denied, spanked_reason and spanked.

spankall¶

Spank all players matching a pattern from the game server.

default required level

senioradmin

usage

!spankall <pattern> <reason>: spank all players whose name matches the given pattern specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!spankall <pattern>: spank all players whose name matches the given pattern without specifying any reason. This is allowed only for admins of group level higher than noreason_level.

alias

!kall

customization

The messages that can be displayed are: invalid_parameters and error_no_reason, spanked_reason and spanked.

status¶

Report status of B3 database.

default required level

mod

usage

!status

tempban¶

Temporarily ban a player for the duration a given duration.

default required level

admin

usage

!tempban <player> <duration> <reason>: tempban a player for the given duration specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!tempban <player> <duration>: tempban a player for a given duration not specifying a reason. This is allowed only for admins of group level higher than noreason_level.

alias

!tb

customization

The messages that can be displayed are: invalid_parameters, error_no_reason, temp_ban_self, action_denied_masked and temp_ban_denied.

A maximum tempban duration is enforced for admin of level lower than long_tempban_level. See setting long_tempban_max_duration.

time¶

Display the current time.

default required level

user

usage

!time: Display the server time.
!time <timezone/offset>: Display the time for a given timezone or offset.

customization

The messages that can be displayed are: time.

unban¶

Unban a player.

default required level

fulladmin

usage

!tempban <player>

Tip

As the player you which to unban cannot be connected on the game server you will have to get the B3 database ID for that player. To do so, use the lookup command.

customization

The messages that can be displayed are: invalid_parameters.

ungroup¶

Remove a player from a B3 group.

default required level

senioradmin

usage

!ungroup <player> <group>

customization

The messages that can be displayed are: invalid_parameters, group_unknown.

unmask¶

Un-hide level.

Revert what the mask command does.

default required level

superadmin

usage

!unmask: unmask yourself.
!unmask <player>: unmask a given player.

unreg¶

Remove a player from the regular group.

default required level

senioradmin

usage

!unmask <player>

customization

The messages that can be displayed are: invalid_parameters.

warn¶

Give a warning to a player.

If then the player reaches a high number of active warnings, he is temporarily banned. See Warning system.

default required level

mod

usage

!warn <player> <reason>: warn a player specifying a reason. The reason can be any text of your choice or a reference to a reason shortcut as defined in the warn_reasons section of the admin config file.
!warn <player>: warn a player without specifying any reason.

alias

!w

customization

The messages that can be displayed are: invalid_parameters, warn_self, warn_denied and warn_too_fast.

warnclear¶

Clear all of a users’ warnings.

default required level

senioradmin

usage

!warnclear <player>

alias

!wc

customization

The messages that can be displayed are: invalid_parameters.

warninfo¶

Display how many active warnings a user has.

default required level

mod

usage

!warninfo <player>

alias

!wi

customization

The messages that can be displayed are: invalid_parameters.

warnremove¶

Remove the last warning of a user.

default required level

mod

usage

!warnremove <player>

alias

!wr

customization

The messages that can be displayed are: invalid_parameters.

warns¶

List the available warning ids.

default required level

mod

usage

!warns

customization

See the warn_reasons section of the admin plugin config file.

warntest¶

Test a warning

default required level

mod

usage

!warntest <warning id>: See the warn_reasons section of the admin plugin config file or the warns command for the list of warning ids.

alias

!wt

Advertisement¶

Censor¶

Status¶

TeamKill¶

Stats¶

Welcome¶

The welcome plugin will welcome players that join the game server.

You can define different messages that will be sent privately to players depending on if it is the first time the player joins the server of if he is a registered player.

Also you can define announcement messages that are broadcasted to all players when a player joins for the first time or if he is a registered player.

Finally you can allow players to define their own custom announcement message that will be displayed to all on joining the server. This custom greeting is to be set with the !greeting command.

Note

The plugin won’t welcome anyone in the 5 first minutes after B3 started.

Configuration¶

Commands¶

greeting¶

Group/level required to be able to use the !greeting command.

expected values: any group keyword or any group level, see B3 Groups
default value: mod

Settings¶

welcome_first¶

Define if private message welcoming first time players will be sent.

expected values: yes or no
default value: yes

welcome_newb¶

Define if private message welcoming newbie players will be sent.

expected values: yes or no
default value: yes

welcome_user¶

Define if private message welcoming registered players will be sent.

expected values: yes or no
default value: yes

announce_first¶

Define if a message welcoming first time players will be broadcasted.

expected values: yes or no
default value: yes

announce_user¶

Define if a message welcoming registered players will be broadcasted.

expected values: yes or no
default value: yes

show_user_greeting¶

Define if players custom greeting message will be broadcasted.

expected values: yes or no
default value: yes

newb_connections¶

Define the maximum number of connections above which a non registered player won’t be considered a newbie anymore.

expected values: integer greater than 0
default value: 15

delay¶

Define the delay in second after which the welcome message will be sent when a player connects.

expected values: integer greater than 0
default value: 30

min_gap¶

Define the duration in seconds the bot must wait before welcoming a player again.

i.e.: if you set min_gap to 3600 seconds (one hour) then the bot will not welcome a player more than once per hour.

expected values: integer greater than 0
default value: 3600

messages¶

first¶

Define the message to sent privately to joining first time players.

The text can contain placeholders that will be replaced just before sending the message.

expected values: text
default value: ^7Welcome $name^7, this must be your first visit, you are player ^3#$id. Type !help for help

newb¶

Define the message to sent privately to joining newbie players. Newbie players are players with less than newb_connections connections.

The text can contain placeholders that will be replaced just before sending the message.

expected values: text
default value: ^7[^2Authed^7] Welcome back $name ^7[^3@$id^7], last visit ^3$lastVisit. Type !register in chat to register. Type !help for help

user¶

Define the message to sent privately to joining registered players.

The text can contain placeholders that will be replaced just before sending the message.

expected values: text
default value: ^7[^2Authed^7] Welcome back $name ^7[^3@$id^7], last visit ^3$lastVisit^7, you're a ^2$group^7, played $connections times

announce_first¶

Define the message to broadcast when a first time player joins.

The text can contain placeholders that will be replaced just before sending the message.

expected values: text
default value: ^7Everyone welcome $name^7, player number ^3#$id^7, to the server

announce_user¶

Define the message to broadcast when a registered player joins.

The text can contain placeholders that will be replaced just before sending the message.

expected values: text
default value: ^7Everyone welcome back $name^7, player number ^3#$id^7, to the server, played $connections times

greeting¶

Define the message to broadcast when a player having defined a custom greeting message with the !greeting joins.

The text can contain the following placeholders that will be replaced just before sending the message:

placeholder	replacement
$name	the name of the joining player
$maxLevel	the level of the joining player
$group	the group of the joining player
$connections	the number of connections the joining player already made on that server

expected values: text with a special placeholder $greeting which will get replaced with the player custom greeting message.
default value: ^7$name^7 joined: $greeting

greeting_empty¶

Feedback message for the !greeting command.

expected values: text
default value: ^7You have no greeting set

greeting_yours¶

Feedback message for the !greeting command.

expected values: text with a %s placeholder which will get replaced by the current user custom greeting message.
default value: ^7Your greeting is %s

greeting_bad¶

Feedback message for the !greeting command.

expected values: text with a %s placeholder which will get replaced with details on what went wrong.
default value: ^7Greeting is not formatted properly: %s

greeting_changed¶

Feedback message for the !greeting command.

expected values: text with a %s placeholder which will get replaced by the new user custom greeting message.
default value: ^7Greeting changed to: %s

greeting_cleared¶

Feedback message for the !greeting command.

expected values: text
default value: ^7Greeting cleared

Placeholders¶

The text can contain the following placeholders that will be replaced just before sending the message:

placeholder	replacement
$name	the name of the joining player
$id	the B3 id number of the joining player
$group	the group of the joining player
$level	the group level of the joining player
$lastVisit	the date / time of the last connection of the joining player
$connections	the number of connections the joining player already made on that server

Commands¶

greeting¶

The !greeting command allows players to set / clear their custom greeting message.

default required level

mod

usage

!greeting

Shows the current player’s custom greeting message.

!greeting <message>

Sets <player> as the new player’s custom greeting message.

!greeting none

Clears the player’s custom greeting message.

SpamControl¶

PingWatch¶

Punkbuster¶

Customizing¶

Advanced configuration
How to install 3rd party plugins

Miscellaneous¶

Duration syntax¶

Many plugin settings need to express durations. For this purpose, B3 provides a convenient syntax using a suffix for expressing different duration units :

s: second i.e.: 45s
m: minute i.e.: 5m
h: hour i.e.: 1h
d: day i.e.: 7d
w: week i.e.: 4w

For example, let’s say you want to ban player Joe for 1 week with reason ‘insult other players‘, you would use the command :

!ban joe 1w insult other players

Player identification in commands¶

Commands that accept player designations can use several types of input.

Partial Name¶

The simplest player identifier is the players name. You can use any part of the player name. Only enough characters to match the players name uniquely is needed. If more than one player on the server has a similar name, you will be prompted with all players matching that name and their client id.

Example:

!warn sam cuss for giving a warning to a connected player named ‘Samuel’

Note

You can use the find command to show which connected players match a given name.

Note

If the player’s name contains blank characters as in M I K E, then you can use its name without the blanks: !kick mike

Another solution is to wrap single quotes (') around the name: !kick 'm i k e'

Client ID¶

The client ID is the number assigned to the player by the game server. The client ID only works for the current gaming session. For a list of players’ client IDs, use the !list command. If a players name is too hard to type or there are more than one players with similar names, you can use the client id to single them out.

Example:

!kick 3 tk to kick a player connected on game slot number 3

Database ID¶

The Database ID is the players unique identification within the B3 database. It is prepended with an ”@” and is often referred to as the “at ID”. This ID is displayed with the leveltest command and the lookup command. You can use this ID to perform actions against a player even when that player is not connected.

Example:

!makereg @1235

Note

You can use the lookup command to find offline users in the database and get their database ID.

MySQL tools¶

The following tools facilitate the use and administration of a MySQL database. Probably you have already installed one of these tools.

Adminer

phpMyAdmin

MySQL Workbench

Frequently Asked Questions¶

How do I become superadmin?
Someone typed !iamgod before me ! what to do?
Can B3 run remotely?
Why does B3 not respond to my commands?
B3 lags and is slow to respond to my commands
Does B3 have to be installed on the game server for quake based games?
Can I run B3 from a webhosting server?
I cant connect to my MySQL Database!!
Can I run B3 on a LAN?
Can I run many different bots? Using the same sort of settings and database?
I need a provider that sell game servers with B3 bot! Dedicated servers are far too expensive for our clan.
b3_run.exe fails to start
The time is off by an hour
B3 doesn’t support python 2.4 and I’m on CentOS... now what?
Will B3 run with python on Windows 2k3 server 64-bit?
CRITICAL Error loading plugin: No module named ...
Using B3 remote with sshfs
How to run B3 on Free BSD or MAC OS X

How do I become superadmin?¶

Be the first one to type !iamgod in the game chat.

Someone typed !iamgod before me ! what to do?¶

Once the !iamgod has been successfully used, it is not available anymore.

Chances are that you just installed B3 not long ago and can afford to delete the B3 database altogether and recreate it. Then:

make sure nobody is on your game server
restart B3
be the first one to type !iamgod

If you don’t want to delete your B3 database, you can remove the user from the superadmin group by editing the database. For that you will need a tool to connect to your database and be able to alter it (see mysql-tools).

Once you are connected to the B3 database, open up the clients table. This table lists all players seen by B3 on your game server.

To find who is in the superadmin group, sort the clients table on the group_bits column. A value of 128 indicates that a player is in the superadmin group. Simply change the value 128 to 0 to remove the player from the superadmin group.

Now that no one is superadmin anymore, you can restart B3 and make sure to be the first one to type !iamgod in the game chat.

Can B3 run remotely?¶

For games B3 reads the game log file, refer to Does B3 have to be installed on the game server for quake based games?.

For other games, B3 just work from the RCON system alone.

Why does B3 not respond to my commands?¶

If B3 seems to be ignoring your commands there can be different reasons. To determine what is going wrong follow the procedure:

restart B3

join your game server

type !help in the game chat

open the B3 log file (often named b3.log)

search your log file for the word CONSOLE (in upper case)

If you cannot find any line with CONSOLE in them¶

B3 has difficulties getting notified of what is happening on your game server. As a consequence, B3 is not even aware that you typed a command in the game chat.

Depending on the game, B3 can be reading the game server log file. If this is the case, make sure the setting game_log of your b3.xml config file is correct. Also make sure you can find a line in that game log file that shows you typing the !help command.

If B3 is not supposed to read any game server log file, then check your rcon settings in b3.xml.

Make sure no line as ERROR in it in b3.log file.

If you find lines with CONSOLE in them¶

If none of them contains !help (the command you typed earlier), then check that the correct game log file is set for game_log in your b3.xml config file. Or check your rcon settings. For CoD games, if you are running a game mod, then you should have different game log files in the mod folder. Make sure B3 reads the one that is being written to by your game server.

If you can find the CONSOLE line that shows you typing the !help command your typed earlier, then examine the lines that follow and look for any error that could give you hints about the issue. Most likely, B3 was not able to send the response to the game server through rcon. If that is the case, tripple check your rcon settings in b3.xml.

B3 lags and is slow to respond to my commands ¶

If B3 is reading the game server log file, then your game log file might not be updated in real-time by the game server.

Check your game settings as instructed at game-configuration.

Does B3 have to be installed on the game server for quake based games?¶

No. B3 can read your game log file over different remote protocols such as FTP, SFTP, HTTP, HTTPS. In your b3.xml file, just set the url of your game log file for setting game_log.

Note

The url can contain the login and password if any. Example: ftp://my_login:my_password@my-hosting-provider.com/game.log.

Tip

To verify your url is correct, paste it in your Internet browser and check the game log file content appears

Can I run B3 from a webhosting server?¶

No, B3 needs more than just a webserver. B3 depends also on Python and MySQL. Generally (some of) those packages are not available on a webhosting environment.

I cant connect to my MySQL Database!!¶

First, make sure that the format of your MySQL info is correct in b3.xml for setting database.

The syntax for the database setting is :

mysql://<username>:<password>@<hostname>[:port]/<databasename>

username¶: the MySQL user that has privileges to access the B3 MySQL database

password¶: the MySQL password of the user that has privileges to access the B3 MySQL database

hostname¶: the hostname of the machine that runs the MySQL server. It can also be the IP address of that machine.

Tip

if the hostname is localhost and you still have errors, try 127.0.0.1 instead of localhost

port¶: the port the MySQL server is listening on. Can be omitted if your MySQL server is listening on the default port : 3306

databasename¶: the name of the MySQL database B3 should use

Make sure all that info is correct by connecting to your MySQL database with a MySQL adminstration tool (see mysql-tools).

Can I run B3 on a LAN?¶

Unfortunately not for all games.

For some games B3 uses Punkbuster (The Anti-Cheat tool) to authenticate players. Punkbuster doesn’t authorize people on LAN servers, so B3 will not run correctly.

Also the CoD series games will not provide you with a GUID, so on CoD B3 won’t even work without PunkBuster on a LAN.

Can I run many different bots? Using the same sort of settings and database?¶

Yes you can run many bots on the same machine. You can also have many B3 bots sharing the same database, as long as its the same game (eg. 2 x CoD2 Servers).

If you wish to do this then you need to make another B3 config file (eg. b3-2.xml) with the details of your other game server.

Then you need to tell your second B3 to start using the new config file b3-2.xml. To do so, use the --config argument of the b3_run program.

b3_run.exe --config "C:\b3\conf\b3-2.xml"

I need a provider that sell game servers with B3 bot! Dedicated servers are far too expensive for our clan.¶

There are indeed a few providers that will allow you to buy game servers with B3 Bot installed! Also you can find companies that will just host your B3 alone.

See list of hosting providers

b3_run.exe fails to start ¶

If the error message is::

This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem

then you most likely are missing a few dll. Install the Microsoft Visual C++ 2008 Redistributable Package (x86)

The time is off by an hour ¶

B3 does not automatically apply daylight saving time changes. To reflect summer/winter time change, you have to tell B3 explicitly in the b3.xml main config file. see available_timezones

B3 doesn’t support python 2.4 and I’m on CentOS... now what?¶

While B3 can work on python 2.6, it is advised to run in with python 2.7.

Python 2.6 is not at all in the Standard Repos of the RHEL / CentOS. Install Python 2.6 will work only, when you use the epel Repository which can found here:

https://fedoraproject.org/wiki/EPEL

To install it use:

for 32bit systems

su -c 'rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm'

for 64bit systems

su -c 'rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/x86_64/epel-release-5-3.noarch.rpm'

after that you can do:

yum install python26 mod_python26

Will B3 run with python on Windows 2k3 server 64-bit?¶

B3 will run just fine under Server 2K3 64-bit. The trick is to use 100% 32-bit Python.

If you get the same error when trying to execute the 32-bit Python installers, get Microsoft’s 32-bit C++ runtime.

CRITICAL Error loading plugin: No module named ...¶

If you have an error in your b3.log file complaining about a plugin that could be loaded::

091030 09:59:42   CRITICAL   Error loading plugin: No module named xlrstats
Traceback (most recent call last):
  File "/usr/lib/python2.5/site-packages/b3-1.2.1-py2.5.egg/b3/parser.py", line 437, in loadPlugins
    pluginModule = self.pluginImport(p)
  File "/usr/lib/python2.5/site-packages/b3-1.2.1-py2.5.egg/b3/parser.py", line 500, in pluginImport
    fp, pathname, description = imp.find_module(name, [self.config.getpath('plugins', 'external_dir')])
ImportError: No module named xlrstats

Then verify that the plugin file does exist in the extplugins folder of the B3 installation directory.

It the plugin .py exists in the right folder, then also check that file is not copied a second time in another folder of your B3 installation directory.

Using B3 remote with sshfs ¶

Q:

I have been playing sshfs to monitor a remote server with b3. It works, but is kinda weird. If I mount with sshfs the remote game server dir in the box where b3 is running and then send a command from the game, for example !time, b3 will see the command like after two or three minutes. BUT, if I do a tail/cat/more of the game log file in the sshfs’ed mounted directory then b3 will immediately see the command in the log and respond. If I leave a tail -f game.log running then b3 will work perfectly, and when stopped it then b3 will again start to react two or three minutes after.

A:

The magic parameters are direct_io and cache=no. It works like a charm. You will mount it like this::

sshfs -odirect_io,cache=no urban@xxx.xxx.xxx.xxx:/home/urban/UrbanTerror servers/remote_server/

To avoid having to enter the remote user password each time you mount the remote dir you will have to generate a ssh key pair with the ssh-keygen command and upload the public key to the game server .ssh/authorized_keys file. (Thanks to Mazter)

How to run B3 on Free BSD or MAC OS X ¶

Q:: On some Free BSD and Mac OS X, B3 does not read game log file content. As a result it does not respond to your in-game commands.
A:: This topic on the forum as two solutions. One is to apply a patch on your Python installation while the other one is a patch to apply to B3