API des fournisseurs

La version actuelle de l’API des fournisseurs est 1. Les noms de fournisseurs doivent être en minuscules, comporter au plus 64 caractères et ne contenir que des lettres, des chiffres, _, . ou -. Les priorités doivent être des nombres finis compris entre -100000 et 100000.

Enregistrer un fournisseur serveur

local ok, errorMessage = exports.humalike:RegisterProvider(domain, descriptor)

domain vaut player, inventory, dispatch ou actions. L’enregistrement doit provenir d’une ressource externe. Il renvoie true en cas de succès, ou false accompagné d’une raison stable et lisible lorsque le descripteur est rejeté. Chaque descripteur requiert :

Champ	Type	Description
`name`	string	Nom du fournisseur utilisé par sa convar de sélection.
`apiVersion`	number	Doit valoir `1`.
`priority`	number	En mode `auto`, la priorité disponible la plus élevée l’emporte.
`Available`	function, facultatif	Renvoie `true` lorsque les dépendances sont prêtes ; peut aussi renvoyer `false, reason`.

Descripteur joueur

Callback	Requis	Contrat
`GetCharacterId(source)`	Oui	Renvoie un id stable du personnage actif, ou `nil`.
`GetCharacterName(source)`	Oui	Renvoie le nom affiché du personnage actif, ou `nil`.
`IsCharacterLoaded(source)`	Oui	Renvoie exactement `true` lorsque l’état de jeu est prêt.
`HasJob(source, names, requireDuty)`	Non	Renvoie exactement `true` lorsqu’un des métiers demandés correspond et que les exigences de service sont satisfaites.
`Notify(source, message, kind)`	Non	Affiche une notification au joueur.

kind peut valoir success, error, warning ou inform. Traitez les types inconnus comme informatifs.

Descripteur d’inventaire

exports.humalike:RegisterProvider('inventory', {
    name = 'my_inventory',
    apiVersion = 1,
    priority = 100,
    AddItem = function(source, itemName, quantity, metadata)
        return true
    end,
})

AddItem doit renvoyer exactement true après avoir accepté l’opération. Renvoyez false pour un inventaire plein, un objet inconnu, des métadonnées invalides ou tout autre refus.

Descripteur de dispatch

exports.humalike:RegisterProvider('dispatch', {
    name = 'my_dispatch',
    apiVersion = 1,
    priority = 100,
    Report = function(kind, payload)
        return true
    end,
})

Traduisez le kind et le payload neutres vers votre ressource de dispatch. Renvoyez false uniquement lorsque le signalement a été rejeté ; nil compte comme accepté après un callback réussi.

Descripteur d’actions

exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = { 'hand_over_money' },
    RunAction = function(action, source, npcCoords, params)
        return true
    end,
})

Les clés d’action doivent commencer par une lettre minuscule, ne contenir que des lettres minuscules, des chiffres et _, et comporter au plus 64 caractères. RunAction doit renvoyer exactement true après avoir terminé ou accepté l’action ; il est facultatif pour un fournisseur dont SupportedActions est vide. Validez source, la distance par rapport à npcCoords, les permissions, les identifiants, les montants et tous les params côté serveur. Le nom de l’action ne vaut pas autorisation. Le même descripteur déclare les observations serveur que l’intégration peut signaler (voir Observations serveur) :

exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = {},
    Namespace = 'myserver',
    Observations = {
        item_given = {
            fields = { item = 'string', quantity = 'integer' },
            template = {
                en = 'the character handed you {quantity} x {item}',
                pl = 'postać wręczyła ci {quantity} x {item}',
            },
        },
    },
})

