AI Core

Интеграция своего скрипта

Как ваш ресурс работает с AI Core - подключение либы, вызов слоёв вместо других скриптов, чего нельзя касаться, и чек-лист перед релизом.

Чтобы работать с AI Core, вашему скрипту не нужно быть скриптом ai-*. Что делать - зависит от того, что вы пишете:

Что у вас естьЧто делать
Скрипт, написанный под ESX, QBCore, Qbox или vRPНичего. AI Core предоставляет es_extended, qb-core, qbx_core и vrp и отвечает на их API, поэтому скрипт работает без изменений. См. Совместимость.
Ваш собственный новый ресурс (Lua, TypeScript или обычный JavaScript)Подключить либу и обращаться к AI Core через неё. Об этом эта страница.
Скрипт, который предоставляет то, что нужно другим скриптам (инвентарь, телефон, система ключей, гараж, скрипт топлива...)То же самое плюс адаптер в этом слое, чтобы остальной сервер до него добрался. См. Рекомендуемые скрипты.

Цель в одном предложении: всё, что ваш скрипт делит с другим скриптом, идёт через либу или ai-core, но никогда через экспорты этого скрипта. Тогда владелец может заменить инвентарь, систему ключей или телефон, а ваш скрипт продолжит работать.

Подключите либу

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> доступен в каждом файле вашего ресурса. Полная настройка, какие вызовы ждут ответа и как таблицы и векторы Lua переходят в TypeScript: Либа для Lua.

TypeScript

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

@aicore8/lib берётся из npm: ресурс вне рабочего пространства AI Core ставит её через bun install @aicore8/lib @aicore8/shared. Обычный JavaScript-ресурс без сборки подключает @ai-lib/dist/server.js и использует тот же глобальный aiLib.

Порядок запуска

ai-core и ai-lib запускаются до вашего ресурса:

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

Вызывайте AI Core, а не другой скрипт

У каждой общей задачи одна дверь. Вызов либы и экспорт ai-core делают одно и то же; берите то, что подходит вашему языку.

Что нужноLuaTypeScriptСправочник
Выдать, забрать, посчитать предметыaiLib.inventory.addIteminventory.addItemПредметы, предметы ai-core
Используемый предметaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Хранилище или магазинaiLib.inventory.registerStashinventory.registerStashПредметы
Ключи от машиныaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasТранспорт
Создать машину (номер, топливо, вид, ключи и места одним вызовом)aiLib.spawnVehiclespawnVehiclespawnVehicle
Поставить в гараж или на штрафстоянкуaiLib.garages.storegarages.storegarages.store
Деньги игрокаexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Деньги
Деньги между двумя счетами, одной транзакциейaiLib.money.transfermoney.transfermoney.transfer
Работы, банды, сменаexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Работы и банды
Кто в сети, его имя, его работаaiLib.online.nameonline.nameИгроки
Вызов для полицииaiLib.dispatch.alertdispatch.alertdispatch.alert
ТюрьмаaiLib.prison.jailprison.jailprison.jail
Запись в MDTaiLib.mdt.recordmdt.recordmdt.record
Поднять, вылечить, "мёртв ли"aiLib.medical.revivemedical.revivemedical.revive
Телефон (номер, почта, сообщение, уведомление)aiLib.phone.numberphone.numberТелефон
Внешность, комплект одеждыaiLib.appearance.applyappearance.applyappearance.apply
Погода и времяaiLib.world.setWeatherworld.setWeatherМир
Закрыть дверьaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Уведомления, полосы прогресса, меню, диалоги вводаaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuОбщий интерфейс
Пункт радиального менюaiLib.radial.addradial.addradial.add
Команда (видна в админ-панели, проверяется по ACE)aiLib.addCommandaddCommandaddCommand
Строка лога в каналах владельцаaiLib.aiLogaiLogaiLog

Какой скрипт отвечает за каждый пункт на этом сервере и список адаптеров: Слои и мост. Каждая функция с подписью, параметрами и возвратом: Справочник API.

