Written in response to Issue #944 to create documentation for future implementation of the interface for the player module. This page will discuss possible functions and additions to existing player functionality, and will be especially concerned with adding functionality for interacting with new fields in the player struct added in Pull Request #898.

The Current Player Struct

Currently, a player in Chiventure is stored in player.h as:

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_race, player_class, player_stats, player_skills, and player_effects all have been recently introduced into the struct, and thus are not often interacted with in the current interface.

Interface Wishlist

We intend for the new fields to be accessed/modified throughout the course of the game. Having discussed (In progress) with the playerclass, skilltrees, and quests team, they desire to interact with the playermodule in the following ways:

Playerclass

Classes, as currently stored in class_t objects, are intended to store basic information about a playerclass that will set starting values for players who choose a given class.

/* A player class struct storing the name, descriptions, attributes,
 * and stats */
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;

Currently, we intend for the starting_skills, effects and stats fields to set the respective player_skills, player_effects, and player_stats fields when a class is selected. These fields within the player struct can then be modified/added to over the course of a game.

To allow for class_t objects to fully serve this purpose, the player module will need to include

• An updated player_set_class() function that also initializes the player_skills, player_effects and player_stats fields. This will require deep copy functionality for these fields.

Skilltrees

We currently predict that basic getter/setter functions to access player skills will be required. These functions may be:

• player_add_skill() to add a given skill to the player's skill inventory
• player_remove_skill() to remove a given skill
• player_has_skill() to check if a player has a given skill

Quests

After discussion with the quest team, a player_quests field should be added to the player struct to keep track of currently assigned quests. We can use existing functionality within the quests module to create the following functions:

• player_assign_quest() to add a quest to the quests field (calling start_quest() in quests_state.c)
• player_quest_status()/player_is_quest_completed() to get the status of given quest (calling get_quest_status() or is_quest_completed() in quests_state.c)
• player_complete_achievement() to mark given achievement for given quest as completed (calling complete_achievement() in quests_state.c )
• player_complete_quest() to mark given quest as complete and give reward item to player (calling complete_quest() in quests_state.c and the existing add_item_to_player() in the player module, as well as player_is_quest_completed())

Stats/Effects

The player's stats may need to be updated for a variety of reasons during a game. This would be accomplished by:

• player_change_stat and player_change_stat_max to change a current stat and held by the player (calling change_stat and change_stats_max in stats.c)
• player_get_current_stat to return the current value of the request stat (calling get_current_stat in `stats.c)
• player_add_stat to add a new stat to the player (calling in add_stat in stats.c)
• Similar functions for adding effects to stats (will be implemented once stat functionality exists)

Battles

(UPDATE: the battles team is taking responsibility for this) After discussion with the battles team, they mentioned that the player struct should include a player_moves field to store any moves that they player may make during a battle. Existing functionality for battles represents players in combat through combatant_t structs. The only extra functions that the player interface would need to provide to facilitate the creation of an associated combatant_t struct would be:

• player_get_moves and player_set_moves to retrieve and set the moves that a player uses as a combatant during battle