from __future__ import annotations

from engine.character import Character
from engine.defs import DefRegistry
from engine.inventory import Inventory
from engine.world import World


def open_companion_inventory(
    actor: Character,
    world: World,
    registry: DefRegistry,
    aim_direction: tuple[int, int, int],
    slot: str,
) -> Inventory | None:
    """Opens the equipped inventory (e.g. a saddlebag) worn by an adjacent companion NPC - a
    companion dog wearing a dog_saddlebag being the sample case. Returns None if there's no
    Character adjacent in that direction, the target is the actor themself, or nothing worn at
    `slot` grants an inventory (get_equipped_inventory already covers that last case).

    This is a targeted variant of Character.get_equipped_inventory - that method reads a
    character's own gear, this one reads a companion's, gated on being next to them.
    """
    assert actor.position is not None
    dx, dy, dz = aim_direction
    ahead = (actor.position.x + dx, actor.position.y + dy, actor.position.z + dz)
    target = world.entity_at(actor.position.map_id, *ahead)
    if not isinstance(target, Character) or target is actor:
        return None
    return target.get_equipped_inventory(slot, registry)