Никогда не обращайтесь к таблицам AI Core. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned и остальные таблицы ai_* внутренние: персонажи, деньги, работы и машины живут в памяти и пишутся по расписанию самого ai-core, поэтому прямой SELECT может вернуть устаревшее, а колонка может измениться в любом релизе. Спросите ai-core - он отвечает и о загруженном игроке, и о сохранённом персонаже (персонажи, деньги, работы). То же касается файлов данных другого скрипта ai-* (data/*.json его админ-панели): это содержимое панели, а не интерфейс.

citizenid - это не id персонажа. Есть два id: id персонажа (charId, число) и citizenid (текст), которым пользуются скрипты других фреймворков. Никогда не пересчитывайте одно в другое сами - спросите ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Персонажи.

Как определить AI Core

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

В TypeScript либа делает это за вас: isResourceStarted("ai-core") или optionalExport("ai-core"), который равен null, пока ресурс остановлен (экспорты).

Скрипт, поддерживающий несколько фреймворков, увидит запущенными и qbx_core, и qb-core, и es_extended, потому что их предоставляет ai-core. Этот путь работает, но добирается только до того, что умеют сказать те API. Проверяйте ai-core до имён фреймворков и выбирайте путь AI Core, когда он есть; код фреймворка оставьте как запасной для других серверов.

Правила, по которым оценивают ваш скрипт

Это те же правила, которым следует каждый скрипт ai-* (Обзор), и то, на что смотрит ревью:

Решает сервер

Каждый запрос клиента проходит через калитку либы: ограничение частоты, один вызов за раз (lock), проверка ACE, а в TypeScript ещё и стражи (админ, есть персонаж, рядом с точкой) и разбор аргументов. Деньги, предметы и права никогда не меняются на клиенте, а значение от клиента никогда не используется как пришло - в Lua вы проверяете каждый аргумент сами.

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
    -- здесь, на сервере, списать деньги и выдать предмет
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Ввод от клиента, строгие читатели TypeScript (readText, oneArg) и отказы (fail, ActionResult).

Снимок, затем дельты

Живые данные уходят клиенту один раз целиком, дальше - только изменения и только тем игрокам, кому они нужны. Никаких опросов, никаких сигналов "что-то изменилось, запроси снова", никакого трафика каждый тик. State bag'и для значений на сущность и на игрока, AreaStream для объектов мира, state bag'и для остального.

Настройки в админ-панели

Владельцу сервера не следует править Lua. Экран настроек вашего скрипта получает карточку на главной странице панели ai-core одним вызовом, чтобы владелец находил настройки всех скриптов в одном месте:

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

Скрипт, который вы не можете изменить, перечисляется строками ai_admin_label / ai_admin_command в его fxmanifest.lua: RegisterExternalPanel. Команды, зарегистрированные через aiLib.addCommand, и клавиши, сделанные через aiLib.Keybind, сами попадают в списки команд и клавиш панели.

Ваши данные - ваши

Таблицы вашего ресурса - ваше дело: называйте их по имени ресурса (myscript_*) и создавайте на старте. Lua-ресурсы используют ai-mysql, который заменяет oxmysql, mysql-async и ghmattimysql (MySQL.query.await, MySQL.single.await), так что имеющиеся запросы продолжат работать. Ресурсу, который сам читает строку подключения, нужна ещё одна строка в env.cfg:

env.cfg
add_convar_permission my-resource read mysql_connection_string

См. База данных.

Перед релизом

  • ai-lib (или @aicore8/lib) подключена, в манифесте есть dependency 'ai-lib'.
  • Нет экспортов другого скрипта для предметов, ключей, денег, работ, телефона, вызовов, одежды, топлива, дверей, гаражей и тюрьмы.
  • Нет запросов к таблицам ai_* AI Core и нет чтения data/*.json другого скрипта.
  • У каждого запроса клиента есть ограничение частоты и проверка на сервере.
  • Живые данные идут снимком и дельтами.
  • Настройки в панели, тексты в собственных языковых файлах (locale).
  • Проверено со скриптами ai-*, которых касается функция, а если задействован слой - ещё и с заменённым выбором сервера (другой инвентарь, другая система ключей).

На этой странице