Namespace correspond à ^[a-z][a-z0-9]{1,15}$ et est requis dès que Observations n’est pas vide. Il préfixe chaque clé sur le réseau (myserver:item_given), de sorte qu’une clé serveur ne puisse jamais reproduire un type d’événement intégré.
Observations associe jusqu’à 32 clés (^[a-z][a-z0-9_]{0,31}$) à une définition comportant jusqu’à 8 fields, nommés comme des clés et typés string, integer, number ou boolean, ainsi qu’un template avec au moins l’une des langues proposées par le tableau de bord (la langue du PNJ est utilisée, sinon l’anglais, sinon la première déclarée). Chaque ligne comporte au plus 400 caractères sans caractères de contrôle, ses {placeholders} nomment des champs déclarés, et elle ne contient aucune autre accolade. Un modèle de texte est aussi dimensionné par son rendu dans le pire des cas — chaque occurrence d’espace réservé à la valeur la plus large de son champ (64 caractères pour un string, 21 pour un number, 17 pour un integer, 5 pour un boolean) — qui doit rester dans la limite de 912 caractères.

La ressource applique tout cela dans RegisterProvider : un descripteur qui enfreint une règle est rejeté avec la raison, et rien n’est enregistré.

Désenregistrer un fournisseur serveur

local ok, errorMessage = exports.humalike:UnregisterProvider(domain, name)

Seule la ressource propriétaire peut désenregistrer son fournisseur. Arrêter la ressource propriétaire effectue ce nettoyage automatiquement.

État côté serveur

local status = exports.humalike:GetProviderStatus()

Le résultat contient :

apiVersion et runtimeEpoch ;
selected, une correspondance compacte par domaine ;
domains, incluant pour chacun le réglage, l’état, la raison, le fournisseur sélectionné et tous les candidats enregistrés.

Les états sont selected, disabled, unavailable, ambiguous ou degraded. Un échec de callback dégrade le fournisseur sélectionné ; un callback réussi ultérieur efface l’état d’échec.

Enregistrer un fournisseur d’interaction client

local ok, errorMessage = exports.humalike:RegisterInteractionProvider({
    name = 'my_target',
    apiVersion = 1,
    priority = 100,
    Available = function() return true end,
    watchedResources = { 'my-target' },
    Add = function(id, entity, options) return true end,
    Remove = function(id) end,
    Progress = function(durationMs, label) return true end,
})

Add et Remove sont requis. Progress est facultatif. Add doit renvoyer exactement true lorsque l’enregistrement réussit. Progress renvoie exactement true une fois terminé et false en cas d’annulation ou d’échec. watchedResources liste les dépendances dont le démarrage ou l’arrêt doit déclencher une réévaluation du fournisseur.

exports.humalike:UnregisterInteractionProvider('my_target')
local status = exports.humalike:GetInteractionProviderStatus()

L’état côté client rapporte apiVersion, runtimeEpoch, le réglage, l’état, la raison et le fournisseur sélectionné.

Événement ready

AddEventHandler('humalike:integration:ready', function(info)
    print(info.apiVersion, info.runtimeEpoch)
end)

L’événement est local et émis indépendamment côté serveur et côté client après chaque démarrage de Humalike. Enregistrez à nouveau les fournisseurs de ce côté lorsqu’il se déclenche.

Premiers pas

Configurer

Intégrer

Exploiter

API des fournisseurs

Enregistrer un fournisseur serveur

Descripteur joueur

Descripteur d’inventaire

Descripteur de dispatch

Descripteur d’actions

Désenregistrer un fournisseur serveur

État côté serveur

Enregistrer un fournisseur d’interaction client

Événement ready

Suite

​Enregistrer un fournisseur serveur

​Descripteur joueur

​Descripteur d’inventaire

​Descripteur de dispatch

​Descripteur d’actions

​Désenregistrer un fournisseur serveur

​État côté serveur

​Enregistrer un fournisseur d’interaction client

​Événement ready

​Suite

Enregistrer un fournisseur serveur

Descripteur joueur

Descripteur d’inventaire

Descripteur de dispatch

Descripteur d’actions

Désenregistrer un fournisseur serveur

État côté serveur

Enregistrer un fournisseur d’interaction client

Événement ready

Suite