================
| pychop alpha |
================

pychop (Python CHannel OPerator) is a fork of the now ended ChOP++ project. The original project was developed by Spoof.3D (Michael Höferle) & jampe (Daniel Jampen), but pychop is currently being developed by uakf.b. pychop has currently only been tested on Linux, but should also work on Windows and OS X.

Additional core features include: numerous stability and bug patches, support for commands sent through standard input, and Python plugin support.

The official pychop website is at http://code.google.com/p/pychop/. The issues tab there should be used for support, feature request, and bug/crash reports.

Introduction
============

pychop is an open source C++ channel bot for Blizzard's battle.net servers and private PvPGN servers. It is divided into the core and the plugins. The current goal of this project is to make a relatively small, highly stable and efficient core that allows the installation of powerful plugins. Plugins then support additional features.

Currently, the core is capable of, among other things, managing clans and automatically moderating channels. Plugins include trivia, greetings, and a map downloader.

To connect to the official battle.net servers, you need a Blizzard game cd key. So far, pychop only supports Warcraft III: Reign of Chaos keys. Other options should follow by time.


Installation
============

To install pychop, simply unzip the ZIP download. Alternatively, you can checkout the latest SVN revision:

svn checkout http://pychop.googlecode.com/svn/trunk/ pychop

The SVN includes all plugins, while plugins are separated in the main ZIP download. pychop has several requirements:

- Python 2.7
- game.dll, storm.dll, and war3.exe from Warcraft III (see below)
- libboost
- libbncutil
- StormLib

To install most of these on Debian:
	apt-get install libboost-dev python2.7-dev

PluginDB, which is used to connect plugins with the MySQL database, also requires:
	apt-get install python-mysqldb


Configuration
=============

chop.cfg must be modified in order for pychop to properly work. All config values have descriptive comments that should guide you.

pychop, like GHost++, requires some Warcraft III game files to connect. It will search for these in the bot_war3path set in chop.cfg.

These files are: game.dll, storm.dll, and war3.exe. There is no need to forward any ports for this bot to work.


Database setup
==============

pychop requires a MySQL database or it will fail upon startup. Support for additional database systems is not planned.

All MySQL connection information must be filled in chop.cfg. To create the needed tables on your MySQL server simply use 'mysql_create_users.sql'. Both 'mysql_create_users.sql' and 'mysql_upgrade_ghost.sql' can be used to upgrade your existing GHost++ database without any data loss (mysql_upgrade_ghost.sql will attempt to create GHost tables, but only if they do not already exist).


Users
=====

pychop has a hierachical access system. To be able to execute any core command you need a specific access level defined in 'command.txt' (this file is located in 'bot_cfgpath'). Plugin command access levels are individually setup.

Access levels range from 0 (default access) to 10 (full access) and are saved to the database together with some other user data. Both the root admin and the console user always have an access of 10.

To grant other users access:
	!add [user] [access]
To delete a user from the database use:
	!del [user]

To remove access from a user, it is recommended to set the access to 0: deleting the user will clear other data that you may want to keep (for example, when they were last seen).


Automated scripts: core
=======================

pychop includes three scripts that can be individually enabled or disabled with the corresponding config value. These are from the original ChOP++ project; no new scripts will be added now that the plugin system has been implemented. Additionally, these scripts are no longer supported.

AntiSpam: a basic anti-spam implementation trying to keep the channel clean. If enabled it will cache the last channel messages from all users in the current channel (bot commands are ignored and not saved to the cache; this may be revised). The amount of cached messages is set with op_spam_cachesize. When a single user with access 0 fills up the chat cache, that user will be kicked.

AntiYell: a script to kick yelling users (uppercase messages) from the channel. Bot commands and users with more than 0 access are ignored.

PhraseKick: kicks users that write any banned phrases from 'phrase.txt' (in 'bot_cfgpath'). Bot commands and users with more than 0 access are ignored.

External scripts: plugins
=========================

Several official plugins are included in the SVN repository and in the plugins download. These are:

accesskick: automatically kicks users from the channel who do not have a certain access level on the bot.

afk: keeps track of AFK users.

alarm: an alarm clock. Alarm messages are stored via PluginDB so that if the bot is restarted, alarms do not have to be set again. If you do wish to reset all alarms, clearing the database is also supported.

announce: announces a message at a set time interval.

calc: a basic calculator.

chanstats: basic channel statistics. Currently displays the number of unique users who have entered the channel, the number of messages sent in the channel, and the number of joins/leaves recorded in the channel (these should be about the same).

copycat: copies everything that users say in the channel.

dbstats: displays some statistics about your MySQL database.

gamequeue: can be used to implement a public hosting system.

