API dostawcy

Aktualna wersja API dostawcy to 1. Nazwy dostawców muszą być pisane małymi literami, mieć co najwyżej 64 znaki i zawierać wyłącznie litery, cyfry, _, . lub -. Priorytety muszą być skończonymi liczbami z przedziału od -100000 do 100000.

Rejestracja dostawcy serwerowego

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

domain to player, inventory, dispatch lub actions. Rejestracja musi pochodzić z zewnętrznego zasobu. Zwraca true przy powodzeniu albo false wraz ze stałym, czytelnym dla człowieka powodem, gdy deskryptor zostanie odrzucony. Każdy deskryptor wymaga:

Pole	Typ	Opis
`name`	string	Nazwa dostawcy używana przez convar wyboru.
`apiVersion`	number	Musi wynosić `1`.
`priority`	number	W trybie `auto` wygrywa wyższy dostępny priorytet.
`Available`	function, opcjonalne	Zwróć `true`, gdy zależności są gotowe; opcjonalnie zwróć `false, reason`.

Deskryptor gracza

Callback	Wymagany	Kontrakt
`GetCharacterId(source)`	Tak	Zwróć stabilny id aktywnej postaci lub `nil`.
`GetCharacterName(source)`	Tak	Zwróć wyświetlaną nazwę aktywnej postaci lub `nil`.
`IsCharacterLoaded(source)`	Tak	Zwróć dokładnie `true`, gdy stan rozgrywki jest gotowy.
`HasJob(source, names, requireDuty)`	Nie	Zwróć dokładnie `true`, gdy jedna z żądanych prac pasuje i warunki służby są spełnione.
`Notify(source, message, kind)`	Nie	Wyświetl graczowi powiadomienie.

kind może być success, error, warning lub inform. Nieznane rodzaje traktuj jako informacyjne.

Deskryptor ekwipunku

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

AddItem musi zwrócić dokładnie true po przyjęciu operacji. Zwróć false przy pełnym ekwipunku, nieznanym przedmiocie, nieprawidłowych metadanych lub każdym innym odrzuceniu.

Deskryptor dispatch

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

Przetłumacz neutralne kind i payload na wywołania swojego zasobu dispatch. Zwróć false tylko wtedy, gdy zgłoszenie zostało odrzucone; nil po udanym callbacku liczy się jako przyjęcie.

Deskryptor akcji

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

Klucze akcji muszą zaczynać się małą literą, zawierać wyłącznie małe litery, cyfry i _ oraz mieć co najwyżej 64 znaki. RunAction musi zwrócić dokładnie true po wykonaniu lub przyjęciu akcji; jest opcjonalne dla dostawcy, którego SupportedActions jest puste. Waliduj na serwerze source, odległość od npcCoords, uprawnienia, identyfikatory, kwoty oraz wszystkie params. Nazwa akcji nie jest autoryzacją. Ten sam deskryptor deklaruje obserwacje serwerowe, które integracja może zgłaszać (zobacz Obserwacje serwerowe):

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 pasuje do ^[a-z][a-z0-9]{1,15}$ i jest wymagane, gdy tylko Observations jest niepuste. Poprzedza każdy klucz przesyłany po sieci (myserver:item_given), więc klucz serwera nigdy nie pokryje się z wbudowanym typem zdarzenia.
Observations mapuje do 32 kluczy (^[a-z][a-z0-9_]{0,31}$) na definicję z maksymalnie 8 fields, nazwanymi jak klucze i typowanymi jako string, integer, number lub boolean, oraz template z co najmniej jednym z języków oferowanych w panelu (używany jest język NPC, w przeciwnym razie angielski, a w ostateczności pierwszy zadeklarowany). Każda linia ma co najwyżej 400 znaków bez znaków sterujących, jej {placeholders} nazywają zadeklarowane pola i nie zawiera innych nawiasów klamrowych. Szablon jest też mierzony według najgorszego przypadku renderowania — każde wystąpienie symbolu zastępczego w najszerszej wartości jego pola (64 znaki dla string, 21 dla number, 17 dla integer, 5 dla boolean) — który musi mieścić się w 912 znakach.

Zasób egzekwuje to wszystko w RegisterProvider: deskryptor łamiący regułę jest odrzucany wraz z powodem i nic nie zostaje zarejestrowane.

Wyrejestrowanie dostawcy serwerowego

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

Tylko zasób będący właścicielem może wyrejestrować swojego dostawcę. Zatrzymanie właściciela wykonuje to czyszczenie automatycznie.

Status serwera

local status = exports.humalike:GetProviderStatus()

Wynik zawiera:

apiVersion i runtimeEpoch;
selected, zwięzłą mapę według domen;
domains, w tym każde ustawienie, stan, powód, wybranego dostawcę i wszystkich zarejestrowanych kandydatów.

Stany to selected, disabled, unavailable, ambiguous lub degraded. Błąd callbacku degraduje wybranego dostawcę; późniejszy udany callback czyści stan błędu.

Rejestracja klienckiego dostawcy interakcji

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 i Remove są wymagane. Progress jest opcjonalne. Add musi zwrócić dokładnie true, gdy rejestracja się powiedzie. Progress zwraca dokładnie true po ukończeniu oraz false po anulowaniu lub niepowodzeniu. watchedResources wymienia zależności, których uruchomienie/zatrzymanie ma wywołać ponowną ocenę dostawcy.

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

Status kliencki raportuje apiVersion, runtimeEpoch, ustawienie, stan, powód oraz wybranego dostawcę.

Zdarzenie ready

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

Zdarzenie jest lokalne i emitowane niezależnie na serwerze i kliencie po każdym uruchomieniu Humalike. Gdy się pojawi, zarejestruj ponownie dostawców dla danej strony.

Pierwsze kroki

Konfiguracja

Integracja

Obsługa

Rejestracja dostawcy serwerowego

Deskryptor gracza

Deskryptor ekwipunku

Deskryptor dispatch

Deskryptor akcji

Wyrejestrowanie dostawcy serwerowego

Status serwera

Rejestracja klienckiego dostawcy interakcji

Zdarzenie ready

Dalej

​Rejestracja dostawcy serwerowego

​Deskryptor gracza

​Deskryptor ekwipunku

​Deskryptor dispatch

​Deskryptor akcji

​Wyrejestrowanie dostawcy serwerowego

​Status serwera

​Rejestracja klienckiego dostawcy interakcji

​Zdarzenie ready

​Dalej

Rejestracja dostawcy serwerowego

Deskryptor gracza

Deskryptor ekwipunku

Deskryptor dispatch

Deskryptor akcji

Wyrejestrowanie dostawcy serwerowego

Status serwera

Rejestracja klienckiego dostawcy interakcji

Zdarzenie ready

Dalej