wattazoum/meowth repository overview

⁠Meowth

A Discord helper bot for Pokemon Go communities.

Meowth is a Discord bot written in Python 3.6.1+ built with discord.py v1.0.0a (rewrite branch)⁠

⁠Meowth v2 Features

Meowth assists with organising Pokemon Go communities with support for:

• Team assignments
• Server greetings
• Wild Pokemon reporting
• Raid reporting and RSVP
• Research reporting
• Pokebattler integration for raid counters
• Silph card integration
• Gym matching extension for self-hosters

⁠Note: All reports are provided by your active server members. Meowth does not support any TOS breaking features such as spoofing, Pokemon Go bot accounts and automated raid reporting.

⁠Invite Public Meowth (no hosting required)

1. Use THIS LINK⁠ to invite Meowth
2. Select your server and click Authorize
3. Verify you aren't a robot (if the captcha doesn't appear, disable your adblocker)
4. In your server, type !configure
5. Go through the DM configuration session with Meowth to setup your server
   Be sure to read the prompts carefully and join the support server⁠ if you get stuck
6. That's it! Enjoy!

⁠Note: You must have the manage_server permission to invite a bot.

You can join the Meowth Discord Support Server for updates, setup help, feature requests, or just to test out the bot before you add it:
https://discord.gg/hhVjAN8⁠

⁠Install your own Meowth

⁠Using docker⁠

1. Install Docker CE⁠ on your server.

2. Create a configuration directory where your configuration and all your generated files will reside. Let's assume it's in the current directory : config

3. Optionally create a logs directory, if you want to easily have access to your logging files. Let's assume it's in the current directory : logs

4. Now build your docker image. Place yourself in the sources directory you retreived via GIT:

   docker build . --tag meowth2

5. Run the docker image:

   docker run -d --restart unless-stopped --name meowth2 \
               -v $PWD/config:/opt/meowth/config \
               -v $PWD/logs:/opt/meowth/logs \
               meowth2
   

   Copy

⁠[Non Docker] Dependancies

⁠Python 3.6.1+

Go here⁠ for details on how to install Python 3.6.

For all future CLI commands, replace the command name python3 with the relevant interpreter command name for your system (such as the common py command name on Windows). See details here⁠.

⁠Discord.py v1.0.0a (Rewrite Branch)

The rewrite branch of discord.py⁠ is an in-development branch that does not yet have an official stable release, however the default/master branch is feature-frozen, and lacks support for some of the newer features in discord such as categories.

If you intend to fork Meowth and alter any code, ensure you keep up to date with any breaking changes that might occur in this branch of discord.py.

python3 -m pip install -U git+https://github.com/Rapptz/discord.py@rewrite

⁠Note: You will receive the following warning on your first run, which can be disregarded:

PyNaCl is not installed, voice will NOT be supported

⁠Git

To clone the files from our repository or your own forked repository on GitHub, you will need to have git installed.

⁠Windows

Download the Git for Windows⁠ software.

On install, ensure the following:

• Windows Explorer integration component (and all sub-components) is selected.
• Use Git from the Windows Command Prompt is selected in the PATH adjustment step.
• Checkout as-is, commit Unix-style line endings is selected in the line ending config step.

⁠Linux

First check if it's already installed with:

git --version

If it's not already installed, use your relevant package manager to install it.

For Debian and Ubuntu, it would usually be:

sudo apt-get install git

⁠Required Python Packages

Linux:

python3 -m pip install "requests>=2.18.4" "hastebin.py>=0.2" "python-dateutil>=2.6.1" "fuzzywuzzy>=0.15.1" "dateparser>=0.6.0"

⁠Optional Python Packages

python-Levenshtein is an optional package that increases the speed of fuzzy matching strings, which we use for matching up pokemon names, gym names and possibly other things in future. It also removes the Using slow pure-python SequenceMatcher warning emitted from the fuzzywuzzy python package, which can otherwise be ignored.

