Why the Player Struct?

After discussion with other RPG teams, previous iterations of the action-management/game-state team determined that chiventure should include functionalities to allow games to interact with a "player" struct throughout the course of a game. This player struct would allow developers to easily track the progress of a player throughout a game session. The addition of a player struct would also open future possibilities for chiventure to support multi-player games, where every person playing a game could be given an their own respective player struct to keep track of their status.

The Player Struct

This year (Spring 2021) the action-management team has updated the player struct, and its respective player module to meet these desired changes. Players (as of 5/30/2021) are now currently defined as:

/* A player in game */
typedef struct player {
    /* hh is used for hashtable, as provided in uthash.h*/
    UT_hash_handle hh;

    /* Unique id identifying the player */
    char *player_id;

    /* The player's current level */
    int level;

    /* The cumulative total of experience points acquired by the player */
    int xp;

    /* A string containing the player's race */
    char *player_race;

    /* The player's current class. class_t contains the base stats, and skills for that class at
    the beginning of a game. These may change throughout the game, so their current states are stored 
    in the health, player_stats, player_skills fields in this player struct */
    class_t *player_class;

    /* All of the stats, with their values, the player has. This should include
    both the maximum and current health if health is a feature of the current game */
    stats_hash_t *player_stats;

    /* The current skills known to the player */
    skill_inventory_t *player_skills;

    /* All of the effects the player is currently experiencing */
    effects_hash_t *player_effects;

    /* The current items held by the player*/
    item_hash_t *inventory;
} player_t;

The player module also significantly reduces cognitive load when updating data structures associated with a player. Now, developers only need to use the player_t struct and call the player module's respective function to update the various data structures that contain different information for a player. For example: a developer interested in simultaneously damaging the player's health stat and giving them a "poison" effect does not need to individually retrieve the stats_hash_t required by the change_stat() function and an effects_hash_t struct for add_stat_effect(); instead, they only need to use the player_t struct and use the player module's associated player_change_stat() and player_add_stat_effect() functions.

Creating a new player

New player_t structs in chiventure are currently created using the player_new() function. This function only takes in one string argument for the player's ID. Despite the many fields in a given player_t struct, game developers may not wish to use every RPG feature in their games. For this reason, creating a new player will only initialize a player ID. Other fields in a player struct can be updated using many of the functions described in player.h.

One important field of note is player_t's player_class field. Classes, as currently stored in class_t structs, are intended to store basic information about a playerclass that will set starting values for players who choose a given class. For this reason, the player_set_class() function is unique in that it will create deep copies in memory to copy over the starting information of a class.

As of (5/30/2021), class_t objects are defined as:

/* A player class struct storing the name, descriptions, attributes, stats, 
 * stat effects, skill inventories, and skill tree associated with a class. */
typedef struct class {
    // Name of the class
    char* name;

    // Number of parent classes
    int num_parent_class;

    // All base classes that have been multiclassed into
    char **parent_class_names;

    // A short description of the class
    char* shortdesc;

    // A long description of the class
    char* longdesc;

    // An object containing all the attributes of the class
    obj_t* attributes;

    // All the base_stats of the class
    stats_hash_t* base_stats;

    // Effects on the class
    effects_hash_t* effects;

    // Class skilltree
    skill_tree_t* skilltree;

    // Class skills
    skill_inventory_t* starting_skills;

    // Memory used internally by the UTHASH macros
    UT_hash_handle hh;
} class_t;

The player_set_class() function will create deep copies of the effects, base_stats, and starting_skills fields in a given class_t struct, and will store these copies in a player_t's respective player_effects, player_stats and player_skills fields. Deep copying these fields is necessary to preserve the data in a class_t object if the player later changes their class throughout a game, or if multiple players decide to be the same class.

The Player Module

Many of the functions included in player.h and player.c are solely used as "wrapper" functions that call a RPG module's respective function with the associated struct stored in a player_t struct. This means that functions will need to be continually added/updated to reflect new functionalities implemented by RPG teams.

The current plan (which is mostly implemented) for integrating the functionalities provided by modules of other RPG teams into the player module is outlined in our interface plan.

Currently, the player module has implemented all desired functions outlined in the Stats/Effects (Issue #952), Skilltrees (also Issue #952), and Playerclass (Issue #1057) sections of the plan. The quests and battle sections will be implemented by Issues #1058 and #1053 respectively.

Future Plans for the Player Module

As described earlier, the player module will need to be continuously updated to accommodate new features created by other RPG teams. It is likely that that some functions that are updated by RPG teams in their own modules will break the corresponding wrapper function in the player module. We recommend that a member of action-management or game-state should review any necessary updates to the player module that is made to allow chiventure to build.

Additionally, while many of the functionalities provided in the player module are intended to track the player's status throughout a game, there is little implementation that actually uses these functions throughout the course of a game. Future issues should be created to integrate the player module with the game flow.