/**
 * 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 Component extends AcediaObject
    abstract;

//! A base class to implement components from, supposed to function as a special data storage
//! for in-game [`Entity`]s.
//!
//! On the current stage of implementation doesn't do anything by itself.

/// Creates an independent copy of the component.
///
/// This function duplicates the caller component, copying all data in an identical
/// fashion, including references to other entities (stored as [`EntityRef`]).
/// The result is a new component that is a direct copy of the original, maintaining
/// all internal states and links.
///
/// To make a new component using this one like a template use [`Component::TemplateCopy()`].
public final function Component Copy() {
    return _copy(false);
}

/// Generates a new component instance using the caller as a template.
///
/// This function uses the caller component as a template to create a new component.
/// Unlike the [`Component::Copy()`] method, references to other entities (stored as [`EntityRef`])
/// are not directly copied.
/// Instead, they are dropped, and new references are created based on the template names provided
/// by [`EntityRef`] if available.
/// This method is intended for scenarios where a new, similar instance is needed without retaining
/// direct links to the entities referenced by the original component.
public final function Component TemplateCopy() {
    return _copy(true);
}

/// Internal component copy function to avoid code duplication for copying logic in
/// [`Component::Copy()`] and [`Component::TemplateCopy()`].
///
/// This protected function serves as the core implementation for copying component instances.
/// It can operate in two modes depending on the `actAsTemplate` flag:
/// 1. When `actAsTemplate` is false, it performs a direct copy of the component,
///     replicating all data and entity references exactly as in the original component.
/// 2. When `actAsTemplate` is true, it creates a new component based on the template
///     characteristics of the caller.
///     In this mode, entity references (stored as [`EntityRef`]) are not directly copied.
///     Instead, these references are dropped, and new instances are created based on the template
///     names provided by the [`EntityRef`] if available, ensuring that the new component does not
///     retain direct links to the entities of the original.
///
/// This method should not be called directly; use `Copy()` or `TemplateCopy()` as
/// public interfaces.
/// They correspond to modes 1 and 2 respectively.
protected function Component _copy(bool actAsTemplate) {
    return none;
}

defaultproperties {
}