Интеграция своего скрипта
Как ваш ресурс работает с 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
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
import { inventory, onClientCallback } from "@aifivem/lib/server";@aifivem/lib берётся из npm: ресурс вне рабочего пространства AI Core ставит её через bun install @aifivem/lib @aifivem/shared. Обычный JavaScript-ресурс без сборки подключает @ai-lib/dist/server.js и использует тот же глобальный aiLib.
Порядок запуска
ai-core и ai-lib запускаются до вашего ресурса:
ensure ai-core
ensure ai-lib
ensure my-resourceВызывайте AI Core, а не другой скрипт
У каждой общей задачи одна дверь. Вызов либы и экспорт ai-core делают одно и то же; берите то, что подходит вашему языку.
| Что нужно | Lua | TypeScript | Справочник |
|---|---|---|---|
| Выдать, забрать, посчитать предметы | aiLib.inventory.addItem | inventory.addItem | Предметы, предметы ai-core |
| Используемый предмет | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Хранилище или магазин | aiLib.inventory.registerStash | inventory.registerStash | Предметы |
| Ключи от машины | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Транспорт |
| Создать машину (номер, топливо, вид, ключи и места одним вызовом) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Поставить в гараж или на штрафстоянку | aiLib.garages.store | garages.store | garages.store |
| Деньги игрока | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Деньги |
| Деньги между двумя счетами, одной транзакцией | aiLib.money.transfer | money.transfer | money.transfer |
| Работы, банды, смена | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Работы и банды |
| Кто в сети, его имя, его работа | aiLib.online.name | online.name | Игроки |
| Вызов для полиции | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| Тюрьма | aiLib.prison.jail | prison.jail | prison.jail |
| Запись в MDT | aiLib.mdt.record | mdt.record | mdt.record |
| Поднять, вылечить, "мёртв ли" | aiLib.medical.revive | medical.revive | medical.revive |
| Телефон (номер, почта, сообщение, уведомление) | aiLib.phone.number | phone.number | Телефон |
| Внешность, комплект одежды | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Погода и время | aiLib.world.setWeather | world.setWeather | Мир |
| Закрыть дверь | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Уведомления, полосы прогресса, меню, диалоги ввода | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Общий интерфейс |
| Пункт радиального меню | aiLib.radial.add | radial.add | radial.add |
| Команда (видна в админ-панели, проверяется по ACE) | aiLib.addCommand | addCommand | addCommand |
| Строка лога в каналах владельца | aiLib.aiLog | aiLog | aiLog |
Какой скрипт отвечает за каждый пункт на этом сервере и список адаптеров: Слои и мост. Каждая функция с подписью, параметрами и возвратом: Справочник 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
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 вы проверяете каждый аргумент сами.
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 одним вызовом, чтобы владелец находил настройки всех скриптов в одном месте:
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:
add_convar_permission my-resource read mysql_connection_stringСм. База данных.
Перед релизом
ai-lib(или@aifivem/lib) подключена, в манифесте естьdependency 'ai-lib'.- Нет экспортов другого скрипта для предметов, ключей, денег, работ, телефона, вызовов, одежды, топлива, дверей, гаражей и тюрьмы.
- Нет запросов к таблицам
ai_*AI Core и нет чтенияdata/*.jsonдругого скрипта. - У каждого запроса клиента есть ограничение частоты и проверка на сервере.
- Живые данные идут снимком и дельтами.
- Настройки в панели, тексты в собственных языковых файлах (locale).
- Проверено со скриптами
ai-*, которых касается функция, а если задействован слой - ещё и с заменённым выбором сервера (другой инвентарь, другая система ключей).
Справочник API
Каждый экспорт, событие и функция либы с подписью, параметрами и возвратом.
Либа для Lua
aiLib: настройка, вызовы которые ждут, таблицы и векторы Lua через границу ресурса.
Слои и мост
Какой скрипт отвечает в каждом слое и как работает мост ESX / QB / Qbox.
Рекомендуемые скрипты
Как бесплатный скрипт попадает в список панели и как написать адаптер его слоя.