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 masz | Co zrobić |
|---|---|
| Skrypt napisany pod ESX, QBCore, Qbox lub vRP | Nic. 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
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
import { inventory, onClientCallback } from "@aicore8/lib/server";@aicore8/lib pochodzi z npm: resource poza workspace'em AI Core instaluje go przez bun install @aicore8/lib @aicore8/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:
ensure ai-core
ensure ai-lib
ensure my-resourceWoł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 potrzebujesz | Lua | TypeScript | Dokumentacja |
|---|---|---|---|
| Dać, zabrać, zliczyć przedmioty | aiLib.inventory.addItem | inventory.addItem | Przedmioty, przedmioty ai-core |
| Przedmiot do użycia | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Skrytka albo sklep | aiLib.inventory.registerStash | inventory.registerStash | Przedmioty |
| Kluczyki do pojazdu | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Pojazdy |
| Zespawnować pojazd (tablica, paliwo, wygląd, kluczyki i miejsca w jednym wywołaniu) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Wstawić do garażu albo odholować | aiLib.garages.store | garages.store | garages.store |
| Pieniądze gracza | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Pieniądze |
| Pieniądze między dwoma kontami, w jednej transakcji | aiLib.money.transfer | money.transfer | money.transfer |
| Prace, gangi, służba | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Prace i gangi |
| Kto jest online, jego imię, jego praca | aiLib.online.name | online.name | Gracze |
| Zgłoszenie dla policji | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| Więzienie | aiLib.prison.jail | prison.jail | prison.jail |
| Wpis w MDT | aiLib.mdt.record | mdt.record | mdt.record |
| Reanimacja, leczenie, "czy leży" | aiLib.medical.revive | medical.revive | medical.revive |
| Telefon (numer, mail, wiadomość, powiadomienie) | aiLib.phone.number | phone.number | Telefon |
| Wygląd, strój | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Pogoda i czas | aiLib.world.setWeather | world.setWeather | Świat |
| Zamknąć drzwi | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Powiadomienia, paski postępu, menu, okna wpisywania | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Wspólny interfejs |
| Wpis w menu radialnym | aiLib.radial.add | radial.add | radial.add |
| Komenda (widoczna w panelu admina, sprawdzana przez ACE) | aiLib.addCommand | addCommand | addCommand |
| Linia logu na kanałach właściciela | aiLib.aiLog | aiLog | aiLog |
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
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.
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:
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:
add_convar_permission my-resource read mysql_connection_stringZobacz Baza danych.
Przed wydaniem
ai-lib(albo@aicore8/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 czytaniadata/*.jsoninnego 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).
Dokumentacja API
Każdy eksport, event i funkcja liba z sygnaturą, parametrami i zwracaną wartością.
Lib dla Lua
aiLib: konfiguracja, wywołania które czekają, tablice i wektory Lua przez granicę resource'a.
Warstwy i bridge
Który skrypt odpowiada w każdej warstwie i jak działa bridge ESX / QB / Qbox.
Polecane skrypty
Jak darmowy skrypt trafia na listę w panelu i jak napisać adapter jego warstwy.