Escapeling

Contents

1. Motivation
2. Bug Fixes
3. Minor Improvements
4. Outlook
5. References

Motivation

One of the main goals for the fourth semester was “Making the game playable”. The wish for this goal was caused by a multitude of small to severe bugs and partial usability problems. Of course, the bot was running before, but in some situations, it needed developer knowledge to complete the game: The game was usable, but it wasn’t playable.

The following section will provide an overview of the problematic bugs and their fixes. Afterwards, there will be a section, regarding minor usability improvements. Finally, we will talk about what’s left to improve, what future works could and should do.

Bug Fixes

This section is about errors that were made in the code. It describes, how the bug influenced the game, what caused it and how we solved it.

The flood-error

problematic Behaviour: After sending many messages, the bot stopped sending messages for a while. This often leads to omitted prompts and questions.

intended Behaviour: The Bot should send every message. *Explanation: Our code sends out requests to the telegram API. This API is responsible for sending and receiving messages. Since this API is running on the servers of Telegram FC-LLC and is available for free, access to it is somewhat restricted. Part of these restrictions is, that only 20 requests per minute are answered. Every other request is answered with the telegram.error.RetryAfter exception.

Solution: To solve this bug, we decided, to catch the exception and resend the same request after 15 seconds. This leads to the user having to wait for a moment, but is still a better solution, than missing out on possibly important messages. An alternative solution would have been the ‘telegram.ext.MessageQueue’. Sadly it is being deprecated, which is why we ultimately decided against using it.

Task-Pressuring

problematic Behaviour: In the listening task, the users typically have 90 seconds, till one of them has to answer. Instead of waiting these 90 seconds, they could press a button on the inline-keyboard, labelled “I want to answer now”. So far this button could be pressed by everybody, not only the person, who has to answer. This could, potentially, lead to pressuring the answering person.

intended Behaviour: The button should only be clickable by the answering person. For all the other players it should tell them, that only the answering players are allowed to click this button.

Solution: A simple if-block, to test, whether the person who clicked is the person who has to answer or someone else, resolved this problem.

Amount of users was counted wrong / Problematic joining behaviour

problematic Behaviour: Right at the start of the group room, the players were asked, whether they are ready. If a player responded with “Yes”, they got a message consisting of a ✔️-emoji for everyone who is ready and a ❌ who did not answer yet. If all people stated, that they were ready the game started. One problem was, that this feature sometimes showed the wrong number of participants. This could lead to the bot not starting because it thought, there was a fourth person. An alternative condition to start would be, that if at least 3 people were ready and a certain time passed, the game started. The problem with this was, that the time started after one of the first messages, that was sent in the chat. In combination with the increased time per message, that we implemented in semester 3, this lead to the time already being passed, before the players were able to state their readiness. In turn, this lead to the bot starting immediately after the third person wrote, that they are ready, even if there was a fourth person present.

intended Behaviour: The bot should only start, if all the players, that want to play, wrote, that they were ready.

Solution: We fixed the counter, that was counting the players in the group and decided to remove the countdown. Instead of the countdown, we decided to have an inline-keyboard, that allowed to “start without the missing players”.

Improvements

This part describes the small things, that we reprogrammed in order to make the user experience better and decrease the difficulty of the game.

levenshtein distance typo correction

Problem description: One of the complaints we got during our playthroughs, was that many of our tasks were not typo-friendly. In the vocabulary guessing task, when writing the correct word, the users got the message, that they are incorrect when writing an answer that was slightly misspelt. Even though the bot is, of course, right, when classifying them as incorrect, a message, that tells the users, that their spelling was incorrect would help them understand and solve their problem better. In the sentence correction task, the users could fail, because they misspelt a word.

How it should be: The bot should tell the user, that the word was spelt incorrect, instead of telling them, that the word itself is incorrect. A misspelt word should never lead to a failed task.

Solution: The solution for this problem was the so-called “Levenshtein-distance”. This is a string-comparison algorithm, that finds out, how many insertions, deletions and substitutions have to be done to change one string to another. If the amount of these edits was 1, the bot did send out a message, that implied, that there was a typo in the word. All above was still counted incorrect, all below 1 edit, was counted as correct.

