<?php

namespace Adventurebook;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Security check
}

interface Combat_System {

	/**
	 * each combat system has a description
	 *
	 * @return string The description of the combat system.
	 */
	public function get_combat_system_description(): string;

	/**
	 * Execute a combat round between the character and the enemies.
	 *
	 * @param Character $character The character engaging in combat.
	 * @param array $enemies An array of enemies the character is fighting against.
	 * @return array An array containing the results of the combat round. (strings)
	 */
	public function do_combat(Character $character, array $enemies) : array;

	/**
	 * each combat system has a name
	 *
	 * @return string The name of the combat system.
	 */
	public function get_name() : string;

	/**
	 * each combat system has a description
	 * that contains the main features of the combat system
	 *
	 * @return string The description of the combat system.
	 */
	public function get_description() : string;

	/**
	 * each combat system has a label for the character
	 * e.g. Character, Hero, Adventurer, Pilgrim etc.
	 *
	 * @return string The label for the character in the combat system.
	 */
	public function get_character_label(): string;

	/**
	 * Execute the player's attack on an enemy.
	 *
	 * @param Character $player The character performing the attack.
	 * @param Enemy $enemy The enemy being attacked.
	 *
	 * @return array An array containing the results of the player's attack. (strings)
	 */
	public function player_attack_enemy(Character $player, Enemy $enemy) : array;

	/**
	 * Handle the action of an enemy during its turn.
	 * It sets the enemies' next action before it is executed in the doCombat method.
	 *
	 * @param Enemy $enemy The enemy taking the action.
	 * @param Character $player The character that the enemy is interacting with.
	 */
	public function enemy_handle_action(Enemy $enemy, Character $player);

	/**
	 *  Execute the enemy's attack on the player.
	 *
	 * @param Enemy $enemy The enemy performing the attack.
	 * @param Character $player The character being attacked.
	 *
	 * @return array An array containing the results of the enemy's attack. (strings)
	 */
	public function enemy_attack_player(Enemy $enemy, Character $player) : array;

	/**
	 * each combat system restricts the values that are shown for an item
	 * for example, some combat systems do not use certain stats
	 *
	 * @param array $stats An associative array of item stats.
	 * @return array An associative array of item stats to be shown.
	 */
	public function get_item_stats_to_show(array $stats): array;

	/**
	 *  the item stats that need to be instantiated for an item of this combat system
	 *
	 * @return array An array of item stat names that need to be instantiated.
	 */
	public function get_item_stats_to_be_instantiated(): array;

	/**
	 *  the initial stats for a new character
	 *
	 * @return array An associative array of initial character stats.
	 */
	public function get_initial_character_stats(): array;

	/**
	 *  get the name of the item stat that represents the item price
	 *
	 * @return string The name of the item stat used for price.
	 */
	public function get_item_stat_name_for_price(): string;

	/**
	 *  get the wealth/price unit, e.g. "gold", "coins", "gems", etc.
	 *
	 * @return string The wealth unit used in the combat system.
	 */
	public function get_wealth_unit(): string;

	/**
	 *  get the abbreviated combat stats output for a combatant
	 *  e.g. for characters: Ini +x, Atk +x, etc.
	 *  used in character overview
	 *
	 * @param AbstractCombatant $combatant The combatant for which to get the combat stats output.
	 *
	 * @return array An associative array of strings with the output
	 */
	public function get_combat_stats_output( AbstractCombatant $combatant): array;

	public function get_combat_stats_output_long( AbstractCombatant $combatant): array;

	/**
	 * Returns the combat strength output for a combatant.
	 * It is compared to the average combat strength of all enemies in the adventurebook.
	 *
	 * You are stronger than xyz. You are equal to xyz. You are weaker than xyz.
	 *
	 * @param Character $character
	 *
	 * @return string
	 */
	public function get_combat_strength_output( Character $character ): string;

	/**
	 *  get the abbreviated combat stats output for an item
	 *  e.g. for weapons: Ini +x, Atk +x, etc.
	 *  used in character overview
	 *
	 * @param Item_Definition $item The item for which to get the combat stats output.
	 * @return array An associative array of strings with the output
	 */
	public function get_item_combat_stats_output( Item_Definition $item ): array;


	#region SKILLS

	/**
	 *  check if a combatant can raise a specific skill
	 *
	 * @param AbstractCombatant $combatant The combatant to check.
	 * @param string $skill_name The name of the skill to check.
	 *
	 * @return bool True if the combatant can raise the skill, false otherwise.
	 */
	public function combatant_can_raise_skill( AbstractCombatant $combatant, string $skill_name ): bool;
	public function combatant_get_skill_cost_for_next_skill_level( AbstractCombatant $combatant, string $skill_code ): int;

	public function combatant_raise_skill( AbstractCombatant $combatant, string $skill_name ): array;

	public function combatant_use_skill( AbstractCombatant $combatant, string $skill_name ): array;


	/**
	 *  get the list of available skills in this combat system
	 *
	 *  structure:
	 *
	 * $skills = [
	 * 'climbing' => [
	 * 'name' => 'Climbing',
	 * 'description' => 'Allows you to climb walls and obstacles more easily.',
	 * 'cooldown' => 0,
	 * 'max_level' => 5,
	 * 'base_cost' => 50,
	 * 'cost_multiplier' => 1.5,
	 * ],
	 * 'firstaid' => [
	 * 'name' => 'First Aid',
	 * 'description' => 'Allows you to treat your wounds.',
	 * 'cooldown' => 20,
	 * 'max_level' => 8,
	 * 'base_cost' => 100,
	 * 'cost_multiplier' => 2,
	 * ],
	 *
	 * ];
	 *
	 *
	 * @return array An array of skills available in the combat system.
	 */
	public function get_available_skills(): array;

	/**
	 * get the skill by its code
	 */
	public function get_skill_by_code(string $skill_code): array;

	#endregion

    #region Resources

    /**
     *  return a list of all available resources in this combat system
     *
     */
    public function get_available_resources(): array;

    public function get_resource_yield_for_page(int $page_id, string $code): int;

    public function get_skill_code_for_harvesting_resource(string $resource_code): ? string;

}