python3 -m pip install python-Levenshtein

The above may not be supported on all systems. You can sometimes find a suitable wheel here⁠ to install with, or you may have to look around for details suitable for your specific system.

⁠Meowth

1. Create a Bot user in the Discord Developers panel⁠:

   • Click New App
   • Add an App Name, Description and App Icon (which will be intial bot avatar image)
   • Click Create App
   • Click Create a Bot User
   • Copy down your Client ID in the App Details box at the very top
   • In the App Bot User box, click to reveal Token and copy it down
   • Optional: Tick the Public Bot tickbox if you want to allow others to invite your bot to their own server.

2. Download the files in this repository, or your own fork if you intend to modify source

   ⁠Note: If you alter the code significantly, adapt to support platforms we don't or integrate any TOS-breaking features, we ask you don't name your instance Meowth to avoid confusion to users between our instance and yours.

3. Copy the bot config template config_blank.json, rename to config.json and edit it:

   • bot_token is the Token you copied down earlier from the Discord Developers page and requires quotes as it's a string.
   • default_prefix is the prefix the bot will use by default until a guild specifies otherwise with the set prefix command
   • master is your personal discord account ID. This should be a long set of numbers like 174764205927432192 and should not have quotes around it, as it's an int not a string.
     • You can get your ID by enabling Developer Mode on the Discord Client, in User Settings > Appearance > Advanced, which then enables you to right-click your username in chat and select the option Copy ID
     • Another method is to mention yourself in chat and add \ directly behind the mention for it to escape the mention string that's created, revealing your ID.
   • type_id_dict specifies what Pokemon Type emojis to use for your bot.
     • By default, it assumes you have the emojis in your own discord guild, and doesn't use the specific external emoji format. If you intend to allow the bot on multiple guilds, you will want to setup the external emoji strings.

4. Invite your Bot's User to your guild:

   • Get the Client ID you copied earlier from the Discord Developers page and replace the text <CLIENT_ID> with it in the following URL:
     https://discordapp.com/oauth2/authorize?client_id=<CLIENT_ID>&scope=bot&permissions=268822608
   • Go to the URL, select your server and click Authorize
   • Verify you aren't a robot (if the captcha doesn't appear, disable your adblocker)

5. Run the launcher from the command prompt or terminal window:
   python3 launcher.py

   If successful, it should send "Meowth! That's right!" as well as basic info on startup.

6. Simply type !configure in your server to start the configuration process as normal.

⁠Launcher Reference:

⁠Arguments

  --help, -h           Show the help message
  --auto-restart, -r   Auto-Restarts Meowth in case of a crash.
  --debug, -d          Prevents output being sent to Discord DM, as restarting
                       could occur often.

⁠Launch Meowth normally

python3 launcher.py

⁠Launch Meowth in debug mode if working on code changes

python3 launcher.py -d

⁠Launch Meowth with Auto-Restart

python3 launcher.py -r

⁠How to Translate Meowth:

We currently only support English with our public bot, with self-hosting being the only way to support other languages.

However, we have quite a few people on our support server⁠ who have been working on their own translations in a variety of languages.

If you are wanting to translate Meowth to your language, check there in our #non-english-support channel to see if someone might be able to share what they've worked on in the language you need.

To translate Meowth yourself, you can use pygettext.py and edit the generated translation files using Poedit⁠.

To generate a .pot file in Windows for example:

1. Nativate to [pythonpath]\Python36\Tools\i18n\

2. Open Command Prompt or PowerShell in this directory and run:

   py pygettext.py -d <RESULTING FILENAME> <PATH TO SPECIFIC *.PY FILE>

3. This will generate a meowth.pot that you can then translate using Poedit

4. Place the po/mo files from poedit into the /locale/<language abbreviation>/LC_MESSAGES directory (use other languages for reference)