html formatting

Problem description: Some players noted, that important pieces of information, like codewords, were hard to find in chat, because of the sheer amount of textual input.

How it should be: We decided, that the saliency of these key-informations should be increased.

Solution: Therefore we decided to use the HTML formatting option. This way certain information could be highlighted, by changing the colour, underlining it or printing it boldly. Passcodes were even more highlighted, by using the 1️⃣2️⃣3️⃣-emojis.

multiple answers

Problem description: In some cases one question allowed for multiple correct answers. For example words like “theatre” and “theatre”, that change, depending on if British or American English is used, or words like “can’t”, that are similar in meaning to “can not” or “cant”. Up until this semester, the other options were simply considered incorrect.

How it should be: These alternative answers should work as well.

Solution: We implemented an option to have multiple correct answers in the database. Therefore the pipeline to check, if a word was correct had to be adjusted as well.

instructions: What to do, if the answering options do not pop up

Problem description: Especially people who never worked with a bot on telegram, often wondered, how to reopen the answering options, if they accidentally closed it.

How it should be: The bot should show, how to open the answering options.

Solution: The first thing the bot sends to the user now, is a small explanation of how to open the answering options.

fixes for the deployment of the bot on the server/pc

Problem description: For many newcomers it was hard to get the bot running on their computers. There How it should be: It should be easy to run the bot on your pc or on a server. Solution: An detailed instruction has been written for both processes. They can be found in the readme file and here.

One fundamental mechanism for the Telegram Bot to work is the creation of new Telegram groups, which only works if the Telegram-API authentification was configured correctly. If the Telegram Bot wasn’t set up properly, the bot does not have permission to create new Escapeling Missions. The underlying problem here is, that creation of new groups is only prohibited by non-bot entities. This problem was solved by registering a smartphone number, which is used to create new rooms, instead of letting the bot create new groups itself. Three important steps are necessary to fulfil the authentification requirements. First, the phone number specified in the bot.config.json file (see: ‘telegram_api[phone_number]’ in the config file) must be a smartphone number that is registered as an active Telegram account and you have access to. Second, after the Telegram bot program was started, the program asks for a phone number. Enter the one that was specified in the bot.config.json file mentioned before and paste the Telegram Login Code you received for that specified number. If these instructions were followed correctly, the Telegram Bot can create new Escapeling Missions and does not throw errors related to this issue. The Escapeling bot was deployed on a Linux server of the University of Osnabrück. A remote connection to this server can be established via the network communication protocol secure shell (SSH). Compared to other legacy login protocols, SSH offers password or public-key authentication to establish a connection, as well as end-to-end encryption, which provides a secure connection over an unsecured network. As the process that runs the Escapling bot needs to continue running even if the SSH connection has ended, the terminal multiplexer tmux was used. Due to the client-server concept of tmux, a server is created in the background when a new terminal session is started. This server ensures that processes running in a specific session remain alive after the client detaches from the tmux session and killed the SSH connection. Compared to other methods, e.g. the ‘nohup’ command, tmux does not dump the output of the script that is run to ‘/dev/null’ and thus allows for better maintenance.

Github-fixes

Problem description: At the beginning of the Semester multiple people had the problem, that their GitHub refused to correctly pull the current branch.

Explanation: This was caused by git LFS, where large files were stored. Since semester 3 added a huge amount of .mp3 files and a big model for the use of the grammatical error correction, the amount of data, that was allowed to be downloaded from git LFS has quickly been exceeded.

Solution: The solution was to put these files into an external drive, where they could be downloaded separately. Simultaneously these big files were removed from the Github repository. If the Bot is started without these files, it gives out clear instructions on how to download and insert them into the file structure.

Outlook

Although we already changed a lot during the last semester, a lot still has to change in order to really get a perfect, polished outcome. The most pressing Issues were completed, but there are still features missing. Features like an Installer for people who want to run the bot on their computer, that automatically downloads the big files from a Server and helps with the setup would be important. In addition, the possibility to save games mid-play would help for groups to play. The Interviews also revealed that it should be possible for teachers to influence what exactly the questions for the students are or even implement their own tasks. Furthermore, there are still some bugs, that could not be reproduced, that should be fixed.