TiedUp-/src/main/java/com/tiedup/remake/state/ICaptor.java

package com.tiedup.remake.state;

import net.minecraft.world.entity.Entity;

/**
 * C6-V2: Narrowed parameters from IRestrainable to IBondageState (minimum needed type)
 *
 * Interface for entities that can capture other entities (players or NPCs).
 *
 * Terminology:
 * - "Captive" = Entity attached by leash (active physical control)
 * - "Slave" = Entity wearing a collar owned by someone (passive ownership via CollarRegistry)
 *
 * Design Pattern:
 * - Interface-based design allows both players (PlayerCaptorManager)
 *   and NPCs (EntityKidnapper) to act as captors
 * - Separates concerns: ICaptor manages captives, IBondageState is managed
 *
 * Implementation:
 * - PlayerCaptorManager: For player captors
 * - EntityKidnapper: For NPC captors
 *
 * @see IBondageState
 * @see PlayerCaptorManager
 */
public interface ICaptor {
    // Captive Management

    /**
     * Add a captive to this captor's captive list.
     * Called when capture succeeds.
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param captive The IBondageState entity to capture
     */
    void addCaptive(IBondageState captive);

    /**
     * Remove a captive from this captor's captive list.
     * Called when freeing a captive or when captive escapes.
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param captive The IBondageState captive to remove
     * @param transportState If true, also despawn the transport entity
     */
    void removeCaptive(IBondageState captive, boolean transportState);

    /**
     * Check if this captor can capture the given target.
     *
     * Conditions (from original):
     * - Target must be tied up OR have collar with this captor as owner
     * - Target must not already be captured
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param target The potential IBondageState captive
     * @return true if capture is allowed
     */
    boolean canCapture(IBondageState target);

    /**
     * Check if this captor can release the given captive.
     * Only the current captor can release their captive.
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param captive The IBondageState captive to check
     * @return true if this captor is the captive's captor
     */
    boolean canRelease(IBondageState captive);

    // Configuration

    /**
     * Whether this captor allows captives to be transferred to other captors.
     *
     *
     * @return true if captive transfer is allowed (default for players)
     */
    boolean allowCaptiveTransfer();

    /**
     * Whether this captor can have multiple captives simultaneously.
     *
     *
     * @return true if multiple captives allowed (default for players)
     */
    boolean allowMultipleCaptives();

    // Event Callbacks

    /**
     * Called when a captive logs out while captured.
     * Allows the captor to handle cleanup or persistence.
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     * Note: For NPC captives, this may never be called (NPCs don't log out)
     *
     * @param captive The IBondageState captive that logged out
     */
    void onCaptiveLogout(IBondageState captive);

    /**
     * Called when a captive is released (freed).
     * Allows the captor to react to losing a captive.
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param captive The IBondageState captive that was released
     */
    void onCaptiveReleased(IBondageState captive);

    /**
     * Called when a captive attempts to struggle.
     * Allows the captor to react (e.g., shock collar activation).
     *
     * C6-V2: Narrowed from IRestrainable to IBondageState
     *
     * @param captive The IBondageState captive that struggled
     */
    void onCaptiveStruggle(IBondageState captive);

    // Queries

    /**
     * Check if this captor currently has any captives.
     *
     *
     * @return true if captive list is not empty
     */
    boolean hasCaptives();

    /**
     * Get the entity representing this captor.
     * Used for lead attachment and position queries.
     *
     * @return The entity (Player or custom entity)
     */
    Entity getEntity();
}