Action Management ~ End Conditions Design

Team Action Management - End Conditions Design (Eric Chang)

---

Introduction

As of writing this, the only way to end a game is if a player moves into a "final room." This document describes the design of an additional game-ending mechanism: the game ends if specific items have been interacted with such that their attributes have been changed to an "end state." After the implementation of this feature, a game can end in three different ways:

1. A player moves into a "final room"
2. Specific items have been interacted with appropriately
3. A combination of the above two methods

---

Mechanism Overview

How will this new mechanism be implemented?

• The file include/game-state/item.h includes definitions for a game_action_condition_t struct, which would appropriately store an end condition. This struct contains:
  • a pointer to an item
  • a pointer to an attribute to check
  • the expected value of the attribute
• include/game-state/item.h also contains a definition for an action_condition_list_t, which would appropriately store a list of end conditions.
• This list will be stored in the game_t struct defined in include/game-state/game.h as the field action_condition_list_t *end_conditions.

How can end conditions be added to a game?

The following function (which would add an end condition to a game's list of end conditions) would be added to game state's game module:

int add_end_condition_to_game(game_t *game, game_action_condition_t *end_condition)

Parameters:

• game - the game to which end_condition should be added to
• end_condition - the new end condition for this game

Returns:

• FAILURE if the end condition cannot be added to the game. This can occur if:
  • the item in end_condition is not already part of the game
  • the attribute to check does not exist or is not an attribute of the item
• SUCCESS if the end_condition is successfully added to the game.

A note to WDL: since add_end_condition_to_game requires the item referenced in end_condition to already be a part of a game, end conditions should not be added to a game until after items have been added.

How will end conditions be checked during a game?

The following function (which would check if all end conditions have been met) would be added to game state's game module:

bool end_conditions_met(game_t *game)

Parameters:

• game - the game to check the end conditions of

Returns:

• true if:
  • all end conditions have attributes with their expected values
  • no end conditions exist (end_conditions is NULL)
• false if the attribute of at least one end condition does not match with its expected value

How will end conditions be removed from a game?

The following function (which would delete and free all game_action_condition_ts from an action_condition_list_t) would be added to game state's item module:

int delete_action_condition_llist(action_condition_list_t *head)

Parameters:

• head - pointer to the first element in the list

Returns:

• SUCCESS always

---

Utilizing this Mechanism

• add_end_condition_to_game
  • Used by WDL when loading games into chiventure
  • Note that this function must be used AFTER loading in items into a game
  • While I go into detail in how the following functions are used, I am not doing that with this function. Determining how exactly add_end_condition_to_game will be utilized is a problem for WDL to work out. Since I am on the action management team and I will already be changing the code of game state to implement the functions, I or my team will likely be doing the work of integrating the other two functions into the code, so I went ahead and thought about how this can be done.
• end_conditions_met
  • Used by action management in the actionmanagement module after an action is successfully completed to determine if the game is over
  • In do_item_action and do_item_item_action, in the else block that executes if the action is successfully carried out:
    • Use sprintf to add game_act->success_str to string (note that this code is already implemented)
    • Check if the final room exists AND the current room is the final room AND end_conditions_met returns true
      • If this test evaluates to true, append a congratulatory message (similar to that on line 168) to string
    • Set the value of ret_string to that of string (note that this code is already implemented)
    • Return SUCCESS (note that this code is already implemented)
  • In do_path_action:
    • Switch the placements of the if (move == SUCCESS) and else if (move == FINAL_ROOM) so that the check for the final room comes first
    • Change the conditional statement move == FINAL_ROOM to move == FINAL_ROOM && end_conditions_met(g)
    • Change the conditional statement move == SUCCESS to move == SUCCESS || move == FINAL_ROOM
• delete_action_condition_llist
  • Used by game state in the game_free function found in the game module to free the end_conditions field of a game.
  • I don't know if it matters whether this function is called before delete_all_rooms or after since both might be trying to free the same items - keep this in mind as a likely culprit if there's some nasty looking error from this area of the code

---

Implementation Details

• int add_end_condition_to_game(game_t *game, game_action_condition_t *end_condition):
  • Check that end_condition->item exists using HASH_FIND
    • If item does not exist, return FAILURE
  • Check that the end_condition->item contains end_condition->attribute_to_check
    • If this check fails, return FAILURE
    • Get attribute key, use get_attribute, see if return value and original attribute point to same value/place in memory
  • Set end_condition->next to game->end_conditions
  • Set game->end_conditions to end_condition
• bool end_conditions_met(game_t *game)
  • If game->end_conditions is NULL return true
  • Create new pointer iterator to game->end_conditions
  • Loop while iterator->next is not NULL:
    • if not check_condition(iterator) return false
  • At this point, all conditions have been checked and confirmed to be their expected values - return true
• int delete_action_condition_llist(action_condition_list_t *head):
  • For each node, free node
  • I don't think freeing item or attribute_to_check is necessary since delete_all_rooms should free them (again though if there's an error I suspect this would be a cause)

---

Final Notes

• To use end_conditions_met, the headers of do_item_action and do_item_item_action would need to be changed so that it is passed an additional parameter: a context struct chiventure_ctx_t *c like that found as the first parameter of do_path_action
  • A search via get grep -n do_item_action reveals that the only places in code that use this function are in:
    1. src/cli/src/operations.c:161 - the function that contains this line of code is itself passed a context struct, so updating the call would be simple
    2. tests/action_management/test_item_actions.c - this would require creating a dummy context struct to pass along
  • A search via get grep -n do_item_item_action reveals that the only places in code that use this function are in:
    1. src/cli/src/operations.c:231 - the function that contains this line of code is itself passed a context struct, so updating the call would be simple
    2. tests/action_management/test_item_item_actions.c - again, this would require creating a dummy context struct to pass along
• I don't have any other actual notes. This design is probably way more detailed than is actually necessary, but I wanted to get as many details ironed out as possible dangit.