Aller au contenu principal

Créer un plugin

InteractV peut charger des actions personnalisées depuis vos propres fichiers .dll, sans toucher au code du mod lui-même. Cela permet d'ajouter une toute nouvelle action de PNJ et de l'utiliser dans un scénario XML, exactement comme une action intégrée.

Ce que fait un plugin​

Un plugin ajoute un nouveau nom d'action utilisable dans une étape de scénario, par exemple <Actor action="MY_ACTION" />. Quand cette action se déclenche, InteractV appelle votre plugin pour créer l'objet qui l'exécute réellement. Les plugins sont chargés au démarrage, donc redémarrez le jeu (ou rechargez les scripts) après en avoir ajouté un.

Un plugin peut aussi réutiliser le nom d'une action déjà intégrée. Si c'est le cas, votre plugin prend le dessus sur le comportement intégré pour cette action.

Noms d'actions intégrées​

Avant d'écrire un plugin, vérifiez si ce que vous voulez existe déjà. Voici les principaux noms d'action que le mod reconnaît actuellement. Si l'action est inconnue, le mod journalise un avertissement et retombe sur IDLE.

  • Cerveau : AUTO_REACT (alias DYNAMIC_AI)
  • Déplacement / social : LOOK, APPROACH, PURSUE, FOLLOW, POSITION_SIDEWALK, IDLE, WANDER, HOLD, STARE, ARGUE (alias VERBAL), SHOVE, THREATEN, BACK_DOWN, STAGGER, OUTRO, PLAY_ANIM, PLAY_SCENARIO (alias SCENARIO), SURRENDER, HANDSHAKE, HIGHFIVE, HUG, INSULT_GESTURE, HEADBUTT, MENACE, CONFRONT, INTERROGATE, STANDOFF, TAKE_HOSTAGE
  • Combat : AIM, COMBAT, MELEE_COMBAT, RELOAD, FLEE, FLEE_VEHICLE, COWER, WARNING_SHOT, THROW_PROJECTILE, EXECUTION_SHOT, TAKEDOWN
  • Véhicule : DRIVE_BY, PARK_VEHICLE, FOLLOW_VEHICLE, CARJACK, EXIT_VEHICLE, ENTER_VEHICLE, RETURN_VEHICLE, OPEN_TRUNK, CLOSE_TRUNK, BLOCK_VEHICLE
  • Gang : GANG_SURRENDER, SUICIDE_BOMB, DEAL_SUICIDE_BOMB, ROBBERY_GIVE_MONEY, TORCH_VEHICLE
  • Police / arrestation : COP_APPROACH, COP_DRIVE_APPROACH, COP_IDLE, COP_SCENARIO, COP_RADIO, COP_CALL_BACKUP, COP_TACTICAL, COP_TASER, COP_NATIVE_ARREST, COP_FOOT_CHASE, COP_FOOT_CHASE_DUO, COP_CUFF, COP_CUFF_SIMPLE, COP_UNCUFF, COP_DIVE_TACKLE, COP_BATON, COP_PURSUIT, COP_SEARCH, COP_SEARCH_VEHICLE, COP_ESCORT_SUSPECT, PATDOWN, ARREST_ON_FLOOR, SUSPECT_ALERTED, SUSPECT_KNEEL, SUSPECT_KNEEL_LOOP, SUSPECT_PRONE, SUSPECT_STANDUP, SUSPECT_HANDS_UP, SUSPECT_WALK_TO_CAR, SUSPECT_ENTER_CAR, SUSPECT_DROP_FLOOR, SUSPECT_GETUP_STATE, SUSPECT_EXIT_VEHICLE_ON_COMMAND, DEPARTURE, COP_RETURN_VEHICLE
  • Ambulance / secours : REVIVE_TARGET, MEDIC_TREAT, MEDIC_CPR, MEDIC_ESCORT, RESCUE_VICTIM, PATIENT_BOARD

Cette liste reflète le catalogue actuellement livré : si vous pensez qu'une action utilisée par une scène devrait exister ici et n'y est pas, elle a probablement été renommée ou déplacée entre deux versions. Vérifiez le log du mod (les actions inconnues journalisent un avertissement et retombent sur IDLE) et gardez vos scènes synchronisées avec la version que vous lancez.

Comment écrire un plugin​

  1. Créez une bibliothèque de classes .NET Framework 4.8.
  2. Ajoutez une référence à l'assembly InteractV.Plugin (ou à InteractV.dll compilée en mode développement, qui contient ICustomState et les types dont votre plugin a besoin : StateBase, ActorAction, StepDefinition, SceneContext, Config), ainsi que ScriptHookVDotNet3.dll pour GTA.Ped.
  3. Implémentez ICustomState :
public interface ICustomState
{
    string ActionName { get; }   // le nom d'action XML, ex. "MY_ACTION"

    StateBase Create(
        GTA.Ped actor,
        GTA.Ped target,
        ActorAction action,
        StepDefinition step,
        SceneContext context,
        Config config);
}
  1. StateBase est la classe de base de tous les états de PNJ. Implémentez Process() (appelée à chaque frame tant que votre état est actif) et passez IsDone = true quand il est terminé. Redéfinissez DisplayName pour identifier votre état dans les logs. OnEnter() / OnExit() sont des points d'entrée optionnels pour l'initialisation/le nettoyage.
  2. Compilez votre DLL et déposez-la dans scripts/InteractV/plugins/. Le mod crée ce dossier au premier lancement s'il n'existe pas.
  3. Référencez votre action depuis un scénario XML :
<Actor id="A" action="MY_ACTION" target="B" />

Exemple de base​

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()
    {
        // votre logique ici, appelée à chaque frame tant que l'étape est active
        IsDone = true; // à passer à true quand l'état est terminé
    }
}

À savoir​

  • La surface API publique sur laquelle reposent les plugins (le contrat ICustomState et ses types) reste stable entre les versions ; un plugin compilé pour une version continue de fonctionner après une mise à jour, tant que ce contrat n'a pas changé.
  • Documentez vous-même les actions de votre plugin. La liste d'actions intégrées ci-dessus ne couvre que ce qui est livré avec InteractV.