Unofficial Showdown! Client

Content

• Introduction
• Technical overview
• Notes
• Contributing
  • Report a bug
  • TODO list
• Credits
• Licence

Introduction

This repo contains source code for unofficial PokemonShowdown Client app. This client is now written mostly in kotlin and works through android framework. It was formerly written in java so you'll still encounter some objects written in java.

Why developing a native app when play.pokemonshowdown.com is supporting mobile devices ? Well, web client does its best to support small screen sizes (and it does it pretty well) but the user experience is far away from what a native app is able to provide.

What Android PS Client is ?

The goal of this app is to provide a client with a convenient and suitable UI for mobile devices without loosing any part of the experience you would have on official client (eg. tips, types, stats etc...).

What Android PS Client is not ?

This client is not, and will never be, a replacement for the desktop/web client. It's more like a companion app to be able to play PS everywhere, without needing your desktop computer.

Technical overview

Code structure

Here I will briefly describe packages along with their main components to help you finding out how each components are interacting together to make this app work.

Tree:

com.majeur.psclient

• .ui
  • .teambuilder
    • .TeamBuilderActivity.kt Regular android activity in charge of setting up navigation framework.
    • .*Fragment.kt Self explanatory name.
  • .MainActivity.kt In charge of setting up fragments and managing connection with ShowdownService.
  • .*Fragment.kt Responsible of UI management by implementing their associate *MessageObserver callbacks (except for TeamsFragment that works without registering any observer to ShowdownService).
  • .*Dialog.kt Self explanatory name.
• .service Everything related to Showdown's protocol will be found in this package. From shodown server communication to handling and processing of incoming data.
  • .ShowdownService.kt Responsible of all interactions with showdown server, including authentication.
  • .observer
    • .AbsMessageObserver.kt Base definition for a component that would handle messages from showdown server.
    • .GlobalMessageObserver.kt In charge of handling global server messages such as '|challstr|', '|popup|', '|formats|' etc... and rooms initialization.
    • .RoomMessageObserver.kt Handles everything for a basic room to work.
    • .BattleRoomMessageObserver.kt Extends from .RoomMessageObserver.kt and adds support for battle commands.
    • .ChatRoomMessageObserver.kt
  • [...]
• .io Contains everything involving loading content (eg. from disk for dex/move/poke details and dex icons or from web for sprites).
  • .AssetLoader.kt Helper class for loading content easily, with caching etc... Defines suspend functions for loading any type of asset using Kotlin coroutines.
  • .BattleTextBuilder.java Provides formatted text according to an action and its effect (and/or its origin).
  • .BattleAudioManager.java Handles everything related to audio playback during a battle.
  • [...]
• .model Contains every classes representing data.
  • [...]
• .widget Contains every custom android UI components.
  • [...]
• .util Contains various utility classes.
  • .html Utilities for displaying basic html using native android text framework. Mainly used for |html| and |raw| room messages.
    • .Html.java Entry point for using html utilities
  • .SmogonTeamParser.kt Responsible for parsing raw text teams formatted with Smogon standards.
  • .SmogonTeamBuilder.kt Responsible for building text teams formatted with Smogon standards.
  • [...]

Core mechanisms

I'll describe here some of the core mechanisms through quick flow graphs.

Incomming data flow

For ui updates, abstract methods are now replaced by interfaces (See: 05bbad5).

Outcomming data flow

Notes

Limitations

Multiple battles at the same time

For now, this client is designed to handle only one battle at a time. This because I think it makes more sense in app's UI design :), but mainly because I think it's not that relevant on a mobile device to run multiple battle like you would do on desktop. Anyway, I wrote code in a way that leaves the option to implement such feature in the future.

Doubles, Triples and other types

For now, only single and double battles are implemented. The code allows triple battle but no testing has been done, so it works 'as is'.

Data files

For maintainability reasons and to keep app binary file size as low as possible, I tried to retrieve data from showdown server as much as possible. But, for heavily/recurrent accessed data, such as poke/move details, json files are kept locally to ensure a very low loading time. Dex icons are also stored locally to allow region only icon decoding, avoiding us to load the entire icon sheet. A download of these files at first launch might be implemented in the future.

Web protocols

Every single http connection established by this client is using secured http protocol (https:). For WebSocket, wss: is now used since alpha3.

Android string resources

I was a bit lazy on this one... Most UI strings are hard-coded and aren't placed in the regular res/values/string.xml. This because Showdown is only available in English and has no localization implementation planned for now. So a Showdown client with localization would be completely pointless, and would lead into a partially 'translated' application.

Contributing

Any help is very welcomed! Please make sure you are respecting the coding patterns and please strongly test your modifications before PR!

Report a bug

• Smogon thread: here
• Submit a bug report: here
• Reported bugs tracking: here
• Open an issue in this repo

TODO list

For now, there is still a lot of testing to be done, but some new features would be nice and need a bit of thinking on how to integrate them nicely. Here is a non exhaustive list:

• Better handling of 'player as spectator' in battles: For now, the client assumes the trainer is the player and the foe well.. the foe. But If you just want to watch a battle (eg. being neither the trainer nor the foe), you'll find out that it works, but that tip popups among with other things behave weirdly.
• Support for battle replays: replays are 'just' battle logs that can be retrieved and played later. There is not a lot of things to do to support them, but thinking on how to integrate them is not that easy. Also, having a control on position in battle log needs to be implemented (thing like previous/next turn), because for now we are just waiting for the server to send us new part of the battle log.
• Better display of room users: add md5 colors, handle the @! marker and maybe sort them (See ChatFragment:line74)
• Decision cancelling: ability to get back to the first choice prompt without needing of terminating the decision and quickly cancel it if possible.
• Test more the challenge accept/request UI in HomeFragment: I've seen it keeping the cancel button shown when coming back from an ended battle.
• Think about the possibility of leaving a battle room (goes with second item in this list) if we are a spectator. How would this be coherent with the overall behaviour/design ?
• Add more unit tests: But this is really not a priority.
• Anything else you can think about 🤩, if it can be integrated nicely.

Credits

• Everybody on our Smogon thread: For the huge help with bug reporting
• Zarel: For PokemonShowdown itself.
• NamTThai: For some piece of java code translated from js I reuse here.
• http://pokemonshowdown.com/credits
• Type icons: DevianArt

Licence

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file or any in this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.