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 include an operation which does not fit into one of the four action kinds (re: above), 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);