Interactables

The interactable system lets entities in the scene be targeted and interacted with by the player. Chests, NPCs, doors, crafting stations, and collectibles all use this system.

IInteractable Interface

Any component that implements IInteractable can be targeted and interacted with by the player's InteractorEntity:

public interface IInteractable
{
    string DisplayName { get; }
    float IndicatorYOffset { get; }
    float IndicatorDistance { get; }
    float CanInteractDistance { get; }

    bool IsInIndicatorRange { get; }
    bool IsInInteractRange { get; }
    bool IsTargeted { get; }
    bool CanInteract { get; }

    void SetInIndicatorRange(bool value);
    void SetInInteractRange(bool value);
    void SetTargeted(bool value);
    void Interact(GameObject interactor);
    void UpdateRequirementsCheck();
}

Properties

Property	Description
DisplayName	Text shown in the interaction prompt (e.g., "Open Chest", "Talk to Blacksmith").
IndicatorYOffset	Vertical offset for the interaction indicator above the object.
IndicatorDistance	Distance at which the interaction indicator becomes visible.
CanInteractDistance	Distance at which the player can actually interact.
IsInIndicatorRange	Whether the player is close enough to see the indicator.
IsInInteractRange	Whether the player is close enough to interact.
IsTargeted	Whether the player is currently looking at this interactable.
CanInteract	Whether interaction is currently possible (requirements met, not locked, etc.).

Methods

Method	Description
SetInIndicatorRange(bool)	Called by InteractorEntity when range state changes.
SetInInteractRange(bool)	Called by InteractorEntity when range state changes.
SetTargeted(bool)	Called by InteractorEntity when targeting state changes.
Interact(GameObject)	Called when the player activates the interaction.
UpdateRequirementsCheck()	Called to re-evaluate whether interaction is allowed.

Creating Custom Interactables

Implement IInteractable on a MonoBehaviour and add it to a GameObject with a collider:

using UnityEngine;

public class TreasureChest : MonoBehaviour, IInteractable
{
    [SerializeField] private string chestName = "Treasure Chest";
    [SerializeField] private float indicatorDistance = 8f;
    [SerializeField] private float interactDistance = 3f;
    [SerializeField] private string lootTableId;

    private bool _isOpen = false;

    public string DisplayName => _isOpen ? "Empty Chest" : chestName;
    public float IndicatorYOffset => 1.5f;
    public float IndicatorDistance => indicatorDistance;
    public float CanInteractDistance => interactDistance;
    public bool IsInIndicatorRange { get; private set; }
    public bool IsInInteractRange { get; private set; }
    public bool IsTargeted { get; private set; }
    public bool CanInteract => !_isOpen;

    public void SetInIndicatorRange(bool value) => IsInIndicatorRange = value;
    public void SetInInteractRange(bool value) => IsInInteractRange = value;
    public void SetTargeted(bool value) => IsTargeted = value;

    public void Interact(GameObject interactor)
    {
        if (_isOpen) return;
        _isOpen = true;

        // Roll the loot table and give items to the player
        var entity = interactor.GetComponent<SparkEntity>();
        if (entity == null) return;

        Spark.Network?.ExecuteCommand(new RollLootTableCommand
        {
            LootTableId = lootTableId,
            TargetEntityId = entity.EntityId
        });
    }

    public void UpdateRequirementsCheck()
    {
        // Re-check if the chest can be interacted with
    }
}

The InteractorEntity on the player handles detection via camera raycasting. When the player aims at an object with an IInteractable component and is within range, the interaction system activates.

InteractableObjectEntity

The Interactables plugin provides a built-in InteractableObjectEntity component for simple interactable objects. Instead of writing a custom class, you can add this component to a GameObject and configure its behavior through the inspector and triggers.

Interaction Flow

1. Player moves near an interactable. SetInIndicatorRange(true) is called. The indicator appears.

2. Player aims at the interactable. SetTargeted(true) is called. The indicator highlights.

3. Player moves within interact distance. SetInInteractRange(true) is called. The interact prompt appears.

4. Player presses the interact key. Interact(interactorGameObject) is called. The action happens.

5. Player moves away. The range/target methods are called with false.

InteractablesManager

The InteractablesManager singleton coordinates interaction UI. It receives updates from InteractorEntity and manages the display of interaction indicators and prompts.

Best Practices

• Keep Interact() lightweight. Execute commands rather than doing heavy logic directly.

• Use CanInteract to gate interactions (locked doors, already-looted chests, cooldowns).

• Set appropriate distances for indicator and interact ranges. Indicators should be visible from further away than the interact range.

• Add colliders to interactable objects. The raycast system needs colliders to detect them.

• Use UpdateRequirementsCheck() when external conditions change (player gains a key item, time of day changes).