6. String constants in the template game

6.1. Modify the strings in the game

(found in text_constants.py)

The string GAME_INSTRUCTIONS_TEACHERS explains the game for teachers. It could be used for the command line or web app versions of the game.

The string GAME_QUESTION_CHILDREN is a very simple game question that can be understood by a child.

The string GAME_INSTRUCTIONS_CHILDREN is for very simple game instructions that can be understood by a child. It might describe a story for the game, in the way that most Bebras-style tasks are introduced with a one or two sentence story.

The string SCIENCE_FACT_CHILDREN is a gimmick that is designed to draw the child into the game by relating some fact about a topic that children would already be familiar with. It should be an interesting child-friendly scientific/historical/geographical fact that could appeal to the widest possible range of children, and that is somehow related to the story in the game. It should not be related to computer science, unless it is some aspects of computer technology that is widely known or used.

Tip

The SCIENCE_FACT_CHILDREN string can be filled in later. Usually it is only evident later in the game development (during the web app creation) what would be most interesting to put here.

6.1.1. Parameterised text strings

Sometimes the text strings need to be dynamically modified, depending on the data randomly generated for that particular game round. The parameterised text strings can be specified here and then values given to those parameters in the function construct_cl_formatted_strings() (explained below) when the game round is defined.

Count from Zero defines the following parameterised text string:

GAME_QUESTION_CHILDREN = 'Which truck number has {} ?'
"""A very simple game question that can be understood by a child."""

Molecules defines the following parameterised text string:

GAME_QUESTION_CHILDREN = 'How many {} molecules can be made using these?'
"""A very simple game question that can be understood by a child."""

Pollen defines the following parameterised text string:

GAME_QUESTION_CHILDREN = '''\
        How much pollen can the bee get? It can carry {} pollen per
        flight and can make {} flights.'''
"""A very simple game question that can be understood by a child."""

Kangaroo defines the following parameterised text string:

GAME_QUESTION_CHILDREN = 'What jumps will collect {} {}{}?'
"""A very simple game question that can be understood by a child."""

6.2. Modify the function construct_cl_formatted_strings()

(found in cl.py)

The CTGames framework prints some default strings and applies some default text formatting for the command-line versions of games. These strings include the problem instance, question, rules text, custom parameters, and so on. These defaults are to get your command-line games up and running as quickly as possible. However, you may want to customise these strings. One type of customisation is pretty printing the string or making it more human readable. Another modification is injecting information from the game state that might change from game round to game round.

The function construct_cl_formatted_strings() is the only function that appears by default in the file cl.py from a game newly created using the template. The purpose of this function is to customise the strings that will be printed during the command-line version of your game. Some of these customised strings will also be re-used by default in the web app version of your game.

Tip

The function construct_cl_formatted_strings() is only needed if customisation of text strings in the command-line version of the game is desired. A lot of useful game state information is printed by default if the returned dict is empty (and even if this function is not defined at all). If you are happy with the default information printed then this function does not need to be modified.

The most common usage of this function is to bring elements of the player’s game state into the strings, and for this reason the framework passes game_state (the named tuple with the player’s game state) as a parameter to the function. The function returns a dict named formatted_strings. The keys in formatted_strings recognised by the CTGames framework (of which the ones other than the first three are rarely used) are

'problem_instance'

A pretty printed version of the problem instance

'question'

A modified version of the question for children

'rules_text'

The rules for the current round; an empty string is stored by default if no rules are defined

'custom_state_info'

A string representation of the custom game state information (most games will not need to modify this)

'multiple_choice_answers'

The multiple choice answers, if an MCQ game, formatted as a single string, each prepended with one of ‘A)’, ‘B)’, ‘C)’, and so on, and each separated separated with ‘\n’ (most games will not need to modify this)

'players_answer'

Feedback for the player: a specially formatted version of the player’s answer (most games will not need to modify this)

'correct_answer'

Feedback for the player: the correct answer (most games will not need to modify this)

'helpful_comment'

Feedback for the player: a helpful comment (most games will not need to modify this)

Note

In most cases, modifications to these strings are visible in the web app versions of games (e.g. the question string). However, modifications to the 'correct_answer' string affect the command-line version of the game only, and will not carry forward to the web app version of a game. This is to allow more flexibility in the web app versions of games compared with the command-line versions. To change the formatting of the correct answer in the web app version of a game, one should use the function format_correct_answer() in file x/webapp/__init__.py where x is the game’s directory.

If no string is given for a particular key in formatted_strings, a sensible default is given by the CTGames framework.

6.2.1. Examples

Several games change the problem instance string, for example, Ordered List

# Add a string with the problem instance
problem_instance = f'The list is: {original_list}'
formatted_strings.update({'problem_instance': problem_instance})

and Just Addition

# Add a string with the problem instance
operator = '-' if subtraction else '+'
problem_instance = f'The sum is: {pair[0]} {operator} {pair[1]} ='
formatted_strings.update({'problem_instance': problem_instance})

Some games modify the question string, although this is often not needed as the same question is appropriate for each game round, e.g. “Which path is shortest?” For example, in Count from Zero

# Add a formatted string with the question
question = GAME_QUESTION_CHILDREN.format(PRIZE)
formatted_strings.update({'question': question})

Molecules changes…

Pollen changes…

Kangaroo changes…

As another example, the game Ordered updates the rules text, problem_instance, and the question in this function.