tdmalone / slackemon

Inspired by Pokémon Go, now you can catch and battle Pokémon with your teammates on Slack!

Slackémon

Inspired by Pokémon Go, now you can catch and battle Pokémon with your teammates on Slack!

This program is very much a WORK IN PROGRESS, and should be considered very ALPHA. If you have any questions you're welcome to log an issue, but please be aware that code may be messy/incomplete, and some things may not work. In addition, not all mechanics are implemented yet. We're getting there!

Full Heroku deployment instructions
Scroll down for more setup options

Screenshots

            

More screenshots

Features

• Catch randomly spawned wild Pokémon and build your collection
• 'Travel' to different regions in the Pokémon world to find different wild Pokémon
• Battle wild Pokémon to make them easier to catch, and to level up your own Pokémon
• Battle your teammates to see who is the strongest!
• Compete with your teammates to see who can fill their Pokédex first
• Pick up randomly spawned items 'found on the ground': teach your Pokémon new moves, and evolve some Pokémon!
• Support for evolution based on level, happiness, time of day, item use, and known move/move type
• Tools to manage your Pokémon collection
• Live weather integration for a higher chance of, for example, water Pokémon during rain
• Add custom logic to control when legendary Pokémon can spawn
• Implements IVs, EVs, happiness, natures and growth rates
• Implements damage moves with PP, damage class, STAB, type effectiveness, recoil and drain
• Fainted, damaged and low-PP Pokémon auto-heal after an amount of time
• Respects users' Slack DND settings, so no-one wakes up to hundreds of missed spawns
• Includes a user-specific 'offline mode' so the game can be turned off when the interruptions are not wanted

Requirements

• A web environment running PHP7
• Access to a Slack organisation (if a free organisation, installing this will take up 1 of your 10 integrations)
• Optional: An API key for OpenWeatherMap, to enable weather features based on real-world weather
• Optional: An AWS S3 bucket for better performance when caching image assets

Setup

Setup of Slackémon is not quick. This may be worked on further in the future. For now, there are quite a few steps!

1. Download/clone/etc. the contents of this repository, and put it on a web server somewhere that runs PHP7.
   • Download ZIP or clone with Git: git clone https://github.com/tdmalone/slackemon.git
     • You may need to install depdendencies as well by running composer install. If you don't have Composer, get it here first. If you're not going to be developing Slackémon, you can speed up the install of depdendencies by instead running composer install --no-dev.
   • Install with Composer: composer require tdmalone/slackemon
   • Deploy with Docker
   • Deploy with Heroku
