Enhanced CLI ~ How to Implement a New Action Operation

This page concerns the process of adding a new action to Chiventure from beginning to end.

Note: there are already groups of actions that are grouped into 4 kinds (5/23/2022). If you have a command that matches these types of input, there is a distinct workflow. These are:

1. ACTION <item>

• Such as take chair

2. ACTION <path>

• Such as go north

3. ACTION <item> <item>

• Such as put orb on chair

4. ACTION <self>

• These are actions that involve some attribute about the player, like quests, stats, class, etc...
  • Such as view stats

Implementing a Completely New and Independent Action

This would be for implementing a unique action that does not follow the formatting of any of the 4 types of actions. Previous examples include view, quit, and credits.

First, define an operation

In the operations.h file, you will find many commands with the following type ascription:

char *operation(char *tokens[TOKEN_LIST_SIZE], chiventure_ctx_t *ctx);

This is the formatting all operation functions must fall under, where tokens is an array of strings outputted from parsing the command line input, and ctx is the chiventure context struct which holds basically all other relevant information about the game.

How to design an operation function

Once you've decided to implement a new action type that is NOT any of the existing types, you need to actually write your function! Usually as CLI we are validating the input to make sure it has the correct parameters, such that we can feed those parameters into someone else's function. Generally, it will have the following control flow: (in pseudocode)

char *operation(char *tokens[TOKEN_LIST_SIZE], chiventure_ctx_t *ctx)
{
  if (game is null) 
    return status message

  if (missing game element, like curr_room == NULL)
     return status message

  if (too few or too many arguments
    return status message

  else
    //often there will be a string which we pass by reference into another groups function, 
    char *return_string;
    run someone else's function

}

Note about tokens:

As of now (5/23/2022) the list of tokens will contain just the action word in the first slot, then

Update the Command Hash Table

At this point, chiventure probably will not recognize your input and run your new operation because it won't recognize your action token.

To fix this, you have to add the function and the associated action command verb (e.g. fight, talk, help, look) to a hash table of commands. This hash table is created upon the start of a game as a lookup_t struct (defined in cmd.h), and is initialized with all possible action commands and operations.

To do so, you must call the add_entry function directly in the lookup_t_init function. It should follow this format:

add_entry("LOOK",look_operation, NULL, t);

1. The first argument is the action you want in all caps.
2. The second argument is the name of the operation you want to call with this action. This operation should follow the general operation function type as defined above.
3. The third argument is NULL, since this operation is not one of the four action kinds (re: above).
4. The fourth argument is t, which is the name of the hash table that your operation and command will be stored in. It is the parameter of lookup_t_init.

Now that your action is recognized by chiventure, you should add it to be a possible suggestion to the user. In the operations.c file, there is an array of strings called actions_for_sug and a global variable called NUM_ACTIONS. Add your new action in all caps to the end of the array, and increment the NUM_ACTIONS variable by 1.

Congrats! At this point, after recompiling, your input should be recognized and run your operation.