perk_ms_h.fos

/**
 *  Perk: Mysterious Stranger   -   Header
 *
 *  Description:
 *      From time to time, a mysterious stranger will help the player, regarding the rules below.
 *          0.  If the MS (Mysterious Stranger) dies, it will not spawn for X hours.
 *          1.  Spawn rate of MS shall depend both on the players Charisma and Luck.
 *              1.a. Chance for MS to spawn at random encounter: X + Y * CH + U * LK (Min V, Max Z)
 *              1.b. Chance for MS to spawn for FA: X + CH * LK * U (Min V, Max Z)
 *              1.c. Chance for MS to spawn for Doctor: X + CH * LK * U (Min V, Max Z)
 *              1.d. If MS fails to spawn for FA or Doctor, a separate cooldown shall trigger: X / CHA;
 *                      (This is needed because of mechanics, else whenever a crippled player gets attacked by someone,
 *                       it will have an extra chance to spawn MS, changing the mechanic.)
 *          2.  Special spawns shall depend on the players Charisma and the frequency on Luck.
 *              2.a. Player drops below half a % of HP, chance for MS to spawn and try to FA the player.
 *              2.b. Player gets crippled, chance for MS to spawn and try to FA and then Doctor the Player.
 *              2.c. Player (not in group) spawns in the random encounter of the player, chance for MS to appear, warn and stay for a duration.
 *              2.d. Special and normal spawns have a global cooldown.
 *          3.  Players Charisma shall also affect the duration, cool down and strength of the MS.
 *              3.a. Duration of aid lasts X + Y * CH turns in TB combat.
 *              3.b. Duration of help lasts X + Y * CH seconds in RT combat.
 *              3.c. Cooldown of special spawns and base MS spawn depends on CH: CD = X / CH minutes.
 *              3.d. Level of MS shall be 3 levels higher than the owner.
 *              3.e. Perk, stat and weapon composition of MS shall be better if the player has higher CH.
 *              3.f. If the players Luck is below X, the MS may have the Jinxed Trait. Good luck!
 *          4.  AI of MS:
 *              4.a. If the player is attacked, the attacker is added to the MS's target list.
 *              4.b. MS will try to FA the player, as long as he is in a reachable distance, if not, he will tell him to move closer.
 *              4.c. MS will try to FA the player, if he is knocked out or in negative HP, but not dead.
 *              4.d. If another player is attacking the owner, MS shall change target to it, possibly changing to a crowd control weapon, like rocket launcher or sniper riffle.
 *          5.  Integration into projects/servers:
 *              5.a. All of the parameters of the MS mechanic, shall be configurable.
 *              5.b. Special triggers shall be disableable with macros from header.
 *              5.c. Solutions shall be done without modifying crucial parts of modules, like combat.fos.
 *              5.d. Integration shall be documented in the tutorial as well.
 *
 *  Author:     Slowhand
 *  Reviewer:   n/a
 *  Tested by:  Slowhand
 *              Check perk_ms_test.fos for test details.
 *  Known bugs: MS will skip first TB turn and has much more AP than it should. (15 instead of 10)
 */

/**< TODO:  1. CRITTER_EVENT_TURN_BASED_PROCESS
 *              - These events never get called, so I removed them, when SDK is ready, it can be added for TB AI.
 *          2. Add different weapon arsenal to the 3rd level Mysterious Stranger.
 *          3. Check character model compatibility with weapon types.
 *          4. Fix the problem with repeatable FA/Doctor spawn. In case MS failed to spawn, it shall not try until some time.
 *          5. Do the 1.d part, as that is missing. (in progress)
 */

#ifndef __PERK_MS_H__
#define __PERK_MS_H__

/**< Debug log for Mysterious Stranger perk */
#define __MS_ALLOW_DEBUG_LOG__                          //  comment this line to disable debug mode for Mysterious Stranger perk related stuff.

#ifdef __MS_ALLOW_DEBUG_LOG__
    #define MS_LOG                      # (__s)     { Log(__s); }
#endif
#ifndef __MS_ALLOW_DEBUG_LOG__
    #define MS_LOG                      # (__s)     {; }
#endif


/**< Model parameters for different strength if the Mysterious Stranger */
#define MS_PID_LEVEL1                   (36)        //  Gun thug, male, leather jacket. 36 - 408
#define MS_PID_LEVEL2                   (403)       //  Leather jacket slaver guard.
#define MS_PID_LEVEL3_BOS               (468)       //  APA Brotherhood of Steel guard.
#define MS_PID_LEVEL3_ENC               (292)       //  APA Enclave guard.
#define MS_PID_LEVEL3_GR                (518)       //  CA Gun Runners guard.
#define MS_PID_LEVEL3_NRC               (475)       //  NCR Ranger.

/**< AI package used, the values have been modified at npc_ai.fos to support this perk. */
#define MS_AI_PACK_USED                 (AIPACKET_MYSTERIOUS_STRANGER)

/**< Duration and cooldown parameters */
#define MS_BASE_RESPAWN_CD              (6000)      //  MS base spawn CD time in real seconds
#define MS_BASE_MEDICAL_SPAWN_BLOCK_CD  (100)       //  MS base medical spawn CD time in real seconds
#define MS_BASE_DEATH_CD                (72000)     //  MS base re-birth time in real seconds
#define MS_BASE_RT_DURATION             (20)        //  MS base duration in RT mode
#define MS_RT_DURATION_FACTOR           (10)        //  MS duration extension factor in RT mode


/**
 *  Chance to spawn at encounter parameters
 *  Formula:    X + Y * CH + U * LK (Min V, Max Z)
 *  Function:   bool shallMsSpawnOnEncounter(uint playerId)
 */
#define MS_ENC_BASE_CHANCE              (5)
#define MS_ENC_CHA_CHANCE_FACTOR        (2)
#define MS_ENC_LK_CHANCE_FACTOR         (1)
#define MS_ENC_MIN_CHANCE               (5)
#define MS_ENC_MAX_CHANCE               (35)

/**
 *  Chance to spawn when player below HP limit.
 *  Formula:    FA: X + CH * LK (Min V, Max Z)
 *  Function:   bool shallMsSpawnForFirstAid(uint playerId)
 */
#define MS_FA_BASE_CHANCE               (25)
#define MS_FA_CHANCE_FACTOR             (5)
#define MS_FA_MIN_CHANCE                (25)
#define MS_FA_MAX_CHANCE                (65)

/**
 *  Chance to spawn when player is crippled.
 *  Formula:    FA: X + CH * LK (Min V, Max Z)
 *  Function:   bool
 */
#define MS_DOC_BASE_CHANCE               (35)
#define MS_DOC_CHANCE_FACTOR             (5)
#define MS_DOC_MIN_CHANCE                (35)
#define MS_DOC_MAX_CHANCE                (85)

/**<
 * Add TC town maps, or any other map that MS shall not appear at.
 * Other options are to disable Mysterious Stranger in TC towns with location.isTCTown(), but this way other towns can be disabled as well.
 * Note: Only the base map of the TC maps is disabled, so the MS could spawn in other areas of the map, like the mines in Redding or Broken Hills.
 */
array<string> disabledMsMaps = {"den", "klamath", "modoc", "gecko", "broken", "redding"};

#endif  //  __PERK_MS_H__