2. Log in to your Slack team, and visit https://api.slack.com/apps?new_app=1 to create a new App. You can call it whatever you like, but 'Slackémon' usually works best! You can then proceed to set up the app features through Slack's interface.
3. Set up Slack's Interactive Messages
   1. From your App control page, under Features in the sidebar, click Interactive Messages
   2. For the Request URL and Options URL, enter the address where you are hosting Slackémon (eg. http://example.com/slackemon)
4. Set up Slack's Slash Commands
   1. From your App control page, under Features in the sidebar, click Slash Commands
   2. Create a new command, naming it /slackemon. Set the Request URL to the same URL you used above.
   3. Enter any description you like - this is what will show to your team when they start typing /slacke..... Something like 'Catch Pokémon and battle your teammates!' usually works well.
   4. Leave the 'Escape channels...' checkbox unticked, and click Save.
5. Set up permissions and install the app to your team
   1. From your App control page, under Features in the sidebar, click OAuth & Permissions
   2. Scroll down and add the following permission scopes:
      • dnd:read
      • chat:write:bot
      • users.profile:read
      • users:read
   3. Click Save Changes, then at the top of the page, click the button to install the app to your team, giving it the permissions it asks for. Make a note of your OAuth Access Token.
      • At this point, if you are on a free Slack team, Slackémon will take up one of your 10 available integrations. If you have already used your 10 integrations, you'll need to completely remove one at https://YOUR-DOMAIN.slack.com/apps/manage before you can add Slackémon - or alternatively, upgrade to a paid Slack plan.
6. Head back to the 'Basic Information' page for your app, and scroll down to your app's credentials section. Make a note of the Verification Token.
   • You may also like to set up an icon for your app to make messages from it look slightly nicer - this Pokéball makes a good icon!
7. Set up your environment variables, either by copying .env.example to .env (development mode only - see instructions in the file), or setting the variables within your environment (recommended). Either way, see .env.example for instructions on the variables to set.
8. In your system's crontab (eg. crontab -e on a Linux machine, or find the Cron option in your hosting control panel), set up cron.php to run every minute, sending through the cron token you created earlier.
   • If you're invoking via the command line, you can use eg. php /path/to/cron.php --token=XXXXXXXXXXXXXXXXXXXX
   • If you're invoking via a GET request, you can use eg. http://example.com/slackemon/cron.php?token=XXXXXXXXXXXXXXXXXXXX
   • If you don't have access to cron, you can use a service such as cron-job.org
9. Time to install custom emoji! There's a lot to install, so we make use of the wonderful emojipacks:
   • Enter npm install -g emojipacks at a command line (if you don't have Node.js/NPM installed, do that first)
   • Run emojipacks -y https://github.com/tdmalone/slackemon/blob/master/etc/emojipack.yml
   • You will be prompted for your Slack subdomain (eg. YOUR-SUBDOMAIN.slack.com - leave out the slack.com part when entering it) as well as your username and password for Slack (neither Slackémon nor emojipacks will have access to your login details; it is simply required because Slack doesn't yet have an API endpoint for uploading emoji)
   • Wait... for quite awhile! When the script is done, you'll have almost a thousand new custom emoji covering every single Pokémon plus a few more custom emoji used by Slackémon 😃
   • If you can't install custom emoji in your Slack organisation, ask your team admins, or set SLACKEMON_ENABLE_CUSTOM_EMOJI to false in your environment variables.

Well done, it's time to start playing! You should now be able to run /slackemon anywhere in your Slack team to start the quick user onboarding process 👍

Future enhancements

Future enhancement ideas are progressively being added to the Projects section.

You can generally track what we're working on at moment through the Milestones.

User guide

A user guide will progressively be written at this repo's wiki.

Acknowledgements

Slackémon was first and foremost inspired by Pokémon Go. It borrows a few mechanics from Pokémon Go (mainly for simplicity), but as time goes on the aim is to be more true to the original Pokémon games wherever possible.

The idea of doing this on Slack came from Robert Vinluan's bot for having Pokemon battles in Slack. Inspiration and some battle move data has also been gleaned from Pokémon Showdown.

Thank you to those who have done the hard yards in bringing together Pokémon sprites, particularly PokeCSS.

Thank you to my co-worker Julian, who has been my main playmate in testing (and competing with!) this on our company Slack organisation at Chromatix, and to Alessandro Pezzè for being the first 'stranger contributor' to jump on board the project :). You can see the full list of contributors in CONTRIBUTORS.md.

Thanks to Slack for maintaining a well-documented, open API and inviting collaboration on their platform.

Last but not least, this project would never have happened without the extensive work undertaken by Paul Hallet at Pokéapi. Working on Slackémon has been fun rather than painful, thanks to the rich collection of readibly accessible data that Paul and his team have collected and structured. Thank you!

License

Slackémon - Catch and battle Pokémon with your teammates on Slack
Copyright (C) 2016-2017, Tim Malone and contributors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

slackemon's Issues

Make optional settings changeable via environment variables

Following the move to using environment variables, there are some optional settings that can no longer be easily adjusted by users.

These probably need to be moved to config.php and amalgamated into the get_env() structure.

Code coverage needs increasing

Code coverage recently went up from 0% to 4%... yay! But that's still pretty low.

Every file in _functions needs reviewing and unit tests written for at least a portion of functions. Some functions will need to wait until their complexity is reduced, but there's a lot of tests that can be written now.

Pokemon emojis not loaded on playslackemon.slack.com

Should load the emojis

Need good default error reporting settings

Need to ensure that all possible errors, warnings and notices that PHP reports are effectively set to go somewhere the administrator will see them.

• On Heroku, Papertrail works well for this, but we need to ensure the config is correct so every error goes there by default.
• On Docker, we need to ensure we're setting up the right settings and have somewhere to send the data. Maybe just to the error_log file will be fine? (although if not mounting the local file system over /var/www/html its possible it won't ever be seen)

Then we can also remove the ini_set()'s from init.php.

Prevent users from running key commands

Users need to be prevented from running key commands (eg. /slackemon maybe-spawn) - unless APP_ENV is development.

Need to set up data cache on AWS

Currently the data cache only works locally, which is not feasible for ephemeral filesystems.

While the image cache functions work whether set on either 'local' or 'aws', the data cache is not yet set up to work on AWS. It will need read and write operations set up, unlike the image cache which only writes and which is accessible publicly.

Special and speed stats aren't easily viewable in mobile mode

In mobile mode, when viewing Pokemon in your collection, special and speed stats are hidden for space reasons. These often are important (well, the special stats anyway, given that speed isn't implemented in battles yet), and probably still need to be visible.

In addition, it might be nice to see the special and speed stats on the spawn message as well (both for mobile and desktop views).

File/folder (and some function) structure needs slight redesigning

Slackémon was originally part of another framework but since moving out has both retained the original structure of that framework and added additional integrations such as CI. Configuration for additional integrations pollutes the root folder, especially when there's some source code mixed in there too. In addition, from the original framework, some of these files do not much else but call counterparts in the slackemon/ folder... which in turn end up calling functions in _functions/pokemon, some of which use functions directly in the _functions folder.

Some of the functions are also prefixed pokedex_ rather than slackemon_, which reflect that that they were originally written for a Pokédex feature part of the same framework Slackémon came from.

Whew! So basically, the structure needs rethinking so it's clear and less confusing. At the same time, we should clear the root folder of any source code, and try to put some of the directly run code into functions where they can be properly tested.

Cron token

define( 'CRON_TOKEN', 'XXXXXXXXXXXXXXXXXXXX' );

Could this variable be autogenerated randomly?

Pokeapi is shutting down - Slackémon needs an alternative

Re: PokeAPI/pokeapi#294

I knew this was coming at some stage but didn't realise it would be so soon.

Slackémon cannot run without Pokeapi.

I have forked it just in case (although Paul isn't going to remove it), but we'll need to look into setting up an instance of it before 1st July. Probably on Heroku? However, Pokeapi gets a lot of use and I won't be able to support everyone who wants to use it, so the instance will probably only be set up for use by Slackémon.

Nidoran male & female animated sprites aren't loading

This is caused by the move to PokeCSS graphics, which stores as eg. nidoran-male and nidoranm, but we're looking for nidoran-m (and same for the -f sprites).

Best way to fix is probably to duplicate all these sprites in the media repo to also be available at the -m / -f suffixes.

Searching in message menus not working on iPhone

When message menus are used for selecting a Pokemon (eg. to teach it a move, or use an item on it), on iPhone when you search there are always no results. It works fine on Windows and web, and on the Android app as well.

This may be a Slack iPhone app bug, but there's a chance something was implemented incorrectly in our use of the Slack API.

Clean source code with a set of code standards

Slackemon has been built with only adhering manually to code standards, and also across slightly different environments.

Some older files use tabs for indentations whereas newer ones use spaces. And while the code is generally clean, there's no enforcing of standards and there certainly are parts of the code that should be cleaner.

Need to build an appropriate set of PHPCS rules, clean everything up, and then possibly make it part of the Travis build process.

When a Pokemon faints due to a self-damaging move, the faint isn't dealt with properly

To finish the battle you have to make a 'pointless' move.

We need to detect fainting of a Pokemon after its own move, not only after an opposing move.

Larger sample icon needed for Slack app

The sample icon suggested in the README for users creating their Slackemon Slack apps is 128 x 128 and no longer accepted by Slack:

Icons must be squares between 512px by 512px and 2000px by 2000px, please!

Need to find an additional icon to use as an app icon (we still need the existing one for emoji use, as larger icons aren't accepted for that).

Travis jobs have stopped generating coverage reports

eg. https://travis-ci.org/tdmalone/slackemon/jobs/242321511 - expand the coveralls submission towards the bottom to see that it can't read tests/logs/clover.xml.

I've had a quick look into this and can't see why - pretty sure I didn't change anything. Will try to look into further when I have some time.

Pruning of stale spawn, battle and move data

Given that the Postgres data store is now active, we also need a way to prune stale spawn, battle and move data - otherwise the database is just going to fill up and reach limits (eg. 10k row limit on Heroku free).

All of the content in spawns, battles_active, battles_complete, battles_invites and moves can be cleared after 24 hours (even earlier probably, but this should be safe), and this could be done by cron.

Pokemon are no longer in alphabetical order in message menus

When using items or teaching moves, Pokemon names in message menus no longer come back in alphabetical order (they used to).

There might possibly be a bug in the sorting rules.

Transferring a Pokemon with a held item results in the item being lost

Transferring a Pokemon holding an item should either result in the item being returned to your bag (probably the preferred option), or the transfer failing/not being possible.

To assist in this, the held item icon could possibly also be shown next to a Pokemon on the bulk transfer list.

Need to re-implement a method for locking out employees while working

The first versions of Slackémon - which ran inside an existing proprietary Slack framework in our office - had a feature that locked staff out from playing it while they had a toggl timer running (this was how I avoided the risk of being asked not to continue making Slackémon available :) ).

That's not in the current version, because it depended on features available in that framework's environment.

To move my office over to the new current version - that is, the one here on GitHub! - I need to re-implement that, but obviously now in a hookable way.

I'm thinking perhaps an option to set a webhook URL that will be called periodically, sending across Slack user IDs of active users and requesting their 'status'. That webhook URL could then respond with a flag for those users that should be 'locked' out. This would allow me to respond in a custom manner from our office when Slackémon users have a toggl timer running - and will hopefully allow anyone else to integrate their own custom logic in (eg. lock people out during business hours, etc.)

Favourite button for Pokemon is blank on Android Slack app

Maybe on mobile view, just use text?

Wurmple evolution chain incorrect

Wurmple's evolution chain is reported incorrectly due to a bug in PokeAPI.

Since PokeAPI is not being actively maintained at the moment, we may need to find a way to 'override' data retrieved from the API in this case... to correct the bug with this bug's evolution chain.

Decide on a git branch strategy

Soon after I put this project on Github, and after @Naramsim's first pull requests, I slightly changed how I was branching. I noticed that @Naramsim then started setting his pull requests to go into my new tim branch - which is essentially my 'develop' branch.

To make things clearer, I'm thinking of adopting A successful Git branching model, minus the release branch flow for now (probably because we're in alpha, we generally just make releases when there's a feature or two that's ready, so that could happen straight from the develop branch). Version bumps would then happen directly after a merge from develop into master.

This would mean that each 'feature' I work on will have its own branch, which is not too different from how I have been developing tests and data-store. However, rather than merging into tim, I would instead merge into develop, which is also where @Naramsim and others could make their pull requests into.

Sound alright? @Naramsim?

Use composer for AWS SDK

The AWS SDK is currently included directly in the repository (via the .phar file).

It should be moved to Composer instead, and tested that image caching still works ok.

Function complexity needs decreasing

Some functions - in particular some spawn, catch and battle routines - have quite high cyclomatic and NPath complexity. This makes it difficult to write tests for them, and of course makes development of some new features difficult and increases the possibilities of introducing bugs.

Some current functions need to be re-thought in order to resolve this.

Ensure initial use on a new deployment is error-free

Because Slackemon has been newly separated from the Slack framework it was in previously ('Slashies'), it still retains some links such as old constant names that need to be updated.

A lot of these have been updated now but a few may still remain, and currently the first user onboarding on a new deployment does not go through smoothly.

This is probably the most important step to take next to make it easier for new people to jump on board.

Data store/cache service improvements needed

v0.0.38 added support for AWS being used for the data store/data cache. This means that Slackémon can now finally be used on a ephemeral filesystem service like Heroku.

However, there are issues inherent in this:

• AWS is an eventually consistent filesystem, which theoretically could cause some player and battle data to be lost, overridden, or to temporarily step back in time.
• Slackémon was originally written around using the filesystem as a data store, so it is quite liberal in its opening of and writing to files. While this doesn't seem to cause too much latency when the calls are coming from nearby (eg. Heroku is also on AWS), it can quickly add up AWS costs.
• There is no concept of file locking built in. This is already an issue that exists even when Slackémon is run with its own local data store: a player trying to perform certain actions simultaneously, across different Slack messages or button actions, could potentially find they lose some data or even worse, corrupt their player JSON file if it is read by a local system while it is being written to.

Slackémon currently has separate settings for an image cache and a data cache, they can both be set to either 'local' or 'aws' independently. However, we're utilising the data cache as both a data cache and a data store.

We likely could solve the above issues by:

1. When 'aws' is set as the data cache, also using a secondary local cache to reduce reads from AWS for the life of the current filesystem.
2. Implementing an additional option for the data store, allowing either 'local' or an alternative store such as Redis or Postgres.
   • Slackémon currently uses JSON files to store player and battle data (one per player and one per battle) so it would be ideal, to avoid having to rewrite alot, to stick somewhat to this method if possible. However, perhaps each individual player's Pokémon could be separated into a separate file to prevent single JSON strings from ever getting too big.
   • The method chosen would need to be easy to set up and support. Both Redis and Postgres are simple on Heroku; we would just need to look into Docker options too.
3. Implementing some sort of file lock for the data store, whether 'local' or the above alternative option is in use.

In addition, while in-memory caching is already in use for most data cache reads (eg. Pokémon & species data, move data, item data) and data store reads (player data and battle data), we could also probably reduce writes by ensuring that there's one save to a player file per request (at the moment there are sometimes two especially due to the slackemon_add_xp() function being called while something else requiring a save is also happening, such as catching a Pokémon).