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. In this version 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 30 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.

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

ASCII-Hangman Web Application
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.

ASCII-Hangman Web Application
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.

Getting started

ASCII-Hangman installation

The web-app version does not need to be installed. Just navigate to ASCII-Hangman Web-App.

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.

ASCII-Hangman invocation: how to start the game

Web-App

Navigate to ASCII-Hangman-Web-App.

Linux

  1. Open a terminal

  2. Navigate to a folder containing configuration files, e.g.

    cd vocabulary-chapter-1
  3. If the folder contains only one configuration file hangman-words.txt just type

    ascii-hangman

    otherwise type, e.g.

    ascii-hangman words-page3.txt words-page5.txt

Windows

  1. Open the folder where the ascii-hangman.exe file resides.

  2. Open a second explorer window and navigate to a folder with a configuration file.

  3. Drag and drop one or more configuration files on ascii-hangman.exe.

ASCII-Hangman configuration

ASCII-Hangman needs a custom list of secrets it can choose secrets to let the user guess. This list is provided by a configuration file with a very simple syntax explained below. When you start the desktop version 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, its will read the modified list of secrets.

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

Linux configuration

  1. Run ASCII-Hangman once. It creates a configuration file ascii-hangman-words.txt in the current working directory.

  2. Edit the configuration file

    nano ascii-hangman-words.txt
  3. Start the game

    ./ascii-hangman

Windows configuration

  1. Generate a configuration file in your working directory

    Double click on ascii-hangman.exe

    This creates the file ascii-hangman_words.txt

  2. 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.

  3. Start the game

    Double-click on ascii-hangman.exe.

Synopsis and syntax

Usage: ascii-hangman
       ascii-hangman [FILE]...
       ascii-hangman -h|--help
       asciiart-ascii-hangman-for-kids -V|--version

[FILE] are configuration files containing word-lists and optionally Ascii-Art images.

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 file containing 4 different line-types:

  • lines starting with a letter, a digit or '-' are secret strings. At the beginning of the game one line is randomly chosen and all characters are hidden. If you want to give an additional hint, enclose some characters with _. The enclosed is then displayed in clear when the game starts. For example the configuration line:

    Guess _me_
    is shown in the game as:
    _ _ _ _ _ _ m e
  • lines starting with # are ignored. This can be used for comments.

  • lines starting with | are part of an optional custom ASCII-Art image shown progressively in the course of the game. If not defined here, built in ASCII-Art images are used instead.

  • lines starting with : are game modifier. They change the logic how the image is progressively disclosed:

    `:success-rewarding`       Every guessed character shows a bit more of
                               the image. This mode is default.
    `:traditional-rewarding`   Every lost live discloses a bit more of the
                               image. Choose this mode together with a
                               traditional gallows image (not built in).

Sample configuration files

Simple configuration file

guess me
hangman
good luck
3*7=21

Simple configuration file with hints

guess me
hang_man_
_good l_uck
_3*_7_=21_

Configuration file with custom image

A configuration file may contain a custom image. The image is gradually disclosed after each right guess.

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


:success-rewarding
|      !!!!\\\\
|    '`!_  ||||
|     ` \`-'''|
|       `\   /
|        )\  \
| ejm   /  \  \
|           \|

# Author: ejm

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: The image is gradually disclosed after each lost life.

- _guess _me
- hang_man_
- _good l_uck


:traditional-rewarding
|  ______
|  |    |
|  |    O
|  |   /|\
|  |    |
|  |   / \
|__|_____
||      |___
||_________|

Note: The gallows image is not part of the built-in ASCII-art. If wished for, it can be defined it the configuration file.

Play the game in the classroom

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

Classroom requirements

  • Big screen or projector

  • Browser with Internet access - or -

  • Windows or Linux Computer with ascii-hangman.exe or ascii-hangman binary installed.

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 words.

  • 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 at the screen and correct spelling mistakes.

  • The list of secrets can be recent vocabulary or calculation exercises. A secret is always encoded as one line in the configuration file and can be a word or a whole sentence of vocabulary or even a math exercise.

  • To give an additional hint it, is possible to tag a part of the secret sentence. This part will be disclosed immediately when the game starts.

  • When the game starts the computer will choose one secret of the list randomly. The teacher can play also as he does not know the next secret either. Every secret appears only once, unless it is not guessed correctly. Then it will appear again at some random time in the future.

Game rules

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

  1. The whole class is asked to write down all guessed letters on a sheet of paper.

  2. A player can guess again when when the last guess was right, meaning the secret contained the guessed letter.

  3. If not, the next player may try it. In bigger groups the next player should be chosen randomly. This incites the whole group as nobody knows who will be the next.

  4. A player is not allowed to ask others to remind him if a letter was already tried or not. He has to solely rely on his own notes.

  5. The winner of the game it the person who discloses the last letter of the secret word.

Alternatively, the game can be played in a more disorganized manner: In order to activate a group, choose a game master who will type the letters the group calls in.

Data privacy statement

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

This applies in particular to the web application version of ASCII-Hangman: due to its Web-Assembly-technology, the programm runs - once started - entirely in your Web-Browser’s sandbox without any networks connection.