AI Core

Integracja własnego skryptu

Jak Twój resource współpracuje z AI Core - wczytanie liba, wywoływanie warstw zamiast innych skryptów, czego nigdy nie wolno ruszać i lista kontrolna przed wydaniem.

Twój skrypt nie musi być skryptem ai-*, żeby działać z AI Core. To, co masz zrobić, zależy od tego, co piszesz:

Co maszCo zrobić
Skrypt napisany pod ESX, QBCore, Qbox lub vRPNic. AI Core udostępnia es_extended, qb-core, qbx_core i vrp oraz odpowiada na ich API, więc skrypt działa bez zmian. Zobacz Kompatybilność.
Twój własny nowy resource (Lua, TypeScript lub czysty JavaScript)Wczytać liba i wołać AI Core przez niego. O tym jest ta strona.
Skrypt, który dostarcza coś, czego potrzebują inne skrypty (ekwipunek, telefon, system kluczy, garaż, skrypt paliwa...)To samo co wyżej plus adapter w tej warstwie, żeby reszta serwera go dosięgła. Zobacz Polecane skrypty.

Cel w jednym zdaniu: wszystko, co Twój skrypt dzieli z innym skryptem, idzie przez liba albo ai-core, nigdy przez eksporty tego skryptu. Właściciel może wtedy wymienić ekwipunek, system kluczy czy telefon, a Twój skrypt dalej działa.

Wczytaj liba

Lua

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

dependency 'ai-lib'
shared_script '@ai-lib/init.lua'

client_script 'client.lua'
server_script 'server.lua'

aiLib.<name> jest potem dostępne w każdym pliku Twojego resource'a. Pełna konfiguracja, które wywołania czekają i jak tablice oraz wektory Lua przechodzą do TypeScriptu: Lib dla Lua.

TypeScript

server.ts
import { inventory, onClientCallback } from "@aifivem/lib/server";

@aifivem/lib pochodzi z npm: resource poza workspace'em AI Core instaluje go przez bun install @aifivem/lib @aifivem/shared. Czysty resource JavaScript bez kroku budowania wczytuje @ai-lib/dist/server.js i używa tego samego globalnego aiLib.

Kolejność startu

ai-core i ai-lib startują przed Twoim resource'em:

server.cfg
ensure ai-core
ensure ai-lib
ensure my-resource

Wołaj AI Core, nie drugi skrypt

Każde wspólne zadanie ma jedne drzwi. Wywołanie liba i eksport ai-core robią to samo; użyj tego, co pasuje do Twojego języka.

Czego potrzebujeszLuaTypeScriptDokumentacja
Dać, zabrać, zliczyć przedmiotyaiLib.inventory.addIteminventory.addItemPrzedmioty, przedmioty ai-core
Przedmiot do użyciaaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Skrytka albo sklepaiLib.inventory.registerStashinventory.registerStashPrzedmioty
Kluczyki do pojazduaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasPojazdy
Zespawnować pojazd (tablica, paliwo, wygląd, kluczyki i miejsca w jednym wywołaniu)aiLib.spawnVehiclespawnVehiclespawnVehicle
Wstawić do garażu albo odholowaćaiLib.garages.storegarages.storegarages.store
Pieniądze graczaexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Pieniądze
Pieniądze między dwoma kontami, w jednej transakcjiaiLib.money.transfermoney.transfermoney.transfer
Prace, gangi, służbaexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Prace i gangi
Kto jest online, jego imię, jego pracaaiLib.online.nameonline.nameGracze
Zgłoszenie dla policjiaiLib.dispatch.alertdispatch.alertdispatch.alert
WięzienieaiLib.prison.jailprison.jailprison.jail
Wpis w MDTaiLib.mdt.recordmdt.recordmdt.record
Reanimacja, leczenie, "czy leży"aiLib.medical.revivemedical.revivemedical.revive
Telefon (numer, mail, wiadomość, powiadomienie)aiLib.phone.numberphone.numberTelefon
Wygląd, strójaiLib.appearance.applyappearance.applyappearance.apply
Pogoda i czasaiLib.world.setWeatherworld.setWeatherŚwiat
Zamknąć drzwiaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Powiadomienia, paski postępu, menu, okna wpisywaniaaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuWspólny interfejs
Wpis w menu radialnymaiLib.radial.addradial.addradial.add
Komenda (widoczna w panelu admina, sprawdzana przez ACE)aiLib.addCommandaddCommandaddCommand
Linia logu na kanałach właścicielaaiLib.aiLogaiLogaiLog

Który skrypt odpowiada na każdą z tych rzeczy na tym serwerze i lista adapterów: Warstwy i bridge. Każda funkcja z sygnaturą, parametrami i zwracaną wartością: Dokumentacja API.

