ASCII Art Hangman for Kids

ASCII-Hangman is a paper and pencil guessing game for two or more players. One player thinks of a word, phrase or sentence and the other tries to guess it by suggesting letters or numbers, within a certain number of guesses. ASCII-Hangman is a variant of the game especially designed for children: the computer selects a word, phrase or sentence randomly out of a word-list defined in a configuration file.

In the course of the game, ASCII-Art images - designed for children - are progressively disclosed. There are more than 300 built in ASCII-Art images from which one is chosen randomly at the beginning of the game. Alternatively own ASCII-Art can be provided in the configuration file.

Highlights:

simple, non distracting user interface,
setting up word lists is part of the learning process,
visual non distracting reward system with more than 300 built-in ASCII-art images,
no built in traditional gallows image,
designed for group learning in classroom,
fully configurable:
- design your own ASCII-art (depending on the learning subject) and associate it with your word list,
- provide the user with hints by disclosing some characters from the start,
web-application: play without installation,
desktop versions: play without network access,
open source software: guaranteed availability, always free of charge.

ASCII-Hangman is available as web-application and can be played online here: ASCII-Hangman Web-App.

Figure 1. ASCII Hangman web-app version

ASCII-Hangman is also available as desktop-terminal-application for Linux, Mac and Windows. Download and installation instruction are here: ASCII-Hangman Desktop App.

Figure 2. ASCII Hangman terminal version

The project is hosted on Github: getreu/ascii-hangman. The project’s webpage is on getreu.net. There you also find a pdf rendition of this document and compiled binaries.

1. Getting started

1.1. ASCII-Hangman installation

The web-app version does not need to be installed on your computer. Just navigate to ASCII-Hangman Web-App and start playing.

As far as the desktop version is concerned, there is no installation in the proper sense either, as the whole application consists of only one binary file. Download this file here: ASCII-Hangman Desktop App and just execute it.

1.2. ASCII-Hangman invocation: how to start the game

Web-App

Navigate to ASCII-Hangman-Web-App.

Linux

Open a terminal.
Navigate to a folder containing configuration files, e.g.
```
cd vocabulary-chapter-1
```
If the folder contains only one configuration file named hangman-words.txt just type:
```
ascii-hangman
```
otherwise type, e.g.:
```
ascii-hangman words-page3.txt
```

Windows

Open the folder in which the ascii-hangman.exe executable file resides.
Open a second explorer window and navigate to a folder with a configuration file, e.g. hangman-words.
Drag and drop one or more configuration files on ascii-hangman.exe.

2. ASCII-Hangman configuration

ASCII-Hangman needs a custom list of secrets, from which it selects randomly those the user guesses. This list is provided by a configuration file, which has a very simple syntax explained below. When you start the desktop version of ASCII-Hangman for the first time, a sample configuration file, named ascii-hangman-words.txt, is created. Adding own secrets to this file can be done with any text editor. Next time ASCII-Hangman starts, it will read the modified list of secrets.

The Web-App version of ASCII-Hangman works similar. Here the program starts with a configuration page allowing you to enter the list of secrets directly without external editor. If you wish, you can upload a prepared list of secrets from a file on your hard disk. Note, it is also possible to select more than one file in the file selector dialogue.

2.1. Linux configuration

Run ASCII-Hangman once. It creates a configuration file ascii-hangman-words.txt in the current working directory.
Edit the configuration file
```
nano ascii-hangman-words.txt
```
Start the game
```
./ascii-hangman
```

2.2. Windows configuration

Generate a configuration file in your working directory

Double click on ascii-hangman.exe

This creates the file ascii-hangman_words.txt
Edit the configuration file

Double-click on ascii-hangman-words.txt. This opens the file in the Notepad editor. Add own secrets, one per line.
Start the game

Double-click again on ascii-hangman.exe.

2.3. Synopsis and syntax

ASCII-Hangman expects its configuration file in YAML format:

Usage: ascii-hangman
       ascii-hangman [FILE]
       ascii-hangman -h|--help
       ascii-hangman -V|--version

`[FILE]` are configuration files containing one word-list hereafter referred to as "secrets" and
optionally one Ascii-Art image.

When no `[FILE]` argument is given, `[FILE]` defaults to `ascii-hangman-words.txt`. In case no
`[FILE]` is found, a template configuration file `ascii-hangman-words.txt` is written into the
current working directory. Multiple `[FILE]`s are concatenated.

`[FILE]` is a UTF-8 YAML formatted file containing 3 different variables:

- `secrets:` is an array of secrets, one per line. A secret is a string, that interprets the `|`
  character as newline and the `_` character as visibility switch. This switch allows to
  disclose a part of the secret when the game starts.
