AI Core
Справочник APIAI Core: серверные экспорты

Сохранённые персонажи

Читайте и меняйте любого персонажа, загруженного или нет - найти его, прочитать, изменить деньги, работы, банды, метаданные и имя, сохранить, удалить.

Экспорты на странице Персонажи отвечают про игрока, подключённого с загруженным персонажем. Эти отвечают про любого персонажа, подключённого или нет: ai-core читает загруженного персонажа из памяти, а сохранённого из базы, и запись доходит до живого персонажа, когда он загружен, и до строки, когда нет.

Три вещи до начала:

  • К персонажу обращаются по его id персонажа (charId, число - CharacterInfo.id). citizenid - это текст, он принадлежит мостам фреймворков; переводите одно в другое через GetCharIdByCitizenId, но не руками.
  • Эти экспорты отвечают через колбэк (done), потому что сохранённому персонажу нужно чтение из базы, а ни один Promise не пересекает границу ресурсов. В TypeScript модуль characters из библиотеки даёт Promise; в Lua aiLib.characters ждёт за вас.
  • Каждая запись отвечает ActionResult: { ok: true } или { ok: false, error: "LANG_KEY" } с одним из языковых ключей ai-core (locales/en.json), который можно показать через callAction или перевести самому.

Никогда не читайте и не пишите таблицы ai-core (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) своими запросами. Персонажи живут в памяти и пишутся по расписанию ai-core, поэтому прямой SELECT может вернуть устаревшее, а колонки внутренние.

GetCharIdByCitizenId

Id персонажа за citizenid, загружен он или нет. Загруженный персонаж отвечает из памяти, сохранённый - одним индексированным чтением.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.idOf

Сигнатура
GetCharIdByCitizenId(citizenid: string, done: (charId: number | null) => void): void
Lua
exports['ai-core']:GetCharIdByCitizenId(citizenid, function(charId) end)

Параметры

Prop

Type

Возвращает

Ничего. Ответ приходит в done.

Пример

import { characters } from "@aicore8/lib/server";

// Библиотека оборачивает колбэк в Promise.
export async function fine(citizenid: string, amount: number): Promise<boolean> {
  const charId = await characters.idOf(citizenid);
  if (charId === null) return false;
  const result = await characters.removeMoney(charId, "bank", amount, "Штраф");
  return result.ok;
}

GetOfflineCharacter

Всё, что ai-core хранит о персонаже: имя и дату рождения, деньги по счетам, работы, банды, метаданные, сохранённую позицию, последнее сохранение и серверный id, когда он загружен.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.get

Сигнатура
GetOfflineCharacter(charId: number, done: (character: OfflineCharacter | null) => void): void
Lua
exports['ai-core']:GetOfflineCharacter(charId, function(character) end)

Параметры

Возвращает

Ничего. done получает OfflineCharacter или null. Загруженный персонаж отвечает из памяти, поэтому его деньги и принадлежности - актуальные, а source - это игрок.

Пример

import { characters } from "@aicore8/lib/server";

export async function describe(charId: number): Promise<string> {
  const c = await characters.get(charId);
  if (!c) return "неизвестный персонаж";
  const where = c.source === null ? "офлайн" : `онлайн как ${c.source}`;
  return `${c.info.firstname} ${c.info.lastname} (${where}), банк ${c.money.bank ?? 0}`;
}

SearchCharacters

Персонажи по набранному тексту, загруженные или нет: начало имени или фамилии ("jane doe" тоже), citizenid, id fivem / license / discord. 25 на страницу, самый новый персонаж первым.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.search

Сигнатура
SearchCharacters(text: string, done: (page: CharacterSearchPage) => void, cursor?: number): void
Lua
exports['ai-core']:SearchCharacters(text, function(page) end, cursor)

Параметры

Prop

Type

Возвращает

Ничего. done получает CharacterSearchPage: до 25 совпадений и курсор next (null на последней странице). Пустой текст отвечает самыми новыми персонажами, поэтому экран просмотра работает и без запроса.

Пример

import { characters, onClientCallback } from "@aicore8/lib/server";
import { oneArg, readText } from "@aicore8/lib/shared";

onClientCallback(
  "myscript:searchPeople",
  { args: oneArg((v) => readText(v, 64)), rate: { count: 10, windowMs: 10_000 } },
  async (_source, text) => {
    const page = await characters.search(text);
    return { ok: true, people: page.characters, next: page.next };
  },
);

GetCharactersOfUser

Все персонажи одного аккаунта, по слотам. Для экрана, который показывает игроку всех его персонажей, или для админского инструмента, работающего с аккаунтом.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.ofUser