5. Change Meowth's config.json bot-language and pokemon-language to <language abbreviation>

⁠Note: Since moving to Python 3.6 we have utlised f-strings in our source code in order to take advantage of the cleanliness and additional performance it brings. Unfortunately, we have later found out it is incompatible with pygettext's string extraction and replacement methods. As such, any strings that require translating that use f-strings will need to be edited in source to use str.format() instead.

⁠Directions for using Meowth:

Note: Avoid punctuation inside commands.

Arguments within < > are required.
Arguments within [ ] are optional.
pkmn = Pokemon

⁠Admin or Manager Commands:

⁠Miscellaneous Commands

⁠Pokemon Notification Commands:

⁠Reporting Commands:

⁠Raid Channel Management:

⁠Status Management:

⁠List Commands:

⁠General notes on Meowth:

Meowth relies completely on users for reports. Meowth was designed as an alternative to Discord bots that use scanners and other illegitimate sources of information about Pokemon Go. As a result, Meowth works only as well as the users who use it. As there are a lot of ways to interact with Meowth, there can be a bit of a rough learning period, but it quickly becomes worth it. Some commands are not necessary for normal usage and are only there for advanced users.

If you are having trouble getting Meowth running in your server, we have found that the majority of problems are either from permissions or your configuration. Check permissions with !get perms and check your configuration with !configure before asking for help in the support server.

⁠Known issues:

Compatibility with Python 3.6 on Mac OS X requires running "Install Certificates.command" in the Python 3.6 folder.

⁠Installing Python

⁠Windows

Install the latest Python 3.6 package from the official site if you have not already got it. At the time of writing, Python 3.6.5 was the latest maintenance release.
https://www.python.org/downloads/release/python-365/⁠

Python must be added the the environment's PATH, which is typically done automatically on install.

Your newly installed Python interpreter can be run in CLI in either Command Prompt or PowerShell typically with one of the following commands:

To check your referenced interpreter version, use:

python --version

Be sure to replace all instructions that specify a certain interpreter command with the one relevant to your system, as this differs between each individual OS, configuration and environment.

⁠Linux

If you're using Linux, you will likely have a version of Python 3 already installed on your system. Check your current version with:

python3 --version

If the version is not 3.6.1 or above, or python3 is not found, you will need to install it on your system. You do not need to remove any existing versions from your system and it is usually not recommended to uninstal the default package as other system packages may rely on it.

There are a large variety of flavours of linux, so be sure to reference online guides on how to install the required Python version with your specific system and package manager.

If you're on a version of Debian or Ubuntu and there is not a suitable ready-made package to install, the following is how to build and install Python 3.6.5 tailored for your specific system:

sudo apt-get update &&
sudo apt-get install ca-certificates libexpat1 libffi6 libgdbm3 libreadline7 libsqlite3-0 libssl1.1 dpkg-dev gcc libbz2-dev libc6-dev libexpat1-dev libffi-dev libgdbm-dev liblzma-dev libncursesw5-dev libreadline-dev libsqlite3-dev libssl-dev make tcl-dev tk-dev wget xz-utils zlib1g-dev gnupg dirmngr
wget https://www.python.org/ftp/python/3.6.5/Python-3.6.5.tar.xz
wget https://www.python.org/ftp/python/3.6.5/Python-3.6.5.tar.xz.asc
gpg --keyserver ha.pool.sks-keyservers.net --recv-keys 0D96DF4D4110E5C43FBFB17F2D347EA6AA65421D
gpg --batch --verify Python-3.6.5.tar.xz.asc Python-3.6.5.tar.xz
tar -xf Python-3.6.5.tar.xz
cd Python-3.6.5
./configure --enable-optimizations --enable-loadable-sqlite-extensions --enable-shared --with-system-expat --with-system-ffi
sudo make -j "$(nproc)"
sudo make altinstall

⁠Credits to Devon from the discord.py support server for testing and providing the above script.