Nigdy nie pytaj tabel AI Core. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned i pozostałe tabele ai_* są wewnętrzne: postacie, pieniądze, prace i pojazdy żyją w pamięci i są zapisywane w rytmie ai-core, więc bezpośredni SELECT może być przedawniony, a kolumna może się zmienić w każdym wydaniu. Zapytaj ai-core - odpowiada zarówno o wczytanego gracza, jak i o zapisaną postać (postacie, pieniądze, prace). To samo dotyczy plików danych innego skryptu ai-* (data/*.json jego panelu): to treść panelu, nie interfejs.

citizenid to nie id postaci. Są dwa id: id postaci (charId, liczba) i citizenid (tekst), którego używają skrypty innych frameworków. Nigdy nie przeliczaj jednego na drugie samodzielnie - zapytaj ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Postacie.

Rozpoznanie AI Core

Lua
local onAiCore = GetResourceState('ai-core') == 'started'

W TypeScripcie lib robi to za Ciebie: isResourceStarted("ai-core") albo optionalExport("ai-core"), który jest null, dopóki resource jest zatrzymany (eksporty).

Skrypt wspierający kilka frameworków zobaczy też qbx_core, qb-core i es_extended jako wystartowane, bo ai-core je udostępnia. Ta droga działa, ale dosięga tylko tego, co te API potrafią powiedzieć. Sprawdź ai-core przed nazwami frameworków i wybierz ścieżkę AI Core, gdy jest dostępna; kod frameworka zostaw jako zapas dla innych serwerów.

Zasady, według których ocenia się Twój skrypt

To te same zasady, których trzyma się każdy skrypt ai-* (Przegląd), i na to patrzy recenzja:

Decyduje serwer

Każde żądanie klienta przechodzi przez bramkę liba: limit częstotliwości, jedno wywołanie naraz (lock), sprawdzenie ACE, a w TypeScripcie dodatkowo stróże (admin, ma postać, blisko punktu) i parser argumentów. Pieniądze, przedmioty i uprawnienia nigdy nie zmieniają się na kliencie, a wartość od klienta nigdy nie jest używana taka, jaka przyszła - w Lua każdy argument sprawdzasz sam.

server.lua
aiLib.onClientCallback('myshop:buy', function(source, item)
    if type(item) ~= 'string' or #item > 32 then return aiLib.fail('CORE_ERR_ARGS') end
    if not aiLib.inventory.canCarryItem(source, item, 1) then return aiLib.fail('INVENTORY_FULL') end
    -- tutaj, na serwerze, pobierz pieniądze i wydaj przedmiot
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Wejście od klienta, surowe czytniki TypeScriptu (readText, oneArg) i odmowy (fail, ActionResult).

Snapshot, potem delty

Dane na żywo idą do klienta raz w całości, potem już tylko to, co się zmieniło, i tylko do graczy, którzy tego potrzebują. Żadnego odpytywania, żadnego sygnału "coś się zmieniło, pobierz ponownie", żadnego ruchu w każdym ticku. State bagi dla wartości na encję i na gracza, AreaStream dla obiektów świata, state bagi dla reszty.

Ustawienia w panelu admina

Właściciel serwera nie powinien edytować Lua. Ekran ustawień Twojego skryptu dostaje kartę na pulpicie panelu ai-core jednym wywołaniem, więc właściciel znajduje ustawienia wszystkich skryptów w jednym miejscu:

server.lua
exports['ai-core']:RegisterExternalPanel({
    label = 'My script',
    icon = 'gear',
    description = 'Shops, prices and rewards',
    command = 'myscriptconfig',
})

Skrypt, którego nie możesz zmienić, listuje się zamiast tego liniami ai_admin_label / ai_admin_command w jego fxmanifest.lua: RegisterExternalPanel. Komendy zarejestrowane przez aiLib.addCommand i klawisze zrobione przez aiLib.Keybind same pojawiają się na listach komend i klawiszy w panelu.

Twoje dane są Twoje

Tabele Twojego resource'a to Twoja sprawa: nazwij je po swoim resource (myscript_*) i twórz na starcie. Resource'y Lua używają ai-mysql, który zastępuje oxmysql, mysql-async i ghmattimysql (MySQL.query.await, MySQL.single.await), więc zapytania, które już masz, dalej działają. Resource, który sam czyta connection string, potrzebuje jeszcze jednej linii w env.cfg:

env.cfg
add_convar_permission my-resource read mysql_connection_string

Zobacz Baza danych.

Przed wydaniem

  • ai-lib (albo @aifivem/lib) wczytany, dependency 'ai-lib' w manifeście.
  • Żadnych eksportów innego skryptu do przedmiotów, kluczy, pieniędzy, prac, telefonu, zgłoszeń, ubrań, paliwa, drzwi, garaży ani więzienia.
  • Żadnego zapytania do tabeli ai_* AI Core i żadnego czytania data/*.json innego skryptu.
  • Każde żądanie klienta z limitem częstotliwości i sprawdzone na serwerze.
  • Dane na żywo jako snapshot i delty.
  • Ustawienia w panelu, teksty we własnych plikach językowych (locale).
  • Przetestowane ze skryptami ai-*, których dotyczy funkcja, a przy warstwie także z podmienionym wyborem serwera (inny ekwipunek, inny system kluczy).

Na tej stronie