INTERACTV - PLUGINS
====================
Drop any .dll file here to register custom actions usable in scene XMLs.
Plugins are loaded at startup — restart the game (or reload scripts) after adding one.


WHAT A PLUGIN DOES
------------------
A plugin adds a new action name that can be used in <Actor action="MY_ACTION"/> steps.
The engine calls your plugin factory to create the state instance when that action fires.


BUILT-IN ACTIONS USED BY SHIPPED SCENES
---------------------------------------
These action names are understood by the engine in <Step type="..."> and <Actor action="...">.
Use one of these names; an unknown action falls back to IDLE.

  AI brain          : AUTO_REACT (alias DYNAMIC_AI)
  Movement / social : LOOK, APPROACH, PURSUE, FOLLOW, POSITION_SIDEWALK, IDLE, WANDER, HOLD,
                      STARE, ARGUE (alias VERBAL), SHOVE, THREATEN, BACK_DOWN, STAGGER, OUTRO,
                      PLAY_ANIM, SCENARIO (alias PLAY_SCENARIO), SURRENDER
  Combat            : AIM, COMBAT, MELEE_COMBAT, RELOAD, FLEE, FLEE_VEHICLE, COWER, WARNING_SHOT,
                      THROW_PROJECTILE
  Vehicle           : DRIVE_BY, DISMOUNT_ASSAULT, PARK_VEHICLE, FOLLOW_VEHICLE, CARJACK,
                      EXIT_VEHICLE, RETURN_VEHICLE
  Gang              : GANG_SURRENDER
  Police / arrest   : COP_APPROACH, COP_DRIVE_APPROACH, COP_IDLE, COP_SCENARIO, COP_RADIO,
                      COP_CALL_BACKUP, COP_TACTICAL, COP_TASER, COP_NATIVE_ARREST, ARREST_ON_FLOOR,
                      COP_CUFF, COP_ESCORT_SUSPECT, SUSPECT_ALERTED, SUSPECT_KNEEL, SUSPECT_PRONE,
                      SUSPECT_KNEEL_LOOP, SUSPECT_STANDUP, SUSPECT_HANDS_UP, SUSPECT_WALK_TO_CAR,
                      SUSPECT_ENTER_CAR, DEPARTURE, COP_RETURN_VEHICLE
  Ambulance         : REVIVE_TARGET, PATIENT_BOARD, MEDIC_ESCORT, MEDIC_BOARD, MEDIC_DEPART

To add another action, create a plugin as described below instead of inventing an unregistered name.


HOW TO WRITE A PLUGIN
----------------------
1. Create a .NET Framework 4.8 Class Library.
2. Reference InteractV.Plugin.dll (ships alongside InteractV.dll).
3. Implement the ICustomState interface:

   public interface ICustomState
   {
       string ActionName { get; }   // the XML action name, e.g. "MY_ACTION"

       StateBase Create(
           GTA.Ped actor,
           GTA.Ped target,
           ActorAction action,
           StepDefinition step,
           SceneContext context,
           Config config);
   }

4. StateBase is the base class for all ped states. Implement Process() and set
   IsDone = true when the state is finished. DisplayName identifies it in logs.

5. Build your DLL and drop it in this folder.

6. Reference your action in a scene XML:
   <Actor id="A" action="MY_ACTION" target="B" />


EXAMPLE SKELETON
----------------
using InteractV.Plugin;
using InteractV.Runtime;
using InteractV.Models;
using InteractV.Configuration;

public class MyActionFactory : ICustomState
{
    public string ActionName => "MY_ACTION";

    public StateBase Create(GTA.Ped actor, GTA.Ped target,
        ActorAction action, StepDefinition step,
        SceneContext context, Config config)
    {
        return new MyActionState(actor, target);
    }
}

public class MyActionState : StateBase
{
    private readonly GTA.Ped _actor;
    private readonly GTA.Ped _target;

    public MyActionState(GTA.Ped actor, GTA.Ped target)
    {
        _actor = actor;
        _target = target;
    }

    public override string DisplayName => "MY_ACTION";

    public override void Process()
    {
        // your logic here, called every frame while the step is active
        IsDone = true; // set when the state is complete
    }
}