Сигнатура
GetCharactersOfUser(user: number | string, done: (characters: StoredCharacter[]) => void): void
Lua
exports['ai-core']:GetCharactersOfUser(user, function(characters) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает массив StoredCharacter.

Пример

import { characters, resourceExport } from "@aicore8/lib/server";

const core = resourceExport("ai-core");

export async function slotsOf(source: number): Promise<number[]> {
  const userId = core.GetUserId(source);
  if (userId === null) return [];
  return (await characters.ofUser(userId)).map((c) => c.slot);
}

GetJobMembers and GetGangMembers

Все, у кого есть работа (или кто в банде), загруженные или нет, страница за страницей и со своим грейдом. Это тот состав, который нужен экрану управления: зеркало online из библиотеки знает только подключённых игроков.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.jobMembers

Сигнатура
GetJobMembers(job: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
GetGangMembers(gang: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
Lua
exports['ai-core']:GetJobMembers(job, function(page) end, after, limit)
exports['ai-core']:GetGangMembers(gang, function(page) end, after, limit)

Параметры

Prop

Type

Возвращает

Ничего. done получает MembersPage: участников и after следующей страницы (null на последней). У каждого участника есть source, так что подключённые - это записи, у которых source не null.

Пример

import { characters } from "@aicore8/lib/server";

/** Все участники работы, страница за страницей. */
export async function roster(job: string) {
  const all = [];
  let after: number | undefined;
  do {
    const page = await characters.jobMembers(job, after);
    all.push(...page.members);
    after = page.next ?? undefined;
  } while (after !== undefined);
  return all;
}

Один только вопрос "есть ли у кого-нибудь эта работа?" читает одну строку: библиотечный characters.hasJobMember вызывает этот экспорт с limit = 1.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

Деньги персонажа, загруженного или нет. Загруженный проходит через свой живой кошелёк (игрок видит сразу), сохранённый пишется в базу с теми же правилами и той же строкой журнала.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.addMoney

Сигнатура
AddOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
RemoveOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
SetOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:AddOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:RemoveOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:SetOfflineMoney(charId, account, amount, reason, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error } с языковым ключом: неизвестный персонаж, счёт, которого нет на сервере, дробная или отрицательная сумма, либо - у RemoveOfflineMoney - баланс, которым нельзя заплатить (если тип счёта не разрешает уходить ниже нуля).

Пример

import { characters } from "@aicore8/lib/server";

/** Выплачивает продажу, онлайн продавец или нет. */
export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Машина продана");
  if (!result.ok) console.log(`выплата отклонена: ${result.error}`);
  return result.ok;
}

SetOfflineJob and RemoveOfflineJob

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

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.setJob

Сигнатура
SetOfflineJob(charId: number, job: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineJob(charId: number, job: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineJob(charId, job, grade, function(result) end)
exports['ai-core']:RemoveOfflineJob(charId, job, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error } с языковым ключом: неизвестный персонаж, неизвестная работа, несуществующий грейд или лимит работ из панели.

Пример

import { characters } from "@aicore8/lib/server";

/** Увольняет участника, онлайн он или нет. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

SetOfflineGang and RemoveOfflineGang

То же для банд. Персонаж может быть в нескольких бандах, но действует за одну (SetActiveGang выбирает её для подключённого игрока).

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.setGang

Сигнатура
SetOfflineGang(charId: number, gang: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineGang(charId: number, gang: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineGang(charId, gang, grade, function(result) end)
exports['ai-core']:RemoveOfflineGang(charId, gang, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error }, как с работами.

SetOfflineMeta

Одно значение метаданных персонажа, загруженного или нет. Загруженный персонаж получает его дельтой на своей игре, поэтому HUD и интерфейс сразу подхватывают.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.setMeta

Сигнатура
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineMeta(charId, key, value, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error } при неизвестном персонаже либо значении, которое JSON не умещает.

Пример

import { characters } from "@aicore8/lib/server";

await characters.setMeta(12, "myscript_licence", { kind: "drive", since: Date.now() });
await characters.setMeta(12, "myscript_licence", null); // убирает её

Для подключённого игрока короче путь GetMeta / SetMeta, и читать метаданные можно только там (на этой странице нет GetOfflineMeta: прочитайте персонажа целиком через GetOfflineCharacter и возьмите metadata).

SetCharacterInfo

Меняет собственные поля персонажа: имя, дату рождения, национальность, пол и рост. Каждое поле проверяется так, как его проверяет форма создания персонажа, поэтому админский инструмент не впишет имя, которое создание отклонило бы.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.setInfo

Сигнатура
SetCharacterInfo(charId: number, patch: CharacterInfoPatch, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetCharacterInfo(charId, patch, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error } с языковым ключом. sex отклоняется, пока персонаж загружен, потому что модель педа следует за ним; всё остальное доходит до загруженного персонажа дельтой.

Пример

import { characters } from "@aicore8/lib/server";

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`смена фамилии отклонена: ${result.error}`);

DeleteCharacter

Удаляет персонажа. Это мягкое удаление: строка остаётся для логов, а персонаж исчезает из всех списков и из всех поисков.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.remove

Сигнатура
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:DeleteCharacter(charId, by, function(result) end)

Параметры

Prop

Type

Возвращает

Ничего. done получает { ok: true } или { ok: false, error } при неизвестном персонаже либо персонаже, загруженном прямо сейчас - игроку сначала надо вернуться на экран персонажей. При успехе ai-core вызывает своё событие characterDeleted; см. События и состояние.

GetPlayTime

Сколько персонажа отыграли, в секундах: сохранённая сумма плюс текущая сессия.

Сторона: сервер · Ожидание: нет для подключённого игрока · Библиотека: characters.playTime

Сигнатура
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- подключённый игрок: отвечает сразу
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Параметры

Prop

Type

Возвращает

number | null: секунды, когда они известны без чтения из базы (серверный id или загруженный { charId }). null значит «не здесь, ждите done» - или, для серверного id, что у игрока нет загруженного персонажа.

SavePlayer

Записывает сейчас позицию и метаданные подключённого игрока и ждёт его отложенные записи. Используйте перед тем, что не должно потерять последние минуты: рестарт, передача, админское действие, которое вы логируете.

Сторона: сервер · Ожидание: нет (ответ приходит в done) · Библиотека: characters.save

Сигнатура
SavePlayer(source: number, done?: (ok: boolean) => void): void
Lua
exports['ai-core']:SavePlayer(source, function(ok) end)

Параметры

Prop

Type

Возвращает

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

Персонаж, который не загружен, уже записан: сбрасывать нечего. Чтобы передвинуть точку спавна сохранённого персонажа, используйте characters.setOfflinePosition (SetOfflinePosition).

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