Game State ~ How to implement a new CLI mode

When working on our run_battle function, Emilio, Nafis, and I realized we would need to switch our mode into battle mode, but we were unsure how to do so and what exactly that meant. This document goes through how to switch to the desired mode and how CLI works in each mode. We will use the battle mode as an example.

How does the CLI use modes?

The cli loop has four main steps:

1. it takes a user input.
2. it runs the mode_operation function for its current mode.
3. it takes the string returned by the mode_operation and prints it as a prompt.

The mode_operation in NORMAL mode parses the user's input and searches a hash table of commands for the command the user inputted, then runs the command operation function designated to that command (e.g. the PULL entry in the hash table has a value pull_operation()) the given operation function is run and the return string printed as a prompt.

If the cli mode is changed by set_game_mode(), a different mode_operation will be run.

What is a mode?

The chiventure_ctx of a given game contains a mode struct:

/* Mode data type */
typedef struct game_mode {
    mode_type_t curr_mode;
    mode_operation *run_mode; //the mode's run function
    char* mode_ctx; //for specifying mode's context, e.g. npc_id
} game_mode_t;

curr_mode specifies the mode, currently either NORMAL, CONVERSATION, or BATTLE.

run_mode is a mode_operation function which has to be a function in the form:

  int mode_operation(char *str, cli_callback callback_func, void *callback_args, chiventure_ctx_t *ctx);

mode_ctx is just a string that describes the battle (e.g. "fight Gandalf the Grey") for an instance of the battle mode.

the mode tells the cli how to handle an input by specifying a mode_operation that takes an input string and returns an output/prompt string.

What is a cli_callback function?

A CLI callback function prints the given string to the CLI. A callback function takes in a pointer to a Chiventure context struct, a string to be printed as a result of running this command, and additional arguments. See cli/cmd.h for more information.

How to implement a mode:

The first step in the process is adding the desired entry to the normal mode. The add_entry function will take in a command name, operation of added entry, an action type, and a lookup table.

For example, this is what adding the entry for the fight operation would look like:

add_entry("FIGHT", fight_operation, NULL, ctx->cli_ctx->table);

Now, the CLI knows to switch to battle mode when a player inputs "FIGHT <enemy". It does so with the fight operation. The fight operation is a CLI operation for starting a fight, and it will check if the enemy name that was inputting is valid. If it is, the CLI will print the beginning string of the battle and start the first turn of the battle. For different modes, the keyword will be different--for example, you can enter NPC conversation mode by typing "TALK ".

Now that the CLI has switched to the desired mode, it will run the mode with the corresponding run function found in game-state/mode.h. For example, the run_battle_mode will now parse user input and run another turn of the fight. Once the fight is over, the mode will be switched back to regular mode.

While the battle mode was used in this example, this may be applied to all modes, such as the NPC conversation mode.

In summary, to implement a mode, you need to add support for it in set_game_mode in game_state/mode.c, write a function in the mode module that runs any setup that you need before the mode starts running and then returns the first line to be printed, then add it as an entry in the cli/operations module. Finally you need to write a mode_operation that takes an input string and calls callback_func to send back an output string.