/**
 * Author: dkanus
 * Home repo: https://www.insultplayers.ru/git/AcediaFramework/AcediaCore
 * License: GPL
 * Copyright 2024 Anton Tarasenko
 *------------------------------------------------------------------------------
 * This file is part of Acedia.
 *
 * Acedia is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, version 3 of the License, or
 * (at your option) any later version.
 *
 * Acedia is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Acedia.  If not, see <https://www.gnu.org/licenses/>.
 */
class WeaponComponent extends Component
    abstract;

//! A base class for weapon components that must, at the very minimum, support
//! a list of weapon fire modes, along with supported ammunition.

/// Describes all supported ammunition types by listing them inside an array.
///
/// This type was created to avoid possible issues with arrays of arrays
/// that arise with use of [`WeaponComponent::GetSupportedAmmo()`] and
/// [`WeaponComponent::SetSupportedAmmo()`].
struct SupportedAmmunitionTypes {
    var public array<Text> types;
};

/// Returns array with entity references to this weapon's fire modes.
///
/// Referred entities (or entity templates) are guaranteed contain
/// [`WeaponFireControlComponent`] component.
public function array<EntityRef> GetFireModes();

/// Changes available fire modes for the given weapon.
///
/// Referred entities (or entity templates) must contain
/// [`WeaponFireControlComponent`] component, otherwise they would not qualify
/// as "fire modes".
public function SetFireModes(array<EntityRef> newFireModes);

/// Returns array with supported ammunition types for this weapon's fire modes
/// with the same index.
///
/// The array structure and its interpretation are highly
/// implementation-specific.
/// While some implementations may strictly enforce these as the only
/// permissible ammunition types, others may use them as flexible guidelines,
/// useful for modding scenarios or when dealing with expansive customizations.
/// This method provides a foundation for indicating ammo compatibility but
/// allows extensive freedom in how it's applied.
///
/// Length of the returned array is guaranteed to match that of the one returned
/// by the [`WeaponComponent::GetFireModes()`].
public function array<SupportedAmmunitionTypes> GetSupportedAmmo();

/// Changes the array that lists supported ammunition types for this weapon's
/// fire modes. Each array of types corresponds to the fire mode with
/// the same index.
///
/// Implementations can choose to strictly adhere to this list or use it as
/// a basis for recommendations, influencing how mods and game mechanics
/// interpret ammunition flexibility.
///
/// The length of the provided array must match that of
/// the one returned by the [`WeaponComponent::GetFireModes()`], ensuring
/// consistency across fire modes.
public function SetSupportedAmmo(array<SupportedAmmunitionTypes> newSupportedAmmunition);

/// Returns array with entity references to ammunition that are currently being
/// used by this weapon's fire mode with the same index.
///
/// This method allows for a broad interpretation of what can be used
/// as ammunition, catering to a wide range of implementations.
/// In some game setups, virtually any entity recognized by the engine might be
/// loaded and used as ammo.
/// This is why referred entities might not be considered supported by the
/// [`WeaponComponent::GetSupportedAmmo()`] method.
///
/// Length of the returned array is guaranteed to match that of the one returned
/// by the [`WeaponComponent::GetFireModes()`].
public function array<EntityRef> GetLoadedAmmo();

/// Returns array with entity references to ammunition that are currently being
/// used by this weapon's fire mode with the same index.
///
/// This method allows for a broad interpretation of what can be used
/// as ammunition, catering to a wide range of implementations.
/// In some game setups, virtually any entity recognized by the engine might be
/// loaded and used as ammo.
/// This is why specified entities might not be considered supported by the
/// [`WeaponComponent::GetSupportedAmmo()`] method.
///
/// Length of the specified array must match that of the one returned
/// by the [`WeaponComponent::GetFireModes()`].
public function SetLoadedAmmo(array<EntityRef> newAmmunition);

defaultproperties {
}