getgames: if you have the MySQL gamelist modification installed (http://www.codelain.com/forum/index.php?topic=18076.0), then you can use the getgames plugin to display the list of games. getgames relies on plugindb.

getmap: downloads a map from a URL and stores in in a preset directory.

gettime: retrieves the server time.

greet: automatically sends a message when a user joins the channel.

inactive: keeps track of inactive users in the clan based on channel activity.

inviteme: allows users to type !inviteme to receive a clan invitation.

lottery: a lottery game where channel users can bet on a number.

matchmake: a plugin to randomly create teams for matches.

plugindb: a library that takes database configuration values from pychop and allows plugins to access it. Also supports access to a plugindb table where key/value pairs can be recorded, and automatic score management.

pluginman: the pychop plugin manager

pounce: send a message when a target user joins the channel

queue: chat queue system; if you have multiple pychop instances, you can have a central pychop instance queue chat commands to the other ones to increase your chatting bandwidth.

rand: a simple plugin to display randomly generated numbers.

randkick: kicks a random user from the channel (pretty fun).

randspeed: a simple game. pychop will display a string to the channel, and the first user to type it out wins. Stats are stored via plugindb.

rroulette: a game where players are randomly kicked from the channel. Hope that you do not get kicked!

security: the simplest security plugin ever created.

test: a plugin to see if you correctly installed pychop.  Type !test and see if it works.

trivia: a powerful trivia handler. Trivia questions are read from the snapnjacks.com trivia question database. Category and difficulty can be specified both in the python file and through battle.net. Hints are given, and stats are stored via plugindb.

votekick: allows non-admin users to votekick disruptive users from the channel.

To submit a plugin, post it on the codelain.com forums in the pychop topic.

Plugin management
=================

This section will assume that you have pychop installed in /pychop/ (i.e., chop.cfg and chop++ binary are both located in /pychop/).

To install a plugin, copy the Python file (for example: plugin.py) to /pychop/plugins/pychop/.

After installing a plugin, you will also need to load it. If you are using plugin manager, then you can load a plugin without restarting the bot using the "!pluginman load" command. To reload or unload a plugin, replace load with "reload" and "unload". If you unload and then load a plugin, it will not be updated; only reload updates the compiled Python file.

You may also wish to load certain plugins on startup (especially the plugin manager). To do this, edit /pychop/plugins/pychop/__init__.py so that the plugin is imported and initiated. The comments in that file show the format of how to add a plugin. If the target plugin is called target.py, append to __init__.py:

import target
target.init()

This can be repeated for loading multiple plugins. Note that plugins can do whatever they want, and you should only install plugins from sources you trust (i.e., if that source were to give you an executable file, you should be willing to use it). You can always, of course, look over the plugin's source and make sure it doesn't do anything nasty.

If you add plugins to be loaded in this way, then you won't be able to unload or reload them with the plugin manager. If you want to use plugin manager functionality, you should use the plugin manager's startup load feature. To add a plugin to be loaded on startup with the plugin manager, look at "startupLoad" in /pychop/plugins/pychop/pluginman.py.

Warden
======

Warden is currently not active.

Commands: core
==============

All commands are accessible via battle.net chat. These can be sent through the channel or whispered directly to the bot (the latter option can be disabled in chop.cfg). Alternatively, you can send them through standard input (through the terminal).

=== user / access
- add [name] [access]	- sets the access for user [name] to [access]
- del [name]			- delete ALL data about user [name] from the database
- count					- displays the total number of users in the database
- access (name)			- displays the access of user (name), leave blank to see your own access

=== ban
- addban [name]			- bans user [name] from the channel and adds him to the database (ban from GHost++ bots with same database), accepts partial names (channel)
- ban [name]			- alias to addban
- delban [name]			- unbans user [name] from the channel and the database
- unban	[name]			- alias to delban
- checkban [name]		- checks if user [name] is banned in the database
- countbans				- displays the total number of bans in the database

=== channel
- channel [channel]		- joins channel [channel]
- say [text]			- repeats [text], can be used to execute BNet commands
- saycommand			- NOT A COMMAND, command.txt config value to control 'say'ing of BNet commands
- kick [user]			- kicks [user] from the channel, accepts partial names (channel)
- designate [name]		- designates user [name] and rejoins the channel
- rejoin				- rejoins the current channel

=== clan (require ChOP++ to be shaman or chieftain)
- motd [text]			- set the clan motd to [text]
- invite [name]			- invites user [name] to join the clan, accepts partial names (channel)
- remove [name]			- throws user [name] out of the clan, accepts partial names (clan)
- peon [name]			- change user [name]'s clan rank to peon, accepts partial names (clan)
- grunt [name]			- change user [name]'s clan rank to grunt, accepts partial names (clan)
- shaman [name]			- change user [name]'s clan rank to shaman, accepts partial names (clan), requires chieftain

=== managemant
- dbstatus				- show database status information
- wardenstatus			- show warden status information
- lastwhisper			- displays name of the last user that whispered
- lw					- alias to lastwhisper
- getclan				- refresh the internal copy of the clan member list
- getfriends			- refresh the internal copy of the friends list
- exit					- shuts ChOP++ down
- quit					- alias to exit
- uptime				- displays how much time passed since ChOP++ startup
- reload				- reloads all textfiles in the bot_cfgpath

=== misc
- seen [name]			- displays when user [name] was last seen in the channel (clan members only), accepts partial names (clan)
- version				- displays version information
- ping (name)			- displays the ping of user (name), leave blank to see your own
- owner					- displays the owner of the bot (root admin)

=== stats
- stats (name)			- displays basic player statistics of (name), leave blank to display your own
- statsdota (name)		- displays dota player statistics of (name), leave blank to display your own

=== fun
- slap [name]			- makes a random joke about [name], can also hit yourself! (jokes read from 'slap_pos.txt' & 'slap_neg.txt')
- ask8ball [question]	- gives random answers to [question] (answers read from 'ask8ball.txt')
- addquote [quote]		- adds a quote to 'quote.txt'
- quote					- displays a random quote from 'quote.txt'