- `traditional:` is an optional boolean variable indicating how the ASCII-art image should be
  disclosed:
  * `true`: the image gets disclosed with every lost life,
  * `false`: the image gets disclosed with every guessed character (default).
- `image: |1` is an optional multiline string providing own ASCII-art. When missing, built-in
  ASCII-art is chosen randomly.
- Lines starting with `#` are ignored.

Example:

secrets: - guess me - "guess me: with colon" - line| break - _disclose _partly

 # The following is optional.
traditional: false
 # Optional ASCII-art lines start with 1 space ' '.

image: |1
   ::
 C|__|

2.4. Sample configuration files

Simple configuration file

secrets:
- guess me
- hangman
- "der Hund: the dog"
- good luck
- 3*7=21

Note	When a string contains a colon, as in `der Hund: the dog`, it must be enclosed by double quotes `"der Hund: the dog"`!

Simple configuration file with hints

secrets:
- guess me
- hang_man_
- "_der Hund_:| the dog"
- _good l_uck
- _3*_7_=21_

Note	Substrings enclosed by underscores, as in `_good l\_`, are visible from the start of the game.

Note	The pipe character `\|` indicates a hard line break within a string.

Configuration file with custom image

A configuration file may contain a custom image. Just like with built in ASCII art, the image is gradually disclosed after each right guess.

secrets:
- _guess_ me
- hang_man_
- good luck
- _3*_7_=    21_

image: |1
      !!!!\\\\
    '`!_  ||||
     ` \`-'''|
       `\   /
        )\  \
 ejm   /  \  \
           \|

# Author: ejm

Important

ASCII-art lines, the lines after the image: |1 statement, must start with at least one (invisible) space character.

It is also possible to split the word list and the image into two files and load them separately:

ascii-hangman wordlist.txt custom-image.txt

Configuration file with traditional gallows image

The following image has a different rewarding mode: traditional: true. In this mode the image is gradually disclosed after each lost life.

secrets:
- _guess _me
- hang_man_
- _good l_uck

traditional: true
image: |1
   ______
   |    |
   |    O
   |   /|\
   |    |
   |   / \
 __|_____
 |      |___
 |_________|

Note	The gallows image is not part of the built-in ASCII-art. If wished for, it must be provided within the configuration file.

3. Play the game in the classroom

The game is designed for classroom usage, but can be played alone as well.

3.1. Classroom requirements

Bigger screen or projector
Browser with Internet access - or -
Windows, Mac or Linux computer with the ascii-hangman.exe (Windows) or Ascii-Hangman (MacOs and Linux) binary downloaded.

3.2. Prepare a configuration file with secret words

The following may serve as a suggestion how to integrate the game in a lesson in class:

The aim of the game is to consolidate recently learned vocabulary. For this purpose the class composes a vocabulary list of words or expressions, hereafter referred to as “list of secrets”.

The class composes the list of secrets together with the teacher. To optimize the learning progress, it is most useful to involve the pupils in the preparation of the list of secrets, e.g.: One pupil types the suggested words into the configuration file, the others follow on the screen and correct spelling mistakes.
The list of secrets can be recent vocabulary or even some simple calculation exercises. A secret is always encoded as one line in the configuration file. This can be a word or a whole sentence or expression.
To give an additional hint it, is possible to tag some letters of the secret sentence (see examples above). This part will be disclosed immediately when the game starts.
At the beginning of the game, the computer chooses randomly one secret out of the list. When a secret is guessed correctly, it will not be asked again. The game ends, when all secrets are guessed correctly.

3.3. Suggested game rules for the classroom

The following rules are designed to stimulate the participation of the whole group of learners. Vary them according to your needs.

Each pupil is asked to write down all already guessed letters on a sheet of paper.
A player is allowed to guess once more, when the last guess was right.
When he fails, he passes the turn to the next player. In bigger groups the next player may be chosen randomly. This keeps more pupils concentrated, as nobody knows who will be the next.
A player is not allowed to ask others what letters are guessed already. He has to solely rely on his own notes.
The winner of the game is the player who discloses the last letter of the secret word.

Alternatively, as activation activity, the game can be played in a more disorganized manner: First the group chooses a game master. He or she will then type in the guesses the group calls in loudly.

4. Data privacy statement

All desktop versions of ASCII-Hangman run locally on your computer and do not collect or transfer any data.

The same applies to the web application version of ASCII-Hangman too: due to its Web-Assembly-technology, the program runs - once started - entirely in your Web-Browser’s sandbox and never connects to the Internet.