Сохранённые персонажи
Читайте и меняйте любого персонажа, загруженного или нет - найти его, прочитать, изменить деньги, работы, банды, метаданные и имя, сохранить, удалить.
Экспорты на странице Персонажи отвечают про игрока, подключённого с загруженным персонажем. Эти отвечают про любого персонажа, подключённого или нет: ai-core читает загруженного персонажа из памяти, а сохранённого из базы, и запись доходит до живого персонажа, когда он загружен, и до строки, когда нет.
Три вещи до начала:
- К персонажу обращаются по его id персонажа (
charId, число -CharacterInfo.id). citizenid - это текст, он принадлежит мостам фреймворков; переводите одно в другое через GetCharIdByCitizenId, но не руками. - Эти экспорты отвечают через колбэк (
done), потому что сохранённому персонажу нужно чтение из базы, а ни один Promise не пересекает границу ресурсов. В TypeScript модуль characters из библиотеки даёт Promise; в LuaaiLib.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): voidexports['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): voidexports['ai-core']:GetOfflineCharacter(charId, function(character) end)Параметры
Prop
Type
Возвращает
Ничего. 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): voidexports['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): voidexports['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): voidexports['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): voidexports['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): voidexports['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): voidexports['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): voidexports['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): voidexports['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): voidexports['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 | nulllocal 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): voidexports['ai-core']:SavePlayer(source, function(ok) end)Параметры
Prop
Type
Возвращает
Ничего. ai-core сохраняет сам (периодически, при выгрузке и при остановке), поэтому это нужно только тогда, когда запись должна была случиться до вашего следующего шага.
Персонаж, который не загружен, уже записан: сбрасывать нечего. Чтобы передвинуть точку спавна сохранённого персонажа, используйте characters.setOfflinePosition (SetOfflinePosition).
Персонажи и игроки
Прочитать данные и персонажа загруженного игрока, найти игрока по id персонажа или citizen id, сменить персонажа, переместить офлайн-персонажа, игроки в зоне видимости.
Деньги и счета
Читать и менять балансы игрока, счета работ и банд, перемещать деньги между двумя счетами одной транзакцией, читать типы счетов.